Elements

elements

ARBounds

Bounds that define which (ρ, ρ̇) pairs are admissible.

An admissible region is the subset of the topocentric (range, range-rate) plane consistent with a closed Earth orbit. Without additional constraints the closed-orbit condition energy < 0 alone admits a band that stretches from impactors to escape; ARBounds narrows it to the physically interesting subset by clipping perigee altitude, apogee altitude, and eccentricity.

The defaults — perigee ≥ 150 km, apogee ≤ 50 000 km, eccentricity ≤ 0.99 — cover the LEO through HEO regimes without admitting near-impactor or hyperbolic-escape trajectories.

Attributes:

Name	Type	Description
perigee_altitude_min_km	float	Minimum admissible perigee altitude above the WGS-84 equator [km; ≥ 0].
apogee_altitude_max_km	float	Maximum admissible apogee altitude above the WGS-84 equator [km; ≥ perigee_altitude_min_km].
eccentricity_max	float	Maximum admissible eccentricity [dimensionless; 0..1).

apogee_altitude_max_km property

Maximum admissible apogee altitude above the WGS-84 equator [km].

eccentricity_max property

Maximum admissible eccentricity [dimensionless; 0..1).

perigee_altitude_min_km property

Minimum admissible perigee altitude above the WGS-84 equator [km; ≥ 0].

__init__(perigee_altitude_min_km, apogee_altitude_max_km, eccentricity_max)

Creates an ARBounds with explicit altitude and eccentricity limits.

Parameters:

Name	Type	Description	Default
perigee_altitude_min_km	float	Minimum admissible perigee altitude [km; ≥ 0].	required
apogee_altitude_max_km	float	Maximum admissible apogee altitude [km; ≥ perigee_altitude_min_km].	required
eccentricity_max	float	Maximum admissible eccentricity [dimensionless; 0..1).	required

__repr__()

Returns ARBounds(perigee_altitude_min_km=…, apogee_altitude_max_km=…, eccentricity_max=…).

default() staticmethod

Returns the default ARBounds.

Defaults: perigee ≥ 150 km, apogee ≤ 50 000 km, eccentricity ≤ 0.99.

Returns:

Type	Description
ARBounds	Default bounds.

AdmissibleRegion

Sampled admissible region for an angles-only TrackletFit.

Each particle is a (ρ, ρ̇, weight) triple in the topocentric range / range-rate plane. Together with the parent tracklet's right ascension, declination, and rates at the same epoch, a particle promotes to a full 6-D inertial state; the HypothesisCloud produced by the hypothesis-generation stage carries the promoted states (with covariance) rather than the raw particles.

Attributes:

Name	Type	Description
fit_epoch	ModifiedJulianDate	Epoch of the parent TrackletFit; every particle is interpreted at this epoch.
bounds	ARBounds	Bounds that defined which particles were retained from the raw sample.
particles	list[tuple[float, float, float]]	Particles in (range_km, range_rate_km_per_s, weight) form. Weights are non-negative and need not sum to 1.

bounds property

Bounds that defined which particles were retained from the raw sample.

fit_epoch property

Epoch of the parent tracklet fit; every particle is interpreted at this epoch.

particles property

Particles in (range_km, range_rate_km_per_s, weight) form.

__init__(fit_epoch, bounds, particles)

Creates a new AdmissibleRegion.

Parameters:

Name	Type	Description	Default
fit_epoch	ModifiedJulianDate	Epoch of the parent tracklet fit.	required
bounds	ARBounds	Bounds applied during sampling.	required
particles	list[tuple[float, float, float]]	(ρ, ρ̇, weight) triples [km, km/s, dimensionless].	required

__len__()

Number of particles in the sampled region.

__repr__()

Returns AdmissibleRegion(fit_epoch=…, n_particles=…).

is_empty()

True when the sampled region contains no particles.

AdvancedStateBundle

Multi-representation snapshot of a satellite state at a single epoch.

Bundles four representations of the same satellite state — the osculating Cartesian state, the osculating Keplerian elements, a MeanKozaiGP TLE (SGP4), and a MeanBrouwerXP TLE (SGP4-XP) — produced atomically from a single propagated arc. Top-level drag_coefficient and srp_coefficient scalars are passthroughs of the source satellite's properties.

Both TLEs are intrinsically in the TEME frame regardless of reference_frame; reference_frame describes only the Cartesian and osculating Keplerian fields.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Common epoch of the osculating snapshot.
reference_frame	ReferenceFrame	Frame of cartesian_state and osculating_keplerian. Mean TLEs are always TEME.
cartesian_state	CartesianState	Osculating position and velocity at epoch [km, km/s].
osculating_keplerian	KeplerianState	Classical Keplerian elements at epoch.
mean_kozai_gp	TLE	SGP4 TLE in MeanKozaiGP form. Force-model scalars (B*, mean-motion derivatives) embedded in force_terms.
mean_brouwer_xp	TLE	SGP4-XP TLE in MeanBrouwerXP form. Force-model scalars (b_term, agom) embedded in force_terms.
drag_coefficient	float	Drag coefficient from the source satellite's properties. Nominally dimensionless Cd; see note below.
srp_coefficient	float	SRP coefficient from the source satellite's properties. Nominally dimensionless Cr; same note.

Note

The keplime Satellite.properties.drag_coefficient field is populated by different code paths with different unit conventions: TLE parsing assigns the AFSPC b_term (1/earth-radii) directly into the field, while physical-input construction stores the dimensionless Cd. The same applies to srp_coefficient. Consumers who need an unambiguous drag/SRP scalar should prefer mean_kozai_gp.b_star (classical SGP4 B*), mean_kozai_gp.force_terms.b_term (AFSPC drag term in 1/earth-radii), or mean_brouwer_xp.force_terms.agom (Cr · A / m in m²/kg). Those are produced by Satellite.to_tle's internal chain and have well-defined units regardless of how the input satellite was constructed.

cartesian_state property

Osculating Cartesian state at epoch [km, km/s].

drag_coefficient property

Drag coefficient from the source satellite's properties.

Nominally dimensionless Cd; see the class-level units note.

epoch property

Common epoch of the osculating snapshot.

mean_brouwer_xp property

Fitted MeanBrouwerXP TLE (SGP4-XP), always in TEME.

mean_kozai_gp property

Fitted MeanKozaiGP TLE (SGP4), always in TEME.

osculating_keplerian property

Osculating classical Keplerian elements at epoch.

reference_frame property

Reference frame of cartesian_state and osculating_keplerian.

Mean TLEs are always TEME regardless of this value.

srp_coefficient property

SRP coefficient from the source satellite's properties.

Nominally dimensionless Cr; see the class-level units note.

BoreToBodyAngles

Angular separations from a boresight direction to Earth, Sun, and Moon.

Attributes:

Name	Type	Description
earth_angle	float	Angle from boresight to Earth center [rad; 0..π].
sun_angle	float	Angle from boresight to Sun center [rad; 0..π].
moon_angle	float	Angle from boresight to Moon center [rad; 0..π].

earth_angle property

Angle from boresight to Earth center [rad; 0..π].

moon_angle property

Angle from boresight to Moon center [rad; 0..π].

sun_angle property

Angle from boresight to Sun center [rad; 0..π].

__init__(earth_angle, sun_angle, moon_angle)

Creates BoreToBodyAngles from explicit angle values.

Parameters:

Name	Type	Description	Default
earth_angle	float	Angle from boresight to Earth center [rad; 0..π].	required
sun_angle	float	Angle from boresight to Sun center [rad; 0..π].	required
moon_angle	float	Angle from boresight to Moon center [rad; 0..π].	required

__repr__()

Returns BoreToBodyAngles(earth_angle=…, sun_angle=…, moon_angle=…).

CartesianState

Cartesian state vector (position and optional velocity) at an epoch.

All vector components are expressed in the associated reference frame.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Epoch of the state.
reference_frame	ReferenceFrame	Frame of the position and velocity.
position	CartesianVector	Position [km].
velocity	Optional[CartesianVector]	Velocity [km/s], or None.

epoch property

Epoch of the state.

position property

Position vector [km].

reference_frame property

Reference frame of position and velocity.

velocity property

Velocity vector [km/s], or None for position-only states.

__init__(epoch, reference_frame, position, velocity)

Creates a CartesianState.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the state.	required
reference_frame	ReferenceFrame	Frame for position and velocity.	required
position	CartesianVector	Position vector [km].	required
velocity	Optional[CartesianVector]	Velocity vector [km/s], or None.	required

__repr__()

Returns CartesianState(epoch=…, reference_frame=…, position=(…, …, …), velocity=…).

__str__()

Returns the same representation as __repr__.

relative_to(origin_state, frame)

Computes this state relative to origin_state.

Both states must share the same epoch and reference frame.

Parameters:

Name	Type	Description	Default
origin_state	CartesianState	Origin (chief / reference) state.	required
frame	RelativeFrame	Inertial or RIC (Radial–In-track–Cross-track) output frame.	required

Returns:

Type	Description
CartesianState	Relative state [position in km, velocity in km/s].

Raises:

Type	Description
ValueError	If epochs differ, frames differ, or either state lacks velocity.

to_cartesian_vector()

Returns the position as a CartesianVector.

Returns:

Type	Description
CartesianVector	Position vector [km].

to_keplerian(mu)

Converts this Cartesian state to classical Keplerian elements.

Applies the standard rv2coe (r-v to classical elements) algorithm. Only elliptic orbits are supported.

Parameters:

Name	Type	Description	Default
mu	float	Gravitational parameter of the central body [km³/s²]. Use 398600.4418 for WGS84 Earth, or 398600.8 for WGS72.	required

Returns:

Type	Description
KeplerianElements	KeplerianElements with semi_major_axis [km], eccentricity,
KeplerianElements	inclination [rad], ascending_node [rad],
KeplerianElements	argument_of_periapsis [rad], and mean_anomaly [rad].

Raises:

Type	Description
ValueError	If this state has no velocity, position is at the origin, angular momentum is zero, or the orbit is non-elliptic (energy ≥ 0).

to_reference_frame(target, priority)

Converts this state to a different reference frame.

Parameters:

Name	Type	Description	Default
target	ReferenceFrame	Destination reference frame.	required
priority	PerformancePriority	Trade-off between speed and numerical precision.	required

Returns:

Type	Description
CartesianState	New state in target [position in km, velocity in km/s].

Raises:

Type	Description
ValueError	If the frame transformation is not supported.

CartesianVector

A three-component Cartesian vector.

Components may represent position [km], velocity [km/s], or a dimensionless direction depending on context.

Attributes:

Name	Type	Description
x	float	X component [km, km/s, or dimensionless].
y	float	Y component [same units as x].
z	float	Z component [same units as x].
magnitude	float	Euclidean norm [same units as components].

magnitude property

Euclidean norm of the vector [same units as components].

x property

X component [km, km/s, or dimensionless depending on context].

y property

Y component [same units as x].

z property

Z component [same units as x].

__add__(other)

Returns the component-wise sum self + other [same units].

__getitem__(index)

Returns a component by index (0=x, 1=y, 2=z; negative indices supported).

Raises:

Type	Description
IndexError	If index is outside -3..2.

__init__(x, y, z)

Creates a CartesianVector from explicit component values.

Parameters:

Name	Type	Description	Default
x	float	X component [km, km/s, or dimensionless depending on context].	required
y	float	Y component [same units as x].	required
z	float	Z component [same units as x].	required

__iter__()

Iterates over the components as (x, y, z) [same units].

__len__()

Returns the component count (always 3).

__neg__()

Returns the component-wise negation -self.

__repr__()

Returns CartesianVector(x=…, y=…, z=…).

__str__()

Returns the same representation as __repr__.

__sub__(other)

Returns the component-wise difference self - other [same units].

as_tuple()

Returns the components as an (x, y, z) tuple.

Returns:

Type	Description
Vector3	(x, y, z) [same units as components].

distance(other)

Returns the Euclidean distance between this vector and another.

Parameters:

Name	Type	Description	Default
other	CartesianVector	The other vector [same units].	required

Returns:

Type	Description
float	Distance [same units as components].

get_angle(other)

Returns the angle between this vector and another.

Uses arccos(a · b / (‖a‖ ‖b‖)). Undefined for zero-magnitude vectors.

Parameters:

Name	Type	Description	Default
other	CartesianVector	The other vector.	required

Returns:

Type	Description
float	Angle between the two vectors [rad; 0..π].

in_earth_shadow(sun_position)

Returns whether this position lies inside Earth's cylindrical shadow.

self is treated as a body position relative to Earth's center, and sun_position as the Sun position in the same frame and units [km]. Cylindrical model only — no penumbra, no flattening.

Parameters:

Name	Type	Description	Default
sun_position	CartesianVector	Sun position in the same frame as self [km].	required

Returns:

Type	Description
bool	True if the body is inside Earth's cylindrical shadow,
bool	False otherwise. False when sun_position is the
bool	zero vector or non-finite.

CorrelatedTrackletSet

A set of tracklets the correlation stage has identified as likely sharing the same underlying object.

Correlation produces these sets by gating propagated HypothesisClouds against each other and keeping the surviving tracklet groupings. The set is the input to the initial-orbit-determination stage, which fits one state from the union of the member tracklets' observations.

Attributes:

Name	Type	Description
tracklet_indices	list[int]	Indices into the pipeline's tracklet vector. Each index identifies a member tracklet of the set.
score	float	Correlation score that drove the grouping decision [dimensionless; 0..1, higher is more confident].

score property

Correlation score that drove the grouping decision [dimensionless; 0..1].

tracklet_indices property

Indices into the pipeline's tracklet vector identifying member tracklets.

__init__(tracklet_indices, score)

Creates a new CorrelatedTrackletSet.

Parameters:

Name	Type	Description	Default
tracklet_indices	list[int]	Indices of member tracklets in the pipeline's tracklet vector.	required
score	float	Correlation score [dimensionless; 0..1].	required

__len__()

Number of member tracklets in the set.

__repr__()

Returns CorrelatedTrackletSet(n_tracklets=…, score=…).

is_empty()

True when the set has no member tracklets.

Ephemeris

A time-ordered collection of Cartesian states for a single object.

Attributes:

Name	Type	Description
satellite_id	str	Identifier of the satellite.
norad_id	int	NORAD catalog number (0 if not set).
number_of_states	int	Number of states stored.

norad_id property

NORAD catalog number (0 if not set).

number_of_states property

Number of states stored in this ephemeris.

satellite_id property

Identifier of the satellite.

__init__(satellite_id, state, norad_id=...)

Creates an Ephemeris with a single initial state.

Parameters:

Name	Type	Description	Default
satellite_id	str	Identifier of the satellite.	required
state	CartesianState	Initial Cartesian state.	required
norad_id	Optional[int]	NORAD catalog number (optional).	...

add_state(state)

Appends a state to the ephemeris.

Parameters:

Name	Type	Description	Default
state	CartesianState	Cartesian state to append.	required

covers_epoch(epoch)

Returns whether epoch falls within the ephemeris coverage.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch to test.	required

Returns:

Type	Description
bool	True if epoch is within the covered range.

covers_range(start, end)

Returns whether the ephemeris fully covers [start, end].

Parameters:

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

Returns:

Type	Description
bool	True if both endpoints lie within the coverage.

get_epoch_range()

Returns the epoch range covered by this ephemeris.

Returns:

Type	Description
Optional[tuple[ModifiedJulianDate, ModifiedJulianDate]]	(start, end) pair, or None if the ephemeris is empty.

get_horizon_sensor_access(bore, target, constraints)

Reports access windows from this ephemeris (the sensor host) to a target ephemeris using a boresight fixed in the host's local horizon frame (Az/El).

Parameters:

Name	Type	Description	Default
bore	HorizonElements	Boresight as HorizonElements.	required
target	Ephemeris	Body whose access is being reported.	required
constraints	SensorConstraints	SensorConstraints to apply.	required

Returns:

Type	Description
SensorAccessReport	A SensorAccessReport over the
SensorAccessReport	intersection of observer/target coverage.

Raises:

Type	Description
ValueError	If either ephemeris has no epoch range.

get_inertial_sensor_access(bore, target, constraints)

Reports access windows from this ephemeris (the sensor host) to a target ephemeris using a constant inertial boresight (RA/Dec).

Parameters:

Name	Type	Description	Default
bore	TopocentricElements	Boresight as TopocentricElements; both right_ascension and declination must be set.	required
target	Ephemeris	Body whose access is being reported.	required
constraints	SensorConstraints	SensorConstraints to apply.	required

Returns:

Type	Description
SensorAccessReport	A SensorAccessReport over the
SensorAccessReport	intersection of observer/target coverage.

Raises:

Type	Description
ValueError	If bore lacks RA or Dec, or either ephemeris has no epoch range.

get_state_at_epoch(epoch)

Interpolates the state at the given epoch.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Desired epoch.	required

Returns:

Type	Description
Optional[CartesianState]	Interpolated state [position in km, velocity in km/s], or None
Optional[CartesianState]	if epoch is outside the covered range.

get_target_sensor_access(primary_target, secondary_target, constraints)

Reports access windows from this ephemeris (the sensor host) to secondary_target while the host points at primary_target.

Parameters:

Name	Type	Description	Default
primary_target	Ephemeris	Body the boresight tracks.	required
secondary_target	Ephemeris	Body whose access is being reported.	required
constraints	SensorConstraints	SensorConstraints to apply.	required

Returns:

Type	Description
SensorAccessReport	A SensorAccessReport over the
SensorAccessReport	intersection of observer/secondary_target coverage.

Raises:

Type	Description
ValueError	If observer or secondary_target has no epoch range.

stitch(other)

Joins this arc with another at their minimum-separation crossover.

Both arcs are treated as overlapping trajectories of the same object (for example two element sets propagated across the span between their epochs). The arc that starts earlier supplies the pre-crossover states and the later arc the post-crossover states, so a.stitch(b) and b.stitch(a) return the same result.

