Bodies

bodies

AtmosphereModel

Atmospheric density model for drag computations.

Wraps one of the available atmospheric density models. Instances are obtained from the class methods exponential, nrlmsise00, harris_priester, and jacchia_bowman_2008.

The density and drag_acceleration methods use altitude-only context; richer inputs (position, Sun direction, space-weather) are not available through this interface.

Attributes:

Name	Type	Description
name	str	Model identifier string (e.g. "Exponential", "NRLMSISE00", "HarrisPriester", "JacchiaBowman2008").

name property

Model identifier string.

__repr__()

Returns AtmosphereModel(name=…).

density(altitude)

Returns atmospheric density at a given geodetic altitude.

Uses altitude-only context; time, position, and solar-activity inputs are not used by this interface.

Parameters:

Name	Type	Description	Default
altitude	float	Geodetic altitude above the reference ellipsoid [km; ≥ 0].	required

Returns:

Type	Description
float	Atmospheric mass density [kg/m³].

drag_acceleration(altitude, velocity_rel, cd, area_mass_ratio)

Computes the drag acceleration at a given altitude and velocity.

Implements a = -½ ρ Cd (A/m) |v| v. Returns the zero vector when density or relative speed is zero.

Parameters:

Name	Type	Description	Default
altitude	float	Geodetic altitude above the reference ellipsoid [km].	required
velocity_rel	tuple[float, float, float]	Velocity relative to the rotating atmosphere [km/s].	required
cd	float	Drag coefficient [dimensionless; typically 2.0–2.5].	required
area_mass_ratio	float	Effective drag area-to-mass ratio [m²/kg].	required

Returns:

Type	Description
tuple[float, float, float]	Drag acceleration opposing the relative velocity [km/s²].

exponential() staticmethod

Returns the US Standard Atmosphere 1976 piecewise-exponential model.

Depends only on altitude; safe to use with the altitude-only density interface.

Returns:

Type	Description
AtmosphereModel	Singleton exponential model instance.

harris_priester() staticmethod

Returns the Harris-Priester analytical drag model.

Uses minimum/maximum density envelopes with a diurnal-bulge cosine. When called via the simple density method, the Sun direction defaults to zero and only the minimum-density envelope is used.

Returns:

Type	Description
AtmosphereModel	Singleton Harris-Priester model instance.

jacchia_bowman_2008() staticmethod

Returns the Jacchia-Bowman 2008 thermosphere model.

Refines the original Jacchia formulation with corrections from satellite drag observations and an updated EUV proxy.

Returns:

Type	Description
AtmosphereModel	Singleton Jacchia-Bowman 2008 model instance.

nrlmsise00() staticmethod

Returns the NRLMSISE-00 thermosphere / mesosphere model.

Includes diurnal, semi-annual, and geomagnetic correction terms. When called via the simple density method, solar and geomagnetic indices default to quiet-time nominal values.

Returns:

Type	Description
AtmosphereModel	Singleton NRLMSISE-00 model instance.

Constellation

A collection of satellites that can be operated on together.

Supports batch propagation, ephemeris caching, conjunction analysis, and observation association. Implements the Python mapping protocol ([], in, len, iteration) keyed by satellite ID string.

Attributes:

Name	Type	Description
name	str | None	Optional human-readable constellation name.
count	int	Number of satellites in the constellation.
ephemeris_cache_start	ModifiedJulianDate | None	Start of the currently cached ephemeris window, or None if uncached.
ephemeris_cache_end	ModifiedJulianDate | None	End of the currently cached ephemeris window, or None if uncached.

count property

Number of satellites in the constellation.

ephemeris_cache_end property

End of the currently cached ephemeris window, or None if no cache window is set.

ephemeris_cache_start property

Start of the currently cached ephemeris window, or None if no cache window is set.

name property writable

Optional human-readable constellation name, or None if not set.

__contains__(satellite_id)

Returns whether a satellite is stored under satellite_id.

__delitem__(satellite_id)

Removes the satellite stored under satellite_id.

Raises:

Type	Description
KeyError	If no entry is stored under satellite_id.

__getitem__(satellite_id)

Returns the satellite stored under satellite_id.

Raises:

Type	Description
KeyError	If no entry is stored under satellite_id.

__init__(name=...)

Creates an empty Constellation.

Parameters:

Name	Type	Description	Default
name	Optional[str]	Optional human-readable constellation name.	...

__iter__()

Iterates over the satellite identifiers.

__len__()

Returns the number of satellites in the constellation.

__setitem__(satellite_id, satellite)

Adds or replaces the satellite stored under satellite_id.

add_satellite(satellite_id, satellite)

Adds a satellite to the constellation.

If a satellite with the same satellite_id already exists it is replaced.

Parameters:

Name	Type	Description	Default
satellite_id	str	Unique string key for this satellite.	required
satellite	Satellite	Satellite to add.	required

cache_ephemeris(start, end, step, purge_on_fail=..., reference_frame=..., device=DevicePreference.CPU)

Batch-propagates all satellites and caches their ephemerides.

If purge_on_fail is True, satellites that fail to propagate are removed from the constellation rather than raising. When device is DevicePreference.GPU, XP members use mixed-epoch GPU dispatch with each satellite's own XP epoch offset; large Mode 1 cache spans are chunked by row count to stay within GPU buffer limits. Unsupported GPU settings remain propagation failures and are not rebuilt on CPU.

Parameters:

Name	Type	Description	Default
start	ModifiedJulianDate	Start of the ephemeris window.	required
end	ModifiedJulianDate	End of the ephemeris window.	required
step	TimeSpan	Propagation step size.	required
purge_on_fail	bool	If True, remove failing satellites instead of raising. Defaults to False.	...
reference_frame	ReferenceFrame | None	Frame for the cached states; defaults to TEME.	...
device	DevicePreference	Compute device preference; defaults to CPU.	CPU

clear_ephemeris_cache()

Clears cached ephemerides for all satellites in the constellation.

from_tle_catalog(catalog) staticmethod

Creates a Constellation from a TLE catalog.

Each TLE in the catalog becomes a Satellite backed by SGP4/SDP4 propagation.

Parameters:

Name	Type	Description	Default
catalog	TLECatalog	Source TLE catalog.	required

Returns:

Type	Description
Constellation	Constellation with one satellite per catalog entry.

get_association_reports(collections, device=DevicePreference.CPU)

Associates observation collections to cached constellation states.

Parameters:

Name	Type	Description	Default
collections	list[ObservationCollection]	Observation collections to associate.	required
device	DevicePreference	Compute device preference; defaults to CPU.	CPU

Returns:

Type	Description
list[CollectionAssociationReport]	list[CollectionAssociationReport]:
list[CollectionAssociationReport]	One report per collection.

Raises:

Type	Description
ValueError	If cached ephemerides are missing, out of range, or the selected device path is unavailable.

get_ca_report_vs_many(start, end, distance_threshold, other=None, device=DevicePreference.CPU)

Computes close-approach events within the constellation or against another.

If other is None, performs intra-constellation analysis.

Parameters:

Name	Type	Description	Default
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
distance_threshold	float	Maximum range [km; > 0].	required
other	Optional[Constellation]	Optional second constellation; None for intra-constellation analysis.	None
device	DevicePreference	Compute device preference; defaults to CPU.	CPU

Returns:

Type	Description
CloseApproachReport	CloseApproachReport for all events.

Raises:

Type	Description
ValueError	If propagation fails.

get_ca_report_vs_one(other, start, end, distance_threshold, device=DevicePreference.CPU)

Computes close-approach events between the constellation and one satellite.

Parameters:

Name	Type	Description	Default
other	Satellite	The single satellite to check against.	required
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
distance_threshold	float	Maximum range [km; > 0].	required
device	DevicePreference	Compute device preference; defaults to CPU.	CPU

Returns:

Type	Description
CloseApproachReport	CloseApproachReport for all events.

Raises:

Type	Description
ValueError	If propagation fails.

get_coverage_grid(sensor, sites, start, end, step, metric=..., min_observations=...)

Scores how well a sensor observes the constellation from each site.

Builds every satellite's ephemeris once over [start, end], then evaluates sensor (using its constraints, treated as a steerable ground site) against the whole constellation from each candidate site. The grid rows pair 1:1 with sites.

Parameters:

