opengnc.utils package

Submodules

opengnc.utils.cayley_klein_utils module

Cayley-Klein parameters for attitude representation and composition.

opengnc.utils.cayley_klein_utils.cayley_klein_mult(u1: ndarray, u2: ndarray) → ndarray

Multiply two Cayley-Klein matrices (composes rotations).

Parameters:

• u1 (np.ndarray) – First 2x2 complex matrix.

• u2 (np.ndarray) – Second 2x2 complex matrix.

Returns:

Product 2x2 complex matrix.

Return type:

np.ndarray

opengnc.utils.cayley_klein_utils.cayley_klein_to_quat(u_mat: ndarray) → ndarray

Convert a 2x2 Cayley-Klein matrix to a quaternion.

Parameters:

u_mat (np.ndarray) – 2x2 complex Cayley-Klein matrix.

Returns:

Quaternion [x, y, z, w].

Return type:

np.ndarray

opengnc.utils.cayley_klein_utils.quat_to_cayley_klein(q: ndarray) → ndarray

Convert a quaternion to Cayley-Klein parameters.

The Cayley-Klein parameters $(alpha, beta)$ are complex numbers representing the rotation: $alpha = w + i z$ $beta = y + i x$

Parameters:

q (np.ndarray) – Quaternion [x, y, z, w].

Returns:

2x2 complex unitary matrix: [[alpha, beta],

[-beta*, alpha*]]

Return type:

np.ndarray

opengnc.utils.covariance module

Covariance transformation and reachability analysis tools.

class opengnc.utils.covariance.CovarianceTransform

Bases: object

Tools for transforming state covariances between various frames.

static eci_to_ric(r_eci: ndarray, v_eci: ndarray, P_eci: ndarray) → ndarray

Transform covariance from ECI to RIC (Radial, In-Track, Cross-Track).

Parameters:

• r_eci (np.ndarray) – Position (m).

• v_eci (np.ndarray) – Velocity (m/s).

• P_eci (np.ndarray) – $6 imes 6$ Covariance matrix in ECI.

Returns:

$6 imes 6$ Covariance matrix in RIC.

Return type:

np.ndarray

static ric_to_eci(r_eci: ndarray, v_eci: ndarray, P_ric: ndarray) → ndarray

Transform covariance from RIC back to ECI.

Parameters:

• r_eci (np.ndarray) – Position (m).

• v_eci (np.ndarray) – Velocity (m/s).

• P_ric (np.ndarray) – $6 imes 6$ Covariance matrix in RIC.

Returns:

$6 imes 6$ Covariance matrix in ECI.

Return type:

np.ndarray

class opengnc.utils.covariance.ReachabilityAnalysis(mu: float = 398600441800000.0)

Bases: object

Orbital maneuver reachability analysis.

get_reachable_delta_elements(a: float, e: float, i: float, dv_total: float) → dict[str, float]

Calculate maximum possible changes in orbital elements for a total delta-V.

Based on impulsive GVE approximations.

Parameters:

• a (float) – Current semi-major axis, eccentricity, inclination.

• e (float) – Current semi-major axis, eccentricity, inclination.

• i (float) – Current semi-major axis, eccentricity, inclination.

• dv_total (float) – Total $Delta V$ budget (m/s).

Returns:

Max theoretical $Delta a, Delta e, Delta i$.

Return type:

dict

opengnc.utils.crp_utils module

Classical Rodrigues Parameters (CRP) kinematics and composition.

opengnc.utils.crp_utils.crp_addition(q1: ndarray, q2: ndarray) → ndarray

Compose two rotations represented by Classical Rodrigues Parameters.

$mathbf{q}_{res} = frac{mathbf{q}_1 + mathbf{q}_2 + mathbf{q}_2 times mathbf{q}_1}{1 - mathbf{q}_1 cdot mathbf{q}_2}$

Parameters:

• q1 (np.ndarray) – Initial CRP vector.

• q2 (np.ndarray) – Secondary CRP vector.

Returns:

Resultant CRP vector.

Return type:

np.ndarray

Raises:

ValueError – If the denominator is near zero.

opengnc.utils.crp_utils.crp_to_dcm(q_crp: ndarray) → ndarray

Convert Classical Rodrigues Parameters to a Direction Cosine Matrix.

Parameters:

q_crp (np.ndarray) – CRP vector $[q_1, q_2, q_3]^T$.

Returns:

3x3 Direction Cosine Matrix.

Return type:

np.ndarray

opengnc.utils.crp_utils.crp_to_quat(q_crp: ndarray) → ndarray

Convert Classical Rodrigues Parameters to a quaternion.

Parameters:

q_crp (np.ndarray) – CRP vector $[q_1, q_2, q_3]^T$.

Returns:

Unit quaternion [x, y, z, w].

Return type:

np.ndarray

opengnc.utils.crp_utils.quat_to_crp(q: ndarray) → ndarray

Convert a quaternion to Classical Rodrigues Parameters (CRP/Gibbs).

Mathematical form: $mathbf{q}_{vec} / q_w$. Singular for 180-degree rotations ($q_w = 0$).

Parameters:

q (np.ndarray) – Quaternion [x, y, z, w].

Returns:

CRP vector $[q_1, q_2, q_3]^T$.

Return type:

np.ndarray

Raises:

ValueError – If the rotation is 180 degrees.

opengnc.utils.ephemeris module

JPL Ephemeris integration using jplephem.

class opengnc.utils.ephemeris.JPLEphemeris(spk_path: str | None = None)

Bases: object

Handler for JPL SPK (Space Property Kernel) files.

Provides high-precision position and velocity for planets, Sun, and Moon.

Parameters:

spk_path (str, optional) – Path to the .bsp SPK file (e.g., de421.bsp).

get_position(body_id: int, jd: float) → ndarray

Get body position in km (usually relative to solar system barycenter).

Parameters:

• body_id (int) – JPL Body ID (e.g., 399 for Earth, 301 for Moon, 10 for Sun).

• jd (float) – Julian Date.

Returns:

Position vector [x, y, z] in meters.

Return type:

np.ndarray

get_state(body_id: int, jd: float) → ndarray

Get body position and velocity.

Parameters:

• body_id (int) – JPL Body ID.

• jd (float) – Julian Date.

Returns:

State vector [x, y, z, vx, vy, vz] in m, m/s.

Return type:

np.ndarray

opengnc.utils.equinoctial_utils module

Equinoctial orbital element operations and conversions.

opengnc.utils.equinoctial_utils.equinoctial2eci(a: float, h: float, k: float, p: float, q: float, mean_lon: float, mu: float = 398600441500000.0) → tuple[ndarray, ndarray]

Direct conversion from Equinoctial elements to ECI state.

Parameters:

• a (float) – Equinoctial elements.

• h (float) – Equinoctial elements.

• k (float) – Equinoctial elements.

• p (float) – Equinoctial elements.

• q (float) – Equinoctial elements.

• mean_lon (float) – Equinoctial elements.

• mu (float, optional) – Gravitational parameter ($m^3/s^2$).

Returns:

(Position vector (m), Velocity vector (m/s)).

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.utils.equinoctial_utils.equinoctial2kepler(a: float, h: float, k: float, p: float, q: float, mean_lon: float) → tuple[float, float, float, float, float, float, float]

Convert Equinoctial elements back to Keplerian elements.

Parameters:

• a (float) – Equinoctial elements.

• h (float) – Equinoctial elements.

• k (float) – Equinoctial elements.

• p (float) – Equinoctial elements.

• q (float) – Equinoctial elements.

• mean_lon (float) – Equinoctial elements.

Returns:

Keplerian (a, ecc, incl, raan, argp, nu, M).

Return type:

tuple[float, float, float, float, float, float, float]

opengnc.utils.equinoctial_utils.kepler2equinoctial(a: float, ecc: float, incl: float, raan: float, argp: float, m_anom: float) → tuple[float, float, float, float, float, float]

Convert Keplerian elements to Classical Equinoctial elements.

Equinoctial elements $(a, h, k, p, q, lambda_M)$ are non-singular for zero eccentricity and zero/90-deg inclination.

Parameters:

• a (float) – Semi-major axis (m).

• ecc (float) – Eccentricity.

• incl (float) – Inclination (rad).

• raan (float) – RAAN (rad).

• argp (float) – Argument of Perigee (rad).

• m_anom (float) – Mean Anomaly (rad).

Returns:

Equinoctial elements (a, h, k, p, q, mean_lon).

Return type:

tuple[float, float, float, float, float, float]

opengnc.utils.equinoctial_utils.solve_kepler_equinoctial(mean_lon: float, h: float, k: float) → float

Iteratively solve the Equinoctial Kepler Equation for $F$.

$lambda_M = F + h cos F - k sin F$

Parameters:

• mean_lon (float) – Mean longitude (rad).

• h (float) – Equinoctial elements.

• k (float) – Equinoctial elements.

Returns:

Eccentric longitude F (rad).

Return type:

float

opengnc.utils.euler_utils module

Euler angle kinematics and Direction Cosine Matrix (DCM) utilities.

opengnc.utils.euler_utils.dcm_to_euler(dcm: ndarray, sequence: str) → ndarray

