DA Filtering (Inversion) Methods

This subpackage provides implementations to solve both time-independent as well as time-dependent DA problems where one observation is assimilated/matched against model output. For time-dependent problems, the filtering is carried out sequentially.

DA Filtering Algorithms

• Three dimensional Variational (3DVar) DA
  • VanillaThreeDVarConfigs
  • VanillaThreeDVar
  • DolfinThreeDVar
• Kalman Filtering
  • KalmanFilterConfigs
  • KalmanFilter
  • ConventionalComplexKalmanFilterConfigs
  • ConventionalComplexKalmanFilter
  • AugmentedComplexKalmanFilterConfigs
  • AugmentedComplexKalmanFilter

DA Filtering Base Classes

Abstract classes for filtering algoirthms (Bayesian and Variational approaches). A HybridFilter Class is also added, but without clear functionality yet. Unlike smoothing algorithms, in the case of filters a single observation is given (e.g., time-independent problems). The output of a filtering algorithm is a point estimate of the truth. Uncertainty measure, e.g., posterior covariance, provided if a Bayesian approach is followed.

class VariationalFilterConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, model=None, prior=None, observation_error_model=None, observation_operator=None, observations=None, optimizer=None, optimizer_configs=None)

Bases: FilterConfigs

Configurations class for the VariationalFilter abstract base class.

Parameters:

• verbose (bool) – a boolean flag to control verbosity of the object.

• debug (bool) – a boolean flag that enables adding extra functionlity in a debug mode

• output_dir (str | Path) – the base directory where the output files will be saved.

• name (str | None) – name of the DA (inverse problem solver) approach/method.

• model (None | SimulationModel) – the simulation model.

• prior (None | ErrorModel) – Background/Prior model (e.g., GaussianErrorModel)

• observation_operator (None | ObservationOperator) – operator to map model state to observation space

• observation_error_model (None | ErrorModel) – Observation error model (e.g., GaussianErrorModel)

• observations (None | Any) – Observational data (the data type is very much dependent of the DA method)

• optimizer (None | Optimizer) –

  the optimization routine (optimizer) to be registered and later used for solving the OED problem. This can be one of the following:

  • None: In this case, no optimizer is registered, and the solve() won’t be functional until an optimization routine is registered.

  • An optimizer instance (object that inherits :py:class`Optimizer`). In this case, the optimizer is registered as is and is updated with the passed configurations if available.

  • The class (subclass of Optimizer) to be used to instantiate the optimizer.

• optimizer_configs (None | dict | OptimizerConfigs) –

  the configurations of the optimization routine. This can be one of the following:

  • None, in this case configurations are discarded, and whatever default configurations of the selected/passed optimizer are employed.

  • A dict holding full/partial configurations of the selected optimizer. These are either used to instantiate or update the optimizer configurations based on the type of the passed optimizer.

  • A class providing implementations of the configurations (this must be a subclass of OptimizerConfigs.

  • An instance of a subclass of OptimizerConfigs which is to set/udpate optimizer configurations.

  Note

  Not all DA (inverse problem) objects are optimization-based. For example, particle-based (EnKF, PF, etc.) employ a sample to estimate the flow of the distribution through the model dynamics (prior -> posterior). Thus, the optimizer (and configs) in this case (the default) are set to None. For optimization-based methods such as 3DVar, 4DVar, etc., an optimizer must be registered for the inverse problem to be solved.

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, model=None, prior=None, observation_error_model=None, observation_operator=None, observations=None, optimizer=None, optimizer_configs=None)

class VariationalFilter(configs=None)

Bases: Filter

Base class for variational filters. In this case, a single point estimate is obtained by solving a weighted least-squares optimization problem to minimize the mismatch between model prediction and observation (in the appropriate projected space, e.g., observation space) The mismatch is usually regularized using a penalty term (usually asserted by the prior)

__init__(configs=None)

objective(init_guess, data_misfit_only=False)

Evaluate the objective function, and the associated gradient

Parameters:

• init_guess – model parameter/state to evaluate the objective function and the associated gradient at

• data_misfit_only (bool) – discard the prior/regularization term if True. This is added for flexibility

Returns:

objective function value, and the gradient; (the objective value is a scalar, and the gradient is a one-dimensional Numpy array)

abstract objective_function_value(init_guess, data_misfit_only=False)

A method to evaluate the variational objective function.

objective_function_gradient(init_guess, data_misfit_only=False)

A method to evaluate the variational objective function. This implementation (by default) provides a gradient approximation using finite difference approximation. For efficient evaluation of the gradient, the derived class need to provide and implementation of the analytical gradient.

class VariationalFilterResults(*, inverse_problem=None, optimization_results=None)

Bases: FilterResults

Base class for objects holding results of Filter

Parameters:

inverse_problem (InverseProblem | None) – instance of a class derived from InverseProblem.

__init__(*, inverse_problem=None, optimization_results=None)

class BayesianFilterConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, model=None, prior=None, observation_error_model=None, observation_operator=None, observations=None, optimizer=None, optimizer_configs=None)

Bases: FilterConfigs

Configurations class for the BayesianFilter abstract base class.

Parameters:

• verbose (bool) – a boolean flag to control verbosity of the object.

• debug (bool) – a boolean flag that enables adding extra functionlity in a debug mode

• output_dir (str | Path) – the base directory where the output files will be saved.