Name	Type	Description	Default
sensor	Sensor	Sensor whose constraints gate visibility.	required
sites	list[GeodeticPosition]	Candidate ground locations (1:1 with the grid rows).	required
start	ModifiedJulianDate	Start of the evaluation window.	required
end	ModifiedJulianDate	End of the evaluation window.	required
step	TimeSpan	Ephemeris sampling step for the constellation.	required
metric	CoverageMetric	How each site is scored; defaults to CoverageMetric.UniqueSatellitesCovered.	...
min_observations	int	Windows required for a satellite to count as covered; defaults to 1.	...

Returns:

Type	Description
CoverageGrid	CoverageGrid with one entry per site.

Raises:

Type	Description
ValueError	If the constellation ephemerides cannot be built.

get_ephemeris(start, end, step)

Generates ephemerides for all satellites over a time window.

Parameters:

Name	Type	Description	Default
start	ModifiedJulianDate	Start of the ephemeris window.	required
end	ModifiedJulianDate	End of the ephemeris window.	required
step	TimeSpan	Propagation step size.	required

Returns:

Type	Description
dict[str, Ephemeris]	dict[str, Ephemeris]: Mapping from satellite ID to ephemeris.

Raises:

Type	Description
ValueError	If propagation fails for any satellite.

get_horizon_access_report(observers, start, end, min_elevation, min_duration)

Computes horizon access intervals for all satellites against ground observers.

Parameters:

Name	Type	Description	Default
observers	list[GeodeticPosition]	List of ground observer positions.	required
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
min_elevation	float	Minimum elevation angle [rad; >= 0].	required
min_duration	TimeSpan	Minimum pass duration.	required

Returns:

Type	Description
HorizonAccessReport	HorizonAccessReport for the
HorizonAccessReport	constellation.

Raises:

Type	Description
ValueError	If propagation fails for any satellite.

get_maneuver_events(future_sats, start, end, distance_threshold, velocity_threshold, device=DevicePreference.CPU)

Detects maneuver events by comparing current and future constellation states.

Parameters:

Name	Type	Description	Default
future_sats	Constellation	Constellation representing the post-maneuver states.	required
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
distance_threshold	float	Position difference threshold [km; > 0].	required
velocity_threshold	float	Velocity difference threshold [km/s; > 0].	required
device	DevicePreference	Compute device preference; defaults to CPU.	CPU

Returns:

Type	Description
ManeuverReport	ManeuverReport for all detected events.

Raises:

Type	Description
ValueError	If propagation fails.

get_plot_data(start, end, step)

Generates orbit plot data for all satellites over a time window.

Parameters:

Name	Type	Description	Default
start	ModifiedJulianDate	Start of the plot window.	required
end	ModifiedJulianDate	End of the plot window.	required
step	TimeSpan	Propagation step size.	required

Returns:

Type	Description
dict[str, OrbitPlotData]	dict[str, OrbitPlotData]: Mapping from satellite ID to plot data.

Raises:

Type	Description
ValueError	If propagation fails for any satellite.

get_proximity_report_vs_many(start, end, distance_threshold, other=None, device=DevicePreference.CPU)

Computes proximity events within the constellation or against another.

If other is None, performs intra-constellation analysis.

Parameters:

Name	Type	Description	Default
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
distance_threshold	float	Maximum range [km; > 0].	required
other	Optional[Constellation]	Optional second constellation; None for intra-constellation analysis.	None
device	DevicePreference	Compute device preference; defaults to CPU.	CPU

Returns:

Type	Description
ProximityReport	ProximityReport for all intervals.

Raises:

Type	Description
ValueError	If propagation fails.

get_proximity_report_vs_one(other, start, end, distance_threshold)

Computes proximity events between the constellation and one satellite.

Parameters:

Name	Type	Description	Default
other	Satellite	The single satellite to check against.	required
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
distance_threshold	float	Maximum range [km; > 0].	required

Returns:

Type	Description
ProximityReport	ProximityReport for all intervals.

Raises:

Type	Description
ValueError	If propagation fails.

get_satellite(satellite_id)

Returns the satellite with the given identifier.

Parameters:

Name	Type	Description	Default
satellite_id	str	Unique string key to look up.	required

Returns:

Type	Description
Optional[Satellite]	Satellite if found, otherwise None.

get_states_at_epoch(epoch)

Propagates all satellites to the given epoch and returns their states.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Target epoch for all propagations.	required

Returns:

Type	Description
dict[str, CartesianState]	dict[str, CartesianState]: Mapping from satellite ID to state in
dict[str, CartesianState]	TEME.

Raises:

Type	Description
ValueError	If propagation fails for any satellite.

get_uct_validity(uct, all_collections, orphan_collections)

Classifies the physical validity of an uncorrelated track.

Parameters:

Name	Type	Description	Default
uct	Satellite	Satellite representing the uncorrelated track.	required
all_collections	list[ObservationCollection]	All available observation collections.	required
orphan_collections	list[ObservationCollection]	Collections not yet associated with any known object.	required

Returns:

Type	Description
UCTValidityReport	UCTValidityReport with validity
UCTValidityReport	classification and supporting evidence.

Raises:

Type	Description
ValueError	If propagation fails.

keys()

Returns a sorted list of all satellite IDs in the constellation.

Returns:

Type	Description
list[str]	list[str]: Sorted satellite ID strings.

optimize_sensor_locations(sensors, sites, start, end, step, metric=..., min_observations=..., allow_multisite=..., co_detection_bonus=...)

Picks where to place a list of sensors to best observe the constellation.

Evaluates each sensor's coverage of every candidate site (honoring its own constraints), then chooses sites to maximize distinct satellites observed: allow_multisite=False co-locates all sensors at the single best site; allow_multisite=True assigns one distinct site per sensor by greedy marginal coverage (requires at least as many sites as sensors). The report's per_sensor_grids are renderable heatmaps.

With CoverageMetric.MultiSensorCoverage the objective rewards satellites co-detected by several sensors (e.g. radar and telescope), so a near-omniscient sensor does not make a complementary one irrelevant the way the unique-satellites union does.

Parameters:

Name	Type	Description	Default
sensors	list[Sensor]	Sensors to place (each carries its own constraints).	required
sites	list[GeodeticPosition]	Candidate ground locations.	required
start	ModifiedJulianDate	Start of the evaluation window.	required
end	ModifiedJulianDate	End of the evaluation window.	required
step	TimeSpan	Ephemeris sampling step for the constellation.	required
metric	CoverageMetric	Objective and per-sensor grid metric; defaults to CoverageMetric.UniqueSatellitesCovered.	...
min_observations	int	Windows required for a satellite to count as covered; defaults to 1.	...
allow_multisite	bool	True for distinct sites, False (default) to co-locate.	...
co_detection_bonus	float	Co-detection weight for CoverageMetric.MultiSensorCoverage (value = k + bonus*C(k,2)); defaults to 1.0 and is ignored by the other metrics.	...

Returns:

Type	Description
SensorPlacementReport	SensorPlacementReport.

Raises:

Type	Description
ValueError	On an empty sensor or site list, when multisite is requested with fewer sites than sensors, or if the constellation ephemerides cannot be built.

remove_satellite(satellite_id)

Removes and returns the satellite with the given identifier.

Parameters:

Name	Type	Description	Default
satellite_id	str	Unique string key of the satellite to remove.	required

Returns:

Type	Description
Optional[Satellite]	Satellite if it existed, otherwise None.

with_ephemeris_cache_range(start, end)

Returns a copy of this constellation with the ephemeris cache window set.

Parameters:

Name	Type	Description	Default
start	ModifiedJulianDate	Start of the desired cache window.	required
end	ModifiedJulianDate	End of the desired cache window.	required

Returns:

Type	Description
Constellation	Constellation with the updated cache window metadata.

Earth

Factory for Earth gravity and geodetic model constants.

Access pre-resolved model constants as class attributes. Use wgs_72 for SGP4/SDP4 propagation; use egm_96 or egm_2008 for numerical (XP) propagation.

Attributes:

Name	Type	Description
wgs_72	EarthModel	World Geodetic System 1972 constants.
wgs_84	EarthModel	World Geodetic System 1984 constants.
egm_96	EarthModel	Earth Gravitational Model 1996 constants.
egm_2008	EarthModel	Earth Gravitational Model 2008 constants.

