Crate gravitational

Expand description

§gravitational

Gravitational waves from nanohertz to terahertz, in one place: what they carry, how they travel, how sensitive every kind of detector is, and how far a detector can see. Strain conventions, noise curves, inspirals and binary pulsars, the black hole a merger leaves and how it rings, neutron-star tides, memory, the graviton’s mass and number, stochastic backgrounds, high-frequency limits, lensing and cosmological distances, and the gravity of lab sources, each tested against published numbers. Pure Rust, SI units.

§Install

cargo add gravitational metrology

§Example: how far can Advanced LIGO see two neutron stars?

use gravitational::{curves, inspiral};
use metrology::{MPC, SOLAR_MASS};

let (m1, m2) = (1.4 * SOLAR_MASS, 1.4 * SOLAR_MASS);
let horizon = inspiral::horizon(m1, m2, 8.0, curves::aligo, 20.0);
let range = horizon / inspiral::HORIZON_TO_RANGE;
println!("horizon {:.0} Mpc, average range {:.0} Mpc", horizon / MPC, range / MPC);

§Example: the strongest and the weakest

The brightest events radiate about a thousandth of the Planck luminosity c⁵/G; the oldest confirmed prediction is the slow decay of a binary pulsar’s orbit. A detectable wave holds about 10³⁶ gravitons per wavelength-sized cell, yet matter is so transparent that water absorbs it over 10¹¹ Gpc.

use gravitational::{energy, propagation, quanta};
use metrology::{C, MPC, SOLAR_MASS};

assert!((3.5e49 / energy::PLANCK_LUMINOSITY - 9.6e-4).abs() < 1e-5); // GW150914 at its peak

let pbdot = energy::peters_pbdot(1.438 * SOLAR_MASS, 1.390 * SOLAR_MASS, 0.322997448918 * 86_400.0, 0.6171340);
println!("Hulse–Taylor: {pbdot:.3e} s/s"); // −2.402e-12; measured −2.40263(5)e-12

println!("{:.1e} gravitons", quanta::graviton_count(1e-21, 150.0)); // 3.9e36
let water = propagation::viscous_damping(1e-3, 1e3, 1e-12).unwrap();
println!("absorbed over {:.1e} Gpc of water", C / water / (1e3 * MPC)); // 2.6e11

§Example: the ceiling on high-frequency waves

Any gravitational-wave background from the early Universe counts as extra radiation, so Big Bang nucleosynthesis and the CMB cap it. No detector built or proposed above 10 kHz reaches the cap.

use gravitational::{hf, strain::{Convention, hc_from_omega}};

let ceiling = hc_from_omega(hf::CEILING_BBN_CMB, 1e9, 1.0, Convention::OneSided);
println!("at 1 GHz no background can exceed h_c = {ceiling:.1e}"); // 1.3e-30

for limit in hf::REGISTRY {
    println!("{:<45} {:.1e} {} ({:?})", limit.name, limit.value, limit.quantity, limit.status);
}

§Example: a gravity sensor as a wave detector

A wave of strain h stretches a baseline L, so two free masses feel a tidal acceleration ½ω²hL. Gradiometers, atom interferometers and satellite pairs all measure that; the baseline decides how well.

use gravitational::detectors::{AtomGwDetector, K_SR87, gradiometer_strain};

// AION-km: two strontium clouds 2 km apart (Badurina et al. 2020).
let aion = AtomGwDetector { baseline: 2000.0, t: 5.0, lmt: 40_000.0, phase_noise: 3e-6, k: K_SR87, diamonds: 1.0 };
println!("{:.1e} per √Hz at 0.1 Hz", aion.peak_strain()); // 2.1e-21

// A GOCE-class gradiometer (10 mE/√Hz) read the same way: 5e-11 per √Hz at 0.1 Hz.
assert!(gradiometer_strain(1e-11, 0.1) > 1e10 * aion.peak_strain());

§What is inside