The crossover epoch is the instant within the temporal overlap at which the two trajectories are closest in position. The overlap is scanned at the union of both arcs' knot epochs (interpolating where a knot is absent), so no shared cadence or grid alignment is assumed. The join is a hard cut that preserves the original states: the earlier arc's states up to and including the crossover are concatenated with the later arc's states after it. The seam carries the small position discontinuity equal to the minimum separation and is generally non-uniform; resample the result with get_state_at_epoch on a uniform set of epochs when a strictly-uniform grid is required. Stitch more than two arcs by sorting them by epoch and folding this method left-to-right.

Parameters:

Name	Type	Description	Default
other	Ephemeris	Another overlapping arc of the same object.	required

Returns:

Type	Description
Ephemeris	A new ephemeris spanning [earlier.start, later.end], cut at the
Ephemeris	minimum-separation epoch, inheriting the earlier arc's
Ephemeris	satellite_id and norad_id.

Raises:

Type	Description
ValueError	If either arc is empty or the two arcs do not overlap in time.

EquinoctialElements

Singularity-free equinoctial orbital elements.

Equinoctial elements avoid the coordinate singularities present in classical Keplerian elements at zero inclination and zero eccentricity. Defined from the Keplerian set (a, e, i, Ω, ω, M) as:

• af = e cos(Ω + ω)
• ag = e sin(Ω + ω)
• chi = tan(i/2) sin(Ω)
• psi = tan(i/2) cos(Ω)
• mean_longitude = Ω + ω + M

Warning

The chi and psi components contain a factor of tan(i/2) which diverges as i → π. Retrograde-equatorial orbits (i = π) are undefined in this parameterisation.

Attributes:

Name	Type	Description
semi_major_axis	float	Semi-major axis [km; > 0].
af	float	Eccentricity vector cosine component [dimensionless].
ag	float	Eccentricity vector sine component [dimensionless].
chi	float	Inclination vector sine component [dimensionless; diverges at i = π].
psi	float	Inclination vector cosine component [dimensionless; diverges at i = π].
mean_longitude	float	Mean longitude Ω + ω + M [rad; 0..2π).

af property

Eccentricity vector cosine component e cos(Ω + ω) [dimensionless].

ag property

Eccentricity vector sine component e sin(Ω + ω) [dimensionless].

chi property

Inclination vector sine component tan(i/2) sin(Ω) [dimensionless; diverges at i = π].

mean_longitude property

Mean longitude Ω + ω + M [rad; 0..2π).

psi property

Inclination vector cosine component tan(i/2) cos(Ω) [dimensionless; diverges at i = π].

semi_major_axis property

Semi-major axis [km; > 0].

__init__(semi_major_axis, af, ag, chi, psi, mean_longitude)

Creates equinoctial orbital elements from the six element components.

Parameters:

Name	Type	Description	Default
semi_major_axis	float	Semi-major axis [km; > 0].	required
af	float	Eccentricity vector cosine component, e cos(Ω + ω) [dimensionless].	required
ag	float	Eccentricity vector sine component, e sin(Ω + ω) [dimensionless].	required
chi	float	Inclination vector sine component, tan(i/2) sin(Ω) [dimensionless].	required
psi	float	Inclination vector cosine component, tan(i/2) cos(Ω) [dimensionless].	required
mean_longitude	float	Mean longitude Ω + ω + M [rad; 0..2π).	required

Returns:

Type	Description
None	EquinoctialElements with the given components.

to_cartesian(epoch, frame, mu)

Converts these equinoctial elements to a Cartesian state vector.

Delegates to KeplerianElements.to_cartesian by first converting via to_keplerian.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the output state vector.	required
frame	ReferenceFrame	Reference frame for the output state.	required
mu	float	Gravitational parameter of the central body [km³/s²].	required

Returns:

Type	Description
CartesianState	Cartesian state with position [km] and velocity [km/s] at the
CartesianState	given epoch in the specified frame.

Raises:

Type	Description
ValueError	If the underlying Keplerian solver fails (e.g. semi_major_axis ≤ 0 or eccentricity outside [0, 1)).

to_keplerian()

Converts these equinoctial elements to classical Keplerian elements.

Recovers (e, i, Ω, ω, M) from the equinoctial vector components via inverse trigonometric identities and wraps each angle into its canonical range.

Returns:

Type	Description
KeplerianElements	Equivalent classical Keplerian elements.

EquinoctialState

Equinoctial orbital state at an epoch.

Bundles a set of EquinoctialElements with the epoch and the central body's gravitational parameter so that derived quantities such as mean motion can be computed without additional context.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Epoch of the state.
elements	EquinoctialElements	Equinoctial orbital elements at epoch.
mu	float	Gravitational parameter of the central body [km³/s²].
mean_motion	float	Mean motion derived from the semi-major axis [rev/day].

elements property

Equinoctial orbital elements at the epoch.

epoch property

Epoch of the state.

mean_motion property

Mean motion derived from the semi-major axis [rev/day].

Computed as n = √(μ/a³) and converted to revolutions per day.

Returns:

Type	Description
float	Mean motion [rev/day].

Raises:

Type	Description
ValueError	If semi_major_axis ≤ 0.

mu property

Gravitational parameter of the central body [km³/s²].

__init__(epoch, elements, mu)

Creates an equinoctial orbital state from its components.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch at which the elements are valid.	required
elements	EquinoctialElements	Equinoctial orbital elements.	required
mu	float	Gravitational parameter of the central body [km³/s²].	required

GeodeticGrid

Builders for regular latitude/longitude meshes of candidate sites.

Produces lists of GeodeticPosition for sensor-coverage heatmaps. Every generated site sits at altitude 0 (on the WGS-84 ellipsoid), so the search space is two-dimensional. The returned list is row-major (latitude south to north, longitude west to east) and pairs 1:1 with the scores of a CoverageGrid built from it. All angles are in degrees.

This class is a stateless namespace and is never instantiated.

global_grid(step_deg) staticmethod

Builds a whole-Earth lat/lon mesh at altitude 0.

Latitude spans -90..90 inclusive; longitude spans -180..180 with 180 excluded so the antimeridian is not duplicated.

Parameters:

Name	Type	Description	Default
step_deg	float	Grid spacing [deg; > 0].	required

Returns:

Type	Description
list[GeodeticPosition]	list[GeodeticPosition]: Candidate sites covering the globe at altitude 0.

Raises:

Type	Description
ValueError	If step_deg is not finite and positive.

global_land(step_deg) staticmethod

Like global_grid but keeps only sites on land.

The whole-Earth mesh with ocean cells removed via the embedded land mask. See regular_land for the resolution caveat and the 1:1 pairing requirement.

Parameters:

Name	Type	Description	Default
step_deg	float	Grid spacing [deg; > 0].	required

Returns:

Type	Description
list[GeodeticPosition]	list[GeodeticPosition]: The land-only subset of global_grid, at altitude 0.

Raises:

Type	Description
ValueError	If step_deg is not finite and positive.

is_land(latitude, longitude) staticmethod

Returns whether a geodetic location lies on land.

Looks up the point in the embedded ~0.25 deg Natural Earth land mask. Longitude is wrapped into [-180, 180) and latitude clamped to [-90, 90], so any finite input is valid; near-shore results are approximate at the raster resolution.

Parameters:

Name	Type	Description	Default
latitude	float	Geodetic latitude [deg; -90..90].	required
longitude	float	Geodetic longitude [deg; -180..180].	required

Returns:

Name	Type	Description
bool	bool	True if the cell containing the point is land.

regular(latitude_min, latitude_max, longitude_min, longitude_max, step_deg) staticmethod

Builds a regular lat/lon mesh over a bounding box at altitude 0.

Endpoints are inclusive: a sweep from -10 to 10 at step_deg = 5 yields latitudes -10, -5, 0, 5, 10.

Parameters:

Name	Type	Description	Default
latitude_min	float	Southern bound [deg; -90..90].	required
latitude_max	float	Northern bound [deg; -90..90], >= latitude_min.	required
longitude_min	float	Western bound [deg; -180..180].	required
longitude_max	float	Eastern bound [deg; -180..180], >= longitude_min.	required
step_deg	float	Grid spacing [deg; > 0].	required

Returns:

Type	Description
list[GeodeticPosition]	list[GeodeticPosition]: Row-major candidate sites at altitude 0.

Raises:

Type	Description
ValueError	If step_deg is not finite and positive, or either maximum is below its corresponding minimum.

regular_land(latitude_min, latitude_max, longitude_min, longitude_max, step_deg) staticmethod

Like regular but keeps only sites on land.

Drops every site whose cell is ocean per the embedded Natural Earth land mask (~0.25 deg, so near-shore classification is approximate). The result is no longer a dense rectangle and pairs 1:1 only with a CoverageGrid built from this same list. Use it to restrict candidate sites to land a ground sensor could stand on.

Parameters:

Name	Type	Description	Default
latitude_min	float	Southern bound [deg; -90..90].	required
latitude_max	float	Northern bound [deg; -90..90], >= latitude_min.	required
longitude_min	float	Western bound [deg; -180..180].	required
longitude_max	float	Eastern bound [deg; -180..180], >= longitude_min.	required
step_deg	float	Grid spacing [deg; > 0].	required

