keplemon.bodies

bodies

Constellation

count instance-attribute

Number of satellites in the constellation

name instance-attribute

Human-readable name of the constellation

cache_ephemeris(start, end, step, purge_on_fail=False)

Cache ephemeris for all satellites in the constellation.

This pre-computes and caches ephemeris data for each satellite, enabling faster interpolation-based state lookups via interpolate_state_at_epoch.

Parameters:

Name	Type	Description	Default
start	Epoch	Start epoch for ephemeris caching	required
end	Epoch	End epoch for ephemeris caching	required
step	TimeSpan	Time step between cached states	required
purge_on_fail	bool	Remove satellites that fail to build ephemeris	False

from_tle_catalog(tle_catalog) classmethod

Instantiate a Constellation from a TLE catalog

Parameters:

Name	Type	Description	Default
tle_catalog	TLECatalog	TLE catalog for the constellation	required

get_association_reports(collections)

Get association reports for multiple observation collections.

Parameters:

Name	Type	Description	Default
collections	list[ObservationCollection]	List of observation collections to find associations for	required

Returns:

Type	Description
list[CollectionAssociationReport]	List of CollectionAssociationReport, one per input collection

get_ca_report_vs_many(start, end, distance_threshold)

Calculate close approaches among satellites in the calling constellation.

Warning

This is a long-running operation when the constellation is large.

Parameters:

Name	Type	Description	Default
start	Epoch	UTC epoch of the start of the close approach report	required
end	Epoch	UTC epoch of the end of the close approach report	required
distance_threshold	float	Distance threshold for close approach screening in kilometers	required

Returns:

Type	Description
CloseApproachReport	Close approach report for the constellation vs. all other satellites

get_ca_report_vs_one(other, start, end, distance_threshold)

Calculate close approaches between the constellation and a given satellite.

Parameters:

Name	Type	Description	Default
other	Satellite	Satellite to compare against	required
start	Epoch	UTC epoch of the start of the close approach report	required
end	Epoch	UTC epoch of the end of the close approach report	required
distance_threshold	float	Distance threshold for close approach screening in kilometers	required

Returns:

Type	Description
CloseApproachReport	Close approach report for the constellation vs. the given satellite

get_ephemeris(start, end, step)

Parameters:

Name	Type	Description	Default
start	Epoch	UTC epoch of the start of the ephemeris	required
end	Epoch	UTC epoch of the end of the ephemeris	required
step	TimeSpan	Time step for the ephemeris	required

Returns:

Type	Description
dict[str, Ephemeris]	(satellite_id, ephemeris) dictionary for the constellation

get_horizon_access_report(site, start, end, min_el, min_duration)

Calculate horizon access to a given observatory.

Parameters:

Name	Type	Description	Default
site	Observatory	Observatory to check for horizon access	required
start	Epoch	UTC epoch of the start of the report	required
end	Epoch	UTC epoch of the end of the report	required
min_el	float	Minimum elevation angle in degrees	required
min_duration	TimeSpan	Minimum duration of access	required

Returns:

Type	Description
HorizonAccessReport	Horizon access report for the constellation from the observatory

get_maneuver_events(future_sats, start, end, distance_threshold, velocity_threshold)

Detect maneuvers by comparing current satellite states with future states.

Matches satellites by ID between the two constellations and detects maneuvers where the velocity difference exceeds the threshold.

Parameters:

Name	Type	Description	Default
future_sats	Constellation	Constellation with future epoch states to compare against	required
start	Epoch	UTC epoch of the start of the search window	required
end	Epoch	UTC epoch of the end of the search window	required
distance_threshold	float	Distance threshold for matching in kilometers	required
velocity_threshold	float	Velocity threshold for maneuver detection in meters per second	required

Returns:

Type	Description
ManeuverReport	ManeuverReport containing all detected maneuvers

get_proximity_report_vs_many(start, end, distance_threshold)

Check which satellite pairs in the constellation stay within a distance threshold.

Parameters:

Name	Type	Description	Default
start	Epoch	UTC epoch of the start of the report	required
end	Epoch	UTC epoch of the end of the report	required
distance_threshold	float	Maximum distance threshold in kilometers	required

Returns:

Type	Description
ProximityReport	Proximity report containing events for satellite pairs that stay within threshold

get_proximity_report_vs_one(other, start, end, distance_threshold)

Check which constellation satellites stay within a distance threshold of a given satellite.

Parameters:

Name	Type	Description	Default
other	Satellite	Satellite to compare against	required
start	Epoch	UTC epoch of the start of the report	required
end	Epoch	UTC epoch of the end of the report	required
distance_threshold	float	Maximum distance threshold in kilometers	required

Returns:

Type	Description
ProximityReport	Proximity report containing events for satellite pairs that stay within threshold

get_states_at_epoch(epoch)

Parameters:

Name	Type	Description	Default
epoch	Epoch	UTC epoch at which the states will be calculated	required

Returns:

Type	Description
dict[int, CartesianState]	(satellite_id, state) dictionary for the constellation at the given epoch

get_uct_validity(uct, all_collections, orphan_collections)

Analyze the validity of a UCT (Uncorrelated Track) against the constellation.

This method uses cached ephemeris to analyze: - Observation associations with orphan observations - Proximity events with approved satellites (possible cross-tags) - Close approaches with approved satellites (possible maneuver origins)

The analysis window is automatically determined based on the UCT's orbital period and the constellation's cached ephemeris bounds.

Parameters:

Name	Type	Description	Default
uct	Satellite	The UCT satellite to analyze	required
all_collections	list[ObservationCollection]	All observation collections for visibility checks	required
orphan_collections	list[ObservationCollection]	Observation collections of orphan observations	required

Returns:

Type	Description
UCTValidityReport	UCT validity report with analysis results

Raises:

Type	Description
ValueError	If the UCT satellite has no valid orbit state

Observatory

Parameters:

Name	Type	Description	Default
latitude	float	Latitude in degrees	required
longitude	float	Longitude in degrees	required
altitude	float	Altitude in kilometers	required

id instance-attribute

Unique identifier for the observatory.

sensors instance-attribute

List of sensors at the observatory

from_cartesian_state(state) classmethod

Create an observatory from a Cartesian state.

Parameters:

Name	Type	Description	Default
state	CartesianState	Cartesian state of the observatory	required

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

Calculate satellites in the field of view from a given time and direction.

Parameters:

Name	Type	Description	Default
epoch	Epoch	UTC epoch of the report	required
sensor_direction	TopocentricElements	Topocentric direction the sensor is pointing	required
angular_threshold	float	Angular threshold in degrees	required
sats	Constellation	Constellation of satellites to check for being in the field of view	required
reference_frame	ReferenceFrame	Reference frame of the output direction elements	required

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

Calculate horizon access for a satellite from the observatory.

Parameters:

Name	Type	Description	Default
satellite	Satellite	Satellite to check for horizon access	required
start	Epoch	UTC epoch of the start of the report	required
end	Epoch	UTC epoch of the end of the report	required
min_el	float	Minimum elevation angle in degrees	required
min_duration	TimeSpan	Minimum duration of access in seconds	required

Returns:

Type	Description
HorizonAccessReport	Horizon access report for the satellite from the observatory

get_state_at_epoch(epoch)

Parameters:

Name	Type	Description	Default
epoch	Epoch	UTC epoch of the state	required

Returns:

Type	Description
CartesianState	TEME Cartesian state of the observatory in kilometers and kilometers per second

get_theta(epoch)

Calculate the Greenwich angle plus the observatory longitude at a given epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	UTC epoch for the calculation	required

Returns:

Type	Description
float	Greenwich angle plus the observatory longitude in radians

get_topocentric_to_satellite(epoch, sat, reference_frame)

Get the topocentric elements of a satellite as seen from the observatory. Args: epoch: UTC epoch of the observation sat: Satellite to observe reference_frame: Reference frame of the output direction elements

Satellite

force_properties instance-attribute

Force properties of the satellite used for propagation

geodetic_position instance-attribute

Geodetic position of the satellite at the epoch of the TLE, if available

id instance-attribute

Unique identifier for the satellite.

keplerian_state instance-attribute

Keplerian state of the satellite at the epoch of the TLE, if available

name instance-attribute

