ProcessNoise#

class ProcessNoise(continuous_time_covariance: CovarianceMatrix, state_definition=None, sequence_definition=None, max_interval=None, body=None)#

Bases: ABC

Abstract base class for process noise modeling in orbit determination filters.

Provides a common interface for different process noise models used to account for unmodeled dynamics in spacecraft orbit determination. Handles conversion between continuous-time and discrete-time representations.

Parameters:
continuous_time_covarianceCovarianceMatrix

Covariance of the process noise input, held constant over each timeline interval.

state_definitionoptional

State vector definition. Defaults to None.

sequence_definitionoptional

Sequence definition for multi-leg trajectories. Defaults to None.

max_intervalArrayWUnits or float, optional

Longest interval the noise is accumulated over, in seconds when a float. See _noise_intervals(). Defaults to None, no limit.

bodyBody or int, optional

Body whose dynamics the noise drives, or its SPICE ID. Defaults to None, the owner of the first position in the state.

Attributes:
frame

The reference frame of the process noise covariance.

Methods

combined_covariance_at(models, k, n)

Discrete-time process noise covariance of several models at timeline index k, the sum of theirs as their inputs are independent:

combined_gamma_at(models, k, n)

Gamma matrices of several models at timeline index k, side by side.

combined_input_covariance_at(models, k)

Covariance of the stacked noise inputs of several models (see combined_gamma_at()) at timeline index k, block diagonal as the inputs are independent:

covariance_at(k, n)

Discrete-time process noise covariance at timeline index k for an n-state, zero outside the states of its body (see gamma_at()).

gamma_at(k, n)

Process noise gamma matrix at timeline index k for an n-state.

input_covariance_at(k)

Inertial covariance of the noise input over the interval ending at timeline index k, which the SRIF factors.

interval_in_seconds(interval)

A time span in seconds, checked to be positive.

noise_rows_at(k)

Rows of the estimated states the noise drives at timeline index k.

transform_from_rtn(Q, position, velocity)

Rotate a covariance from the RTN frame of a state to the inertial frame.

Raises:
ProcessNoise.NoiseBodyNotInStateError

If the state of no leg carries the noise states of body.

ProcessNoise.ConsideredNoiseStateError

If a noise state of body is considered.

ProcessNoise.MissingNoiseStateError

If a leg carries some, but not all, of the noise states of body.

See also

scarabaeus.StateNoiseCompensation

Piecewise-constant SNC implementation.

scarabaeus.DynamicalModelCompensation

Exponentially-correlated DMC implementation.

scarabaeus.ProcessNoiseSettings

Configuration object consumed by the filter.

Notes

Process noise accounts for unmodeled spacecraft dynamics and is primarily used in sequential filters to address model uncertainties and filter saturation. Concrete sub-classes must implement _compute_discrete_time_covariances().

The noise drives the states of body listed in _noise_states, wherever they sit in the state of each leg, so several propagated bodies are noised with one model each, which the filters stack (see combined_gamma_at()). On a leg whose state does not carry body the noise is zero.

References

[1]

Tapley, B. D., Schutz, B. E., & Born, G. H. (2004). Statistical Orbit Determination. Elsevier Academic Press. ISBN 978-0-12-683630-1.

static combined_covariance_at(models: list, k: int, n: int) → ndarray#

Discrete-time process noise covariance of several models at timeline index k, the sum of theirs as their inputs are independent:

\[\mathbf{Q}_k = \sum_i \mathbf{Q}_k^{(i)}\]
Parameters:
modelslist of ProcessNoise

One model per noised body, discretized on the same epochs.

kint

Index in the epochs the matrices were computed on.

nint

Size of the state the noise is added to.

Returns:
np.ndarray

Covariance of shape (n, n).

static combined_gamma_at(models: list, k: int, n: int) → ndarray#

Gamma matrices of several models at timeline index k, side by side.

Each model drives the states of its own body (see noise_rows_at()), so the noise inputs are independent and stack:

\[\mathbf{\Gamma}_k = [\,\mathbf{\Gamma}_k^{(1)} \;\cdots\; \mathbf{\Gamma}_k^{(m)}\,]\]

with three noise components per body.

Parameters:
modelslist of ProcessNoise

One model per noised body, discretized on the same epochs.

kint

