Measurement Models

class stonesoup.models.measurement.base.MeasurementModel(ndim_state: int, mapping: Sequence[int])

Bases: Model, ABC

Measurement Model base class

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

ndim_state: int

Number of state dimensions

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

abstract property ndim_meas: int

Number of measurement dimensions

Linear

class stonesoup.models.measurement.linear.LinearGaussian(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None)

Bases: MeasurementModel, LinearModel, GaussianModel

This is a class implementation of a time-invariant 1D Linear-Gaussian Measurement Model.

The model is described by the following equations:

\[y_t = H_k*x_t + v_k,\ \ \ \ v(k)\sim \mathcal{N}(0,R)\]

where H_k is a (ndim_meas, ndim_state) matrix and v_k is Gaussian distributed.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

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

noise_covar: CovarianceMatrix

Noise covariance

property ndim_meas

ndim_meas getter method

Returns:

The number of measurement dimensions

Return type:

int

matrix(**kwargs)

Model matrix \(H(t)\)

Returns:

The model matrix evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_meas, ndim_state)

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

Model function \(h(t,x(t),w(t))\)

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 model function evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_meas, 1)

covar(**kwargs)

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

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

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

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

NonLinear

class stonesoup.models.measurement.nonlinear.CombinedReversibleGaussianMeasurementModel(model_list: Sequence[GaussianModel], seed: int | None = None)

Bases: ReversibleModel, GaussianModel, MeasurementModel

Combine multiple models into a single model by stacking them.

The assumption is that all models are Gaussian, and must be combination of LinearModel and NonLinearModel models. They must all expect the same dimension state vector (i.e. have the same ndim_state), using model mapping as appropriate.

This also implements the inverse_function(), but will raise a NotImplementedError if any model isn’t either a LinearModel or ReversibleModel.

Parameters:

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

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

model_list: Sequence[GaussianModel]

List of Measurement Models.

property ndim_state: int

Number of state dimensions

property ndim_meas: int

Number of measurement dimensions

property mapping

Mapping between measurement and state dims

function(state, **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

inverse_function(detection, **kwargs) → StateVector

Takes in the result of the function and computes the inverse function, returning the initial input of the function.

Parameters:

detection (Detection) – Input state (non-linear format)

Returns:

The linear co-ordinates

Return type:

StateVector

covar(**kwargs) → CovarianceMatrix

Model covariance

rvs(num_samples=1, **kwargs) → StateVector | StateVectors

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().

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

seed: int | None

Seed for random number generation

class stonesoup.models.measurement.nonlinear.NonLinearGaussianMeasurement(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None)

Bases: MeasurementModel, GaussianModel, ABC

This class combines the MeasurementModel, NonLinearModel and GaussianModel classes. It is not meant to be instantiated directly but subclasses should be derived from this class.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

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

• rotation_offset (StateVector, optional) – A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

rotation_offset: StateVector

A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

noise_covar: CovarianceMatrix

Noise covariance

covar(**kwargs) → CovarianceMatrix

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

property rotation_matrix: ndarray

3D axis rotation matrix

Note

This will be cached until rotation_offset is replaced.

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

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

abstract property ndim_meas: int

Number of measurement dimensions

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.measurement.nonlinear.CartesianToElevationBearingRange(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None)

Bases: NonLinearGaussianMeasurement, ReversibleModel

This is a class implementation of a time-invariant measurement model, where measurements are assumed to be received in the form of bearing (\(\phi\)), elevation (\(\theta\)) and range (\(r\)), with Gaussian noise in each dimension.

The model is described by the following equations:

\[\vec{y}_t = h(\vec{x}_t, \vec{v}_t)\]

where:

• \(\vec{y}_t\) is a measurement vector of the form:

\[\begin{split}\vec{y}_t = \begin{bmatrix} \theta \\ \phi \\ r \end{bmatrix}\end{split}\]

• \(h\) is a non-linear model function of the form:

\[\begin{split}h(\vec{x}_t,\vec{v}_t) = \begin{bmatrix} asin(\mathcal{z}/\sqrt{\mathcal{x}^2 + \mathcal{y}^2 +\mathcal{z}^2}) \\ atan2(\mathcal{y},\mathcal{x}) \\ \sqrt{\mathcal{x}^2 + \mathcal{y}^2 + \mathcal{z}^2} \end{bmatrix} + \vec{v}_t\end{split}\]

• \(\vec{v}_t\) is Gaussian distributed with covariance \(R\), i.e.:

\[\vec{v}_t \sim \mathcal{N}(0,R)\]

\[\begin{split}R = \begin{bmatrix} \sigma_{\theta}^2 & 0 & 0 \\ 0 & \sigma_{\phi}^2 & 0 \\ 0 & 0 & \sigma_{r}^2 \end{bmatrix}\end{split}\]

The mapping property of the model is a 3 element vector, whose first (i.e. mapping[0]), second (i.e. mapping[1]) and third (i.e. mapping[2]) elements contain the state index of the \(x\), \(y\) and \(z\) coordinates, respectively.

Note

The current implementation of this class assumes a 3D Cartesian plane.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

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

• rotation_offset (StateVector, optional) – A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

• translation_offset (StateVector, optional) – A 3x1 array specifying the Cartesian origin offset in terms of \(x,y,z\) coordinates.

translation_offset: StateVector

A 3x1 array specifying the Cartesian origin offset in terms of \(x,y,z\) coordinates.

property ndim_meas: int

ndim_meas getter method

Returns:

The number of measurement dimensions

Return type:

int

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

Model function \(h(\vec{x}_t,\vec{v}_t)\)

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 model function evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_state, 1)

