opengnc.ssa package

Submodules

opengnc.ssa.collision_avoidance module

Collision Avoidance Maneuver (CAM) Planning.

opengnc.ssa.collision_avoidance.plan_collision_avoidance_maneuver(r_sat_tca: ndarray, v_sat_tca: ndarray, cov_sat_tca: ndarray, r_deb_tca: ndarray, v_deb_tca: ndarray, cov_deb_tca: ndarray, hbr: float, t_man_before_tca: float, pc_limit: float = 0.0001) → tuple[ndarray, float][source]

Plan an impulsive Collision Avoidance Maneuver (CAM).

Finds the minimum Delta-V magnitude to reduce Probability of Collision (Pc) below the specified limit.

Assumes Keplerian motion for sensitivity matrix (State Transition Matrix).

Parameters:

  • r_sat_tca (np.ndarray) – ECI state of the satellite at predicted TCA (m, m/s).

  • v_sat_tca (np.ndarray) – ECI state of the satellite at predicted TCA (m, m/s).

  • cov_sat_tca (np.ndarray) – Covariance of the satellite at TCA (3x3).

  • r_deb_tca (np.ndarray) – ECI state of the debris at predicted TCA (m, m/s).

  • v_deb_tca (np.ndarray) – ECI state of the debris at predicted TCA (m, m/s).

  • cov_deb_tca (np.ndarray) – Covariance of the debris at TCA (3x3).

  • hbr (float) – Hard Body Radius (m).

  • t_man_before_tca (float) – Time before TCA to perform the maneuver (s).

  • pc_limit (float) – Maximum allowable Probability of Collision.

Returns:

  • Delta-V vector in ECI (m/s).

  • Probability of Collision after maneuver.

Return type:

Tuple[np.ndarray, float]

opengnc.ssa.conjunction module

Conjunction analysis and probability of collision utilities.

opengnc.ssa.conjunction.compute_pc_chan(r1: ndarray, v1: ndarray, cov1: ndarray, r2: ndarray, v2: ndarray, cov2: ndarray, hbr: float) → float[source]

Compute probability of collision via Chan’s analytical approximation.

Parameters:

  • r1 (np.ndarray) – ECI position vectors at TCA in meters.

  • r2 (np.ndarray) – ECI position vectors at TCA in meters.

  • v1 (np.ndarray) – ECI velocity vectors at TCA in meters per second.

  • v2 (np.ndarray) – ECI velocity vectors at TCA in meters per second.

  • cov1 (np.ndarray) – 3 x 3 covariance matrices in square meters.

  • cov2 (np.ndarray) – 3 x 3 covariance matrices in square meters.

  • hbr (float) – Combined hard-body radius in meters.

Returns:

Computed probability of collision.

Return type:

float

opengnc.ssa.conjunction.compute_pc_foster(r1: ndarray, v1: ndarray, cov1: ndarray, r2: ndarray, v2: ndarray, cov2: ndarray, hbr: float) → float[source]

Compute probability of collision via Foster’s method.

The encounter is projected into a 2D collision plane and the Gaussian probability density is integrated over the circular hard-body region.

Parameters:

  • r1 (np.ndarray) – ECI state of object 1 at TCA in meters and meters per second.

  • v1 (np.ndarray) – ECI state of object 1 at TCA in meters and meters per second.

  • cov1 (np.ndarray) – 3 x 3 covariance of object 1 in square meters.

  • r2 (np.ndarray) – ECI state of object 2 at TCA in meters and meters per second.

  • v2 (np.ndarray) – ECI state of object 2 at TCA in meters and meters per second.

  • cov2 (np.ndarray) – 3 x 3 covariance of object 2 in square meters.

  • hbr (float) – Combined hard-body radius in meters.

Returns:

Probability of collision in [0, 1].

Return type:

float

opengnc.ssa.conjunction.find_tca(r1_func: Callable[[float], ndarray], r2_func: Callable[[float], ndarray], t_start: float, t_end: float, tol: float = 0.1) → float[source]

Find the time of closest approach between two objects.

Parameters:

  • r1_func (Callable[[float], np.ndarray]) – Functions returning ECI position at time t.

  • r2_func (Callable[[float], np.ndarray]) – Functions returning ECI position at time t.

  • t_start (float) – Search window in seconds.

  • t_end (float) – Search window in seconds.

  • tol (float, optional) – Scalar search tolerance in seconds.

Returns:

Time of closest approach.

Return type:

float

opengnc.ssa.conjunction.propagate_covariance(cov0: ndarray, r: ndarray, v: ndarray, dt: float) → ndarray[source]

Linearly propagate a 3 x 3 position covariance using a simple growth model.

opengnc.ssa.maneuver module

Debris Avoidance Maneuver Planning.

opengnc.ssa.maneuver.plan_avoidance_maneuver(r_sat: ndarray, v_sat: ndarray, r_debris: ndarray, v_debris: ndarray, safety_radius: float, t_encounter: float) → tuple[ndarray, float][source]

