Skip to content

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: Any, state: Any, propagation_config: Any, force_config: Any, params: Any = None, initial_covariance: Any = None, additional_dynamics: Any = None, control_input: Any = 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 - Solid Earth tides

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 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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.

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 
1
2
3
4
5
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)

builder staticmethod 

builder(epoch: Epoch, state: ndarray, force_config: ForceModelConfig) -> NumericalOrbitPropagatorBuilder

Create a builder for constructing a numerical orbit propagator.

The builder takes the three required inputs directly; optional inputs (propagation config, params, additional dynamics, 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 in ECI Cartesian [x, y, z, vx, vy, vz] (meters, m/s). Can be 6D or 6+N dimensional for extended state.

 required
force_config ForceModelConfig

Force model configuration.

 required

Returns:

Name Type Description
NumericalOrbitPropagatorBuilder NumericalOrbitPropagatorBuilder

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

bh.initialize_eop()

epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7612.0, 0.0])

prop = (
    bh.NumericalOrbitPropagator.builder(epoch, state, bh.ForceModelConfig())
    .initial_covariance(np.eye(6))
    .build()
)

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_epoch method descriptor 

current_epoch() -> Any

Get current epoch.

current_params method descriptor 

current_params() -> Union[ndarray, None]

Get current parameter vector.

Returns:

Type Description
Union[ndarray, None]

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

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.
Example 
1
2
3
4
5
6
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() -> 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: int) -> Any

Propagate forward by specified number of steps.

Parameters:

Name Type Description Default
num_steps int

Number of steps to take.

 required

Raises:

Type Description
Exception

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

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

Raises:

Type Description
Exception

Propagates the original exception raised by an additional-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.

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

sensitivity method descriptor 

sensitivity() -> Union[ndarray, None]

Get current sensitivity matrix if enabled.

Returns:

Type Description
Union[ndarray, None]

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

sensitivity_at method descriptor 

sensitivity_at(epoch: Epoch) -> Union[ndarray, None]

Get sensitivity matrix at a specific epoch.

Parameters:

Name Type Description Default
epoch Epoch

Target epoch for sensitivity query.

 required

Returns:

Type Description
Union[ndarray, None]

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_bcbf method descriptor 

state_bcbf(epoch: Epoch) -> ndarray

Get the state at the given epoch in the central body's body-centered body-fixed (BCBF) frame (ITRF for an Earth-centered propagator, LFPA for a Moon-centered one, MCMF for Mars, the configured fixed frame for a custom body).

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 the central body's
ndarray

body-fixed frame.

Raises:

Type Description
RuntimeError

If epoch is outside the propagator's stored trajectory, or the central body has no body-fixed frame (EMB/SSB barycenters, custom bodies without a configured frame).

state_bci method descriptor 

state_bci(epoch: Epoch) -> ndarray

Get the state at the given epoch in the central body's body-centered inertial (BCI) frame (GCRF for an Earth-centered propagator, LCI for a Moon-centered one, MCI for Mars, etc.).

This is the state the integrator actually propagates: no central-body offset or axis rotation is applied. state_eci always returns an Earth-centered state regardless of the propagator's central body; use this method to get the state in its native frame instead, which avoids an Earth round trip for non-Earth propagators.

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 the central body's
ndarray

inertial frame.

Raises:

Type Description
RuntimeError

If epoch is outside the propagator's stored trajectory and does not match the current 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_in_frame method descriptor 

state_in_frame(frame: CelestialFrame, epoch: Epoch) -> ndarray

Compute the state at the given epoch in an arbitrary reference frame.

Converts directly from this propagator's own central body's inertial frame, avoiding an unnecessary Earth round trip for a lunar/Martian propagator.

Parameters:

Name Type Description Default
frame CelestialFrame

Reference frame to express the state in.

 required
epoch Epoch

Target epoch for state computation.

 required

Returns:

Type Description
ndarray

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

Raises:

Type Description
RuntimeError

If the state cannot be computed or the frame conversion fails.

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_bcbf method descriptor 

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

Compute states at multiple epochs in the propagator's central body's body-centered body-fixed (BCBF) frame.

Parameters:

Name Type Description Default
epochs list[Epoch]

List of epochs for state computation.

 required

Returns:

Type Description
ndarray

list[numpy.ndarray]: List of BCBF state vectors [x, y, z, vx, vy, vz] (meters, m/s).

states_bci method descriptor 

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

Compute states at multiple epochs in the propagator's central body's body-centered inertial (BCI) frame.

Parameters:

Name Type Description Default
epochs list[Epoch]

List of epochs for state computation.

 required

Returns:

Type Description
ndarray

list[numpy.ndarray]: List of BCI state vectors [x, y, z, vx, vy, vz] (meters, m/s).

states_ecef method descriptor 

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

