Goal-Oriented DA Tools

This subpackage provides implementations to support Goal-Oriented DA (inverse problems) formulations and solutions.

Goal-Oriented DA Base Classes

This module provides blueprint for Gola-Oriented Inverse problems and data assimilation. The goal operator is an additional operator that performs on the inference parameter/state. This includes prediction to future time, etc.

class GoalOrientedOperatorConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name='Goal-Oriented Operator', inverse_problem=None)

Bases: PyOEDConfigs

Configurations class for the GoalOrientedOperator abstract base class. This class inherits functionality from PyOEDConfigs and only adds new class-level variables which can be updated as needed.

Parameters:

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

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

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

• inverse_problem (None | InverseProblem) – The inverse problem instance to be used with the goal operator (e.g., prediction operator)

name: str

inverse_problem: None | InverseProblem

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name='Goal-Oriented Operator', inverse_problem=None)

class GoalOrientedOperator(configs=None)

Bases: PyOEDObject

Base class implementing a Goal-Oriented Operator that performs over an inverse problem.

Note

Every Goal-Oriented Operator SHOULD inherit this class.

Parameters:

configs (dict | GoalOrientedOperatorConfigs | None) – (optional) configurations for the goal-oriented operator object

Raises:

PyOEDConfigsValidationError – if passed invalid configs

__init__(configs=None)

validate_configurations(configs, raise_for_invalid=True)

Each simulation optimizer SHOULD implement it’s own function that validates its own configurations. If the validation is self contained (validates all configuations), then that’s it. However, one can just validate the configurations of of the immediate class and call super to validate configurations associated with the parent class.

If one does not wish to do any validation (we strongly advise against that), simply add the signature of this function to the optimizer class.

Note

The purpose of this method is to make sure that the settings in the configurations object self._CONFIGURATIONS are of the right type/values and are conformable with each other. This function is called upon instantiation of the object, and each time a configuration value is updated. Thus, this function need to be inexpensive and should not do heavy computations.

Parameters:

configs (dict | GoalOrientedOperatorConfigs) – configurations to validate. If a InverseProblemonfigs object is passed, validation is performed on the entire set of configurations. However, if a dictionary is passed, validation is performed only on the configurations corresponding to the keys in the dictionary.

Raises:

• PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

• AttributeError – if any (or a group) of the configurations does not exist in the optimizer configurations GoalOrientedOperatorConfigs.

update_configurations(**kwargs)

Take any set of keyword arguments, and lookup each in the configurations, and update as nessesary/possible/valid

Raises:

PyOEDConfigsValidationError – if invalid configurations passed

register_inverse_problem(inverse_problem=None)

Register (and return) the inverse problem to be registered.

Raises:

TypeError – if the type of passed inverse problem is not supported

generate_vector(*args, **kwargs)

Create a vector conformable with the goal operator (goal-vector)

apply(*args, **kwargs)

Apply goal-oriented operator

apply_adjoint(*args, **kwargs)

Apply the adjoint (Jacbian-transposed, etc.) of the goal-oriented operator

property inverse_problem

A reference to the underlying inverse problem.

property size

Dimension/Size of the goal space (size of a goal vector)

Note

Better implementation should be provided to return dimension without creating a vector.

property shape

Shape (codomain-size, domain-size). This is (goal size x model size) of the operator viewed as a matrix.

class GoalOrientedInverseProblemConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name='Goal-Oriented Inverse Problem', inverse_problem=None, goal_operator=None)

Bases: PyOEDConfigs

Configurations class for the GoalOrientedInverseProblem base class. This class inherits functionality from PyOEDConfigs and only adds new class-level variables which can be updated as needed.

Parameters:

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

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

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

• inverse_problem (None | InverseProblem) – The inverse problem instance to be used with the goal operator (e.g., prediction operator)

• goal_operator (None | GoalOrientedOperator) – a goal operator (function of the inverse problem); this needs to be None or an instance (derived from GoalOrientedOperator).

name: str

inverse_problem: None | InverseProblem

goal_operator: None | GoalOrientedOperator

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name='Goal-Oriented Inverse Problem', inverse_problem=None, goal_operator=None)

class GoalOrientedInverseProblem(configs=None)

Bases: PyOEDObject

Base class implementing a Goal-Oriented Inverse problems.

Note

Every Goal-Oriented inverse problem SHOULD inherit this class.

Parameters:

configs (dict | GoalOrientedInverseProblemConfigs | None) – (optional) configurations for the goal-oriented inverse problem

Raises:

PyOEDConfigsValidationError – if passed invalid configs

