opengnc.disturbances package

Submodules

opengnc.disturbances.drag module

Lumped atmospheric drag model for spacecraft acceleration.

class opengnc.disturbances.drag.LumpedDrag(density_model: Any, co_rotate: bool = True)[source]

Bases: object

Atmospheric Drag Model.

Acceleration Equation: $mathbf{a}_d = -frac{1}{2} rho v_{rel}^2 frac{C_d A}{m} hat{mathbf{v}}_{rel}$

Parameters:

density_model (Any) – Atmospheric density provider.
co_rotate (bool, optional) – Atmospheric co-rotation with planet. Default True.

get_acceleration(r_eci: ndarray, v_eci: ndarray, jd: float, mass: float, area: float, cd: float) → ndarray[source]

Calculate instantaneous drag acceleration vector.

Formula: $mathbf{a}_d = -frac{1}{2} rho v_{rel}^2 frac{C_d A}{m} hat{mathbf{v}}_{rel}$

Parameters:

r_eci (np.ndarray) – ECI Position vector (m).
v_eci (np.ndarray) – ECI Velocity vector (m/s).
jd (float) – Julian Date.
mass (float) – Total spacecraft mass (kg).
area (float) – Effective cross-sectional area ($m^2$).
cd (float) – Drag coefficient.

Returns:

Acceleration vector ($m/s^2$).

Return type:

np.ndarray

opengnc.disturbances.gravity module

Gravitational acceleration models (Two-Body, J2, Harmonics) and Gradient Torques.

class opengnc.disturbances.gravity.GradientTorque(mu: float = 398600441800000.0)[source]

Bases: object

Gravity Gradient Pointing Restoration Torque.

Models the restorative moment acting on an asymmetric rigid body within a non-uniform gravity field.

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

gravity_gradient_torque(J: ndarray, r_eci: ndarray, q_body2eci: ndarray) → ndarray[source]

Calculate Gravity Gradient torque in Body frame.

Equation: $mathbf{T}_{gg} = frac{3mu}{r^3} mathbf{u}_n times (mathbf{J} mathbf{u}_n)$

Parameters:

J (np.ndarray) – Inertia tensor ($3 times 3$) ($kg cdot m^2$).
r_eci (np.ndarray) – ECI Position (m).
q_body2eci (np.ndarray) – Body-to-ECI quaternion $[q_w, q_x, q_y, q_z]$.

Returns:

Reaction torque vector (3,) (Nm).

Return type:

np.ndarray

class opengnc.disturbances.gravity.HarmonicsGravity(mu: float = 398600441800000.0, re: float = 6378137.0, n_max: int = 20, m_max: int = 20, file_path: str | None = None)[source]

Bases: object

High-Fidelity Spherical Harmonics Model (EGM2008).

Calculates the fine-grained gravitational acceleration by expanding the potential as an infinite series of Legendre polynomials and associated functions.

Parameters:

mu (float, optional) – Gravitational parameter ($m^3/s^2$).
re (float, optional) – Planetary reference radius (m).
n_max (int, optional) – Maximum expansion degree.
m_max (int, optional) – Maximum expansion order.
file_path (Optional[str], optional) – Path to harmonic coefficients CSV.

get_acceleration(r_eci: ndarray, jd: float) → ndarray[source]

Calculate harmonic acceleration vector in ECI.

Implements Pines-style or Cunningham recursion for high-order gravity. Handles coordinate transformation between ECI/ECEF.

Parameters:

r_eci (np.ndarray) – ECI Position (m).
jd (float) – Julian Date for frame rotation.

Returns:

Total acceleration vector ($m/s^2$).

Return type:

np.ndarray

class opengnc.disturbances.gravity.J2Gravity(mu: float = 398600441800000.0, j2: float = 0.001082635855, re: float = 6378137.0)[source]

Bases: object

Oblateness Perturbation ($J_2$).

Specific Acceleration: $a_{J2} = frac{3mu J_2 R_e^2}{2r^5} left[ (5frac{z^2}{r^2}-1)x, (5frac{z^2}{r^2}-1)y, (5frac{z^2}{r^2}-3)z right]$

Parameters:

mu (float, optional) – Gravitational parameter ($m^3/s^2$).
j2 (float, optional) – J2 coefficient.
re (float, optional) – Equatorial radius (m).

get_acceleration(r_eci: ndarray, jd: float | None = None) → ndarray[source]

Calculate acceleration including $J_2$ perturbation.

Formula: $a_{j2,x} = frac{3}{2} J_2 frac{mu}{r^2} frac{R_e^2}{r^2} frac{x}{r} (5frac{z^2}{r^2} - 1)$

Parameters:

r_eci (np.ndarray) – ECI Position (m).
jd (float | None, optional) – Julian Date.

Returns:

Acceleration vector ($m/s^2$).

Return type:

np.ndarray

class opengnc.disturbances.gravity.OceanTidesGravity(mu: float = 398600441800000.0, re: float = 6378137.0)[source]

Bases: object

Spherical Harmonic Ocean Tide Model (Simplified).

Applies periodic corrections to the potential field due to displacement of oceanic mass.

Parameters:

mu (float, optional) – Gravitational parameter.
re (float, optional) – Reference radius.

get_acceleration(r_eci: ndarray, jd: float) → ndarray[source]

Calculate tidal acceleration contribution in ECI.

Parameters:

r_eci (np.ndarray) – ECI Position.
jd (float) – Julian Date.

Returns:

Correction vector ($m/s^2$).

Return type:

np.ndarray

class opengnc.disturbances.gravity.RelativisticCorrection(mu: float = 398600441800000.0, J_earth: ndarray | None = None)[source]

Bases: object

General Relativistic Gravitational Correction.

Includes static Schwarzschild and dynamic Lense-Thirring (frame-dragging) effects.

Parameters:

mu (float, optional) – Gravitational parameter.
J_earth (Optional[np.ndarray], optional) – Angular momentum vector of the planet.

get_acceleration(r_eci: ndarray, v_eci: ndarray) → ndarray[source]

Calculate relativistic acceleration correction.

Parameters:

r_eci (np.ndarray) – State vectors in ECI.
v_eci (np.ndarray) – State vectors in ECI.

Returns:

Correction vector ($m/s^2$).

Return type:

np.ndarray

class opengnc.disturbances.gravity.ThirdBodyGravity(mu_sun: float = 1.32712440018e+20, mu_moon: float = 4902800066000.0)[source]

Bases: object

Solar and Lunar Gravitational Perturbation Model.

Calculates the point-mass acceleration acting on the spacecraft due to the Sun and Moon.

Parameters:

mu_sun (float, optional) – Solar gravitational parameter.
mu_moon (float, optional) – Lunar gravitational parameter.

get_acceleration(r_eci: ndarray, jd: float) → ndarray[source]

Calculate combined third-body acceleration.

Parameters:

r_eci (np.ndarray) – Satellite ECI position (m).
jd (float) – Julian Date.

Returns:

Acceleration vector ($m/s^2$).

Return type:

np.ndarray

class opengnc.disturbances.gravity.TwoBodyGravity(mu: float = 398600441800000.0)[source]

Bases: object

Standard Point-Mass Gravity.

Acceleration: $mathbf{a}_{gg} = -frac{mu}{r^3} mathbf{r}$

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

get_acceleration(r_eci: ndarray, jd: float | None = None) → ndarray[source]

Calculate point mass acceleration.

Parameters:

r_eci (np.ndarray) – ECI Position (m).
jd (float | None, optional) – Julian Date.

Returns:

Acceleration ($m/s^2$).

Return type:

np.ndarray

opengnc.disturbances.srp module

Solar Radiation Pressure (SRP) acceleration models.

class opengnc.disturbances.srp.Canonball[source]

Bases: object

Solar Radiation Pressure (SRP) ‘Cannonball’ Model.

Calculates acceleration due to solar photon momentum transfer, assuming a spherical spacecraft with uniform optical properties.

Acceleration Equation: $mathbf{a}_{srp} = -nu P_{AU} left(frac{AU}{d_{sun}}right)^2 C_r frac{A}{m} hat{mathbf{u}}_{sun}$

Parameters:: None – Initialized with default solar pressure at 1 AU.

check_eclipse(r_sat: ndarray, r_sun: ndarray) → float[source]

Determine if the spacecraft is in Earth’s shadow (Cylindrical Model).

Parameters:

r_sat (np.ndarray) – Satellite ECI position.
r_sun (np.ndarray) – Sun ECI position.

Returns:

Shadow factor [0=Full shadow, 1=Full sunlight].

Return type:

float

get_acceleration(r_eci: ndarray, jd: float, mass: float, area: float, cr: float) → ndarray[source]

Calculate SRP acceleration vector.

Formula: $mathbf{a}_{srp} = -nu P_{AU} left(frac{AU}{d_{sun}}right)^2 C_r frac{A}{m} hat{mathbf{u}}_{sun}$

Parameters:

r_eci (np.ndarray) – ECI Position (m).
jd (float) – Julian Date.
mass (float) – Total mass (kg).
area (float) – Solar cross-sectional area ($m^2$).
cr (float) – Radiation pressure coefficient $[1, 2]$.

Returns:

Acceleration vector ($m/s^2$).

Return type:

np.ndarray

opengnc.disturbances package

Submodules

opengnc.disturbances.drag module

opengnc.disturbances.gravity module

opengnc.disturbances.srp module

Module contents