API: astrodyn_core

astrodyn_core

ASTRODYN-CORE public package API.

Exports are organized into three tiers:

Tier 1 -- Facade clients (recommended for most users) AstrodynClient, PropagationClient, StateFileClient, MissionClient, UncertaintyClient, TLEClient

Tier 2 -- Data models and specs (needed for configuration) PropagatorSpec, PropagatorKind, IntegratorSpec, BuildContext, force/spacecraft/attitude specs, state/scenario models, mission models, uncertainty models, TLE models

Tier 3 -- Advanced low-level helpers (expert Orekit-native usage) PropagatorFactory, ProviderRegistry, register_default_orekit_providers, assembly helpers, config loaders, data preset lookups

Symbols that were previously exported at root but belong to domain-specific workflows (e.g. compile_scenario_maneuvers, setup_stm_propagator, individual TLE parser functions) have been moved to subpackage exports only. They remain importable via their subpackage paths (e.g. from astrodyn_core.mission import compile_scenario_maneuvers).

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

Union of supported declarative force specification dataclasses.

AstrodynClient(universe=None, default_mass_kg=1000.0, interpolation_samples=None, tle_base_dir='data/tle', tle_allow_download=False, space_track_client=None, ephemeris_secrets_path=None, ephemeris_cache_dir='data/cache') dataclass

Unified app-level facade for state, mission, uncertainty, TLE, and ephemeris workflows.

AttitudeRecord(mode, frame=None, params=dict()) dataclass

Serializable attitude directive placeholder for timeline support.

Attributes:

Name	Type	Description
mode	str	Attitude mode name (normalized to lowercase).
frame	str | None	Optional reference frame (normalized to uppercase).
params	Mapping[str, Any]	Free-form attitude parameters.

from_mapping(data) classmethod

Build an attitude record from a plain mapping.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Serialized attitude mapping.	required

Returns:

Type	Description
AttitudeRecord	Validated attitude record.

to_mapping()

Serialize the attitude record to a plain mapping.

Returns:

Type	Description
dict[str, Any]	Mapping suitable for scenario-file serialization.

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.

CompiledManeuver(name, trigger_type, epoch, dv_inertial_mps, metadata=dict()) dataclass

Resolved maneuver execution entry.

Attributes:

Name	Type	Description
name	str	Maneuver name from the scenario file.
trigger_type	str	Trigger type that resolved the epoch.
epoch	str	Resolved execution epoch in ISO-8601 UTC format.
dv_inertial_mps	tuple[float, float, float]	Inertial delta-v vector in m/s.
metadata	Mapping[str, Any]	Auxiliary metadata from trigger/model resolution.

CovarianceRecord(epoch, matrix, frame='GCRF', orbit_type='CARTESIAN', include_mass=False, metadata=dict()) dataclass

Covariance matrix snapshot at a single epoch.

The matrix field stores an n×n covariance matrix (n=6 for orbit-only, n=7 if mass is included) as a tuple of tuples. Use to_numpy() for numerical operations.

The covariance is expressed in the coordinate system defined by frame and orbit_type.

from_mapping(data) classmethod

Build a covariance record from a plain mapping.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Mapping loaded from YAML/JSON/HDF5-derived metadata.	required

Returns:

Type	Description
CovarianceRecord	Validated covariance record.

from_numpy(epoch, matrix, *, frame='GCRF', orbit_type='CARTESIAN', include_mass=False, metadata=None) classmethod

Build a covariance record from a NumPy array.

Parameters:

Name	Type	Description	Default
epoch	str	UTC epoch string.	required
matrix	ndarray	Covariance array of shape (6, 6) or (7, 7).	required
frame	str	Covariance frame label.	'GCRF'
orbit_type	str	Orbit element representation label.	'CARTESIAN'
include_mass	bool	Whether the covariance includes a mass dimension.	False
metadata	Mapping[str, Any] | None	Optional metadata mapping stored alongside the matrix.	None

Returns:

Type	Description
CovarianceRecord	Validated covariance record.

to_mapping()

Serialize the record into a plain mapping for file I/O.

Returns:

Type	Description
dict[str, Any]	Mapping with scalar metadata and a nested-list matrix payload.

to_numpy()

Return the covariance matrix as a NumPy array.

Returns:

Type	Description
ndarray	Array of shape (n, n) where n is 6 or 7 depending on
ndarray	include_mass.

CovarianceSeries(name, records, method='stm') dataclass

Time series of covariance snapshots.

Attributes:

Name	Type	Description
name	str	Identifier for this covariance series.
records	tuple[CovarianceRecord, ...]	Ordered tuple of :class:CovarianceRecord instances.
method	str	Propagation method used to generate this series (for example "stm"). Informational metadata only.

epochs property

Return all epochs in the series.

Returns:

Type	Description
tuple[str, ...]	Tuple of UTC epoch strings in record order.

from_mapping(data) classmethod

Build a covariance series from a plain mapping.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Mapping with name, method, and records entries.	required

Returns:

Type	Description
CovarianceSeries	Validated covariance series.

matrices_numpy()

Return all matrices stacked into a single NumPy array.

Returns:

Type	Description
ndarray	Array of shape (N, n, n) where N is the number of records.

to_mapping()

Serialize the series into a plain mapping for file I/O.

Returns:

Type	Description
dict[str, Any]	Mapping containing series metadata and serialized records.

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.

EphemerisClient(secrets_path=None, cache_dir='data/cache', edc_api_client=None, edc_ftp_client=None) dataclass

Single entrypoint for ephemeris-based propagator creation.

Supports creating Orekit BoundedPropagator objects from standard ephemeris file formats:

• OEM (CCSDS Orbit Ephemeris Message) -- local files
• OCM (CCSDS Orbit Comprehensive Message) -- local files
• SP3 (IGS Standard Product 3) -- downloaded via EDC FTP
• CPF (ILRS Consolidated Prediction Format) -- downloaded via EDC API

