Propagation

propagation

BatchIntegrator

Batched numerical Gauss-Jackson 8 propagator.

Holds a satellite roster under a single PerformancePriority preset and emits one Ephemeris per satellite over a requested window. CPU and GPU backends are selected by DevicePreference; results are returned in the same order as add_satellite calls.

The GPU backend (when feature = "gpu" is enabled at build time and a wgpu adapter is available) supports gravity, third-body Sun/Moon, cannonball SRP with cylindrical shadow, and NRLMSISE-00 atmospheric drag. Other drag models (Harris-Priester, Jacchia-Bowman 2008, Jacchia-Roberts 71) fall back only under DevicePreference.Auto and raise GpuUnsupportedSetting under DevicePreference.GPU.

is_empty property

True when no satellites have been added.

Returns:

Type	Description
bool	Whether the batch is empty.

len property

Number of satellites currently in the batch.

Returns:

Type	Description
int	Satellite count.

__init__(priority, drag=True)

Creates a new BatchIntegrator.

Parameters:

Name	Type	Description	Default
priority	PerformancePriority	Preset for force-model defaults (Precision / Balanced / Speed). Drag, SRP, third bodies, gravity order, and step size all derive from this preset.	required
drag	bool	Whether to include drag in the force model. Defaults to True. Set to False for high-altitude orbits where drag is negligible — disabling drag widens GPU eligibility because only NRLMSISE-00 is supported on GPU.	True

add_satellite(satellite)

Append a satellite to the batch.

Parameters:

Name	Type	Description	Default
satellite	Satellite	Satellite with a Cartesian state set.	required

Raises:

Type	Description
ValueError	If satellite.cartesian_state is None.

propagate_ephemeris(start, end, step, target_frame, device)

Propagate every satellite from start to end.

Parameters:

Name	Type	Description	Default
start	ModifiedJulianDate	Window start epoch.	required
end	ModifiedJulianDate	Window end epoch.	required
step	TimeSpan	Output sample cadence.	required
target_frame	ReferenceFrame	Frame for the output states.	required
device	DevicePreference	Backend selector. Auto consults the GPU work-item threshold and the force-model settings to decide CPU vs GPU.	required

Returns:

Type	Description
Dict[str, Ephemeris]	One Ephemeris per satellite,
Dict[str, Ephemeris]	keyed by satellite id.

Raises:

Type	Description
RuntimeError	If every satellite returned an error. Partial success returns a dict containing only successful entries.

ForceModelSettings

Force-model configuration for the numerical Integrator.

Controls which perturbations are evaluated (gravity field, drag, SRP, third bodies) and the underlying physical models used for each. Build a default preset with ForceModelSettings(priority) keyed on a PerformancePriority, then override individual fields before passing the settings to IntegratorSettings.

Attributes:

Name	Type	Description
gravity_order	Optional[int]	Spherical-harmonic degree cap for the gravity field; None selects the gravity model's native maximum. When use_adaptive_gravity is True, an additional altitude-based cap is applied on top of this value.
use_adaptive_gravity	bool	Whether to apply the altitude-adaptive degree cap on top of gravity_order. True for all built-in presets.
include_tides	bool	Whether the IERS 2010 Step 1 solid Earth tide acceleration is summed into the force model.
include_drag	bool	Whether atmospheric drag is included in the force model.
use_srp	bool	Whether solar radiation pressure (SRP) is included.
use_shadow	bool	Whether the conical Earth-shadow model is applied to SRP (turning off SRP while the spacecraft is eclipsed).
atmosphere_radius	float	Outer radius of the drag-modelled atmosphere [km]. Drag is zero above this altitude.
third_bodies	List[CelestialBody]	Perturbing bodies whose accelerations are summed into the total force.
drag_model	DragModel	Atmospheric density model used when include_drag is True.
gravity_model	EarthGravityModel	Earth gravity model providing μ, equatorial radius, and the spherical-harmonic coefficient set.
central_body	CelestialBody	Central body for the two-body acceleration. Earth in standard configurations.
ephemeris_source	EphemerisSource	Source of planetary/lunar positions for third-body and SRP computations.
frame_transform_priority	PerformancePriority	Performance priority forwarded to frame-transform routines.

atmosphere_radius property writable

Outer radius of the drag-modelled atmosphere [km].

Drag is set to zero above this altitude.

