Interpolation Observation Operators#

`ArrayOperator`([configs])	This class implements a linear observation operator given its array representation.
`SelectionOperator`([configs])	This class implements an observation operator that is selects entries of the state vector.

This module implements very simple array-like observation operators. This includes ArrayOperator and SelectionOperator.

class ArrayOperatorConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=None, model=None, observation_array=None)[source]#

Bases: ObservationOperatorConfigs

Configuration class for ArrayOperator

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.
design (None | bool | Sequence[bool] | ndarray[bool]) –
an experimental design to define active/inactive entries of the observation vector.

Note

An experimental design here is always binary (on/off) indicating which entries of the design space are active/inactive. This corresponds to turning on/off some of the observational sensors. Thus, if the design is None, it is set to all ones; that is everything is observed
model (SimulationModel | None) – the simulation model to use
observation_array (ndarray | None) – The array/matrix representation of the observation operator

model: SimulationModel | None#

observation_array: ndarray | None#

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=None, model=None, observation_array=None)#

class ArrayOperator(configs=None)[source]#

Bases: ObservationOperator

This class implements a linear observation operator given its array representation. The operator is thus both linear and constant.

All functions/methods return a restriction of the states passed as arguments to the observation space by dot product with the underlying array represenation of the observation operator passed upon initialization.

In addition to standard functionality, here we provide a specific attribute ‘design’ which enables modifying the observation space by projection/selection.

If the design is a binary vector (bool or int dtype attributes with 0/1 entries), the observation operator restricts observations to only entries identified by the 1/True entries. This acts like sensor placing/activation where 1 means ON/ACTIVE, and 0 means OFF.
If the design contains non-binary values, it is transformed to boolean flag; any entry in the design variable that’s not zero is set to 1.

Raises:: PyOEDConfigsValidationError – if the passed model is not an instance of pyoed.models.SimulationModel.

__init__(configs=None)[source]#

validate_configurations(configs, raise_for_invalid=True)[source]#

Check the passed configuratios and make sure they are conformable with each other, and with current configurations once combined. This guarantees that any key-value pair passed in configs can be properly used

Note

Here only the locally-defined configurations in ArrayOperatorConfigs are validated. Finally, super classes validators are called.

Parameters:

configs – full or partial (subset) configurations to be validated
raise_for_invalid – if True raise an error for invalid configrations type/key. Default True

Returns:

flag indicating whether passed configurations dictionary is valid or not

Raises:

AttributeError – if any (or a group) of the configurations does not exist in the model configurations ArrayOperatorConfigs.
PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

update_configurations(**kwargs)[source]#

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

Raises:: TypeError – if any of the passed keys in kwargs is invalid/unrecognized

update_observation_array(observation_array)[source]#: Update the observation array (representation of the linear operator).

apply(state, eval_at_t=None)[source]#

Given a state/parameter vector (laid out as defined by the model grid passed upon instantiation), evaluate the observation vector by applying (matrix-vector product) the underlying observation array, that is the selection operator.

Parameters:

state – instance of a model state with entries corresponding the model grid passed upon instantiation
eval_at_t – the time at which the observation operator is evaluated. Since some observation operators are time-dependent, this parameter is added for generality and for a unified interface.

Returns:

an observation vector/instance

Raises:

TypeError is raised if state has the wrong shape.

Jacobian_T_matvec(observation, eval_at=None, eval_at_t=None)[source]#

Multiply (Matrix-free matrix-vector product) of transpose of the Jacobian/tangent-linear (TLM) of the observation operator by the passed observation; The Jacobian is evaluated (for nonlinear operators) at eval_at

Parameters:

observation – observation instance/vector
eval_at – state around which observation operator is linearized; ignored here since the observation operator here is linear
eval_at_t – the time at which the observation operator is evaluated. Since some observation operators are time-dependent, this parameter is added for generality and for a unified interface.

Returns:

result of multiplying the transpose of derivative of the observation operator by the passed observation

Raises:

TypeError – if the passed observation is invalid (type/shape/etc.)

property shape#: The shape of the observation operator discarding any experimental design. An observation operator maps the model state onto the observation space. Thus, the shape of the observation operator here is defined as a tuple on the form \((ny, nx)\) where \(ny\) is the size of the observation vector, and nx is the size of the state vector.

Note

The shape of the operator is INDEPENDENT from the design and defines the codomain of the operator \(ny\) assuming all entries of the design are active. To get the shape of the operator corresponding to the active entries of the design only use active_shape().

property observation_array#: A COPY of the underlying observation array. If you want access to the observation array itself use self.configurations.observation_array instead.