inverse_function(detection, **kwargs) → StateVector

Takes in the result of the function and computes the inverse function, returning the initial input of the function.

Parameters:

detection (Detection) – Input state (non-linear format)

Returns:

The linear co-ordinates

Return type:

StateVector

rvs(num_samples=1, **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)

covar(**kwargs) → CovarianceMatrix

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

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

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

ndim_state: int

Number of state dimensions

noise_covar: CovarianceMatrix

Noise covariance

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

property rotation_matrix: ndarray

3D axis rotation matrix

Note

This will be cached until rotation_offset is replaced.

rotation_offset: StateVector

A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

seed: int | None

Seed for random number generation

class stonesoup.models.measurement.nonlinear.CartesianToBearingRange(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None)

Bases: NonLinearGaussianMeasurement, ReversibleModel

This is a class implementation of a time-invariant measurement model, where measurements are assumed to be received in the form of bearing (\(\phi\)) and range (\(r\)), with Gaussian noise in each dimension.

The model is described by the following equations:

\[\vec{y}_t = h(\vec{x}_t, \vec{v}_t)\]

where:

• \(\vec{y}_t\) is a measurement vector of the form:

\[\begin{split}\vec{y}_t = \begin{bmatrix} \phi \\ r \end{bmatrix}\end{split}\]

• \(h\) is a non-linear model function of the form:

\[\begin{split}h(\vec{x}_t,\vec{v}_t) = \begin{bmatrix} atan2(\mathcal{y},\mathcal{x}) \\ \sqrt{\mathcal{x}^2 + \mathcal{y}^2} \end{bmatrix} + \vec{v}_t\end{split}\]

• \(\vec{v}_t\) is Gaussian distributed with covariance \(R\), i.e.:

\[\vec{v}_t \sim \mathcal{N}(0,R)\]

\[\begin{split}R = \begin{bmatrix} \sigma_{\phi}^2 & 0 \\ 0 & \sigma_{r}^2 \end{bmatrix}\end{split}\]

The mapping property of the model is a 2 element vector, whose first (i.e. mapping[0]) and second (i.e. mapping[1]) elements contain the state index of the \(x\) and \(y\) coordinates, respectively.

Note

The current implementation of this class assumes a 2D Cartesian plane.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

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

• rotation_offset (StateVector, optional) – A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

• translation_offset (StateVector, optional) – A 2x1 array specifying the origin offset in terms of \(x,y\) coordinates.

translation_offset: StateVector

A 2x1 array specifying the origin offset in terms of \(x,y\) coordinates.

property ndim_meas: int

ndim_meas getter method

Returns:

The number of measurement dimensions

Return type:

int

inverse_function(detection, **kwargs) → StateVector

Takes in the result of the function and computes the inverse function, returning the initial input of the function.

Parameters:

detection (Detection) – Input state (non-linear format)

Returns:

The linear co-ordinates

Return type:

StateVector

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

Model function \(h(\vec{x}_t,\vec{v}_t)\)

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 model function evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_meas, 1)

rvs(num_samples=1, **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)

covar(**kwargs) → CovarianceMatrix

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

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

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

ndim_state: int

Number of state dimensions

noise_covar: CovarianceMatrix

Noise covariance

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

property rotation_matrix: ndarray

3D axis rotation matrix

Note

This will be cached until rotation_offset is replaced.

rotation_offset: StateVector

A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

seed: int | None

Seed for random number generation

class stonesoup.models.measurement.nonlinear.CartesianToElevationBearing(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None)

Bases: NonLinearGaussianMeasurement

This is a class implementation of a time-invariant measurement model, where measurements are assumed to be received in the form of bearing (\(\phi\)) and elevation (\(\theta\)) and with Gaussian noise in each dimension.

The model is described by the following equations:

\[\vec{y}_t = h(\vec{x}_t, \vec{v}_t)\]

where:

• \(\vec{y}_t\) is a measurement vector of the form:

