Transition Models

class stonesoup.models.transition.base.TransitionModel

Bases: Model

Transition Model base class

property ndim: int

Number of dimensions of model

abstract property ndim_state: int

Number of state dimensions

class stonesoup.models.transition.base.CombinedGaussianTransitionModel(model_list: Sequence[GaussianModel], seed: int | None = None)

Bases: TransitionModel, GaussianModel

Combine multiple models into a single model by stacking them.

The assumption is that all models are Gaussian. Time Variant, and Time Invariant models can be combined together. If any of the models are time variant the keyword argument “time_interval” must be supplied to all methods

Parameters:

• model_list (Sequence[GaussianModel]) – List of Transition Models.

• seed (Optional[int], optional) – Seed for random number generation

model_list: Sequence[GaussianModel]

List of Transition Models.

function(state, noise=False, **kwargs) → StateVector

Applies each transition model in model_list in turn to the state’s corresponding state vector components. For example, in a 3D state space, with model_list = [modelA(ndim_state=2), modelB(ndim_state=1)], this would apply modelA to the state vector’s 1st and 2nd elements, then modelB to the remaining 3rd element.

Parameters:

state (stonesoup.state.State) – The state to be transitioned according to the models in model_list.

Returns:

state_vector – of shape (ndim_state, 1). The resultant state vector of the transition.

Return type:

stonesoup.types.array.StateVector

jacobian(state, **kwargs)

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

property ndim_state

ndim_state getter method

Returns:

The number of combined model state dimensions.

Return type:

int

covar(**kwargs)

Returns the transition model noise covariance matrix.

Returns:

The process noise covariance.

Return type:

stonesoup.types.state.CovarianceMatrix of shape (ndim_state, ndim_state)

Linear

class stonesoup.models.transition.linear.LinearGaussianTransitionModel(seed: int | None = None)

Bases: TransitionModel, LinearModel, GaussianModel

Parameters:

seed (Optional[int], optional) – Seed for random number generation

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

abstract covar(**kwargs) → CovarianceMatrix

Model covariance

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

abstract matrix(**kwargs) → ndarray

Model matrix

property ndim: int

Number of dimensions of model

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.CombinedLinearGaussianTransitionModel(model_list: Sequence[GaussianModel], seed: int | None = None)

Bases: LinearModel, CombinedGaussianTransitionModel

Combine multiple models into a single model by stacking them.

The assumption is that all models are Linear and Gaussian. Time Variant, and Time Invariant models can be combined together. If any of the models are time variant the keyword argument “time_interval” must be supplied to all methods

Parameters:

• model_list (Sequence[GaussianModel]) – List of Transition Models.

• seed (Optional[int], optional) – Seed for random number generation

matrix(**kwargs)

Model matrix \(F\)

Return type:

numpy.ndarray of shape (ndim_state, ndim_state)

covar(**kwargs)

Returns the transition model noise covariance matrix.

Returns:

The process noise covariance.

Return type:

stonesoup.types.state.CovarianceMatrix of shape (ndim_state, ndim_state)

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

model_list: Sequence[GaussianModel]

List of Transition Models.

property ndim: int

Number of dimensions of model

property ndim_state

ndim_state getter method

Returns:

The number of combined model state dimensions.

Return type:

int

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.LinearGaussianTimeInvariantTransitionModel(transition_matrix: ndarray, covariance_matrix: CovarianceMatrix, seed: int | None = None, control_matrix: ndarray = None)

Bases: LinearGaussianTransitionModel, TimeInvariantModel

Generic Linear Gaussian Time Invariant Transition Model.

Parameters:

• transition_matrix (numpy.ndarray) – Transition matrix \(\mathbf{F}\).

• covariance_matrix (CovarianceMatrix) – Transition noise covariance matrix \(\mathbf{Q}\).

• seed (Optional[int], optional) – Seed for random number generation

• control_matrix (numpy.ndarray, optional) – Control matrix \(\mathbf{B}\).

transition_matrix: ndarray

Transition matrix \(\mathbf{F}\).

control_matrix: ndarray

Control matrix \(\mathbf{B}\).

covariance_matrix: CovarianceMatrix