Extract Euler angles from a 3x3 Direction Cosine Matrix.

Supports all 12 standard rotation sequences (Symmetric and Asymmetric). Handles gimbal lock singularities by setting the first angle to zero.

Parameters:

• dcm (np.ndarray) – 3x3 Direction Cosine Matrix.

• sequence (str) – Sequence of rotations (e.g., ‘321’, ‘313’).

Returns:

Euler angles $[theta_1, theta_2, theta_3]$ in radians.

Return type:

np.ndarray

opengnc.utils.euler_utils.euler_to_dcm(angles: ndarray, sequence: str) → ndarray

Convert Euler angles to a 3x3 Direction Cosine Matrix (DCM).

Standard convention for satellite dynamics is the Body-to-Inertial rotation $R_{I/B} = R_3(theta_3) R_2(theta_2) R_1(theta_1)$.

Parameters:

• angles (np.ndarray) – Three Euler angles in radians $[theta_1, theta_2, theta_3]$.

• sequence (str) – Rotation sequence (e.g., ‘321’, ‘313’). Must be 3 characters.

Returns:

3x3 Direction Cosine Matrix.

Return type:

np.ndarray

Raises:

ValueError – If the sequence is invalid or length is not 3.

opengnc.utils.euler_utils.rot_x(angle: float) → ndarray

Elementary rotation matrix about the X-axis.

Parameters:

angle (float) – Rotation angle (radians).

Returns:

3x3 rotation matrix.

Return type:

np.ndarray

opengnc.utils.euler_utils.rot_y(angle: float) → ndarray

Elementary rotation matrix about the Y-axis.

Parameters:

angle (float) – Rotation angle (radians).

Returns:

3x3 rotation matrix.

Return type:

np.ndarray

opengnc.utils.euler_utils.rot_z(angle: float) → ndarray

Elementary rotation matrix about the Z-axis.

Parameters:

angle (float) – Rotation angle (radians).

Returns:

3x3 rotation matrix.

Return type:

np.ndarray

opengnc.utils.frame_conversion module

Frame conversion utilities (ECI, ECEF, LVLH, LLH).

opengnc.utils.frame_conversion.ecef2eci(r_ecef: ndarray, v_ecef: ndarray, jd_ut1: float, dut1: float = 0.0) → tuple[ndarray, ndarray]

Convert ECEF position and velocity to ECI frame.

Parameters:

• r_ecef (np.ndarray) – ECEF position vector (m).

• v_ecef (np.ndarray) – ECEF velocity vector (m/s).

• jd_ut1 (float) – Julian Date (UT1).

• dut1 (float, optional) – UT1-UTC difference (seconds). Default 0.0.

Returns:

(ECI position vector (m), ECI velocity vector (m/s)).

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.utils.frame_conversion.eci2ecef(r_eci: ndarray, v_eci: ndarray, jd_ut1: float, dut1: float = 0.0) → tuple[ndarray, ndarray]

Convert ECI to ECEF.

Rotation: $mathbf{r}_{ecef} = mathbf{R}_z(theta_{gmst}) mathbf{r}_{eci}$ $mathbf{v}_{ecef} = mathbf{R}_z(theta_{gmst}) (mathbf{v}_{eci} - mathbf{omega}_e times mathbf{r}_{eci})$

Parameters:

• r_eci (np.ndarray) – ECI Position (m).

• v_eci (np.ndarray) – ECI Velocity (m/s).

• jd_ut1 (float) – Julian Date.

• dut1 (float, optional) – UT1-UTC (s).

Returns:

(ECEF position vector (m), ECEF velocity vector (m/s)).

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.utils.frame_conversion.eci2eme2000(reci: ndarray, veci: ndarray) → tuple[ndarray, ndarray]

Converts ECI (J2000) to EME2000.

In many contexts these are treated as identical. This function treats ECI as Earth-Centered Inertial at epoch of date, and EME2000 as fixed at J2000.

Parameters:

• reci (np.ndarray) – ECI position vector (m).

• veci (np.ndarray) – ECI velocity vector (m/s).

Returns:

(EME2000 position vector (m), EME2000 velocity vector (m/s)).

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.utils.frame_conversion.eci2geodetic(r_eci: ndarray, jd: float) → tuple[float, float, float]

Converts ECI position to Geodetic coordinates.

Parameters:

• r_eci (np.ndarray) – ECI position vector (m).

• jd (float) – Julian Date.

Returns:

(Longitude (deg), Latitude (deg), Altitude (m)).

Return type:

tuple[float, float, float]

opengnc.utils.frame_conversion.eci2icrf(reci: ndarray, veci: ndarray, jd: float) → tuple[ndarray, ndarray]

