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. ‘gasparicohn’, ‘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: Nonnegative 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. ‘gasparicohn’, ‘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. ‘gasparicohn’, ‘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 pointwise multiplication of the decorrelation array/function and the passed
covariance_arrayParameters:  covariance_array –
 localization_function –
 localization_radius –
 *argv –
 **kwargs –
Returns: localized_covariance

apply_state_covariance_localization
(covariance_array, localization_function=None, localization_radius=None, *argv, **kwargs)¶ Apply localization/decorrelation to a given statebased square array. This generally a pointwise multiplication of the decorrelation array/function and the passed
covariance_arrayParameters:  covariance_array –
 localization_function –
 localization_radius –
 *argv –
 **kwargs –
Returns: 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 –
Returns: Return type: 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 statedependent 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 –
Returns: 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 –
Returns: 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
 ensemblebased data assimilation.
All ensembles in DATeS are lists of state_vector objects.
Parameters:  ensemble_size –
 *argv –
 **kwargs –
Returns: list of model states
Return type: initial_ensemble

create_model_error_model
(configs=None, *argv, **kwargs)¶ Create a model error model
Parameters:  configs –
 *argv –
 **kwargs –
Returns: model_error_model

create_observation_error_model
(configs=None, *argv, **kwargs)¶ Create an observation error model
Parameters:  configs –
 *argv –
 **kwargs –
Returns: observation_error_model

ensemble_covariance_matrix
(ensemble, localize=False, *argv, **kwargs)¶ Construct an ensemblebased covariance matrix
Parameters:  ensemble – a list (ensemble) of model states
 localize (default False) – flag upon which spatial decorrelation is applied or not.
 *argv –
 **kwargs –
Returns: state_matrix containing ensemblebased covariances.
Return type: 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 –
Returns: the Jacobian of the observation operator evaluated at the passed in_state
Return type: 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 –
Returns: equivalent observation vector of the passed in_state. observation = H(in_state)
Return type: observation

get_model_configs
(*argv, **kwargs)¶ Return a dictionary containing model configurations.
Parameters:  *argv –
 **kwargs –
Returns: a dictionary containing model configurations. can be used e.g. for file output.
Return type: 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 nonzero dimensional models. For zero dimensional models this will be straight forward, but for nonzeros dimensional models, this has to be handled carefully.
Parameters:  index – state vector index (0:state_size1)
 radius – radius of influence
 *argv –
 **kwargs –
Returns: a list containing spatial indexes with the radius of influence from the passed index
Return type: 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.
Returns: 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.
Return type: 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.
Returns: 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.
Return type: trajectory

observation_dimension
()¶ Return the size of the state vector
Returns: Return type: 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 –
Returns: Return type:

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: Return type: 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 –
Returns: Return type:

observation_vector_size
()¶ return the size of an observation vector given the currently defined observation operator
Returns: Return type: 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 –
Returns: observation_vector read from file
Return type: 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 –
Returns: state_vector read from file
Return type: state

state_dimension
()¶ Return the size of the state vector
Returns: Return type: 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 –
Returns: Return type:

state_size
()¶ Return the size of the state vector
Returns: Return type: 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 –
Returns: Return type:

state_vector_size
()¶ Return the size of the state vector
Returns: Return type: state_size

step_forward_function
(time_point, in_state, *argv, **kwargs)¶  In the simplest case, this implements the righthand side of the model and evaluates it at
 the given model state_vector
Parameters:  time_point –
 in_state –
 *argv –
 **kwargs –
Returns: righthandside function value

step_forward_function_Jacobian
(time_point, in_state, *argv, **kwargs)¶  The Jacobian of the righthand side of the model and evaluate it at the given model state.
 rhs: the derivative/Jacobian of the righthand 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 timevarying.
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 –
Returns: 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 –
Returns: None
 model_configs –