pypfilt.model

All simulation models should derive from the following base class:

class pypfilt.model.Model

The base class for simulation models, which defines the minimal set of methods that are required.

init(ctx, vec)

Initialise a matrix of state vectors.

Parameters:

ctx – The simulation context.
vec – An uninitialised \(P \times S\) matrix of state vectors, for \(P\) particles and state vectors of length \(S\) (as defined by field_types()).

Note

The default implementation initialises each state vector field to the prior samples of the same name, and produces warnings if there were unused prior samples.

Models should only implement this method if the state vectors should not be initialised in this manner, or if there are other initialisation actions that must be performed.

abstract field_types(ctx)

Return a list of (field_name, field_dtype, field_shape) tuples that define the state vector.

The third element, field_shape, is optional and contains the shape of this field if it forms an array of type field_dtype.

These tuples must be in the same order as the state vector itself.

Parameters:: ctx – The simulation context.

field_names(ctx)

Return a list of the fields that define the state vector.

These tuples must be in the same order as the state vector itself.

Parameters:: ctx – The simulation context.

can_smooth(): Return the set of field names in the state vector that can be smoothed by the post-regularised particle filter (see post_regularise()).

Note

Models should only implement this method if the state vector contains parameters that can be smoothed.

abstract update(ctx, time_step, is_fs, prev, curr)

Perform a single time-step, jumping forward to time and recording the updated particle states in curr.

Parameters:

ctx (Context) – The simulation context.
time_step (TimeStep) – The time-step details.
is_fs – Indicates whether this is a forecasting simulation.
prev – The state before the time-step.
curr – The state after the time-step (destructively updated).

resume_from_cache(ctx)

Notify the model that a simulation will begin from a saved state.

The model does not need to initialise the state vectors, since these will have been loaded from a cache file, but it may need to update any internal variables (i.e., those not stored in the state vectors).

Note

Models should only implement this method if they need to prepare for the simulation.

stat_info(): Describe each statistic that can be calculated by this model as a (name, stat_fn) tuple, where name is a string that identifies the statistic and stat_fn is a function that calculates the value of the statistic.

Note

Models should only implement this method if they define one or more statistics.

is_valid(hist): Identify particles whose state and parameters can be inspected. By default, this function returns True for all particles. Override this function to ensure that inchoate particles are correctly ignored.

Note

Models should only implement this method if there are conditions where some particles should be ignored.

Ordinary differential equations

Models that can be expressed as a system of ordinary differential equations should instead derive from the OdeModel class, which provides a convenient wrapper around scipy.integrate.solve_ivp().

class pypfilt.model.OdeModel

A base class for systems of ordinary differential equations.

The default integration method is the explicit Runge-Kutta method of order 5(4) (“RK45”). Sub-classes can override this by setting self.method to any supported integration method, and scenarios can override this by defining the "model.ode_method" setting. Sub-classes can also pass custom arguments to the solver by defining named parameters in the "model.ode_solver_options" setting.

Note

Sub-classes must implement d_dt() (see below), and must not implement update().

Warning

This only supports models whose state vectors contain floating-point fields (which may be scalar or multi-dimensional).

abstract d_dt(time, xt, ctx, is_forecast)

The right-hand side of the ODE system.

Parameters:

time – The current (scalar) time.
xt – The particle state vectors.
ctx – The simulation context.
is_forecast – True if this is a forecasting simulation.

Returns:

The rate of change for each field in the particle state vectors.

update(ctx, time_step, is_forecast, prev, curr)

Perform a single time-step, jumping forward to time and recording the updated particle states in curr.

Parameters:

ctx (Context) – The simulation context.
time_step (TimeStep) – The time-step details.
is_fs – Indicates whether this is a forecasting simulation.
prev – The state before the time-step.
curr – The state after the time-step (destructively updated).

Performing “mini-steps”

For simulation models that require very small time-steps, it may be desirable to avoid recording the particle states at each time-step. This can be achieved by using a large time-step (e.g., setting steps_per_unit = 1) and dividing each time-step into a number of “mini-steps” that will not be recorded. See Record only a subset of simulation model time-steps for several examples of using the ministeps() decorator.

pypfilt.model.ministeps(mini_steps=None)

Wrap a model’s update() method to perform multiple “mini-steps” for each time-step.

Parameters:: mini_steps – The (optional) number of “mini-steps” to perform for each time-step. This can be overridden by providing a value for the "time.mini_steps_per_step" setting.