Transition Models
- class stonesoup.models.transition.base.TransitionModel[source]
Bases:
Model
Transition Model base class
- class stonesoup.models.transition.base.CombinedGaussianTransitionModel(model_list: Sequence[GaussianModel], seed: Optional[int] = None)[source]
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 [source]
Applies each transition model in
model_list
in turn to the state’s corresponding state vector components. For example, in a 3D state space, withmodel_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 inmodel_list
.- Returns
state_vector – of shape (
ndim_state, 1
). The resultant state vector of the transition.- Return type
- jacobian(state, **kwargs)[source]
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
- covar(**kwargs)[source]
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: Optional[int] = None)[source]
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
- abstract covar(**kwargs) CovarianceMatrix
Model covariance
- function(state: State, noise: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.CombinedLinearGaussianTransitionModel(model_list: Sequence[GaussianModel], seed: Optional[int] = None)[source]
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)[source]
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: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- model_list: Sequence[GaussianModel]
List of Transition Models.
- property ndim_state
ndim_state getter method
- Returns
The number of combined model state dimensions.
- Return type
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.LinearGaussianTimeInvariantTransitionModel(transition_matrix: ndarray, covariance_matrix: CovarianceMatrix, seed: Optional[int] = None, control_matrix: ndarray = None)[source]
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 generationcontrol_matrix (
numpy.ndarray
, optional) – Control matrix \(\mathbf{B}\).
- covariance_matrix: CovarianceMatrix
Transition noise covariance matrix \(\mathbf{Q}\).
- matrix(**kwargs)[source]
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)[source]
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: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- property ndim_state
ndim_state getter method
- Returns
The number of model state dimensions.
- Return type
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.ConstantNthDerivative(constant_derivative: int, noise_diff_coeff: float, seed: Optional[int] = None)[source]
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
andConstantAcceleration
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 accelerationnoise_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
- property ndim_state
ndim_state getter method
- Returns
The number of model state dimensions.
- Return type
- function(state: State, noise: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.RandomWalk(noise_diff_coeff: float, seed: Optional[int] = None)[source]
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
- property constant_derivative
For random walk, this is 0.
- covar(time_interval, **kwargs)
Model covariance
- function(state: State, noise: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- matrix(time_interval, **kwargs)
Model matrix
- property ndim_state
ndim_state getter method
- Returns
The number of model state dimensions.
- Return type
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.ConstantVelocity(noise_diff_coeff: float, seed: Optional[int] = None)[source]
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
- property constant_derivative
For constant velocity, this is 1.
- covar(time_interval, **kwargs)
Model covariance
- function(state: State, noise: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- matrix(time_interval, **kwargs)
Model matrix
- property ndim_state
ndim_state getter method
- Returns
The number of model state dimensions.
- Return type
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.ConstantAcceleration(noise_diff_coeff: float, seed: Optional[int] = None)[source]
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
- property constant_derivative
For constant acceleration, this is 2.
- covar(time_interval, **kwargs)
Model covariance
- function(state: State, noise: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- matrix(time_interval, **kwargs)
Model matrix
- property ndim_state
ndim_state getter method
- Returns
The number of model state dimensions.
- Return type
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.NthDerivativeDecay(decay_derivative: int, noise_diff_coeff: float, damping_coeff: float, seed: Optional[int] = None)[source]
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
andSinger
respectively.- Parameters
decay_derivative (
int
) – The derivative with respect to time to decay exponentially, eg if 2 identical to singernoise_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
- property ndim_state
ndim_state getter method
- Returns
The number of model state dimensions.
- Return type
- function(state: State, noise: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.OrnsteinUhlenbeck(noise_diff_coeff: float, damping_coeff: float, seed: Optional[int] = None)[source]
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
- 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: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- matrix(time_interval, **kwargs)
Model matrix
- property ndim_state
ndim_state getter method
- Returns
The number of model state dimensions.
- Return type
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.Singer(noise_diff_coeff: float, damping_coeff: float, seed: Optional[int] = None)[source]
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
- 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: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- matrix(time_interval, **kwargs)
Model matrix
- property ndim_state
ndim_state getter method
- Returns
The number of model state dimensions.
- Return type
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.SingerApproximate(noise_diff_coeff: float, damping_coeff: float, seed: Optional[int] = None)[source]
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)[source]
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
)
- function(state: State, noise: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- matrix(time_interval, **kwargs)
Model matrix
- property ndim_state
ndim_state getter method
- Returns
The number of model state dimensions.
- Return type
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.KnownTurnRateSandwich(turn_noise_diff_coeffs: ndarray, turn_rate: float, model_list: Sequence[LinearGaussianTransitionModel], seed: Optional[int] = None)[source]
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 aConstantVelocity
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
- 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
- matrix(time_interval, **kwargs)[source]
Model matrix \(F\)
- Return type
numpy.ndarray
of shape (ndim_state
,ndim_state
)
- covar(time_interval, **kwargs)[source]
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: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.linear.KnownTurnRate(turn_noise_diff_coeffs: ndarray, turn_rate: float, seed: Optional[int] = None)[source]
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^2 \frac{dt^3}{3} & q_x^2 \frac{dt^2}{2} & 0 & 0 \\ q_x^2 \frac{dt^2}{2} & q_x^2 dt & 0 & 0 \\ 0 & 0 & q_y^2 \frac{dt^3}{3} & q_y^2 \frac{dt^2}{2}\\ 0 & 0 & q_y^2 \frac{dt^2}{2} & q_y^2 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: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is added)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- matrix(time_interval, **kwargs)
Model matrix \(F\)
- Return type
numpy.ndarray
of shape (ndim_state
,ndim_state
)
- property ndim_state
ndim_state getter method
- Returns
The number of combined model state dimensions.
- Return type
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
NonLinear
- class stonesoup.models.transition.nonlinear.GaussianTransitionModel(seed: Optional[int] = None)[source]
Bases:
TransitionModel
,GaussianModel
- Parameters
seed (
Optional[int]
, optional) – Seed for random number generation
- abstract covar(**kwargs) CovarianceMatrix
Model covariance
- abstract function(state: State, noise: Union[bool, ndarray] = False, **kwargs) Union[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 ofrvs()
is used)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- 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
)
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.nonlinear.ConstantTurn(linear_noise_coeffs: ndarray, turn_noise_coeff: float, seed: Optional[int] = None)[source]
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} x+ \frac{x_{vel}}{\omega}\sin\omega dt - \frac{y_{vel}}{\omega}(1-\cos\omega dt) \\ x_{vel}\cos\omega dt - y_{vel}\sin\omega dt \\ y+ \frac{v_{vel}}{\omega}\sin\omega dt + \frac{x_{vel}}{\omega}(1-\cos\omega dt) \\ x_{vel}\sin\omega dt + y_{vel}\sin\omega dt \\ \omega \end{bmatrix}\end{split}\]\[\begin{split}Q_t & = & \begin{bmatrix} \frac{dt^4q_x^2}{4} & \frac{dt^3q_x^2}{2} & \frac{dt^4q_xq_y}{4} & \frac{dt^3q_xq_y}{2} & \frac{dt^2q_xq_\omega}{2} \\ \frac{dt^3q_x^2}{2} & dt^2q_x^2 & \frac{dt^3q_xq_y}{2} & dt^2q_xq_y & dt q_x q_\omega \\ \frac{dt^4q_xq_y}{4} & \frac{dt^3q_xq_y}{2} & \frac{dt^4q_y^2}{4} & \frac{dt^3q_y^2}{2} & \frac{dt^2q_y q_\omega}{2} \\ \frac{dt^3q_x q_y}{2} & dt^2q_xq_y & \frac{dt^3q_y^2}{2} & dt^2q_y^2 & dt q_y q_\omega \\ \frac{dt^2q_xq_\omega}{2} & dtq_xq_\omega & \frac{dt^2q_yq_\omega}{2} & dt q_y q_\omega & q_\omega^2 \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
- property ndim_state
ndim_state getter method
- Returns
The number of combined model state dimensions.
- Return type
- function(state, noise=False, **kwargs) StateVector [source]
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 ofrvs()
is used)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- covar(time_interval, **kwargs)[source]
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
)
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
- class stonesoup.models.transition.nonlinear.ConstantTurnSandwich(linear_noise_coeffs: ndarray, turn_noise_coeff: float, model_list: Sequence[GaussianTransitionModel], seed: Optional[int] = None)[source]
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 aConstantVelocity
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
- function(state, noise=False, **kwargs) StateVector [source]
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 ofrvs()
is used)
- Returns
The StateVector(s) with the model function evaluated.
- Return type
StateVector
orStateVectors
- covar(time_interval, **kwargs)[source]
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\)
- pdf(state1: State, state2: State, **kwargs) Union[Probability, ndarray]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.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
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability
- rvs(num_samples: int = 1, random_state=None, **kwargs) Union[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
)
Categorical
- class stonesoup.models.transition.categorical.MarkovianTransitionModel(transition_matrix: Matrix)[source]
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: Optional[timedelta] = None, noise: bool = False, **kwargs)[source]
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
- property ndim_state
Number of state dimensions
- rvs()[source]
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
)
- pdf()[source]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
.- Parameters
- Returns
The likelihood of
state1
, givenstate2
- Return type
Probability
orndarray
ofProbability