Converts ECI (J2000) to ICRF.

Includes simplified Precession and Nutation.

Parameters:

• reci (np.ndarray) – ECI position vector (m).

• veci (np.ndarray) – ECI velocity vector (m/s).

• jd (float) – Julian Date.

Returns:

(ICRF position vector (m), ICRF velocity vector (m/s)).

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.utils.frame_conversion.eci2llh(r_eci: ndarray, jd_ut1: float) → tuple[float, float, float]

Convert ECI position to Geodetic LLH (Latitude, Longitude, Height).

Parameters:

• r_eci (np.ndarray) – ECI position vector (m).

• jd_ut1 (float) – Julian Date (UT1).

Returns:

(Latitude (rad), Longitude (rad), Altitude (m)).

Return type:

tuple[float, float, float]

opengnc.utils.frame_conversion.eci2lvlh_dcm(r_eci: ndarray, v_eci: ndarray) → ndarray

Calculate the DCM from ECI to LVLH (Local Vertical Local Horizontal).

LVLH Frame (Nadir-Pointed): - Z: Nadir (opposite to position vector) - Y: Negative Orbit Normal - X: Completes the right-handed system (approx velocity direction)

Parameters:

• r_eci (np.ndarray) – ECI position vector (m).

• v_eci (np.ndarray) – ECI velocity vector (m/s).

Returns:

3x3 Direction Cosine Matrix $C_{LVLH/ECI}$.

Return type:

np.ndarray

opengnc.utils.frame_conversion.elements2perifocal_dcm(raan: float, inc: float, arg_p: float) → ndarray

Calculates the DCM from perifocal (PQW) to ECI.

Parameters:

• raan (float) – Right Ascension of the Ascending Node (rad).

• inc (float) – Inclination (rad).

• arg_p (float) – Argument of Perigee (rad).

Returns:

3x3 Direction Cosine Matrix (PQW to ECI).

Return type:

np.ndarray

opengnc.utils.frame_conversion.eme20002eci(reci: ndarray, veci: ndarray) → tuple[ndarray, ndarray]

Converts EME2000 to ECI (J2000).

Parameters:

• reci (np.ndarray) – EME2000 position vector (m).

• veci (np.ndarray) – EME2000 velocity vector (m/s).

Returns:

(ECI position vector (m), ECI velocity vector (m/s)).

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.utils.frame_conversion.icrf2eci(reci: ndarray, veci: ndarray, jd: float) → tuple[ndarray, ndarray]

Converts ICRF to ECI (J2000).

Parameters:

• reci (np.ndarray) – ICRF position vector (m).

• veci (np.ndarray) – ICRF velocity vector (m/s).

• jd (float) – Julian Date.

Returns:

(ECI position vector (m), ECI velocity vector (m/s)).

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.utils.frame_conversion.llh2ecef(lat_rad: float, lon_rad: float, alt_m: float) → ndarray

Converts Geodetic coordinates (LLH) to ECEF.

Parameters:

• lat_rad (float) – Latitude in radians.

• lon_rad (float) – Longitude in radians.

• alt_m (float) – Altitude in meters above ellipsoid.

Returns:

Position in ECEF [m].

Return type:

np.ndarray

opengnc.utils.frame_conversion.rot_y_local(angle: float) → ndarray

Rotation matrix for rotation about y-axis.

Parameters:

angle (float) – Rotation angle in radians.

Returns:

3x3 rotation matrix.

Return type:

np.ndarray

opengnc.utils.mean_elements module

Mean element conversions and secular perturbation rates (e.g., J2 secular theory).

opengnc.utils.mean_elements.get_j2_secular_rates(a: float, ecc: float, incl: float, j2: float = 0.00108262668, re: float = 6378137.0, mu: float = 398600441500000.0) → tuple[float, float, float]

Calculate high-precision secular rates due to J2 oblateness.

Computes $dot{Omega}$, $dot{omega}$, and the mean motion correction $dot{M}$.

Parameters:

• a (float) – Semi-major axis (m).

• ecc (float) – Eccentricity.

• incl (float) – Inclination (rad).

• j2 (float, optional) – J2 perturbation coefficient.

• re (float, optional) – Equatorial radius (m).

• mu (float, optional) – Gravitational parameter ($m^3/s^2$).

Returns:

(raan_dot, argp_dot, m_dot) in rad/s.

Return type:

tuple[float, float, float]

opengnc.utils.mean_elements.osculating2mean(a: float, ecc: float, incl: float, raan: float, argp: float, m_anom: float, j2: float = 0.00108262668, re: float = 6378137.0) → tuple[float, float, float, float, float, float]

