Core (Base Classes) of Models

Abstract class for simulation models. Code snippets given in the abstract methods is just given as an example, but will never utilized

class SimulationModelConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name=None, screen_output_iter=1, file_output_iter=1)

Bases: PyOEDConfigs

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

See PyOEDConfigs for more details on the functionality of this class along with a few additional fields. Otherwise SimulationModelConfigs provides the following fields:

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.

• model_name (str | None) – name of the model. Default is None.

• screen_output_iter (int) – iteration interval for screen output. Default is 1. Note that this should be a positive integer to enforce proper effect.

• file_out_iter – iteration interval for file output. Default is 1. Note that this should be a positive integer to enforce proper effect.

model_name: str | None

screen_output_iter: int

file_output_iter: int

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name=None, screen_output_iter=1, file_output_iter=1)

class SimulationModel(configs=None)

Bases: PyOEDObject

Abstract class (following Python’s abc convention) for Simulation models (both time-dependent and time-independent)’ (wrappers’) implementation.

The implementation in classes inheriting this base class MUST carry out all essential tasks (marked with abstractmethod decorators) which in turn should be provided by dynamical model.

Note

Each class derived from SimulationModel should have its own __init__ method in which the constructor just calls super().__init__(configs=configs) and then add any additiona initialization as needed. The validation self.validate_configurations() is carried out at the initialization time by the base class SimulationModel. See for example, the __init__ method of TimeIndependentModel.

Note

The structure is similar to DATeS base class for simulation models.

Parameters:

configs (dict | SimulationModelConfigs | None) – (optional) configurations for the model

__init__(configs=None)

validate_configurations(configs, raise_for_invalid=True)

Each simulation model 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 model 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 | SimulationModelConfigs) – configurations to validate. If a SimulationModelConfigs 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 model configurations ToyLinearTimeIndependentConfigs.

get_model_grid()

property model_grid

Retrieve a copy of the model grid (enumeration of all model grid coordinates as they are ranked in a model state vector) as an array

property state_size

An example to return the model state size; this should be overwridden by a more efficient implementation that does not require building a full state vector

property parameter_size

An example to return the model parameter size; this should be overwridden by a more efficient implementation that does not require building a full parameter vector

class TimeIndependentModelConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name=None, screen_output_iter=1, file_output_iter=1)

Bases: SimulationModelConfigs

Configuration dataclass for the TimeIndependentModel abstract base class. This class mirrors SimulationModelConfigs and does not add additional features/attributes.

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.

• model_name (str | None) – name of the model. Default is None.

• screen_output_iter (int) – iteration interval for screen output. Default is 1. Note that this should be a positive integer to enforce proper effect.

• file_out_iter – iteration interval for file output. Default is 1. Note that this should be a positive integer to enforce proper effect.

model_name: str | None

screen_output_iter: int

file_output_iter: int

class TimeIndependentModel(configs)

Bases: SimulationModel

Base class for time-independent models (such as tomography, ptychography, etc.)

The implementation in classes inheriting this base class MUST carry out all essential tasks (marked with abstractmethod decorators) which in turn should be provided by dynamical model.

Parameters:

configs ([dict | SimulationModelConfigs | None]) – (optional) configurations for the model

__init__(configs)

validate_configurations(configs, raise_for_invalid=True)

Each simulation model 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 model class.

Note

The purposed 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 | TimeIndependentModelConfigs) – configurations to validate. If a SimulationModelConfigs 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 model configurations ToyLinearTimeIndependentConfigs.

abstract state_vector(init_val=0, **kwargs)

Create an instance of model state vector

Parameters:

init_val (float) – (optional) value assigned to entries of the state vector upon initialization

abstract parameter_vector(init_val=0, **kwargs)

Create an instance of model parameter vector

Parameters:

init_val (float) – (optional) value assigned to entries of the parameter vector upon initialization

abstract is_state_vector(state, **kwargs)

Test whether the passed state vector is valid or not

abstract is_parameter_vector(parameter, **kwargs)

Test whether the passed parameter vector is valid or not

abstract solve_forward(state, verbose=False)

Apply (solve the forward model) to the given state,

and return the result.

Parameters:

• state – state to which the forward model is applied.

• verboe (bool) – flag to control screen-verbosity

Returns:

result (usually an observation vector) resulting from applying the forward model to state

apply(*args, **kwargs)

calls self.solve_forward()

solve_adjoint(adjoint)

solve the adjoint problem (solve the model backward) to the

given adjoint, and return the result.

Parameters:

adjoint – adjoint to which the forward model is applied.

Returns:

result resulting from applying the adjoint model to adjoint

Jacobian_T_matvec(state, eval_at)

Evaluate and return the product of the Jacobian (of the right-hand-side) of

the model (TLM) transposed, by a model state.

Parameters:

• state – state to multiply the Jacobian by

• eval_at – state around which the Jacobian is evaluated

class TimeDependentModelConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name=None, screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>)

Bases: SimulationModelConfigs

Configuration dataclass for the TimeDependentModel 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.

• model_name (str | None) – name of the model. Default is None.

• screen_output_iter (int) – iteration interval for screen output. Default is 1. Note that this should be a positive integer to enforce proper effect.

• file_out_iter – iteration interval for file output. Default is 1. Note that this should be a positive integer to enforce proper effect.

• time_integration (dict | None) –

  dictionary holding time integration configurations:

  • scheme: string specifying the time integration scheme (e.g., ‘RK4’, ‘RK45’, ‘BDF’, etc.). Default is None.

  • stepsize: float specifying the time integration stepsize. Default is None.

  • adaptive: bool specifying whether the time integration is adaptive. Default is False.