EarthModel

Constant parameters for an Earth gravity and geodetic model.

Instances are obtained from the Earth class attributes (e.g. Earth.egm_96). All values are static and zero-allocation.

Attributes:

Name	Type	Description
equatorial_radius	float	Equatorial radius [km].
mu	float	Gravitational parameter GM [km³/s²].
j2	float	Second zonal harmonic coefficient [dimensionless].
j3	float	Third zonal harmonic coefficient [dimensionless].
j4	float	Fourth zonal harmonic coefficient [dimensionless].
flattening	float	Flattening factor f = (a − b) / a [dimensionless].

equatorial_radius property

Equatorial radius [km].

flattening property

Flattening factor f = (a − b) / a [dimensionless].

j2 property

Second zonal harmonic coefficient J₂ [dimensionless].

j3 property

Third zonal harmonic coefficient J₃ [dimensionless].

j4 property

Fourth zonal harmonic coefficient J₄ [dimensionless].

mu property

Gravitational parameter GM [km³/s²].

Moon

Moon ephemeris backed by the DE441 Horizons data file.

All methods are static; no instantiation is required. State positions and velocities are in TEME (NASA Horizons J2000 records are converted to TEME at ephemeris-load time). Position accuracy vs JPL: ~5 m at the daily record epochs, up to ~3 km between records, for epochs within the DE441 span.

get_state_at_epoch(epoch) staticmethod

Returns the Moon's Cartesian state in TEME at the given epoch.

Uses the DE441 ephemeris (~5 m at the daily record epochs, up to ~3 km between records). Triggers lazy load of the ephemeris file on first call. Velocity is the Hermite-interpolated record velocity plus the small TEME frame-drift term (≈ 3 mm/s) that keeps the stored TEME series differentiable.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch in any supported time system.	required

Returns:

Type	Description
Optional[CartesianState]	CartesianState in TEME
Optional[CartesianState]	[km, km/s] if the epoch is within the ephemeris span,
Optional[CartesianState]	otherwise None.

Satellite

A spacecraft that can be propagated, analyzed, and used for event detection.

A Satellite may hold a TLE, a Cartesian state, or a pre-computed Ephemeris. The propagator is chosen automatically: SGP4/SDP4 for TLE-backed satellites, numerical XP integration otherwise.

State mutations follow a builder pattern for the with_* methods (which return a new copy) and direct property assignment for mutable fields such as id and dry_mass.

Attributes:

Name	Type	Description
id	str	Unique string identifier.
name	str | None	Optional human-readable name.
norad_id	int | None	NORAD catalog number, if known.
tle	TLE | None	Two-Line Element set.
keplerian_state	KeplerianState | None	Keplerian state derived from the TLE or Cartesian state.
cartesian_state	CartesianState | None	Current Cartesian state in TEME [km, km/s].
ephemeris	Ephemeris | None	Pre-computed ephemeris.
dry_mass	float	Structural mass without propellant [kg].
wet_mass	float	Total mass including propellant in all tanks [kg].
drag_area	float	Effective aerodynamic cross-sectional area [m²].
drag_coefficient	float	Aerodynamic drag coefficient [dimensionless; typically 2.0–2.5].
srp_area	float	Effective solar-radiation-pressure area [m²].
srp_coefficient	float	SRP reflectivity coefficient [dimensionless; typically 1.0–2.0].
tanks	list[Tank]	Propellant tanks.
thrusters	list[Thruster]	Thrusters with tank connections.
periapsis	float | None	Periapsis radius from Earth's center [km], or None if no orbit is defined.
apoapsis	float | None	Apoapsis radius from Earth's center [km], or None if no orbit is defined.
period	float | None	Orbital period [s], or None if no orbit is defined.
geodetic_position	GeodeticPosition | None	WGS84 geodetic position derived from the current state.

apoapsis property

Apoapsis radius from Earth's center [km], or None if no orbit is defined.

Computed as a (1 + e) from the TLE-derived Keplerian elements; this is the distance from Earth's center, not the altitude above the surface.

cartesian_state property writable

Current Cartesian state in TEME [km, km/s], or None if not set.

covariance property

Attached state covariance, or None if no covariance has been set.

State propagation does not touch the covariance; see covariance_at_epoch for the opt-in propagation entry point.

drag_area property writable

Effective aerodynamic cross-sectional area [m²].

drag_coefficient property writable

Aerodynamic drag coefficient Cd [dimensionless; typically 2.0–2.5].

dry_mass property writable

Structural mass without propellant [kg].

ephemeris property writable

Pre-computed ephemeris, or None if not set.

geodetic_position property

Current WGS84 geodetic position, or None if no state is available.

Raises:

Type	Description
ValueError	If the coordinate conversion fails.

id property writable

Unique string identifier.

keplerian_state property

Keplerian state derived from the TLE or Cartesian state, or None if no state is available.

Raises:

Type	Description
ValueError	If the Cartesian-to-Keplerian conversion fails.

name property writable

Optional human-readable name, or None if not set.

norad_id property writable

NORAD catalog number, or None if not set.

periapsis property

Periapsis radius from Earth's center [km], or None if no orbit is defined.

Computed as a (1 - e) from the TLE-derived Keplerian elements; this is the distance from Earth's center, not the altitude above the surface.

period property

Orbital period [s], or None if no orbit is defined.

srp_area property writable

Effective solar-radiation-pressure area [m²].

srp_coefficient property writable

Solar-radiation-pressure reflectivity coefficient Cr [dimensionless; typically 1.0–2.0].

tanks property

Propellant tanks.

thrusters property

Thrusters with tank connections.

tle property writable

Two-Line Element set, or None if not set.

wet_mass property

Total mass including all tank propellant [kg].

__init__()

Creates a default Satellite with no orbit, no mass, and a blank ID.

cache_ephemeris(start, end, step, reference_frame=...)

Generates and caches an ephemeris over the specified time window.

Propagates at each step from start to end (inclusive) and stores the states for fast lookup.

Parameters:

Name	Type	Description	Default
start	ModifiedJulianDate	Start of the ephemeris window.	required
end	ModifiedJulianDate	End of the ephemeris window.	required
step	TimeSpan	Propagation step size.	required
reference_frame	ReferenceFrame | None	Frame for the cached states; defaults to TEME.	...

Returns:

Type	Description
Ephemeris	Ephemeris over the requested window.

Raises:

Type	Description
ValueError	If no orbit is set, or propagation or frame transform fails.

characterize_stability(observations, min_period, max_period, max_fractional_error=..., threshold_odds_ratio=...)

Characterize stability via phase-folding string length.

Searches a grid of candidate periods, phase-folds the lightcurve at each, and scores it by the total Euclidean path length around the phase-magnitude loop. The period that minimizes the path length is the best fit; reported only when it beats a randomized baseline by threshold_odds_ratio.

Parameters:

Name	Type	Description	Default
observations	list[Observation]	Photometric observations. Entries without visual_magnitude are dropped.	required
min_period	float	Lower bound of the search [s; > 0].	required
max_period	float	Upper bound of the search [s; >= min_period].	required
max_fractional_error	float	Target relative grid resolution per period [dimensionless; > 0]. Defaults to 0.001.	...
threshold_odds_ratio	float	Detection threshold; the best string length must be no more than prior / threshold_odds_ratio for a period to be reported [dimensionless; > 1]. Defaults to 2.0.	...

Returns:

Type	Description
AttitudeCharacterization	AttitudeCharacterization with log_odds set
AttitudeCharacterization	to None (string-length does not produce a log-odds
AttitudeCharacterization	score).

characterize_stability_gregory_loredo(observations, min_period, max_period, max_fractional_error=..., log_odds_threshold=...)

Characterize stability via the Gregory-Loredo Bayesian binned-phase periodogram.

Marginalizes over phase-bin counts (default (2, 12)) so the data picks the model complexity. Rejects P/2 aliases on multi-peaked tumblers — a fixed m=2 model would prefer the half-period because two flashes per rotation fold onto each other.

Parameters:

Name	Type	Description	Default
observations	list[Observation]	Photometric observations. Entries without visual_magnitude are dropped.	required
min_period	float	Lower bound of the search [s; > 0].	required
max_period	float	Upper bound of the search [s; >= min_period].	required
max_fractional_error	float	Target relative grid resolution per period [dimensionless; > 0]. Defaults to 0.005.	...
log_odds_threshold	float	Detection threshold [nats; >= 0]. The best log Bayes factor must exceed this to report a period (e.g. 5.0 ~ 148x more likely than the constant-brightness model). Defaults to 5.0.	...