Convert osculating Keplerian elements to mean elements using J2 secular theory.

This implements the secular mapping (ignoring short/long period terms). Mean elements are essential for long-term orbit propagation and mission planning.

Parameters:

• a (float) – Osculating semi-major axis (m).

• ecc (float) – Osculating eccentricity.

• incl (float) – Osculating inclination (rad).

• raan (float) – Osculating RAAN (rad).

• argp (float) – Osculating Argument of Perigee (rad).

• m_anom (float) – Osculating Mean Anomaly (rad).

• j2 (float, optional) – J2 perturbation coefficient. Default is Earth.

• re (float, optional) – Planet Equatorial Radius (m). Default is Earth.

Returns:

Mean elements (a_m, e_m, i_m, raan_m, argp_m, M_m).

Return type:

tuple[float, float, float, float, float, float]

opengnc.utils.mee_utils module

Modified Equinoctial Elements (MEE) kinematics and conversions.

opengnc.utils.mee_utils.eci2mee(r_eci: ndarray, v_eci: ndarray, mu: float = 398600441500000.0) → tuple[float, float, float, float, float, float]

Convert ECI Cartesian state to Modified Equinoctial Elements.

Parameters:

• r_eci (np.ndarray) – Position vector (m).

• v_eci (np.ndarray) – Velocity vector (m/s).

• mu (float, optional) – Gravitational parameter ($m^3/s^2$). Default is Earth.

Returns:

MEE elements (p, f, g, h, k, L).

Return type:

tuple[float, float, float, float, float, float]

opengnc.utils.mee_utils.kepler2mee(a: float, ecc: float, incl: float, raan: float, argp: float, nu: float, mu: float = 398600441500000.0) → tuple[float, float, float, float, float, float]

Convert Keplerian elements to Modified Equinoctial Elements (MEE).

MEE are non-singular for circular and equatorial orbits. State vector: $[p, f, g, h, k, L]^T$.

Parameters:

• a (float) – Semi-major axis (m).

• ecc (float) – Eccentricity.

• incl (float) – Inclination (rad).

• raan (float) – RAAN (rad).

• argp (float) – Argument of Perigee (rad).

• nu (float) – True Anomaly (rad).

• mu (float, optional) – Gravitational parameter ($m^3/s^2$). Default is Earth.

Returns:

MEE elements (p, f, g, h, k, L).

Return type:

tuple[float, float, float, float, float, float]

opengnc.utils.mee_utils.mee2eci(p: float, f: float, g: float, h: float, k: float, l_true: float, mu: float = 398600441500000.0) → tuple[ndarray, ndarray]

Convert Modified Equinoctial Elements to ECI Cartesian state.

Parameters:

• p (float) – Modified Equinoctial Elements.

• f (float) – Modified Equinoctial Elements.

• g (float) – Modified Equinoctial Elements.

• h (float) – Modified Equinoctial Elements.

• k (float) – Modified Equinoctial Elements.

• l_true (float) – Modified Equinoctial Elements.

• mu (float, optional) – Gravitational parameter ($m^3/s^2$). Default is Earth.

Returns:

(Position vector (m), Velocity vector (m/s)).

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.utils.mrp_utils module

Modified Rodrigues Parameters (MRP) kinematics and math utilities.

opengnc.utils.mrp_utils.check_mrp_switching(sigma: ndarray, threshold: float = 1.0) → ndarray

Ensure the MRP magnitude remains below a threshold by switching to the shadow set.

Typically used to maintain the MRP within the unit sphere ($threshold=1.0$).

Parameters:

• sigma (np.ndarray) – Current MRP vector.

• threshold (float, optional) – Magnitude threshold for switching. Default is 1.0.

Returns:

Standard or shadow MRP vector.

Return type:

np.ndarray

opengnc.utils.mrp_utils.get_shadow_mrp(sigma: ndarray) → ndarray

Return the shadow set for the given MRP.

The shadow set represents the same rotation but stays within the unit sphere ($|sigma| le 1$). $sigma_{shadow} = -sigma / |sigma|^2$.

Parameters:

sigma (np.ndarray) – MRP vector $[sigma_1, sigma_2, sigma_3]^T$.

Returns:

Shadow MRP vector.

Return type:

np.ndarray

opengnc.utils.mrp_utils.mrp_to_dcm(sigma: ndarray) → ndarray

Convert Modified Rodrigues Parameters to a Direction Cosine Matrix.

Parameters:

sigma (np.ndarray) – MRP vector $[sigma_1, sigma_2, sigma_3]^T$.

Returns:

3x3 Direction Cosine Matrix.

Return type:

np.ndarray