• num_prognostic_variables (int | None) – number of prognostic variables in the model. Default is None. Must be a positive integer if not None.

• space_discretization (dict | None) –

  dictionary holding space discretization configurations. Contains:

  • scheme: string specifying the space discretization scheme (e.g., ‘FD’, ‘FE’, ‘BE’, etc.). Default is None.

time_integration: dict | None

num_prognostic_variables: int | None

space_discretization: dict | None

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name=None, screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>)

class TimeDependentModel(configs=None)

Bases: SimulationModel

Abstract class (following Python’s abc convention) for PyOED dynamical models’ (wrappers’) implementation.

A base class for dynamical models implementations/wrappers.

The implementation in classes inheriting this base class MUST carry out

all essential tasks (marked with abstractmethod decorators) which in turn should be provided by dynamical model.

The structure is similar to DATeS base class for simulation models.

__init__(configs=None)

validate_configurations(configs, raise_for_invalid=True)

Validation stage for the the passed configs.

Parameters:

configs (dict | TimeDependentModelConfigs) – configurations to validate. If a TimeDependentModelConfigs 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 model configurations ToyLinearTimeIndependentConfigs.

abstract state_vector(t=None, init_val=0, **kwargs)

Create an instance of model state vector

Parameters:

t – (optional) time assigned to the state vector (for time dependent models); None otherwise

abstract is_state_vector(state, **kwargs)

Test whether the passed state vector is valid or not

abstract integrate_state(state, tspan, checkpoints, *argv, **kwargs)

Simulate/integrate the mdoel starting from the initial state over the passed checkpoints.

If state is assigned a time t, it is replaced with the first entry of checkpoints.

Parameters:

• state – data structure holding the initial model state

• tspan – (t0, tf) iterable with two entries specifying of the time integration window

• checkpoints – times at which to store the computed solution, must be sorted and lie within tspan. If None (default), use points selected by the solver [t0, t1, …, tf].

Returns:

timespan and a trajectory (checkpointed solution): - the timespan is an iterable (e.g., a list) hodlding timepoints at which state is propagated, - the trajectory is an iterable (e.g., a list) holding the model trajectory with entries corresponding to the simulated model state at entries of checkpoints starting from checkpoints[0] and ending at checkpoints[-1].

Jacobian_T_matvec(state, eval_at_t, eval_at)

Evaluate and return the product of the Jacobian (of the right-hand-side) of

the model (TLM) transposed, by a model state.

Parameters:

• state – state to multiply the Jacobian by

• eval_at_t – time at which the Jacobian is evaluated

• eval_at – state around which the Jacobian is evaluated

class ErrorModelConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_')

Bases: PyOEDConfigs

Base configuration class for error models

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.

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_')

class ErrorModel(configs=None)

Bases: PyOEDObject

Base class for error models. The simplest is a Gaussian error model. More will be added as needed.

__init__(configs=None)

validate_configurations(configs, raise_for_invalid=True)

Each simulation model MUST 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 model class.

Note

The purposed 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 | PyOEDConfigs) – configurations to validate. If a PyOEDConfigs 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 model configurations PyOEDConfigs.

abstract generate_noise()

Generate a random noise vector sampled from the underlying distribution

abstract sample()

Sample a random vector from the underlying distribution

pdf(*args, **kwargs)

Evaluate the value of the density function (normalized or upto a fixed scaling constant) at the passed state/vector.

pdf_gradient(*args, **kwargs)

Evaluate the gradient of the density function at the passed state/vector.

log_density(*args, **kwargs)

Evaluate the logarithm of the density function at the passed state x.

log_density_gradient(*args, **kwargs)

Evaluate the gradient of the logarithm of the density function at the passed state.

property supports_relaxation

Flag to check whether the model supports relaxation or not

abstract property size

Dimension of the underlying probability distribution

property active

Flags (boolean 1d array-like) corresponding to active/inactive dimensions

property random_seed

Registered random seed (if available in configurations)

abstract property active_size

Dimension of the probability distribution projected onto the design space (only active/nonzero entries of the design)

abstract property design

A copy of the design vector

abstract property extended_design

A vector (1d array-like) indicating active/inactive entries (with proper replication for multiple prognostic variables) of the observation vector/range

Base class for observation operators: transform a model state into an observaiton

class ObservationOperatorConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_')

Bases: PyOEDConfigs

Base configuration class for observation operators.

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.

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_')

class ObservationOperator(configs=None)

Bases: PyOEDObject

Base class for observation operators: transform a model state into an observaiton

__init__(configs=None)

validate_configurations(configs, raise_for_invalid=True)

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

Parameters:

• configs (dict) – a dictionary holding key/value configurations

• raise_for_invalid (bool) – if True raise TypeError for invalid configrations type/key

Returns:

bool flag indicating whether passed coinfigurations dictionary is valid or not

Raises:

see the parameter raise_for_invalid

Return type:

bool

abstract observation_vector(*args, **kwargs)

Create an observation vector

abstract apply(state, **kwargs)

Apply the observation operator to a model state, and return an observation instance

Jacobian_T_matvec(observation, eval_at, **kwargs)

Evaluate and return the product of the Jacobian (tangent-linear (TLM) of the observation operator),

evaluated at eval_at transposed multiplied by the passed observation.

abstract is_observation_vector(observation, **kwargs)

Test whether the passed observation vector is valid or not

property observation_size: int

An example to return the observation vector size; This should be overwridden by a more efficient implementation that does not require building a full state vector

copy()

Return a copy of this observation operator by creating a new instance of this object with registered the configurations.