Skip to content

NumericalPropagator

Generic numerical propagator for arbitrary dynamical systems. Unlike NumericalOrbitPropagator which has built-in orbital force models, NumericalPropagator accepts user-defined dynamics functions, making it suitable for attitude propagation, chemical kinetics, population models, or any ODE system.

Note

For conceptual explanations and usage examples, see Generic Dynamics in the User Guide.

NumericalPropagator 

NumericalPropagator(epoch: Any, state: Any, dynamics: Any, propagation_config: Any, params: Any = None, initial_covariance: Any = None, control_input: Any = None)

Generic numerical propagator for arbitrary N-dimensional dynamical systems.

This propagator accepts a user-defined Python dynamics function and can be applied to any system of ODEs: attitude dynamics, chemical kinetics, population models, control systems, etc.

Attributes:

Name Type Description
current_epoch Epoch

Current propagation time
initial_epoch Epoch

Initial epoch from propagator creation
state_dim int

Dimension of state vector
step_size float

Current integration step size in seconds
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import brahe as bh
import numpy as np

# Define dynamics: simple harmonic oscillator
# dx/dt = v, dv/dt = -ω²x
omega = 1.0
def sho_dynamics(t, state, params):
    return np.array([state[1], -omega**2 * state[0]])

# Create initial state
epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([1.0, 0.0])  # [position, velocity]

# Create propagator
prop = bh.NumericalPropagator(
    epoch, state, sho_dynamics,
    bh.NumericalPropagationConfig.default()
)

# Propagate one period
prop.propagate_to(epoch + 2.0 * np.pi)
print(f"Final state: {prop.current_state()}")  # Should be ~[1, 0]

Initialize instance.

initial_epoch property 

initial_epoch: Any

Get initial epoch.

state_dim property 

state_dim: ndarray

Get state dimension.

step_size property 

step_size: Any

Get current step size.

trajectory property 

trajectory: SOrbitTrajectory

Get accumulated trajectory.

add_event_detector method descriptor 

add_event_detector(event: Union[TimeEvent, ValueEvent, BinaryEvent]) -> Any

Add an event detector to this propagator.

Parameters:

Name Type Description Default
event TimeEvent or ValueEvent or BinaryEvent

Event detector

 required
Example 
1
2
3
4
5
import brahe as bh

prop = bh.NumericalPropagator(epoch, state, dynamics, config)
event = bh.TimeEvent(epoch + 5.0, "5 second mark")
prop.add_event_detector(event)

builder staticmethod 

builder(epoch: Epoch, state: ndarray, dynamics: callable) -> NumericalPropagatorBuilder

Create a builder for constructing a generic numerical propagator.

The builder takes the three required inputs directly; optional inputs (propagation config, params, control input, initial covariance) are set through chained setter calls before calling build().

Parameters:

Name Type Description Default
epoch Epoch

Initial epoch.

 required
state ndarray

Initial state vector (N-dimensional).

 required
dynamics callable

Dynamics function: f(t, state, params) -> derivative. Should accept (float, np.ndarray, Optional[np.ndarray]) and return np.ndarray.

 required

Returns:

Name Type Description
NumericalPropagatorBuilder NumericalPropagatorBuilder

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

omega = 1.0
def sho_dynamics(t, state, params):
    return np.array([state[1], -omega**2 * state[0]])

epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([1.0, 0.0])

prop = (
    bh.NumericalPropagator.builder(epoch, state, sho_dynamics)
    .propagation_config(bh.NumericalPropagationConfig.default())
    .build()
)

clear_events method descriptor 

clear_events() -> Any

Clear all detected events from the event log.

covariance method descriptor 

covariance(epoch) -> Any

Get covariance at a specific epoch.

current_epoch method descriptor 

current_epoch() -> Any

Get current epoch.

current_state method descriptor 

current_state() -> ndarray

Get current state vector.

disable_stm_propagation method descriptor 

disable_stm_propagation() -> Any

Disable STM (variational equation) propagation.