\[\begin{split}\vec{y}_t = \begin{bmatrix} \theta \\ \phi \end{bmatrix}\end{split}\]

• \(h\) is a non-linear model function of the form:

\[\begin{split}h(\vec{x}_t,\vec{v}_t) = \begin{bmatrix} asin(\mathcal{z}/\sqrt{\mathcal{x}^2 + \mathcal{y}^2 +\mathcal{z}^2}) \\ atan2(\mathcal{y},\mathcal{x}) \\ \end{bmatrix} + \vec{v}_t\end{split}\]

• \(\vec{v}_t\) is Gaussian distributed with covariance \(R\), i.e.:

\[\vec{v}_t \sim \mathcal{N}(0,R)\]

\[\begin{split}R = \begin{bmatrix} \sigma_{\theta}^2 & 0 \\ 0 & \sigma_{\phi}^2\\ \end{bmatrix}\end{split}\]

The mapping property of the model is a 3 element vector, whose first (i.e. mapping[0]), second (i.e. mapping[1]) and third (i.e. mapping[2]) elements contain the state index of the \(x\), \(y\) and \(z\) coordinates, respectively.

Note

The current implementation of this class assumes a 3D Cartesian plane.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

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

• rotation_offset (StateVector, optional) – A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

• translation_offset (StateVector, optional) – A 3x1 array specifying the origin offset in terms of \(x,y,z\) coordinates.

translation_offset: StateVector

A 3x1 array specifying the origin offset in terms of \(x,y,z\) coordinates.

property ndim_meas: int

ndim_meas getter method

Returns:

The number of measurement dimensions

Return type:

int

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

Model function \(h(\vec{x}_t,\vec{v}_t)\)

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 model function evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_state, 1)

rvs(num_samples=1, **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)

covar(**kwargs) → CovarianceMatrix

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

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

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

ndim_state: int

Number of state dimensions

noise_covar: CovarianceMatrix

Noise covariance

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

property rotation_matrix: ndarray

3D axis rotation matrix

Note

This will be cached until rotation_offset is replaced.

rotation_offset: StateVector

A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

seed: int | None

Seed for random number generation

class stonesoup.models.measurement.nonlinear.Cartesian2DToBearing(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None)

Bases: NonLinearGaussianMeasurement

This is a class implementation of a time-invariant measurement model, where measurements are assumed to be received in the form of bearing (\(\phi\)) with Gaussian noise.

The model is described by the following equations:

\[\phi_t = h(\vec{x}_t, v_t)\]

• \(h\) is a non-linear model function of the form:

\[h(\vec{x}_t,v_t) = atan2(\mathcal{y},\mathcal{x}) + v_t\]

• \(v_t\) is Gaussian distributed with covariance \(R\), i.e.:

\[v_t \sim \mathcal{N}(0,\sigma_{\phi}^2)\]

The mapping property of the model is a 2 element vector, whose first (i.e. mapping[0]) and second (i.e. mapping[1]) elements contain the state index of the \(x\) and \(y\) coordinates, respectively.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

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

• rotation_offset (StateVector, optional) – A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

• translation_offset (StateVector, optional) – A 2x1 array specifying the origin offset in terms of \(x,y\) coordinates.

translation_offset: StateVector

A 2x1 array specifying the origin offset in terms of \(x,y\) coordinates.

property ndim_meas

ndim_meas getter method

Returns:

The number of measurement dimensions

Return type:

int

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

Model function \(h(\vec{x}_t,v_t)\)

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 model function evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_state, 1)

rvs(num_samples=1, **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)

covar(**kwargs) → CovarianceMatrix

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

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

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

ndim_state: int

Number of state dimensions

noise_covar: CovarianceMatrix

Noise covariance

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

property rotation_matrix: ndarray

3D axis rotation matrix

Note

This will be cached until rotation_offset is replaced.

rotation_offset: StateVector

A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

seed: int | None

Seed for random number generation

class stonesoup.models.measurement.nonlinear.CartesianToBearingRangeRate(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None, velocity_mapping: Tuple[int, int, int] = (1, 3, 5), velocity: StateVector = None)

Bases: NonLinearGaussianMeasurement

This is a class implementation of a time-invariant measurement model, where measurements are assumed to be received in the form of bearing (\(\phi\)), range (\(r\)) and range-rate (\(\dot{r}\)), with Gaussian noise in each dimension.

The model is described by the following equations:

\[\vec{y}_t = h(\vec{x}_t, \vec{v}_t)\]

where:

• \(\vec{y}_t\) is a measurement vector of the form:

\[\begin{split}\vec{y}_t = \begin{bmatrix} \phi \\ r \\ \dot{r} \end{bmatrix}\end{split}\]

• \(h\) is a non-linear model function of the form:

\[\begin{split}h(\vec{x}_t,\vec{v}_t) = \begin{bmatrix} atan2(\mathcal{y},\mathcal{x}) \\ \sqrt{\mathcal{x}^2 + \mathcal{y}^2} \\ (x\dot{x} + y\dot{y})/\sqrt{x^2 + y^2} \end{bmatrix} + \vec{v}_t\end{split}\]

• \(\vec{v}_t\) is Gaussian distributed with covariance \(R\), i.e.:

\[\vec{v}_t \sim \mathcal{N}(0,R)\]

\[\begin{split}R = \begin{bmatrix} \sigma_{\phi}^2 & 0 & 0\\ 0 & \sigma_{r}^2 & 0 \\ 0 & 0 & \sigma_{\dot{r}}^2 \end{bmatrix}\end{split}\]

The mapping property of the model is a 3 element vector, whose first (i.e. mapping[0]), second (i.e. mapping[1]) and third (i.e. mapping[2]) elements contain the state index of the \(x\), \(y\) and \(z\) coordinates, respectively.

Note

This class implementation assuming at 3D cartesian space, it therefore expects a 6D state space.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

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

• rotation_offset (StateVector, optional) – A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

• translation_offset (StateVector, optional) – A 3x1 array specifying the origin offset in terms of \(x,y\) coordinates.

• velocity_mapping (Tuple[int, int, int], optional) – Mapping to the targets velocity within its state space

• velocity (StateVector, optional) – A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.

velocity_mapping: Tuple[int, int, int]

Mapping to the targets velocity within its state space

translation_offset: StateVector

A 3x1 array specifying the origin offset in terms of \(x,y\) coordinates.

velocity: StateVector

A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.

property ndim_meas: int

ndim_meas getter method

Returns:

The number of measurement dimensions

Return type:

int

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

Model function \(h(\vec{x}_t,\vec{v}_t)\)

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 model function evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_state, 1)

rvs(num_samples=1, **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)

covar(**kwargs) → CovarianceMatrix

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

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

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

ndim_state: int

Number of state dimensions

noise_covar: CovarianceMatrix

Noise covariance

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

property rotation_matrix: ndarray

3D axis rotation matrix

Note

This will be cached until rotation_offset is replaced.

rotation_offset: StateVector

A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

seed: int | None

Seed for random number generation

class stonesoup.models.measurement.nonlinear.CartesianToElevationBearingRangeRate(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None, velocity_mapping: Tuple[int, int, int] = (1, 3, 5), velocity: StateVector = None)

Bases: NonLinearGaussianMeasurement, ReversibleModel

This is a class implementation of a time-invariant measurement model, where measurements are assumed to be received in the form of elevation (\(\theta\)), bearing (\(\phi\)), range (\(r\)) and range-rate (\(\dot{r}\)), with Gaussian noise in each dimension.

The model is described by the following equations:

\[\vec{y}_t = h(\vec{x}_t, \vec{v}_t)\]

where:

• \(\vec{y}_t\) is a measurement vector of the form:

\[\begin{split}\vec{y}_t = \begin{bmatrix} \theta \\ \phi \\ r \\ \dot{r} \end{bmatrix}\end{split}\]

• \(h\) is a non-linear model function of the form:

\[\begin{split}h(\vec{x}_t,\vec{v}_t) = \begin{bmatrix} asin(\mathcal{z}/\sqrt{\mathcal{x}^2 + \mathcal{y}^2 +\mathcal{z}^2}) \\ atan2(\mathcal{y},\mathcal{x}) \\ \sqrt{\mathcal{x}^2 + \mathcal{y}^2 + \mathcal{z}^2} \\ (x\dot{x} + y\dot{y} + z\dot{z})/\sqrt{x^2 + y^2 + z^2} \end{bmatrix} + \vec{v}_t\end{split}\]

• \(\vec{v}_t\) is Gaussian distributed with covariance \(R\), i.e.:

\[\vec{v}_t \sim \mathcal{N}(0,R)\]

\[\begin{split}R = \begin{bmatrix} \sigma_{\theta}^2 & 0 & 0 & 0\\ 0 & \sigma_{\phi}^2 & 0 & 0\\ 0 & 0 & \sigma_{r}^2 & 0\\ 0 & 0 & 0 & \sigma_{\dot{r}}^2 \end{bmatrix}\end{split}\]

The mapping property of the model is a 3 element vector, whose first (i.e. mapping[0]), second (i.e. mapping[1]) and third (i.e. mapping[2]) elements contain the state index of the \(x\), \(y\) and \(z\) coordinates, respectively.

Note

This class implementation assuming at 3D cartesian space, it therefore expects a 6D state space.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

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

• rotation_offset (StateVector, optional) – A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

• translation_offset (StateVector, optional) – A 3x1 array specifying the origin offset in terms of \(x,y,z\) coordinates.

