@essrt/physics 8.0.0 → 9.1.0

package/types/moon/deep-ecc-channel.d.cts

@@ -1,12 +1,39 @@
 /**
+ * THE SLOPE ANCHOR (owner-approved model change, after the Moon panels).
+ * The 18-term table reproduces the attractor and the 405-kyr beat, but
+ * nothing constrained its local DERIVATIVE at J2000: measured, its ė read
+ * −5.00e-5/cy against the run's own −4.24e-5 (and the observed −4.20e-5),
+ * a 19 % slope error that the lunar chain multiplied straight into the
+ * perigee and node curvature (−44″/cy² against Meeus's −37″/cy² — the
+ * "18 % split" the Moon precession panels showed). Against the ±10-Myr
+ * series the table compresses, the error is a LINEAR vector drift of
+ * 2.25e-4 per kyr out to ±20 kyr (an unresolved ultra-long mode), then
+ * spectrum-class either way. So the anchored form gains a second,
+ * BOUNDED term of the same class as the constant remainder:
+ *
+ *     z(t) = Σ … + (z_J2000 − Σ(0)) + (ż_J2000 − Σ̇(0))·I(t),
+ *     I(t) = ∫₀ᵗ cos²(π τ / 2T_q) dτ  (the arguments' taper: linear near
+ *            J2000, saturating at ±T_q/2 beyond |t| ≥ T_q)
+ *
+ * — ż_J2000 is the run's own z-rate at J2000 (script-written into the
+ * artifact by generate.mjs from the banked series: "we are the source"),
+ * T_q the H/12 taper the arguments' rate anchors ride. Inside the canon it
+ * restores the run's slope exactly; beyond ±T_q it is a constant vector
+ * offset of ~3e-3, the size of the table's own spectrum-class scatter
+ * there, never a growing polynomial. Absent the two fields (an older
+ * artifact), the channel is the value-anchored form above, unchanged.
+ *
  * @param {{
  *   earthZ: ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>,
  *   anchorE: number,
  *   anchorPeriEclipticDeg: number,
+ *   anchorZDotPerYr?: ReadonlyArray<number>,
+ *   slopeTaperYears?: number,
  * }} artifact — the embedded deep-modes artifact (earth z-modes + the J2000
- *   anchor pair joined from the chain artifact's one home).
+ *   anchor pair joined from the chain artifact's one home, + the J2000
+ *   z-rate pair and the taper from the series' one home).
  */
