TODO: A bit about Forecast Models...

# Numerical Forecast Models¶

## Models Base Class¶

class ModelsBase(model_configs=None, output_configs=None, *argv, **kwargs)

Bases: object

Abstract class for DATeS dynamical models’ (wrappers’) implementation.

A base class for dynamical models implementations/wrappers. The implementation in classes inheriting this base class should carry out all essential tasks should be generally provided by dynamical model (wrappers).

Remarks The methods defined here are all the essential methods needed by all the assimilation implemented by default in DATeS releases.

Parameters: model_configs – dict, A configurations dictionary for model settings This is expected to vary greately from one model to another. The configs provided here are just guidelines. Supported Configurations: * model_name: string representation of the model name * time_integration_scheme: decides what time integration used to propagate model state and/or perturbations forward/backward in time. default_step_size: optimized (stable) step size for model propagation. This can be usefule when long timesteps in timespans passed to the forward propagation method num_prognostic_variables: Number of prognostic/physical variables at each gridpoint. model_grid_type: ‘cartesian’, ‘spherical’, etc. num_spatial_dimensions: number of dimensions in the physical domain. model_errors_distribution: probability distribution of model errors (e.g. for imperfect model with additive noise) model_error_variances: an iterable that contains the model errors’ variances (e.g. for models with Gaussian model errors) model_errors_covariance_localization_function: e.g. ‘gaspari-cohn’, ‘gauss’, etc. model_errors_covariance_localization_radius: radius of influence for model error covariance matrix localization model_errors_covariance_method’: an indicator of the method used to construct model error covariances model_errors_steps_per_model_steps: Non-negative integer; number of model steps after which (additive) model noise are added to the model state when the time integrator is called to propagate the model.state_vector forward in time. If the value is zero, no model errors are incorporated (Perfect Model). observation_operator_type (default ‘linear’): type of the relation between model state and observations, e.g. ‘linear’, etc. observation_vector_size: size of the observation vector. This can be used e.g. to control the observation operator construction process observation_errors_distribution (default ‘gaussian’): probability distribution of observational errors (e.g. defining the likelihood fuction in the data assimialtion settings) observation_errors_variances: an iterable that contains the observational errors’ variances observation_errors_covariance_method: an indicator of the method used to construct observational error covariances observation_errors_covariance_localization_function: e.g. ‘gaspari-cohn’, ‘gauss’, etc. observation_errors_covariance_localization_radius: radius of influence for observation error covariance matrix localization background_error_variances: an iterable that contains the background errors’ variances background_errors_covariance_localization_function: e.g. ‘gaspari-cohn’, ‘gauss’, etc. background_errors_covariance_localization_radius: radius of influence for background error covariance matrix localization background_errors_covariance_method’: an indicator of the method used to construct background error covariances output_configs – dict, A dictionary containing screen/file output configurations for the model Supported configuarations: scr_output (default False): Output results to screen on/off switch scr_output_iter (default 1): printing to screen after this number of model steps verbose (default False): This is used for extensive screen outputting e.g. while debugging. This overrides scr_output. file_output (default False): Output results to file on/off switch file_output_iter (default 1): saving model results to file after this number of model steps file_output_dir: Location to save model output to (if file_output is set to True). Some default directory should be provided by model or an exception will be thrown.

Methods

__init__(model_configs=None, output_configs=None, *argv, **kwargs)
apply_observation_covariance_localization(covariance_array, localization_function=None, localization_radius=None, *argv, **kwargs)

Apply localization/decorrelation to a given observation square array. This generally a point-wise multiplication of the decorrelation array/function and the passed

covariance_array
Parameters: covariance_array – localization_function – localization_radius – *argv – **kwargs – localized_covariance
apply_state_covariance_localization(covariance_array, localization_function=None, localization_radius=None, *argv, **kwargs)

Apply localization/decorrelation to a given state-based square array. This generally a point-wise multiplication of the decorrelation array/function and the passed

covariance_array
Parameters: covariance_array – localization_function – localization_radius – *argv – **kwargs – localized_covariance
construct_model_grids(*argv, **kwargs)