• velocity_mapping (Tuple[int, int, int], optional) – Mapping to the targets velocity within its state space

• velocity (StateVector, optional) – A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.

velocity_mapping: Tuple[int, int, int]

Mapping to the targets velocity within its state space

translation_offset: StateVector

A 3x1 array specifying the origin offset in terms of \(x,y,z\) coordinates.

velocity: StateVector

A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.

property ndim_meas: int

ndim_meas getter method

Returns:

The number of measurement dimensions

Return type:

int

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

Model function \(h(\vec{x}_t,\vec{v}_t)\)

Parameters:

• state (StateVector) – An input state vector for the target

• 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 model function evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_state, 1)

inverse_function(detection, **kwargs) → StateVector

Takes in the result of the function and computes the inverse function, returning the initial input of the function.

Parameters:

detection (Detection) – Input state (non-linear format)

Returns:

The linear co-ordinates

Return type:

StateVector

rvs(num_samples=1, **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)

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)

covar(**kwargs) → CovarianceMatrix

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

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

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

ndim_state: int

Number of state dimensions

noise_covar: CovarianceMatrix

Noise covariance

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

property rotation_matrix: ndarray

3D axis rotation matrix

Note

This will be cached until rotation_offset is replaced.

rotation_offset: StateVector

A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

seed: int | None

Seed for random number generation

class stonesoup.models.measurement.nonlinear.RangeRangeRateBinning(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, range_res: float, range_rate_res: float, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None, velocity_mapping: Tuple[int, int, int] = (1, 3, 5), velocity: StateVector = None)

Bases: CartesianToElevationBearingRangeRate

This is a class implementation of a time-invariant measurement model, where measurements are assumed to be in the form of elevation (\(\theta\)), bearing (\(\phi\)), range (\(r\)) and range-rate (\(\dot{r}\)), with Gaussian noise in each dimension and the range and range-rate are binned based on the range resolution and range-rate resolution respectively.

The model is described by the following equations:

\[\vec{y}_t = h(\vec{x}_t, \vec{v}_t)\]

where:

• \(\vec{y}_t\) is a measurement vector of the form:

\[\begin{split}\vec{y}_t = \begin{bmatrix} \theta \\ \phi \\ r \\ \dot{r} \end{bmatrix}\end{split}\]

• \(h\) is a non-linear model function of the form:

\[\begin{split}h(\vec{x}_t,\vec{v}_t) = \begin{bmatrix} \textrm{asin}(\mathcal{z}/\sqrt{\mathcal{x}^2 + \mathcal{y}^2 +\mathcal{z}^2}) \\ \textrm{atan2}(\mathcal{y},\mathcal{x}) \\ \sqrt{\mathcal{x}^2 + \mathcal{y}^2 + \mathcal{z}^2} \\ (x\dot{x} + y\dot{y} + z\dot{z})/\sqrt{x^2 + y^2 + z^2} \end{bmatrix} + \vec{v}_t\end{split}\]

• \(\vec{v}_t\) is Gaussian distributed with covariance \(R\), i.e.:

\[\vec{v}_t \sim \mathcal{N}(0,R)\]

\[\begin{split}R = \begin{bmatrix} \sigma_{\theta}^2 & 0 & 0 & 0\\ 0 & \sigma_{\phi}^2 & 0 & 0\\ 0 & 0 & \sigma_{r}^2 & 0\\ 0 & 0 & 0 & \sigma_{\dot{r}}^2 \end{bmatrix}\end{split}\]

The covariances for radar are determined by different factors. The angle error is affected by the radar beam width. Range error is affected by the SNR and pulse bandwidth. The error for the range rate is dependent on the dwell time. The range and range rate are binned to the centre of the cell using

\[x = \textrm{floor}(x/\Delta x)*\Delta x + \frac{\Delta x}{2}\]

The mapping property of the model is a 3 element vector, whose first (i.e. mapping[0]), second (i.e. mapping[1]) and third (i.e. mapping[2]) elements contain the state index of the \(x\), \(y\) and \(z\) coordinates, respectively.

The velocity_mapping property of the model is a 3 element vector, whose first (i.e. velocity_mapping[0]), second (i.e. velocity_mapping[1]) and third (i.e. velocity_mapping[2]) elements contain the state index of the \(\dot{x}\), \(\dot{y}\) and \(\dot{z}\) coordinates, respectively.

Note

This class implementation assumes a 3D cartesian space, it therefore expects a 6D state space.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

• range_res (float) – Size of the range bins in m

• range_rate_res (float) – Size of the velocity bins in m/s

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

• rotation_offset (StateVector, optional) – A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

• translation_offset (StateVector, optional) – A 3x1 array specifying the origin offset in terms of \(x,y,z\) coordinates.

• velocity_mapping (Tuple[int, int, int], optional) – Mapping to the targets velocity within its state space