Transition noise covariance matrix \(\mathbf{Q}\).

matrix(**kwargs)

Model matrix \(F\)

Returns:

The model matrix evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_state, ndim_state)

covar(**kwargs)

Returns the transition model noise covariance matrix.

Returns:

The process noise covariance.

Return type:

stonesoup.types.state.CovarianceMatrix of shape (ndim_state, ndim_state)

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

property ndim: int

Number of dimensions of model

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.ConstantNthDerivative(constant_derivative: int, noise_diff_coeff: float, seed: int | None = None)

Bases: LinearGaussianTransitionModel, TimeVariantModel

Discrete model based on the Nth derivative with respect to time being constant, to set derivative use keyword argument constant_derivative

The model is described by the following SDEs:

\begin{eqnarray} dx^{(N-1)} & = & x^{(N)} dt & | {(N-1)th \ derivative \ on \ X-axis (m)} \\ dx^{(N)} & = & q\cdot dW_t,\ W_t \sim \mathcal{N}(0,q^2) & | \ Nth\ derivative\ on\ X-axis (m/s^{N}) \end{eqnarray}

It is hard to represent the matrix form of these due to the fact that they vary with N, examples for N=1 and N=2 can be found in the ConstantVelocity and ConstantAcceleration models respectively. To aid visualisation of \(F_t\) the elements are calculated as the terms of the taylor expansion of each state variable.

Parameters:

• constant_derivative (int) – The order of the derivative with respect to time to be kept constant, eg if 2 identical to constant acceleration

• noise_diff_coeff (float) – The Nth derivative noise diffusion coefficient (Variance) \(q\)

• seed (Optional[int], optional) – Seed for random number generation

constant_derivative: int

The order of the derivative with respect to time to be kept constant, eg if 2 identical to constant acceleration

noise_diff_coeff: float

The Nth derivative noise diffusion coefficient (Variance) \(q\)

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

matrix(time_interval, **kwargs)

Model matrix

covar(time_interval, **kwargs)

Model covariance

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

property ndim: int

Number of dimensions of model

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.RandomWalk(noise_diff_coeff: float, seed: int | None = None)

Bases: ConstantNthDerivative

This is a class implementation of a discrete, time-variant 1D Linear-Gaussian Random Walk Transition Model.

The target is assumed to be (almost) stationary, where target velocity is modelled as white noise.

Parameters:

• noise_diff_coeff (float) – The position noise diffusion coefficient \(q\)

• seed (Optional[int], optional) – Seed for random number generation

noise_diff_coeff: float

The position noise diffusion coefficient \(q\)

property constant_derivative

For random walk, this is 0.

covar(time_interval, **kwargs)

Model covariance

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

matrix(time_interval, **kwargs)

Model matrix

property ndim: int

Number of dimensions of model

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.ConstantVelocity(noise_diff_coeff: float, seed: int | None = None)

Bases: ConstantNthDerivative

This is a class implementation of a discrete, time-variant 1D Linear-Gaussian Constant Velocity Transition Model.

The target is assumed to move with (nearly) constant velocity, where target acceleration is modelled as white noise.

The model is described by the following SDEs:

\begin{eqnarray} dx_{pos} & = & x_{vel} d & | {Position \ on \ X-axis (m)} \\ dx_{vel} & = & q\cdot dW_t,\ W_t \sim \mathcal{N}(0,q^2) & | \ Speed on\ X-axis (m/s) \end{eqnarray}

Or equivalently:

\[x_t = F_t x_{t-1} + w_t,\ w_t \sim \mathcal{N}(0,Q_t)\]

where:

\[\begin{split}x & = & \begin{bmatrix} x_{pos} \\ x_{vel} \end{bmatrix}\end{split}\]

\[\begin{split}F_t & = & \begin{bmatrix} 1 & dt\\ 0 & 1 \end{bmatrix}\end{split}\]

\[\begin{split}Q_t & = & \begin{bmatrix} \frac{dt^3}{3} & \frac{dt^2}{2} \\ \frac{dt^2}{2} & dt \end{bmatrix} q\end{split}\]

Parameters:

• noise_diff_coeff (float) – The velocity noise diffusion coefficient \(q\)

