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 typefield_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 incurr
.- 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, wherename
is a string that identifies the statistic andstat_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.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 incurr
.- 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.