NumericalOrbitPropagator¶

High-fidelity numerical orbit propagator with built-in force models. The NumericalOrbitPropagator integrates orbital dynamics equations using configurable integrators and force models including gravity harmonics, atmospheric drag, solar radiation pressure, and third-body perturbations.

Note

For conceptual explanations and usage examples, see Numerical Propagation in the User Guide.

NumericalOrbitPropagator ¶

NumericalOrbitPropagator(epoch: Epoch, state: ndarray, propagation_config: NumericalPropagationConfig, force_config: ForceModelConfig, params: Union[ndarray, None] = None, initial_covariance: Union[ndarray, None] = None, additional_dynamics: Union[callable, None] = None, control_input: Union[callable, None] = None)

High-fidelity numerical orbit propagator with configurable force models.

This propagator uses numerical integration with built-in orbital force models: - Gravity (point mass or spherical harmonic) - Atmospheric drag (Harris-Priester, NRLMSISE-00, or exponential) - Solar radiation pressure with eclipse modeling - Third-body perturbations (Sun, Moon, planets) - Relativistic corrections

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Initial epoch.	required
`state`	`ndarray`	Initial state vector in ECI Cartesian [x, y, z, vx, vy, vz] (meters, m/s). Can be 6D or 6+N dimensional for extended state.	required
`propagation_config`	`NumericalPropagationConfig`	Propagation configuration.	required
`force_config`	`ForceModelConfig`	Force model configuration.	required
`params`	`ndarray or None`	Parameter vector [mass, drag_area, Cd, srp_area, Cr, ...]. Required if force_config references parameter indices.	`None`
`initial_covariance`	`ndarray or None`	Optional 6x6 initial covariance matrix (enables STM).	`None`
`additional_dynamics`	`callable or None`	Optional function for extended state dynamics. Signature: f(t, state, params) -> derivative.	`None`
`control_input`	`callable or None`	Optional control input function for thrust accelerations. Signature: f(t, state, params) -> 3D acceleration vector.	`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 (6 for basic, 6+N for extended)
`step_size`	`float`	Current integration step size in seconds
`trajectory`	`OrbitTrajectory`	Accumulated trajectory states

Example

import brahe as bh
import numpy as np

bh.initialize_eop()

# Create initial state (ECI Cartesian)
epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
oe = np.array([bh.R_EARTH + 500e3, 0.01, 97.8, 15.0, 30.0, 45.0])
state = bh.state_koe_to_eci(oe, bh.AngleFormat.DEGREES)

# Parameters: [mass, drag_area, Cd, srp_area, Cr]
params = np.array([1000.0, 10.0, 2.2, 10.0, 1.3])

# Create propagator with default configs
prop = bh.NumericalOrbitPropagator(
    epoch, state,
    bh.NumericalPropagationConfig.default(),
    bh.ForceModelConfig.default(),
    params
)

# Propagate
prop.propagate_to(epoch + 3600.0)  # 1 hour
print(f"Final state: {prop.current_state()}")

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: OrbitTrajectory

Get accumulated trajectory.

Returns:

Name	Type	Description
`OrbitTrajectory`	`OrbitTrajectory`	The accumulated trajectory.

trajectory_mode `property` ¶

trajectory_mode: TrajectoryMode

Get current trajectory storage mode.

Returns:

Name	Type	Description
`TrajectoryMode`	`TrajectoryMode`	Current trajectory mode.

add_event_detector `method descriptor` ¶

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

Add an event detector to this propagator.

Parameters:

Name	Type	Description	Default
`event`	`TimeEvent or ValueEvent or BinaryEvent or AltitudeEvent`	Event detector	required

Example

import brahe as bh

prop = bh.NumericalOrbitPropagator.from_eci(epoch, state)
event = bh.TimeEvent(epoch + 1800.0, "30 min 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: Epoch) -> ndarray

Get covariance at a specific epoch.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: Covariance matrix at the requested epoch.

covariance_gcrf `method descriptor` ¶

covariance_gcrf(epoch: Epoch) -> ndarray

Get covariance at a specific epoch in GCRF frame.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: Covariance matrix in GCRF frame.

covariance_rtn `method descriptor` ¶

covariance_rtn(epoch: Epoch) -> ndarray

Get covariance at a specific epoch in RTN (Radial-Tangential-Normal) frame.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: Covariance matrix in RTN frame.

current_params `method descriptor` ¶

current_params() -> ndarray

Get current parameter vector.

Returns:

Type	Description
`ndarray`	numpy.ndarray or None: Current parameter vector, or None if no params.

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.

Example

import brahe as bh

prop.propagate_to(epoch + 3600.0)
events = prop.event_log()
for event in events:
    print(f"Event '{event.name}' at {event.window_open}")

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

events_by_detector_index_in_range(index: int, start: Epoch, end: Epoch) -> list[DetectedEvent]

Get events by detector index within a time range.

Parameters:

Name	Type	Description	Default
`index`	`int`	Detector index (0-based, in order of add_event_detector calls).	required
`start`	`Epoch`	Start of time range (inclusive).	required
`end`	`Epoch`	End of time range (inclusive).	required

Returns:

Type	Description
`list[DetectedEvent]`	list[DetectedEvent]: Events from the specified detector within the time range.

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

events_by_name_in_range(name_pattern: str, start: Epoch, end: Epoch) -> list[DetectedEvent]

Get events by name pattern within a time range.

Parameters:

Name	Type	Description	Default
`name_pattern`	`str`	Substring to search for in event names.	required
`start`	`Epoch`	Start of time range (inclusive).	required
`end`	`Epoch`	End of time range (inclusive).	required

Returns:

Type	Description
`list[DetectedEvent]`	list[DetectedEvent]: Events matching the name pattern within the time range.

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.

from_eci `builtin` ¶

from_eci(epoch: Epoch, state: ndarray, params: Union[ndarray, None] = None, force_config: Union[ForceModelConfig, None] = None) -> NumericalOrbitPropagator

Create a propagator from ECI Cartesian state with simplified configuration.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Initial epoch.	required
`state`	`ndarray`	Initial ECI Cartesian state [x, y, z, vx, vy, vz].	required
`params`	`ndarray or None`	Parameter vector.	`None`
`force_config`	`ForceModelConfig or None`	Force model config (default if None).	`None`

Returns:

Name	Type	Description
`NumericalOrbitPropagator`	`NumericalOrbitPropagator`	New propagator instance.

get_covariance_interpolation_method `method descriptor` ¶

get_covariance_interpolation_method() -> CovarianceInterpolationMethod

Get current interpolation method for covariance queries.

Returns:

Name	Type	Description
`CovarianceInterpolationMethod`	`CovarianceInterpolationMethod`	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 current interpolation method for state trajectory queries.

Returns:

Name	Type	Description
`InterpolationMethod`	`InterpolationMethod`	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: int) -> Any

Propagate forward by specified number of steps.

Parameters:

Name	Type	Description	Default
`num_steps`	`int`	Number of steps to take.	required

propagate_to `method descriptor` ¶

propagate_to(target_epoch: Epoch) -> Any

Propagate to a specific target epoch.

Parameters:

Name	Type	Description	Default
`target_epoch`	`Epoch`	The epoch to propagate to.	required

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.

After calling this, propagation can continue even if it was previously stopped by a terminal event.

sensitivity `method descriptor` ¶

sensitivity() -> ndarray

Get current sensitivity matrix if enabled.

Returns:

Type	Description
`ndarray`	numpy.ndarray or None: The current sensitivity (n x p matrix), or None if not enabled.

sensitivity_at `method descriptor` ¶

sensitivity_at(epoch: Epoch) -> ndarray

Get sensitivity matrix at a specific epoch.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch for sensitivity query.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray or None: The sensitivity matrix at the requested epoch, or None if not enabled.

set_covariance_interpolation_method `method descriptor` ¶

set_covariance_interpolation_method(method: CovarianceInterpolationMethod) -> Any

Set interpolation method for covariance queries.

Parameters:

Name	Type	Description	Default
`method`	`CovarianceInterpolationMethod`	Interpolation method for covariance.	required

set_eviction_policy_max_age `method descriptor` ¶

set_eviction_policy_max_age(max_age: float) -> Any

Set trajectory eviction policy based on maximum age.

Parameters:

Name	Type	Description	Default
`max_age`	`float`	Maximum age in seconds to keep states in trajectory.	required

set_eviction_policy_max_size `method descriptor` ¶

set_eviction_policy_max_size(max_size: int) -> Any

Set trajectory eviction policy based on maximum size.

Parameters:

Name	Type	Description	Default
`max_size`	`int`	Maximum number of states to keep in trajectory.	required

set_id `method descriptor` ¶

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

Set propagator numeric ID (mutating).

Parameters:

Name	Type	Description	Default
`id`	`int or None`	New numeric ID for the propagator.	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 at once (mutating).

Parameters:

Name	Type	Description	Default
`name`	`str or None`	New name.	required
`uuid_str`	`str or None`	New UUID string.	required
`id`	`int or None`	New numeric ID.	required

Raises:

Type	Description
`ValueError`	If the UUID string is invalid.

set_interpolation_method `method descriptor` ¶

set_interpolation_method(method: InterpolationMethod) -> Any

Set interpolation method for state trajectory queries.

Parameters:

Name	Type	Description	Default
`method`	`InterpolationMethod`	Interpolation method to use.	required

set_name `method descriptor` ¶

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

Set propagator name (mutating).

Parameters:

Name	Type	Description	Default
`name`	`str or None`	New name for the propagator.	required

set_trajectory_mode `method descriptor` ¶

set_trajectory_mode(mode: TrajectoryMode) -> Any

Set trajectory storage mode.

Parameters:

Name	Type	Description	Default
`mode`	`TrajectoryMode`	The new trajectory mode.	required

set_uuid `method descriptor` ¶

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

Set propagator UUID (mutating).

Parameters:

Name	Type	Description	Default
`uuid_str`	`str or None`	New UUID string for the propagator.	required

Raises:

Type	Description
`ValueError`	If the UUID string is invalid.

state `method descriptor` ¶

state(epoch: Epoch) -> ndarray

Compute state at a specific epoch.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch for state computation.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: State vector at the requested epoch.

state_ecef `method descriptor` ¶

state_ecef(epoch: Epoch) -> ndarray

Compute state at a specific epoch in ECEF coordinates.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch for state computation.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: State vector [x, y, z, vx, vy, vz] in ECEF frame.

state_eci `method descriptor` ¶

state_eci(epoch: Epoch) -> ndarray

Compute state at a specific epoch in ECI coordinates.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch for state computation.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: State vector [x, y, z, vx, vy, vz] in ECI frame.

state_eme2000 `method descriptor` ¶

state_eme2000(epoch: Epoch) -> ndarray

Compute state at a specific epoch in EME2000 coordinates.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch for state computation.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: State vector [x, y, z, vx, vy, vz] in EME2000 frame.

state_gcrf `method descriptor` ¶

state_gcrf(epoch) -> ndarray

Compute state at a specific epoch in GCRF coordinates.

state_itrf `method descriptor` ¶

state_itrf(epoch) -> ndarray

Compute state at a specific epoch in ITRF coordinates.

state_koe_mean `method descriptor` ¶

state_koe_mean(epoch: Epoch, angle_format: AngleFormat) -> ndarray

Compute state as mean Keplerian elements at a specific epoch.

Mean elements are orbit-averaged elements that remove short-period and long-period J2 perturbations using first-order Brouwer-Lyddane theory.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch.	required
`angle_format`	`AngleFormat`	Format for angular elements.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: Mean Keplerian elements [a, e, i, Ω, ω, M].

state_koe_osc `method descriptor` ¶

state_koe_osc(epoch: Epoch, angle_format: AngleFormat) -> ndarray

Compute state as osculating Keplerian elements at a specific epoch.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch.	required
`angle_format`	`AngleFormat`	Format for angular elements.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: Osculating Keplerian elements [a, e, i, Ω, ω, M].

states_koe_mean `method descriptor` ¶

states_koe_mean(epochs: list[Epoch], angle_format: AngleFormat) -> List

Compute states as mean Keplerian elements at multiple epochs.

Mean elements are orbit-averaged elements that remove short-period and long-period J2 perturbations using first-order Brouwer-Lyddane theory.

Parameters:

Name	Type	Description	Default
`epochs`	`list[Epoch]`	List of target epochs.	required
`angle_format`	`AngleFormat`	Format for angular elements.	required

Returns:

Type	Description
`List`	list[numpy.ndarray]: List of mean Keplerian elements [a, e, i, Ω, ω, M].

states_koe_osc `method descriptor` ¶

states_koe_osc(epochs: list[Epoch], angle_format: AngleFormat) -> List

Compute states as osculating Keplerian elements at multiple epochs.

Parameters:

Name	Type	Description	Default
`epochs`	`list[Epoch]`	List of target epochs.	required
`angle_format`	`AngleFormat`	Format for angular elements.	required

Returns:

Type	Description
`List`	list[numpy.ndarray]: List of osculating Keplerian elements [a, e, i, Ω, ω, M].

step `method descriptor` ¶

step() -> Any

Step forward by the default step size.

step_by `method descriptor` ¶

step_by(step_size: float) -> Any

Step forward by a specified time duration.

Parameters:

Name	Type	Description	Default
`step_size`	`float`	Time step in seconds.	required

step_past `method descriptor` ¶

step_past(target_epoch: Epoch) -> Any

Step past a specified target epoch.

Parameters:

Name	Type	Description	Default
`target_epoch`	`Epoch`	The epoch to step past.	required

stm `method descriptor` ¶

stm() -> ndarray

Get current STM (State Transition Matrix) if enabled.

Returns:

Type	Description
`ndarray`	numpy.ndarray or None: The current STM (n x n matrix), or None if STM not enabled.

stm_at `method descriptor` ¶

stm_at(epoch: Epoch) -> ndarray

Get STM (State Transition Matrix) at a specific epoch.

Parameters:

Name	Type	Description	Default
`epoch`	`Epoch`	Target epoch for STM query.	required

Returns:

Type	Description
`ndarray`	numpy.ndarray or None: The STM at the requested epoch, or None if STM not 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.

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

Set all identity fields and return self (builder pattern).

Parameters:

Name	Type	Description	Default
`name`	`str or None`	New name.	required
`uuid_str`	`str or None`	New UUID string.	required
`id`	`int or None`	New numeric ID.	required

Returns:

Name	Type	Description
`NumericalOrbitPropagator`	`NumericalOrbitPropagator`	Self for method chaining.

Raises:

Type	Description
`ValueError`	If the UUID string is invalid.

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.

NumericalOrbitPropagator¶