Skip to content

Extended Kalman Filter

Sequential state estimator using linearized dynamics and measurement models.

ExtendedKalmanFilter 

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

Extended Kalman Filter for sequential state estimation.

Processes observations one at a time, propagating state and covariance between observation epochs using a numerical propagator. Supports both built-in and custom Python measurement models.

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])

ekf = bh.ExtendedKalmanFilter(
    epoch, state, p0,
    propagation_config=bh.NumericalPropagationConfig.default(),
    force_config=bh.ForceModelConfig.two_body_gravity(),
    measurement_models=[bh.InertialPositionMeasurementModel(10.0)],
)

Initialize instance.

builder staticmethod 

builder(epoch: Epoch, state: ndarray, initial_covariance: ndarray, force_config: ForceModelConfig, config: EKFConfig) -> ExtendedKalmanFilterBuilder

Create a builder for constructing an ExtendedKalmanFilter.

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 EKFConfig

EKF configuration.

 required

Returns:

Name Type Description
ExtendedKalmanFilterBuilder ExtendedKalmanFilterBuilder

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

ekf = (
    bh.ExtendedKalmanFilter.builder(
        epoch, state, p0, bh.ForceModelConfig.two_body(), bh.EKFConfig.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.

Performs predict (propagate to observation epoch) then update (incorporate measurement).

Parameters:

Name Type Description Default
observation Observation

The observation to process.

 required

Returns:

Name Type Description
FilterRecord FilterRecord

Record containing pre/post-fit residuals, Kalman 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.

ExtendedKalmanFilterBuilder 

ExtendedKalmanFilterBuilder()

Builder for [ExtendedKalmanFilter].

Created by ExtendedKalmanFilter.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 ExtendedKalmanFilter'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

ekf = (
    bh.ExtendedKalmanFilter.builder(
        epoch, state, p0, bh.ForceModelConfig.two_body(), bh.EKFConfig.default(),
    )
    .propagation_config(bh.NumericalPropagationConfig.default())
    .measurement_model(bh.InertialPositionMeasurementModel(10.0))
    .build()
)

Initialize instance.

additional_dynamics method descriptor 

additional_dynamics(dynamics: callable) -> ExtendedKalmanFilterBuilder

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
ExtendedKalmanFilterBuilder ExtendedKalmanFilterBuilder

The builder, for method chaining.

build method descriptor 

build() -> ExtendedKalmanFilter

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
ExtendedKalmanFilter ExtendedKalmanFilter

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, 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) -> ExtendedKalmanFilterBuilder

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
ExtendedKalmanFilterBuilder ExtendedKalmanFilterBuilder

The builder, for method chaining.

measurement_model method descriptor 

measurement_model(model: MeasurementModel) -> ExtendedKalmanFilterBuilder

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
ExtendedKalmanFilterBuilder ExtendedKalmanFilterBuilder

The builder, for method chaining.

measurement_models method descriptor 

measurement_models(models: List) -> ExtendedKalmanFilterBuilder

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
ExtendedKalmanFilterBuilder ExtendedKalmanFilterBuilder

The builder, for method chaining.

params method descriptor 

params(params: ndarray) -> ExtendedKalmanFilterBuilder

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
ExtendedKalmanFilterBuilder ExtendedKalmanFilterBuilder

The builder, for method chaining.

propagation_config method descriptor 

propagation_config(config: NumericalPropagationConfig) -> ExtendedKalmanFilterBuilder

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

Defaults to NumericalPropagationConfig.default() if not called. STM propagation is force-enabled regardless, since the EKF requires it for covariance propagation.

Parameters:

Name Type Description Default
config NumericalPropagationConfig

Numerical propagation configuration.

 required

Returns:

Name Type Description
ExtendedKalmanFilterBuilder ExtendedKalmanFilterBuilder

The builder, for method chaining.

See Also

  • EKF Guide - Setup, processing, and diagnostics
  • Common Types - Observation, FilterRecord, configuration types