Skip to content

Unscented Kalman Filter

Sequential state estimator using sigma points to capture nonlinear dynamics without linearization.

UnscentedKalmanFilter 

UnscentedKalmanFilter(epoch: Any, state: Any, initial_covariance: Any, propagation_config: Any, force_config: Any, measurement_models: Any, config: Any = None, params: Any = None, additional_dynamics: Any = None, control_input: Any = None)

Unscented Kalman Filter for sequential state estimation.

Uses sigma points to propagate state statistics through nonlinear dynamics and measurement models without linearization. Does not require Jacobians or STM propagation.

Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import brahe as bh
import numpy as np

bh.initialize_eop()

epoch = bh.Epoch(2024, 1, 1, 0, 0, 0.0)
state = np.array([6878e3, 0.0, 0.0, 0.0, 7612.0, 0.0])
p0 = np.diag([1e6, 1e6, 1e6, 1e2, 1e2, 1e2])

ukf = bh.UnscentedKalmanFilter(
    epoch, state, p0,
    propagation_config=bh.NumericalPropagationConfig.default(),
    force_config=bh.ForceModelConfig.two_body(),
    measurement_models=[bh.InertialPositionMeasurementModel(10.0)],
)

Initialize instance.

builder staticmethod 

builder(epoch: Epoch, state: ndarray, initial_covariance: ndarray, force_config: ForceModelConfig, config: UKFConfig) -> UnscentedKalmanFilterBuilder

Create a builder for constructing an UnscentedKalmanFilter.

The builder takes the required inputs directly; optional inputs (propagation config, params, additional dynamics, control input, measurement models) are set through chained setter calls before calling build().

Parameters:

Name Type Description Default
epoch Epoch

Initial epoch.

 required
state ndarray

Initial state vector in ECI [x,y,z,vx,vy,vz,...] (meters, m/s).

 required
initial_covariance ndarray

Initial covariance matrix (n x n).

 required
force_config ForceModelConfig

Force model configuration.

 required
config UKFConfig

UKF configuration.

 required

Returns:

Name Type Description
UnscentedKalmanFilterBuilder UnscentedKalmanFilterBuilder

New builder instance.
Example 
1
2
3
4
5
6
7
8
9
import brahe as bh

ukf = (
    bh.UnscentedKalmanFilter.builder(
        epoch, state, p0, bh.ForceModelConfig.two_body(), bh.UKFConfig.default(),
    )
    .measurement_model(bh.InertialPositionMeasurementModel(10.0))
    .build()
)

current_covariance method descriptor 

current_covariance() -> ndarray

Get current covariance estimate.

Returns:

Type Description
ndarray

numpy.ndarray: Current covariance matrix.

current_epoch method descriptor 

current_epoch() -> Epoch

Get current epoch.

Returns:

Name Type Description
Epoch Epoch

Current filter epoch.

current_state method descriptor 

current_state() -> ndarray

Get current state estimate.

Returns:

Type Description
ndarray

numpy.ndarray: Current state vector.

process_observation method descriptor 

process_observation(observation: Observation) -> FilterRecord

Process a single observation.

Parameters:

Name Type Description Default
observation Observation

The observation to process.

 required

Returns:

Name Type Description
FilterRecord FilterRecord

Record containing pre/post-fit residuals, gain, etc.

Raises:

Type Description
Exception

Propagates the original exception raised by an additional-dynamics or control-input callback, or a BraheError if propagation or the measurement update fails.

process_observations method descriptor 

process_observations(observations: list[Observation]) -> Any

Process multiple observations (auto-sorted by epoch).

Parameters:

Name Type Description Default
observations list[Observation]

List of observations.

 required

Raises:

Type Description
Exception

Propagates the original exception raised by an additional-dynamics or control-input callback, or a BraheError if propagation or a measurement update fails.

propagate_to method descriptor 

propagate_to(epoch: Epoch) -> FilterRecord

Propagate the filter to an epoch without a measurement update.

Runs the prediction step only, applying process noise, and records a FilterRecord with measurement fields empty (measurement_name is "Propagation"). Use to advance the filter across measurement gaps while recording covariance growth.

Parameters:

Name Type Description Default
epoch Epoch

Target epoch (at or after the current filter epoch).

 required

Returns:

Name Type Description
FilterRecord FilterRecord

Record of the prediction step.

Raises:

Type Description
Exception

Propagates the original exception raised by an additional-dynamics or control-input callback, or a BraheError if epoch is before the current filter epoch or propagation fails.

records method descriptor 

records() -> list[FilterRecord]

Get all stored filter records.

Returns:

Type Description
list[FilterRecord]

list[FilterRecord]: List of filter records.

UnscentedKalmanFilterBuilder 

UnscentedKalmanFilterBuilder()

Builder for [UnscentedKalmanFilter].

