Propagate exoplanets with their real orbital period

Every exoplanet was propagated with gmForParent(undefined) — the Sun's
gravitational parameter — so the whole catalogue orbited as though each host
were exactly one solar mass. Most hosts are red dwarfs far lighter than that,
and a heavier central mass pulls harder and shortens the period, so their
planets were whirling round much too fast: TRAPPIST-1 is 0.09 solar masses, and
its planets were completing an orbit in roughly a third of the true time.

pl_orbper was already in the TAP query and was being discarded on the way into
the record. It is now kept, along with st_mass. A period and a semi-major axis
together pin the host's gravitational parameter exactly, via GM = n^2 a^3 — no
stellar model, no assumption, just the inverse of the orbitalPeriodDays helper
that was already there.

resolveGravitationalParameter picks the best available source: the measured
period, else the published host mass, else one solar mass as before. A derived
value implying something outside 0.01-150 solar masses is rejected and falls
through, since a period and axis taken from disagreeing solutions would
otherwise send a planet spinning at a visibly absurd rate.

Note the direction of the error, which is the opposite of what it looks like:
assuming a *heavier* host than reality makes a planet orbit *faster*. A test
pins it, and caught me stating it backwards first.

The NASA Exoplanet Archive is unreachable from this environment (egress policy
returns 403 on CONNECT), so exoplanets.json cannot be regenerated here and still
carries no periods. Behaviour is therefore unchanged until `npm run etl` is run
somewhere with archive access, at which point every planet with a published
period starts moving correctly with no further code changes. build.ts reports
how many records gained a period, and rejects non-positive ones.

Tests: 171 passing, up from 151, including a new end-to-end check that
TRAPPIST-1 b with its real period completes exactly one orbit in 1.51088 days
and sits a full diameter away at half that.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WaySiNst4HhDXBHnMy8p5G

src/app/shared/astro/kepler.spec.ts

@@ -2,11 +2,13 @@ import { describe, expect, it } from 'vitest';
 
 import { GM_SUN_AU3_PER_DAY2, DEFAULT_EPOCH_JD } from './constants';
 import {
+  gravitationalParameterFromPeriod,
   meanMotionRadPerDay,
   orbitEllipsePoints,
   orbitalPeriodDays,
   positionAtTrueAnomaly,
   propagateOrbit,
+  resolveGravitationalParameter,
   resolveOrbitalElements,
   solveEccentricAnomaly,
   trueAnomalyFromEccentricAnomaly
@@ -163,3 +165,90 @@ describe('resolveOrbitalElements', () => {
     expect(resolved.argumentOfPeriapsisDeg).toBe(50);
   });
 });
