rms-gravity

Introduction

rms-gravity models the gravity field of an oblate planet as GM plus the even zonal harmonics (J2, J4, ...) and computes the quantities that ring and satellite dynamicists need from such a field. Around an oblate planet the three fundamental orbital frequencies -- the mean motion, the radial (epicyclic) oscillation frequency, and the vertical oscillation frequency -- differ from one another, which drives apsidal precession, nodal regression, and the rich resonant structure of planetary rings.

The package supplies those frequencies and their radial derivatives, solves the inverse problem (which orbit has a given frequency), locates Lindblad resonances, and converts between Cartesian state vectors and two kinds of orbital elements. It was developed at the PDS Ring-Moon Systems Node of the SETI Institute and includes ready-made fields for the Sun, the planets, and the major satellites.

Features

• Orbital frequencies: mean motion, radial and vertical oscillation frequencies, and their radial derivatives, with second-order eccentricity and inclination corrections.
• Precision frequency combinations: apsidal precession and nodal regression rates computed without catastrophic cancellation, even where the combination cancels to first or second order.
• Frequency inversion: solve for the semimajor axis that has a given mean motion, precession rate, or any linear combination of the three frequencies.
• Lindblad resonances: pattern speeds of inner and outer Lindblad resonances of any order.
• Orbital elements: conversions between state vectors and both osculating (two-body) and geometric (Renner & Sicardy 2006) orbital elements, vectorized over NumPy arrays.
• Predefined fields: the Sun, all planets, major satellites, and combined system fields (for example the Pluto-Charon barycenter field), retrievable by name.

Installation

rms-gravity requires Python 3.10 or later and depends only on NumPy. Install it from PyPI:

pip install rms-gravity

Quick Start

import gravity

# Orbital frequencies at Saturn's F ring (radians/s)
a = 140220.                        # semimajor axis in km
print(gravity.SATURN.omega(a))     # mean motion
print(gravity.SATURN.kappa(a))     # radial oscillation frequency
print(gravity.SATURN.nu(a))        # vertical oscillation frequency

# Apsidal precession rate in degrees per day
print(gravity.SATURN.dperi_dt(a) * gravity.DPD)

# Where is the Mimas 2:1 inner Lindblad resonance?
n_mimas = gravity.SATURN.omega(185539.)
print(gravity.SATURN.solve_a(2.*n_mimas, (2, -1, 0)))   # ~117,555 km

# Convert geometric orbital elements to a state vector and back
elements = (140220., 0.003, 0., 0., 0., 0.)   # (a, e, inc, mean_lon, peri, node)
pos, vel = gravity.SATURN.state_from_geom(elements)
print(gravity.SATURN.geom_from_state(pos, vel))

# Fields are also available by name
print(gravity.lookup('SATURN BARYCENTER').gm)

All distances are in km, all angles in radians, and all frequencies in radians per second. The User Guide covers each of these workflows in detail.

Documentation

Full documentation, including the User Guide and the API reference, is available at Read the Docs. To build it locally, run ./scripts/read-docs.sh from the repository root.

Contributing

Information on contributing to this package can be found in the Contributing Guide.

Links

• Documentation
• Repository
• Issue tracker
• PyPi

Licensing

This code is licensed under the Apache License v2.0.