Compute states at multiple epochs in ECEF coordinates.

Parameters:

Name Type Description Default
epochs list[Epoch]

List of epochs for state computation.

 required

Returns:

Type Description
ndarray

list[numpy.ndarray]: List of ECEF state vectors.

states_eci method descriptor 

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

Compute states at multiple epochs in ECI coordinates.

Parameters:

Name Type Description Default
epochs list[Epoch]

List of epochs for state computation.

 required

Returns:

Type Description
ndarray

list[numpy.ndarray]: List of ECI state vectors.

states_eme2000 method descriptor 

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

Compute states at multiple epochs in EME2000 coordinates.

Parameters:

Name Type Description Default
epochs list[Epoch]

List of epochs for state computation.

 required

Returns:

Type Description
ndarray

list[numpy.ndarray]: List of EME2000 state vectors.

states_gcrf method descriptor 

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

Compute states at multiple epochs in GCRF coordinates.

Parameters:

Name Type Description Default
epochs list[Epoch]

List of epochs for state computation.

 required

Returns:

Type Description
ndarray

list[numpy.ndarray]: List of GCRF state vectors.

states_in_frame method descriptor 

states_in_frame(frame: CelestialFrame, epochs: list[Epoch]) -> ndarray

Compute states at multiple epochs expressed in an arbitrary reference frame, converting from the propagator's native central-body frame.

Parameters:

Name Type Description Default
frame CelestialFrame

The reference frame to express the states in.

 required
epochs list[Epoch]

List of epochs for state computation.

 required

Returns:

Type Description
ndarray

list[numpy.ndarray]: List of state vectors [x, y, z, vx, vy, vz] in frame (meters, m/s).

states_itrf method descriptor 

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

Compute states at multiple epochs in ITRF coordinates.

Parameters:

Name Type Description Default
epochs list[Epoch]

List of epochs for state computation.

 required

Returns:

Type Description
ndarray

list[numpy.ndarray]: List of ITRF state vectors.

states_koe_mean method descriptor 

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

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
ndarray

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

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
ndarray

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

step method descriptor 

step() -> Any

Step forward by the default step size.

Raises:

Type Description
Exception

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

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

Raises:

Type Description
Exception

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

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

Raises:

Type Description
Exception

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

stm method descriptor 

stm() -> Union[ndarray, None]

Get current STM (State Transition Matrix) if enabled.

Returns:

Type Description
Union[ndarray, None]

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) -> Union[ndarray, None]

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
Union[ndarray, None]

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.

NumericalOrbitPropagatorBuilder 

NumericalOrbitPropagatorBuilder()

Builder for [NumericalOrbitPropagator].

Created by NumericalOrbitPropagator.builder(), which takes the three required inputs (epoch, state, force_config). 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
import brahe as bh
import numpy as np

bh.initialize_eop()

epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7612.0, 0.0])

prop = (
    bh.NumericalOrbitPropagator.builder(epoch, state, bh.ForceModelConfig())
    .propagation_config(bh.NumericalPropagationConfig.default())
    .initial_covariance(np.eye(6))
    .build()
)

Initialize instance.

additional_dynamics method descriptor 

additional_dynamics(dynamics: callable) -> NumericalOrbitPropagatorBuilder

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

Parameters:

Name Type Description Default
dynamics callable

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

 required

Returns:

Name Type Description
NumericalOrbitPropagatorBuilder NumericalOrbitPropagatorBuilder

The builder, for method chaining.

build method descriptor 

build() -> NumericalOrbitPropagator

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

Initialized propagator ready for propagation.

Raises:

Type Description
RuntimeError

If the builder was already consumed by a prior build() call, or if the force model references parameter indices but no parameter vector was provided.
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) -> NumericalOrbitPropagatorBuilder

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

Parameters:

Name Type Description Default
control callable

Control function returning a 3D acceleration perturbation. Signature: f(t, state, params) -> acceleration.

 required

Returns:

Name Type Description
NumericalOrbitPropagatorBuilder NumericalOrbitPropagatorBuilder

The builder, for method chaining.

initial_covariance method descriptor 

initial_covariance(covariance: ndarray) -> NumericalOrbitPropagatorBuilder

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

The builder, for method chaining.

params method descriptor 

params(params: ndarray) -> NumericalOrbitPropagatorBuilder

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

Required when the force model references parameter indices for drag or SRP.

Parameters:

Name Type Description Default
params ndarray

Parameter vector.

 required

Returns:

Name Type Description
NumericalOrbitPropagatorBuilder NumericalOrbitPropagatorBuilder

The builder, for method chaining.

propagation_config method descriptor 

propagation_config(config: NumericalPropagationConfig) -> NumericalOrbitPropagatorBuilder

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

The builder, for method chaining.

See Also