Returns:

Type	Description
float	Atmosphere outer radius [km].

central_body property writable

Central body for the two-body acceleration.

Returns:

Type	Description
CelestialBody	Central body.

drag_model property writable

Atmospheric density model used when include_drag is True.

Returns:

Type	Description
DragModel	Atmospheric density model.

ephemeris_source property writable

Source of planetary/lunar positions for third-body and SRP computations.

Returns:

Type	Description
EphemerisSource	Ephemeris source.

frame_transform_priority property writable

Performance priority forwarded to frame-transform routines.

Returns:

Type	Description
PerformancePriority	Frame-transform priority.

gravity_model property writable

Earth gravity model providing μ, equatorial radius, and the spherical-harmonic coefficient set.

Returns:

Type	Description
EarthGravityModel	Earth gravity model.

gravity_order property writable

Spherical-harmonic degree cap for the gravity field [dimensionless].

None selects the gravity model's native maximum degree.

Returns:

Type	Description
Optional[int]	Degree cap, or None for the model maximum.

include_drag property writable

Whether atmospheric drag is included in the force model.

Returns:

Type	Description
bool	True if drag is included.

include_tides property writable

Whether the IERS 2010 solid Earth tide acceleration is included.

Returns:

Type	Description
bool	True if solid Earth tides are included.

third_bodies property writable

Perturbing third bodies whose accelerations are summed into the total force.

Returns:

Type	Description
List[CelestialBody]	List of perturbing bodies.

use_adaptive_gravity property writable

Whether to apply the altitude-adaptive degree cap on top of gravity_order.

Returns:

Type	Description
bool	True if altitude-adaptive gravity is enabled.

use_shadow property writable

Whether the conical Earth-shadow model is applied to SRP.

Returns:

Type	Description
bool	True if shadow modelling is applied.

use_srp property writable

Whether solar radiation pressure (SRP) is included.

Returns:

Type	Description
bool	True if SRP is included.

__init__(priority)

Build a force-model preset keyed on the requested performance priority.

Selects the drag model, gravity-order cap, and frame-transform priority that match the requested speed/accuracy trade-off. All presets enable drag, SRP, shadow, and Sun + Moon as third bodies.

Parameters:

Name	Type	Description	Default
priority	PerformancePriority	Speed/accuracy trade-off. Precision uses JB2008 + EGM96 to degree 36 with full IAU 2000A frames; Balanced and Speed drop to NRLMSISE-00 and lower gravity orders.	required

__repr__()

Returns ForceModelSettings(drag_model=…, gravity_order=…, include_drag=…).

Integrator

Single-satellite numerical orbit-propagation integrator.

Implements Gauss-Jackson 8, Dormand-Prince 5(4), and Runge-Kutta 4 over the equations of motion in TEME Cartesian coordinates. Force evaluation is driven by the ForceModelSettings inside the supplied IntegratorSettings: spherical-harmonic gravity, atmospheric drag, solar radiation pressure (with conical shadow), and third-body perturbations.

The integrator is stateful — Gauss-Jackson 8 caches its multi-step history across calls so that successive get_state_at_epoch calls on the same arc are cheap. Call invalidate_gj8_cache after any event that creates an acceleration discontinuity (e.g. a maneuver).

For large populations consider BatchIntegrator, which parallelises across multiple satellites and optionally offloads to the GPU backend.

Attributes:

Name	Type	Description
settings	IntegratorSettings	Read-only view of the integrator configuration supplied at construction.

settings property

Read-only view of the integrator configuration supplied at construction.

Returns:

Type	Description
IntegratorSettings	Integrator configuration.

__init__(settings)

Construct a new Integrator from the supplied settings.

The internal Gauss-Jackson cache and gravity workspace start unpopulated; they are filled lazily on the first propagation call.

Parameters:

Name	Type	Description	Default
settings	IntegratorSettings	Integrator and force-model configuration.	required

get_state_at_epoch(target_epoch, initial_state, satellite)

Propagate a Cartesian state from its epoch to target_epoch.

Converts the initial state to TEME, advances it with the configured integrator (Gauss-Jackson 8 for long arcs, single-step otherwise), and returns the result in the same reference frame as initial_state. Sub-nanosecond propagations are short-circuited as a frame round-trip.