Returns:

Type	Description
AttitudeCharacterization	AttitudeCharacterization with log_odds
AttitudeCharacterization	populated.

characterize_stability_quasi_periodic_gp(observations, min_period, max_period, max_fractional_error=..., log_odds_threshold=...)

Characterize stability via the quasi-periodic Gaussian-process periodogram.

Models the lightcurve with a quasi-periodic kernel k(tau) = sigma_f^2 * exp(-tau^2/(2 L^2)) * exp(-2 sin^2(pi tau / P) / lambda^2) (MacKay 1998). The squared-exponential envelope of length scale L lets correlation decay over time, so a tumbler whose spin rate drifts across a campaign isn't unfairly penalized — unlike the binned-phase Gregory-Loredo model, which assumes a stationary period.

Hyperparameters are auto-derived from the data. Requires at least 10 valid observations.

Parameters:

Name	Type	Description	Default
observations	list[Observation]	Photometric observations. Entries without visual_magnitude are dropped.	required
min_period	float	Lower bound of the search [s; > 0].	required
max_period	float	Upper bound of the search [s; >= min_period].	required
max_fractional_error	float	Target relative grid resolution per period [dimensionless; > 0]. Defaults to 0.01.	...
log_odds_threshold	float	Detection threshold [nats; >= 0]. The best QP-GP log marginal likelihood must exceed the noise-only baseline by this margin to report a period. Defaults to 5.0.	...

Returns:

Type	Description
AttitudeCharacterization	AttitudeCharacterization with log_odds
AttitudeCharacterization	populated.

clear_ephemeris_cache()

Returns a copy of this satellite with the ephemeris cache cleared.

Returns:

Type	Description
Satellite	Satellite with no cached ephemeris.

covariance_at_epoch(target_epoch, priority=None)

Propagates the attached covariance to target_epoch.

Algorithm selection follows PerformancePriority:

• Speed — series-truncated two-body STM. Cheap, accurate only for short arcs in near-Keplerian regimes.
• Balanced — Van der Merwe scaled Unscented Transform with 13 sigma points propagated through the configured integrator.
• Precision — Monte Carlo with 1000 samples through the configured integrator. Gold-standard reference. Significantly slower than Balanced; deterministic (fixed PRNG seed).

priority = None defers to the priority configured on this satellite's integrator.

Covariance propagation requires cartesian_state to be set (it defines the source-epoch reference). SGP4-backed satellites should call with_cartesian_state first to pin the initial state into the integrator path.

Parameters:

Name	Type	Description	Default
target_epoch	ModifiedJulianDate	Target propagation epoch.	required
priority	PerformancePriority | None	Algorithm selector; None uses the integrator's configured priority.	None

Returns:

Type	Description
CovarianceMatrix	Propagated covariance at target_epoch. The
CovarianceMatrix	covariance_type of the result matches the input — RIC in →
CovarianceMatrix	RIC out (re-rotated against the propagated state),
CovarianceMatrix	Inertial(F) in → Inertial(F) out. Matrices larger than
CovarianceMatrix	6×6 keep appended drag/SRP parameter axes; those axes are
CovarianceMatrix	identity-mapped while the orbital block and its
CovarianceMatrix	cross-covariances are propagated. For these larger matrices,
CovarianceMatrix	Balanced and Precision currently use the same
CovarianceMatrix	block-linear propagation map as Speed.

Raises:

Type	Description
ValueError	If no covariance is attached, no cartesian_state is set, propagation fails, or Cholesky decomposition of the input covariance fails (UT path requires positive-definite input).

execute_maneuver(maneuver, thruster=...)

Executes an impulsive or finite-burn maneuver.

Updates the satellite's state in place and returns a summary of the burn.

Parameters:

Name	Type	Description	Default
maneuver	Maneuver	Maneuver definition (epoch, delta-v or burn duration).	required
thruster	str | None	Identifier of the thruster to use, or None to use the first available thruster.	...

Returns:

Type	Description
ManeuverResult	ManeuverResult with pre/post-burn
ManeuverResult	states and propellant consumed.

Raises:

Type	Description
ValueError	If no orbit is set, the thruster is not found, or propagation fails.

from_citra_elset(payload) staticmethod

Creates a Satellite from a CITRA elset dictionary.

Required keys: id, satellite_id, epoch, type, semi_major_axis, inclination, raan, eccentricity, argument_of_perigee, mean_anomaly, mean_motion_dot, mean_motion_dot_dot, b_star, ballistic_coefficient, srp_coefficient. Optional key: satellite_name.

Parameters:

Name	Type	Description	Default
payload	dict[str, object]	Dictionary containing the CITRA elset fields.	required

Returns:

Type	Description
Satellite	Satellite initialized from the elset.

Raises:

Type	Description
ValueError	If a required key is missing or the epoch string cannot be parsed.

from_tle(tle) staticmethod

Creates a Satellite from a Two-Line Element set.

The satellite id is set to the TLE name if non-empty, otherwise to the NORAD catalog number string.

Parameters:

Name	Type	Description	Default
tle	TLE	Two-Line Element set to initialize the satellite.	required

Returns:

Type	Description
Satellite	Satellite backed by SGP4/SDP4 propagation.

from_tles(satellite_id, tles, start, end, step, reference_frame=...) staticmethod

Builds a satellite with ephemeris stitched from multiple element sets.

The element sets describe one object. They are sorted by epoch and de-duplicated (sets within 1 ms of one another collapse to the latest). Only the sets relevant to [start, end] are propagated — from the last set with epoch <= start through the first with epoch >= end. With a single relevant set the result is a plain SGP4 arc; with several, one arc is propagated per set across the span between consecutive epochs, the arcs are joined at their closest-approach crossovers (see Ephemeris.stitch), and the folded arc is resampled onto the uniform [start, end, step] grid. The returned satellite carries this ephemeris as its cached state source and the freshest element set as its TLE metadata.

Parameters:

Name	Type	Description	Default
satellite_id	str	Identifier assigned to the satellite and its ephemeris.	required
tles	list[TLE]	Element sets for one object, in any order.	required
start	ModifiedJulianDate	Start of the ephemeris window.	required
end	ModifiedJulianDate	End of the ephemeris window.	required
step	TimeSpan	Propagation / resampling step.	required
reference_frame	ReferenceFrame | None	Frame for the cached states; defaults to TEME.	...

Returns:

Type	Description
Satellite	Satellite whose cached Ephemeris
Satellite	covers [start, end].

Raises:

Type	Description
ValueError	If tles is empty, the step or window is invalid, propagation fails, or two consecutive arcs do not overlap.

get_body_angles_at_epoch(other, epoch)

Computes the boresight-to-body angles between this satellite and another.

Parameters:

Name	Type	Description	Default
other	Satellite	Target satellite.	required
epoch	ModifiedJulianDate	Epoch at which to compute the angles.	required

Returns:

Type	Description
Optional[BoreToBodyAngles]	BoreToBodyAngles if both states are
Optional[BoreToBodyAngles]	available, otherwise None.

Raises:

Type	Description
ValueError	If propagation fails.

get_close_approach(other, start, end, distance_threshold)

Searches for the first close approach to another satellite.

Parameters:

Name	Type	Description	Default
other	Satellite	The other satellite to check against.	required
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
distance_threshold	float	Maximum range to count as a close approach [km; > 0].	required

Returns:

Type	Description
Optional[CloseApproach]	CloseApproach if one occurs,
Optional[CloseApproach]	otherwise None.

Raises:

Type	Description
ValueError	If propagation fails.

get_coverage_grid(sensor, sites, start, end, step, metric=..., min_observations=...)

Scores how well a sensor observes this satellite from each site.

Builds this satellite's ephemeris once over [start, end], then evaluates sensor (using its constraints, treated as a steerable ground site) against it from each candidate site. The grid rows pair 1:1 with sites. For a single satellite, CoverageMetric.UniqueSatellitesCovered degenerates to 0/1; prefer PassCount or TotalAccessTime.

Parameters:

Name	Type	Description	Default
sensor	Sensor	Sensor whose constraints gate visibility.	required
sites	list[GeodeticPosition]	Candidate ground locations (1:1 with the grid rows).	required
start	ModifiedJulianDate	Start of the evaluation window.	required
end	ModifiedJulianDate	End of the evaluation window.	required
step	TimeSpan	Ephemeris sampling step for the satellite.	required
metric	CoverageMetric	How each site is scored; defaults to CoverageMetric.UniqueSatellitesCovered.	...
min_observations	int	Windows required to count as covered; defaults to 1.	...

Returns:

Type	Description
CoverageGrid	CoverageGrid with one entry per site.

Raises:

Type	Description
ValueError	If the satellite ephemeris cannot be built.

get_horizon_access_report(observers, start, end, min_elevation, min_duration)

Computes horizon access intervals for a set of ground observers.

Returns all pass windows where the satellite elevation exceeds min_elevation for at least min_duration.

Parameters:

Name	Type	Description	Default
observers	list[GeodeticPosition]	List of ground observer positions.	required
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
min_elevation	float	Minimum elevation angle [rad; >= 0].	required
min_duration	TimeSpan	Minimum pass duration.	required

Returns:

Type	Description
Optional[HorizonAccessReport]	HorizonAccessReport if any passes
Optional[HorizonAccessReport]	occur, otherwise None.

Raises:

Type	Description
ValueError	If propagation fails.

get_maneuver_event(future_sat, start, end, distance_threshold, velocity_threshold)

Detects whether a maneuver occurred between two ephemeris epochs.

Compares states from this satellite and future_sat over [start, end].

Parameters:

Name	Type	Description	Default
future_sat	Satellite	The satellite representing the post-maneuver state.	required
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
distance_threshold	float	Position difference threshold [km; > 0].	required
velocity_threshold	float	Velocity difference threshold [km/s; > 0].	required

Returns:

Type	Description
Optional[ManeuverEvent]	ManeuverEvent if a maneuver is
Optional[ManeuverEvent]	detected, otherwise None.

Raises:

Type	Description
ValueError	If propagation fails.

get_next_apogee_epoch()

Propagates forward to find the next apogee epoch.

Returns:

Type	Description
ModifiedJulianDate	ModifiedJulianDate of the next apogee.

Raises:

Type	Description
ValueError	If no orbit is set or propagation fails.

get_next_ascending_node_epoch()

Propagates forward to find the next ascending node epoch.

Returns:

Type	Description
ModifiedJulianDate	ModifiedJulianDate of the next ascending
ModifiedJulianDate	node crossing.

Raises:

Type	Description
ValueError	If no orbit is set or propagation fails.

get_next_descending_node_epoch()

Propagates forward to find the next descending node epoch.

Returns:

Type	Description
ModifiedJulianDate	ModifiedJulianDate of the next descending
ModifiedJulianDate	node crossing.

Raises:

Type	Description
ValueError	If no orbit is set or propagation fails.

get_next_node_epoch()

Propagates forward to find the next equatorial node crossing.

Returns the earlier of the next ascending or descending node.

Returns:

Type	Description
ModifiedJulianDate	ModifiedJulianDate of the next node.

Raises:

Type	Description
ValueError	If no orbit is set or propagation fails.

get_next_perigee_epoch()

Propagates forward to find the next perigee epoch.

Returns:

Type	Description
ModifiedJulianDate	ModifiedJulianDate of the next perigee.

Raises:

Type	Description
ValueError	If no orbit is set or propagation fails.

get_next_tangent_epoch()

Propagates forward to find the next tangent-pass epoch.

A tangent pass is the moment when the line-of-sight from the satellite to a ground observer is tangent to Earth's surface.

Returns:

Type	Description
ModifiedJulianDate	ModifiedJulianDate of the next tangent
ModifiedJulianDate	pass.

Raises:

Type	Description
ValueError	If no orbit is set or propagation fails.

get_observation_at_epoch(sensor, epoch, observer=..., reference_frame=...)

Simulates an observation of this satellite from a sensor at the given epoch.

Parameters:

Name	Type	Description	Default
sensor	Sensor	Sensor model providing noise parameters and modality.	required
epoch	ModifiedJulianDate	Epoch at which to generate the observation.	required
observer	GeodeticPosition | None	Ground observer location; required for topocentric observations (optical / DOA), ignored for space-based.	...
reference_frame	ReferenceFrame | None	Reference frame for propagation; defaults to TEME.	...

Returns:

Type	Description
Observation	Observation with simulated
Observation	measurements.

Raises:

Type	Description
ValueError	If no orbit is set, propagation fails, or the sensor type is incompatible with the observer configuration.

get_plot_data(start, end, step)

Generates orbit plot data over a time window.

Parameters:

Name	Type	Description	Default
start	ModifiedJulianDate	Start of the plot window.	required
end	ModifiedJulianDate	End of the plot window.	required
step	TimeSpan	Propagation step size.	required

Returns:

Type	Description
Optional[OrbitPlotData]	OrbitPlotData if the satellite has
Optional[OrbitPlotData]	an orbit, otherwise None.

Raises:

Type	Description
ValueError	If propagation fails.

get_proximity_report(other, start, end, distance_threshold)

Generates a proximity event report between this satellite and another.

Records all intervals where the inter-satellite range is within distance_threshold.

Parameters:

Name	Type	Description	Default
other	Satellite	The other satellite to check against.	required
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
distance_threshold	float	Maximum range to count as a proximity event [km; > 0].	required

Returns:

Type	Description
Optional[ProximityReport]	ProximityReport if any events occur,
Optional[ProximityReport]	otherwise None.

Raises:

Type	Description
ValueError	If propagation fails.

get_relative_state_at_epoch(other, epoch)

Computes the RIC relative state of this satellite with respect to another.

Equivalent to calling relative_to with Rotating.

Parameters:

Name	Type	Description	Default
other	Satellite	Reference satellite (origin of the RIC frame).	required
epoch	ModifiedJulianDate	Epoch at which to compute the relative state.	required

Returns:

Type	Description
Optional[CartesianState]	CartesianState in the RIC frame,
Optional[CartesianState]	or None if either satellite has no state at the epoch.

Raises:

Type	Description
ValueError	If propagation or frame transform fails.

get_residuals(obs)

Computes observation residuals against a set of measurements.

Parameters:

Name	Type	Description	Default
obs	list[Observation]	List of observations to compute residuals for.	required

Returns:

Type	Description
list[ObservationResidual]	list[ObservationResidual]: One
list[ObservationResidual]	residual per observation.

Raises:

Type	Description
ValueError	If propagation fails for any observation epoch.

get_rms(obs)

Computes the RMS observation residual.

Parameters:

Name	Type	Description	Default
obs	list[Observation]	List of observations to evaluate.	required

Returns:

Name	Type	Description
float	float	Root-mean-square residual [rad for optical; km for radar].

Raises:

Type	Description
ValueError	If propagation fails or the list is empty.

get_state_at_epoch(epoch, reference_frame=...)

Propagates the satellite to the given epoch and returns the state.

Uses SGP4/SDP4 for TLE-backed satellites; uses the numerical XP integrator otherwise. The result frame defaults to TEME.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Target propagation epoch.	required
reference_frame	ReferenceFrame | None	Output reference frame; defaults to TEME.	...

Returns:

Type	Description
CartesianState	CartesianState at the requested epoch
CartesianState	in the requested frame.

Raises:

Type	Description
ValueError	If no orbit is set, the frame transform fails, or propagation fails — including when the SGP4-propagated orbit has decayed (osculating radius below one Earth radius, AFSPC/Vallado error code 6), so callers never receive a sub-surface position. Decay is evaluated per query epoch, matching the reference implementation.

get_weighted_rms(obs)

Computes the noise-weighted RMS observation residual.

Each residual is divided by the sensor's 1-sigma noise before squaring, so the result is dimensionless (number of sigma).

Parameters:

Name	Type	Description	Default
obs	list[Observation]	List of observations to evaluate.	required

Returns:

Name	Type	Description
float	float	Noise-weighted RMS residual [dimensionless; number of σ].

Raises:

Type	Description
ValueError	If propagation fails, the list is empty, or any observation has no associated noise value.

optimize_sensor_locations(sensors, sites, start, end, step, metric=..., min_observations=..., allow_multisite=..., co_detection_bonus=...)

