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: Epoch, state: ndarray, dynamics: callable, propagation_config: NumericalPropagationConfig, params: Union[ndarray, None] = None, initial_covariance: Union[ndarray, None] = 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.

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
`propagation_config`	`NumericalPropagationConfig`	Propagation configuration.	required
`params`	`ndarray or None`	Optional parameter vector for the dynamics function.	`None`
`initial_covariance`	`ndarray or None`	Optional initial covariance matrix (enables STM).	`None`

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

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.

current_epoch `property` ¶

current_epoch: Any

Get current epoch.

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

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)

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_state `method descriptor` ¶

current_state() -> ndarray

Get current state vector.

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

Get latest detected event, if any.

Returns:

Type	Description
`DetectedEvent`	DetectedEvent or None: The most recently detected event.

propagate_steps `method descriptor` ¶

propagate_steps(num_steps) -> Any

Propagate forward by specified number of steps.

propagate_to `method descriptor` ¶

propagate_to(target_epoch) -> Any

Propagate to a specific target epoch.

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

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

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.

step `method descriptor` ¶

step() -> Any

Step forward by the default step size.

step_by `method descriptor` ¶

step_by(step_size) -> Any

Step forward by a specified time duration.

step_past `method descriptor` ¶

step_past(target_epoch) -> Any

Step past a specified target epoch.

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

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.

NumericalPropagator¶