Providing an initial covariance at construction enables STM propagation automatically. When the STM is not needed, disabling it removes the cost of integrating the variational equations at every step. Covariance propagation requires the STM, so any covariance held by the propagator is cleared: stm() and current_covariance() return None afterwards. Sensitivity propagation, if enabled, is unaffected. No-op if STM propagation is not enabled.

event_log method descriptor 

event_log() -> list[DetectedEvent]

Get the event log (list of detected events).

Returns:

Type Description
list[DetectedEvent]

list[DetectedEvent]: List of events detected during propagation.

events_by_detector_index method descriptor 

events_by_detector_index(index: int) -> list[DetectedEvent]

Get events by detector index.

Parameters:

Name Type Description Default
index int

Detector index (0-based, in order of add_event_detector calls).

 required

Returns:

Type Description
list[DetectedEvent]

list[DetectedEvent]: Events from the specified detector.

events_by_name method descriptor 

events_by_name(name: str) -> list[DetectedEvent]

Get events by name.

Parameters:

Name Type Description Default
name str

Event name to filter by.

 required

Returns:

Type Description
list[DetectedEvent]

list[DetectedEvent]: Events matching the given name.

events_in_range method descriptor 

events_in_range(start: Epoch, end: Epoch) -> list[DetectedEvent]

Get events in time range.

Parameters:

Name Type Description Default
start Epoch

Start of time range.

 required
end Epoch

End of time range.

 required

Returns:

Type Description
list[DetectedEvent]

list[DetectedEvent]: Events within the given time range.

generate_uuid method descriptor 

generate_uuid() -> Any

Generate a new UUID and set it in-place (mutating).

get_covariance_interpolation_method method descriptor 

get_covariance_interpolation_method() -> CovarianceInterpolationMethod

Get the current covariance interpolation method.

Returns:

Name Type Description
CovarianceInterpolationMethod CovarianceInterpolationMethod

The current covariance interpolation method.

get_id method descriptor 

get_id() -> Any

Get the current numeric ID.

get_interpolation_method method descriptor 

get_interpolation_method() -> InterpolationMethod

Get the current interpolation method.

Returns:

Name Type Description
InterpolationMethod InterpolationMethod

The current interpolation method.

get_name method descriptor 

get_name() -> Any

Get the current name.

get_uuid method descriptor 

get_uuid() -> Any

Get the current UUID.

initial_state method descriptor 

initial_state() -> ndarray

Get initial state vector.

latest_event method descriptor 

latest_event() -> Union[DetectedEvent, None]

Get latest detected event, if any.

Returns:

Type Description
Union[DetectedEvent, None]

DetectedEvent or None: The most recently detected event.

params method descriptor 

params() -> Union[ndarray, None]

Get the parameter vector supplied at construction.

These are the force-model / consider parameters passed to the dynamics, control input, and (via the estimation filters) measurement models.

Returns:

Type Description
Union[ndarray, None]

numpy.ndarray or None: Parameter vector, or None if no parameters were provided.

propagate_steps method descriptor 

propagate_steps(num_steps) -> Any

Propagate forward by specified number of steps.

Raises:

Type Description
Exception

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

propagate_to method descriptor 

propagate_to(target_epoch) -> Any

Propagate to a specific target epoch.

Raises:

Type Description
Exception

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

query_events method descriptor 

query_events() -> EventQuery

Create an event query builder for filtering detected events.

Returns an EventQuery that allows chainable filtering of detected events. Call .collect() on the query to get the final list of events.

Returns:

Name Type Description
EventQuery EventQuery

Query builder for filtering events
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import brahe as bh

# Get events from detector 0 within a time range
events = prop.query_events() \
    .by_detector_index(0) \
    .in_time_range(start, end) \
    .collect()

# Count events by name pattern
count = prop.query_events() \
    .by_name_contains("Altitude") \
    .count()

# Combined filters
events = prop.query_events() \
    .by_detector_index(1) \
    .in_time_range(start, end) \
    .collect()

reset method descriptor 

reset() -> Any

Reset propagator to initial conditions.

reset_termination method descriptor 

reset_termination() -> Any

Reset the termination flag to allow continued propagation.

