Blackbox Models

TimeIndependentBlackBox([configs])	Wrapper simulation model for time independent models with some user provided black box forward model.
create_TimeIndependentBlackBox_model(...[, ...])	A simple interface to creating an instance of TimeIndependentBlackBox.

class TimeIndependentBlackBoxConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name=None, screen_output_iter=1, file_output_iter=1, solve_forward=None, N_p=1, N_x=1, Jacobian_T_matvec=None)

Bases: TimeIndependentModelConfigs

Configuration class for TimeIndependentBlackBox model. solve_forward, N_p, and N_x are required fields, whereas Jacobian_T_matvec is optional.

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.

• 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.

• solve_forward (Callable[[ndarray], ndarray] | None) – A callable that takes a np.ndarray of size N_p and returns a np.ndarray of size N_x.

• N_p (int) – Number of parameters. Must be an int > 0.

• N_x (int) – Number of state variables. Must be an int > 0.

• Jacobian_T_matvec (Callable[[ndarray, ndarray], ndarray] | None) – A callable that takes a np.ndarray of size N_x and a np.ndarray of size N_p and returns a np.ndarray of size N_p. This is the Jacobian of the solve_forward function transposed, evaluated in the direction of the second argument. If this is not provided, then a finite-difference approximation is used (expensive!).

solve_forward: Callable[[ndarray], ndarray] | None

N_p: int

N_x: int

Jacobian_T_matvec: Callable[[ndarray, ndarray], ndarray] | None

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

class TimeIndependentBlackBox(configs=None)

Bases: TimeIndependentModel

Wrapper simulation model for time independent models with some user provided black box forward model.

Parameters:

configs (TimeIndependentBlackBoxConfigs | dict | None) – Configurations of the model, either as a TimeIndependentBlackBoxConfigs object, a dictionary, or None. The default is None, in which case the default configurations are used.

__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

Note

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

Parameters:

• configs (dict | TimeIndependentBlackBoxConfigs) – full or partial (subset) configurations to be validated

• raise_for_invalid (bool) – if True raise TypeError 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 TimeIndependentBlackBoxConfigs.

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

Return type:

bool

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

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

is_parameter_vector(parameter, **kwargs)

Test whether the passed parameter vector is valid or not

is_state_vector(state, **kwargs)

Test whether the passed state vector is valid or not

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.

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

Returns:

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

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. If the Jacobian is not provided by the user (i.e. Jacobian_T_matvec is None), then a finite-difference approximation is used.

Parameters:

• state – state to multiply the Jacobian by

• eval_at – state around which the Jacobian is evaluated

property N_x

Number of state variables

property N_p

Number of parameters

create_TimeIndependentBlackBox_model(solve_forward, Np, Nx, Jacobian_T_matvec=None)

A simple interface to creating an instance of TimeIndependentBlackBox.

Parameters:

• solve_forward (Callable[[np.ndarray], np.ndarray]) – a callable that takes a np.ndarray of size N_p and returns a np.ndarray of size N_x.

• N_p (int) – number of parameters of the model.

• N_x (int) – number of state variables.

• Jacobian_T_matvec (Callable[[np.ndarray, np.ndarray], np.ndarray]) – a callable that takes a np.ndarray of size N_x and a np.ndarray of size N_p and returns a np.ndarray of size N_p. This is the Jacobian of the solve_forward function transposed, evaluated in the direction of the second argument. If this is not provided, then a finite-difference approximation is used (expensive!).