Either construct the spatial grids of the model (if the model is fully implemented in Python), or obtain model grids from the given implementation (probably by a simple run and read output

files or so.)
Parameters: *argv – **kwargs – model_grid
construct_observation_operator(*argv, **kwargs)

Construct the observation operator (H) in full. This should be avoided in practice. We need it’s (or it’s TLM) effect on a state vector always.

Parameters: *argv – **kwargs –
construct_observation_operator_Jacobian(*argv, **kwargs)

This creates the Jacobian of the observation operator (forward operator). This could be a constant matrix if the observation operator is linear, or state-dependent matrix This might be called by evaluate_observation_operator_Jacobian if needed. Most of the models won’t need it.

Parameters: *argv – **kwargs –
create_background_error_model(configs=None, *argv, **kwargs)

Create an observation error model

Parameters: configs – *argv – **kwargs – background_error_model
create_initial_condition(*argv, **kwargs)
Create initial condition state for the model. This state can be used as reference initial condition
in the experimental data assimilation settings.
Parameters: *argv – **kwargs – model_state
create_initial_ensemble(ensemble_size, *argv, **kwargs)
create an ensemble of states. This can be used for example as an initial ensemble in the
ensemble-based data assimilation.

All ensembles in DATeS are lists of state_vector objects.

Parameters: ensemble_size – *argv – **kwargs – list of model states initial_ensemble
create_model_error_model(configs=None, *argv, **kwargs)

Create a model error model

Parameters: configs – *argv – **kwargs – model_error_model
create_observation_error_model(configs=None, *argv, **kwargs)

Create an observation error model

Parameters: configs – *argv – **kwargs – observation_error_model
ensemble_covariance_matrix(ensemble, localize=False, *argv, **kwargs)

Construct an ensemble-based covariance matrix

Parameters: ensemble – a list (ensemble) of model states localize (default False) – flag upon which spatial decorrelation is applied or not. *argv – **kwargs – state_matrix containing ensemble-based covariances. ensemble_covariances
evaluate_observation_operator_Jacobian(in_state, *argv, **kwargs)
Evaluate the Jacobian of the observation operator at specific model state.
i.e. evaluate $mathbf{H}$ evaluated at in_state.
Parameters: in_state – model.state_vector to evaluate the Jacobian of the observation operator at *argv – **kwargs – the Jacobian of the observation operator evaluated at the passed in_state Jacobian
evaluate_theoretical_observation(in_state, *argv, **kwargs)

Evaluate the theoretical observation corresponding to a model state vector, i.e. evaluate H(state), where H is the observation operator.

Parameters: in_state – model.state_vector to be projected onto the observation space *argv – **kwargs – equivalent observation vector of the passed in_state. observation = H(in_state) observation
get_model_configs(*argv, **kwargs)

Return a dictionary containing model configurations.

Parameters: *argv – **kwargs – a dictionary containing model configurations. can be used e.g. for file output. configs
get_neighbors_indexes(index, radius, *argv, **kwargs)

A function that returns the indexes within a given radius of influence w.r.t. a given index in the state vector. Of course this will be different for non-zero dimensional models. For zero dimensional models this will be straight forward, but for non-zeros dimensional models, this has to be handled carefully.

Parameters: index – state vector index (0:state_size-1) radius – radius of influence *argv – **kwargs – a list containing spatial indexes with the radius of influence from the passed index indexes_list
integrate_state(initial_state, checkpoints, *argv, **kwargs)

March the model state forward in time (backward for negative step or decreasing list).

Parameters: initial_state – model.state_vector to be propagated froward according to checkpoints checkpoints – a timespan that should be a float scalar (taken as one step) or an iterable including beginning, end, or a full timespan to build model trajectory at. model trajectory. this can be either a list of model state_vector objects (e.g. if checkpoints is an iterable) or simply a single state_vector if checkpoints is a scalar. trajectory
integrate_state_perturbations(initial_perturbations, checkpoints, *argv, **kwargs)

March the model state perturbations forward in time (backward for negative step or decreasing list).