__init__(configs=None)

validate_configurations(configs, raise_for_invalid=True)

Each simulation optimizer SHOULD implement it’s own function that validates its own configurations. If the validation is self contained (validates all configuations), then that’s it. However, one can just validate the configurations of of the immediate class and call super to validate configurations associated with the parent class.

If one does not wish to do any validation (we strongly advise against that), simply add the signature of this function to the optimizer class.

Note

The purpose of this method is to make sure that the settings in the configurations object self._CONFIGURATIONS are of the right type/values and are conformable with each other. This function is called upon instantiation of the object, and each time a configuration value is updated. Thus, this function need to be inexpensive and should not do heavy computations.

Parameters:

configs (dict | GoalOrientedInverseProblemConfigs) – configurations to validate. If a InverseProblemonfigs object is passed, validation is performed on the entire set of configurations. However, if a dictionary is passed, validation is performed only on the configurations corresponding to the keys in the dictionary.

Raises:

• PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

• AttributeError – if any (or a group) of the configurations does not exist in the optimizer configurations GoalOrientedOperatorConfigs.

update_configurations(**kwargs)

Take any set of keyword arguments, and lookup each in the configurations, and update as nessesary/possible/valid

Raises:

PyOEDConfigsValidationError – if invalid configurations passed

register_inverse_problem(inverse_problem=None)

Register (and return) the inverse problem to be registered.

Raises:

TypeError – if the type of passed inverse problem is not supported

register_goal_operator(goal_operator=None)

Register (and return) the goal-oriented operator to be registered.

Raises:

TypeError – if the type of passed goal oriented operator i s not supported

Hessian_matvec(state, eval_at=None, data_misfit_only=False)

Hessian_inv_matvec(state, eval_at=None, data_misfit_only=False)

The posterior covariance (assuming Laplacian approximation) defined as the projection of the posterior covariance of the parameter onto the goal-space.

property base_inverse_problem

A reference to the underlying (base) inverse problem.

property goal_operator

A reference to the underlying goal-operator.

property optimizer

Proxy to InverseProblem.optimizer of the underlying base_inverse_problem.

property model

Proxy to InverseProblem.model of the underlying base_inverse_problem.

property observation_error_model

attr:InverseProblem.observation_error_model <pyoed.assimilation.InverseProblem.observation_error_model> of the underlying base_inverse_problem.

Type:

Proxy to

Type:

py

property observation_operator

attr:InverseProblem.observation_operator <pyoed.assimilation.InverseProblem.observation_operator> of the underlying base_inverse_problem.

Type:

Proxy to

Type:

py

property observations

attr:InverseProblem.observations <pyoed.assimilation.InverseProblem.observations> of the underlying base_inverse_problem.

Type:

Proxy to

Type:

py

property observation_times

attr:Smoother.observation_times <pyoed.assimilation.Smoother.observation_times> of the underlying base_inverse_problem. Only meaningful when the base inverse problem is a smoother.

Type:

Proxy to

Type:

py

Goal-Oriented Linear Inverse Problems

The most simple goal-oriented linear inverse problem. Linear Inverse problem + Linear goal operator.

class GoalOrientedLinearInverseProblemConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name='Goal Oriented Linear Inverse Problem', inverse_problem=None, goal_operator=None)

Bases: GoalOrientedInverseProblemConfigs

Configurations class for the GoalOrientedLinearInverseProblem class. This class inherits functionality from GoalOrientedInverseProblemConfigs and only adds new class-level variables which can be updated as needed.

Parameters:

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

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

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

• inverse_problem (None | InverseProblem) – The inverse problem instance to be used with the goal operator (e.g., prediction operator)

• goal_operator (None | GoalOrientedOperator) – a goal operator (function of the inverse problem); this needs to be None or an instance (derived from GoalOrientedOperator).

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name='Goal Oriented Linear Inverse Problem', inverse_problem=None, goal_operator=None)

class GoalOrientedLinearInverseProblem(configs=None)

Bases: GoalOrientedInverseProblem

__init__(configs=None)

validate_configurations(configs, raise_for_invalid=True)

Each simulation optimizer SHOULD implement it’s own function that validates its own configurations. If the validation is self contained (validates all configuations), then that’s it. However, one can just validate the configurations of of the immediate class and call super to validate configurations associated with the parent class.

If one does not wish to do any validation (we strongly advise against that), simply add the signature of this function to the optimizer class.

Note

The purpose of this method is to make sure that the settings in the configurations object self._CONFIGURATIONS are of the right type/values and are conformable with each other. This function is called upon instantiation of the object, and each time a configuration value is updated. Thus, this function need to be inexpensive and should not do heavy computations.