For remote formats (SP3, CPF), provide EDC credentials either via secrets_path (reads edc_username and edc_password from a secrets.ini file) or by passing pre-built client objects via edc_api_client and edc_ftp_client.

Parameters:

Name	Type	Description	Default
secrets_path	str | Path | None	Optional path to a secrets.ini file containing EDC credentials (edc_username / edc_password) for remote SP3/CPF workflows.	None
cache_dir	str | Path	Local cache directory for downloaded ephemeris files.	'data/cache'
edc_api_client	Any | None	Optional pre-built EDC API client. When provided, this is used instead of lazily creating one from secrets_path.	None
edc_ftp_client	Any | None	Optional pre-built EDC FTP client for SP3 downloads.	None

Example

client = EphemerisClient()
propagator = client.create_propagator(
    EphemerisSpec.for_oem("data/oem_files/satellite.oem")
)

create_propagator(spec)

Create an Orekit bounded propagator from an ephemeris specification.

Local specs (OEM/OCM) are parsed directly. Remote specs (SP3/CPF) trigger EDC metadata/file acquisition before parsing and propagator construction.

Parameters:

Name	Type	Description	Default
spec	EphemerisSpec	Immutable ephemeris request describing source, format, and required query or file fields.	required

Returns:

Type	Description
Any	An Orekit BoundedPropagator (or equivalent Orekit propagator
Any	object returned by the parser/factory flow).

Raises:

Type	Description
ValueError	If required remote credentials/clients are missing or the spec cannot be fulfilled.

create_propagator_from_cpf(satellite_name, start_date, end_date, *, identifier_type='satellite_name', local_root=None)

Create a propagator from remote CPF data via EDC API.

Parameters:

Name	Type	Description	Default
satellite_name	str	Satellite identifier value used for EDC lookup.	required
start_date	str	Inclusive start date in YYYY-MM-DD format.	required
end_date	str	Inclusive end date in YYYY-MM-DD format.	required
identifier_type	str	Identifier type field understood by EDC.	'satellite_name'
local_root	str | None	Optional local CPF archive root checked before API download fallback.	None

Returns:

Type	Description
Any	An Orekit bounded propagator built from one or more CPF files.

create_propagator_from_ocm(file_paths)

Create a propagator from one or more local OCM files.

Parameters:

Name	Type	Description	Default
file_paths	str | Path | Sequence[str | Path]	One path or a sequence of OCM file paths.	required

Returns:

Type	Description
Any	An Orekit bounded propagator, potentially an aggregate when multiple
Any	OCM segments/satellites are fused.

create_propagator_from_oem(file_path)

Create a propagator from a local OEM file.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Path to a local OEM file.	required

Returns:

Type	Description
Any	An Orekit bounded propagator derived from the OEM ephemeris.

create_propagator_from_sp3(satellite_name, start_date, end_date, *, identifier_type='satellite_name', provider_preference=None)

Create a propagator from remote SP3 data via EDC FTP.

Parameters:

Name	Type	Description	Default
satellite_name	str	Satellite identifier value used for EDC lookup.	required
start_date	str	Inclusive start date in YYYY-MM-DD format.	required
end_date	str	Inclusive end date in YYYY-MM-DD format.	required
identifier_type	str	Identifier type field understood by EDC.	'satellite_name'
provider_preference	Sequence[str] | None	Optional SP3 provider priority order.	None

Returns:

Type	Description
Any	An Orekit bounded propagator built from one or more SP3 files.

parse_cpf(file_path)

Parse a local CPF file.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Path to an ILRS CPF file.	required

Returns:

Type	Description
Any	The parsed Orekit CPF object.

parse_ocm(file_path)

Parse a local OCM file.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Path to a CCSDS OCM file.	required

Returns:

Type	Description
Any	The parsed Orekit Ocm object.

parse_oem(file_path)

Parse a local OEM file.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Path to a CCSDS OEM file.	required

Returns:

Type	Description
Any	The parsed Orekit Oem object.

parse_sp3(file_path)

Parse a local SP3 file.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Path to an SP3 file.	required

Returns:

Type	Description
Any	The parsed Orekit SP3 object.

EphemerisFormat

Bases: str, Enum

Supported ephemeris file formats.

Attributes:

Name	Type	Description
OEM		CCSDS Orbit Ephemeris Message (local files).
OCM		CCSDS Orbit Comprehensive Message (local file sets).
SP3		IGS Standard Product 3 precise orbit files (remote via EDC FTP).
CPF		ILRS Consolidated Prediction Format files (remote via EDC API).

EphemerisSpec(format, source, file_path=None, file_paths=None, satellite_name=None, identifier_type=None, start_date=None, end_date=None, provider_preference=None, local_root=None) dataclass

Immutable specification for creating a BoundedPropagator from ephemeris data.

This is the "request object" in the spec/factory pattern. Create one using the convenience class methods (for_oem, for_ocm, for_sp3, for_cpf), then pass it to EphemerisClient.create_propagator().

Attributes:

Name	Type	Description
format	EphemerisFormat	Ephemeris file format.
source	EphemerisSource	Whether data is local or fetched remotely.
file_path	Path | None	Single local file path (OEM).
file_paths	tuple[Path, ...] | None	Multiple local file paths (OCM).
satellite_name	str | None	Satellite identifier value for remote queries (SP3, CPF).
identifier_type	str | None	Identifier type for remote queries (for example "satellite_name" or "cospar_id").
start_date	str | None	Start date for remote queries in YYYY-MM-DD format.
end_date	str | None	End date for remote queries in YYYY-MM-DD format.
provider_preference	tuple[str, ...] | None	Preferred SP3 providers in priority order.
local_root	str | None	Optional local CPF directory root used before API fallback.

for_cpf(satellite_name, start_date, end_date, *, identifier_type='satellite_name', local_root=None) classmethod