• seed (Optional[int], optional) – Seed for random number generation

noise_diff_coeff: float

The velocity noise diffusion coefficient \(q\)

property constant_derivative

For constant velocity, this is 1.

covar(time_interval, **kwargs)

Model covariance

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

matrix(time_interval, **kwargs)

Model matrix

property ndim: int

Number of dimensions of model

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.ConstantAcceleration(noise_diff_coeff: float, seed: int | None = None)

Bases: ConstantNthDerivative

This is a class implementation of a discrete, time-variant 1D Constant Acceleration Transition Model.

The target acceleration is modeled as a zero-mean white noise random process.

The model is described by the following SDEs:

\begin{eqnarray} dx_{pos} & = & x_{vel} d & | {Position \ on \ X-axis (m)} \\ dx_{vel} & = & x_{acc} d & | {Speed \ on\ X-axis (m/s)} \\ dx_{acc} & = & q W_t,\ W_t \sim \mathcal{N}(0,q^2) & | {Acceleration \ on \ X-axis (m^2/s)} \end{eqnarray}

Or equivalently:

\[x_t = F_t x_{t-1} + w_t,\ w_t \sim \mathcal{N}(0,Q_t)\]

where:

\[\begin{split}x & = & \begin{bmatrix} x_{pos} \\ x_{vel} \\ x_{acc} \end{bmatrix}\end{split}\]

\[\begin{split}F_t & = & \begin{bmatrix} 1 & dt & \frac{dt^2}{2} \\ 0 & 1 & dt \\ 0 & 0 & 1 \end{bmatrix}\end{split}\]

\[\begin{split}Q_t & = & \begin{bmatrix} \frac{dt^5}{20} & \frac{dt^4}{8} & \frac{dt^3}{6} \\ \frac{dt^4}{8} & \frac{dt^3}{3} & \frac{dt^2}{2} \\ \frac{dt^3}{6} & \frac{dt^2}{2} & dt \end{bmatrix} q\end{split}\]

Parameters:

• noise_diff_coeff (float) – The acceleration noise diffusion coefficient \(q\)

• seed (Optional[int], optional) – Seed for random number generation

noise_diff_coeff: float

The acceleration noise diffusion coefficient \(q\)

property constant_derivative

For constant acceleration, this is 2.

covar(time_interval, **kwargs)

Model covariance

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

matrix(time_interval, **kwargs)

Model matrix

property ndim: int

Number of dimensions of model

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.NthDerivativeDecay(decay_derivative: int, noise_diff_coeff: float, damping_coeff: float, seed: int | None = None)

Bases: LinearGaussianTransitionModel, TimeVariantModel

Discrete model based on the Nth derivative with respect to time decaying to 0 exponentially, to set derivative use keyword argument decay_derivative

The model is described by the following SDEs:

\begin{eqnarray} dx^{(N-1)} & = & x^{(N)} dt & | {(N-1)th derivative \ on \ X-axis (m)} \\ dx^{(N)} & = & -K x^{N} dt + q\cdot dW_t,\ W_t \sim \mathcal{N}(0,q^2) & | \ Nth\ derivative\ on\ X-axis (m/s^{N}) \end{eqnarray}

The transition and covariance matrices are very difficult to express simply, but examples for N=1 and N=2 are given in OrnsteinUhlenbeck and Singer respectively.

Parameters:

• decay_derivative (int) – The derivative with respect to time to decay exponentially, eg if 2 identical to singer

• noise_diff_coeff (float) – The noise diffusion coefficient \(q\)

• damping_coeff (float) – The Nth derivative damping coefficient \(K\)

• seed (Optional[int], optional) – Seed for random number generation

decay_derivative: int

The derivative with respect to time to decay exponentially, eg if 2 identical to singer

noise_diff_coeff: float

The noise diffusion coefficient \(q\)

damping_coeff: float

The Nth derivative damping coefficient \(K\)

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

matrix(time_interval, **kwargs)

Model matrix

covar(time_interval, **kwargs)

Model covariance

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

property ndim: int

Number of dimensions of model

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.OrnsteinUhlenbeck(noise_diff_coeff: float, damping_coeff: float, seed: int | None = None)