Plan an impulsive Debris Avoidance Maneuver (DAM).

Primarily calculates an along-track thrust to achieve a target miss distance at encounter via phasing.

Parameters:

  • r_sat (np.ndarray) – Spacecraft ECI state at planning epoch (m, m/s).

  • v_sat (np.ndarray) – Spacecraft ECI state at planning epoch (m, m/s).

  • r_debris (np.ndarray) – Debris ECI state at planning epoch (m, m/s).

  • v_debris (np.ndarray) – Debris ECI state at planning epoch (m, m/s).

  • safety_radius (float) – Desired minimum separation distance (m).

  • t_encounter (float) – Time until predicted conjunction (s).

Returns:

  • Delta-V vector in ECI (m/s).

  • Estimated miss distance after maneuver (m).

Return type:

Tuple[np.ndarray, float]

opengnc.ssa.tle_interface module

TLE Catalog Interface and Utilities.

class opengnc.ssa.tle_interface.TLECatalog[source]

Bases: object

Catalog for managing and searching a collection of satellite TLEs.

add_tle(name: str, line1: str, line2: str) → None[source]

Register a new TLE in the catalog.

Parameters:

  • name (str) – Satellite name.

  • line1 (str) – TLE data.

  • line2 (str) – TLE data.

get_by_name(name: str) → TLEEntity | None[source]

Lookup satellite by name (case-insensitive).

get_by_norad_id(norad_id: str | int) → TLEEntity | None[source]

Lookup satellite by catalog ID.

list_satellites() → list[str][source]

List names of all registered satellites.

load_from_txt(filepath: str) → None[source]

Load TLE data from a standard text file.

Supports both 2-line and 3-line (with name) TLE formats.

Parameters:

filepath (str) – Path to the TLE file.

class opengnc.ssa.tle_interface.TLEEntity(name: str, line1: str, line2: str)[source]

Bases: object

Representation of a Two-Line Element (TLE) set for a satellite.

Parameters:

  • name (str) – Common name of the satellite.

  • line1 (str) – First line of the TLE.

  • line2 (str) – Second line of the TLE.

get_propagator() → Sgp4Propagator[source]

Create a propagator instance for this TLE.

Returns:

SGP4 propagator initialized with TLE lines.

Return type:

Sgp4Propagator

opengnc.ssa.tracking module

Object Tracking and Orbit Correlation Utilities.

opengnc.ssa.tracking.compute_mahalanobis_distance(x1: ndarray, x2: ndarray, cov1: ndarray, cov2: ndarray) → float[source]

Compute the Mahalanobis statistical distance between two state estimates.

Used to measure the separation between two Gaussian distributions accounting for their covariance. Formula: $d_M = sqrt{(mathbf{x}_1 - mathbf{x}_2)^T (mathbf{P}_1 + mathbf{P}_2)^{-1} (mathbf{x}_1 - mathbf{x}_2)}$.

Parameters:

  • x1 (np.ndarray) – State vectors (e.g., Position/Velocity) (6,).

  • x2 (np.ndarray) – State vectors (e.g., Position/Velocity) (6,).

  • cov1 (np.ndarray) – Estimation error covariance matrices (6, 6).

  • cov2 (np.ndarray) – Estimation error covariance matrices (6, 6).

Returns:

Mahalanobis distance.

Return type:

float

opengnc.ssa.tracking.correlate_tracks(x1: ndarray, x2: ndarray, cov1: ndarray, cov2: ndarray, threshold: float = 3.0) → bool[source]

Correlate two tracks based on a Mahalanobis distance threshold.

Used for track-to-track association in SSA catalogs.

Parameters:

  • x1 (np.ndarray) – State vectors to compare.

  • x2 (np.ndarray) – State vectors to compare.

  • cov1 (np.ndarray) – State covariances.

  • cov2 (np.ndarray) – State covariances.

  • threshold (float, optional) – Correlation limit (n-sigma). Default is 3.0 (3-sigma).

Returns:

True if the distance is within the specified threshold.

Return type:

bool

Module contents

Space Situational Awareness (SSA) Module.

class opengnc.ssa.TLECatalog[source]

Bases: object

Catalog for managing and searching a collection of satellite TLEs.

add_tle(name: str, line1: str, line2: str) → None[source]

Register a new TLE in the catalog.

Parameters:

  • name (str) – Satellite name.

  • line1 (str) – TLE data.

  • line2 (str) – TLE data.

get_by_name(name: str) → TLEEntity | None[source]

Lookup satellite by name (case-insensitive).

get_by_norad_id(norad_id: str | int) → TLEEntity | None[source]

Lookup satellite by catalog ID.

list_satellites() → list[str][source]

List names of all registered satellites.

load_from_txt(filepath: str) → None[source]

Load TLE data from a standard text file.

Supports both 2-line and 3-line (with name) TLE formats.

Parameters:

filepath (str) – Path to the TLE file.

class opengnc.ssa.TLEEntity(name: str, line1: str, line2: str)[source]

Bases: object