Create a spec for remote CPF data queried from the EDC API.

Parameters:

Name	Type	Description	Default
satellite_name	str	Satellite identifier value (for the chosen identifier_type).	required
start_date	str	Inclusive start date in YYYY-MM-DD format.	required
end_date	str	Inclusive end date in YYYY-MM-DD format.	required
identifier_type	str	Remote identifier field name understood by EDC.	'satellite_name'
local_root	str | None	Optional local CPF archive root to scan before API download fallback.	None

Returns:

Type	Description
EphemerisSpec	A validated remote CPF ephemeris specification.

for_ocm(file_paths) classmethod

Create a spec for one or more local OCM files.

Parameters:

Name	Type	Description	Default
file_paths	str | Path | Sequence[str | Path]	One path or a sequence of paths to CCSDS OCM files.	required

Returns:

Type	Description
EphemerisSpec	A validated local OCM ephemeris specification.

for_oem(file_path) classmethod

Create a spec for a local OEM file.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Path to a CCSDS OEM (Orbit Ephemeris Message) file.	required

Returns:

Type	Description
EphemerisSpec	A validated local OEM ephemeris specification.

for_sp3(satellite_name, start_date, end_date, *, identifier_type='satellite_name', provider_preference=None) classmethod

Create a spec for remote SP3 data queried from EDC FTP.

Parameters:

Name	Type	Description	Default
satellite_name	str	Satellite identifier value (typically a satellite name).	required
start_date	str	Inclusive start date in YYYY-MM-DD format.	required
end_date	str	Inclusive end date in YYYY-MM-DD format.	required
identifier_type	str	Remote identifier field name understood by EDC.	'satellite_name'
provider_preference	Sequence[str] | None	Optional provider priority order for SP3 file selection (one best file per day is chosen).	None

Returns:

Type	Description
EphemerisSpec	A validated remote SP3 ephemeris specification.

validate()

Validate field combinations for the selected source/format.

Raises:

Type	Description
ValueError	If required fields are missing or the source/format combination is unsupported.

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.

ManeuverFiredEvent(maneuver_name, epoch, trigger_type, dv_inertial_mps, applied, guard_skip_reason) dataclass

Record of a single maneuver trigger event during detector-driven execution.

Attributes:

Name	Type	Description
maneuver_name	str	Maneuver name from the scenario file.
epoch	str	ISO-8601 UTC string when the detector fired.
trigger_type	str	Trigger condition that fired (for example apogee).
dv_inertial_mps	tuple[float, float, float] | None	Applied inertial delta-v vector (m/s), or None if skipped before delta-v resolution.
applied	bool	True if the impulse was applied.
guard_skip_reason	str | None	Human-readable skip reason, or None if applied.

ManeuverRecord(name, trigger, model, frame=None) dataclass

Serializable maneuver placeholder for scenario timelines.

Attributes:

Name	Type	Description
name	str	Maneuver identifier.
trigger	Mapping[str, Any]	Trigger condition mapping.
model	Mapping[str, Any]	Maneuver model/parameter mapping.
frame	str | None	Optional frame name (normalized to uppercase).

from_mapping(data) classmethod

Build a maneuver record from a plain mapping.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Serialized maneuver mapping.	required

Returns:

Type	Description
ManeuverRecord	Validated maneuver record.

to_mapping()

Serialize the maneuver record to a plain mapping.

Returns:

Type	Description
dict[str, Any]	Mapping suitable for scenario-file serialization.

MissionClient(universe=None, default_mass_kg=1000.0, interpolation_samples=None) dataclass

Facade for mission planning, execution, export, and plotting workflows.

Parameters:

Name	Type	Description	Default
universe	Mapping[str, Any] | None	Optional default universe configuration used by frame/mu resolvers in downstream helpers.	None
default_mass_kg	float	Fallback spacecraft mass for exported state records.	1000.0
interpolation_samples	int | None	Optional default interpolation sample count for exported trajectories.	None

compile_scenario_maneuvers(scenario, initial_state)

Compile scenario maneuvers into absolute epochs and inertial delta-v.

Parameters:

Name	Type	Description	Default
scenario	ScenarioStateFile	Scenario state file model containing maneuvers/timeline.	required
initial_state	Any	Orekit SpacecraftState used as planning anchor.	required

Returns:

Type	Description
tuple[CompiledManeuver, ...]	Tuple of compiled maneuvers in execution order.

export_trajectory_from_scenario(propagator, scenario, epoch_spec, output_path, *, series_name='trajectory', representation='cartesian', frame='GCRF', mu_m3_s2='WGS84', interpolation_samples=None, dense_yaml=True, universe=None, default_mass_kg=None)

Simulate a scenario and export the sampled trajectory to file.

Parameters:

Name	Type	Description	Default
propagator	Any	Orekit propagator used for simulation.	required
scenario	ScenarioStateFile	Scenario state file model.	required
epoch_spec	OutputEpochSpec	Output epoch specification.	required
output_path	str | Path	Destination YAML/JSON/HDF5 path.	required
series_name	str	Output state-series name.	'trajectory'
representation	str	Output orbit representation.	'cartesian'
frame	str	Output frame name.	'GCRF'
mu_m3_s2	float | str	Gravitational parameter stored in output records.	'WGS84'
interpolation_samples	int | None	Optional interpolation sample override.	None
dense_yaml	bool	Dense row formatting for YAML compact output.	True
universe	Mapping[str, Any] | None	Optional per-call universe config override.	None
default_mass_kg	float | None	Optional per-call fallback mass override.	None

Returns:

Type	Description
tuple[Path, tuple[CompiledManeuver, ...]]	Tuple (saved_path, compiled_maneuvers).

plot_orbital_elements_series(series, output_png, *, universe=None, title=None)

Plot orbital elements from a state series and save as PNG.

Parameters:

Name	Type	Description	Default
series	StateSeries	Input state series.	required
output_png	str | Path	Destination PNG path.	required
universe	Mapping[str, Any] | None	Optional per-call universe config override.	None
title	str | None	Optional plot title override.	None

Returns:

Type	Description
Path	Resolved output path.

run_scenario_detector_mode(propagator, scenario, epoch_spec, *, series_name='trajectory', representation='cartesian', frame='GCRF', mu_m3_s2='WGS84', universe=None, default_mass_kg=None)

Execute a scenario in detector-driven mode and sample the result.

Parameters:

Name	Type	Description	Default
propagator	Any	Orekit numerical/DSST propagator supporting event detectors.	required
scenario	ScenarioStateFile	Scenario state file model.	required
epoch_spec	OutputEpochSpec	Output epoch specification.	required
series_name	str	Output state-series name.	'trajectory'
representation	str	Output orbit representation.	'cartesian'
frame	str	Output frame name.	'GCRF'
mu_m3_s2	float | str	Gravitational parameter stored in output records.	'WGS84'
universe	Mapping[str, Any] | None	Optional per-call universe config override.	None
default_mass_kg	float | None	Optional per-call fallback mass override.	None

Returns:

Type	Description
tuple[StateSeries, MissionExecutionReport]	Tuple (StateSeries, MissionExecutionReport).

simulate_scenario_series(propagator, scenario, epoch_spec, *, series_name='trajectory', representation='cartesian', frame='GCRF', mu_m3_s2='WGS84', interpolation_samples=None, universe=None, default_mass_kg=None)

Simulate a scenario by applying maneuvers during propagation and sample output.

Parameters:

Name	Type	Description	Default
propagator	Any	Orekit propagator exposing propagate and resetInitialState when maneuvers are present.	required
scenario	ScenarioStateFile	Scenario state file model.	required
epoch_spec	OutputEpochSpec	Output epoch specification.	required
series_name	str	Output state-series name.	'trajectory'
representation	str	Output orbit representation.	'cartesian'
frame	str	Output frame name.	'GCRF'
mu_m3_s2	float | str	Gravitational parameter stored in output records.	'WGS84'
interpolation_samples	int | None	Optional interpolation sample override.	None
universe	Mapping[str, Any] | None	Optional per-call universe config override.	None
default_mass_kg	float | None	Optional per-call fallback mass override.	None

Returns:

Type	Description
tuple[StateSeries, tuple[CompiledManeuver, ...]]	Tuple (StateSeries, compiled_maneuvers).

MissionExecutionReport(events, total_dv_mps, propagation_start, propagation_end) dataclass

Summary of a detector-driven scenario execution.

Attributes:

Name	Type	Description
events	tuple[ManeuverFiredEvent, ...]	All maneuver events in chronological order.
total_dv_mps	float	Scalar total applied delta-v (m/s).
propagation_start	str	Propagation start epoch (ISO-8601 UTC).
propagation_end	str	Propagation end epoch (ISO-8601 UTC).

applied_events()

Return only events where the maneuver was actually applied.

skipped_events()

Return only events that were skipped.

OceanTidesSpec(degree=5, order=5) dataclass

Ocean tides perturbation options.

Attributes:

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

OrbitStateRecord(epoch, frame='GCRF', representation='keplerian', position_m=None, velocity_mps=None, elements=None, mu_m3_s2='WGS84', mass_kg=None, metadata=dict()) dataclass

Serializable orbital state snapshot at one epoch.

Attributes:

Name	Type	Description
epoch	str	ISO-8601 UTC epoch string.
frame	str	Reference frame name (normalized to uppercase).
representation	str	State representation (cartesian, keplerian, or equinoctial; normalized to lowercase).
position_m	Sequence[float] | None	Cartesian position vector in meters (cartesian only).
velocity_mps	Sequence[float] | None	Cartesian velocity vector in m/s (cartesian only).
elements	Mapping[str, Any] | None	Orbital elements mapping (keplerian/equinoctial only).
mu_m3_s2	float | str	Gravitational parameter as numeric value or symbolic model key.
mass_kg	float | None	Optional spacecraft mass in kg.
metadata	Mapping[str, Any]	Free-form metadata preserved through serialization.

from_mapping(data) classmethod

Build an orbit-state record from a parsed mapping.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Mapping loaded from YAML/JSON.	required

Returns:

Type	Description
OrbitStateRecord	Validated and normalized orbit-state record.

to_mapping()

Serialize this record to a plain mapping.

Returns:

Type	Description
dict[str, Any]	Mapping suitable for YAML/JSON serialization.

OutputEpochSpec(explicit_epochs=tuple(), start_epoch=None, end_epoch=None, step_seconds=None, count=None, include_end=True) dataclass

Epoch grid specification for trajectory export and sampling helpers.

The grid can be defined in one of two mutually exclusive modes:

• explicit epoch list via explicit_epochs
• generated range via start_epoch/end_epoch and either step_seconds or count

Attributes:

Name	Type	Description
explicit_epochs	Sequence[str]	Explicit ISO-8601 UTC epochs.
start_epoch	str | None	Inclusive range start epoch.
end_epoch	str | None	Inclusive range end epoch.
step_seconds	float | None	Fixed step size in seconds (range mode only).
count	int | None	Number of output epochs (range mode only).
include_end	bool	Whether generated range output should include end_epoch.

epochs()

Return the concrete output epochs as ISO-8601 UTC strings.

Returns:

Type	Description
tuple[str, ...]	Tuple of UTC epoch strings in output 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).

ScenarioExecutor(propagator, scenario, *, universe=None)

Executes a scenario using Orekit event detectors for maneuver triggering.

Usage::

executor = ScenarioExecutor(propagator, scenario)
state_series, report = executor.run_and_sample(epoch_spec)

Parameters:

Name	Type	Description	Default
propagator	Any	Built Orekit numerical/DSST propagator exposing addEventDetector.	required
scenario	ScenarioStateFile	Loaded scenario state file model.	required
universe	Mapping[str, Any] | None	Optional universe configuration for frame resolution.	None

configure()

Resolve the scenario timeline and register all detectors on the propagator.

Called automatically by :meth:run_and_sample if not called explicitly. Calling it explicitly allows inspecting the detectors before propagation.

run(target_date_or_epoch)

Propagate to the target epoch and return the final state + report.

Parameters:

Name	Type	Description	Default
target_date_or_epoch	Any	Orekit AbsoluteDate or ISO-8601 UTC string.	required

Returns:

Type	Description
tuple[Any, MissionExecutionReport]	Tuple (final_state, MissionExecutionReport).

run_and_sample(epoch_spec, *, series_name='trajectory', representation='cartesian', frame='GCRF', mu_m3_s2='WGS84', default_mass_kg=1000.0)

Propagate the full mission and sample the trajectory at output epochs.

The propagator runs detector-driven to the last epoch in epoch_spec, applying maneuvers when detectors fire. After propagation, a second pass samples the trajectory at the requested output epochs using the propagator's built-in ephemeris (the propagator is used in EPHEMERIS_GENERATION_MODE internally via Orekit's step handling).

For simplicity, this implementation propagates to each output epoch in sequence and records the state. Because Orekit's NumericalPropagator tracks state resets from detectors, each propagate(date) call returns the physically correct post-maneuver state.

Parameters:

Name	Type	Description	Default
epoch_spec	OutputEpochSpec	Output epoch specification.	required
series_name	str	Name for the returned state series.	'trajectory'
representation	str	Output orbit representation.	'cartesian'
frame	str	Output frame name.	'GCRF'
mu_m3_s2	float | str	Gravitational parameter for output records.	'WGS84'
default_mass_kg	float	Fallback spacecraft mass.	1000.0

Returns:

Type	Description
tuple[StateSeries, MissionExecutionReport]	Tuple (StateSeries, MissionExecutionReport).

ScenarioStateFile(schema_version=1, universe=None, spacecraft=None, initial_state=None, timeline=tuple(), state_series=tuple(), maneuvers=tuple(), attitude_timeline=tuple(), metadata=dict()) dataclass

Top-level scenario state-file model.

Attributes:

Name	Type	Description
schema_version	int	Scenario schema version (currently 1 only).
universe	Mapping[str, Any] | None	Optional universe configuration mapping.
spacecraft	Mapping[str, Any] | None	Optional spacecraft configuration mapping.
initial_state	OrbitStateRecord | None	Optional initial state record.
timeline	Sequence[TimelineEventRecord]	Timeline events for mission sequencing.
state_series	Sequence[StateSeries]	Serialized state trajectories.
maneuvers	Sequence[ManeuverRecord]	Maneuver definitions.
attitude_timeline	Sequence[AttitudeRecord]	Attitude directives.
metadata	Mapping[str, Any]	Free-form scenario metadata.

from_mapping(data) classmethod

Build a scenario state file from a serialized mapping.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Mapping loaded from YAML/JSON.	required

Returns:

Type	Description
ScenarioStateFile	Validated scenario state file model.

to_mapping()

Serialize the scenario state file to a plain mapping.

Returns:

Type	Description
dict[str, Any]	Mapping suitable for YAML/JSON serialization.

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.

StateFileClient(universe=None, default_mass_kg=1000.0, interpolation_samples=None) dataclass

Single entrypoint for state-file workflows and Orekit conversion.

Core responsibilities

• load/save state files, initial states, state series
• Orekit date/orbit conversion
• ephemeris conversion from state series
• trajectory export from propagator

Parameters:

Name	Type	Description	Default
universe	Mapping[str, Any] | None	Optional universe configuration mapping used by frame/mu resolvers during Orekit conversions.	None
default_mass_kg	float	Fallback spacecraft mass used when states omit mass.	1000.0
interpolation_samples	int | None	Optional default interpolation sample count for ephemeris export helpers.	None

export_trajectory_from_propagator(propagator, epoch_spec, output_path, *, series_name='trajectory', representation='cartesian', frame='GCRF', mu_m3_s2='WGS84', interpolation_samples=None, dense_yaml=True, universe=None, default_mass_kg=None)

Sample a propagator/ephemeris and export a serialized trajectory file.

Parameters:

Name	Type	Description	Default
propagator	Any	Orekit propagator or precomputed ephemeris-like object.	required
epoch_spec	OutputEpochSpec	Output epoch grid specification.	required
output_path	str | Path	Destination YAML/JSON/HDF5 file path.	required
series_name	str	Name for the exported state series.	'trajectory'
representation	str	Output state representation.	'cartesian'
frame	str	Output frame name.	'GCRF'
mu_m3_s2	float | str	Gravitational parameter stored in exported records.	'WGS84'
interpolation_samples	int | None	Interpolation sample count override.	None
dense_yaml	bool	Whether YAML compact rows should use dense formatting.	True
universe	Mapping[str, Any] | None	Optional per-call universe config override.	None
default_mass_kg	float | None	Optional fallback mass override.	None

Returns:

Type	Description
Path	Resolved output path.

from_orekit_date(date)

Convert an Orekit AbsoluteDate to an ISO-8601 UTC epoch string.

load_initial_state(path)

Load only the initial state record from a state file.

Parameters:

Name	Type	Description	Default
path	str | Path	Source file path.	required

Returns:

Type	Description
OrbitStateRecord	Initial orbit state record.

load_state_file(path)

Load a YAML/JSON state file into a typed scenario model.

Parameters:

Name	Type	Description	Default
path	str | Path	Source file path.	required

Returns:

Type	Description
ScenarioStateFile	Parsed scenario state file model.

load_state_series(path, *, series_name=None)

Load a state series from a scenario YAML/JSON file or HDF5 file.

Parameters:

Name	Type	Description	Default
path	str | Path	Source file path.	required
series_name	str | None	Optional series name selector when multiple series are present in a scenario file.	None

Returns:

Type	Description
StateSeries	Loaded state series.

Raises:

Type	Description
ValueError	If no state series exist, or a named series is missing.

save_initial_state(path, state)

Save a file containing only an initial state payload.

Parameters:

Name	Type	Description	Default
path	str | Path	Destination file path.	required
state	OrbitStateRecord	Orbit state record to store.	required

Returns:

Type	Description
Path	Resolved output path.

save_state_file(path, scenario)

Save a scenario state file as YAML or JSON.

Parameters:

Name	Type	Description	Default
path	str | Path	Destination file path.	required
scenario	ScenarioStateFile	Scenario model to serialize.	required

Returns:

Type	Description
Path	Resolved output path.

save_state_series(path, series, *, dense_yaml=True, compression='gzip', compression_level=4, shuffle=True)

Save a state series to YAML/JSON compact format or HDF5.

Parameters:

Name	Type	Description	Default
path	str | Path	Destination file path. .h5/.hdf5 selects HDF5.	required
series	StateSeries	State series to serialize.	required
dense_yaml	bool	When writing YAML/JSON compact rows, prefer dense row formatting for YAML output.	True
compression	str	HDF5 compression algorithm for HDF5 outputs.	'gzip'
compression_level	int	HDF5 compression level.	4
shuffle	bool	Whether to enable HDF5 shuffle filter.	True

Returns:

Type	Description
Path	Resolved output path.

scenario_to_ephemeris(scenario, *, series_name=None, interpolation_samples=None, default_mass_kg=None)

Convert a scenario's state series into an Orekit ephemeris.

Parameters:

Name	Type	Description	Default
scenario	ScenarioStateFile	Scenario state file model.	required
series_name	str | None	Optional state-series selector. Defaults to first.	None
interpolation_samples	int | None	Optional interpolation sample count override.	None
default_mass_kg	float | None	Optional fallback mass override.	None

Returns:

Type	Description
Any	Orekit ephemeris / bounded propagator.

state_series_to_ephemeris(series, *, universe=None, interpolation_samples=None, default_mass_kg=None)

Convert a state series into an Orekit bounded ephemeris propagator.

Parameters:

Name	Type	Description	Default
series	StateSeries	Input state series.	required
universe	Mapping[str, Any] | None	Optional per-call universe config override.	None
interpolation_samples	int | None	Optional interpolation sample count override.	None
default_mass_kg	float | None	Optional fallback mass override.	None

Returns:

Type	Description
Any	Orekit ephemeris / bounded propagator built from the state series.

to_orekit_date(epoch)

Convert an ISO-8601 UTC epoch string to Orekit AbsoluteDate.

to_orekit_orbit(record, *, universe=None)

Convert a serializable orbit-state record into an Orekit orbit.

Parameters:

Name	Type	Description	Default
record	OrbitStateRecord	Serializable orbit-state record.	required
universe	Mapping[str, Any] | None	Optional per-call universe config override.	None

Returns:

Type	Description
Any	Orekit orbit instance matching the record representation.

StateSeries(name, states, interpolation_hint=None, interpolation=dict()) dataclass

Ordered sequence of orbit states with optional interpolation metadata.

Attributes:

Name	Type	Description
name	str	Series identifier.
states	Sequence[OrbitStateRecord]	Ordered orbit-state records.
interpolation_hint	str | None	Informal interpolation hint label.
interpolation	Mapping[str, Any]	Structured interpolation metadata mapping.

from_mapping(data) classmethod

Build a state series from expanded or compact serialized mappings.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Mapping containing either states or compact rows data.	required

Returns:

Type	Description
StateSeries	Validated state series.

to_mapping()

Serialize the state series into an expanded mapping.

Returns:

Type	Description
dict[str, Any]	Mapping with states entries suitable for YAML/JSON serialization.

TLEClient(base_dir='data/tle', allow_download=False, space_track_client=None) dataclass

Facade for TLE cache, parsing, and resolution workflows.

Parameters:

Name	Type	Description	Default
base_dir	str | Path	Root directory for monthly cached TLE files.	'data/tle'
allow_download	bool	Default policy for downloading missing cache files.	False
space_track_client	Any | None	Optional authenticated Space-Track client used for download-enabled workflows.	None

build_query(norad_id, target_epoch, *, base_dir=None, allow_download=None)

Build a normalized :class:TLEQuery from raw inputs.

Parameters:

Name	Type	Description	Default
norad_id	int	NORAD catalog identifier.	required
target_epoch	datetime	Epoch to resolve (naive datetimes are treated as UTC).	required
base_dir	str | Path | None	Optional cache root override for this query.	None
allow_download	bool | None	Optional download-policy override for this query.	None

Returns:

Type	Description
TLEQuery	A validated query object with normalized UTC epoch and Path
TLEQuery	cache root.

download_tles_for_month(norad_id, year, month, *, space_track_client=None, base_dir=None)

Download one month of TLE history into the local cache.

Parameters:

Name	Type	Description	Default
norad_id	int	NORAD catalog identifier.	required
year	int	UTC year.	required
month	int	UTC month in [1, 12].	required
space_track_client	Any | None	Optional client override. Falls back to the client stored on this instance.	None
base_dir	str | Path | None	Optional cache root override.	None

Returns:

Type	Description
TLEDownloadResult	A structured download result describing success/failure and output.

ensure_tles_available(norad_id, target_epoch, *, space_track_client=None, base_dir=None)

Ensure the required monthly cache files exist for a target epoch.

The current month is required. The previous month is also included when the target day is early in the month, to avoid missing the latest TLE before the requested epoch.

Parameters:

Name	Type	Description	Default
norad_id	int	NORAD catalog identifier.	required
target_epoch	datetime	Epoch to resolve.	required
space_track_client	Any | None	Optional client override for downloads.	None
base_dir	str | Path | None	Optional cache root override.	None