Bases: NthDerivativeDecay

This is a class implementation of a discrete, time-variant 1D Linear-Gaussian Ornstein Uhlenbeck Transition Model.

The target is assumed to move with (nearly) constant velocity, which exponentially decays to zero over time, and target acceleration is modeled as white noise.

The model is described by the following SDEs:

\begin{eqnarray} dx_{pos} & = & x_{vel} dt & | {Position \ on \ X-axis (m)} \\ dx_{vel} & = & -K x_{vel} dt + q dW_t, W_t \sim \mathcal{N}(0,q) & | {Speed\ on \ X-axis (m/s)} \end{eqnarray}

Or equivalently:

\[x_t = F_t x_{t-1} + w_t,\ w_t \sim \mathcal{N}(0,Q_t)\]

where:

\[\begin{split}x & = & \begin{bmatrix} x_{pos} \\ x_{vel} \end{bmatrix}\end{split}\]

\[\begin{split}F_t & = & \begin{bmatrix} 1 & \frac{1}{K}(1 - e^{-Kdt})\\ 0 & e^{-Kdt} \end{bmatrix}\end{split}\]

\[\begin{split}Q_t & = & \begin{bmatrix} \frac{dt - \frac{2}{K}(1 - e^{-Kdt}) + \frac{1}{2K}(1 - e^{-2Kdt})}{K^2} & \frac{\frac{1}{K}(1 - e^{-Kdt}) - \frac{1}{2K}(1 - e^{-2Kdt})}{K} \\ \frac{\frac{1}{K}(1 - e^{-Kdt}) - \frac{1}{2K}(1 - e^{-2Kdt})}{K} & \frac{1 - e^{-2Kdt}}{2K} \end{bmatrix} q\end{split}\]

Parameters:

• noise_diff_coeff (float) – The velocity noise diffusion coefficient \(q\)

• damping_coeff (float) – The velocity damping coefficient \(K\)

• seed (Optional[int], optional) – Seed for random number generation

noise_diff_coeff: float

The velocity noise diffusion coefficient \(q\)

damping_coeff: float

The velocity damping coefficient \(K\)

property decay_derivative

The derivative with respect to time to decay exponentially, eg if 2 identical to singer

covar(time_interval, **kwargs)

Model covariance

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

matrix(time_interval, **kwargs)

Model matrix

property ndim: int

Number of dimensions of model

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.Singer(noise_diff_coeff: float, damping_coeff: float, seed: int | None = None)

Bases: NthDerivativeDecay

This is a class implementation of a discrete, time-variant 1D Singer Transition Model.

The target acceleration is modeled as a zero-mean Gauss-Markov random process.

The model is described by the following SDEs:

\begin{eqnarray} dx_{pos} & = & x_{vel} dt & | {Position \ on \ X-axis (m)} \\ dx_{vel} & = & x_{acc} dt & | {Speed \ on\ X-axis (m/s)} \\ dx_{acc} & = & -K x_{acc} dt + q W_t,\ W_t \sim \mathcal{N}(0,q^2) & | {Acceleration \ on \ X-axis (m^2/s)} \end{eqnarray}

Or equivalently:

\[x_t = F_t x_{t-1} + w_t,\ w_t \sim \mathcal{N}(0,Q_t)\]

where:

\[\begin{split}x & = & \begin{bmatrix} x_{pos} \\ x_{vel} \\ x_{acc} \end{bmatrix}\end{split}\]

\[\begin{split}F_t & = & \begin{bmatrix} 1 & dt & (K dt-1+e^{-K dt})/K^2 \\ 0 & 1 & (1-e^{-K dt})/K \\ 0 & 0 & e^{-K t} \end{bmatrix}\end{split}\]

