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
Returns:

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
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 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
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
ensemble-based 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 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
Returns:

state_matrix containing ensemble-based 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 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
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_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:
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

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_matrix

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

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 right-hand side of the model and evaluates it at
the given model state_vector
Parameters:
  • time_point
  • in_state
  • *argv
  • **kwargs
Returns:

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