Returns:

Type	Description
tuple[Path, ...]	Tuple of existing local monthly cache file paths.

find_best_tle(records, target_epoch)

Select the latest TLE record at or before a target epoch.

Parameters:

Name	Type	Description	Default
records	Iterable[TLERecord]	Candidate records (order does not matter).	required
target_epoch	datetime	Desired epoch.	required

Returns:

Type	Description
TLERecord | None	The best matching record, or None if no record qualifies.

find_best_tle_in_file(path, target_epoch)

Parse a file and select the latest record at or before a target epoch.

Parameters:

Name	Type	Description	Default
path	str | Path	Local .tle file path.	required
target_epoch	datetime	Desired epoch.	required

Returns:

Type	Description
TLERecord | None	The best matching record, or None if no record qualifies.

get_tle_file_path(norad_id, year, month, *, base_dir=None)

Return the canonical monthly TLE cache path.

Parameters:

Name	Type	Description	Default
norad_id	int	NORAD catalog identifier.	required
year	int	UTC year.	required
month	int	UTC month in [1, 12].	required
base_dir	str | Path | None	Optional cache root override.	None

Returns:

Type	Description
Path	Canonical file path {base}/{norad}/{norad}_YYYY-MM.tle.

parse_norad_id(tle_line1)

Parse the NORAD catalog identifier from TLE line 1.

Parameters:

Name	Type	Description	Default
tle_line1	str	TLE line 1 text.	required

Returns:

Type	Description
int	Parsed NORAD ID.

parse_tle_epoch(tle_line1)

Parse a TLE line-1 epoch field into a UTC datetime.

Parameters:

Name	Type	Description	Default
tle_line1	str	TLE line 1 text.	required

Returns:

Type	Description
datetime	Parsed timezone-aware UTC epoch.

parse_tle_file(path)

Parse a local .tle file into sorted records.

Parameters:

Name	Type	Description	Default
path	str | Path	Local file path.	required

Returns:

Type	Description
tuple[TLERecord, ...]	Parsed records sorted by ascending epoch.

resolve_tle_record(query, *, space_track_client=None)

Resolve a query to a concrete :class:TLERecord.

Parameters:

Name	Type	Description	Default
query	TLEQuery	TLE query descriptor.	required
space_track_client	Any | None	Optional client override used if downloads are enabled on the query.	None

Returns:

Type	Description
TLERecord	The best TLE record with epoch less than or equal to the query epoch.

Raises:

Type	Description
ValueError	If downloads are enabled but no Space-Track client is available.
FileNotFoundError	If required cache files are missing and downloads are disabled (or fail to produce files).
RuntimeError	If cache files exist but no qualifying record is found.

resolve_tle_record_for_epoch(norad_id, target_epoch, *, base_dir=None, allow_download=None, space_track_client=None)

Convenience wrapper: build a query and resolve a TLE record.

Parameters:

Name	Type	Description	Default
norad_id	int	NORAD catalog identifier.	required
target_epoch	datetime	Desired epoch.	required
base_dir	str | Path | None	Optional cache root override.	None
allow_download	bool | None	Optional download-policy override.	None
space_track_client	Any | None	Optional client override for download-enabled queries.	None

Returns:

Type	Description
TLERecord	Resolved best TLE record.

resolve_tle_spec(query, *, space_track_client=None)

Resolve a query into a propagation-layer :class:TLESpec.

Parameters:

Name	Type	Description	Default
query	TLEQuery	TLE query descriptor.	required
space_track_client	Any | None	Optional client override used if downloads are enabled on the query.	None

Returns:

Type	Description
TLESpec	A propagation-ready TLESpec built from the resolved record.

resolve_tle_spec_for_epoch(norad_id, target_epoch, *, base_dir=None, allow_download=None, space_track_client=None)

Convenience wrapper: build a query and resolve a propagation TLE spec.

Parameters:

Name	Type	Description	Default
norad_id	int	NORAD catalog identifier.	required
target_epoch	datetime	Desired epoch.	required
base_dir	str | Path | None	Optional cache root override.	None
allow_download	bool | None	Optional download-policy override.	None
space_track_client	Any | None	Optional client override for download-enabled queries.	None

Returns:

Type	Description
TLESpec	A propagation-layer TLESpec.

TLEDownloadResult(norad_id, year, month, success, file_path=None, message='', tle_count=0) dataclass

Result of one monthly TLE download attempt.

Attributes:

Name	Type	Description
norad_id	int	NORAD catalog identifier requested.
year	int	Requested UTC year.
month	int	Requested UTC month.
success	bool	Whether the download attempt produced a usable cache file.
file_path	Path | None	Local cache file path when download succeeded.
message	str	Human-readable status or error message.
tle_count	int	Number of TLE sets written to the cache file.

TLEQuery(norad_id, target_epoch, base_dir='data/tle', allow_download=False) dataclass

Input query for local/download-backed TLE resolution.

Attributes:

Name	Type	Description
norad_id	int	NORAD catalog identifier to resolve.
target_epoch	datetime	Desired propagation epoch, normalized to UTC.
base_dir	str | Path	Root directory of the monthly TLE cache hierarchy.
allow_download	bool	Whether missing cache files may be downloaded from Space-Track.

TLERecord(line1, line2, norad_id, epoch) dataclass

Parsed two-line element set with normalized epoch metadata.

Attributes:

Name	Type	Description
line1	str	TLE line 1 text (must start with "1 ").
line2	str	TLE line 2 text (must start with "2 ").
norad_id	int	NORAD catalog identifier parsed from line 1.
epoch	datetime	TLE epoch normalized to timezone-aware UTC.

as_two_line_string()

Render the TLE as a standard two-line string block.

Returns:

Type	Description
str	The original TLE lines separated by a newline.

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.