• velocity (StateVector, optional) – A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.

range_res: float

Size of the range bins in m

range_rate_res: float

Size of the velocity bins in m/s

property ndim_meas

ndim_meas getter method

Returns:

The number of measurement dimensions

Return type:

int

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

Model function \(h(\vec{x}_t,\vec{v}_t)\)

Parameters:

• state (StateVector) – An input state vector for the target

• noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added and no binning takes place if True, the output of rvs is added and the range and range rate are binned)

Returns:

The model function evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_state, 1)

covar(**kwargs) → CovarianceMatrix

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

inverse_function(detection, **kwargs) → StateVector

Takes in the result of the function and computes the inverse function, returning the initial input of the function.

Parameters:

detection (Detection) – Input state (non-linear format)

Returns:

The linear co-ordinates

Return type:

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)

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

ndim_state: int

Number of state dimensions

noise_covar: CovarianceMatrix

Noise covariance

property rotation_matrix: ndarray

3D axis rotation matrix

Note

This will be cached until rotation_offset is replaced.

rotation_offset: StateVector

A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

rvs(num_samples=1, **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

translation_offset: StateVector

A 3x1 array specifying the origin offset in terms of \(x,y,z\) coordinates.

velocity: StateVector

A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.

velocity_mapping: Tuple[int, int, int]

Mapping to the targets velocity within its state space

pdf(state1, state2, **kwargs)

Model pdf/likelihood evaluation function

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

For the first 2 dimensions, 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,

\(Q\) = covar and \(\mathcal{N}\) is a normal distribution

The probability for the binned dimensions, the last 2, can be written as:

\[p = P(a \leq \mathcal{N} \leq b)\]

In this equation a and b are the edges of the bin.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability

logpdf(*args, **kwargs)

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

class stonesoup.models.measurement.nonlinear.CartesianToAzimuthElevationRange(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None)

Bases: NonLinearGaussianMeasurement, ReversibleModel

This is a class implementation of a time-invariant measurement model, where measurements are assumed to be received in the form of azimuth (\(\phi\)), elevation (\(\theta\)), and range (\(r\)), with Gaussian noise in each dimension. For this model, the Azimuth is defined as the angle of the measurement from the YZ plan to the YX plane and the Elevation is the angle from the XY plan to the XZ plane. The z axis is the direction the radar is pointing (broadside) and is only defined in the positive z. The x axis is generally the direction of travel for an airborne radar and the y axis is orthogonal to both the x and z. Measurements are only correctly defined for +z (measurements must be in front of the sensor.

The model is described by the following equations:

\[\vec{y}_t = h(\vec{x}_t, \vec{v}_t)\]

where:

• \(\vec{y}_t\) is a measurement vector of the form:

\[\begin{split}\vec{y}_t = \begin{bmatrix} \phi \\ \theta \\ r \end{bmatrix}\end{split}\]

• \(h\) is a non-linear model function of the form:

\[\begin{split}h(\vec{x}_t,\vec{v}_t) = \begin{bmatrix} asin(\mathcal{x}/\sqrt{\mathcal{x}^2 + \mathcal{y}^2 +\mathcal{z}^2}) \\ asin(\mathcal{y}/\sqrt{\mathcal{x}^2 + \mathcal{y}^2 +\mathcal{z}^2}) \\ \sqrt{\mathcal{x}^2 + \mathcal{y}^2 + \mathcal{z}^2} \end{bmatrix} + \vec{v}_t\end{split}\]

• \(\vec{v}_t\) is Gaussian distributed with covariance \(R\), i.e.:

\[\vec{v}_t \sim \mathcal{N}(0,R)\]

\[\begin{split}R = \begin{bmatrix} \sigma_{\phi}^2 & 0 & 0 \\ 0 & \sigma_{\theta}^2 & 0 \\ 0 & 0 & \sigma_{r}^2 \end{bmatrix}\end{split}\]

The mapping property of the model is a 3 element vector, whose first (i.e. mapping[0]), second (i.e. mapping[1]) and third (i.e. mapping[2]) elements contain the state index of the \(x\), \(y\) and \(z\) coordinates, respectively.

Note

The current implementation of this class assumes a 3D Cartesian plane.

Parameters:

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

• noise_covar (CovarianceMatrix) – Noise covariance

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

• rotation_offset (StateVector, optional) – A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

• translation_offset (StateVector, optional) – A 3x1 array specifying the Cartesian origin offset in terms of \(x,y,z\) coordinates.

covar(**kwargs) → CovarianceMatrix

Returns the measurement model noise covariance matrix.

Returns:

The measurement noise covariance.

Return type:

CovarianceMatrix of shape (ndim_meas, ndim_meas)

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

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim: int

Number of dimensions of model

ndim_state: int

Number of state dimensions

noise_covar: CovarianceMatrix

Noise covariance

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

property rotation_matrix: ndarray

3D axis rotation matrix

Note

This will be cached until rotation_offset is replaced.

rotation_offset: StateVector

A 3x1 array of angles (rad), specifying the clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

seed: int | None

Seed for random number generation

translation_offset: StateVector

A 3x1 array specifying the Cartesian origin offset in terms of \(x,y,z\) coordinates.

property ndim_meas: int

ndim_meas getter method

Returns:

The number of measurement dimensions

Return type:

int

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

Model function \(h(\vec{x}_t,\vec{v}_t)\)

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 model function evaluated given the provided time interval.

Return type:

numpy.ndarray of shape (ndim_state, 1)

inverse_function(detection, **kwargs) → StateVector

Takes in the result of the function and computes the inverse function, returning the initial input of the function.

Parameters:

detection (Detection) – Input state (non-linear format)

Returns:

The linear co-ordinates

Return type:

StateVector

rvs(num_samples=1, **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)

Categorical

class stonesoup.models.measurement.categorical.MarkovianMeasurementModel(emission_matrix: Matrix, measurement_categories: Sequence[str] = None)

Bases: MeasurementModel

The measurement model for categorical states

This is a time invariant, measurement model of a hidden Markov process.

A measurement can take one of a finite number of observable categories \(Z = \{\zeta^n|n\in \mathbf{N}, n\le N\}\) (for some finite \(N\)). A measurement vector represents a categorical distribution over \(Z\).

\[\mathbf{y}_t^i = P(\zeta_t^i)\]

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\)).

