Defining a scenario#

Scenarios are defined in TOML files, as illustrated in the example below.

  1. The key components are defined in the [components] table:

    • The simulation model (model);

    • The time scale (time, either scalar time or date-time);

    • The prior distribution sampler (sampler, see pypfilt.sampler); and

    • The output recorder (summary).

  2. The simulation period and time-step settings are defined in the [time] table.

  3. The model prior distribution is defined in the [prior] table. Here, we have defined all the parameters and state variables to have fixed values, so that we can simulate observations from a known ground truth.

  4. Each observation model is defined in an [observations.UNIT] table, where UNIT is the observation unit (see The observation model for details). Here, we have defined three observations models, with observation units 'x', 'y', and 'z'.

  5. Particle filter settings are defined in the [filter] table, including:

    • The number of particles (particles); and

    • The seed for the pseudo-random number generator (prng_seed).

  6. Each scenario is defined in a [scenario.ID] table, where ID is a unique identifier for the scenario. In Defining multiple scenarios we will see how to define multiple scenarios and scenario-specific settings.

An example scenario for simulating observations from the Lorenz-63 system.#
 1# NOTE: Save this file as 'lorenz63_simulate.toml'
 2
 3[components]
 4model = "pypfilt.examples.lorenz.Lorenz63"
 5time = "pypfilt.Scalar"
 6sampler = "pypfilt.sampler.LatinHypercube"
 7summary = "pypfilt.summary.HDF5"
 8
 9[time]
10start = 0.0
11until = 25.0
12steps_per_unit = 10
13summaries_per_unit = 10
14
15[prior]
16sigma = { name = "constant", args.value = 10 }
17rho = { name = "constant", args.value = 28 }
18beta = { name = "constant", args.value = 2.66667 }
19x = { name = "constant", args.value = 1 }
20y = { name = "constant", args.value = 1 }
21z = { name = "constant", args.value = 1 }
22
23[observations.x]
24model = "pypfilt.examples.lorenz.ObsLorenz63"
25
26[observations.y]
27model = "pypfilt.examples.lorenz.ObsLorenz63"
28
29[observations.z]
30model = "pypfilt.examples.lorenz.ObsLorenz63"
31
32[filter]
33particles = 500
34prng_seed = 2001
35history_window = -1
36resample.threshold = 0.25
37
38[scenario.simulate]

Note

Call save_lorenz63_scenario_files() to save this scenario file (and the others used in this tutorial) in the working directory.

Once we have defined one or more scenarios in a TOML file, we can iterate over the scenario instances with pypfilt.load_instances():

def check_lorenz63_instances():
    """Ensure that the example Lorenz-63 file defines a single scenario."""
    scenario_file = 'lorenz63_simulate.toml'
    instances = list(pypfilt.load_instances(scenario_file))
    assert len(instances) == 1