\[\begin{split}Q_t & = & q \begin{bmatrix} \frac{[1-e^{-2K dt}] + 2K dt + \frac{2K^3 dt^3}{3}- 2K^2 dt^2 - 4K dt e^{-K dt} }{2K^5} & \frac{(K dt - [1-e^{-K dt}])^2}{2K^4} & \frac{[1-e^{-2K dt}]-2K dt e^{-K dt}} {2K^3} \\ \frac{(K dt - [1 - e^{-K dt}])^2}{2K^4} & \frac{2K dt - 4[1-e^{-K dt}] + [1-e^{-2K dt}]}{2K^3} & \frac{[1-e^{-K dt}]^2}{2K^2} \\ \frac{[1- e^{-2K dt}]-2K dt e^{-K dt}} {2K^3} & \frac{[1-e^{-K dt}]^2}{2K^2} & \frac{1-e^{-2K dt}}{2K} \end{bmatrix}\end{split}\]

Parameters:

• noise_diff_coeff (float) – The acceleration noise diffusion coefficient \(q\)

• damping_coeff (float) – The reciprocal of the decorrelation time \(\alpha\)

• seed (Optional[int], optional) – Seed for random number generation

noise_diff_coeff: float

The acceleration noise diffusion coefficient \(q\)

damping_coeff: float

The reciprocal of the decorrelation time \(\alpha\)

property decay_derivative

The derivative with respect to time to decay exponentially, eg if 2 identical to singer

covar(time_interval, **kwargs)

Model covariance

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

matrix(time_interval, **kwargs)

Model matrix

property ndim: int

Number of dimensions of model

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.SingerApproximate(noise_diff_coeff: float, damping_coeff: float, seed: int | None = None)

Bases: Singer

Parameters:

• noise_diff_coeff (float) – The acceleration noise diffusion coefficient \(q\)

• damping_coeff (float) – The reciprocal of the decorrelation time \(\alpha\)

• seed (Optional[int], optional) – Seed for random number generation

property decay_derivative

The derivative with respect to time to decay exponentially, eg if 2 identical to singer

covar(time_interval, **kwargs)

Returns the transition model noise covariance matrix.

Parameters:

time_interval (datetime.timedelta) – A time interval \(dt\)

Returns:

The process noise covariance.

Return type:

stonesoup.types.state.CovarianceMatrix of shape (ndim_state, ndim_state)

damping_coeff: float

The reciprocal of the decorrelation time \(\alpha\)

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

matrix(time_interval, **kwargs)

Model matrix

property ndim: int

Number of dimensions of model

property ndim_state

ndim_state getter method

Returns:

The number of model state dimensions.

Return type:

int

noise_diff_coeff: float

The acceleration noise diffusion coefficient \(q\)

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.KnownTurnRateSandwich(turn_noise_diff_coeffs: ndarray, turn_rate: float, model_list: Sequence[LinearGaussianTransitionModel], seed: int | None = None)

Bases: LinearGaussianTransitionModel, TimeVariantModel

This is a class implementation of a time-variant 2D Constant Turn Model. This model is used, as opposed to the normal KnownTurnRate model, when the turn occurs in 2 dimensions that are not adjacent in the state vector, eg if the turn occurs in the x-z plane but the state vector is of the form \((x,y,z)\). The list of transition models are to be applied to any state variables that lie in between, eg if for the above example you wanted the y component to move with constant velocity, you would put a ConstantVelocity model in the list.

The target is assumed to move with (nearly) constant velocity and also known (nearly) constant turn rate.

Parameters:

• turn_noise_diff_coeffs (numpy.ndarray) – The acceleration noise diffusion coefficients \(q\)

• turn_rate (float) – The turn rate \(\omega\)

• model_list (Sequence[LinearGaussianTransitionModel]) – List of Transition Models.

• seed (Optional[int], optional) – Seed for random number generation

turn_noise_diff_coeffs: ndarray

The acceleration noise diffusion coefficients \(q\)

turn_rate: float

The turn rate \(\omega\)

model_list: Sequence[LinearGaussianTransitionModel]

List of Transition Models.

property ndim_state

ndim_state getter method

Returns:

The number of combined model state dimensions.

Return type:

int

matrix(time_interval, **kwargs)

Model matrix \(F\)

Return type:

numpy.ndarray of shape (ndim_state, ndim_state)

covar(time_interval, **kwargs)

Returns the transition model noise covariance matrix.

Returns:

The process noise covariance.

Return type:

stonesoup.types.state.CovarianceMatrix of shape (ndim_state, ndim_state)

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

property ndim: int