opengnc.utils.mrp_utils.mrp_to_quat(sigma: ndarray) → ndarray

Convert Modified Rodrigues Parameters to a quaternion.

Parameters:

sigma (np.ndarray) – MRP vector $[sigma_1, sigma_2, sigma_3]^T$.

Returns:

Unit quaternion [x, y, z, w].

Return type:

np.ndarray

opengnc.utils.mrp_utils.quat_to_mrp(q: ndarray) → ndarray

Convert a quaternion to Modified Rodrigues Parameters (MRP).

Mathematical form: $sigma = mathbf{q}_{vec} / (1 + q_w)$. Singular for 360-degree rotations ($q_w = -1$).

Parameters:

q (np.ndarray) – Quaternion [x, y, z, w].

Returns:

MRP vector $[sigma_1, sigma_2, sigma_3]^T$.

Return type:

np.ndarray

opengnc.utils.quat_utils module

Quaternion kinematics and math utilities.

opengnc.utils.quat_utils.axis_angle_to_quat(axis: ndarray, angle: float | None = None) → ndarray

Convert axis and angle (or a rotation vector) to a rotation quaternion.

Parameters:

• axis (np.ndarray) – Rotation axis $[u_x, u_y, u_z]$ (if angle is provided) or rotation vector $boldsymbol{theta}$ (if angle is None).

• angle (float, optional) – Rotation angle (radians).

Returns:

Unit quaternion [x, y, z, w].

Return type:

np.ndarray

opengnc.utils.quat_utils.quat_conj(q: ndarray) → ndarray

Compute the conjugate of a quaternion.

Parameters:

q (np.ndarray) – Quaternion [x, y, z, w].

Returns:

Conjugate quaternion [-x, -y, -z, w].

Return type:

np.ndarray

opengnc.utils.quat_utils.quat_inv(q: ndarray) → ndarray

Compute the inverse of a quaternion.

Parameters:

q (np.ndarray) – Quaternion [x, y, z, w].

Returns:

Inverse quaternion.

Return type:

np.ndarray

opengnc.utils.quat_utils.quat_mult(q_left: ndarray, q_right: ndarray) → ndarray

Multiply two quaternions (Hamilton product).

Equation: $mathbf{q}_c = mathbf{q}_a otimes mathbf{q}_b$

Parameters:

• q_left (np.ndarray) – Left quaternion $[x_1, y_1, z_1, w_1]$.

• q_right (np.ndarray) – Right quaternion $[x_2, y_2, z_2, w_2]$.

Returns:

Resulting quaternion $[x_c, y_c, z_c, w_c]$.

Return type:

np.ndarray

opengnc.utils.quat_utils.quat_norm(q: ndarray) → float

Compute the norm of a quaternion.

Parameters:

q (np.ndarray) – Quaternion [x, y, z, w].

Returns:

Norm of the quaternion.

Return type:

float

opengnc.utils.quat_utils.quat_normalize(q: ndarray) → ndarray

Normalize a quaternion to unit length.

Parameters:

q (np.ndarray) – Quaternion [x, y, z, w].

Returns:

Unit quaternion $mathbf{q} / |mathbf{q}|$.

Return type:

np.ndarray

opengnc.utils.quat_utils.quat_rot(q: ndarray, v: ndarray) → ndarray

Rotate a 3D vector by a quaternion.

Equation: $mathbf{v}’ = mathbf{q} otimes [0, mathbf{v}] otimes mathbf{q}^*$

Parameters:

• q (np.ndarray) – Unit quaternion $[x, y, z, w]$.

• v (np.ndarray) – Vector to rotate $[x, y, z]$.

Returns:

Rotated vector $[x’, y’, z’]$.

Return type:

np.ndarray

opengnc.utils.quat_utils.quat_to_rmat(q: ndarray) → ndarray

Convert quaternion to a 3x3 Direction Cosine Matrix (DCM).

Parameters:

q (np.ndarray) – Unit quaternion [x, y, z, w].

Returns:

3x3 rotation matrix.

Return type:

np.ndarray

opengnc.utils.quat_utils.skew_symmetric(v: ndarray) → ndarray

Create a 3x3 skew-symmetric matrix from a vector.

Used for cross products: $a times b = [a]times b$.

Parameters:

v (np.ndarray) – 3D vector.

Returns:

3x3 skew-symmetric matrix.

Return type:

np.ndarray

opengnc.utils.state_conversion module

State and attitude representation conversion utilities.

opengnc.utils.state_conversion.dcm_to_euler(dcm: ndarray, sequence: str) → ndarray

Convert a Direction Cosine Matrix to Euler angles.

Parameters:

• dcm (np.ndarray) – 3x3 Direction Cosine Matrix.