+
+describe('gravitationalParameterFromPeriod', () => {
+  it('round-trips with orbitalPeriodDays', () => {
+    const derived = gravitationalParameterFromPeriod(1, 365.256);
+    expect(orbitalPeriodDays(1, derived)).toBeCloseTo(365.256, 9);
+  });
+
+  it('recovers the Sun from Earth\'s orbit', () => {
+    // 1 AU in one sidereal year is the definition of the solar gravitational parameter.
+    const derived = gravitationalParameterFromPeriod(1, 365.256363);
+    expect(derived / GM_SUN_AU3_PER_DAY2).toBeCloseTo(1, 4);
+  });
+
+  it('recovers a red dwarf from a real short-period orbit', () => {
+    // TRAPPIST-1 b: 0.01154 AU in 1.51088 days around a 0.0898 solar-mass star.
+    const derived = gravitationalParameterFromPeriod(0.01154, 1.51088);
+    expect(derived / GM_SUN_AU3_PER_DAY2).toBeCloseTo(0.09, 2);
+  });
+
+  it('scales as a^3 at fixed period', () => {
+    const single = gravitationalParameterFromPeriod(1, 100);
+    const doubled = gravitationalParameterFromPeriod(2, 100);
+    expect(doubled / single).toBeCloseTo(8, 9);
+  });
+});
+
+describe('resolveGravitationalParameter', () => {
+  it('prefers the measured period over everything else', () => {
+    // The period says 0.09 solar masses; the (deliberately wrong) host mass says 5.
+    const gm = resolveGravitationalParameter({ semiMajorAxisAu: 0.01154, periodDays: 1.51088, hostStarMassSolar: 5 });
+    expect(gm / GM_SUN_AU3_PER_DAY2).toBeCloseTo(0.09, 2);
+  });
+
+  it('corrects a red dwarf planet that the solar-mass assumption spun too fast', () => {
+    const withPeriod = resolveGravitationalParameter({ semiMajorAxisAu: 0.01154, periodDays: 1.51088 });
+    const assumingSolar = resolveGravitationalParameter({ semiMajorAxisAu: 0.01154 });
+
+    // A heavier central mass pulls harder, so it shortens the period: T scales as 1/sqrt(GM).
+    // Assuming the Sun for TRAPPIST-1's 0.09 solar masses therefore made its planets orbit
+    // sqrt(0.09) = 0.3x the true period — about 3.3x too fast, not too slow.
+    expect(orbitalPeriodDays(0.01154, withPeriod)).toBeCloseTo(1.51088, 4);
+    const ratio = orbitalPeriodDays(0.01154, assumingSolar) / orbitalPeriodDays(0.01154, withPeriod);
+    expect(ratio).toBeCloseTo(Math.sqrt(0.09), 2);
+  });
+
+  it('falls back to the host star mass when no period is published', () => {
+    const gm = resolveGravitationalParameter({ semiMajorAxisAu: 0.5, hostStarMassSolar: 0.31 });
+    expect(gm).toBeCloseTo(GM_SUN_AU3_PER_DAY2 * 0.31, 12);
+  });
+
+  it('falls back to one solar mass when nothing is known', () => {
+    expect(resolveGravitationalParameter({ semiMajorAxisAu: 1 })).toBe(GM_SUN_AU3_PER_DAY2);
+  });
+
+  it('ignores a period that is missing, zero, negative or not a number', () => {
+    for (const periodDays of [undefined, 0, -5, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(resolveGravitationalParameter({ semiMajorAxisAu: 1, periodDays })).toBe(GM_SUN_AU3_PER_DAY2);
+    }
+  });
+
+  it('ignores a host mass that is missing, zero or negative', () => {
+    for (const hostStarMassSolar of [undefined, 0, -1, Number.NaN]) {
+      expect(resolveGravitationalParameter({ semiMajorAxisAu: 1, hostStarMassSolar })).toBe(GM_SUN_AU3_PER_DAY2);
+    }
+  });
+
+  it('rejects a period implying something that cannot be a star, and falls through', () => {
+    // 1 AU in a single day implies thousands of solar masses.
+    const gm = resolveGravitationalParameter({ semiMajorAxisAu: 1, periodDays: 1, hostStarMassSolar: 0.5 });
+    expect(gm).toBeCloseTo(GM_SUN_AU3_PER_DAY2 * 0.5, 12);
+  });
+
+  it('rejects a period implying far too little mass', () => {
+    // 1 AU taking a million days implies a mass far below any star.
+    expect(resolveGravitationalParameter({ semiMajorAxisAu: 1, periodDays: 1e6 })).toBe(GM_SUN_AU3_PER_DAY2);
+  });
+
+  it('rejects an implausible host mass too', () => {
+    expect(resolveGravitationalParameter({ semiMajorAxisAu: 1, hostStarMassSolar: 5000 })).toBe(GM_SUN_AU3_PER_DAY2);
+  });
+
+  it('keeps a real short-period hot Jupiter around a sun-like star', () => {
+    // 51 Pegasi b: 0.0527 AU in 4.23 days around a ~1.1 solar-mass star.
+    const gm = resolveGravitationalParameter({ semiMajorAxisAu: 0.0527, periodDays: 4.230785 });
+    expect(gm / GM_SUN_AU3_PER_DAY2).toBeCloseTo(1.1, 1);
+  });
+});

src/app/shared/astro/kepler.ts

@@ -1,5 +1,5 @@
 import { CartesianCoordinates } from './coordinates';
-import { DEFAULT_EPOCH_JD } from './constants';
+import { DEFAULT_EPOCH_JD, GM_SUN_AU3_PER_DAY2 } from './constants';
 import { OrbitalElements } from '../models/body.model';
 
 const DEG_TO_RAD = Math.PI / 180;
@@ -34,6 +34,72 @@ export function orbitalPeriodDays(semiMajorAxisAu: number, gmAu3PerDay2: number)
   return TWO_PI / meanMotionRadPerDay(semiMajorAxisAu, gmAu3PerDay2);
 }
 