Created by UnscentedKalmanFilter.builder(), which takes the required inputs (epoch, state, initial_covariance, force_config, config). Remaining inputs are provided through chained setters and default to None / empty (NumericalPropagationConfig.default() for the propagation configuration, no measurement models). build() delegates to UnscentedKalmanFilter's flat constructor; the builder is single-use, and calling build() a second time raises RuntimeError.

Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import brahe as bh

ukf = (
    bh.UnscentedKalmanFilter.builder(
        epoch, state, p0, bh.ForceModelConfig.two_body(), bh.UKFConfig.default(),
    )
    .propagation_config(bh.NumericalPropagationConfig.default())
    .measurement_model(bh.InertialPositionMeasurementModel(10.0))
    .build()
)

Initialize instance.

additional_dynamics method descriptor 

additional_dynamics(dynamics: callable) -> UnscentedKalmanFilterBuilder

Set additional dynamics for extended state dimensions beyond the orbital state.

Parameters:

Name Type Description Default
dynamics callable

Function computing derivatives for extra state elements. Signature: f(t, state, params) -> derivative.

 required

Returns:

Name Type Description
UnscentedKalmanFilterBuilder UnscentedKalmanFilterBuilder

The builder, for method chaining.

build method descriptor 

build() -> UnscentedKalmanFilter

Construct the filter from the accumulated configuration.

This consumes the builder. The builder is single-use: calling build() a second time raises RuntimeError.

Returns:

Name Type Description
UnscentedKalmanFilter UnscentedKalmanFilter

Initialized filter ready to process observations.

Raises:

Type Description
RuntimeError

If the builder was already consumed by a prior build() call, or if the underlying filter construction fails (no measurement models, mismatched covariance dimensions, invalid sigma-point parameters, or the propagator could not be constructed).
Exception

Propagates the original exception raised by a dynamics or control-input callback invoked during construction (e.g. computing the initial acceleration when store_accelerations is enabled).

control_input method descriptor 

control_input(control: callable) -> UnscentedKalmanFilterBuilder

Set a continuous control-input function that adds an acceleration perturbation.

Parameters:

Name Type Description Default
control callable

Control function returning an acceleration perturbation vector. Signature: f(t, state, params) -> acceleration.

 required

Returns:

Name Type Description
UnscentedKalmanFilterBuilder UnscentedKalmanFilterBuilder

The builder, for method chaining.

measurement_model method descriptor 

measurement_model(model: MeasurementModel) -> UnscentedKalmanFilterBuilder

Append a measurement model.

Call multiple times to register multiple measurement types; Observation's model_index selects among them.

Parameters:

Name Type Description Default
model MeasurementModel

Measurement model to append (built-in or custom).

 required

Returns:

Name Type Description
UnscentedKalmanFilterBuilder UnscentedKalmanFilterBuilder

The builder, for method chaining.

measurement_models method descriptor 

measurement_models(models: List) -> UnscentedKalmanFilterBuilder

Replace the full list of measurement models.

Parameters:

Name Type Description Default
models list

Measurement models, replacing any previously set.

 required

Returns:

Name Type Description
UnscentedKalmanFilterBuilder UnscentedKalmanFilterBuilder

The builder, for method chaining.

params method descriptor 

params(params: ndarray) -> UnscentedKalmanFilterBuilder

Set the parameter vector [mass, drag_area, Cd, srp_area, Cr, ...].

Required when force_config references parameter indices for drag or SRP.

Parameters:

Name Type Description Default
params ndarray

Parameter vector.

 required

Returns:

Name Type Description
UnscentedKalmanFilterBuilder UnscentedKalmanFilterBuilder

The builder, for method chaining.

propagation_config method descriptor 

propagation_config(config: NumericalPropagationConfig) -> UnscentedKalmanFilterBuilder

Set the propagation configuration (integrator method, tolerances, and step sizes).

Defaults to NumericalPropagationConfig.default() if not called.

Parameters:

Name Type Description Default
config NumericalPropagationConfig

Numerical propagation configuration.

 required

Returns:

Name Type Description
UnscentedKalmanFilterBuilder UnscentedKalmanFilterBuilder

The builder, for method chaining.

UKFConfig 

UKFConfig(alpha: Any = 0.001, beta: Any = 2.0, kappa: Any = 0.0, process_noise: Any = None, store_records: Any = True)

Configuration for the Unscented Kalman Filter.

Example 
1
2
import brahe as bh
config = bh.UKFConfig(alpha=1e-3, beta=2.0, kappa=0.0)

Initialize instance.

alpha property 

alpha: Any

TODO: Add docstring

beta property 

beta: Any

TODO: Add docstring

kappa property 

kappa: Any

TODO: Add docstring

store_records property 

store_records: Any

TODO: Add docstring

default staticmethod 

default() -> UKFConfig

Create a default UKF configuration.

Returns:

Name Type Description
UKFConfig UKFConfig

Default configuration (alpha=1e-3, beta=2.0, kappa=0.0).

See Also

  • UKF Guide - Setup, sigma points, and EKF comparison
  • Common Types - Observation, FilterRecord, configuration types