The satellite's physical properties (mass, drag area, SRP area, drag coefficient, SRP coefficient) are extracted from satellite and forwarded to the force model. The satellite does not need to carry a pre-computed state; only its properties field is used.

Parameters:

Name	Type	Description	Default
target_epoch	ModifiedJulianDate	Epoch to propagate to.	required
initial_state	CartesianState	Initial state with epoch, position, and velocity [km, km/s].	required
satellite	Satellite	Satellite whose physical properties are forwarded to the force model (mass, drag, SRP parameters).	required

Returns:

Type	Description
CartesianState	Propagated state at target_epoch in the same reference frame
CartesianState	as initial_state [km, km/s].

Raises:

Type	Description
ValueError	If initial_state has no velocity.
RuntimeError	If the configured step size is non-finite or non-positive, a frame conversion fails, or any integrator step fails.

invalidate_gj8_cache()

Invalidate the GJ8 history cache, forcing a fresh startup on the next propagation call.

Call this after any event that creates an acceleration discontinuity (e.g. a maneuver, a drag-model switch), so the integrator does not carry stale history forward.

IntegratorSettings

Numerical integrator configuration for the Integrator.

Bundles the integrator algorithm, step-size policy, error tolerances, and the underlying ForceModelSettings. Build one with IntegratorSettings(priority) keyed on a PerformancePriority, or use IntegratorSettings.default() which is equivalent to PerformancePriority.Balanced.

Attributes:

Name	Type	Description
performance_priority	PerformancePriority	Speed/accuracy preset that drove the construction of this settings object.
integrator_type	IntegratorType	Numerical integration algorithm.
step_size	float	Upper bound on the integrator's internal step [s]. GJ8 picks an orbit-class step from the initial (r, v) — 15 s for eccentric orbits, 30 s for near-circular LEO/MEO, 240 s for near-circular GEO — and the actual step is min(class_step, step_size).
absolute_tolerance	float	Dormand-Prince 5(4) absolute error tolerance [km; km/s]. Only consulted by IntegratorType.DormandPrince54.
relative_tolerance	float	Dormand-Prince 5(4) relative error tolerance [dimensionless]. Only consulted by IntegratorType.DormandPrince54.
force_model	ForceModelSettings	Force-model configuration evaluated at each integrator stage.

absolute_tolerance property writable

Dormand-Prince 5(4) absolute error tolerance [km; km/s].

Only consulted by IntegratorType.DormandPrince54.

Returns:

Type	Description
float	Absolute tolerance [km; km/s].

force_model property writable

Force-model configuration evaluated at each integrator stage.

Returns:

Type	Description
ForceModelSettings	Force model configuration.

integrator_type property writable

Numerical integration algorithm.

Returns:

Type	Description
IntegratorType	Integration algorithm.

performance_priority property writable

Speed/accuracy preset that drove the construction of this settings object.

Returns:

Type	Description
PerformancePriority	Performance priority.

relative_tolerance property writable

Dormand-Prince 5(4) relative error tolerance [dimensionless].

Only consulted by IntegratorType.DormandPrince54.

Returns:

Type	Description
float	Relative tolerance [dimensionless].

step_size property writable

Upper bound on the integrator's internal step [s].

Returns:

Type	Description
float	Step size ceiling [s].

__init__(priority)

Build an integrator preset keyed on the requested performance priority.

Selects the integrator type, default step-size cap, error tolerances, and the matching ForceModelSettings for the requested speed/accuracy trade-off.

Parameters:

Name	Type	Description	Default
priority	PerformancePriority	Speed/accuracy trade-off forwarded to both the integrator and the underlying ForceModelSettings.	required

__repr__()

Returns IntegratorSettings(priority=…, step_size=…).

default() staticmethod

Build an integrator settings preset equivalent to PerformancePriority.Balanced.

Returns:

Type	Description
IntegratorSettings	Balanced preset.

Maneuver

A delta-V-driven maneuver specification.

Describes what delta-V to apply, in what direction, and when. Pass a Maneuver to the propagator's maneuver execution interface to apply it impulsively or as a finite burn.

For impulsive maneuvers the full magnitude is applied instantaneously at epoch. For finite burns the burn is centered on epoch with duration derived from the Tsiolkovsky rocket equation.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Center epoch of the maneuver [MJD]. For finite burns the burn is symmetric around this epoch (start = epoch − duration / 2).
direction	tuple[float, float, float]	Unit direction of the delta-V in reference_frame [dimensionless; x, y, z; normalized internally].
reference_frame	ReferenceFrame	Frame for the direction vector. Use TEME for inertial or RIC for radial/in-track/cross-track decomposition.
magnitude	float	Target delta-V magnitude [km/s].