Representation of a Two-Line Element (TLE) set for a satellite.

Parameters:

  • name (str) – Common name of the satellite.

  • line1 (str) – First line of the TLE.

  • line2 (str) – Second line of the TLE.

get_propagator() → Sgp4Propagator[source]

Create a propagator instance for this TLE.

Returns:

SGP4 propagator initialized with TLE lines.

Return type:

Sgp4Propagator

opengnc.ssa.compute_mahalanobis_distance(x1: ndarray, x2: ndarray, cov1: ndarray, cov2: ndarray) → float[source]

Compute the Mahalanobis statistical distance between two state estimates.

Used to measure the separation between two Gaussian distributions accounting for their covariance. Formula: $d_M = sqrt{(mathbf{x}_1 - mathbf{x}_2)^T (mathbf{P}_1 + mathbf{P}_2)^{-1} (mathbf{x}_1 - mathbf{x}_2)}$.

Parameters:

  • x1 (np.ndarray) – State vectors (e.g., Position/Velocity) (6,).

  • x2 (np.ndarray) – State vectors (e.g., Position/Velocity) (6,).

  • cov1 (np.ndarray) – Estimation error covariance matrices (6, 6).

  • cov2 (np.ndarray) – Estimation error covariance matrices (6, 6).

Returns:

Mahalanobis distance.

Return type:

float

opengnc.ssa.compute_pc_chan(r1: ndarray, v1: ndarray, cov1: ndarray, r2: ndarray, v2: ndarray, cov2: ndarray, hbr: float) → float[source]

Compute probability of collision via Chan’s analytical approximation.

Parameters:

  • r1 (np.ndarray) – ECI position vectors at TCA in meters.

  • r2 (np.ndarray) – ECI position vectors at TCA in meters.

  • v1 (np.ndarray) – ECI velocity vectors at TCA in meters per second.

  • v2 (np.ndarray) – ECI velocity vectors at TCA in meters per second.

  • cov1 (np.ndarray) – 3 x 3 covariance matrices in square meters.

  • cov2 (np.ndarray) – 3 x 3 covariance matrices in square meters.

  • hbr (float) – Combined hard-body radius in meters.

Returns:

Computed probability of collision.

Return type:

float

opengnc.ssa.compute_pc_foster(r1: ndarray, v1: ndarray, cov1: ndarray, r2: ndarray, v2: ndarray, cov2: ndarray, hbr: float) → float[source]

Compute probability of collision via Foster’s method.

The encounter is projected into a 2D collision plane and the Gaussian probability density is integrated over the circular hard-body region.

Parameters:

  • r1 (np.ndarray) – ECI state of object 1 at TCA in meters and meters per second.

  • v1 (np.ndarray) – ECI state of object 1 at TCA in meters and meters per second.

  • cov1 (np.ndarray) – 3 x 3 covariance of object 1 in square meters.

  • r2 (np.ndarray) – ECI state of object 2 at TCA in meters and meters per second.

  • v2 (np.ndarray) – ECI state of object 2 at TCA in meters and meters per second.

  • cov2 (np.ndarray) – 3 x 3 covariance of object 2 in square meters.

  • hbr (float) – Combined hard-body radius in meters.

Returns:

Probability of collision in [0, 1].

Return type:

float

opengnc.ssa.correlate_tracks(x1: ndarray, x2: ndarray, cov1: ndarray, cov2: ndarray, threshold: float = 3.0) → bool[source]

Correlate two tracks based on a Mahalanobis distance threshold.

Used for track-to-track association in SSA catalogs.

Parameters:

  • x1 (np.ndarray) – State vectors to compare.

  • x2 (np.ndarray) – State vectors to compare.

  • cov1 (np.ndarray) – State covariances.

  • cov2 (np.ndarray) – State covariances.

  • threshold (float, optional) – Correlation limit (n-sigma). Default is 3.0 (3-sigma).

Returns:

True if the distance is within the specified threshold.

Return type:

bool

opengnc.ssa.plan_avoidance_maneuver(r_sat: ndarray, v_sat: ndarray, r_debris: ndarray, v_debris: ndarray, safety_radius: float, t_encounter: float) → tuple[ndarray, float][source]

Plan an impulsive Debris Avoidance Maneuver (DAM).

Primarily calculates an along-track thrust to achieve a target miss distance at encounter via phasing.

Parameters:

  • r_sat (np.ndarray) – Spacecraft ECI state at planning epoch (m, m/s).

  • v_sat (np.ndarray) – Spacecraft ECI state at planning epoch (m, m/s).

  • r_debris (np.ndarray) – Debris ECI state at planning epoch (m, m/s).

  • v_debris (np.ndarray) – Debris ECI state at planning epoch (m, m/s).

  • safety_radius (float) – Desired minimum separation distance (m).

  • t_encounter (float) – Time until predicted conjunction (s).

Returns:

  • Delta-V vector in ECI (m/s).

  • Estimated miss distance after maneuver (m).

Return type:

Tuple[np.ndarray, float]