property model#: The underlying simulation model

class SelectionOperatorConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=None, model=None, observation_indexes=None, target='state')[source]#

Bases: ObservationOperatorConfigs

Configuration class for SelectionOperator

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.
design (None | bool | Sequence[bool] | ndarray[bool]) –
an experimental design to define active/inactive entries of the observation vector.

Note

An experimental design here is always binary (on/off) indicating which entries of the design space are active/inactive. This corresponds to turning on/off some of the observational sensors. Thus, if the design is None, it is set to all ones; that is everything is observed
model (SimulationModel | None) – the simulation model to use
observation_indexes (ndarray | None) – indexes of the model state_vector to select.
target (str) – either ‘state’ or ‘observation’

model: SimulationModel | None#

observation_indexes: ndarray | None#

target: str#

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', design=None, model=None, observation_indexes=None, target='state')#

class SelectionOperator(configs=None)[source]#

Bases: ObservationOperator

This class implements an observation operator that is selects entries of the state vector. The operator is thus both linear and constant.

All functions/methods return a restriction of the states passed as arguments to the observation indexes

In addition to standard functionality, here we provide a specific attribute ‘design’ which enables modifying the space of the error model by projection or reweighting:

If the design is a binary vector (bool or int dtype attributes with 0/1 entries) the mean, the covariance, and all random vectors are projected onto the space identified by the 1/True entries.

If the design contains non-binary values, the covariance matrix is weighted based on the design as follows. The underlying Cholesky decomposition of the distribution covariance is premultiplied by a design matrix with the design set to its diagonal. This is the standard relaxed OED formulation

Note

This operator is added for convience. It is in fact equivalent to ArrayOperator with the observation_array equal to a short-wide array with each row (and column) containing one and only one entry equal to 1, and everything else is equal to zero.

Parameters:

model – the simulation model to use
observation_indexes – indexes of the model state_vector to select.

__init__(configs=None)[source]#

validate_configurations(configs, raise_for_invalid=True)[source]#

Check the passed configuratios and make sure they are conformable with each other, and with current configurations once combined. This guarantees that any key-value pair passed in configs can be properly used

Note

Here only the locally-defined configurations in ArrayOperatorConfigs are validated. Finally, super classes validators are called.

Parameters:

configs – full or partial (subset) configurations to be validated
raise_for_invalid – if True raise an error for invalid configrations type/key. Default True

Returns:

flag indicating whether passed configurations dictionary is valid or not

Raises:

AttributeError – if any (or a group) of the configurations does not exist in the model configurations ArrayOperatorConfigs.
PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

update_configurations(**kwargs)[source]#

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

Raises:: TypeError – if any of the passed keys in kwargs is invalid/unrecognized

update_observation_indexes(observation_indexes)[source]#: Update the observation array (representation of the linear operator).

apply(state, eval_at_t=None)[source]#

Given a state/parameter vector (laid out as defined by the model grid passed upon instantiation), evaluate the observation vector by applying (matrix-vector product) the underlying observation array.

Parameters:

state – instance of a model state with entries corresponding the model grid passed upon instantiation
eval_at_t – the time at which the observation operator is evaluated. Since some observation operators are time-dependent, this parameter is added for generality and for a unified interface.

Returns:

an observation vector/instance

Raises:

TypeError is raised if state has the wrong shape.

Jacobian_T_matvec(observation, eval_at=None, eval_at_t=None)[source]#

Multiply (Matrix-free matrix-vector product) of transpose of the Jacobian/tangent-linear (TLM) of the observation operator by the passed observation; The Jacobian is evaluated (for nonlinear operators) at eval_at

Parameters:

observation – observation instance/vector
eval_at – state around which observation operator is linearized; ignored here since the observation operator here is linear
eval_at_t – the time at which the observation operator is evaluated. Since some observation operators are time-dependent, this parameter is added for generality and for a unified interface.

Returns:

result of multiplying the transpose of derivative of the observation operator by the passed observation

Raises:

TypeError – if the passed observation is invalid (type/shape/etc.)

property shape#: The shape of the observation operator discarding any experimental design. An observation operator maps the model state onto the observation space. Thus, the shape of the observation operator here is defined as a tuple on the form \((ny, nx)\) where \(ny\) is the size of the observation vector, and nx is the size of the state vector.

Note

The shape of the operator is INDEPENDENT from the design and defines the codomain of the operator \(ny\) assuming all entries of the design are active. To get the shape of the operator corresponding to the active entries of the design only use active_shape().

property observation_indexes#: A COPY of the array holding observation indexes.

property model#: The underlying simulation model