Picks where to place a list of sensors to best observe this satellite.

See Constellation.optimize_sensor_locations for the full semantics. For a single satellite the multisite greedy objective is only meaningful under additive metrics (PassCount / TotalAccessTime), since unique-satellite coverage saturates at one.

Parameters:

Name	Type	Description	Default
sensors	list[Sensor]	Sensors to place (each carries its own constraints).	required
sites	list[GeodeticPosition]	Candidate ground locations.	required
start	ModifiedJulianDate	Start of the evaluation window.	required
end	ModifiedJulianDate	End of the evaluation window.	required
step	TimeSpan	Ephemeris sampling step for the satellite.	required
metric	CoverageMetric	Objective and per-sensor grid metric; defaults to CoverageMetric.UniqueSatellitesCovered.	...
min_observations	int	Windows required to count as covered; defaults to 1.	...
allow_multisite	bool	True for distinct sites, False (default) to co-locate.	...
co_detection_bonus	float	Co-detection weight for CoverageMetric.MultiSensorCoverage (value = k + bonus*C(k,2)); defaults to 1.0 and is ignored by the other metrics.	...

Returns:

Type	Description
SensorPlacementReport	SensorPlacementReport.

Raises:

Type	Description
ValueError	On an empty sensor or site list, when multisite is requested with fewer sites than sensors, or if the satellite ephemeris cannot be built.

relative_to(origin, epoch, frame)

Computes the relative state of this satellite with respect to another.

Parameters:

Name	Type	Description	Default
origin	Satellite	Reference satellite (origin of the relative frame).	required
epoch	ModifiedJulianDate	Epoch at which to compute the relative state.	required
frame	RelativeFrame	Reference frame for the output (Rotating or Inertial).	required

Returns:

Type	Description
Optional[CartesianState]	CartesianState in the requested
Optional[CartesianState]	frame, or None if either satellite has no state at the epoch.

Raises:

Type	Description
ValueError	If propagation or frame transform fails.

to_advanced_state_bundle()

Builds an AdvancedStateBundle from the current state.

Produces four representations of the same satellite state at a single epoch — osculating Cartesian, osculating Keplerian, a MeanKozaiGP TLE, and a MeanBrouwerXP TLE — produced atomically from a single propagated arc. Top-level drag_coefficient and srp_coefficient pass through from the satellite's properties; the same values flow into each fitted TLE's force terms as Cd · A / m and Cr · A / m respectively.

Returns:

Type	Description
AdvancedStateBundle	AdvancedStateBundle: A
AdvancedStateBundle	populated bundle.

Raises:

Type	Description
ValueError	If the satellite has no resolvable state or either underlying BLS fit (MeanKozaiGP or MeanBrouwerXP) fails to converge. Partial bundles are never returned.

to_tle(keplerian_type)

Converts the current state to a Two-Line Element set.

Parameters:

Name	Type	Description	Default
keplerian_type	KeplerianType	Averaging theory for the output TLE.	required

Returns:

Type	Description
TLE	TLE in the requested element type.

Raises:

Type	Description
ValueError	If no state is set or the conversion fails.

with_cartesian_state(cartesian_state)

Returns a copy of this satellite with the given Cartesian state.

Parameters:

Name	Type	Description	Default
cartesian_state	CartesianState	State vector in TEME [km, km/s].	required

Returns:

Type	Description
Satellite	Satellite with the updated Cartesian state.

with_covariance(covariance)

Returns a copy of this satellite with the given state covariance attached.

State propagation via get_state_at_epoch is unaffected — the covariance only participates when covariance_at_epoch is called explicitly.

Parameters:

Name	Type	Description	Default
covariance	CovarianceMatrix	Covariance to attach. Its covariance_type determines how the matrix entries are interpreted (Cartesian inertial / Cartesian RIC / equinoctial element-set).	required

Returns:

Type	Description
Satellite	Satellite with the covariance attached.

with_dry_mass(kg)

Returns a copy of this satellite with the given dry mass.

Parameters:

Name	Type	Description	Default
kg	float	Structural mass without propellant [kg; >= 0].	required

Returns:

Type	Description
Satellite	Satellite with the updated dry mass.

with_ephemeris(ephemeris)

Returns a copy of this satellite with the given pre-computed ephemeris.

Parameters:

Name	Type	Description	Default
ephemeris	Ephemeris	Pre-computed ephemeris to assign.	required

Returns:

Type	Description
Satellite	Satellite with the updated ephemeris.

with_id(id)

Returns a copy of this satellite with the given identifier.

Parameters:

Name	Type	Description	Default
id	str	New unique string identifier.	required

Returns:

Type	Description
Satellite	Satellite with the updated identifier.

with_name(name)

Returns a copy of this satellite with the given name.

Parameters:

Name	Type	Description	Default
name	Optional[str]	Human-readable name, or None to clear it.	required

Returns:

Type	Description
Satellite	Satellite with the updated name.

with_tank(tank)

Returns a copy of this satellite with the given tank added.

Parameters:

Name	Type	Description	Default
tank	Tank	Propellant tank to add.	required

Returns:

Type	Description
Satellite	Satellite with the tank appended.

with_thruster(thruster)

Returns a copy of this satellite with the given thruster added.

Parameters:

Name	Type	Description	Default
thruster	Thruster	Thruster to add.	required

Returns:

Type	Description
Satellite	Satellite with the thruster appended.

with_tle(tle)

Returns a copy of this satellite with the given TLE.

Setting a TLE clears any existing Cartesian state and ephemeris.

Parameters:

Name	Type	Description	Default
tle	TLE	Two-Line Element set to assign.	required

Returns:

Type	Description
Satellite	Satellite backed by the new TLE.

Sensor

A measurement sensor attached to a satellite or ground station.

Noise parameters are 1-sigma values for each measurement type. Set only the parameters relevant to the sensor's modality; unused noise fields default to None.

Attributes:

Name	Type	Description
id	str	Auto-generated UUID identifier.
name	str | None	Optional human-readable label.
angular_noise	float | None	1-sigma angular measurement noise [rad].
range_noise	float | None	1-sigma range measurement noise [km].
range_rate_noise	float | None	1-sigma range-rate measurement noise [km/s].
angular_rate_noise	float | None	1-sigma angular-rate measurement noise [rad/s].
constraints	SensorConstraints	Geometry, range, and lighting gates describing what the sensor can observe. Defaults to the permissive SensorConstraints().

angular_noise property writable

1-sigma angular measurement noise [rad], or None if not set.

angular_rate_noise property writable

1-sigma angular-rate measurement noise [rad/s], or None if not set.

constraints property writable

Geometry, range, and lighting gates describing what the sensor can observe.

id property writable

Auto-generated UUID identifier.

name property writable

Optional human-readable label, or None if not set.

range_noise property writable

1-sigma range measurement noise [km], or None if not set.

range_rate_noise property writable

1-sigma range-rate measurement noise [km/s], or None if not set.

__init__(angular_noise=...)

Creates a new Sensor with a random UUID identifier.

All noise fields except angular_noise are initialized to None.

Parameters:

Name	Type	Description	Default
angular_noise	Optional[float]	1-sigma angular measurement noise [rad]. Pass None for a non-optical sensor.	...

SensorCalibrationLimits

Per-sensor inclusive bounds on measurement noise, applied as a clamp during observation ingest.

Reported and audit-baseline noise values are frequently unphysical — some optical records claim milli-arcsecond pointing noise, some baselines claim tens of degrees — and either extreme breaks the filter's chi-squared gate (absurdly tight noise rejects good observations; absurdly loose noise lets blunders through). SensorCalibrationLimits bounds each Sensor noise field to a sane range after any per-sensor calibration override is applied.

Each dimension carries an independent minimum_*_noise floor and maximum_*_noise ceiling; both are optional. A None bound leaves that side unclamped, so a one-sided clamp (floor only, or ceiling only) is expressible. Angular and angular-rate bounds are expressed in degrees (and degrees per second) and converted to radians when applied to a sensor; range, range-rate, and TDOA bounds use native units (km, km/s, s).

Use telescope and antenna for the default bounds of each sensor type, or construct directly with explicit bounds.

Attributes:

Name	Type	Description
minimum_angular_noise	float | None	Angular-noise floor [deg], or None.
maximum_angular_noise	float | None	Angular-noise ceiling [deg], or None.
minimum_angular_rate_noise	float | None	Angular-rate-noise floor [deg/s], or None.
maximum_angular_rate_noise	float | None	Angular-rate-noise ceiling [deg/s], or None.
minimum_range_noise	float | None	Range-noise floor [km], or None.
maximum_range_noise	float | None	Range-noise ceiling [km], or None.
minimum_range_rate_noise	float | None	Range-rate-noise floor [km/s], or None.
maximum_range_rate_noise	float | None	Range-rate-noise ceiling [km/s], or None.
minimum_tdoa_noise	float | None	TDOA-noise floor [s], or None.
maximum_tdoa_noise	float | None	TDOA-noise ceiling [s], or None.

__init__(minimum_angular_noise=..., maximum_angular_noise=..., minimum_angular_rate_noise=..., maximum_angular_rate_noise=..., minimum_range_noise=..., maximum_range_noise=..., minimum_range_rate_noise=..., maximum_range_rate_noise=..., minimum_tdoa_noise=..., maximum_tdoa_noise=...)

Create noise limits with the given bounds.

Every bound is optional; a None bound leaves that side unclamped.

Parameters:

Name	Type	Description	Default
minimum_angular_noise	float | None	Angular-noise floor [deg], or None.	...
maximum_angular_noise	float | None	Angular-noise ceiling [deg], or None.	...
minimum_angular_rate_noise	float | None	Angular-rate-noise floor [deg/s], or None.	...
maximum_angular_rate_noise	float | None	Angular-rate-noise ceiling [deg/s], or None.	...
minimum_range_noise	float | None	Range-noise floor [km], or None.	...
maximum_range_noise	float | None	Range-noise ceiling [km], or None.	...
minimum_range_rate_noise	float | None	Range-rate-noise floor [km/s], or None.	...
maximum_range_rate_noise	float | None	Range-rate-noise ceiling [km/s], or None.	...
minimum_tdoa_noise	float | None	TDOA-noise floor [s], or None.	...
maximum_tdoa_noise	float | None	TDOA-noise ceiling [s], or None.	...

antenna() staticmethod

Default noise bounds for an antenna (radar / DOA sensor).

Bounds angular noise to [0.05, 0.5] deg, angular-rate noise to [1e-4, 0.1] deg/s, range noise to [0.25, 5.0] km, range-rate noise to [0.001, 0.05] km/s, and TDOA noise to [1e-8, 1e-7] s.

Returns:

Type	Description
SensorCalibrationLimits	Antenna-appropriate bounds.

telescope() staticmethod

Default noise bounds for a telescope (optical sensor).

Bounds angular noise to [0.0003, 0.03] deg and angular-rate noise to [1e-5, 1e-2] deg/s. Range, range-rate, and TDOA bounds are left None because telescopes do not measure those quantities.

Returns:

Type	Description
SensorCalibrationLimits	Telescope-appropriate bounds.

SensorConstraints

Geometry, lighting, and dwell-time gates applied to a sensor's line of sight.

Permissive defaults — maximum_target_angle = π, all minimum angles 0, maximum_range infinite, both eclipse flags True, minimum_duration zero — make a default-constructed SensorConstraints impose no gating, so downstream access methods can apply the same predicate regardless of whether the user customized any field.

For a ground site, the elevation mask is expressed through minimum_earth_angle (measured from the observer's geocentric nadir): set minimum_earth_angle = π/2 + min_elevation to require min_elevation above the local horizon. π/2 is the bare horizon.

Attributes:

Name	Type	Description
maximum_target_angle	float	Max angle from boresight at which a target remains in the field of view [rad; 0..π].
minimum_sun_angle	float	Minimum angle between the line of sight and the Sun direction [rad; 0..π].
minimum_earth_angle	float	Minimum angle between the line of sight and the Earth-center direction [rad; 0..π]. Doubles as a ground-sensor elevation mask (π/2 + min_elevation).
minimum_moon_angle	float	Minimum angle between the line of sight and the Moon direction [rad; 0..π].
maximum_range	float	Maximum slant range from the sensor host to the target [km; > 0]. float('inf') (default) disables it.
allow_target_eclipse	bool	If False, the observed body must not be in Earth's shadow.
allow_sensor_eclipse	bool	If False, the sensor host must not be in Earth's shadow.
minimum_duration	TimeSpan	Minimum dwell time required for an access window to be reported. Windows shorter than this are filtered out of the final report. Default zero (no filter).

allow_sensor_eclipse property writable

True if sensor-host eclipses are allowed, False if they are rejected.

allow_target_eclipse property writable

True if observed-body eclipses are allowed, False if they are rejected.

maximum_range property writable

Maximum slant range from the sensor host to the target [km; > 0]; infinite disables the gate.

maximum_target_angle property writable

Maximum angle from boresight at which a target remains in the field of view [rad; 0..π].

minimum_duration property writable

Minimum dwell time required for an access window to be reported; zero disables the filter.

minimum_earth_angle property writable

Minimum angle between the line of sight and the Earth-center direction [rad; 0..π].

minimum_moon_angle property writable

Minimum angle between the line of sight and the Moon direction [rad; 0..π].

minimum_sun_angle property writable

Minimum angle between the line of sight and the Sun direction [rad; 0..π].

__init__(maximum_target_angle=..., minimum_sun_angle=..., minimum_earth_angle=..., minimum_moon_angle=..., maximum_range=..., allow_target_eclipse=..., allow_sensor_eclipse=..., minimum_duration=...)

Creates a new SensorConstraints.

All arguments default to the permissive values described in the class docstring.

Parameters:

Name	Type	Description	Default
maximum_target_angle	float	Max angle from boresight at which a target remains in the field of view [rad; 0..π].	...
minimum_sun_angle	float	Minimum angle between the line of sight and the Sun direction [rad; 0..π].	...
minimum_earth_angle	float	Minimum angle between the line of sight and the Earth-center direction [rad; 0..π].	...
minimum_moon_angle	float	Minimum angle between the line of sight and the Moon direction [rad; 0..π].	...
maximum_range	float	Maximum slant range from the sensor host to the target [km; > 0]. float('inf') (default) disables the gate.	...
allow_target_eclipse	bool	If False, the observed body must not be in Earth's shadow.	...
allow_sensor_eclipse	bool	If False, the sensor host must not be in Earth's shadow.	...
minimum_duration	Optional[TimeSpan]	Minimum dwell time required for an access window to survive the report. None (the default) is equivalent to a zero TimeSpan and disables the filter.	...

Sun

Sun ephemeris backed by the DE441 Horizons data file.

All methods are static; no instantiation is required. State positions and velocities are in TEME (NASA Horizons J2000 records are converted to TEME at ephemeris-load time). Position accuracy vs JPL: ~0.2 km at the daily record epochs, up to ~1.5 km between records, for epochs within the DE441 span.

get_state_at_epoch(epoch) staticmethod

Returns the Sun's Cartesian state in TEME at the given epoch.

Uses the DE441 ephemeris (~0.2 km at the daily record epochs, up to ~1.5 km between records). Triggers lazy load of the ephemeris file on first call. Velocity is the Hermite-interpolated record velocity plus the small TEME frame-drift term (≈ 1.2 m/s) that keeps the stored TEME series differentiable.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch in any supported time system.	required

Returns:

Type	Description
Optional[CartesianState]	CartesianState in TEME
Optional[CartesianState]	[km, km/s] if the epoch is within the ephemeris span,
Optional[CartesianState]	otherwise None.

Tank

A propellant tank on a satellite.

Tracks the current propellant mass. Multiple tanks may be connected to a single Thruster via TankConnection.

Attributes:

Name	Type	Description
id	str	Human-readable identifier (e.g. "hydrazine").
mass	float	Current propellant mass [kg; >= 0].

id property

Human-readable identifier.

mass property

Current propellant mass [kg; >= 0].

__init__(id, mass)

Creates a new Tank.

Parameters:

Name	Type	Description	Default
id	str	Human-readable identifier (e.g. "hydrazine").	required
mass	float	Initial propellant mass [kg; >= 0].	required

__repr__()

Returns Tank(id='…', mass=…).

TankConnection

Links a thruster to a propellant tank with a fractional draw rate.

All TankConnection fractions for a given Thruster must sum to 1.0.

Attributes:

Name	Type	Description
tank_id	str	References a id.
fraction	float	Fraction of total mass flow drawn from this tank [dimensionless; 0..=1].

fraction property

Fraction of total mass flow drawn from this tank [dimensionless; 0..=1].

tank_id property

Referenced tank identifier.

__init__(tank_id, fraction)

Creates a new TankConnection.

Parameters:

Name	Type	Description	Default
tank_id	str	References a id.	required
fraction	float	Fraction of total mass flow drawn from this tank [dimensionless; 0..=1].	required

__repr__()

Returns TankConnection(tank_id='…', fraction=…).

Thruster

A thruster with fixed performance characteristics.

Connects to one or more Tank instances via TankConnection. All connection fractions must sum to 1.0.

Attributes:

Name	Type	Description
id	str	Human-readable identifier (e.g. "main_engine").
thrust	float	Thrust force [N].
isp	float	Specific impulse [s].
connections	list[TankConnection]	Tank connections for propellant draw.

connections property

Tank connections for propellant draw.

id property

Human-readable thruster identifier.

isp property

Specific impulse [s].

thrust property

Thrust force [N].

__init__(id, thrust, isp)

Creates a new Thruster with no tank connections.

Parameters:

Name	Type	Description	Default
id	str	Human-readable identifier (e.g. "main_engine").	required
thrust	float	Thrust force [N; > 0].	required
isp	float	Specific impulse [s; > 0].	required

__repr__()

Returns Thruster(id='…', thrust=…, isp=…, connections=…).

acceleration(mass_kg)

Computes the instantaneous thrust acceleration.

Parameters:

Name	Type	Description	Default
mass_kg	float	Current total spacecraft mass [kg; > 0].	required

Returns:

Name	Type	Description
float	float	Acceleration magnitude [km/s²].

exhaust_velocity()

Computes the effective exhaust velocity.

Calculated as isp * g0 where g0 = 9.80665e-3 km/s².

Returns:

Name	Type	Description
float	float	Exhaust velocity [km/s].

mass_flow_rate()

Computes the mass flow rate.

Calculated as thrust / (isp * g0) where g0 = 9.80665 m/s².

Returns:

Name	Type	Description
float	float	Mass flow rate [kg/s].

with_connection(connection)

Returns a copy of this thruster with the given tank connection added.

Parameters:

Name	Type	Description	Default
connection	TankConnection	Tank connection to append.	required

Returns:

Type	Description
Thruster	Thruster with the connection added.

acceleration_point_mass(position, mu)

Computes the point-mass gravitational acceleration.

Implements the Newtonian inverse-square law a = -μ r / |r|³. Returns the zero vector when position is the zero vector.

Parameters:

Name	Type	Description	Default
position	tuple[float, float, float]	Position relative to the central body [km].	required
mu	float	Gravitational parameter μ of the central body [km³/s²].	required

Returns:

Type	Description
tuple[float, float, float]	Acceleration directed toward the central body [km/s²].

acceleration_spherical_harmonics(position_inertial, inertial_to_body_fixed, model, max_degree=None)

Computes the spherical-harmonic gravitational acceleration.

Evaluates the EGM96 or EGM2008 gravity field up to the requested harmonic degree and returns the acceleration in the inertial frame. The built-in tables are truncated at degree 36.

Parameters:

Name	Type	Description	Default
position_inertial	tuple[float, float, float]	Position in the inertial frame (e.g. GCRS or J2000) [km].	required
inertial_to_body_fixed	tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]	3×3 rotation matrix from the inertial frame to the body-fixed (ITRF) frame, given as three row-tuples [dimensionless; orthonormal]. Pass the identity matrix when position_inertial is already expressed in the body-fixed frame.	required
model	str	Gravity field identifier. Must be "egm96" or "egm2008".	required
max_degree	Optional[int]	Maximum harmonic degree [0 ≤ max_degree ≤ 36]. None uses the model's built-in maximum (36).	None

Returns:

Type	Description
tuple[float, float, float]	Gravitational acceleration in the inertial frame [km/s²].

Raises:

Type	Description
ValueError	When model is not "egm96" or "egm2008".

acceleration_third_body(position_sat, position_third_body, mu_third_body)

Computes the third-body gravitational perturbation acceleration.

Uses the Battin formulation to avoid catastrophic cancellation when the satellite is far from the third body.

Parameters:

Name	Type	Description	Default
position_sat	tuple[float, float, float]	Spacecraft position relative to the central body (Earth) [km].	required
position_third_body	tuple[float, float, float]	Third-body (Moon or Sun) position relative to the central body [km].	required
mu_third_body	float	Gravitational parameter μ of the third body [km³/s²; Moon ≈ 4902.8, Sun ≈ 1.327e11].	required

Returns:

Type	Description
tuple[float, float, float]	Perturbation acceleration on the spacecraft [km/s²].

acceleration_zonal(position, mu, j2, j3, j4, r_eq)

Computes the combined point-mass + J₂/J₃/J₄ zonal harmonic acceleration.

Evaluates the point-mass term plus J₂, J₃, and J₄ zonal perturbations. The z-axis of position must be aligned with Earth's spin axis.

Parameters:

Name	Type	Description	Default
position	tuple[float, float, float]	Position in the inertial or body-fixed frame with z along the spin axis [km].	required
mu	float	Gravitational parameter μ [km³/s²].	required
j2	float	Second zonal harmonic coefficient (unnormalized) [dimensionless; typically ~1.08263e-3].	required
j3	float	Third zonal harmonic coefficient (unnormalized) [dimensionless; typically ~−2.532e-6].	required
j4	float	Fourth zonal harmonic coefficient (unnormalized) [dimensionless; typically ~−1.616e-6].	required
r_eq	float	Equatorial reference radius [km].	required

Returns:

Type	Description
float	Total acceleration (point-mass + J₂/J₃/J₄) in the same frame as
float	position [km/s²].

normalize_vismag(vismag, obs_range, std_range, obs_phase, std_phase)

Normalises a visual magnitude to a standard range and phase angle.

Convenience wrapper that applies normalize_vismag_to_range and normalize_vismag_to_phase in sequence.

Parameters:

Name	Type	Description	Default
vismag	float	Observed visual magnitude [mag].	required
obs_range	float	Observer-to-target range at observation [km; > 0].	required
std_range	float	Reference range [km; > 0].	required
obs_phase	float	Sun-target-observer phase angle at observation [rad; 0..π].	required
std_phase	float	Reference phase angle [rad; 0..π].	required

Returns:

Type	Description
float	Range- and phase-normalized visual magnitude [mag].

normalize_vismag_to_phase(vismag, obs_phase, std_phase)

Normalises a visual magnitude from an observed phase to a standard phase.

Uses a Lambertian-sphere phase model phase_factor(α) = (1 + cos α) / 2, then converts the ratio to magnitudes via the Pogson relation.

Parameters:

Name	Type	Description	Default
vismag	float	Observed visual magnitude [mag].	required
obs_phase	float	Sun-target-observer phase angle at observation [rad; 0..π].	required
std_phase	float	Reference phase angle to normalize to [rad; 0..π].	required

Returns:

Type	Description
float	Phase-normalized visual magnitude [mag].

normalize_vismag_to_range(vismag, obs_range, std_range)

Normalises a visual magnitude from an observed range to a standard range.

Corrects for inverse-square brightness fall-off: m_std = m − 5 · log₁₀(R_obs / R_std).

Parameters:

Name	Type	Description	Default
vismag	float	Observed visual magnitude [mag].	required
obs_range	float	Observer-to-target range at observation [km; > 0].	required
std_range	float	Reference range to normalize to [km; > 0].	required

Returns:

Type	Description
float	Range-normalized visual magnitude [mag].

vismag_from_relative_flux(ref_vismag, ref_flux, target_flux)

Computes a target visual magnitude from a relative flux measurement.

Uses the Pogson relation m_target = m_ref − 2.5 · log₁₀(F_target / F_ref).

Parameters:

Name	Type	Description	Default
ref_vismag	float	Reference visual magnitude [mag].	required
ref_flux	float	Reference flux [arbitrary units; > 0].	required
target_flux	float	Target flux in the same units [arbitrary units; > 0].	required

Returns:

Type	Description
float	Target visual magnitude [mag].