• sequence (str) – Rotation sequence (e.g., ‘321’).

Returns:

Euler angles in radians.

Return type:

np.ndarray

opengnc.utils.state_conversion.dcm_to_quat(dcm: ndarray) → ndarray

Convert a Direction Cosine Matrix to a quaternion.

Uses Shepperd’s algorithm for numerical stability.

Parameters:

dcm (np.ndarray) – 3x3 Direction Cosine Matrix.

Returns:

Unit quaternion [x, y, z, w].

Return type:

np.ndarray

opengnc.utils.state_conversion.euler_to_dcm(angles: ndarray, sequence: str) → ndarray

Convert Euler angles to a Direction Cosine Matrix.

Parameters:

• angles (np.ndarray) – Euler angles in radians.

• sequence (str) – Rotation sequence.

Returns:

3x3 Direction Cosine Matrix.

Return type:

np.ndarray

opengnc.utils.state_conversion.euler_to_quat(angles: ndarray, sequence: str) → ndarray

Convert Euler angles to a quaternion.

Parameters:

• angles (np.ndarray) – Euler angles in radians.

• sequence (str) – Rotation sequence.

Returns:

Quaternion [x, y, z, w].

Return type:

np.ndarray

opengnc.utils.state_conversion.quat_to_dcm(q: ndarray) → ndarray

Convert a quaternion to a Direction Cosine Matrix (DCM).

Parameters:

q (np.ndarray) – Quaternion [x, y, z, w].

Returns:

3x3 Direction Cosine Matrix (Body-to-ECI rotation).

Return type:

np.ndarray

opengnc.utils.state_conversion.quat_to_euler(q: ndarray, sequence: str) → ndarray

Convert a quaternion to Euler angles in a specified sequence.

Parameters:

• q (np.ndarray) – Quaternion [x, y, z, w].

• sequence (str) – Rotation sequence (e.g., ‘321’, ‘313’).

Returns:

Euler angles $[theta_1, theta_2, theta_3]$ in radians.

Return type:

np.ndarray

opengnc.utils.state_to_elements module

Conversions between ECI position/velocity and Keplerian orbital elements.

opengnc.utils.state_to_elements.anomalies(ecc: float, nu: float) → tuple[float, float]

Compute Eccentric and Mean anomaly from True anomaly.

Parameters:

• ecc (float) – Eccentricity.

• nu (float) – True Anomaly (rad).

Returns:

(Eccentric Anomaly, Mean Anomaly) in radians.

Return type:

tuple[float, float]

opengnc.utils.state_to_elements.eci2kepler(r_eci: ndarray, v_eci: ndarray) → tuple[float, float, float, float, float, float, float, float, float, float, float, float]

Convert ECI Cartesian state to Keplerian orbital elements.

Parameters:

• r_eci (np.ndarray) – ECI position vector $[x, y, z]$ (m).

• v_eci (np.ndarray) – ECI velocity vector $[v_x, v_y, v_z]$ (m/s).

Returns:

(a, ecc, incl, raan, argp, nu, M, E, p, arglat, truelon, lonper) - a: Semi-major axis (m) - ecc: Eccentricity - incl: Inclination (rad) - raan: Right Ascension of the Ascending Node (rad) - argp: Argument of Perigee (rad) - nu: True Anomaly (rad) - M: Mean Anomaly (rad) - E: Eccentric Anomaly (rad) - p: Semi-latus rectum (m) - arglat: Argument of Latitude (rad) - truelon: True Longitude (rad) - lonper: Longitude of Perigee (rad)

Return type:

tuple

opengnc.utils.state_to_elements.kepler2eci(a: float, ecc: float, incl: float, raan: float, argp: float, nu: float) → tuple[ndarray, ndarray]

Convert Keplerian elements to ECI Cartesian state.

Parameters:

• a (float) – Semi-major axis (m).

• ecc (float) – Eccentricity.

• incl (float) – Inclination (rad).

• raan (float) – RAAN (rad).

• argp (float) – Argument of Perigee (rad).

• nu (float) – True Anomaly (rad).

Returns:

(Position vector (m), Velocity vector (m/s)).

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.utils.state_to_elements.rot_x(angle: float) → ndarray

Rotation matrix for rotation about x-axis.

Parameters:

angle (float) – Rotation angle in radians.

Returns:

3x3 rotation matrix.

Return type:

np.ndarray

opengnc.utils.state_to_elements.rot_y(angle: float) → ndarray

Rotation matrix for rotation about y-axis.

Parameters:

angle (float) – Rotation angle in radians.

Returns:

3x3 rotation matrix.

Return type:

np.ndarray

opengnc.utils.state_to_elements.rot_z(angle: float) → ndarray

Rotation matrix for rotation about z-axis.

Parameters:

angle (float) – Rotation angle in radians.

Returns:

3x3 rotation matrix.

Return type:

np.ndarray

opengnc.utils.time_utils module

Time system conversions (UTC, TAI, GPS, TT, TDB) and Julian date utilities.

opengnc.utils.time_utils.calc_doy(year: int, month: int, day: int) → int

Calculates the day of the year.

Parameters:

• year (int) – Year.

• month (int) – Month (1-12).

• day (int) – Day of the month (1-31).

Returns:

Day of the year (1-366).

Return type:

int

opengnc.utils.time_utils.calc_gmst(jd: float, dut1: float = 0.0) → float

Calculates Greenwich Mean Sidereal Time from Julian Date and DUT1.

Parameters:

• jd (float) – Julian Date (UT1).

• dut1 (float, optional) – UT1-UTC difference (s). Default is 0.0.

Returns:

Greenwich Mean Sidereal Time in radians.

Return type:

float

opengnc.utils.time_utils.calc_jd(year: int, month: int, day: int, hour: int = 0, minute: int = 0, sec: float = 0.0) → tuple[float, float]

Calculate the Julian Date (JD) from a Gregorian date and time.

Standard epoch is Noon, January 1, 4713 BC.

Parameters:

• year (int) – Year (e.g. 2024).

• month (int) – Month (1-12).

• day (int) – Day of month (1-31).

• hour (int, optional) – Hour (0-23). Default 0.

• minute (int, optional) – Minute (0-59). Default 0.

• sec (float, optional) – Seconds (0-60). Default 0.0.

Returns:

(JD integer part, JD fractional part).

Return type:

tuple[float, float]

opengnc.utils.time_utils.calc_last(jd: float, lon: float, dut1: float = 0.0) → float

Calculates Local Apparent Sidereal Time from Julian Date and Longitude.

Parameters:

• jd (float) – Julian Date (UT1).

• lon (float) – Longitude (rad).

• dut1 (float, optional) – UT1-UTC difference (s). Default is 0.0.

Returns:

Local Apparent Sidereal Time in radians.

Return type:

float

opengnc.utils.time_utils.calc_lst(gmst: float, lon: float, dut1: float = 0.0) → float

Calculates Local Sidereal Time from GMST and Longitude.

Parameters:

• gmst (float) – Greenwich Mean Sidereal Time (rad).

• lon (float) – Longitude (rad).

• dut1 (float, optional) – UT1-UTC difference (s). Default is 0.0.

Returns:

Local Sidereal Time in radians.

Return type:

float

opengnc.utils.time_utils.convert_time(year: int, month: int, day: int, hour: int, minute: int, sec: float, timezone: float, output: str, dut1: float, dat: float) → tuple[float, float, float, float, float, float, float, float, float, float, float, float, float, float, float]

Converts UTC to any time system.

Parameters:

• year (int) – Year.

• month (int) – Month.

• day (int) – Day.

• hour (int) – Hour.

• minute (int) – Minute.

• sec (float) – Seconds.

• timezone (float) – Timezone offset (hours).

• output (str) – Target time system (placeholder).

• dut1 (float) – UT1 - UTC (s).

• dat (float) – TAI - UTC (s).

Returns:

A tuple containing converted time values for various systems: (ut1, tut1, jdut1, jdut1frac, utc, tai, gps, tt, ttt, jdtt, jdttfrac, tdb, ttdb, jdtdb, jdtdbfrac)

Return type:

tuple

opengnc.utils.time_utils.day_to_mdtime(year: int, doy_frac: float) → tuple[int, int, int, int, float]

Convert day-of-year (DOY) to month, day, and time.

Parameters:

• year (int) – Year.

• doy_frac (float) – Day of the year, including fraction (1.0 = Jan 1 00:00).

Returns:

(Month, Day, Hour, Minute, Second).

Return type:

tuple[int, int, int, int, float]

opengnc.utils.time_utils.is_leap_year(year: int) → bool

Checks if a year is a leap year.

Parameters:

year (int) – Year.

Returns:

True if the year is a leap year, False otherwise.

Return type:

bool

opengnc.utils.time_utils.jd_to_datetime(jd: float, jd_frac: float) → tuple[int, int, int, int, int, float]

Convert Julian Date to Gregorian date and time.

Parameters:

• jd (float) – Integer part of Julian Date.

• jd_frac (float) – Fractional part of Julian Date.

Returns:

(Year, Month, Day, Hour, Minute, Second).

Return type:

tuple[int, int, int, int, int, float]

Module contents