Configuring an Experiment

class DAPyr.Expt(name: str, params: dict = None)

Initialize a Data Assimilation experiment and configurable parameters.

modelParams

A dictionary containing all parameters initializing the chosen toy model.

Type:

dict

obsParams

A dictionary containing all parameters initializing observations.

Type:

dict

basicParams

A dictionary containing all parameters initializing basic experimental set-up.

Type:

dict

miscParams

A dictionary containing all parameters initializing output and other miscellaneous parameters.

Type:

dict

states

A dictionary containing all state vectors (model truth, observations, and initial ensemble states).

Type:

dict

copyStates(expt)

Copy the states (model truth, initial ensemble, and observations) from another experiment

Parameters:

expt (Expt) – The experiment to copy the states from.

Raises:
  • TypeError – Experiment instance not provided.

  • dapExceptions.MismatchModelSize – Model flags do not match between experiments.

  • dapExceptions.MismatchTimeSteps – Attempting to copy from experiment with less time steps than current experiment.

  • dapExceptions.MismatchObs – Number of assimilated observations do not match between experiments.

  • dapExceptions.MismatchEnsSize – Attempting to copy from experiment with less ensemble members than current experiment.

  • dapExceptions.MismatchOperator – Measurement operator flags do not match between experiments.

getBasicParams() tuple

Retrieve the basic parameters describing the experiment (Ne, Nx, T, and dt).

Returns:

  • Ne (int) – Number of ensemble members

  • Nx (int) – Number of model states

  • T (int) – Number of time steps the experiment will run for

  • dt (float) – The model time increment

getParam(param: str)

Retrieve the value of a parameter stored in the Expt class.

Note

getParam returns immutable instances of the state vectors xt, Y, and xf_0, meaning that modifying instances returned by getParam will not modifying the instances stored in the Expt object itself. To modify the states of an experiment after spinup, access them directly through the expt.states dictionary.

Parameters:

param (str) – Name of parameter to retrieve

Returns:

Value of the requested parameter

Return type:

param_value

getParamNames() list

Retrieve all modifiable parameters in the Expt class.

Parameters:

None

Returns:

a list of available parameters to modify

Return type:

list

getStates() tuple
Returns:

  • xf_0 (numpy.ndarray) – Initial ensemble state that begins the experiment. Size (Nx, Ne)

  • xt (numpy.ndarray) – Model truth states throughout the experiment. Size (T, Nx)

  • Y (numpy.ndarray) – Observations throughout the experiment. Size (Ny, T, 1)

modExpt(params: dict, reqUpdate: bool = False)

Modify a parameter in the Expt class, recalculating new initial states if necessary.

Note

Modifying most parameters will cause a recalculation of all state vectors. To maintain consistent ensemble states across modification, consider setting the seed parameter in your experiment.

Parameters:
  • params (dict) – A dictionary containing the parameter to modify and its new modified value

  • reqUpdate (bool) – A boolean determining whether recalculation of new states should be forced

modExptName(exptname: str) None

Modify the name of the Experiment

Parameters:

exptname (str) – New experiment name

resetParams()

Reset all Expt parameters to their default values.

saveExpt(outputdir: str = None)

Save the experiment to the filesystem. Experiments are saved with the filename [exptname].expt

Parameters:

outputdir (str, optional) – Path to directory where to save the experiment , by default the value stored in the output_dir parameter.

Configurable Paramters

basicParams

Parameters in the basicParams attribute store information that define the basic structure of the experiment, such as how long to run the experiment for, how many ensemble members to run, and what data assimilation method to use.

Paramter

Default

Description

T

100

Total number of time steps in experiment

dt

Model Specific

Model time step increment

Ne

10

Number of ensemble members

expt_flag

0

Flag to select which Data Assimilation method to use
0: EnSRF
1: Local Particle Filter
2: No Data Assimilation

seed

-1

Seed for random number generator. Set to -1 to turn off.

obsParams

The obsParams attribute stores all parameters relating to the observations to assimilation, from what measurement operator to use to prescribing observation error. Additionally, the obsParam attribute stores parameters relating to coniguring the data assimilation methods.

Paramter

Default

Description

h_flag

0

Flag to select measurement operator to use
0: Linear (Hx = x)
1: Quadratic (Hx = x^2)
2: Logarithmic (Hx = log(abs(x)))

sig_y

1.0

Observations Standard Deviation

tau

1

Number of cycles between data assimilation cycles

obf

1

Observation spatial frequency. Spacing between assimilated observations

obb

0

Observation buffer. Initial number of observations to skip, used to simulate large spatial gaps in observation coverage.

localize

1

Whether to turn on localization. 0 is off, 1 is on.

roi

0.005

Localization radius of influence

Kalman Filter Parameters

Below are all parameters directly configuring the ensemble square root filter.

Paramter

Default

Description

gamma

0.00

Inflation parameter for Relaxation to Prior Spread (RTPS).

Local Particle Filter Parameters

Below are all parameters directly configuring the local particle filter.

Paramter

Default

Description

mixing_gamma

0.3

Mixing coefficient between prior resampled particles and current particles

kddm_flag

0

Flag to turn on kernel density estimation step. 0 is off, 1 is on

min_res

0.0

Minimum residual for beta inflation

maxiter

1

Maximum number of incremental steps of LPF updates to make

Nt_eff

0.4

Effective ensemble size

modelParams

The modelParams attribute stores parameters configuring the chosen model for the experimenting. Inside the modelParams dictionary is another dictionary, model_params, which separately stores the parameters for tuning model physics.

Paramter

Default

Description

model_flag

0

Flag to select model to use
0 : Lorenz (1963)
1 : Lorenz (1996)
2 : Lorenz (2005)

model_params

See Model Parameters

Configuration of parameters that drive each Lorenz model.

Model Parameters

Model

Paramter

Default

Lorenz (1963)

s

10

r

28

b

8/3

Lorenz (1996)

F

8

Lorenz (2005)

l05_F

15

l05_Fe

15

l05_K

32

l05_I

12

l05_b

10.0

l05_c

2.5

miscParams

The miscParams attribute stores all parameters relating to experiment output, as well as other miscellaneous features.

Paramter

Default

Description

output_dir

‘./’

The default file path for saving the experiment

numPool

8

Number of subprocesses to spawn when conducting model integration and model spinup

saveEns

0

Should the analysis ensemble state be stored each time step in x_ens. 0 is False, 1 is True.

saveEnsMean

1

Should the analysis ensemble mean state be stored each time in x_ensmean. 0 is False, 1 is True.

saveForecastEns

0

Should the forecast ensemble stae be stored each time step in x_fore_ens. 0 is False, 1 is True.

Singular Vector Parameters

Paramter

Default

Description

doSV`

0

Should singular vectors be calculated according to Whitaker and Hamill (2002)

stepSV

1

Number of time steps to skip between SV calculations

forecastSV

4

Optimization time interval

outputSV

output_dir

Output directory for SV calculation files

storeCovar

0

Flag to determine whether to store the analysis and forecast SV ensemble states. 0 is False, 1 is True