It is assumed that a measurement is independent of everything but the true state of a target.

Intended to be used in conjunction with the CategoricalState type.

Parameters:

• emission_matrix (Matrix) – Matrix of emission/output probabilities \(E_t^{ij} = E^{ij} = P(\zeta_t^i | \phi_t^j)\), determining the conditional probability that a measurement is category \(\zeta^i\) at ‘time’ \(t\) given that the true state category is \(\phi^j\) at ‘time’ \(t\). Columns will be normalised.

• measurement_categories (Sequence[str], optional) – Sequence of measurement category names. Defaults to a list of integers

emission_matrix: Matrix

Matrix of emission/output probabilities \(E_t^{ij} = E^{ij} = P(\zeta_t^i | \phi_t^j)\), determining the conditional probability that a measurement is category \(\zeta^i\) at ‘time’ \(t\) given that the true state category is \(\phi^j\) at ‘time’ \(t\). Columns will be normalised.

measurement_categories: Sequence[str]

Sequence of measurement category names. Defaults to a list of integers

function(state, **kwargs)

Applies the linear transformation:

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

The resultant vector is normalised.

Parameters:

state (CategoricalState) – The state to be measured.

Returns:

state_vector – of shape (ndim_meas, 1). The resultant measurement vector.

Return type:

stonesoup.types.array.StateVector

property ndim_state

Number of state dimensions

property ndim_meas

Number of measurement dimensions

property mapping

Assumes that all elements of the state space are considered.

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

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)

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

Gas

class stonesoup.models.measurement.gas.IsotropicPlume(ndim_state: int = 8, mapping: Sequence[int] = (0, 1, 2, 3, 4, 5, 6, 7), seed: int | None = None, min_noise: float = 0.0001, standard_deviation_percentage: float = 0.5, translation_offset: StateVector = None, missed_detection_probability: Probability = 0.1, sensing_threshold: float = 0.1)

Bases: GaussianModel, MeasurementModel

This is a class implementing the isotropic plume model for approximating the resulting plume from gas release. Mathematical formulation of the algorithm can be seen in [1] and [2]. The model assumes isotropic diffusivity and mean wind velocity, source strength and turbulent conditions.

The model calculates the concentration level at a given location based on the provided source term. The model employs a sensing threshold for deciding if gas has been detected or if the reading is just sensor noise and turbulent conditions are accounted for using a missed detection probability. The source term if formed according to the following:

\[\begin{split}\mathbf{S} = \left[\begin{array}{c} x \\ y \\ z \\ Q \\ u \\ \phi \\ \zeta_1 \\ \zeta_2 \end{array}\right],\end{split}\]

where \(x, y\) and \(z\) are the source position in 3D Cartesian space, \(Q\) is the emission rate/strength in g/s, \(u\) is the wind speed in m/s, \(\phi\) is the wind direction in radians, \(\zeta_1\) is the diffusivity of the gas in the environment and \(\zeta_2\) is the lifetime of the gas.

The concentration is calculated according to

