E1004 Annex A Gravity Environment Reference Data
Overview
ECSS-E-ST-10-04C Annex A provides the gravity-environment reference
constants and tables (gravitational parameters, Earth oblateness
coefficients) that every orbit-dependent environment or dynamics
analysis draws on: orbit lifetime, station-keeping budgets, attitude
disturbance-torque, and the trapped-radiation/meteoroid geometry used
by sibling leaves all assume a consistent gravity model as their
starting point. This is a reference-data leaf: it does not size a
mission, it categorizes and supplies the constants and the checks
needed to decide which gravity terms a given orbit case must model.
The environment has three parts that must be categorized and combined
separately:
- Point-mass (two-body) gravity — the dominant
GM/r^2
attraction of the central body, using its gravitational parameter
(GM, km^3/s^2).
- Earth oblateness (J2 zonal harmonic) — the correction from
Earth's equatorial bulge, which is latitude-dependent and falls off
faster with radius than the point-mass term, so it matters most for
low orbits and drops toward negligible at high altitude.
- Third-body tidal perturbation — the differential pull of the
Moon and Sun across the orbit, which grows with orbit radius (it is
negligible in LEO and becomes significant approaching GEO and
beyond).
This leaf computes:
- The point-mass gravitational acceleration for a body's
GM at a
given radius, plus the derived circular-orbit and escape velocities.
- The J2 zonal-harmonic perturbation acceleration at a given radius
and geocentric latitude.
- The third-body tidal perturbation acceleration for the Moon or Sun
at a given orbit radius and body distance.
- Which of the J2 and third-body terms are significant enough
(relative to the point-mass term) that an orbit case's gravity model
must include them, and whether a case's modeled term set is
compliant with that requirement.
When to invoke this skill
- Populating the gravity-constant and gravity-model-term inputs to an
orbit lifetime, station-keeping, or perturbation-budget analysis.
- Deciding whether a mission's orbit propagator configuration (which
zonal harmonics, which third bodies) is adequate for its orbit
regime, rather than carrying every term everywhere by default.
- Cross-checking a vendor-supplied gravity-model configuration (e.g.
from STK, GMAT, or an in-house propagator) against an independent
order-of-magnitude estimate of which terms actually matter.
Not for higher-order geopotential tesseral/sectoral terms beyond J2,
full trapped-radiation or meteoroid environments (e1004-trapped-leo,
e1004-annex-c-flux, and siblings), or atmospheric drag — those are
separate leaves in this family.
Data provenance and fidelity notice
The gravitational parameters (GM_SUN_KM3_S2, GM_EARTH_KM3_S2,
GM_MOON_KM3_S2), Earth equatorial radius, and the J2 coefficient
embedded in scripts/e1004_ref_gravity_logic.py are widely published
astrodynamics reference constants (the same order used by WGS84/
EGM96-class Earth gravity models), not a transcription of the
standard's Annex A tables. The J2 perturbation-acceleration formula is
the standard two-term (radial/meridional) zonal-harmonic approximation
found in general astrodynamics references (e.g. Vallado); the
third-body term uses the standard near-field tidal-acceleration
approximation (2 * GM_third * r / d^3, valid for orbit radius r
much smaller than the third-body distance d). For mission-grade,
traceable analysis, replace the constants with the specific gravity
model (e.g. EGM2008, DE440 planetary ephemeris) called out by the
project's applicable-documents list, keeping the same function
interface (point_mass_gravity_accel_km_s2,
j2_perturbation_acceleration_km_s2, tidal_acceleration_km_s2). The
significance-threshold and compliance logic are model-independent and
do not need to change when the constants are swapped.
Steps
- Get the reference constant.
gm_for_body(body_name) looks up
the gravitational parameter (km^3/s^2) for "sun", "earth", or
"moon"; raises ValueError for any other name.
- Compute the point-mass term.
point_mass_gravity_accel_km_s2(gm_km3_s2, radius_km) returns GM/r^2. circular_orbit_velocity_km_s() and
escape_velocity_km_s() derive the companion reference velocities
for the same GM/radius pair.
- Compute the J2 term.
j2_perturbation_acceleration_km_s2(radius_km, geocentric_latitude_deg) returns the Earth oblateness perturbation
acceleration magnitude at that radius and latitude; rejects a radius
below the Earth's surface or a latitude outside [-90, 90].
- Compute the third-body term.
tidal_acceleration_km_s2(gm_third_km3_s2, orbit_radius_km, distance_to_third_km) returns the Moon's or Sun's
tidal perturbation acceleration for the case's orbit radius and
current body distance; rejects a third body no farther away than the
orbit radius itself.
- Decide which terms are required.
significant_gravity_terms(radius_km, geocentric_latitude_deg, distance_to_moon_km, distance_to_sun_km, threshold_fraction=1e-6) computes the point-mass term and all three
perturbation terms together, and flags each perturbation term
required when its acceleration is at least threshold_fraction of
the point-mass term.
- Check compliance.
missing_gravity_model_terms(term_assessment, modeled_terms) returns the required term names absent from a case's
modeled term set (empty list when compliant);
is_gravity_model_compliant(missing_terms) reduces that to a single
boolean. Do not close the gravity-environment input while any orbit
case has non-empty missing terms.
Script reference
scripts/e1004_ref_gravity_logic.py — gravitational-parameter table,
point-mass/J2/tidal acceleration formulas, and the significance and
compliance checks.
scripts/test_e1004_ref_gravity.py — unit tests for the constant
lookup, acceleration formulas' bounds and monotonicity, and the
significance/compliance logic.
1---2name: e1004-ref-gravity3description: "Use when defining Earth and third-body gravitational reference constants (GM, J2 oblateness coefficient) per ECSS-E-ST-10-04C Annex A for a space mission: compute point-mass, J2 zonal-harmonic, and third-body tidal perturbation accelerations at a given orbit radius, and determine which gravity-model terms the mission's environment specification must carry for the orbit regime and mission duration. Trigger: gravity constants, GM, J2 oblateness, zonal harmonic, third-body tidal acceleration, gravity environment specification, e-st-10-04, ecss."4license: Apache-2.05compliance: STANDARDS-REF6standards:7 - id: ecss8 reference-only: true9gated: false10metadata:11 source: https://skillmd.com/skills/ashfordeou/e1004-ref-gravity12 domain: space-systems13 subdomain: ecss14 tags: [ecss, e-st-10-04c, gravity, gm, j2, zonal-harmonic, third-body, tidal, annex-a]15 version: 0.1.016 author: Aero Agent Skills17---1819# E1004 Annex A Gravity Environment Reference Data2021## Overview2223ECSS-E-ST-10-04C Annex A provides the gravity-environment reference24constants and tables (gravitational parameters, Earth oblateness25coefficients) that every orbit-dependent environment or dynamics26analysis draws on: orbit lifetime, station-keeping budgets, attitude27disturbance-torque, and the trapped-radiation/meteoroid geometry used28by sibling leaves all assume a consistent gravity model as their29starting point. This is a reference-data leaf: it does not size a30mission, it categorizes and supplies the constants and the checks31needed to decide which gravity terms a given orbit case must model.3233The environment has three parts that must be categorized and combined34separately:35361. **Point-mass (two-body) gravity** — the dominant `GM/r^2`37 attraction of the central body, using its gravitational parameter38 (`GM`, km^3/s^2).392. **Earth oblateness (J2 zonal harmonic)** — the correction from40 Earth's equatorial bulge, which is latitude-dependent and falls off41 faster with radius than the point-mass term, so it matters most for42 low orbits and drops toward negligible at high altitude.433. **Third-body tidal perturbation** — the differential pull of the44 Moon and Sun across the orbit, which grows with orbit radius (it is45 negligible in LEO and becomes significant approaching GEO and46 beyond).4748This leaf computes:491. The point-mass gravitational acceleration for a body's `GM` at a50 given radius, plus the derived circular-orbit and escape velocities.512. The J2 zonal-harmonic perturbation acceleration at a given radius52 and geocentric latitude.533. The third-body tidal perturbation acceleration for the Moon or Sun54 at a given orbit radius and body distance.554. Which of the J2 and third-body terms are significant enough56 (relative to the point-mass term) that an orbit case's gravity model57 must include them, and whether a case's modeled term set is58 compliant with that requirement.5960## When to invoke this skill6162- Populating the gravity-constant and gravity-model-term inputs to an63 orbit lifetime, station-keeping, or perturbation-budget analysis.64- Deciding whether a mission's orbit propagator configuration (which65 zonal harmonics, which third bodies) is adequate for its orbit66 regime, rather than carrying every term everywhere by default.67- Cross-checking a vendor-supplied gravity-model configuration (e.g.68 from STK, GMAT, or an in-house propagator) against an independent69 order-of-magnitude estimate of which terms actually matter.7071Not for higher-order geopotential tesseral/sectoral terms beyond J2,72full trapped-radiation or meteoroid environments (`e1004-trapped-leo`,73`e1004-annex-c-flux`, and siblings), or atmospheric drag — those are74separate leaves in this family.7576## Data provenance and fidelity notice7778The gravitational parameters (`GM_SUN_KM3_S2`, `GM_EARTH_KM3_S2`,79`GM_MOON_KM3_S2`), Earth equatorial radius, and the J2 coefficient80embedded in `scripts/e1004_ref_gravity_logic.py` are **widely published81astrodynamics reference constants** (the same order used by WGS84/82EGM96-class Earth gravity models), not a transcription of the83standard's Annex A tables. The J2 perturbation-acceleration formula is84the standard two-term (radial/meridional) zonal-harmonic approximation85found in general astrodynamics references (e.g. Vallado); the86third-body term uses the standard near-field tidal-acceleration87approximation (`2 * GM_third * r / d^3`, valid for orbit radius `r`88much smaller than the third-body distance `d`). For mission-grade,89traceable analysis, replace the constants with the specific gravity90model (e.g. EGM2008, DE440 planetary ephemeris) called out by the91project's applicable-documents list, keeping the same function92interface (`point_mass_gravity_accel_km_s2`,93`j2_perturbation_acceleration_km_s2`, `tidal_acceleration_km_s2`). The94significance-threshold and compliance logic are model-independent and95do not need to change when the constants are swapped.9697## Steps98991. **Get the reference constant.** `gm_for_body(body_name)` looks up100 the gravitational parameter (km^3/s^2) for `"sun"`, `"earth"`, or101 `"moon"`; raises `ValueError` for any other name.1022. **Compute the point-mass term.** `point_mass_gravity_accel_km_s2(gm_km3_s2,103 radius_km)` returns `GM/r^2`. `circular_orbit_velocity_km_s()` and104 `escape_velocity_km_s()` derive the companion reference velocities105 for the same `GM`/radius pair.1063. **Compute the J2 term.** `j2_perturbation_acceleration_km_s2(radius_km,107 geocentric_latitude_deg)` returns the Earth oblateness perturbation108 acceleration magnitude at that radius and latitude; rejects a radius109 below the Earth's surface or a latitude outside `[-90, 90]`.1104. **Compute the third-body term.** `tidal_acceleration_km_s2(gm_third_km3_s2,111 orbit_radius_km, distance_to_third_km)` returns the Moon's or Sun's112 tidal perturbation acceleration for the case's orbit radius and113 current body distance; rejects a third body no farther away than the114 orbit radius itself.1155. **Decide which terms are required.** `significant_gravity_terms(radius_km,116 geocentric_latitude_deg, distance_to_moon_km, distance_to_sun_km,117 threshold_fraction=1e-6)` computes the point-mass term and all three118 perturbation terms together, and flags each perturbation term119 `required` when its acceleration is at least `threshold_fraction` of120 the point-mass term.1216. **Check compliance.** `missing_gravity_model_terms(term_assessment,122 modeled_terms)` returns the required term names absent from a case's123 modeled term set (empty list when compliant);124 `is_gravity_model_compliant(missing_terms)` reduces that to a single125 boolean. Do not close the gravity-environment input while any orbit126 case has non-empty missing terms.127128## Script reference129130- `scripts/e1004_ref_gravity_logic.py` — gravitational-parameter table,131 point-mass/J2/tidal acceleration formulas, and the significance and132 compliance checks.133- `scripts/test_e1004_ref_gravity.py` — unit tests for the constant134 lookup, acceleration formulas' bounds and monotonicity, and the135 significance/compliance logic.