direction property

Unit direction of the delta-V in reference_frame [dimensionless; x, y, z].

Returns:

Type	Description
Tuple[float, float, float]	Direction vector components (x, y, z) [dimensionless].

epoch property

Center epoch of the maneuver [MJD].

For finite burns the burn is centered on this epoch (start = epoch − duration / 2).

Returns:

Type	Description
ModifiedJulianDate	Maneuver epoch.

magnitude property

Target delta-V magnitude [km/s].

Returns:

Type	Description
float	Delta-V magnitude [km/s].

reference_frame property

Reference frame in which direction is expressed.

Returns:

Type	Description
ReferenceFrame	ReferenceFrame for the direction vector.

__init__(epoch, direction_x, direction_y, direction_z, reference_frame, magnitude)

Creates a new Maneuver.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Center epoch of the maneuver [MJD].	required
direction_x	float	X component of the delta-V direction in reference_frame [dimensionless; normalized internally].	required
direction_y	float	Y component of the delta-V direction [dimensionless].	required
direction_z	float	Z component of the delta-V direction [dimensionless].	required
reference_frame	ReferenceFrame	Frame for the direction vector.	required
magnitude	float	Target delta-V magnitude [km/s].	required

__repr__()

Returns Maneuver(magnitude=…, direction=[…, …, …]).

ManeuverResult

Result of executing a maneuver against a propagated state.

Returned by the propagator's maneuver execution interface. For impulsive maneuvers both fuel_consumed and duration are 0.0.

Attributes:

Name	Type	Description
state	CartesianState	Post-maneuver orbital state in the TEME frame.
fuel_consumed	float	Total propellant consumed during the burn [kg]. Zero for impulsive maneuvers without fuel tracking.
duration	float	Total burn duration [s]. Zero for impulsive maneuvers.

duration property

Total burn duration [s].

Returns:

Type	Description
float	Burn duration [s]. Zero for impulsive maneuvers.

fuel_consumed property

Total propellant consumed during the burn [kg].

Returns:

Type	Description
float	Fuel consumed [kg]. Zero for impulsive maneuvers.

state property

Post-maneuver orbital state in the TEME frame.

Returns:

Type	Description
CartesianState	CartesianState immediately after maneuver execution.

__repr__()

Returns ManeuverResult(fuel_consumed=…, duration=…).

PPT3

Analytic PPT3 propagator for TLE ephemeris-type-3 element sets.

Construct with PPT3(tle) from a parsed TLE whose ephemeris type is 3; then call get_state_at_epoch repeatedly. The propagator combines a Brouwer zonal secular model (J2, J2², J4) with an analytic lunisolar third-body model and optional tesseral resonance, producing states in the TEME reference frame.

PPT3 is the analytic sibling of SGP4: both consume Kozai mean elements (paired with WGS72 constants) and produce states in TEME. PPT3 covers the deep-space, resonant, and highly-eccentric orbits carried by type-3 TLEs from the AFSPC / HQ SpOC catalogue.

Note

This class only accepts TLEs with ephemeris type 3. For types 0, 2, and XP types use SGP4.

Attributes:

Name	Type	Description
tle	TLE	The TLE this propagator was constructed from.

tle property

The TLE this propagator was constructed from.

Returns:

Type	Description
TLE	Cloned TLE, preserving the original line-1 / line-2 catalogue
TLE	data.

__init__(tle)

Construct a PPT3 propagator from an ephemeris-type-3 TLE.

Parses the mean elements, recovers the Kozai semi-major axis, and precomputes the secular rates, lunisolar short-period coefficients, and resonance terms once at the TLE epoch so that repeated get_state_at_epoch calls are cheap.

Parameters:

Name	Type	Description	Default
tle	TLE	Two-line element set with ephemeris type 3 (PPT3 / Kozai mean elements).	required

Raises:

Type	Description
ValueError	If the epoch cannot be converted to UTC or the element set yields a non-physical initial state (e.g. a negative recovered semi-major axis).

get_state_at_epoch(target_epoch)