sensitivity method descriptor 

sensitivity() -> Any

Get current sensitivity matrix if enabled.

set_covariance_interpolation_method method descriptor 

set_covariance_interpolation_method(method: CovarianceInterpolationMethod) -> Any

Set the covariance interpolation method in-place.

Parameters:

Name Type Description Default
method CovarianceInterpolationMethod

The covariance interpolation method to use.

 required

set_eviction_policy_max_age method descriptor 

set_eviction_policy_max_age(max_age) -> Any

Set trajectory eviction policy based on maximum age.

set_eviction_policy_max_size method descriptor 

set_eviction_policy_max_size(max_size) -> Any

Set trajectory eviction policy based on maximum size.

set_id method descriptor 

set_id(id: Union[int, None]) -> Any

Set the numeric ID in-place (mutating).

Parameters:

Name Type Description Default
id int or None

Numeric ID to assign, or None to clear.

 required

set_identity method descriptor 

set_identity(name: Union[str, None], uuid_str: Union[str, None], id: Union[int, None]) -> Any

Set all identity fields in-place (mutating).

Parameters:

Name Type Description Default
name str or None

Optional name to assign.

 required
uuid_str str or None

Optional UUID string to assign.

 required
id int or None

Optional numeric ID to assign.

 required

set_interpolation_method method descriptor 

set_interpolation_method(method: InterpolationMethod) -> Any

Set the interpolation method in-place.

Parameters:

Name Type Description Default
method InterpolationMethod

The interpolation method to use.

 required

set_name method descriptor 

set_name(name: Union[str, None]) -> Any

Set the name in-place (mutating).

Parameters:

Name Type Description Default
name str or None

Name to assign, or None to clear.

 required

set_trajectory_mode method descriptor 

set_trajectory_mode(mode: TrajectoryMode) -> Any

Set the trajectory storage mode.

Parameters:

Name Type Description Default
mode TrajectoryMode

The trajectory storage mode.

 required
Example 
1
2
3
4
import brahe as bh

prop = bh.NumericalPropagator(epoch, state, dynamics, config)
prop.set_trajectory_mode(bh.TrajectoryMode.DISABLED)

set_uuid method descriptor 

set_uuid(uuid_str: Union[str, None]) -> Any

Set the UUID in-place (mutating).

Parameters:

Name Type Description Default
uuid_str str or None

UUID string to assign, or None to clear.

 required

state method descriptor 

state(epoch) -> ndarray

Compute state at a specific epoch.

states method descriptor 

states(epochs: list[Epoch]) -> ndarray

Compute states at multiple epochs.

Parameters:

Name Type Description Default
epochs list[Epoch]

List of epochs for state computation.

 required

Returns:

Type Description
ndarray

list[numpy.ndarray]: List of state vectors in the propagator's current output format.

step method descriptor 

step() -> Any

Step forward by the default step size.

Raises:

Type Description
Exception

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

step_by method descriptor 

step_by(step_size) -> Any

Step forward by a specified time duration.

Raises:

Type Description
Exception

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

step_past method descriptor 

step_past(target_epoch) -> Any

Step past a specified target epoch.

Raises:

Type Description
Exception

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

stm method descriptor 

stm() -> Any

Get current STM if enabled.

terminated method descriptor 

terminated() -> bool

Check if propagator is terminated due to a terminal event.

Returns:

Name Type Description
bool bool

True if propagation was stopped by a terminal event.

trajectory_mode method descriptor 

trajectory_mode() -> TrajectoryMode

Get the current trajectory storage mode.

Returns:

Name Type Description
TrajectoryMode TrajectoryMode

The current trajectory storage mode.
Example 
1
2
3
4
5
import brahe as bh

prop = bh.NumericalPropagator(epoch, state, dynamics, config)
mode = prop.trajectory_mode()
print(f"Mode: {mode}")

with_covariance_interpolation_method method descriptor 

with_covariance_interpolation_method(method: CovarianceInterpolationMethod) -> Any