TimelineEventRecord(id, point, metadata=dict()) dataclass

Named timeline event used to schedule mission actions.

Attributes:

Name	Type	Description
id	str	Unique event identifier.
point	Mapping[str, Any]	Event point definition mapping.
metadata	Mapping[str, Any]	Free-form event metadata mapping.

from_mapping(data) classmethod

Build a timeline event record from a plain mapping.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Serialized event mapping.	required

Returns:

Type	Description
TimelineEventRecord	Validated timeline event record.

to_mapping()

Serialize the timeline event record to a plain mapping.

Returns:

Type	Description
dict[str, Any]	Mapping suitable for scenario-file serialization.

UncertaintyClient(default_mass_kg=1000.0) dataclass

Facade for covariance propagation and covariance-series I/O workflows.

Parameters:

Name	Type	Description	Default
default_mass_kg	float	Fallback spacecraft mass used when propagated states do not expose a mass value.	1000.0

create_covariance_propagator(propagator, initial_covariance, *, spec=None, frame='GCRF', mu_m3_s2='WGS84', default_mass_kg=None)

Create a covariance propagator configured for the requested method.

Parameters:

Name	Type	Description	Default
propagator	Any	Orekit propagator instance (numerical/DSST) supporting STM extraction.	required
initial_covariance	ndarray | Sequence[Sequence[float]]	Initial covariance matrix (6x6 or 7x7 depending on spec.include_mass).	required
spec	UncertaintySpec | None	Uncertainty propagation configuration. Defaults to UncertaintySpec().	None
frame	str	Output frame name for generated covariance/state records.	'GCRF'
mu_m3_s2	float | str	Gravitational parameter used in state record serialization (or a symbolic resolver value such as "WGS84").	'WGS84'
default_mass_kg	float | None	Optional per-call override for fallback mass.	None

Returns:

Type	Description
STMCovariancePropagator	Configured STMCovariancePropagator.

load_covariance_series(path)

Load a covariance series from YAML or HDF5 based on file extension.

Parameters:

Name	Type	Description	Default
path	str | Path	Source file path.	required

Returns:

Type	Description
CovarianceSeries	Loaded covariance series.

propagate_with_covariance(propagator, initial_covariance, epoch_spec, *, spec=None, frame='GCRF', mu_m3_s2='WGS84', series_name='trajectory', covariance_name='covariance', default_mass_kg=None)

Propagate a trajectory and covariance series on a shared epoch grid.

Parameters:

Name	Type	Description	Default
propagator	Any	Orekit propagator instance supporting STM extraction.	required
initial_covariance	ndarray | Sequence[Sequence[float]]	Initial covariance matrix (6x6 or 7x7).	required
epoch_spec	OutputEpochSpec	Output epoch grid specification.	required
spec	UncertaintySpec | None	Uncertainty propagation configuration. Defaults to STM.	None
frame	str	Output frame name for state/covariance records.	'GCRF'
mu_m3_s2	float | str	Gravitational parameter for serialized state records.	'WGS84'
series_name	str	Output state-series name.	'trajectory'
covariance_name	str	Output covariance-series name.	'covariance'
default_mass_kg	float | None	Optional per-call override for fallback mass.	None

Returns:

Type	Description
StateSeries	Tuple (StateSeries, CovarianceSeries) evaluated on the same
CovarianceSeries	epochs.

save_covariance_series(path, series, **kwargs)

Persist a covariance series to YAML or HDF5 based on file extension.

Parameters:

Name	Type	Description	Default
path	str | Path	Destination file path.	required
series	CovarianceSeries	Covariance series to persist.	required
**kwargs	Any	Format-specific options forwarded to the underlying save function (for example HDF5 compression settings).	{}

Returns:

Type	Description
Path	Resolved output path.

UncertaintySpec(method='stm', stm_name='stm', include_mass=False, orbit_type='CARTESIAN', position_angle='MEAN') dataclass

Configuration for covariance/uncertainty propagation.

method

• "stm" (default): State Transition Matrix method using Orekit's setupMatricesComputation. Linear approximation; fast and accurate for short arcs or near-linear dynamics.

stm_name

Internal name for the STM additional state. Only used with method="stm".

include_mass

If True, extend the STM to 7×7 (state + mass). The initial covariance must then be 7×7. If False (default), 6×6 state-only covariance.

orbit_type

Orbit element type for the STM state vector: "CARTESIAN" (default), "KEPLERIAN", or "EQUINOCTIAL".

position_angle

Position angle convention used for non-Cartesian orbit types. "MEAN" (default), "TRUE", or "ECCENTRIC".

state_dimension property

Return the configured state dimension.

Returns:

Type	Description
int	6 for orbit-only covariance, 7 when mass is included.

from_mapping(data) classmethod

Build a spec from a plain mapping.

Parameters:

Name	Type	Description	Default
data	dict	Mapping of uncertainty configuration values.	required

Returns:

Type	Description
UncertaintySpec	Validated uncertainty spec with normalized string fields.

to_mapping()

Serialize the spec into a plain mapping.

Returns:

Type	Description
dict	Mapping suitable for YAML/JSON serialization.

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_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.

get_propagation_model(name)

Return the path to a bundled propagation-model YAML preset.

Parameters

name: Preset name, with or without the .yaml extension. Examples: "high_fidelity", "j2_model.yaml".

Returns

Path Absolute path to the YAML file.

Raises

FileNotFoundError If no preset with that name exists.

get_spacecraft_model(name)

Return the path to a bundled spacecraft-model YAML preset.

Parameters

name: Preset name, with or without the .yaml extension. Examples: "leo_smallsat", "box_wing_bus.yaml".

Returns

Path Absolute path to the YAML file.

Raises

FileNotFoundError If no preset with that name exists.

list_propagation_models()

Return names of all bundled propagation-model presets.

list_spacecraft_models()

Return names of all bundled spacecraft-model presets.

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