Propagate to the requested epoch and return the resulting state.

The returned state is always in the TEME reference frame [km, km/s].

Parameters:

Name	Type	Description	Default
target_epoch	ModifiedJulianDate	Epoch at which to evaluate the state.	required

Returns:

Type	Description
CartesianState	Cartesian state in the TEME reference frame [km, km/s].

Raises:

Type	Description
RuntimeError	If the target epoch cannot be converted to UTC or the analytic propagation produces a non-physical result (e.g. a decayed orbit).

SGP4

Stateful SGP4/SDP4 and SGP4-XP analytical propagator.

Construct with SGP4(tle) from a parsed TLE; then call get_state_at_epoch repeatedly. All output states are in the TEME reference frame, which is the native frame of the SGP4 family. Convert with the frames module when an inertial or Earth-fixed frame is required.

The propagator is stateful: GP (SGP4/SDP4) calls reuse the cached satrec initialisation, and XP calls extend the integration cache when the target epoch is past the current horizon.

Note

Ephemeris type 3 (PPT3 analytic theory) is not handled by this class — use PPT3 for type-3 TLEs. Ephemeris type 6 (osculating Cartesian) is also rejected; route those satellites to the numerical Integrator instead.

Attributes:

Name	Type	Description
tle	TLE	The TLE this propagator was constructed from.

tle property

The TLE this propagator was constructed from.

Returns:

Type	Description
TLE	Cloned TLE, preserving the original line-1 / line-2 catalogue
TLE	data.

__init__(tle)

Construct an SGP4 propagator for the given TLE.

Inspects the TLE's ephemeris-type byte and routes to the SGP4/SDP4 initialiser (types 0 and 2) or the SGP4-XP initialiser (other types). Type 6 (osculating Cartesian) is rejected; route those satellites to the numerical Integrator instead.

Parameters:

Name	Type	Description	Default
tle	TLE	Parsed two-line element set.	required

Raises:

Type	Description
ValueError	For ephemeris type 6, or any SGP4 initialisation failure (e.g. negative semi-major axis).

extend_xp_cache(target_minutes)

Ensure the SGP4-XP Mode 1 integration cache covers target_minutes.

Forces the internal forward integrator to extend its cache so that subsequent get_state_at_epoch calls in the same time window do not repeat work. No-op for GP (ephemeris type 0 or 2) satellites. Errors from the underlying integration are silently discarded; surface them by calling get_state_at_epoch directly.

Parameters:

Name	Type	Description	Default
target_minutes	float	Target time relative to the TLE epoch [min]. Negative values extend the backward cache.	required

get_state_at_epoch(target_epoch)

Propagate to the requested epoch and return the resulting state.

Dispatches to the GP (SGP4/SDP4) or XP path depending on the TLE ephemeris type used at construction. The propagator is stateful: GP calls reuse the cached satrec; XP calls extend the integration cache when the target epoch is past the current horizon.

The returned state is always in the TEME reference frame [km, km/s].

Parameters:

Name	Type	Description	Default
target_epoch	ModifiedJulianDate	Epoch at which to evaluate the state.	required

Returns:

Type	Description
CartesianState	Cartesian state in the TEME reference frame [km, km/s].

Raises:

Type	Description
RuntimeError	If the propagation produces a non-physical result (e.g. a decayed orbit or negative semi-major axis).

b_star_to_drag_coefficient(b_star)

Convert a TLE B* drag term to the keplime ballistic coefficient.

The keplime ballistic coefficient B is related to the TLE BSTAR term by the constant B_STAR_TO_B_TERM (≈ 12.74 km²/kg), which encodes the reference atmospheric density and drag coefficient conventions.

Parameters:

Name	Type	Description	Default
b_star	float	TLE BSTAR drag term [1/earth_radii; typically 1e-5..1e-3].	required

Returns:

Type	Description
float	Ballistic coefficient B = B* × B_STAR_TO_B_TERM [km²/kg].

drag_coefficient_to_b_star(drag_coefficient)

Convert a keplime ballistic coefficient to a TLE B* drag term.

Inverts b_star_to_drag_coefficient: B* = B / B_STAR_TO_B_TERM.

Parameters:

Name	Type	Description	Default
drag_coefficient	float	Ballistic coefficient B [km²/kg].	required

Returns:

Type	Description
float	TLE BSTAR drag term [1/earth_radii].