\[\begin{split}\begin{multline} \mathcal{M}(\vec{x}_k, \Theta_k) = \frac{Q}{4\pi\Vert\vec{x}_k-\vec{p}^s\Vert} \cdot\text{exp}\left[\frac{-\Vert\vec{x}_k-\vec{p}^s\Vert}{\lambda}\right]\cdot\\ \text{exp}\left[\frac{-(x_k-x)u\cos\phi}{2\zeta_1}\right] \cdot\text{exp}\left[\frac{-(y_k-y)u\sin\phi}{2\zeta_1}\right], \end{multline}\end{split}\]

where \(\vec{x}_k\) is the position of the sensor in 3D Cartesian space (\([x_k\quad y_k\quad z_k]^\intercal\)), \(\vec{p}^s\) is the source location (\([x\quad y\quad z]^\intercal\)) and

\[\lambda = \sqrt{\frac{\zeta_1\zeta_2}{1+\frac{(u^2\zeta_2)}{4\zeta_1}}}.\]

References

[1]

Vergassola, Massima & Villermaux, Emmanuel & Shraiman, Boris I. “‘Infotaxis’ as a strategy for searching without gradients”, Nature, vol. 445, 406-409, 2007

[2] (1,2)

Hutchinson, Michael & Liu, Cunjia & Chen, Wen-Hua, “Source term estimation of a hazardous airborne release using an unmanned aerial vehicle”, Journal of Field Robotics, Vol. 36, 797-917, 2019

Parameters:

• ndim_state (int, optional) – Number of state dimensions

• mapping (Sequence[int], optional) – Mapping between measurement and state dims

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

• min_noise (float, optional) – Minimum sensor noise

• standard_deviation_percentage (float, optional) – Standard deviation as a percentage of the concentration level

• translation_offset (StateVector, optional) – A 3x1 array specifying the Cartesian origin offset in terms of \(x,y,z\) coordinates.

• missed_detection_probability (Probability, optional) – The probability that the detection has detection has been affected by turbulence.

• sensing_threshold (float, optional) – Measurement threshold. Should be set high enough to minimise false detections.

ndim_state: int

Number of state dimensions

mapping: Sequence[int]

Mapping between measurement and state dims

min_noise: float

Minimum sensor noise

standard_deviation_percentage: float

Standard deviation as a percentage of the concentration level

missed_detection_probability: Probability

The probability that the detection has detection has been affected by turbulence.

sensing_threshold: float

Measurement threshold. Should be set high enough to minimise false detections.

translation_offset: StateVector

A 3x1 array specifying the Cartesian origin offset in terms of \(x,y,z\) coordinates.

covar(**kwargs) → CovarianceMatrix

Model covariance

property ndim_meas: int

Number of measurement dimensions

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

Model function \(h(\vec{x}_t,\vec{v}_t)\)

Parameters:

• state (StateVector) – An input source term state vector

• 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). If False, then the model also does not consider the sensing_threshold and missed_detection_probability

Returns:

The model function evaluated with the provided source term

Return type:

numpy.ndarray of shape (1, 1)

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

Model log pdf/likelihood evaluation function

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

This function implements the likelihood functions from pdf() that have been converted to the log space.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

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().

This function implements the following likelihood function, adapted from (12) in [2], removing the background sensor noise term.

\[p(z_k|\Theta_k) = \frac{1}{\sigma_d\sqrt{2\pi}}\text{exp} \left(-\frac{(z_k-\hat{z}_k)^2}{2\sigma_d}\right),\]

where \(z_k\) = state1, \(\Theta_k\) = state2, \(\hat{z}_k\) = function() on state2 and \(\sigma_d\) is the measurement standard deviation assuming the measurement arose from a true gas detection. This is given by

\[\sigma_d = \sigma_{\text{percentage}} \cdot \hat{z} + \nu_{\text{min}},\]

where \(\sigma_{\text{percentage}}\) = standard_deviation_percentage and \(\nu_{\text{min}}\) = noise. In the event that a measurement is below the sensor threshold or missed, a different likelihood function is used. This is given by

\[p(z_k|\Theta_k) = (P_m) + \left((1-P_m)\cdot\frac{1}{2}\left[1+\text{erf} \left(\frac{z_{\text{thr}}-\hat{z}_k}{\sigma_m\sqrt{2}}\right)\right]\right),\]

where \(P_m\) = missed_detection_probability, \(\sigma_m\) is the missed detection standard deviation which is implemented as equal to sensing_threshold and \(\text{erf}()\) is the error function.

Parameters:

• state1 (State)

• state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability

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: int

Number of dimensions of model

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

Model noise/sample generation function

Generates noise samples from the model. For this noise, the magnitude of sensor noise depends on the measurement. Thus, the noise term is given by

\[\nu_k = \mathcal{N}\left(0,(\sigma_{\text{percentage}}\cdot z_k)^2\right).\]

Parameters:

• state (StateVector or StateVectors) – The measured state (concentration for this model) used to scale the noise term.

• 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