+/**
+ * Gravitational parameter implied by a measured orbital period — the inverse of
+ * {@link orbitalPeriodDays}: `GM = n^2 * a^3`, with `n = 2*pi / T`.
+ *
+ * This is how an exoplanet's host star gets its mass into the propagator. Nothing about the
+ * star needs to be known or guessed: the period and the semi-major axis between them pin the
+ * gravitational parameter exactly.
+ */
+export function gravitationalParameterFromPeriod(semiMajorAxisAu: number, periodDays: number): number {
+  const meanMotion = TWO_PI / periodDays;
+  return meanMotion * meanMotion * semiMajorAxisAu * semiMajorAxisAu * semiMajorAxisAu;
+}
+
+/**
+ * Plausible range for a host star's mass, in solar masses — from below the hydrogen-burning
+ * limit to beyond the heaviest known stars. Used only to reject a derived value that cannot be
+ * a star, which would otherwise send a planet spinning at a visibly absurd rate.
+ */
+const MIN_PLAUSIBLE_STELLAR_MASS_SOLAR = 0.01;
+const MAX_PLAUSIBLE_STELLAR_MASS_SOLAR = 150;
+
+function isPositiveFinite(value: number | undefined): value is number {
+  return value !== undefined && Number.isFinite(value) && value > 0;
+}
+
+/**
+ * The gravitational parameter to propagate a planet with, in AU^3/day^2, best source first:
+ *
+ * 1. **Its measured orbital period.** Exact, and independent of any stellar model.
+ * 2. **Its host star's measured mass.**
+ * 3. **One solar mass**, as a last resort.
+ *
+ * Falling back to the Sun is a real approximation, not a neutral default. Most exoplanet hosts
+ * are red dwarfs far lighter than the Sun, and a heavier central mass pulls harder and shortens
+ * the period, so assuming solar mass makes their planets whirl round far too fast. TRAPPIST-1
+ * is 0.09 solar masses; its planets were completing an orbit in roughly a third of the true
+ * time.
+ */
+export function resolveGravitationalParameter(input: {
+  semiMajorAxisAu: number;
+  periodDays?: number;
+  hostStarMassSolar?: number;
+}): number {
+  const { semiMajorAxisAu, periodDays, hostStarMassSolar } = input;
+
+  if (isPositiveFinite(periodDays) && isPositiveFinite(semiMajorAxisAu)) {
+    const derived = gravitationalParameterFromPeriod(semiMajorAxisAu, periodDays);
+    const impliedMassSolar = derived / GM_SUN_AU3_PER_DAY2;
+    // A period and axis drawn from disagreeing solutions can imply something that is not a
+    // star; prefer a known-approximate answer over a confidently wrong one.
+    if (impliedMassSolar >= MIN_PLAUSIBLE_STELLAR_MASS_SOLAR && impliedMassSolar <= MAX_PLAUSIBLE_STELLAR_MASS_SOLAR) {
+      return derived;
+    }
+  }
+
+  if (
+    isPositiveFinite(hostStarMassSolar) &&
+    hostStarMassSolar >= MIN_PLAUSIBLE_STELLAR_MASS_SOLAR &&
+    hostStarMassSolar <= MAX_PLAUSIBLE_STELLAR_MASS_SOLAR
+  ) {
+    return GM_SUN_AU3_PER_DAY2 * hostStarMassSolar;
+  }
+
+  return GM_SUN_AU3_PER_DAY2;
+}
+
 /** Normalizes an angle (radians) into [0, 2*pi). */
 function normalizeAngle(angleRad: number): number {
   const wrapped = angleRad % TWO_PI;

src/app/shared/models/exoplanet.model.ts

@@ -12,5 +12,13 @@ export interface ExoplanetRecord {
   radiusEarth?: number;
   massEarth?: number;
   discoveryYear?: number;
+  /**
+   * Measured orbital period in days (`pl_orbper`). Together with the semi-major axis this
+   * pins the host star's gravitational parameter exactly, so the planet can be propagated at
+   * its real rate instead of as though it orbited the Sun — see `resolveGravitationalParameter`.
+   */
+  periodDays?: number;
+  /** Host star mass in solar masses (`st_mass`); the fallback when no period is published. */
+  hostStarMassSolar?: number;
   orbit: Partial<OrbitalElements>;
 }