Set the covariance interpolation method using builder pattern. Note: Returns None as Python doesn't support returning mutable self with borrowed args. Use method chaining via separate calls or use set_covariance_interpolation_method instead.

Parameters:

Name Type Description Default
method CovarianceInterpolationMethod

The covariance interpolation method to use.

 required

with_id method descriptor 

with_id(id) -> Any

Set the numeric ID and return self.

with_identity method descriptor 

with_identity(name: Union[str, None], uuid_str: Union[str, None], id: Union[int, None]) -> NumericalPropagator

Set all identity fields at once and return self (consuming constructor pattern).

Parameters:

Name Type Description Default
name str or None

Optional name to assign.

 required
uuid_str str or None

Optional UUID string to assign.

 required
id int or None

Optional numeric ID to assign.

 required

Returns:

Name Type Description
NumericalPropagator NumericalPropagator

Self with identity set.

with_interpolation_method method descriptor 

with_interpolation_method(method: InterpolationMethod) -> Any

Set the interpolation method using builder pattern. Note: Returns None as Python doesn't support returning mutable self with borrowed args. Use method chaining via separate calls or use set_interpolation_method instead.

Parameters:

Name Type Description Default
method InterpolationMethod

The interpolation method to use.

 required

with_name method descriptor 

with_name(name) -> Any

Set the name and return self.

with_new_uuid method descriptor 

with_new_uuid() -> Any

Generate a new UUID, set it, and return self.

with_uuid method descriptor 

with_uuid(uuid_str) -> Any

Set the UUID and return self.

NumericalPropagatorBuilder 

NumericalPropagatorBuilder()

Builder for [NumericalPropagator].

Created by NumericalPropagator.builder(), which takes the three required inputs (epoch, state, dynamics). Optional inputs are provided through chained setters and default to None (NumericalPropagationConfig.default() for the propagation configuration). build() validates the configuration and constructs the propagator; the builder is single-use, and calling build() a second time raises RuntimeError.

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

omega = 1.0
def sho_dynamics(t, state, params):
    return np.array([state[1], -omega**2 * state[0]])

epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([1.0, 0.0])

prop = (
    bh.NumericalPropagator.builder(epoch, state, sho_dynamics)
    .propagation_config(bh.NumericalPropagationConfig.default())
    .initial_covariance(np.eye(2))
    .build()
)

Initialize instance.

build method descriptor 

build() -> NumericalPropagator

Construct the propagator from the accumulated configuration.

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

Returns:

Name Type Description
NumericalPropagator NumericalPropagator

Initialized propagator ready for propagation.

Raises:

Type Description
RuntimeError

If the builder was already consumed by a prior build() call, or if sensitivity propagation is enabled but no parameter vector was provided.

control_input method descriptor 

control_input(control: callable) -> NumericalPropagatorBuilder

Set a continuous control-input function that adds a perturbation to the dynamics output.

Parameters:

Name Type Description Default
control callable

Control function returning a perturbation vector matching the state dimension. Signature: f(t, state, params) -> control_perturbation.

 required

Returns:

Name Type Description
NumericalPropagatorBuilder NumericalPropagatorBuilder

The builder, for method chaining.

initial_covariance method descriptor 

initial_covariance(covariance: ndarray) -> NumericalPropagatorBuilder

Set an initial covariance matrix P0, which also enables STM propagation.

Parameters:

Name Type Description Default
covariance ndarray

Initial covariance matrix. Must be square with dimension matching the state size.

 required

Returns:

Name Type Description
NumericalPropagatorBuilder NumericalPropagatorBuilder

The builder, for method chaining.

params method descriptor 

params(params: ndarray) -> NumericalPropagatorBuilder

Set the parameter vector consumed by the dynamics function, control input, and (when enabled) sensitivity propagation.

Parameters:

Name Type Description Default
params ndarray

Parameter vector.

 required

Returns:

Name Type Description
NumericalPropagatorBuilder NumericalPropagatorBuilder

The builder, for method chaining.

propagation_config method descriptor 

propagation_config(config: NumericalPropagationConfig) -> NumericalPropagatorBuilder

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

The builder, for method chaining.

See Also