Parameters: initial_perturbations – model.state_vector to be propagated froward according to checkpoints checkpoints – a timespan that should be a float scalar (taken as one step) or an iterable including beginning, end, or a full timespan to build model trajectory at. model trajectory. this can be either a list of model state_vector objects (e.g. if checkpoints is an iterable) or simply a single state_vector if checkpoints is a scalar. trajectory
observation_dimension()

Return the size of the state vector

Returns: state_size
observation_matrix(observation_matrix_ref=None, *argv, **kwargs)

Create a wrapper for a model matrix data structure, and return a reference to it. This can hold things such as observation error covariance matrix. observation_matrix_ref could be a numpy array, pointer to C/Fortran array, etc.

Parameters: observation_matrix_ref – *argv – **kwargs – observation_matrix
observation_operator_Jacobian_T_prod_vec(in_state, observation, *argv, **kwargs)
Multiply the transpose of the Jacobian of the observation operator evaluated at in_state by observation
i.e. evaluate $mathbf{H}^T imes ext{observation}$, where $mathbf{H}$ is evaluated at in_state . Should generally be time dependent...

The result is a state vector of course

Parameters: in_state – model.state_vector to evaluate the Jacobian of the observation operator at observation – *argv – **kwargs –
observation_operator_Jacobian_prod_vec(in_state, state, *argv, **kwargs)
Multiply the Jacobian of the observation operator (evaluated at in_state) by state
i.e. evaluate $mathbf{H} imes ext{state}$.

The result is an observation vector

Parameters: in_state – model.state_vector to evaluate the Jacobian of the observation operator at *argv – **kwargs –
observation_size()

Return the size of the state vector

Returns: state_size
observation_vector(observation_vector_ref=None, *argv, **kwargs)

Create a wrapper for a observation vector data structure, and return a reference to it. observation_vector_ref could be a numpy array, pointer to C/Fortran array, etc.

Parameters: observation_vector_ref – *argv – **kwargs – observation_vector
observation_vector_size()

return the size of an observation vector given the currently defined observation operator

Returns: state_size
read_observation(file_name, directory, *argv, **kwargs)

Read an observation vector from a file.

Parameters: file_name – name of the target file directory – location where observation vector will be read from *argv – **kwargs – observation_vector read from file observation
read_state(file_name, directory, *argv, **kwargs)

Save a state vector to a file.

Parameters: file_name – name of the target file directory – location where state vector will be read from *argv – **kwargs – state_vector read from file state
state_dimension()

Return the size of the state vector

Returns: state_size
state_matrix(state_matrix_ref=None, *argv, **kwargs)

Create a wrapper for a model matrix data structure, and return a reference to it. This can hold things such as model or background error covariance matrices. state_matrix_ref could be a numpy array, pointer to C/Fortran array, etc.

Parameters: state_matrix_ref – *argv – **kwargs – state_matrix
state_size()

Return the size of the state vector

Returns: state_size
state_vector(state_vector_ref=None, *argv, **kwargs)

Create a wrapper for a state vector data structure, and return a reference to it. state_vector_ref could be a numpy array, pointer to C/Fortran array, etc.

Parameters: state_vector_ref – *argv – **kwargs – state_vector
state_vector_size()

Return the size of the state vector

Returns: state_size
step_forward_function(time_point, in_state, *argv, **kwargs)
In the simplest case, this implements the right-hand side of the model and evaluates it at
the given model state_vector
Parameters: time_point – in_state – *argv – **kwargs – right-hand-side function value
step_forward_function_Jacobian(time_point, in_state, *argv, **kwargs)
The Jacobian of the right-hand side of the model and evaluate it at the given model state.
rhs: the derivative/Jacobian of the right-hand side function evaluated at ‘in_state’
update_observation_operator(time, *argv, **kwargs)

This should be called for each assimilation cycle if the observation operator is time-varying.

Parameters: time – *argv – **kwargs –
write_observation(observation, directory, file_name, *argv, **kwargs)

Save an observation vector to a file.

Parameters: observation – observation_vector to be written to file directory – location where observation vector will be saved file_name – name of the target file *argv – **kwargs – None
write_state(state, directory, file_name, *argv, **kwargs)

Save a state vector to a file.

Parameters: state – state_vector to be written to file directory – location where state vector will be saved file_name – name of the target file *argv – **kwargs – None