Measurement Models
- class stonesoup.models.measurement.base.MeasurementModel(ndim_state: int, mapping: Sequence[int])[source]
-
Measurement Model base class
- Parameters:
ndim_state (
int) – Number of state dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dims
Linear
- class stonesoup.models.measurement.linear.LinearGaussian(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None)[source]
Bases:
MeasurementModel,LinearModel,GaussianModelThis 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_kis a (ndim_meas,ndim_state) matrix andv_kis Gaussian distributed.- Parameters:
ndim_state (
int) – Number of state dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
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:
- matrix(**kwargs)[source]
Model matrix \(H(t)\)
- Returns:
The model matrix evaluated given the provided time interval.
- Return type:
numpy.ndarrayof shape (ndim_meas,ndim_state)
- function(state, noise=False, **kwargs)[source]
Model function \(h(t,x(t),w(t))\)
- Parameters:
state (
State) – An input statenoise (
numpy.ndarrayor 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 model function evaluated given the provided time interval.
- Return type:
numpy.ndarrayof shape (ndim_meas, 1)
- covar(**kwargs)[source]
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof 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.ndarrayof 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 statestate2which 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_vector2and \(Q\) =covar.
- pdf(state1: State, state2: State, **kwargs) Probability | ndarray
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- 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 =\)
noiseand \(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.measurement.nonlinear.CombinedReversibleGaussianMeasurementModel(model_list: Sequence[GaussianModel], seed: int | None = None)[source]
Bases:
ReversibleModel,GaussianModel,MeasurementModelCombine multiple models into a single model by stacking them.
The assumption is that all models are Gaussian, and must be combination of
LinearModelandNonLinearModelmodels. They must all expect the same dimension state vector (i.e. have the samendim_state), using model mapping as appropriate.This also implements the
inverse_function(), but will raise aNotImplementedErrorif any model isn’t either aLinearModelorReversibleModel.- Parameters:
model_list (
collections.abc.Sequence) – List of Measurement Models.seed (
Optional[int], optional) – Seed for random number generation
- model_list: Sequence[GaussianModel]
List of Measurement Models.
- property mapping
Mapping between measurement and state dims
- function(state, *args, **kwargs) StateVector[source]
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- 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.ndarrayof shape (ndim_meas,ndim_state)
- inverse_function(detection, **kwargs) StateVector[source]
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:
- covar(**kwargs) CovarianceMatrix[source]
Model covariance
- rvs(num_samples=1, **kwargs) StateVector | StateVectors[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)
- logpdf(state1: State, state2: State, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- pdf(state1: State, state2: State, **kwargs) Probability | ndarray
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- class stonesoup.models.measurement.nonlinear.NonLinearGaussianMeasurement(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None)[source]
Bases:
MeasurementModel,GaussianModel,ABCThis 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 dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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[source]
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis replaced.
- abstractmethod 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.ndarrayor 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:
StateVectororStateVectors
- 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.ndarrayof 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 statestate2which 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_vector2and \(Q\) =covar.
- pdf(state1: State, state2: State, **kwargs) Probability | ndarray
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- 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 =\)
noiseand \(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.measurement.nonlinear.CartesianToElevationBearingRange(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None)[source]
Bases:
_AngleNonLinearGaussianMeasurement,ReversibleModelThis 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
mappingproperty 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 dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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:
- inverse_function(detection, **kwargs) StateVector[source]
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:
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- function(state, noise=False, **kwargs) StateVector | StateVectors
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- 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.ndarrayof shape (ndim_meas,ndim_state)
- logpdf(state1, state2, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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.measurement.nonlinear.CartesianToBearingRange(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None)[source]
Bases:
_AngleNonLinearGaussianMeasurement,ReversibleModelThis 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
mappingproperty 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 dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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:
- inverse_function(detection, **kwargs) StateVector[source]
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:
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- function(state, noise=False, **kwargs) StateVector | StateVectors
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- 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.ndarrayof shape (ndim_meas,ndim_state)
- logpdf(state1, state2, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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.measurement.nonlinear.CartesianToElevationBearing(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None)[source]
Bases:
_AngleNonLinearGaussianMeasurementThis 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
mappingproperty 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 dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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:
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- function(state, noise=False, **kwargs) StateVector | StateVectors
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- 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.ndarrayof shape (ndim_meas,ndim_state)
- logpdf(state1, state2, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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.measurement.nonlinear.Cartesian2DToBearing(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, seed: int | None = None, rotation_offset: StateVector = None, translation_offset: StateVector = None)[source]
Bases:
_AngleNonLinearGaussianMeasurementThis 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
mappingproperty 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 dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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:
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- function(state, noise=False, **kwargs) StateVector | StateVectors
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- 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.ndarrayof shape (ndim_meas,ndim_state)
- logpdf(state1, state2, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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.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)[source]
Bases:
_AngleNonLinearGaussianMeasurementThis 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
mappingproperty 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 dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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, optional) – Mapping to the targets velocity within its state spacevelocity (
StateVector, optional) – A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.
- 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:
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- function(state, noise=False, **kwargs) StateVector | StateVectors
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- 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.ndarrayof shape (ndim_meas,ndim_state)
- logpdf(state1, state2, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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.measurement.nonlinear.CartesianToBearingRangeRate2D(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] = (1, 3), velocity: StateVector = None)[source]
Bases:
_AngleNonLinearGaussianMeasurementThis 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
mappingproperty 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
This class implementation assuming a 2D cartesian space, it therefore expects a 4D state space.
- Parameters:
ndim_state (
int) – Number of state dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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.velocity_mapping (
tuple, optional) – Mapping to the targets velocity within its state spacevelocity (
StateVector, optional) – A 2x1 array specifying the sensor velocity in terms of \(x,y\) coordinates.
- translation_offset: StateVector
A 2x1 array specifying the origin offset in terms of \(x,y\) coordinates.
- velocity: StateVector
A 2x1 array specifying the sensor velocity in terms of \(x,y\) coordinates.
- property ndim_meas: int
ndim_meas getter method
- Returns:
The number of measurement dimensions
- Return type:
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- function(state, noise=False, **kwargs) StateVector | StateVectors
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- 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.ndarrayof shape (ndim_meas,ndim_state)
- logpdf(state1, state2, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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.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)[source]
Bases:
_AngleNonLinearGaussianMeasurement,ReversibleModelThis 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
mappingproperty 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 or 9D state space.
- Parameters:
ndim_state (
int) – Number of state dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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, optional) – Mapping to the targets velocity within its state spacevelocity (
StateVector, optional) – A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.
- 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:
- inverse_function(detection, **kwargs) StateVector[source]
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:
- 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.ndarrayof shape (ndim_meas,ndim_state)
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- function(state, noise=False, **kwargs) StateVector | StateVectors
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- logpdf(state1, state2, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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.measurement.nonlinear.CartesianToElevationRateBearingRateRangeRate(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)[source]
Bases:
_AngleNonLinearGaussianMeasurement,ReversibleModelThis 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 elevation-rate (\(\dot{\theta}\)), bearing-rate (\(\dot{\phi}\)), 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{\theta} \\ \dot{\phi} \\ \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} \\ (\dot{y}\mathcal{x} - \dot{x}\mathcal{y}) / (\mathcal{x}^2 + \mathcal{y}^2) \\ (\dot{y}\sqrt{\mathcal{x}^2 + \mathcal{y}^2} - (\mathcal{xy}\cdot\dot{x}\dot{y}/ \sqrt{\mathcal{x}^2 + \mathcal{y}^2})\mathcal{z}}) / \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 & 0\\ 0 & \sigma_{\phi}^2 & 0 & 0 & 0 & 0\\ 0 & 0 & \sigma_{r}^2 & 0& 0 & 0\\ 0 & 0 & 0 & \sigma_{\dot{\theta}}^2 & 0 & 0\\ 0 & 0 & 0 & 0 & \sigma_{\dot{\phi}}^2 & 0\\ 0 & 0 & 0 & 0 & 0 & \sigma_{\dot{r}}^2\\ \end{bmatrix}\end{split}\]The
mappingproperty 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 assumes a 3D cartesian space, it therefore expects a 6D state space.
- Parameters:
ndim_state (
int) – Number of state dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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, optional) – Mapping to the targets velocity within its state spacevelocity (
StateVector, optional) – A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.
- 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:
- inverse_function(detection, **kwargs) StateVector[source]
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:
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- function(state, noise=False, **kwargs) StateVector | StateVectors
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- 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.ndarrayof shape (ndim_meas,ndim_state)
- logpdf(state1, state2, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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.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)[source]
Bases:
CartesianToElevationBearingRangeRateThis 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
mappingproperty 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_mappingproperty 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 dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covariancerange_res (
float) – Size of the range bins in mrange_rate_res (
float) – Size of the velocity bins in m/sseed (
Optional[int], optional) – Seed for random number generationrotation_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, optional) – Mapping to the targets velocity within its state spacevelocity (
StateVector, optional) – A 3x1 array specifying the sensor velocity in terms of \(x,y,z\) coordinates.
- property ndim_meas
ndim_meas getter method
- Returns:
The number of measurement dimensions
- Return type:
- function(state, noise=False, **kwargs)[source]
Model function \(h(\vec{x}_t,\vec{v}_t)\)
- Parameters:
state (
StateVector) – An input state vector for the targetnoise (
numpy.ndarrayor bool) – An externally generated random process noise sample (the default isFalse, in which case no noise will be added and no binning takes place ifTrue, the output ofrvsis added and the range and range rate are binned)
- Returns:
The model function evaluated given the provided time interval.
- Return type:
numpy.ndarrayof shape (ndim_state, 1)
- pdf(state1, state2, **kwargs)[source]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which is passed tofunction().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\) =
covarand \(\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:
- Returns:
The likelihood of
state1, givenstate2- Return type:
- where \(y_t\) =
- logpdf(*args, **kwargs)[source]
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof 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:
- 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.ndarrayof shape (ndim_meas,ndim_state)
- noise_covar: CovarianceMatrix
Noise covariance
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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)
- 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.
- 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)[source]
Bases:
_AngleNonLinearGaussianMeasurement,ReversibleModelThis 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
mappingproperty 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 dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covarianceseed (
Optional[int], optional) – Seed for random number generationrotation_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:
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof shape (ndim_meas,ndim_meas)
- function(state, noise=False, **kwargs) StateVector | StateVectors
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- inverse_function(detection, **kwargs) StateVector[source]
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:
- 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.ndarrayof shape (ndim_meas,ndim_state)
- logpdf(state1, state2, **kwargs) float | ndarray
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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 =\)
noiseand \(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)[source]
Bases:
MeasurementModelThe 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
CategoricalStatetype.- 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 (
collections.abc.Sequence, 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)[source]
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:
- 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.ndarrayof 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 statestate2which is passed tofunction().
- 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)
- pdf()[source]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which is passed tofunction().- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
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)[source]
Bases:
GaussianModel,MeasurementModelThis 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
- Parameters:
ndim_state (
int, optional) – Number of state dimensionsmapping (
collections.abc.Sequence, optional) – Mapping between measurement and state dimsseed (
Optional[int], optional) – Seed for random number generationmin_noise (
float, optional) – Minimum sensor noisestandard_deviation_percentage (
float, optional) – Standard deviation as a percentage of the concentration leveltranslation_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.
- translation_offset: StateVector
A 3x1 array specifying the Cartesian origin offset in terms of \(x,y,z\) coordinates.
- 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.
- covar(**kwargs) CovarianceMatrix[source]
Model covariance
- function(state: State, noise: bool | ndarray = False, random_state=None, **kwargs) StateVector | StateVectors[source]
Model function \(h(\vec{x}_t,\vec{v}_t)\)
- Parameters:
state (
StateVector) – An input source term state vectornoise (
numpy.ndarrayor 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). If False, then the model also does not consider thesensing_thresholdandmissed_detection_probability
- Returns:
The model function evaluated with the provided source term
- Return type:
numpy.ndarrayof shape (1, 1)
- logpdf(state1: State, state2: State, **kwargs) float | ndarray[source]
Model log pdf/likelihood evaluation function
Evaluates the log pdf/likelihood of
state1, given the statestate2which is passed tofunction().This function implements the likelihood functions from
pdf()that have been converted to the log space.
- pdf(state1: State, state2: State, **kwargs) Probability | ndarray[source]
Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which is passed tofunction().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()onstate2and \(\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_percentageand \(\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 tosensing_thresholdand \(\text{erf}()\) is the error function.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
- rvs(state: StateVector | StateVectors, num_samples: int = 1, random_state=None, **kwargs) StateVector | StateVectors[source]
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 (
StateVectororStateVectors) – 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)
- 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.ndarrayof shape (ndim_meas,ndim_state)
Graph
- class stonesoup.models.measurement.graph.OptimalPathToDestinationMeasurementModel(ndim_state: int, mapping: Sequence[int], noise_covar: CovarianceMatrix, graph: RoadNetwork, seed: int | None = None, rotation_offset: StateVector = None, use_indicator: bool = True)[source]
Bases:
NonLinearGaussianMeasurementShortest path to destination measurement model
This is a measurement model that projects the target’s position on the road network to a 2D position, via a non-linear transformation function \(h(x)\), which parameterizes the likelihood of the measurement given the target’s state. This is a generalised implementation of the measurement model described in [3].
The positional measurement noise is modelled as a zero-mean Gaussian distribution with covariance \(R\), such that:
\[y_k = h(x_k) + v_k, v_k \sim \mathcal{N}(0, R)\]where the state vector \(x_k\) is assumed to take the form:
\[x_k = \left[r_k, \cdots, e_k, d_k, s_k\right]\]and \(e_k\) denotes the edge the target is currently on, \(r_k\) is the distance travelled along the edge, \(d_k\) is the destination node, and \(s_k\) is the source node. The notation \(\cdots\) denotes additional state variables that are not used in this model (e.g. velocity).
The likelihood function is defined in either of two ways, depending on the value of
use_indicator:If
use_indicatoris False, then the likelihood function is defined as:
\[p(y_k|x_k) = \mathcal{N}(y_k; h(x_k), R)\]If
use_indicatoris True, then the likelihood function is defined as:
\[\begin{split}p(y_k|x_k) = \begin{cases}\mathcal{N}(y_k; h(x_k), R), & \text{if } e_k \in \text{shortest_path}(s_k, d_k) \\ 0 & \text{otherwise}\end{cases}\end{split}\]where \(\text{shortest_path}(s_k, d_k)\) is the shortest path between the source node \(s_k\) and destination node \(d_k\) on the road network. The indicator function implements Eq. (26) in [3].
References
- Parameters:
ndim_state (
int) – Number of state dimensionsmapping (
collections.abc.Sequence) – Mapping between measurement and state dimsnoise_covar (
CovarianceMatrix) – Noise covariancegraph (
RoadNetwork) – The road network that the target is moving onseed (
Optional[int], optional) – Seed for random number generationrotation_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.use_indicator (
bool, optional) – Whether to use the indicator function in the evaluation of the likelihood
- graph: RoadNetwork
The road network that the target is moving on
- property ndim_meas
ndim_meas getter method
- Returns:
The number of measurement dimensions
- Return type:
- function(state, noise=False, **kwargs)[source]
Model function \(f_k(x(k),w(k))\)
- Parameters:
state (State) – An input state
noise (
numpy.ndarrayor 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:
StateVectororStateVectors
- logpdf(state1, state2, **kwargs)[source]
Model log pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1, given the statestate2which 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_vector2and \(Q\) =covar.
- covar(**kwargs) CovarianceMatrix
Returns the measurement model noise covariance matrix.
- Returns:
The measurement noise covariance.
- Return type:
CovarianceMatrixof 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.ndarrayof shape (ndim_meas,ndim_state)
- 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 statestate2which 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_vector2and \(Q\) =covar.- Parameters:
- Returns:
The likelihood of
state1, givenstate2- Return type:
ProbabilityorndarrayofProbability
- property rotation_matrix: ndarray
3D axis rotation matrix
Note
This will be cached until
rotation_offsetis 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: 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 =\)
noiseand \(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)