Returns:

Type	Description
list[GeodeticPosition]	list[GeodeticPosition]: The land-only subset of regular, at altitude 0.

Raises:

Type	Description
ValueError	If step_deg is not finite and positive, or either maximum is below its corresponding minimum.

GeodeticPosition

Geodetic coordinates on the WGS-84 ellipsoid.

Latitude and longitude are geodetic (not geocentric). Altitude is measured above the WGS-84 reference ellipsoid, not mean sea level.

Attributes:

Name	Type	Description
latitude	float	Geodetic latitude [rad; -π/2..π/2].
longitude	float	Geodetic longitude [rad; -π..π].
altitude	float	Altitude above WGS-84 ellipsoid [km].
id	str	Unique identifier (UUID by default; settable).
name	str | None	Optional human-readable name.

altitude property

Altitude above WGS-84 ellipsoid [km].

latitude property

Geodetic latitude [rad; -π/2..π/2].

longitude property

Geodetic longitude [rad; -π..π].

__init__(latitude, longitude, altitude)

Creates a GeodeticPosition on the WGS-84 ellipsoid.

Parameters:

Name	Type	Description	Default
latitude	float	Geodetic latitude [rad; -π/2..π/2].	required
longitude	float	Geodetic longitude [rad; -π..π].	required
altitude	float	Altitude above WGS-84 ellipsoid [km].	required

__repr__()

Returns GeodeticPosition(latitude=…, longitude=…, altitude=…).

from_cartesian_state(state) staticmethod

Converts an ITRF Cartesian state to geodetic coordinates.

Uses an iterative Bowring method for WGS-84 inversion. The input state is converted to ITRF automatically if needed.

Parameters:

Name	Type	Description	Default
state	CartesianState	Cartesian state (any supported frame) [position in km].	required

Returns:

Type	Description
GeodeticPosition	Geodetic position on the WGS-84 ellipsoid.

Raises:

Type	Description
ValueError	If the frame conversion to ITRF fails.

get_field_of_view_report(epoch, sensor_direction, angular_threshold, sats, reference_frame)

Reports satellites within a sensor's angular field of view.

A satellite is included when its angular separation from sensor_direction does not exceed angular_threshold.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Observation epoch.	required
sensor_direction	TopocentricElements	Boresight as topocentric elements (ra and dec required).	required
angular_threshold	float	Half-angle of the field of view [rad].	required
sats	'Constellation'	Constellation to search.	required
reference_frame	ReferenceFrame	Reference frame for the computation.	required

Returns:

Type	Description
'FieldOfViewReport'	FieldOfViewReport with matching satellites.

Raises:

Type	Description
ValueError	If propagation fails or sensor_direction lacks angles.

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

Finds satellite access intervals above a minimum elevation.

Steps at 60-second resolution and bisects each crossing for accuracy.

Parameters:

Name	Type	Description	Default
satellite	'Satellite'	Target satellite.	required
start	ModifiedJulianDate	Start of the search window.	required
end	ModifiedJulianDate	End of the search window.	required
min_elevation	float	Minimum elevation threshold [rad].	required
min_duration	TimeSpan	Minimum pass duration to include.	required

Returns:

Type	Description
'HorizonAccessReport'	HorizonAccessReport with qualifying passes.

Raises:

Type	Description
ValueError	If start > end or propagation fails.

get_state_at_epoch(epoch, reference_frame=...)

Returns the observer's inertial state at a given epoch.

The observer has zero velocity in ITRF, converted to reference_frame if provided.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Desired epoch.	required
reference_frame	ReferenceFrame | None	Output frame (default: TEME).	...

Returns:

Type	Description
CartesianState	Cartesian state [position in km, zero velocity in km/s].

Raises:

Type	Description
ValueError	If the frame conversion fails.

get_theta(epoch)

Returns the local sidereal angle at the observer's longitude.

Computed as GMST plus the observer's east longitude. Requires EOP data.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Desired epoch.	required

Returns:

Type	Description
float	Local sidereal angle [rad; 0..2π).

get_topocentric_to_satellite(epoch, sat, reference_frame)

Computes the topocentric direction from this observer to a satellite.

Includes range and range-rate when both states carry velocity.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Observation epoch.	required
sat	'Satellite'	Target satellite.	required
reference_frame	ReferenceFrame	Reference frame for the computation.	required

Returns:

Type	Description
TopocentricElements	Topocentric elements [range in km, range-rate in km/s,
TopocentricElements	right_ascension and declination in rad].

Raises:

Type	Description
ValueError	If propagation or frame conversion fails.

HorizonElements

Local-horizon angular observation: azimuth and elevation.

Azimuth is measured clockwise from north. Elevation is positive above the horizon. Rate fields are optional and may be None near singularities (zenith for azimuth rate, nadir for elevation rate).

Attributes:

Name	Type	Description
azimuth	float	Azimuth angle [rad; 0..2π, clockwise from north].
elevation	float	Elevation angle [rad; -π/2..π/2].
range	Optional[float]	Slant range [km].
range_rate	Optional[float]	Range-rate [km/s].
azimuth_rate	Optional[float]	Azimuth rate [rad/s]; None near zenith.
elevation_rate	Optional[float]	Elevation rate [rad/s].

azimuth property

Azimuth angle [rad; 0..2π, clockwise from north].

azimuth_rate property

Azimuth rate [rad/s], or None near zenith.

elevation property

Elevation angle [rad; -π/2..π/2].

elevation_rate property

Elevation rate [rad/s], or None.

range property

Slant range [km], or None.

range_rate property

Range-rate [km/s], or None.

__init__(azimuth, elevation)

Creates HorizonElements with azimuth and elevation only.

Parameters:

Name	Type	Description	Default
azimuth	float	Azimuth angle [rad; 0..2π, clockwise from north].	required
elevation	float	Elevation angle [rad; -π/2..π/2].	required

__repr__()

Returns HorizonElements(azimuth=…, elevation=…).

with_azimuth_rate(azimuth_rate)

Returns a copy with the azimuth-rate field set.

Parameters:

Name	Type	Description	Default
azimuth_rate	Optional[float]	Azimuth rate [rad/s], or None to clear.	required

Returns:

Type	Description
HorizonElements	Updated HorizonElements.

with_elevation_rate(elevation_rate)

Returns a copy with the elevation-rate field set.

Parameters:

Name	Type	Description	Default
elevation_rate	Optional[float]	Elevation rate [rad/s], or None to clear.	required

Returns:

Type	Description
HorizonElements	Updated HorizonElements.

with_range(range)

Returns a copy with the range field set.

Parameters:

Name	Type	Description	Default
range	Optional[float]	Slant range [km], or None to clear.	required

Returns:

Type	Description
HorizonElements	Updated HorizonElements.

with_range_rate(range_rate)

Returns a copy with the range-rate field set.

Parameters:

Name	Type	Description	Default
range_rate	Optional[float]	Range-rate [km/s], or None to clear.	required

Returns:

Type	Description
HorizonElements	Updated HorizonElements.

HorizonState

A horizon observation (azimuth/elevation) at an epoch.

The observer position is normalized to ITRF on construction.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Observation epoch.
elements	HorizonElements	Azimuth, elevation, and optional rates.
origin_state	CartesianState	Observer state in ITRF.

elements property

Azimuth, elevation, and optional rates.

epoch property

Observation epoch.

origin_state property

Observer state in ITRF.

__init__(epoch, elements, origin_state)

Creates a HorizonState.

The origin_state epoch must match epoch; it will be automatically converted to ITRF.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Observation epoch.	required
elements	HorizonElements	Azimuth, elevation, and optional rates.	required
origin_state	CartesianState	Observer Cartesian state (any supported frame).	required

__repr__()

Returns HorizonState(epoch=…).

from_cartesian(observer_state, target_state) staticmethod

Computes the horizon observation from observer to target.

Both states are converted to ITRF. Rates are computed when both states carry velocity; None is set near zenith.

Parameters:

Name	Type	Description	Default
observer_state	CartesianState	Observer Cartesian state (any supported frame).	required
target_state	CartesianState	Target Cartesian state.	required

Returns:

Type	Description
HorizonState	HorizonState at the observer's position.

Raises:

Type	Description
ValueError	If epochs differ, positions coincide, or frame conversion fails.

from_topocentric_state(state) staticmethod

Converts a TopocentricState to a HorizonState.

Transforms right ascension/declination to azimuth/elevation using the observer's geodetic latitude and longitude.

Parameters:

Name	Type	Description	Default
state	TopocentricState	Source topocentric state.	required

Returns:

Type	Description
HorizonState	Equivalent HorizonState.

get_sensor_access_report(candidates, start, end, constraints, tracking_ephemeris=...)

Reports access windows from this observation to candidates.

The observer is already in ITRF; its TEME position is re-sampled over the search range. When tracking_ephemeris is None, the stored Az/El drives the boresight; when Some, the stored Az/El is bypassed and the bore at each epoch is tracking_ephemeris_pos − observer_pos.