Index in the epochs the matrices were computed on.

nint

Size of the state the noise is added to.

Returns:
np.ndarray

Gamma matrix of shape (n, 3 m), for m models.

static combined_input_covariance_at(models: list, k: int) → ndarray#

Covariance of the stacked noise inputs of several models (see combined_gamma_at()) at timeline index k, block diagonal as the inputs are independent:

\[\tilde{\mathbf{Q}}_k = \mathrm{blockdiag}(\tilde{\mathbf{Q}}_k^{(1)}, \ldots, \tilde{\mathbf{Q}}_k^{(m)})\]
Parameters:
modelslist of ProcessNoise

One model per noised body, discretized on the same epochs.

kint

Index in the epochs the matrices were computed on.

Returns:
np.ndarray

Covariance of shape (3 m, 3 m), for m models.

static interval_in_seconds(interval) → float | None#

A time span in seconds, checked to be positive.

Parameters:
intervalArrayWUnits, float or None

Time span, in seconds when a float. None is returned as is.

Returns:
float or None

The span in seconds.

Raises:
ProcessNoise.NonPositiveIntervalError

If the span is not positive.

covariance_at(k: int, n: int) → ndarray#

Discrete-time process noise covariance at timeline index k for an n-state, zero outside the states of its body (see gamma_at()).

Parameters:
kint

Index in the epochs the matrices were computed on.

nint

Size of the state the noise is added to.

Returns:
np.ndarray

Covariance of shape (n, n).

gamma_at(k: int, n: int) → ndarray#

Process noise gamma matrix at timeline index k for an n-state.

The noise drives only the states of its body (see noise_rows_at()), so the rows of every other state are zero. The size is chosen where the matrix is used: a filter carries fewer states when some are considered, and a different number on each leg of a sequence.

Parameters:
kint

Index in the epochs the matrices were computed on.

nint

Size of the state the noise is added to.

Returns:
np.ndarray

Gamma matrix of shape (n, m), with m the size of the noise vector, 3.

input_covariance_at(k: int) → ndarray#

Inertial covariance of the noise input over the interval ending at timeline index k, which the SRIF factors.

Parameters:
kint

Index in the epochs the matrices were computed on.

Returns:
np.ndarray

Covariance of shape (3, 3).

noise_rows_at(k: int) → ndarray#

Rows of the estimated states the noise drives at timeline index k.

They are the rows of the states of body listed in _noise_states, on the leg the filter is on at epochs[k]: the leg an event epoch starts, as the filters map the state through the node before adding the noise. Without a state definition, the leading rows.

Parameters:
kint

Index in the epochs the matrices were computed on.

Returns:
np.ndarray

Integer array, empty on a leg whose state does not carry body.

transform_from_rtn(Q: ndarray, position: ndarray, velocity: ndarray) → ndarray#

Rotate a covariance from the RTN frame of a state to the inertial frame.

The rows of T are the radial, transverse and normal unit vectors built from position and velocity, so an RTN vector maps to the inertial frame as T^T @ a_rtn and the covariance as Q_inertial = T^T @ Q_rtn @ T.

This method is a no-op when self.continuous_time_covariance.frame is not 'RTN' — the input matrix is returned unchanged.

Parameters:
Qnp.ndarray

(3, 3) covariance expressed in the RTN frame.

positionnp.ndarray

Inertial position the RTN frame is built from.

velocitynp.ndarray

Inertial velocity the RTN frame is built from.

Returns:
np.ndarray

Covariance matrix expressed in the inertial frame, or the original Q when no rotation is needed.

property frame: str#

The reference frame of the process noise covariance.

exception ConsideredNoiseStateError#

Bases: ValueError

Raised when a state the noise drives is considered rather than estimated, so the filters have no rows to add the noise to.

exception MissingNoiseStateError#

Bases: ValueError

Raised when a leg carries some, but not all, of the states the noise drives for its body.

exception MissingReferenceStateError#

Bases: ValueError

Raised when an RTN process noise is discretized without the reference trajectory its rotation to the inertial frame is built from.

exception NoiseBodyNotInStateError#

Bases: ValueError

Raised when the state of no leg carries the body the noise drives.

exception NonPositiveIntervalError#

Bases: ValueError

Raised when the longest interval the noise is accumulated over is not a positive time.