Parameters:

configs (dict | GoalOrientedLinearInverseProblemConfigs) – configurations to validate. If a InverseProblemonfigs object is passed, validation is performed on the entire set of configurations. However, if a dictionary is passed, validation is performed only on the configurations corresponding to the keys in the dictionary.

Raises:

• PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

• AttributeError – if any (or a group) of the configurations does not exist in the optimizer configurations GoalOrientedOperatorConfigs.

prior_covariance_matvec(p, eval_at=None, **kwargs)

Multiply the prior covariance matrix by a vector

posterior_covariance_matvec(p, eval_at=None, **kwargs)

Multiply the posterior covariance matrix by a vector

Hessian_inv_matvec(p, eval_at=None, **kwargs)

Multiply the posterior covariance matrix by a vector

property window

property observation_times

attr:Smoother.observation_times <pyoed.assimilation.Smoother.observation_times> of the underlying base_inverse_problem. Only meaningful when the base inverse problem is a smoother.

Type:

Proxy to

Type:

py

property observations

attr:InverseProblem.observations <pyoed.assimilation.InverseProblem.observations> of the underlying base_inverse_problem.

Type:

Proxy to

Type:

py

property prior

Prediction Operators (Time-dependent Goal Operator)

A module that provides implementation of time-dependent prediction (goal-oriented) operators for FEniCSx (dolfinx) time-dependent simulation models.

class DolfinLinearPredictionOperatorConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name='Time-dependent Goal-Oriented Prediction Operator (FEniCSx/dolfinx)', inverse_problem=None, prediction_time=0, prediction_coordinates=None)

Bases: GoalOrientedOperatorConfigs

Configurations class for the DolfinLinearPredictionOperator abstract base class. This class inherits functionality from GoalOrientedOperatorConfigs and only adds new class-level variables which can be updated as needed.

Parameters:

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

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

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

• inverse_problem (None | InverseProblem) – The inverse problem instance to be used with the goal operator (e.g., prediction operator)

• prediction_time (float) – prediction time (non-negative float)

• prediction_coordinates (None | Iterable) – if given, need to be an array with (x, y, …) coordinates at which to make prediction (restriction/observation operator)

prediction_time: float

prediction_coordinates: None | Iterable

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', name='Time-dependent Goal-Oriented Prediction Operator (FEniCSx/dolfinx)', inverse_problem=None, prediction_time=0, prediction_coordinates=None)

class DolfinLinearPredictionOperator(configs=None)

Bases: GoalOrientedOperator

An implementation of a linear goal-oriented time-dependent prediction operator for inverse problems with FEniCSx-based simulation models.

__init__(configs=None)

validate_configurations(configs, raise_for_invalid=True)

Each simulation optimizer SHOULD implement it’s own function that validates its own configurations. If the validation is self contained (validates all configuations), then that’s it. However, one can just validate the configurations of of the immediate class and call super to validate configurations associated with the parent class.

If one does not wish to do any validation (we strongly advise against that), simply add the signature of this function to the optimizer class.

Note

The purpose of this method is to make sure that the settings in the configurations object self._CONFIGURATIONS are of the right type/values and are conformable with each other. This function is called upon instantiation of the object, and each time a configuration value is updated. Thus, this function need to be inexpensive and should not do heavy computations.

Parameters:

configs (dict | GoalOrientedOperatorConfigs) – configurations to validate. If a InverseProblemonfigs object is passed, validation is performed on the entire set of configurations. However, if a dictionary is passed, validation is performed only on the configurations corresponding to the keys in the dictionary.

Raises:

• PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

• AttributeError – if any (or a group) of the configurations does not exist in the optimizer configurations GoalOrientedOperatorConfigs.

update_configurations(**kwargs)

Take any set of keyword arguments, and lookup each in the configurations, and update as nessesary/possible/valid

Raises:

PyOEDConfigsValidationError – if invalid configurations passed

generate_vector(init_val=0, return_np=True)

Generate vector compatible with the prediction space

update_prediction_operator(prediction_coordinates)

Update the prediction operator based on the prediction coordinates

Parameters:

prediction_coordinates – the prediction coordinates to use to create the prediction operator. If None, the prediction operator is set to None

apply(x)

Apply the prediction operator

apply_adjoint(x, eval_at=None)

Apply the adjoint of the prediction operator

property prediction_operator

property size

Dimension/Size of the goal space (size of a goal vector)

Note

Better implementation should be provided to return dimension without creating a vector.