-export function createDeepEccChannel({ earthZ, anchorE, anchorPeriEclipticDeg }: {
+export function createDeepEccChannel({ earthZ, anchorE, anchorPeriEclipticDeg, anchorZDotPerYr, slopeTaperYears }: {
     earthZ: ReadonlyArray<{
         omegaRadPerYr: number;
         re: number;
@@ -14,6 +41,8 @@ export function createDeepEccChannel({ earthZ, anchorE, anchorPeriEclipticDeg }:
     }>;
     anchorE: number;
     anchorPeriEclipticDeg: number;
+    anchorZDotPerYr?: ReadonlyArray<number>;
+    slopeTaperYears?: number;
 }): {
     eccAt: (tYr: number) => number;
     eccRateAt: (tYr: number) => number;

package/types/moon/deep-modes-artifact.d.cts

@@ -136,5 +136,7 @@ export const DEEP_MODES_ARTIFACT: Readonly<{
     anchorPeriEclipticDeg: 462.9179213996577;
     anchorInclEclipticDeg: 0.00010345820355474172;
     anchorAscNodeEclipticDeg: 140.29217988414328;
+    anchorZDotPerYr: number[];
+    slopeTaperYears: 27943.083333333332;
 }>;
 export const DEEP_MODES_ARTIFACT_HASH: "77e0baf779e85de5";

package/types/moon/month-chain.d.cts

@@ -14,6 +14,8 @@
  *     nNodalOfDateJ2000: number,
  *     moonApsidalJ2000Seconds: number,
  *     moonNodalJ2000Seconds: number,
+ *     moonApsidalOfDateJ2000Seconds: number,
+ *     moonNodalOfDateJ2000Seconds: number,
  *     moonSiderealMonthJ2000Seconds: number,
  *     sPerigee: number,
  *     sNode: number,
@@ -47,6 +49,8 @@ export function createMoonMonthChain({ constants, fns }: {
         nNodalOfDateJ2000: number;
         moonApsidalJ2000Seconds: number;
         moonNodalJ2000Seconds: number;
+        moonApsidalOfDateJ2000Seconds: number;
+        moonNodalOfDateJ2000Seconds: number;
         moonSiderealMonthJ2000Seconds: number;
         sPerigee: number;
         sNode: number;

package/types/planets/fibonacci-laws.d.cts

@@ -25,35 +25,6 @@ export function computeInclinationLaw(b: {
     amplitude: number;
     mean: number;
 };
-/**
- * Wobble period: beat of axial precession and perihelion ICRF precession.
- * @param {number} periEclYr @param {number} axialYr @param {number} H
- * @returns {number} years */
-export function computeWobblePeriodYears(periEclYr: number, axialYr: number, H: number): number;
-/**
- * Obliquity cycle with the Venus/Neptune fallback: the record's cycle if
- * present, else |ICRF| (tidally damped — the two-component obliquity
- * formula cancels exactly, constant tilt).
- * @param {number | null | undefined} obliquityCycleYears
- * @param {number} periEclYr @param {number} H @returns {number} */
-export function resolveObliquityCycleYears(obliquityCycleYears: number | null | undefined, periEclYr: number, H: number): number;
-/**
- * Mean obliquity, SNAPSHOT form (the load-time law both engines ship):
- * mean = tiltJ2000 + amp·cos(ωᵢ·t₂₀₀₀) − amp·cos(ωₒ·t₂₀₀₀).
- * @param {{ axialTiltJ2000: number, invPlaneInclinationAmplitude: number,
- *   perihelionEclipticYears: number }} b
- * @param {number | null | undefined} obliqCycleYears — falsy ⇒ static tilt
- * @param {{ H: number, t2000: number }} env — t2000 = 2000 − eccentricity
- *   anchor (balancedYear − systemResetN·H)
- * @returns {number} degrees */
-export function computeObliquityMeanSnapshot(b: {
-    axialTiltJ2000: number;
-    invPlaneInclinationAmplitude: number;
-    perihelionEclipticYears: number;
-}, obliqCycleYears: number | null | undefined, env: {
-    H: number;
-    t2000: number;
-}): number;
 /**
  * K constant from Earth's calibration. @param {{
  *   eccentricityAmplitude: number, massEarthAlone: number, massSun: number,

package/types/planets/model.d.cts

@@ -10,8 +10,14 @@ export type PlanetModelBody = {
     inclinationCycleAnchor?: number | undefined;
     antiPhase?: boolean | undefined;
     perihelionEclipticYears?: number | undefined;
-    axialPrecessionYears?: number | undefined;
-    obliquityCycle?: number | null | undefined;
+    /**
+     * - carriers: the chain's g-mode beat (input since Phase 7 commit 2)
+     */
+    wobblePeriodYears?: number | undefined;
+    /**
+     * - carriers: the derived J2000 obliquity (input since Phase 7 commit 2)
+     */
+    obliquityMeanDeg?: number | undefined;
     axialTiltJ2000?: number | undefined;
     orbitalEccentricityJ2000?: number | undefined;
     ascendingNode?: number | undefined;
@@ -60,8 +66,8 @@ export type PlanetModelRecord = {
  * @property {number} [inclinationCycleAnchor]
  * @property {boolean} [antiPhase]
  * @property {number} [perihelionEclipticYears]
- * @property {number} [axialPrecessionYears]
- * @property {number|null} [obliquityCycle]
+ * @property {number} [wobblePeriodYears] - carriers: the chain's g-mode beat (input since Phase 7 commit 2)
+ * @property {number} [obliquityMeanDeg] - carriers: the derived J2000 obliquity (input since Phase 7 commit 2)
  * @property {number} [axialTiltJ2000]
  * @property {number} [orbitalEccentricityJ2000]
  * @property {number} [ascendingNode]

package/types/planets/secular-shape.d.cts

@@ -0,0 +1,30 @@
+/**
+ * @param {{ secularModes: Record<string, { z: ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}> }> }} artifact
+ * @param {string} key
+ * @returns {{ dom: { arcsecPerYr: number, amp: number }, sub: { arcsecPerYr: number, amp: number },
+ *   rest: { count: number, amp: number }, ampSumAll: number, beatYears: number }}
+ */
+export function computeSecularShape(artifact: {
+    secularModes: Record<string, {
+        z: ReadonlyArray<{
+            omegaRadPerYr: number;
+            re: number;
+            im: number;
+        }>;
+    }>;
+}, key: string): {
+    dom: {
+        arcsecPerYr: number;
+        amp: number;
+    };
+    sub: {
+        arcsecPerYr: number;
+        amp: number;
+    };
+    rest: {
+        count: number;
+        amp: number;
+    };
+    ampSumAll: number;
+    beatYears: number;
+};

package/types/planets/spin-channel.d.cts

@@ -0,0 +1,193 @@
+export type SpinSatellite = {
+    name?: string;
+    gmKm3S2: number;
+    semiMajorAxisKm: number;
+    orbitalPeriodDays: number;
+    retrograde?: boolean;
+};
+export type SpinInputs = {
+    j2: number;
+    j2ReferenceRadiusKm: number;
+    momentOfInertiaFactor: number;
+    momentOfInertiaFactorClass?: string;
+    rotationRateDegPerDay: number;
+    poleRaJ2000Deg: number;
+    poleDecJ2000Deg: number;
+    cassiniLocked?: boolean;
+    satellites: ReadonlyArray<SpinSatellite>;
+};
+/** @typedef {{ name?: string, gmKm3S2: number, semiMajorAxisKm: number, orbitalPeriodDays: number, retrograde?: boolean }} SpinSatellite */
+/** @typedef {{ j2: number, j2ReferenceRadiusKm: number, momentOfInertiaFactor: number,
+ *   momentOfInertiaFactorClass?: string, rotationRateDegPerDay: number,
+ *   poleRaJ2000Deg: number, poleDecJ2000Deg: number, cassiniLocked?: boolean,
+ *   satellites: ReadonlyArray<SpinSatellite> }} SpinInputs */
+/**
+ * The precession constant from the planet's own torques.
+ * @param {{
+ *   j2: number, j2ReferenceRadiusKm: number, momentOfInertiaFactor: number,
+ *   rotationRateDegPerDay: number, satellites: ReadonlyArray<SpinSatellite>,
+ *   gmPlanetSystemKm3S2: number, meanMotionRadPerYr: number, eccentricity: number,
+ * }} p
+ * @returns {{ alphaArcsecPerYr: number, alphaRadPerYr: number, q: number, l: number,
+ *   spinRadPerYr: number, spinRetrograde: boolean, gmPlanetAloneKm3S2: number }}
+ */
+export function computePlanetPrecessionConstant(p: {
+    j2: number;
+    j2ReferenceRadiusKm: number;
+    momentOfInertiaFactor: number;
+    rotationRateDegPerDay: number;
+    satellites: ReadonlyArray<SpinSatellite>;
+    gmPlanetSystemKm3S2: number;
+    meanMotionRadPerYr: number;
+    eccentricity: number;
+}): {
+    alphaArcsecPerYr: number;
+    alphaRadPerYr: number;
+    q: number;
+    l: number;
+    spinRadPerYr: number;
+    spinRetrograde: boolean;
+    gmPlanetAloneKm3S2: number;
+};
+/**
+ * @param {{
+ *   key: string,
+ *   spin: SpinInputs,
+ *   zetaModes: ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>,
+ *   anchorInclEclipticDeg: number, anchorAscNodeEclipticDeg: number,
+ *   semiMajorAxisAU: number, eccentricity: number, massFractionOfSun: number,
+ *   gmSunKm3S2: number, obliquityJ2000Deg: number, stepYr?: number,
+ * }} deps — spin from the astro-reference planetSpinPhysical block; the ζ
+ *   table and the J2000 anchor elements from the governed artifacts; the
+ *   mass fraction (planet system / Sun) for the two-body mean motion
+ *   n = 2π√((1 + μ)/a³); the J2000 obliquity of the ecliptic for the pole
+ *   conversion.
+ */
+export function createPlanetSpinChannel(deps: {
+    key: string;
+    spin: SpinInputs;
+    zetaModes: ReadonlyArray<{
+        omegaRadPerYr: number;
+        re: number;
+        im: number;
+    }>;
+    anchorInclEclipticDeg: number;
+    anchorAscNodeEclipticDeg: number;
+    semiMajorAxisAU: number;
+    eccentricity: number;
+    massFractionOfSun: number;
+    gmSunKm3S2: number;
+    obliquityJ2000Deg: number;
+    stepYr?: number;
+}): Readonly<{
+    key: string;
+    cassiniLocked: boolean;
+    momentOfInertiaFactor: number;
+    momentOfInertiaFactorClass: string;
+    alphaArcsecPerYr: number;
+    satelliteQuadrupole: number;
+    satelliteAngularMomentum: number;
+    spinRetrograde: boolean;
+    meanMotionRadPerYr: number;
+    obliquityJ2000Deg: number;
+    spinPrecessionRateArcsecPerYrJ2000: number | null;
+    axialPrecessionPeriodYearsJ2000: number | null;
+    obliquityDegAtYear: (year: number) => number | null;
+    spinPrecessionRateArcsecPerYrAtYear: (year: number) => number | null;
+    obliquityEnvelopeDeg: (year: number, spanYr: number) => {
+        minDeg: number;
+        meanDeg: number;
+        maxDeg: number;
+    } | null;
+    stepYr: number;
+    maxSpanYr: 10000000;
+}>;
+/**
+ * The channel from the governed artifacts — the ONE construction every
+ * runtime shares (the package model, the Node scene engine, the browser
+ * through the model): the spin block, the chain's J2000 anchor elements and
+ * the deep ζ table for `key`.
+ * @param {{
+ *   key: string,
+ *   planetSpinPhysical: Record<string, SpinInputs>,
+ *   chainAnchorElements: Record<string, { aAU: number, e: number, inclEclipticDeg: number, ascNodeEclipticDeg: number }>,
+ *   planetZeta: Record<string, ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>>,
+ *   massFractionOfSun: number, gmSunKm3S2: number, obliquityJ2000Deg: number,
+ * }} deps
+ */
+export function createPlanetSpinChannelFromArtifacts(deps: {
+    key: string;
+    planetSpinPhysical: Record<string, SpinInputs>;
+    chainAnchorElements: Record<string, {
+        aAU: number;
+        e: number;
+        inclEclipticDeg: number;
+        ascNodeEclipticDeg: number;
+    }>;
+    planetZeta: Record<string, ReadonlyArray<{
+        omegaRadPerYr: number;
+        re: number;
+        im: number;
+    }>>;
+    massFractionOfSun: number;
+    gmSunKm3S2: number;
+    obliquityJ2000Deg: number;
+}): Readonly<{
+    key: string;
+    cassiniLocked: boolean;
+    momentOfInertiaFactor: number;
+    momentOfInertiaFactorClass: string;
+    alphaArcsecPerYr: number;
+    satelliteQuadrupole: number;
+    satelliteAngularMomentum: number;
+    spinRetrograde: boolean;
+    meanMotionRadPerYr: number;
+    obliquityJ2000Deg: number;
+    spinPrecessionRateArcsecPerYrJ2000: number | null;
+    axialPrecessionPeriodYearsJ2000: number | null;
+    obliquityDegAtYear: (year: number) => number | null;
+    spinPrecessionRateArcsecPerYrAtYear: (year: number) => number | null;
+    obliquityEnvelopeDeg: (year: number, spanYr: number) => {
+        minDeg: number;
+        meanDeg: number;
+        maxDeg: number;
+    } | null;
+    stepYr: number;
+    maxSpanYr: 10000000;
+}>;
+/**
+ * The DERIVED J2000 obliquity to the planet's own orbit, degrees: the angle
+ * between the J2000 spin axis (angular-momentum sense — Venus ≈ 177°,
+ * Uranus ≈ 98°) and the chain's J2000 orbit plane. Needs no mode table and
+ * no integration — the load-time twins read it for the K device's
+ * "mean obliquity" slot (commit 2 of Phase 7); the acute form is
+ * `min(ε, 180 − ε)`.
+ * @param {{ spin: SpinInputs, anchorInclEclipticDeg: number,
+ *   anchorAscNodeEclipticDeg: number, obliquityJ2000Deg: number }} p
+ * @returns {number}
+ */
+export function computeObliquityJ2000Deg(p: {
+    spin: SpinInputs;
+    anchorInclEclipticDeg: number;
+    anchorAscNodeEclipticDeg: number;
+    obliquityJ2000Deg: number;
+}): number;
+/**
+ * The IAU pole (ICRF equatorial RA/Dec) as an ecliptic-J2000 unit vector.
+ * @param {number} raDeg @param {number} decDeg @param {number} obliquityJ2000Deg
+ * @returns {number[]}
+ */
+export function poleEclipticJ2000(raDeg: number, decDeg: number, obliquityJ2000Deg: number): number[];
+/**
+ * The planet's orbit normal n̂(t) in ecliptic J2000 from its deep ζ table,
+ * DC-anchored at the chain's J2000 plane (the Earth hybrid's ζ convention:
+ * ζ = sin(i/2)·e^{iΩ}; the anchor is the coordinate the modes wander around).
+ * @param {ReadonlyArray<{omegaRadPerYr: number, re: number, im: number}>} zetaModes
+ * @param {number} anchorInclEclipticDeg @param {number} anchorAscNodeEclipticDeg
+ * @returns {(tYr: number) => number[]}
+ */
+export function createOrbitNormalEvaluator(zetaModes: ReadonlyArray<{
+    omegaRadPerYr: number;
+    re: number;
+    im: number;
+}>, anchorInclEclipticDeg: number, anchorAscNodeEclipticDeg: number): (tYr: number) => number[];