Parameters:

Name	Type	Description	Default
candidates	list[Ephemeris]	Target ephemerides to evaluate against the bore.	required
start	ModifiedJulianDate	Start of the search range.	required
end	ModifiedJulianDate	End of the search range.	required
constraints	SensorConstraints	SensorConstraints to apply.	required
tracking_ephemeris	Optional[Ephemeris]	Optional bore-pointing override; when provided, the stored Az/El is ignored.	...

Returns:

Type	Description
SensorAccessReport	A SensorAccessReport aggregating
SensorAccessReport	all candidate access windows.

Raises:

Type	Description
ValueError	If start > end, the observer cannot be lifted, or an inner gate evaluation fails.

get_sensor_access_to_constellation(constellation, start, end, constraints, tracking_ephemeris=...)

Convenience: reports access windows to every cached ephemeris in constellation over [start, end].

Satellites are iterated in sorted-id order for deterministic output ordering.

Parameters:

Name	Type	Description	Default
constellation	Constellation	Target Constellation. Every satellite must have a cached ephemeris.	required
start	ModifiedJulianDate	Start of the search range.	required
end	ModifiedJulianDate	End of the search range.	required
constraints	SensorConstraints	SensorConstraints to apply.	required
tracking_ephemeris	Optional[Ephemeris]	Optional bore-pointing override; when provided, the stored Az/El is ignored and the bore at each epoch is tracking_ephemeris_pos − observer_pos.	...

Returns:

Type	Description
SensorAccessReport	A SensorAccessReport.

Raises:

Type	Description
ValueError	If any satellite lacks a cached ephemeris or an inner gate evaluation fails.

Logging

Emits info-level entry/exit records on the keplime logger with the constellation size, time window, and elapsed wall time; debug records per target with the target id, elapsed time, and access count; and warn records when ephemerides are missing or a per-target evaluation panics (panicking targets are returned as empty reports so the batch continues). See keplime.__doc__ for how to surface these logs in the hosting application.

get_sensor_access_to_satellite(satellite, start, end, constraints, tracking_ephemeris=...)

Convenience: reports access windows to satellite's cached ephemeris over [start, end].

Parameters:

Name	Type	Description	Default
satellite	Satellite	Target Satellite. Must have a cached ephemeris.	required
start	ModifiedJulianDate	Start of the search range.	required
end	ModifiedJulianDate	End of the search range.	required
constraints	SensorConstraints	SensorConstraints to apply.	required
tracking_ephemeris	Optional[Ephemeris]	Optional bore-pointing override; when provided, the stored Az/El is ignored and the bore at each epoch is tracking_ephemeris_pos − observer_pos.	...

Returns:

Type	Description
SensorAccessReport	A SensorAccessReport.

Raises:

Type	Description
ValueError	If the satellite has no cached ephemeris or an inner gate evaluation fails.

Hypothesis

A single candidate orbit hypothesis for one tracklet, at a common reference epoch.

A hypothesis is what classical IOD produces (one per tracklet) and what an admissible-region particle promotes to (many per tracklet). Both paths use the same type so downstream correlation and refinement stages do not need to dispatch on which path produced the hypothesis.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Reference epoch the state and covariance are valid at.
state	CartesianState	Candidate inertial Cartesian state at epoch [km, km/s].
covariance	CovarianceMatrix	State covariance at epoch, frame-tagged per ADR 0001.
weight	float	Non-negative weight assigned to this hypothesis [dimensionless; ≥ 0]. Weights across a HypothesisCloud need not sum to 1; downstream stages normalize as needed.

covariance property

State covariance at epoch, frame-tagged per ADR 0001.

epoch property

Reference epoch the state and covariance are valid at.

state property

Candidate inertial Cartesian state at epoch [km, km/s].

weight property

Non-negative weight assigned to this hypothesis [dimensionless; ≥ 0].

__init__(epoch, state, covariance, weight)

Creates a new Hypothesis.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Reference epoch for state and covariance.	required
state	CartesianState	Inertial Cartesian state [km, km/s].	required
covariance	CovarianceMatrix	Frame-tagged state covariance.	required
weight	float	Non-negative hypothesis weight [dimensionless; ≥ 0].	required

__repr__()

Returns Hypothesis(epoch=…, weight=…).

HypothesisCloud

Weighted ensemble of Hypothesis entries for one tracklet at a common epoch.

Cloud size is one for the classical-IOD path and many (typically 256 with the default AdmissibleRegionSampling.QuasiMonteCarlo settings) for the ensemble path.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Common epoch shared by every entry in hypotheses.
hypotheses	list[Hypothesis]	Hypotheses comprising the cloud. Each hypothesis carries its own state, covariance, and weight; all hypotheses share epoch.

epoch property

Common epoch shared by every hypothesis in this cloud.

hypotheses property

Hypotheses comprising the cloud.

__init__(epoch, hypotheses)

Creates a new HypothesisCloud.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Reference epoch shared by every hypothesis.	required
hypotheses	list[Hypothesis]	Hypotheses at the common epoch.	required

__len__()

Number of hypotheses in the cloud.

__repr__()

Returns HypothesisCloud(epoch=…, n_hypotheses=…).

is_empty()

True when the cloud has no hypotheses.

KeplerianElements

Classical Keplerian orbital elements for an elliptic orbit.

The six elements fully characterize a two-body Keplerian orbit at a given epoch. They are the standard representation for near-circular orbits (eccentricity < 1); degenerate cases (equatorial or circular) are representable but some derived quantities become ill-conditioned. Convert to EquinoctialElements for a singularity-free representation, or to CartesianState for propagation and observation modeling.

Attributes:

Name	Type	Description
semi_major_axis	float	Semi-major axis [km; > 0].
eccentricity	float	Eccentricity [dimensionless; 0..1).
inclination	float	Inclination [rad; 0..π].
ascending_node	float	Right ascension of the ascending node [rad; 0..2π).
argument_of_periapsis	float	Argument of periapsis [rad; 0..2π).
mean_anomaly	float	Mean anomaly [rad; 0..2π).
periapsis	float	Periapsis radius a (1 − e) [km].
apoapsis	float	Apoapsis radius a (1 + e) [km].

apoapsis property

Apoapsis (farthest point) radius from the central body's center [km].

Computed as a (1 + e). For a circular orbit (e = 0) this equals the semi-major axis.

argument_of_periapsis property

Argument of periapsis [rad; 0..2π).

ascending_node property

Right ascension of the ascending node [rad; 0..2π).

eccentricity property

Eccentricity [dimensionless; 0..1).

inclination property

Inclination [rad; 0..π].

mean_anomaly property

Mean anomaly [rad; 0..2π).

periapsis property

Periapsis (closest approach) radius from the central body's center [km].

Computed as a (1 − e). For a circular orbit (e = 0) this equals the semi-major axis.

semi_major_axis property

Semi-major axis [km; > 0].

__init__(semi_major_axis, eccentricity, inclination, ascending_node, argument_of_periapsis, mean_anomaly)

Creates classical Keplerian elements from the six element components.

Parameters:

Name	Type	Description	Default
semi_major_axis	float	Semi-major axis [km; > 0].	required
eccentricity	float	Eccentricity [dimensionless; 0..1).	required
inclination	float	Inclination [rad; 0..π].	required
ascending_node	float	Right ascension of the ascending node [rad; 0..2π).	required
argument_of_periapsis	float	Argument of periapsis [rad; 0..2π).	required
mean_anomaly	float	Mean anomaly at epoch [rad; 0..2π).	required

Returns:

Type	Description
None	KeplerianElements with the given components.

to_cartesian(epoch, frame, mu)

Converts these Keplerian elements to a Cartesian state vector.

The eccentric anomaly is solved from the mean anomaly using Halley's method (cubic convergence, typically 3–4 iterations). The perifocal position and velocity are then rotated into the requested reference frame via the argument-of-periapsis, RAAN, and inclination rotation sequence.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the output state vector.	required
frame	ReferenceFrame	Reference frame for the output state.	required
mu	float	Gravitational parameter of the central body [km³/s²].	required

Returns:

Type	Description
CartesianState	Cartesian state with position [km] and velocity [km/s] at the
CartesianState	given epoch in the specified frame.

Raises:

Type	Description
ValueError	If semi_major_axis is not positive or eccentricity is outside [0, 1).

to_equinoctial()

Converts these Keplerian elements to the equinoctial element set.

The equinoctial elements avoid the coordinate singularities present in classical Keplerian elements for equatorial and circular orbits. See EquinoctialElements for the component definitions.

Returns:

Type	Description
EquinoctialElements	Equivalent singularity-free equinoctial elements.

KeplerianState

Keplerian orbital state at an epoch.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Epoch of the state.
keplerian_elements	KeplerianElements	Classical orbital elements.
keplerian_type	KeplerianType	Mean-motion theory classification.
mean_motion	float	Mean motion derived from the semi-major axis [rev/day].
period	float	Orbital period derived from the semi-major axis [s].

epoch property

Epoch of the state.

keplerian_elements property

Classical orbital elements.

keplerian_type property

Mean-motion theory (Kozai, Brouwer, or osculating).

