pypfilt.state

class pypfilt.state.History(ctx, matrix=None, offset=0, times=None)

A simulation history stores the current and past states of each particle, as well as each particle’s weight and parent index.

Note

The matrix and offset arguments should only be provided when restoring a cached history matrix.

Parameters:

ctx – The simulation context.
matrix – The (optional) history matrix; a new matrix will be created if this is None (default behaviour).
offset – The (optional) offset that maps time step numbers to slices of the history matrix.
times – The (optional) list of times associated with each slice of the history matrix.

create_backcast(ctx)

Return a new simulation history that represents the backcast from the current particle states, extending as far back as the oldest recorded particle states.

Parameters:: ctx – The simulation context.

Note

All particle states in the backcast will be assigned the current particle weights.

static load_state(ctx, group)

Load the history matrix state from a cache file and return a new History object.

Parameters:

ctx – The simulation context.
group – The h5py Group object from which to load the history matrix state.

save_state(ctx, group)

Save the history matrix state to a cache file.

Parameters:

ctx – The simulation context.
group – The h5py Group object in which to save the history matrix state.

set_time_step(step_num, time): Update history.index to point to the specified time step.

reached_window_end(): Return True if the current time step lies outside the current history window, in which case the window must be shifted before the time step can be simulated.

shift_window_back(shift): Shift the history window by shift steps.

set_resampled(was_resampled): Record whether the particles were resampled at the current time step.

summary_window(ctx, start, end)

Return a list of Snapshot values for each time unit in the summary window, from start to end (inclusive).

Parameters:

ctx – The simulation context.
start – The starting time for the summary window (inclusive).
end – The ending time for the summary window (inclusive).

snapshot(ctx, expect_time=None)

Return a Snapshot of the current particle states.

Parameters:

ctx – The simulation context.
expected_time – The expected value for the current time (optional).

Raises:

ValueError – if the snapshot time differs from expect_time.

previous_snapshot(ctx, expect_time=None)

Return a Snapshot of the previous particle states.

Parameters:

ctx – The simulation context.
expected_time – The expected value for the previous time (optional).

Raises:

ValueError – if the snapshot time differs from expect_time.

class pypfilt.state.Snapshot(time, steps_per_unit, matrix, hist_ix)

Captures the particle states at a single moment in time.

The following instance variables are defined:

time – The simulation time (time, below).
hist_ix – The index of this snapshot (hist_ix, below).
weights – The array of particle weights.
vec – The history matrix slice for this time.
state_vec – The particle state vectors at this time.

Parameters:

time – The simulation time.
steps_per_unit – The number of time-steps per unit time.
matrix – The history matrix.
hist_ix – The index of this snapshot in the history matrix.

sliced(): Return True if the snapshot captures a slice of the ensemble.

back_n_steps(n)

Return the history matrix slice n time-steps before this snapshot.

Note

This returns an array, not a Snapshot.

Parameters:: n – The number of time-steps to step back.

back_n_steps_state_vec(n)

Return the particle state vectors n time-steps before this snapshot.

Note

This returns the state vectors as an array, not as a Snapshot.

Parameters:: n – The number of time-steps to step back.

back_n_units(n)

Return the history matrix slice n time units before this snapshot.

Note

This returns an array, not a Snapshot.

Parameters:: n – The number of time units to step back.

back_n_units_state_vec(n)

Return the particle state vectors n time units before this snapshot.

Note

This returns the state vectors as an array, not as a Snapshot.

Parameters:: n – The number of time units to step back.

pypfilt.state.history_matrix(ctx)

Allocate a particle history matrix of sufficient size to store an entire particle filter simulation.

Parameters:: ctx – The simulation context.
Returns:: A particle history matrix.
Return type:: numpy.ndarray

pypfilt.state.earlier_states(hist, ix, steps)

Return the particle states at a previous time-step, ordered with respect to their current arrangement.

Parameters:

hist – The particle history matrix.
ix – The current time-step index.
steps – The number of steps back in time.

pypfilt.state.is_history_matrix(ctx, arr)

Check whether the provided array includes all columns (including, e.g., the particle weights and parent indices).

Parameters:

ctx – The simulation context.
arr – The array to check.

Returns:

True if the check is successful, otherwise False.

pypfilt.state.require_history_matrix(ctx, arr)

Check whether the provided array includes all columns (including, e.g., the particle weights and parent indices).

Parameters:

ctx – The simulation context.
arr – The array to check.

Raises:

ValueError – if the check fails.

pypfilt.state.is_state_vec_matrix(ctx, arr)

Check whether the provided array includes only the particle state vector columns.

Parameters:

ctx – The simulation context.
arr – The array to check.

Returns:

True if the check is successful, otherwise False.

pypfilt.state.require_state_vec_matrix(ctx, arr)

Check whether the provided array includes only the particle state vector columns.

Parameters:

ctx – The simulation context.
arr – The array to check.

Raises:

ValueError – if the check fails.

pypfilt.state.repack(svec, astype=<class 'float'>)

Return a copy of the array svec where the fields are contiguous and viewed as a regular Numpy array of astype.

Raises:: ValueError – if svec contains any fields that are incompatible with astype.
Examples:

>>> import numpy as np
>>> from pypfilt.state import repack
>>> xs = np.array(
...     [(1.2, (2.2, 3.2)), (4.2, (5.2, 6.2))],
...     dtype=[('x', float), ('y', float, 2)],
... )
>>> ys = repack(xs)
>>> assert np.array_equal(
...     ys, np.array([[1.2, 2.2, 3.2], [4.2, 5.2, 6.2]])
... )