Number of dimensions of model

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.linear.KnownTurnRate(turn_noise_diff_coeffs: ndarray, turn_rate: float, seed: int | None = None)

Bases: KnownTurnRateSandwich

This is a class implementation of a discrete, time-variant 2D Constant Turn Model.

The target is assumed to move with (nearly) constant velocity and also known (nearly) constant turn rate.

The model is described by the following SDEs:

\begin{eqnarray} dx_{pos} & = & x_{vel} d & | {Position \ on \ X-axis (m)} \\ dx_{vel} & = &-\omega y_{pos} d & | {Speed \ on\ X-axis (m/s)} \\ dy_{pos} & = & y_{vel} d & | {Position \ on \ Y-axis (m)} \\ dy_{vel} & = & \omega x_{pos} d & | {Speed \ on\ Y-axis (m/s)} \end{eqnarray}

Or equivalently:

\[x_t = F_t x_{t-1} + w_t,\ w_t \sim \mathcal{N}(0,Q_t)\]

where:

\[\begin{split}x & = & \begin{bmatrix} x_{pos} \\ x_{vel} \\ y_{pos} \\ y_{vel} \end{bmatrix}\end{split}\]

\[\begin{split}F_t & = & \begin{bmatrix} 1 & \frac{\sin\omega dt}{\omega} & 0 &-\frac{1-\cos\omega dt}{\omega} \\ 0 & \cos\omega dt & 0 & -\sin\omega dt \\ 0 & \frac{1-\cos\omega dt}{\omega} & 1 & \frac{\sin\omega dt}{\omega}\\ 0 & \sin\omega dt & 0 & \cos\omega dt \end{bmatrix}\end{split}\]

\[\begin{split}Q_t & = & \begin{bmatrix} q_x \frac{dt^3}{3} & q_x \frac{dt^2}{2} & 0 & 0 \\ q_x \frac{dt^2}{2} & q_x dt & 0 & 0 \\ 0 & 0 & q_y \frac{dt^3}{3} & q_y \frac{dt^2}{2}\\ 0 & 0 & q_y \frac{dt^2}{2} & q_y dt \end{bmatrix}\end{split}\]

Parameters:

• turn_noise_diff_coeffs (numpy.ndarray) – The acceleration noise diffusion coefficients \(q\)

• turn_rate (float) – The turn rate \(\omega\)

• seed (Optional[int], optional) – Seed for random number generation

property model_list

For a turn in adjacent state vectors, no transition models go in between

covar(time_interval, **kwargs)

Returns the transition model noise covariance matrix.

Returns:

The process noise covariance.

Return type:

stonesoup.types.state.CovarianceMatrix of shape (ndim_state, ndim_state)

function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model linear function \(f_k(x(k),w(k)) = F_k(x_k) + w_k\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is added)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state: State, **kwargs) → ndarray

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

matrix(time_interval, **kwargs)

Model matrix \(F\)

Return type:

numpy.ndarray of shape (ndim_state, ndim_state)

property ndim: int

Number of dimensions of model

property ndim_state

ndim_state getter method

Returns:

The number of combined model state dimensions.

Return type:

int

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

turn_noise_diff_coeffs: ndarray

The acceleration noise diffusion coefficients \(q\)

turn_rate: float

The turn rate \(\omega\)

NonLinear

class stonesoup.models.transition.nonlinear.GaussianTransitionModel(seed: int | None = None)

Bases: TransitionModel, GaussianModel

Parameters:

seed (Optional[int], optional) – Seed for random number generation

abstract covar(**kwargs) → CovarianceMatrix

Model covariance

abstract function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model function \(f_k(x(k),w(k))\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is used)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state, **kwargs)

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

property ndim: int

Number of dimensions of model

abstract property ndim_state: int

Number of state dimensions

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.nonlinear.ConstantTurn(linear_noise_coeffs: ndarray, turn_noise_coeff: float, seed: int | None = None)

Bases: GaussianTransitionModel, TimeVariantModel

This is a class implementation of a discrete, time-variant 2D Constant Turn Model.

The target is assumed to move with (nearly) constant velocity and also an unknown (nearly) constant turn rate.

The model is described by the following SDEs:

\begin{align} dx_{pos} & = x_{vel} d \quad | {Position \ on \ X-axis (m)} \\ dx_{vel} & = -\omega y_{pos} d \quad | {Speed \ on\ X-axis (m/s)} &\\ dy_{pos} & = y_{vel} d \quad | {Position \ on \ Y-axis (m)} \\ dy_{vel} & = \omega x_{pos} d \quad | {Speed \ on\ Y-axis (m/s)} \\ d\omega & = q_\omega dt \quad | {Position \ on \ X,Y-axes (rad/sec)} \end{align}

Or equivalently:

\[x_t = F_t x_{t-1} + w_t,\ w_t \sim \mathcal{N}(0,Q_t)\]

where:

\[\begin{split}x & = & \begin{bmatrix} x_{pos} \\ x_{vel} \\ y_{pos} \\ y_{vel} \\ \omega \end{bmatrix}\end{split}\]

\[\begin{split}F(x) & = & \begin{bmatrix} 1 & \frac{\sin\omega dt}{\omega} & 0 & - \frac{(1-\cos\omega dt)}{\omega} & 0 \\ 0 & \cos\omega dt & 0 & - \sin\omega dt & 0 \\ 0 & \frac{(1-\cos\omega dt)}{\omega} & 1 & \frac{\sin\omega dt}{\omega} & 0 \\ 0 & \sin\omega dt & 0 & \sin\omega dt & 0 \\ 0 & 0 & 0 & 0 & 1 \end{bmatrix}\end{split}\]

\[\begin{split}Q_t & = & \begin{bmatrix} q_x\frac{dt^3}{3} & q_x\frac{dt^2}{2} & 0 & 0 & 0 \\ q_x\frac{dt^2}{2} & q_xdt & 0 & 0 & 0 \\ 0 & 0 & q_y\frac{dt^3}{3} & q_y\frac{dt^2}{2} & 0 \\ 0 & 0 & q_y\frac{dt^2}{2} & q_ydt & 0 \\ 0 & 0 & 0 & 0 & q_\omega dt \end{bmatrix}\end{split}\]

Parameters:

• linear_noise_coeffs (numpy.ndarray) – The acceleration noise diffusion coefficients \([q_x, \: q_y]^T\)

• turn_noise_coeff (float) – The turn rate noise coefficient \(q_\omega\)

• seed (Optional[int], optional) – Seed for random number generation

linear_noise_coeffs: ndarray

The acceleration noise diffusion coefficients \([q_x, \: q_y]^T\)

turn_noise_coeff: float

The turn rate noise coefficient \(q_\omega\)

property ndim_state

ndim_state getter method

Returns:

The number of combined model state dimensions.

Return type:

int

function(state, noise=False, **kwargs) → StateVector

Model function \(f_k(x(k),w(k))\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is used)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

covar(time_interval, **kwargs)

Returns the transition model noise covariance matrix.

Returns:

The process noise covariance.

Return type:

stonesoup.types.state.CovarianceMatrix of shape (ndim_state, ndim_state)

jacobian(state, **kwargs)

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

property ndim: int

Number of dimensions of model

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

class stonesoup.models.transition.nonlinear.ConstantTurnSandwich(linear_noise_coeffs: ndarray, turn_noise_coeff: float, model_list: Sequence[GaussianTransitionModel], seed: int | None = None)

Bases: ConstantTurn

This is a class implementation of a time-variant 2D Constant Turn Model. This model is used, as opposed to the normal ConstantTurn model, when the turn occurs in 2 dimensions that are not adjacent in the state vector, eg if the turn occurs in the x-z plane but the state vector is of the form \((x,y,z)\). The list of transition models are to be applied to any state variables that lie in between, eg if for the above example you wanted the y component to move with constant velocity, you would put a ConstantVelocity model in the list.

The target is assumed to move with (nearly) constant velocity and also unknown (nearly) constant turn rate.

Parameters:

• linear_noise_coeffs (numpy.ndarray) – The acceleration noise diffusion coefficients \([q_x, \: q_y]^T\)

• turn_noise_coeff (float) – The turn rate noise coefficient \(q_\omega\)

• model_list (Sequence[GaussianTransitionModel]) – List of Transition Models.