Human-readable name of the satellite

norad_id instance-attribute

Number corresponding to the satellite's NORAD catalog ID.

from_tle(tle) classmethod

Instantiate a Satellite from a legacy TLE

Parameters:

Name	Type	Description	Default
tle	TLE	Two-line element set for the satellite	required

get_associations(collections)

Find observation associations for this satellite across multiple observation collections.

Parameters:

Name	Type	Description	Default
collections	list[ObservationCollection]	List of observation collections to search for associations	required

Returns:

Type	Description
list[ObservationAssociation]	List of observation associations where this satellite matches observations

get_body_angles_at_epoch(other, epoch)

Calculate the bore-to-body angles between this satellite and another satellite at a given epoch.

Parameters:

Name	Type	Description	Default
other	Satellite	Secondary satellite to calculate the bore-to-body angles against	required
epoch	Epoch	UTC epoch at which the bore-to-body angles will be calculated	required

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

Detect a maneuver by comparing this satellite's state with a future state.

Parameters:

Name	Type	Description	Default
future_sat	Satellite	Satellite with a future epoch state to compare against	required
start	Epoch	UTC epoch of the start of the search window	required
end	Epoch	UTC epoch of the end of the search window	required
distance_threshold	float	Distance threshold for matching in kilometers	required
velocity_threshold	float	Velocity threshold for maneuver detection in meters per second	required

Returns:

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

get_observatory_access_report(observatories, start, end, min_el, min_duration)

Calculate horizon access from multiple observatories to this satellite.

Parameters:

Name	Type	Description	Default
observatories	list[Observatory]	List of observatories to check for horizon access	required
start	Epoch	UTC epoch of the start of the report	required
end	Epoch	UTC epoch of the end of the report	required
min_el	float	Minimum elevation angle in degrees	required
min_duration	TimeSpan	Minimum duration of access	required

Returns:

Type	Description
Optional[HorizonAccessReport]	Horizon access report containing accesses from all observatories to the satellite,
Optional[HorizonAccessReport]	or None if the satellite ephemeris cannot be generated

get_proximity_report(other, start, end, distance_threshold)

Check if this satellite stays within a distance threshold of another satellite.

Parameters:

Name	Type	Description	Default
other	Satellite	Satellite to compare against	required
start	Epoch	UTC epoch of the start of the report	required
end	Epoch	UTC epoch of the end of the report	required
distance_threshold	float	Maximum distance threshold in kilometers	required

Returns:

Type	Description
Optional[ProximityReport]	Proximity report with a single event if satellites stay within threshold,
Optional[ProximityReport]	or an empty report if the threshold is exceeded at any point

get_relative_state_at_epoch(other, epoch)

Calculate the relative state between this satellite and another satellite at a given epoch.

Parameters:

Name	Type	Description	Default
other	Satellite	Secondary satellite to calculate the relative state against	required
epoch	Epoch	UTC epoch at which the relative state will be calculated	required

get_residuals(obs)

Calculate position residuals between observations and the satellite state.

Uses interpolated states from cached ephemeris when available for better performance.

Parameters:

Name	Type	Description	Default
obs	list[Observation]	List of observations to compare against	required

Returns:

Type	Description
list[ObservationResidual]	List of observation residuals

Raises:

Type	Description
ValueError	If no valid residuals could be computed

get_rms(obs)

Calculate the root mean squared position error between observations and the satellite state.

Uses interpolated states from cached ephemeris when available for better performance.

Parameters:

Name	Type	Description	Default
obs	list[Observation]	List of observations to compare against	required

Returns:

Type	Description
float	Root mean squared position error in kilometers

Raises:

Type	Description
ValueError	If no valid residuals could be computed

to_tle()

Returns:

Type	Description
Optional[TLE]	Satellite as a two-line element set or None if no state is loaded

Sensor

Parameters:

Name	Type	Description	Default
name		Identifier of the sensor	required
angular_noise	float	Angular noise in degrees	required

angular_rate_noise instance-attribute

Angular rate noise in degrees per second

id instance-attribute

Unique identifier for the sensor.

range_noise instance-attribute

Range noise in kilometers

range_rate_noise instance-attribute

Range rate noise in kilometers per second