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 (Pc) computation.

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

Probability of Collision (Pc) via Chan’s Analytical Approximation.

Provides a fast, series-based solution to the 2D Gaussian integral over a circular region. Most accurate when the HBR is small compared to the standard deviation of the covariance.

Parameters:

  • r1 (np.ndarray) – ECI Position vectors at TCA (m).

  • r2 (np.ndarray) – ECI Position vectors at TCA (m).

  • v1 (np.ndarray) – ECI Velocity vectors at TCA (m/s).

  • v2 (np.ndarray) – ECI Velocity vectors at TCA (m/s).

  • cov1 (np.ndarray) – $3times 3$ error covariance matrices ($m^2$).

  • cov2 (np.ndarray) – $3times 3$ error covariance matrices ($m^2$).

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

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 (Pc) via Foster’s method.

Projects the encounter into a 2D plane and integrates the PDF: $P_c = iint_{HBR} frac{1}{2pi sqrt{|\mathbf{C}|}} expleft(-frac{1}{2} mathbf{x}^T mathbf{C}^{-1} mathbf{x}right) dA$

Parameters:

  • r1 (np.ndarray) – ECI state of Object 1 at TCA (m, m/s).

  • v1 (np.ndarray) – ECI state of Object 1 at TCA (m, m/s).

  • cov1 (np.ndarray) – $3 times 3$ covariance of Object 1 ($m^2$).

  • r2 (np.ndarray) – ECI state of Object 2 at TCA (m, m/s).

  • v2 (np.ndarray) – ECI state of Object 2 at TCA (m, m/s).

  • cov2 (np.ndarray) – $3 times 3$ covariance of Object 2 ($m^2$).

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

Returns:

Probability of collision $P_c in [0, 1]$.

Return type:

float

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

Find Time of Closest Approach (TCA) between two objects.

Parameters:

  • r1_func (callable) – Functions that return ECI position at time t.

  • r2_func (callable) – Functions that return ECI position at time t.

  • t_start (float) – Search window (s).

  • t_end (float) – Search window (s).

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 3x3 position covariance using Keplerian motion.

Parameters:

  • cov0 (np.ndarray) – Initial 3x3 position covariance (m^2).

  • r (np.ndarray) – Initial ECI state (m, m/s).

  • v (np.ndarray) – Initial ECI state (m, m/s).

  • dt (float) – Time step (s).

Returns:

Propagated 3x3 position covariance.

Return type:

np.ndarray

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]

Probability of Collision (Pc) via Chan’s Analytical Approximation.

Provides a fast, series-based solution to the 2D Gaussian integral over a circular region. Most accurate when the HBR is small compared to the standard deviation of the covariance.

Parameters:

  • r1 (np.ndarray) – ECI Position vectors at TCA (m).

  • r2 (np.ndarray) – ECI Position vectors at TCA (m).

  • v1 (np.ndarray) – ECI Velocity vectors at TCA (m/s).

  • v2 (np.ndarray) – ECI Velocity vectors at TCA (m/s).

  • cov1 (np.ndarray) – $3times 3$ error covariance matrices ($m^2$).

  • cov2 (np.ndarray) – $3times 3$ error covariance matrices ($m^2$).

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

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 (Pc) via Foster’s method.

Projects the encounter into a 2D plane and integrates the PDF: $P_c = iint_{HBR} frac{1}{2pi sqrt{|\mathbf{C}|}} expleft(-frac{1}{2} mathbf{x}^T mathbf{C}^{-1} mathbf{x}right) dA$

Parameters:

  • r1 (np.ndarray) – ECI state of Object 1 at TCA (m, m/s).

  • v1 (np.ndarray) – ECI state of Object 1 at TCA (m, m/s).

  • cov1 (np.ndarray) – $3 times 3$ covariance of Object 1 ($m^2$).

  • r2 (np.ndarray) – ECI state of Object 2 at TCA (m, m/s).

  • v2 (np.ndarray) – ECI state of Object 2 at TCA (m, m/s).

  • cov2 (np.ndarray) – $3 times 3$ covariance of Object 2 ($m^2$).

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

Returns:

Probability of collision $P_c 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]