• seed (Optional[int], optional) – Seed for random number generation

model_list: Sequence[GaussianTransitionModel]

List of Transition Models.

property ndim_state

ndim_state getter method

Returns:

The number of combined model state dimensions.

Return type:

int

function(state, noise=False, **kwargs) → StateVector

Model function \(f_k(x(k),w(k))\)

Parameters:

• state (State) – An input state

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is used)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

covar(time_interval, **kwargs)

Returns the transition model noise covariance matrix.

Returns:

The process noise covariance.

Return type:

stonesoup.types.state.CovarianceMatrix of shape (ndim_state, ndim_state)

jacobian(state, **kwargs)

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

linear_noise_coeffs: np.ndarray

The acceleration noise diffusion coefficients \([q_x, \: q_y]^T\)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

property ndim: int

Number of dimensions of model

pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

In mathematical terms, this can be written as:

\[p = p(y_t | x_t) = \mathcal{N}(y_t; x_t, Q)\]

where \(y_t\) = state_vector1, \(x_t\) = state_vector2 and \(Q\) = covar.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

rvs(num_samples: int = 1, random_state=None, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

In mathematical terms, this can be written as:

\[v_t \sim \mathcal{N}(0,Q)\]

where \(v_t =\) noise and \(Q\) = covar.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

seed: int | None

Seed for random number generation

turn_noise_coeff: float

The turn rate noise coefficient \(q_\omega\)

Categorical

class stonesoup.models.transition.categorical.MarkovianTransitionModel(transition_matrix: Matrix)

Bases: TransitionModel

The transition model for categorical states

This is a time invariant, transition model of a Markov process.

A state space vector takes the form \(\alpha_t^i = P(\phi_t^i)\), representing a categorical distribution over a discrete, finite set of possible categories \(\Phi = \{\phi^m|m\in \mathbf{N}, m\le M\}\) (for some finite \(M\)).

Models the transition from one category to another.

Intended to be used in conjunction with the CategoricalState type.

Parameters:

transition_matrix (Matrix) – Stochastic matrix \(F_t^{ij} = F^{ij} = P(\phi_t^i|\phi_{t-1}^j)\) determining the conditional probability that an object is category \(\phi^i\) at ‘time’ \(t\) given that it was category \(\phi^j\) at ‘time’ \(t-1\). Columns are normalised.

transition_matrix: Matrix

Stochastic matrix \(F_t^{ij} = F^{ij} = P(\phi_t^i|\phi_{t-1}^j)\) determining the conditional probability that an object is category \(\phi^i\) at ‘time’ \(t\) given that it was category \(\phi^j\) at ‘time’ \(t-1\). Columns are normalised.

function(state, time_interval: timedelta = None, noise: bool = False, **kwargs)

Applies the linear transformation:

\[F^{ij}\alpha_{t-1}^j = P(\phi_t^i|\phi_{t-1}^j)P(\phi_t^j)\]

The resultant vector is normalised.

Though this model is time-invariant, a check is made to see whether the time-interval given is 0. In this instance, no transformation is applied.

Parameters:

• state (CategoricalState) – The state to be transitioned.

• time_interval (datetime.timedelta) – Duration to transition state for.

• noise (bool) – Indicates whether transitioned vector is sampled from and the resultant category returned instead. This is a discrete category instead of a distribution over the state space. It is represented by an M-tuples, with all components equal to 0, except at an index corresponding to the relevant category. For example \(e^k\) indicates that the category is \(\phi^k\). If False, the resultant distribution is returned.

Returns:

state_vector – of shape (ndim_state, 1). The resultant state vector of the transition.

Return type:

stonesoup.types.array.StateVector

property ndim_state

Number of state dimensions

rvs()

Model noise/sample generation function

Generates noise samples from the model.

Parameters:

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns:

noise – A set of Np samples, generated from the model’s noise distribution.

Return type:

2-D array of shape (ndim, num_samples)

jacobian(state, **kwargs)

Model jacobian matrix \(H_{jac}\)

Parameters:

state (State) – An input state

Returns:

The model jacobian matrix evaluated around the given state vector.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

property ndim: int

Number of dimensions of model

pdf()

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability