API: astrodyn_core.propagation

astrodyn_core.propagation

Propagation core public API.

Public API

PropagationClient Facade for ergonomic builder/propagator workflows. PropagatorFactory Low-level factory for building propagators from specs. ProviderRegistry Registry of propagation backend providers. BuildContext Context for propagator construction (orbit, universe, metadata).

Specs and models

PropagatorSpec, PropagatorKind, IntegratorSpec, TLESpec, AttitudeSpec, SpacecraftSpec, ForceSpec, GravitySpec, DragSpec, SRPSpec, ThirdBodySpec, RelativitySpec, SolidTidesSpec, OceanTidesSpec, CapabilityDescriptor

Assembly and config helpers

assemble_force_models, assemble_attitude_provider, load_dynamics_config, load_dynamics_from_dict, load_spacecraft_config, load_spacecraft_from_dict, register_default_orekit_providers, register_analytical_providers, register_all_providers

Shared Orekit environment helpers

import from astrodyn_core.orekit_env (get_mu, get_earth_shape, etc.)

ForceSpec = Union[GravitySpec, DragSpec, SRPSpec, ThirdBodySpec, RelativitySpec, SolidTidesSpec, OceanTidesSpec] module-attribute

Union of supported declarative force specification dataclasses.

AttitudeSpec(mode='inertial', provider=None) dataclass

Attitude configuration for propagation.

Attributes:

Name	Type	Description
mode	str	Predefined attitude mode (qsw, vvlh, tnw, nadir, inertial). Ignored when provider is supplied.
provider	Any | None	Optional pre-built Orekit AttitudeProvider instance used as a pass-through escape hatch for custom attitude laws.

BuildContext(initial_orbit=None, position_tolerance=10.0, attitude_provider=None, force_models=tuple(), universe=None, metadata=dict(), body_constants=None) dataclass

Runtime context required by provider implementations.

Orekit-native providers use initial_orbit and force_models. Custom/analytical providers may instead rely on body_constants for physical parameters like mu, J2, and equatorial radius.

Attributes:

Name	Type	Description
initial_orbit	Any | None	Orekit initial orbit for the propagation build.
position_tolerance	float	Position tolerance used by some Orekit builders.
attitude_provider	Any | None	Orekit AttitudeProvider override.
force_models	Sequence[Any]	Assembled Orekit force models for numerical/DSST builds.
universe	Mapping[str, Any] | None	Universe configuration mapping used for assembly/resolvers.
metadata	Mapping[str, Any]	Free-form metadata (for example initial mass).
body_constants	Mapping[str, float] | None	Optional analytical constants mapping (mu, j2, re).

from_state_record(state_record, *, universe=None, position_tolerance=10.0, attitude_provider=None, force_models=(), metadata=None, body_constants=None) classmethod

Construct a BuildContext from a serializable state record.

Parameters:

Name	Type	Description	Default
state_record	OrbitStateRecord	Serializable initial state record.	required
universe	Mapping[str, Any] | None	Optional universe configuration mapping.	None
position_tolerance	float	Builder position tolerance.	10.0
attitude_provider	Any | None	Optional pre-built Orekit attitude provider.	None
force_models	Sequence[Any]	Optional pre-assembled Orekit force models.	()
metadata	Mapping[str, Any] | None	Optional metadata merged into the context.	None
body_constants	Mapping[str, float] | None	Optional analytical constants mapping with keys mu (m^3/s^2), j2 (dimensionless), and re (m).	None

Returns:

Type	Description
BuildContext	Build context with an Orekit initial_orbit converted from the
BuildContext	state record.

require_body_constants()

Return body constants or raise if not provided.

Analytical providers should call this to get mu, j2, and re. If not explicitly set on the context, the constants are resolved from Orekit Constants.WGS84_* at call time.

Returns:

Type	Description
Mapping[str, float]	Mapping containing mu, j2, and re.

Raises:

Type	Description
RuntimeError	If constants are not provided and Orekit is unavailable for lazy resolution.

require_initial_orbit()

Return initial_orbit or raise if it was not provided.

CapabilityDescriptor(supports_builder=True, supports_propagator=True, supports_stm=False, supports_field_state=False, supports_multi_satellite=False, supports_bounded_output=False, is_analytical=False, supports_custom_output=False) dataclass

Describes what a provider supports.

Attributes:

Name	Type	Description
supports_builder	bool	Provider implements build_builder().
supports_propagator	bool	Provider implements build_propagator().
supports_stm	bool	Propagator supports State Transition Matrix extraction.
supports_field_state	bool	Propagator supports field/Taylor state propagation.
supports_multi_satellite	bool	Provider supports multi-satellite propagation.
supports_bounded_output	bool	Output is bounded to a fixed time interval.
is_analytical	bool	Custom/analytical implementation (not Orekit-native numerical).
supports_custom_output	bool	Provider can expose backend-specific output in addition to standard Orekit-compatible states.

DragSpec(atmosphere_model='nrlmsise00', space_weather_source='cssi', solar_activity_strength='average', space_weather_data='default', ref_rho=None, ref_alt=None, scale_height=None) dataclass

Atmospheric drag force model.

Parameters for SimpleExponential atmosphere (ref_rho, ref_alt, scale_height) are only required when atmosphere_model="simpleexponential".

space_weather_source and solar_activity_strength apply to models that consume space-weather data (NRLMSISE00, DTM2000, JB2008).

Attributes:

Name	Type	Description
atmosphere_model	str	Atmosphere model identifier.
space_weather_source	str	Space-weather provider source (cssi/msafe).
solar_activity_strength	str	Strength profile for msafe forecasts.
space_weather_data	str	Reserved/custom data source selector.
ref_rho	float | None	Reference density for simpleexponential.
ref_alt	float | None	Reference altitude (m) for simpleexponential.
scale_height	float | None	Scale height (m) for simpleexponential.

GravitySpec(degree=0, order=0, normalized=True) dataclass

Earth gravity field model.

Set degree=order=0 for a simple point-mass (Keplerian) model.

Attributes:

Name	Type	Description
degree	int	Spherical harmonics degree.
order	int	Spherical harmonics order.
normalized	bool	Whether to request a normalized gravity provider.

IntegratorSpec(kind, min_step=None, max_step=None, position_tolerance=None, step=None, n_steps=None, extra=dict()) dataclass

Integrator builder configuration for numerical and DSST builders.

Attributes:

Name	Type	Description
kind	str	Integrator kind identifier (for example "dp853").
min_step	float | None	Minimum integration step size in seconds (adaptive methods).
max_step	float | None	Maximum integration step size in seconds (adaptive methods).
position_tolerance	float | None	Position tolerance used to derive Orekit tolerances.
step	float | None	Fixed step size in seconds (fixed-step methods).
n_steps	int | None	Optional auxiliary step count for custom providers.
extra	Mapping[str, Any]	Provider-specific integrator options.

OceanTidesSpec(degree=5, order=5) dataclass

Ocean tides perturbation options.

Attributes:

Name	Type	Description
degree	int	Ocean tides degree.
order	int	Ocean tides order.

PropagationClient(universe=None) dataclass

Facade for ergonomic propagation factory/context usage.

Parameters:

Name	Type	Description	Default
universe	Mapping[str, Any] | None	Optional default universe configuration used when converting state records into Orekit orbits for build contexts.	None

build_builder(spec, context)

Build a propagator builder from a spec and build context.

Parameters:

Name	Type	Description	Default
spec	PropagatorSpec	Declarative propagator configuration.	required
context	BuildContext	Runtime build context (initial orbit, forces, etc.).	required

Returns:

Type	Description
Any	Provider-specific propagator builder (typically Orekit-native).

build_factory()

Create a PropagatorFactory with all built-in providers registered.

This includes both Orekit-native providers (numerical, keplerian, DSST, TLE) and built-in analytical providers (currently geqoe).

Returns:

Type	Description
PropagatorFactory	A factory with built-in providers pre-registered.

build_propagator(spec, context)

Build a propagator directly from a spec and build context.

Parameters:

Name	Type	Description	Default
spec	PropagatorSpec	Declarative propagator configuration.	required
context	BuildContext	Runtime build context (initial orbit, forces, etc.).	required

Returns:

Type	Description
Any	Provider-specific propagator instance.

build_propagator_from_state(state, spec, *, universe=None, metadata=None)

Build a propagator from an initial state record and a spec.

Works with any registered propagator kind (numerical, keplerian, DSST, TLE, or custom/analytical).

Parameters:

Name	Type	Description	Default
state	OrbitStateRecord	Serializable initial orbit state.	required
spec	PropagatorSpec	Declarative propagator configuration.	required
universe	Mapping[str, Any] | None	Optional per-call universe config override.	None
metadata	Mapping[str, Any] | None	Optional build-context metadata.	None

Returns:

Type	Description
Any	Built propagator instance created from the provider's builder lane.

context_from_state(state, *, universe=None, metadata=None)

Create a BuildContext from an OrbitStateRecord.

Parameters:

Name	Type	Description	Default
state	OrbitStateRecord	Serializable initial orbit state.	required
universe	Mapping[str, Any] | None	Optional per-call universe config override.	None
metadata	Mapping[str, Any] | None	Optional metadata merged into the build context.	None

Returns:

Type	Description
BuildContext	Build context containing an Orekit orbit converted from state.

load_dynamics_config(path, spacecraft=None)

Load a dynamics YAML config as PropagatorSpec.

Parameters:

Name	Type	Description	Default
path	str | Path	Dynamics YAML file path.	required
spacecraft	str | Path | None	Optional spacecraft YAML file path to merge into the returned spec.	None

Returns:

Type	Description
PropagatorSpec	Parsed propagator spec.

load_dynamics_from_dict(data)

Load a dynamics config mapping as PropagatorSpec.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Parsed dynamics configuration mapping.	required

Returns:

Type	Description
PropagatorSpec	Parsed propagator spec.

load_spacecraft_config(path)

Load a spacecraft YAML config as SpacecraftSpec.

load_spacecraft_from_dict(data)

Load a spacecraft config mapping as SpacecraftSpec.

PropagatorFactory(registry=ProviderRegistry()) dataclass

Build builders or propagators from specs via a provider registry.

Parameters:

Name	Type	Description	Default
registry	ProviderRegistry	Provider registry used to resolve builder/propagator lanes by spec.kind.	ProviderRegistry()

build_builder(spec, context)

Build a provider-specific builder for a propagator spec.

Parameters:

Name	Type	Description	Default
spec	PropagatorSpec	Declarative propagator configuration.	required
context	BuildContext	Runtime build context.	required

Returns:

Type	Description
Any	Provider-specific builder object.

build_propagator(spec, context)

Build a provider-specific propagator for a propagator spec.

Parameters:

Name	Type	Description	Default
spec	PropagatorSpec	Declarative propagator configuration.	required
context	BuildContext	Runtime build context.	required

Returns:

Type	Description
Any	Provider-specific propagator object.

PropagatorKind

Bases: str, Enum

Built-in propagator kinds.

Custom/analytical propagators should define their own string kind (e.g. "geqoe") and register it with the :class:ProviderRegistry. The registry accepts any string as a kind key, so contributors are not required to modify this enum when adding new propagators.

PropagatorSpec(kind, mass_kg=1000.0, position_angle_type='MEAN', dsst_propagation_type='MEAN', dsst_state_type='OSCULATING', integrator=None, tle=None, force_specs=tuple(), spacecraft=None, attitude=None, orekit_options=dict()) dataclass

Top-level propagation configuration.

The kind field accepts any :class:PropagatorKind enum member for built-in Orekit propagators, or a plain string for custom/analytical propagators registered via :class:ProviderRegistry.

Attributes:

Name	Type	Description
kind	PropagatorKind | str	Built-in or custom propagator kind key.
mass_kg	float	Spacecraft mass used by builders/propagators.
position_angle_type	str	Orekit position-angle convention for relevant propagator builders.
dsst_propagation_type	str	DSST propagation type (MEAN/OSCULATING).
dsst_state_type	str	DSST initial state type (MEAN/OSCULATING).
integrator	IntegratorSpec | None	Integrator configuration (required for numerical/DSST).
tle	TLESpec | None	Raw TLE lines (required for TLE propagator).
force_specs	Sequence[ForceSpec]	Declarative force model specs.
spacecraft	SpacecraftSpec | None	Spacecraft physical model for drag/SRP assembly.
attitude	AttitudeSpec | None	Declarative attitude configuration.
orekit_options	Mapping[str, Any]	Provider-specific Orekit/native options passthrough.

with_spacecraft(spacecraft)

Return a copy of the spec with a spacecraft model attached.

Parameters:

Name	Type	Description	Default
spacecraft	SpacecraftSpec	Spacecraft physical model specification.	required

Returns:

Type	Description
PropagatorSpec	New PropagatorSpec with spacecraft replaced.

ProviderRegistry(_builder_providers=dict(), _propagator_providers=dict()) dataclass

In-memory provider registry keyed by propagator kind (any string).

available_builder_kinds()

Return sorted builder-provider kinds.

available_propagator_kinds()

Return sorted propagator-provider kinds.

get_builder_provider(kind)

Resolve a builder provider by kind.

Parameters:

Name	Type	Description	Default
kind	str	Propagator kind key.	required

Returns:

Type	Description
Any	Registered builder provider.

Raises:

Type	Description
KeyError	If no builder provider is registered for kind.

get_propagator_provider(kind)

Resolve a propagator provider by kind.

Parameters:

Name	Type	Description	Default
kind	str	Propagator kind key.	required

Returns:

Type	Description
Any	Registered propagator provider.

Raises:

Type	Description
KeyError	If no propagator provider is registered for kind.

register_builder_provider(provider)

Register or replace a builder-lane provider.

Parameters:

Name	Type	Description	Default
provider	Any	Object exposing kind and build_builder.	required

register_propagator_provider(provider)

Register or replace a propagator-lane provider.

Parameters:

Name	Type	Description	Default
provider	Any	Object exposing kind and build_propagator.	required

RelativitySpec() dataclass

Relativistic correction (Schwarzschild effect).

Presence of this spec in the force list enables the correction.

SRPSpec(enable_moon_eclipse=False, enable_albedo=False) dataclass

Solar radiation pressure force model options.

Attributes:

Name	Type	Description
enable_moon_eclipse	bool	Include lunar occultation in SRP eclipse handling.
enable_albedo	bool	Request Earth albedo handling (separate force model in current assembly implementation).

SolidTidesSpec() dataclass

Solid Earth tides perturbation.

SpacecraftSpec(mass=1000.0, drag_area=10.0, drag_coeff=2.2, srp_area=10.0, srp_coeff=1.5, use_box_wing=False, x_length=1.0, y_length=1.0, z_length=1.0, solar_array_area=20.0, solar_array_axis=(0.0, 1.0, 0.0), box_drag_coeff=2.2, box_lift_coeff=0.0, box_abs_coeff=0.7, box_ref_coeff=0.3) dataclass

Physical spacecraft model used by drag and SRP assembly.

When use_box_wing=False (default), the isotropic parameters are used: drag_area, drag_coeff, srp_area, srp_coeff.

When use_box_wing=True, the box-and-solar-array geometry is used instead. The isotropic parameters are ignored in that case.

Attributes:

Name	Type	Description
mass	float	Spacecraft mass in kg.
drag_area	float	Isotropic drag area (m^2).
drag_coeff	float	Isotropic drag coefficient.
srp_area	float	Isotropic SRP area (m^2).
srp_coeff	float	Isotropic SRP reflection coefficient.
use_box_wing	bool	Enable box-and-solar-array geometry model.
x_length	float	Box dimension along X (m).
y_length	float	Box dimension along Y (m).
z_length	float	Box dimension along Z (m).
solar_array_area	float	Solar array area (m^2).
solar_array_axis	tuple[float, float, float]	Solar array rotation axis (normalized in __post_init__ when non-zero).
box_drag_coeff	float	Box drag coefficient.
box_lift_coeff	float	Box lift coefficient.
box_abs_coeff	float	Box absorptivity coefficient.
box_ref_coeff	float	Box reflectivity coefficient.

TLESpec(line1, line2) dataclass

Raw TLE line pair for SGP4/TLE propagator construction.

Attributes:

Name	Type	Description
line1	str	TLE line 1 text (must start with "1 ").
line2	str	TLE line 2 text (must start with "2 ").

ThirdBodySpec(bodies=('sun', 'moon')) dataclass

Third-body gravitational attractions.

bodies is a sequence of lowercase celestial body names. Common choices: ["sun", "moon"].

Attributes:

Name	Type	Description
bodies	tuple[str, ...]	Celestial body names to include as third-body perturbations.

assemble_attitude_provider(attitude, initial_orbit, universe=None)

Translate an AttitudeSpec into an Orekit AttitudeProvider.

Returns None if no attitude law can be resolved (should not happen if validation passed, but kept defensive).

Parameters:

Name	Type	Description	Default
attitude	AttitudeSpec	Declarative attitude specification.	required
initial_orbit	Any	Orekit initial orbit used to resolve frames.	required
universe	Mapping[str, Any] | None	Optional universe config (used for nadir pointing Earth shape).	None

Returns:

Type	Description
Any | None	Orekit AttitudeProvider or None if no mode could be resolved.

assemble_dsst_force_models(force_specs, spacecraft, initial_orbit, mu=None, universe=None)

Translate ForceSpec objects into Orekit DSST force models.

Parameters:

Name	Type	Description	Default
force_specs	Sequence[ForceSpec]	Declarative force specifications (same types as numerical).	required
spacecraft	SpacecraftSpec	Physical spacecraft model (needed for drag / SRP shapes).	required
initial_orbit	Any	Orekit orbit used to derive mu when not provided.	required
mu	float | None	Optional gravitational parameter override.	None
universe	Mapping[str, Any] | None	Optional universe configuration mapping.	None

Returns:

Type	Description
list[Any]	Orekit DSSTForceModel instances ready for
list[Any]	DSSTPropagatorBuilder.addForceModel().

assemble_force_models(force_specs, spacecraft, initial_orbit, mu=None, universe=None)

Translate a sequence of ForceSpec objects into Orekit force models.

Parameters:

Name	Type	Description	Default
force_specs	Sequence[ForceSpec]	Declarative force specifications.	required
spacecraft	SpacecraftSpec	Physical spacecraft model (needed for drag / SRP shapes).	required
initial_orbit	Any	Orekit orbit used to derive mu when not provided.	required
mu	float | None	Optional gravitational parameter override.	None
universe	Mapping[str, Any] | None	Optional universe config used by Earth/mu/IERS resolvers.	None

Returns:

Type	Description
list[Any]	Orekit ForceModel instances ready to add to a builder.

load_dynamics_config(path, spacecraft=None)

Load a dynamics configuration YAML and return a PropagatorSpec.

Parameters:

Name	Type	Description	Default
path	str | Path	Dynamics YAML file path.	required
spacecraft	str | Path | None	Optional spacecraft YAML file to parse and attach to the resulting spec.	None

Returns:

Type	Description
PropagatorSpec	Parsed propagator spec.

load_dynamics_from_dict(data)

Build a PropagatorSpec from an already-parsed dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Parsed dynamics configuration mapping.	required

Returns:

Type	Description
PropagatorSpec	Parsed propagator spec.

Raises:

Type	Description
TypeError	If data is not a dict.

load_spacecraft_config(path)

Load a spacecraft configuration YAML and return a SpacecraftSpec.

Parameters:

Name	Type	Description	Default
path	str | Path	Spacecraft YAML file path.	required

Returns:

Type	Description
SpacecraftSpec	Parsed spacecraft spec.

load_spacecraft_from_dict(data)

Build a SpacecraftSpec from an already-parsed dictionary.

Supports both a flat dataclass-like mapping and the structured schema-v1 spacecraft.model layout.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Parsed spacecraft configuration mapping.	required

Returns:

Type	Description
SpacecraftSpec	Parsed spacecraft spec.

Raises:

Type	Description
TypeError	If data is not a dict.

register_all_providers(registry)

Register all built-in providers (Orekit-native + analytical).

Parameters:

Name	Type	Description	Default
registry	Any	Provider registry to mutate.	required

register_analytical_providers(registry)

Register built-in analytical (non-Orekit-native) providers.

Currently registers: - GEqOEProvider (kind "geqoe") — J2 Taylor-series propagator in Generalized Equinoctial Orbital Elements.

Parameters:

Name	Type	Description	Default
registry	Any	Provider registry to mutate.	required

register_default_orekit_providers(registry)

Register built-in Orekit-native providers in both registry lanes.

Parameters:

Name	Type	Description	Default
registry	ProviderRegistry	Provider registry to mutate.	required