# Gravity Gradient Stabilization > Use when you must design or analyze passive gravity-gradient stabilization: check the inertia-ratio stability criterion I_y > I_x > I_z with y along the orbit normal for a nadir-pointing spacecraft, compute the pitch libration frequency and period from the mean motion and the inertia spread, estimate the gravity-gradient restoring torque at a pitch offset, and size a gravity boom tip mass for a target libration stiffness. Produces the stability verdict, the libration period, the restoring torque and the boom sizing that gate the passive attitude design of a nadir-pointing spacecraft. Trigger: gravity-gradient stabilization, inertia-ratio criterion, pitch libration frequency and period, gravity boom sizing, nadir-pointing spacecraft, passive attitude stabilization. - Skill: `ashfordeou/gravity-gradient-stabilization` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add ashfordeou/gravity-gradient-stabilization` - Raw SKILL.md: https://api.skillmd.com/api/skills/ashfordeou/gravity-gradient-stabilization/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: Apache-2.0 - Author: ashfordeOU (https://skillmd.com/u/ashfordeou) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ashfordeou/gravity-gradient-stabilization --- # Gravity-Gradient Stabilization (space-systems/adcs/gravity-gradient-stabilization) Use when the task is designing or analyzing passive gravity-gradient stabilization for a nadir-pointing spacecraft: a long, slender body in a circular orbit aligns itself with the local vertical because the gravity gradient of the Earth field makes the smallest-inertia axis point nadir, provided the intermediate-inertia axis lies along the orbit normal. This leaf implements the passive design view in pure Python, stdlib only: the inertia-ratio stability criterion, the pitch libration frequency and period, the restoring torque at a pitch offset, and gravity boom tip-mass sizing for a target libration stiffness. It pairs with gnc-autonomy/space/attitude-dynamics, which models the ambient gravity torque and propagates the full rigid-body state over the same nadir geometry, and with the active actuation leaves of this pack, which replace passive stiffness with momentum exchange. ## Domain quick reference - Mean motion of the circular orbit: n = sqrt(mu / r^3), with mu the gravitational parameter and r the orbital radius. At 500 km altitude the radius is 6,878 km and n = 1.1068e-3 rad/s. - Inertia-ratio stability criterion: passive nadir pointing is stable when I_y > I_x > I_z, where x lies along the velocity direction, y along the orbit normal and z points nadir. The largest principal moment must be about the orbit normal. Verdict via stability_verdict(ix, iy, iz). - Pitch libration frequency: omega_p = sqrt(3 * n^2 * (I_x - I_z) / I_y), computed by pitch_libration_frequency; the period follows as 2 * pi / omega_p via libration_period. - Libration period identity: T_lib = T_orbit / sqrt(3 * (I_x - I_z) / I_y). When the spread fraction (I_x - I_z) / I_y stays below one third, the libration period exceeds the orbital period (6555 s versus 5677 s at the worked example, a 1.155 ratio). - Gravity-gradient restoring torque at a pitch offset theta: T = (3/2) * n^2 * (I_x - I_z) * sin(2 * theta), from restoring_torque. The torque is zero at 0 and 90 degrees and largest in magnitude at 45 degrees. - Gravity boom sizing: a point tip mass m at the end of a boom of length L contributes m * L^2 to the inertia spread I_x - I_z, so m_tip = target_spread / L^2 via boom_tip_mass_for_stiffness. - Units are SI throughout: kg m^2 for inertia, s for period, N m for torque. - ECSS frames the space environment and system context; the relations above are standard engineering methodology, summary-only. ## Workflow 1. Fix the orbit and geometry: the gravitational parameter mu and the circular orbital radius r, then set the mean motion with mean_motion(mu, radius). 2. Fix the principal moments I_x, I_y, I_z and run the inertia-ratio criterion with stability_verdict(ix, iy, iz); confirm the ranking with moment_ordering(ix, iy, iz), which returns the axes by descending moment, for example "y > x > z". 3. When the criterion holds, compute the pitch libration frequency with pitch_libration_frequency(ix, iy, iz, mu, radius) and the libration period with libration_period(ix, iy, iz, mu, radius). 4. Estimate the gravity-gradient restoring torque at the governing pitch offset with restoring_torque(ix, iy, iz, mu, radius, pitch_offset_deg); use 45 degrees for the largest restoring torque. 5. Size the gravity boom for the required stiffness: boom_tip_mass_for_stiffness(ix_other, target_ix_minus_iz, boom_length) returns the tip mass that adds the target inertia spread. 6. Gather the design report with gg_report(ix, iy, iz, mu, radius, pitch_offset_deg), a dict with keys stable, ordering, omega_p, period_s, period_min and torque; quantity keys are None when the criterion fails. 7. Confirm the deterministic checks with the contract test scripts/test_gravity_gradient_stabilization.py. ## Worked example Circular orbit at 500 km: mu = 3.986004418e14 m3/s2 and r = 6.878e6 m give n = 1.1068e-3 rad/s (mean_motion). The principal moments are I = (60, 80, 40) kg m2 with x along velocity, y along the orbit normal and z nadir. - Inertia-ratio criterion: stability_verdict(60, 80, 40) is True because 80 > 60 > 40; moment_ordering returns "y > x > z". A swap to I = (80, 60, 40) fails the verdict (x would be the largest moment). - Pitch libration: omega_p = 9.585e-4 rad/s and the period is 6555 s, equal to 109.25 min, about 1.155 orbital periods (the 5677 s orbit period divided by sqrt(3 * 20 / 80)). - Restoring torque: at a 45 degree pitch offset the torque is 3.675e-5 N m (36.75 uN m), the largest value; it is exactly zero at 0 and 90 degrees. - Boom sizing: for a target inertia spread of 20 kg m2 with a 10 m boom, boom_tip_mass_for_stiffness(60, 20, 10) returns 0.2 kg. - Report: gg_report(60, 80, 40, mu, r) returns stable True, ordering "y > x > z", omega_p 9.585e-4 rad/s, period_s 6555, period_min 109.25 and torque 3.675e-5 N m at the default 45 degree offset. ## Verification - Confirm mean_motion(3.986004418e14, 6.878e6) returns 1.1068e-3 rad/s within 1e-6. - Confirm stability_verdict returns True on (60, 80, 40), False on (80, 60, 40) where ix exceeds iy, and False on (60, 40, 80) where iz is not the smallest moment. - Confirm libration_period returns 6555 s within 20 s and 109.25 min within 0.5 min. - Confirm restoring_torque at 45 degrees is 3.675e-5 N m within 1e-6 and exactly zero at 0 degrees. - Confirm the identities: the period equals the orbital period divided by sqrt(3 * (ix - iz) / iy), and doubling the inertia spread raises omega_p by sqrt(2). - Confirm boom_tip_mass_for_stiffness(60, 20, 10) returns 0.2 kg within 0.01. - Confirm every non-positive inertia, a negative spread (ix - iz < 0), mu or radius at or below zero, and a pitch offset magnitude above 90 degrees raises ValueError. - Confirm gg_report keys are exactly stable, ordering, omega_p, period_s, period_min and torque, and that repeated calls are deterministic. - Run the contract test offline: python3 scripts/test_gravity_gradient_stabilization.py. ## Related leaves - gnc-autonomy/space/attitude-dynamics: the ambient gravity torque model and full rigid-body state propagation over the same nadir-pointing geometry; this leaf adds the stability criterion, libration and boom sizing that attitude-dynamics deliberately does not compute. - space-systems/adcs/attitude-control-sizing: sizing the active pointing alternative when the passive stiffness and damping budget is set. - space-systems/orbit-mechanics/three-body-libration: the libration of a body about the collinear equilibrium points of the restricted three body problem, a distinct regime from the Earth-orbiting nadir libration treated here. ## Pitfalls - Treating the inertia spread as the whole criterion: the libration relations need only a positive spread I_x - I_z, but passive stability needs the full rank order I_y > I_x > I_z; a body with spread yet I_x >= I_y fails the verdict and its report quantities come back None. - Feeding altitude instead of radius: mean_motion takes the orbital radius r = R_earth + h (6,878 km at 500 km altitude); using 500 km in its place overstates the mean motion by a factor of about 51. - Expecting the libration period below the orbital period: with the spread fraction below one third, omega_p stays below n and the libration period exceeds the orbit period (6555 s against 5677 s), so the 2 * pi / n guess understates the true period. - Using the small-angle torque at large offsets: restoring_torque uses sin(2 * theta), which vanishes at 90 degrees; the linear torque 3 * n^2 * (I_x - I_z) * theta is valid only near the nadir equilibrium. - Treating the boom sizing as exact: m_tip = spread / L^2 is the point-mass approximation and ignores the boom's own mass and finite tip size, so it is a preliminary sizing, not a final mass budget. - Mixing torque units: the restoring torque runs at tens of uN m (3.675e-5 N m at the worked example); report in N m and convert deliberately. ## Behavior contract (gate 3) Run the deterministic contract test (stdlib unittest, offline): python3 scripts/test_gravity_gradient_stabilization.py The test covers the worked-example anchors (mean motion at 500 km within 1e-6 rad/s, libration period 6555 s within 20 s, restoring torque 3.675e-5 N m at 45 degrees, boom tip mass 0.2 kg), the inertia-ratio verdict on all three orderings of the example moments, the libration period identity against the orbital period and the sqrt(2) scaling of omega_p with a doubled inertia spread, torque zero crossings at 0 and 90 degrees with the maximum at 45 degrees, gg_report key structure and unstable-configuration behavior, run-to-run determinism, and ValueError rejection of non-positive inertia, negative inertia spread, non-positive mu or radius, and pitch offsets outside the -90 to 90 degree range. ## Compliance - Standards referenced, not reproduced: ECSS standards are copyright ESA and freely downloadable; this leaf cites ECSS as reference only per standards-map.yaml. The logic here is generic passive attitude control physics (inertia-ratio criterion, pitch libration, gravity boom stiffness), not ECSS text. - compliance: STANDARDS-REF, gated: false.