Module	What it computes
`strain`	Ω_GW ↔ S_h ↔ h_c, with the one-sided and two-sided conventions made explicit (Moore, Cole & Berry 2015)
`cosmology`	Flat ΛCDM comoving, angular-diameter and time-delay distances; the six H0LiCOW lenses give back H₀ = 73.3 (Wong et al. 2020); `Cosmology` with curvature, CPL dark energy, radiation and exact massive neutrinos, the transverse and between-redshift angular-diameter distances, and `PLANCK18` (icosmo, Kayser and astropy’s Mathematica values; Planck’s 100θ*)
`curves`	Advanced LIGO and Einstein Telescope fits (Sathyaprakash & Schutz 2009); LISA with galactic confusion (Robson, Cornish & Liu 2019); tabulated curves
`inspiral`	Chirp mass, time to merger, ISCO, the energy spectrum, matched-filter SNR, horizon and range (Chen et al. 2021); the Kerr ISCO with its energy and angular momentum, and the equatorial photon orbit (Bardeen, Press & Teukolsky 1972); the spin-aware ISCO frequency `kerr_f_isco` (Isoyama et al. 2014)
`energy`	The Planck luminosity, strain from luminosity, the circular-binary flux and the multipole flux coefficients (Blanchet), Peters’ eccentricity enhancement and binary-pulsar decay, the Shapiro range, shape and delay (Kramer et al. 2021), the advance of periastron and the geodetic precession (Will 2014); the next-to-leading-order Shapiro delay, with lensing and Kopeikin & Schäfer’s retardation (checked against an exact moving-mass delay), and the aberration terms (Kramer et al. 2021)
`ringdown`	Kerr quasinormal modes for `l = 2, 3, 4`, every `m`, three overtones, from the fits of Berti, Cardoso & Will 2006, checked against their exact tables; ringing frequency and damping time; `qnm_exact`, Leaver’s continued fraction in Cook & Zalutskiy’s form, Berti’s Schwarzschild digits to 10⁻¹⁶ and all 693 BCW06 entries
`remnant`	The final spin (Hofmann, Barausse & Rezzolla 2016), the radiated energy (Barausse, Morozova & Rezzolla 2012) and the horizon area of a merger’s black hole, for aligned spins; the precessing final spin and generic-spin radiated energy
`tides`	Neutron-star tidal deformability `Λ` and the binary `Λ̃` the waveform measures, with GW170817’s bounds (LVC 2019); the relativistic Love number from TOV and Postnikov’s Riccati equation, with Read et al.’s SLy and AP4 piecewise polytropes
`lensing`	The isothermal sphere’s Einstein radius (O’Riordan et al. 2025), microlensing magnification, centroid shift and lens mass (Sahu et al. 2025), the NFW halo (Wright & Brainerd 2000), and a registry of time-delay `H₀` labelled assertive or conservative (TDCOSMO 2025); the critical surface density, NFW normalisation and Dutton–Macciò concentration, Lee et al.’s exact finite-source magnification, the H₀ measurements by method, and the OGLE-2011-BLG-0462 mass history
`memory`	The leading-order memory of a binary (Favata 2010) and its ramp in pulsar timing
`propagation`	Speed bounds from GW170817, graviton Compton wavelength, dispersion and delay with the current mass bounds, point-lens lensing in geometrical and wave optics (Takahashi & Nakamura 2003), viscous absorption with its validity check (Baym et al. 2017)
`quanta`	Graviton counts and occupation numbers, stimulated and spontaneous single-graviton rates and the optimal bar mass (Tobar et al. 2024), and a bar’s absorption cross-section (Aguiar 2011)
`sgwb`	Power-law-integrated sensitivity curves (Thrane & Romano 2013), Hellings–Downs, pulsar-timing backgrounds (NANOGrav 2023), and the energy scale and background of inflation
`hf`	The cosmological ceiling, magnetic conversion of waves to photons (Ejlli et al. 2019), the plasma cut-off, cavity noise, source lines, and a registry of limits with their status (Aggarwal et al. 2025)
`detectors`	Gravity sensors as wave detectors: atom-interferometer strain response (Graham et al. 2016, Eq. 9), and the strain noise of gradiometers, optical clocks (Kolkowitz et al. 2016) and satellite pairs
`ultralight`	Ultralight dark matter as an oscillating signal: the Compton frequency `mc²/h`, the mass window of the mid-band between LISA and the ground detectors (MAGIS-100, AION), and the coherence length
`laboratory`	A beam’s gravitational near field (Rätzel et al. 2016), waves from spinning bodies, wave energy flux, and the Newtonian calibrators of LIGO (Ross et al. 2021) and Virgo (Estevez et al. 2018)

§Applications

Detector design. Horizon and range decide a detector’s event rate, which is how next-generation designs are argued; examples/detector_range.rs works it through.
Testing general relativity. examples/binary_pulsar.rs reproduces the Hulse–Taylor orbital decay from published orbital elements.
Bounding a background. sgwb and hf convert between the strain, spectral density and energy-density conventions papers quote, and hf::REGISTRY carries the published limits with their status.
Sizing a laboratory source. laboratory::quadrupole_strain says what a lab source radiates, and examples/lab_hfgw.rs sets it against the best detectors.
Multi-messenger timing. propagation gives the speed bounds, dispersion and lensing delays.

§How it is checked

Every formula is tested against numbers published in, or recomputed from, the papers above:

Detectors: the LISA curve at five frequencies; the published peak strains of AION-10, AION-100, AION-km and AICE; Kolkowitz et al.’s clock strain.
Binaries: the binary-neutron-star chirp mass, time to merger and ISCO; the decay of B1913+16 (to its quoted mass precision) and of the double pulsar; GW170817’s spectral fluence; the double pulsar’s periastron advance (to its 2PN term), Mercury’s 42.98″ per century, S2’s 12.1′ per orbit, the lunar de Sitter precession and Gravity Probe B’s geodetic drift.
Energy and quanta: the Planck luminosity; Blanchet’s flux coefficients exactly; Tobar et al.’s rates and bar masses; Carney et al.’s occupation number; Aguiar’s LSU bar cross-section.
Propagation: GW170817’s speed bounds; the graviton Compton wavelength against Bernus et al.; lensing magnifications and delays; viscous damping in water and air, and its refusal for a mantle.
Backgrounds: NANOGrav’s energy density; Hellings–Downs values; inflation’s energy scale for r = 0.036, 0.034 and 0.01.
The lab: the petawatt beam; the Misner–Thorne–Wheeler spinning rod; LIGO’s rotor force (19.10 pN by direct summation) and Virgo’s x f² = 3.3×10⁻¹⁴ m Hz²; Ejlli et al.’s photon-rate prefactor; an ADMX-like cavity.

All formulas are written from the papers, not translated from other codes, so the crate stays MIT-licensed. The research behind the newer modules is in the report on where gravity physics is still open.

One of eight crates in physica: physica (all of them, plus cross-domain analogies) · metrology (constants) · geopotential (the gravity field) · gravimetry (missions and GRACE) · gravitational (waves) · gravitics (frontier gravity) · magnetics (magnetism and MHD) · plasmoid (fusion plasma).

Modules§

cosmology: Distances in a Friedmann universe: what a lensed quasar’s time delays, a standard siren, a supernova or the CMB’s acoustic scale measure.
curves: Detector noise curves: one-sided strain power spectral densities S_n(f) in Hz⁻¹.
detectors: Gravitational waves as seen by the sensors this crate models: long-baseline atom interferometers, gradiometers, optical clocks and satellite pairs.
energy: The energy gravitational waves carry: the Planck luminosity c⁵/G, the strain a given luminosity produces, the quadrupole flux of a circular binary and its multipole coefficients, and the orbital decay of binary pulsars (Peters & Mathews 1963).
hf: High-frequency gravitational waves (above 10 kHz): the cosmological ceiling, conversion of waves into photons in a magnetic field, resonant-cavity noise, source frequencies, and a registry of published limits, each with its status.
inspiral: Compact-binary inspirals at leading (Newtonian) order: chirp mass, time to merger, frequency drift, the innermost stable circular orbit, matched-filter signal-to-noise ratio, and how far away a detector can see a binary (Sathyaprakash & Schutz 2009; Chen et al. 2021).
laboratory: Laboratory gravity, sized honestly: the gravitational field of a light or particle beam, the gravitational waves a spinning body radiates, and the energy a wave carries.
lensing: Gravitational lensing by galaxies, stars and dark-matter haloes: the Einstein radius of a singular isothermal sphere, point-lens microlensing of point and finite sources and the mass it weighs, the critical density, the NFW halo’s normalisation, concentration and surface density, and the Hubble constant from lensed quasars beside the other methods.
memory: Gravitational-wave memory: the permanent strain a burst leaves behind, from the waves’ own energy (the nonlinear Christodoulou memory), and how it shows in pulsar timing.
propagation: How gravitational waves travel: their speed, a graviton mass, gravitational lensing, and absorption by matter.
quanta: Gravitons: how many quanta a classical wave holds, and whether a resonant bar could absorb one (Tobar et al. 2024; Carney, Domcke & Rodd 2024).
remnant: The black hole a merger leaves: its spin, the energy radiated, and its horizon area, for binaries with spins aligned or anti-aligned with the orbit, and the spin for generic (precessing) spins.
ringdown: Black-hole ringdown: the quasinormal modes a merger’s remnant rings in, from the fits of Berti, Cardoso & Will 2006, Tables VIII–X.
sgwb: Stochastic backgrounds and pulsar timing: power laws, power-law-integrated sensitivity curves (Thrane & Romano 2013) and the Hellings–Downs curve.
strain: Converting between the three ways to state the size of a gravitational-wave background: energy density Ω_GW, strain power spectral density S_h, and characteristic strain h_c.
tides: Tides in a neutron-star inspiral: how much each star deforms in its companion’s field, and the one combination of the two that the waveform measures first (at 5PN order).
ultralight: Ultralight bosonic dark matter as an oscillating signal: the Compton frequency of a very light boson, and the detector band it falls in.

Constants§

H100: Hubble constant for h = 1 (100 km s⁻¹ Mpc⁻¹), s⁻¹. Multiply by the dimensionless h.

Functions§

integrate_log: ∫ g(f) df from lo to hi (both > 0) by Simpson’s rule on a logarithmic grid of n intervals (n is made even). Accurate for the smooth power-law integrands used here.