mean_motion property

Mean motion derived from the semi-major axis [rev/day].

period property

Orbital period derived from the semi-major axis [s].

Computed as T = 2π √(a³/μ). Returns NaN if semi_major_axis ≤ 0.

Returns:

Type	Description
float	Orbital period [s].

to_cartesian()

Converts this state to an inertial Cartesian state.

Returns:

Type	Description
CartesianState	Cartesian state [position in km, velocity in km/s].

Raises:

Type	Description
ValueError	If the conversion fails.

OrbitPlotData

An ordered collection of OrbitPlotState snapshots for a satellite.

Attributes:

Name	Type	Description
satellite_id	str	Identifier of the satellite.
epochs	list[str]	ISO 8601 epoch strings.
latitudes	list[float]	Geodetic latitudes [rad].
longitudes	list[float]	Geodetic longitudes [rad].
altitudes	list[float]	Altitudes above WGS-84 ellipsoid [km].
semi_major_axes	list[float]	Semi-major axes [km].
eccentricities	list[float]	Eccentricities [dimensionless].
inclinations	list[float]	Inclinations [rad].
ascending_nodes	list[float]	Right ascensions of ascending node [rad].
radii	list[float]	Orbital radii [km].
apogee_radii	list[float]	Apogee radii [km].
perigee_radii	list[float]	Perigee radii [km].

altitudes property

Altitudes above WGS-84 ellipsoid [km].

apogee_radii property

Apogee radii [km].

ascending_nodes property

Right ascensions of ascending node [rad; 0..2π).

eccentricities property

Eccentricities [dimensionless; 0..1).

epochs property

ISO 8601 epoch strings for each snapshot.

inclinations property

Inclinations [rad; 0..π].

latitudes property

Geodetic latitudes [rad; -π/2..π/2].

longitudes property

Geodetic longitudes [rad; -π..π].

perigee_radii property

Perigee radii [km].

radii property

Orbital radii at each epoch [km].

satellite_id property

Identifier of the satellite.

semi_major_axes property

Semi-major axes [km].

__init__(satellite_id)

Creates an empty OrbitPlotData for the given satellite.

Parameters:

Name	Type	Description	Default
satellite_id	str	Identifier of the satellite.	required

add_state(plot_state)

Appends an OrbitPlotState to this collection.

Parameters:

Name	Type	Description	Default
plot_state	OrbitPlotState	Snapshot to append.	required

OrbitPlotState

A snapshot of geodetic and orbital parameters for orbit visualization.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Epoch of the snapshot.
latitude	float	Geodetic latitude [rad; -π/2..π/2].
longitude	float	Geodetic longitude [rad; -π..π].
altitude	float	Altitude above WGS-84 ellipsoid [km].
semi_major_axis	float	Semi-major axis [km].
eccentricity	float	Eccentricity [dimensionless; 0..1).
inclination	float	Inclination [rad; 0..π].
ascending_node	float	Right ascension of ascending node [rad; 0..2π).
radius	float	Orbital radius at this epoch [km].
apogee_radius	float	Apogee radius [km].
perigee_radius	float	Perigee radius [km].

altitude property

Altitude above WGS-84 ellipsoid [km].

apogee_radius property

Apogee radius [km].

ascending_node property

Right ascension of ascending node [rad; 0..2π).

eccentricity property

Eccentricity [dimensionless; 0..1).

epoch property

Epoch of the snapshot.

inclination property

Inclination [rad; 0..π].

latitude property

Geodetic latitude [rad; -π/2..π/2].

longitude property

Geodetic longitude [rad; -π..π].

perigee_radius property

Perigee radius [km].

radius property

Orbital radius at this epoch [km].

semi_major_axis property

Semi-major axis [km].

__init__(epoch, geodetic, orbital, radii)

Creates an OrbitPlotState.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Epoch of the snapshot.	required
geodetic	tuple[float, float, float]	(latitude [rad], longitude [rad], altitude [km]).	required
orbital	tuple[float, float, float, float]	(semi_major_axis [km], eccentricity, inclination [rad], ascending_node [rad]).	required
radii	tuple[float, float, float]	(radius [km], apogee_radius [km], perigee_radius [km]).	required

SphericalVector

Spherical coordinates: range, right ascension, and declination.

Attributes:

Name	Type	Description
range	float	Radial distance [km].
right_ascension	float	Right ascension [rad; -π..π].
declination	float	Declination [rad; -π/2..π/2].

declination property

Declination [rad; -π/2..π/2].

range property

Radial distance [km].

right_ascension property

Right ascension [rad; -π..π].

__init__(range, right_ascension, declination)

Creates a SphericalVector from explicit components.

Parameters:

Name	Type	Description	Default
range	float	Radial distance [km].	required
right_ascension	float	Right ascension [rad; -π..π].	required
declination	float	Declination [rad; -π/2..π/2].	required

__repr__()

Returns SphericalVector(range=…, right_ascension=…, declination=…).

from_cartesian(vector) staticmethod

Converts a CartesianVector to spherical coordinates.

Parameters:

Name	Type	Description	Default
vector	CartesianVector	Input Cartesian vector [km].	required

Returns:

Type	Description
SphericalVector	Equivalent SphericalVector.

to_cartesian()

Converts this SphericalVector to a CartesianVector.

Returns:

Type	Description
CartesianVector	Equivalent Cartesian vector [km].

TLE

A Two-Line Element set for a space object.

Parses the NORAD TLE format and exposes orbital elements, epoch, force terms, and conversions to Keplerian and Cartesian states.

Attributes:

Name	Type	Description
id	str	Object identifier (settable; defaults to satellite number).
name	Optional[str]	Optional common name from line 0.
line1	str	Reconstructed TLE line 1.
line2	str	Reconstructed TLE line 2.
epoch	ModifiedJulianDate	TLE epoch (UTC).
keplerian_state	KeplerianState	Keplerian state at TLE epoch.
mean_motion	float	Mean motion [rev/day].
force_terms	TLEForceTerms	SGP4/SDP4 perturbation parameters.
cartesian_state	CartesianState	Cartesian state at TLE epoch in TEME.
b_star	float	B* drag parameter [1/earth-radii].
satellite_number	int	Satellite catalog number.
norad_id	int	Alias for satellite_number.
classification	Classification	Security classification.
international_designator	str	International launch designator.
ephemeris_type	int	Ephemeris type field.
element_set_number	int	Element set number.
revolution_number	int	Revolution number at epoch.
keplerian_type	KeplerianType	Mean-motion theory (Kozai GP).
semi_major_axis	float	Semi-major axis derived from mean motion [km].
inclination	float	Inclination [rad; 0..π].
raan	float	Right ascension of ascending node [rad; 0..2π).
eccentricity	float	Eccentricity [dimensionless; 0..1).
argument_of_perigee	float	Argument of perigee [rad; 0..2π).
mean_anomaly	float	Mean anomaly [rad; 0..2π).
mean_motion_dot	float	First-order mean motion derivative [(rev/day)/day].
mean_motion_dot_dot	float	Second-order mean motion derivative [(rev/day)/day²].
b_term	float	B* in alternate notation [1/earth-radii].
agom	Optional[float]	Area-to-mass ratio for XP [m²/kg], or None.
periapsis	float	Periapsis radius [km].
apoapsis	float	Apoapsis radius [km].

agom property

Area-to-mass ratio for XP [m²/kg], or None.

apoapsis property

Apoapsis radius [km].

argument_of_perigee property

Argument of perigee [rad; 0..2π).

b_star property

B* drag parameter [1/earth-radii].

b_term property

B* drag term [1/earth-radii].

cartesian_state property

Cartesian state at TLE epoch in TEME [position in km, velocity in km/s].

classification property

Security classification.

eccentricity property

Eccentricity [dimensionless; 0..1).

element_set_number property

Element set number.

ephemeris_type property

Ephemeris type field from the TLE.

epoch property

TLE epoch (UTC).

force_terms property

SGP4/SDP4 perturbation parameters.

id property writable

Object identifier (settable).

inclination property

Inclination [rad; 0..π].

international_designator property

International launch designator.

keplerian_state property

Keplerian state at TLE epoch.

keplerian_type property

Mean-motion theory (Kozai GP / SGP4).

line1 property

Reconstructed TLE line 1.

line2 property

Reconstructed TLE line 2.

mean_anomaly property

Mean anomaly [rad; 0..2π).

mean_motion property

Mean motion [rev/day].

mean_motion_dot property

First-order mean motion derivative [(rev/day)/day].

mean_motion_dot_dot property

Second-order mean motion derivative [(rev/day)/day²].

name property

Optional common name from line 0.

norad_id property

NORAD catalog number (alias for satellite_number).

periapsis property

Periapsis radius [km].

raan property

Right ascension of ascending node [rad; 0..2π).

revolution_number property

Revolution number at epoch.

satellite_number property

Satellite catalog number.

semi_major_axis property

Semi-major axis derived from mean motion [km].

__init__(line1, line2, name=None)

Parses a TLE from two lines and an optional name.

Parameters:

Name	Type	Description	Default
line1	str	TLE line 1 (69-character NORAD format).	required
line2	str	TLE line 2 (69-character NORAD format).	required
name	Optional[str]	Optional object name (line 0).	None

Raises:

Type	Description
ValueError	If the TLE lines cannot be parsed.

__repr__()

Returns TLE(name=…, line1='…', line2='…'), or TLE(name=…, line_error='…') when a line cannot be rendered.

with_id(id)

Returns a copy with a new identifier.

Parameters:

Name	Type	Description	Default
id	str	New identifier string.	required

Returns:

Type	Description
TLE	TLE with the updated id.

TLEForceTerms

SGP4/SDP4 force model perturbation terms from a TLE.

Attributes:

Name	Type	Description
mean_motion_dot	float	First-order mean motion derivative [(rev/day)/day]. Integrated only by PPT3 as its secular mean-anomaly drag; SGP4/SDP4 store but ignore it. Estimable through PPT3 drag estimation.
mean_motion_dot_dot	float	Second-order mean motion derivative [(rev/day)/day²]. Ignored by every propagator (SGP4/SDP4 never read it; PPT3 pins it to zero); retained only for TLE round-trip fidelity.
b_term	float	B* drag term [1/earth-radii].
agom	Optional[float]	Area-to-mass ratio for XP propagator [m²/kg], or None if not present in the TLE.

agom property

Area-to-mass ratio for the XP propagator [m²/kg], or None.

b_term property

B* drag term [1/earth-radii].

mean_motion_dot property

First-order mean motion derivative [(rev/day)/day].

mean_motion_dot_dot property

Second-order mean motion derivative [(rev/day)/day²].

TopocentricElements

Angular and range observation in a topocentric (observer-centered) frame.

All fields are optional to support partial observations (angles-only, range-only, or full six-component measurements).

Attributes:

Name	Type	Description
range	Optional[float]	Slant range from observer to target [km].
range_rate	Optional[float]	Range-rate [km/s].
right_ascension	Optional[float]	Right ascension [rad; -π..π].
declination	Optional[float]	Declination [rad; -π/2..π/2].
right_ascension_rate	Optional[float]	Right ascension rate [rad/s].
declination_rate	Optional[float]	Declination rate [rad/s].
observed_direction	Optional[CartesianVector]	Unit direction vector from right ascension and declination; None if either angle is absent.

declination property

Declination [rad; -π/2..π/2], or None.

declination_rate property

Declination rate [rad/s], or None.

observed_direction property

Unit direction vector from right ascension and declination.

Returns None when either angle is absent.

range property

Slant range from observer to target [km], or None.

range_rate property

Range-rate [km/s], or None.

right_ascension property

Right ascension [rad; -π..π], or None.

right_ascension_rate property

Right ascension rate [rad/s], or None.

__init__(right_ascension, declination)

Creates TopocentricElements with angular components only.

Use builder methods to attach optional range and rate fields.

Parameters:

Name	Type	Description	Default
right_ascension	Optional[float]	Right ascension [rad; -π..π], or None.	required
declination	Optional[float]	Declination [rad; -π/2..π/2], or None.	required

__repr__()

Returns TopocentricElements(right_ascension=…, declination=…).

with_declination_rate(declination_rate)

Returns a copy with the declination-rate field set.

Parameters:

Name	Type	Description	Default
declination_rate	Optional[float]	Declination rate [rad/s], or None.	required

Returns:

Type	Description
TopocentricElements	Updated TopocentricElements.

with_range(range)

Returns a copy with the range field set.

Parameters:

Name	Type	Description	Default
range	Optional[float]	Slant range [km], or None.	required

Returns:

Type	Description
TopocentricElements	Updated TopocentricElements.

with_range_rate(range_rate)

Returns a copy with the range-rate field set.

Parameters:

Name	Type	Description	Default
range_rate	Optional[float]	Range-rate [km/s], or None.	required

Returns:

Type	Description
TopocentricElements	Updated TopocentricElements.

with_right_ascension_rate(right_ascension_rate)

Returns a copy with the right-ascension-rate field set.

Parameters:

Name	Type	Description	Default
right_ascension_rate	Optional[float]	Right ascension rate [rad/s], or None.	required

Returns:

Type	Description
TopocentricElements	Updated TopocentricElements.

TopocentricState

A topocentric observation at an epoch with an associated observer state.

Attributes:

Name	Type	Description
epoch	ModifiedJulianDate	Observation epoch.
elements	TopocentricElements	Angular and range measurements.
reference_frame	ReferenceFrame	Frame in which angles are expressed.
origin_state	CartesianState	Observer Cartesian state at the epoch.

elements property

Angular and range measurements.

epoch property

Observation epoch.

origin_state property

Observer Cartesian state at the epoch.

reference_frame property

Reference frame in which angles are expressed.

__init__(epoch, elements, reference_frame, origin_state)

Creates a TopocentricState.

The origin_state epoch must match epoch; it will be automatically converted to reference_frame.

Parameters:

Name	Type	Description	Default
epoch	ModifiedJulianDate	Observation epoch.	required
elements	TopocentricElements	Angular and range measurements.	required
reference_frame	ReferenceFrame	Frame for the angular elements.	required
origin_state	CartesianState	Observer Cartesian state.	required

__repr__()

Returns TopocentricState(epoch=…, reference_frame=…).

from_horizon_state(state, reference_frame) staticmethod

Converts a HorizonState to a TopocentricState.

Transforms azimuth/elevation to right ascension/declination.

Parameters:

Name	Type	Description	Default
state	HorizonState	Source horizon state.	required
reference_frame	ReferenceFrame	Frame for the output angles.	required

Returns:

Type	Description
TopocentricState	Equivalent TopocentricState in reference_frame.

Raises:

Type	Description
ValueError	If frame conversion fails.

get_sensor_access_report(candidates, start, end, constraints, tracking_ephemeris=...)

Reports access windows from this observation to candidates.

The observer is treated as Earth-fixed (origin_state is converted to ITRF and re-sampled into a TEME ephemeris over the search range). When tracking_ephemeris is None, the stored RA/Dec drives the inertial boresight; when Some, the stored RA/Dec is bypassed and the bore at each epoch is tracking_ephemeris_pos − observer_pos.

Parameters:

Name	Type	Description	Default
candidates	list[Ephemeris]	Target ephemerides to evaluate against the bore.	required
start	ModifiedJulianDate	Start of the search range.	required
end	ModifiedJulianDate	End of the search range.	required
constraints	SensorConstraints	SensorConstraints to apply.	required
tracking_ephemeris	Optional[Ephemeris]	Optional bore-pointing override; when provided, the stored RA/Dec is ignored.	...

Returns:

Type	Description
SensorAccessReport	A SensorAccessReport aggregating
SensorAccessReport	all candidate access windows.

Raises:

Type	Description
ValueError	If start > end, the observer cannot be lifted, the stored elements lack RA or Dec (and no override is supplied), or an inner gate evaluation fails.

get_sensor_access_to_constellation(constellation, start, end, constraints, tracking_ephemeris=...)

Convenience: reports access windows to every cached ephemeris in constellation over [start, end].

Satellites are iterated in sorted-id order for deterministic output ordering.

Parameters:

Name	Type	Description	Default
constellation	Constellation	Target Constellation. Every satellite must have a cached ephemeris.	required
start	ModifiedJulianDate	Start of the search range.	required
end	ModifiedJulianDate	End of the search range.	required
constraints	SensorConstraints	SensorConstraints to apply.	required
tracking_ephemeris	Optional[Ephemeris]	Optional bore-pointing override; when provided, the stored RA/Dec is ignored and the bore at each epoch is tracking_ephemeris_pos − observer_pos.	...

Returns:

Type	Description
SensorAccessReport	A SensorAccessReport.

Raises:

Type	Description
ValueError	If any satellite lacks a cached ephemeris or an inner gate evaluation fails.

Logging

Emits info-level entry/exit records on the keplime logger with the constellation size, time window, and elapsed wall time; debug records per target with the target id, elapsed time, and access count; and warn records when ephemerides are missing or a per-target evaluation panics (panicking targets are returned as empty reports so the batch continues). See keplime.__doc__ for how to surface these logs in the hosting application.

get_sensor_access_to_satellite(satellite, start, end, constraints, tracking_ephemeris=...)

Convenience: reports access windows to satellite's cached ephemeris over [start, end].

Parameters:

Name	Type	Description	Default
satellite	Satellite	Target Satellite. Must have a cached ephemeris.	required
start	ModifiedJulianDate	Start of the search range.	required
end	ModifiedJulianDate	End of the search range.	required
constraints	SensorConstraints	SensorConstraints to apply.	required
tracking_ephemeris	Optional[Ephemeris]	Optional bore-pointing override; when provided, the stored RA/Dec is ignored and the bore at each epoch is tracking_ephemeris_pos − observer_pos.	...

Returns:

Type	Description
SensorAccessReport	A SensorAccessReport.

Raises:

Type	Description
ValueError	If the satellite has no cached ephemeris or an inner gate evaluation fails.

to_frame(reference_frame)

Converts this state to a different reference frame.

Parameters:

Name	Type	Description	Default
reference_frame	ReferenceFrame	Target reference frame.	required

Returns:

Type	Description
TopocentricState	Equivalent TopocentricState in reference_frame.

Raises:

Type	Description
ValueError	If the frame conversion is not supported.

Tracklet

Ordered sequence of observations from a single sensor over a short arc.

A Tracklet is the front-end product of the UCT pipeline's tracklet-formation stage — it groups raw observations that motion-continuity analysis suggests come from the same physical object. The grouping is hypothetical at this stage; correlation, IOD, and refinement downstream either accept the tracklet (by fitting a state from it) or discard it.

All observations in a tracklet share the same sensor and must be sorted ascending by epoch. The modality tag drives downstream IOD and admissible-region dispatch.

Attributes:

Name	Type	Description
sensor_id	str	Identifier of the sensor that produced every observation in this tracklet.
observations	list[Observation]	Time-ordered observations, sorted ascending by epoch.
modality	TrackletModality	Measurement modality common to all observations.
start_epoch	ModifiedJulianDate | None	Epoch of the earliest observation, or None when the tracklet is empty.
end_epoch	ModifiedJulianDate | None	Epoch of the latest observation, or None when the tracklet is empty.

end_epoch property

Epoch of the latest observation, or None when empty.

modality property

Measurement modality common to all observations.

observations property

Time-ordered observations, sorted ascending by epoch.

sensor_id property

Identifier of the sensor that produced every observation.

start_epoch property

Epoch of the earliest observation, or None when empty.

__init__(sensor_id, observations, modality)

Creates a Tracklet.

The caller is responsible for ensuring every observation shares sensor_id and that the observations are sorted ascending by epoch.

Parameters:

Name	Type	Description	Default
sensor_id	str	Identifier of the producing sensor.	required
observations	list[Observation]	Time-ordered observations belonging to this tracklet.	required
modality	TrackletModality	Measurement modality shared by every observation.	required

__len__()

Number of observations in the tracklet.

get_associations(constellation, config=None)

Associates this tracklet to a constellation by track angles and rates.

For every satellite, scores the tracklet's observations in one batch and reduces them to a TrackletResidual — the arc-mean offset (mean-vs-expected) and the slope offset (slope-vs-expected-rate). The residual is gated against config and the tracklet's confidence is the worst across present components. Satellites that cannot be predicted at the tracklet's epochs are skipped; survivors are returned best-first. An orphan tracklet returns an empty list.

Parameters:

Name	Type	Description	Default
constellation	Constellation	Catalog of candidate satellites.	required
config	Optional[TrackletAssociationConfig]	Gate thresholds. Defaults to the built-in starting values when None.	None

Returns:

Type	Description
list[TrackletAssociation]	Gate-passing associations, best-first.

Raises:

Type	Description
ValueError	On an unexpected per-satellite scoring failure.

get_list(observations, strategy=None) staticmethod

Groups raw observations into tracklets using a formation strategy.

Partitions observations by sensor, sorts each group by epoch, splits the stream into short arcs per the strategy, drops singletons, and tags each tracklet with its inferred modality. Parallels ObservationCollection.get_list.

Parameters:

Name	Type	Description	Default
observations	list[Observation]	Raw batch of observations to group.	required
strategy	Optional[TrackletFormation]	Formation strategy. Defaults to the adaptive-motion-continuity strategy when None.	None

Returns:

Type	Description
list[Tracklet]	Tracklets ordered by first-observation epoch ascending.

is_empty()

True when the tracklet has no observations.

TrackletFit

Compact mid-epoch summary of a Tracklet, produced by linear/quadratic fitting of its observations.

TrackletFit is the form downstream pipeline stages (IOD, admissible-region construction, correlation) consume — raw observations are not re-read after fitting. The replacement for the academic SDA term "attributable", chosen for self-documentation.

For optical (angles-only) tracklets the fit produces right-ascension / declination and their time derivatives at the tracklet's mid-epoch. For radar / RF tracklets the fit additionally produces measured range and range-rate. The fit retains the source TrackletModality so downstream UCT stages can dispatch without carrying a parallel raw-tracklet lookup.

Attributes:

Name	Type	Description
modality	TrackletModality	Measurement modality inferred from the source tracklet.
epoch	ModifiedJulianDate	Mid-epoch of the tracklet (typically the median observation epoch).
right_ascension	float	Fit right ascension at epoch [rad; −π..π).
declination	float	Fit declination at epoch [rad; −π/2..π/2].
right_ascension_rate	float	Fit right-ascension rate at epoch [rad/s]. Carries the cos(declination) correction so the topocentric great-circle rate matches the on-sky angular rate.
declination_rate	float	Fit declination rate at epoch [rad/s].
range	tuple[float, float] | None	Optional fit range and range-rate (ρ, ρ̇) [km, km/s]. Populated for radar / RF tracklets, None for angles-only optical tracklets.
observer_state	CartesianState	Inertial Cartesian state of the observer at epoch [km, km/s].

declination property

Fit declination at epoch [rad; −π/2..π/2].

declination_rate property

Fit declination rate at epoch [rad/s].

epoch property

Mid-epoch of the tracklet (typically the median observation epoch).

modality property

Measurement modality inferred from the source tracklet.

observer_state property

Inertial Cartesian state of the observer at epoch [km, km/s].

range property

Optional fit (range_km, range_rate_km_per_s) [km, km/s], or None for angles-only tracklets.

right_ascension property

Fit right ascension at epoch [rad; −π..π).

right_ascension_rate property

Fit right-ascension rate at epoch [rad/s].

__init__(modality, epoch, angles, angle_rates, range, observer_state)

Creates a new TrackletFit from already-computed fit values.

Use this when a caller has already performed tracklet fitting and needs to assemble the compact representation consumed by UCT IOD and admissible-region stages.

Parameters:

Name	Type	Description	Default
modality	TrackletModality	Measurement modality inferred from the source tracklet.	required
epoch	ModifiedJulianDate	Mid-epoch of the tracklet.	required
angles	tuple[float, float]	Fit (right_ascension, declination) at epoch [rad; right ascension normalized to −π..π, declination in −π/2..π/2].	required
angle_rates	tuple[float, float]	Fit (right_ascension_rate, declination_rate) at epoch [rad/s].	required
range	Optional[tuple[float, float]]	Optional (ρ, ρ̇) for radar / RF tracklets [km, km/s]. Pass None for angles-only tracklets.	required
observer_state	CartesianState	Inertial observer state at epoch [km, km/s].	required

__repr__()

Returns TrackletFit(modality=…, epoch=…, ra=…, dec=…).

brouwer_to_kozai(eccentricity, inclination, mean_motion_brouwer)

Converts Brouwer mean motion to Kozai mean motion.

Inverts kozai_to_brouwer iteratively using Newton–Raphson.

Parameters:

Name	Type	Description	Default
eccentricity	float	Orbital eccentricity [dimensionless; 0..1).	required
inclination	float	Orbital inclination [rad; 0..π].	required
mean_motion_brouwer	float	Brouwer mean motion [rev/day].	required

Returns:

Type	Description
float	Kozai mean motion [rev/day].

is_land(latitude, longitude)

Returns whether a geodetic location lies on land.

Looks up the cell containing the point in the embedded 0.25° land raster. Longitude is wrapped into [-180, 180) and latitude clamped to [-90, 90], so any finite input is valid. Coastline fidelity is limited by the raster resolution (~28 km); treat near-shore results as approximate.

Parameters:

Name	Type	Description	Default
latitude	float	Geodetic latitude [rad; -π/2..π/2].	required
longitude	float	Geodetic longitude [rad; -π..π].	required

Returns:

Type	Description
bool	True if the cell containing the point is land, False if ocean.

kozai_to_brouwer(eccentricity, inclination, mean_motion_kozai)

Converts Kozai mean motion to Brouwer mean motion.

Applies the J₂ SGP4 correction using WGS-72 constants.

Parameters:

Name	Type	Description	Default
eccentricity	float	Orbital eccentricity [dimensionless; 0..1).	required
inclination	float	Orbital inclination [rad; 0..π].	required
mean_motion_kozai	float	Kozai mean motion [rev/day].	required

Returns:

Type	Description
float	Brouwer mean motion [rev/day].

mean_motion_from_semi_major_axis(sma_km, mu)

Converts semi-major axis to mean motion.

Parameters:

Name	Type	Description	Default
sma_km	float	Semi-major axis [km; > 0].	required
mu	float	Standard gravitational parameter [km³/s²].	required

Returns:

Type	Description
float	Mean motion [rev/day].

Raises:

Type	Description
ValueError	If sma_km is not positive.

semi_major_axis_from_mean_motion(mean_motion_rev_day, mu)

Converts mean motion to semi-major axis.

Parameters:

Name	Type	Description	Default
mean_motion_rev_day	float	Mean motion [rev/day; > 0].	required
mu	float	Standard gravitational parameter [km³/s²].	required

Returns:

Type	Description
float	Semi-major axis [km].

Raises:

Type	Description
ValueError	If mean_motion_rev_day is not positive.