• name (str | None) – name of the DA (inverse problem solver) approach/method.

• model (None | SimulationModel) – the simulation model.

• prior (None | ErrorModel) – Background/Prior model (e.g., GaussianErrorModel)

• observation_operator (None | ObservationOperator) – operator to map model state to observation space

• observation_error_model (None | ErrorModel) – Observation error model (e.g., GaussianErrorModel)

• observations (None | Any) – Observational data (the data type is very much dependent of the DA method)

• optimizer (None | Optimizer) –

  the optimization routine (optimizer) to be registered and later used for solving the OED problem. This can be one of the following:

  • None: In this case, no optimizer is registered, and the solve() won’t be functional until an optimization routine is registered.

  • An optimizer instance (object that inherits :py:class`Optimizer`). In this case, the optimizer is registered as is and is updated with the passed configurations if available.

  • The class (subclass of Optimizer) to be used to instantiate the optimizer.

• optimizer_configs (None | dict | OptimizerConfigs) –

  the configurations of the optimization routine. This can be one of the following:

  • None, in this case configurations are discarded, and whatever default configurations of the selected/passed optimizer are employed.

  • A dict holding full/partial configurations of the selected optimizer. These are either used to instantiate or update the optimizer configurations based on the type of the passed optimizer.

  • A class providing implementations of the configurations (this must be a subclass of OptimizerConfigs.

  • An instance of a subclass of OptimizerConfigs which is to set/udpate optimizer configurations.

  Note

  Not all DA (inverse problem) objects are optimization-based. For example, particle-based (EnKF, PF, etc.) employ a sample to estimate the flow of the distribution through the model dynamics (prior -> posterior). Thus, the optimizer (and configs) in this case (the default) are set to None. For optimization-based methods such as 3DVar, 4DVar, etc., an optimizer must be registered for the inverse problem to be solved.

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, model=None, prior=None, observation_error_model=None, observation_operator=None, observations=None, optimizer=None, optimizer_configs=None)

class BayesianFilter(configs=None)

Bases: Filter

Base class for Bayesian filtering algorithms. In this case, the probability distribution (or an estimate thereof) of the model state/parameter is considered. The goal is to apply Bayes’ theorem, and retrieve the exact/approximate posterior or samples from teh posterior

__init__(configs=None)

class BayesianFilterResults(*, inverse_problem=None, optimization_results=None)

Bases: FilterResults

Base class for objects holding results of Filter

Parameters:

inverse_problem (InverseProblem | None) – instance of a class derived from InverseProblem.

__init__(*, inverse_problem=None, optimization_results=None)

class HybridFilterConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, model=None, prior=None, observation_error_model=None, observation_operator=None, observations=None, optimizer=None, optimizer_configs=None)

Bases: FilterConfigs

Configurations class for the HybridFilter abstract base class.

Parameters:

• verbose (bool) – a boolean flag to control verbosity of the object.

• debug (bool) – a boolean flag that enables adding extra functionlity in a debug mode

• output_dir (str | Path) – the base directory where the output files will be saved.

• name (str | None) – name of the DA (inverse problem solver) approach/method.

• model (None | SimulationModel) – the simulation model.

• prior (None | ErrorModel) – Background/Prior model (e.g., GaussianErrorModel)

• observation_operator (None | ObservationOperator) – operator to map model state to observation space

• observation_error_model (None | ErrorModel) – Observation error model (e.g., GaussianErrorModel)

• observations (None | Any) – Observational data (the data type is very much dependent of the DA method)

• optimizer (None | Optimizer) –

  the optimization routine (optimizer) to be registered and later used for solving the OED problem. This can be one of the following:

  • None: In this case, no optimizer is registered, and the solve() won’t be functional until an optimization routine is registered.

  • An optimizer instance (object that inherits :py:class`Optimizer`). In this case, the optimizer is registered as is and is updated with the passed configurations if available.

  • The class (subclass of Optimizer) to be used to instantiate the optimizer.

• optimizer_configs (None | dict | OptimizerConfigs) –

  the configurations of the optimization routine. This can be one of the following:

  • None, in this case configurations are discarded, and whatever default configurations of the selected/passed optimizer are employed.

  • A dict holding full/partial configurations of the selected optimizer. These are either used to instantiate or update the optimizer configurations based on the type of the passed optimizer.

  • A class providing implementations of the configurations (this must be a subclass of OptimizerConfigs.

  • An instance of a subclass of OptimizerConfigs which is to set/udpate optimizer configurations.

  Note

  Not all DA (inverse problem) objects are optimization-based. For example, particle-based (EnKF, PF, etc.) employ a sample to estimate the flow of the distribution through the model dynamics (prior -> posterior). Thus, the optimizer (and configs) in this case (the default) are set to None. For optimization-based methods such as 3DVar, 4DVar, etc., an optimizer must be registered for the inverse problem to be solved.

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name=None, model=None, prior=None, observation_error_model=None, observation_operator=None, observations=None, optimizer=None, optimizer_configs=None)

class HybridFilter(configs=None)

Bases: Filter

Base class for Bayesian-variational filters.

__init__(configs=None)

class HybridFilterResults(*, inverse_problem=None, optimization_results=None)

Bases: FilterResults

Base class for objects holding results of Filter

Parameters:

inverse_problem (InverseProblem | None) – instance of a class derived from InverseProblem.

__init__(*, inverse_problem=None, optimization_results=None)