@essrt/physics 4.8.0 → 4.9.0

package/src/constants/generated.d.ts

@@ -17,7 +17,7 @@ export declare const DEFAULT_CONSTANTS: {
       "type": string;
       "angleCorrection": number;
       "startpos": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "ascendingNodeInvPlane": number;
       "inclinationCycleAnchor": number;
       "invPlaneInclinationMean": number;
@@ -29,7 +29,7 @@ export declare const DEFAULT_CONSTANTS: {
       "type": string;
       "angleCorrection": number;
       "startpos": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "ascendingNodeInvPlane": number;
       "inclinationCycleAnchor": number;
       "invPlaneInclinationMean": number;
@@ -41,7 +41,7 @@ export declare const DEFAULT_CONSTANTS: {
       "type": string;
       "angleCorrection": number;
       "startpos": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "ascendingNodeInvPlane": number;
       "inclinationCycleAnchor": number;
       "invPlaneInclinationMean": number;
@@ -53,7 +53,7 @@ export declare const DEFAULT_CONSTANTS: {
       "orbitDistanceOverride": number;
       "angleCorrection": number;
       "startpos": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "ascendingNodeInvPlane": number;
       "inclinationCycleAnchor": number;
       "invPlaneInclinationMean": number;
@@ -377,7 +377,7 @@ export declare const DEFAULT_CONSTANTS: {
       "eocFraction": number;
       "startpos": number;
       "angleCorrection": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "type": string;
       "mirrorPair": string;
       "fibonacciD": number;
@@ -385,16 +385,16 @@ export declare const DEFAULT_CONSTANTS: {
       "inclinationCycleAnchor": number;
       "antiPhase": boolean;
       "ascendingNodeCyclesIn8H": number;
-      "obliquityCycleFraction": number[];
-      "axialPrecessionFraction": number[];
-      "eccentricityCycleFraction": number[];
+      "obliquityCycleFraction": [number, number];
+      "axialPrecessionFraction": [number, number];
+      "eccentricityCycleFraction": [number, number];
     };
     "venus": {
       "name": string;
       "eocFraction": number;
       "startpos": number;
       "angleCorrection": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "type": string;
       "mirrorPair": string;
       "fibonacciD": number;
@@ -403,15 +403,15 @@ export declare const DEFAULT_CONSTANTS: {
       "antiPhase": boolean;
       "ascendingNodeCyclesIn8H": number;
       "obliquityCycleFraction": null;
-      "axialPrecessionFraction": number[];
-      "eccentricityCycleFraction": number[];
+      "axialPrecessionFraction": [number, number];
+      "eccentricityCycleFraction": [number, number];
     };
     "mars": {
       "name": string;
       "eocFraction": number;
       "startpos": number;
       "angleCorrection": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "type": string;
       "mirrorPair": string;
       "fibonacciD": number;
@@ -419,16 +419,16 @@ export declare const DEFAULT_CONSTANTS: {
       "inclinationCycleAnchor": number;
       "antiPhase": boolean;
       "ascendingNodeCyclesIn8H": number;
-      "obliquityCycleFraction": number[];
-      "axialPrecessionFraction": number[];
-      "eccentricityCycleFraction": number[];
+      "obliquityCycleFraction": [number, number];
+      "axialPrecessionFraction": [number, number];
+      "eccentricityCycleFraction": [number, number];
     };
     "jupiter": {
       "name": string;
       "eocFraction": number;
       "startpos": number;
       "angleCorrection": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "type": string;
       "mirrorPair": string;
       "fibonacciD": number;
@@ -436,16 +436,16 @@ export declare const DEFAULT_CONSTANTS: {
       "inclinationCycleAnchor": number;
       "antiPhase": boolean;
       "ascendingNodeCyclesIn8H": number;
-      "obliquityCycleFraction": number[];
-      "axialPrecessionFraction": number[];
-      "eccentricityCycleFraction": number[];
+      "obliquityCycleFraction": [number, number];
+      "axialPrecessionFraction": [number, number];
+      "eccentricityCycleFraction": [number, number];
     };
     "saturn": {
       "name": string;
       "eocFraction": number;
       "startpos": number;
       "angleCorrection": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "type": string;
       "mirrorPair": string;
       "fibonacciD": number;
@@ -453,16 +453,16 @@ export declare const DEFAULT_CONSTANTS: {
       "inclinationCycleAnchor": number;
       "antiPhase": boolean;
       "ascendingNodeCyclesIn8H": number;
-      "obliquityCycleFraction": number[];
-      "axialPrecessionFraction": number[];
-      "eccentricityCycleFraction": number[];
+      "obliquityCycleFraction": [number, number];
+      "axialPrecessionFraction": [number, number];
+      "eccentricityCycleFraction": [number, number];
     };
     "uranus": {
       "name": string;
       "eocFraction": number;
       "startpos": number;
       "angleCorrection": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "type": string;
       "mirrorPair": string;
       "fibonacciD": number;
@@ -470,9 +470,9 @@ export declare const DEFAULT_CONSTANTS: {
       "inclinationCycleAnchor": number;
       "antiPhase": boolean;
       "ascendingNodeCyclesIn8H": number;
-      "obliquityCycleFraction": number[];
-      "axialPrecessionFraction": number[];
-      "eccentricityCycleFraction": number[];
+      "obliquityCycleFraction": [number, number];
+      "axialPrecessionFraction": [number, number];
+      "eccentricityCycleFraction": [number, number];
       "eccentricityCycleApprox": boolean;
     };
     "neptune": {
@@ -480,7 +480,7 @@ export declare const DEFAULT_CONSTANTS: {
       "eocFraction": number;
       "startpos": number;
       "angleCorrection": number;
-      "perihelionEclipticFraction": number[];
+      "perihelionEclipticFraction": [number, number];
       "type": string;
       "mirrorPair": string;
       "fibonacciD": number;
@@ -489,8 +489,8 @@ export declare const DEFAULT_CONSTANTS: {
       "antiPhase": boolean;
       "ascendingNodeCyclesIn8H": number;
       "obliquityCycleFraction": null;
-      "axialPrecessionFraction": number[];
-      "eccentricityCycleFraction": number[];
+      "axialPrecessionFraction": [number, number];
+      "eccentricityCycleFraction": [number, number];
       "eccentricityCycleApprox": boolean;
     };
   };
@@ -690,14 +690,14 @@ export declare const REFERENCE_DATA: {
     "exeligmosDays": number;
   };
   readonly laplaceLagrangeBounds: {
-    "mercury": number[];
-    "venus": number[];
-    "earth": number[];
-    "mars": number[];
-    "jupiter": number[];
-    "saturn": number[];
-    "uranus": number[];
-    "neptune": number[];
+    "mercury": [number, number];
+    "venus": [number, number];
+    "earth": [number, number];
+    "mars": [number, number];
+    "jupiter": [number, number];
+    "saturn": [number, number];
+    "uranus": [number, number];
+    "neptune": [number, number];
   };
   readonly moonGrailWilliams2014: {
     "j2E6": number;

package/src/model.js

@@ -147,12 +147,23 @@ export function assembleModel(C, F, laws = {}, secularSeriesArtifact = /** @type
   let latticeAlphaPin = false;
   /** @type {number|null} */
   let alphaL1J2000 = null;
+  // Exact-argument memo (mirrors src/script.js + tools/lib/deep-time.js —
+  // the round-5 perf campaign): same tMa → bit-identical value; the pin
+  // branch bypasses the memo; bounded by wholesale clear.
+  /** @type {Map<number, number>} */
+  const alphaMemo = new Map();
   /** @param {number} tMa @returns {number} */
   const earthMoiFactorAtAge = (tMa) => {
     if (latticeAlphaPin) return earthMoiFactorJ2000;
-    if (alphaL1J2000 === null) alphaL1J2000 = evalClimateL1(2000);
-    const L1at = evalClimateL1(2000 - tMa * 1e6);
-    return earthMoiFactorJ2000 - alphaClimateScale * (L1at - alphaL1J2000);
+    let v = alphaMemo.get(tMa);
+    if (v === undefined) {
+      if (alphaL1J2000 === null) alphaL1J2000 = evalClimateL1(2000);
+      const L1at = evalClimateL1(2000 - tMa * 1e6);
+      v = earthMoiFactorJ2000 - alphaClimateScale * (L1at - alphaL1J2000);
+      if (alphaMemo.size >= 8192) alphaMemo.clear();
+      alphaMemo.set(tMa, v);
+    }
+    return v;
   };
 
   // ── Layer 0 + deep-time core ──────────────────────────────────────────────

package/types/cardinal/index.d.cts

@@ -0,0 +1,80 @@
+export type DerivedCoefs = {
+    lincoef: number;
+    h0: number;
+    h1: number;
+};
+export type EccTerm = {
+    order: number;
+    sin: number;
+    cos: number;
+};
+export type JointTerm = {
+    order: number;
+    div: number;
+    sin: number;
+    cos: number;
+};
+/** @typedef {{ lincoef: number, h0: number, h1: number }} DerivedCoefs */
+/** @typedef {{ order: number, sin: number, cos: number }} EccTerm */
+/** @typedef {{ order: number, div: number, sin: number, cos: number }} JointTerm */
+/**
+ * @param {{
+ *   isDeepTime: () => boolean,
+ *   constants: {
+ *     anchors: Record<string, number>,
+ *     harmonics: Record<string, Array<[number, number, number]>>,
+ *     eccTerms: (Record<string, EccTerm[]> | null),
+ *     jointTerms: ({ terms: JointTerm[] } | null),
+ *     derived: (DerivedCoefs | null),
+ *     tropicalHarmonics: Array<[number, number, number]>,
+ *     balancedYear: number,
+ *     meanSolarYearDays: number,
+ *     hJ2000: number,
+ *     tiltMeanDeg: number,
+ *     raAngleDeg: number,
+ *     inclAmplitudeDeg: number,
+ *   },
+ *   fns: {
+ *     cyclesBetween: (yearA: number, yearB: number, divisorN: number) => (number | null),
+ *     analyticTropicalDays: (year: number) => (number | null),
+ *     meanHAtAgeMa: (tMa: number) => (number | null),
+ *     meanYearRealLodDays: (tMa: number) => (number | null),
+ *     eccentricityAt: (year: number) => number,
+ *     eccentricityRateAt: (year: number) => number,
+ *   },
+ * }} deps
+ */
+export function createCardinalModel({ isDeepTime, constants, fns }: {
+    isDeepTime: () => boolean;
+    constants: {
+        anchors: Record<string, number>;
+        harmonics: Record<string, Array<[number, number, number]>>;
+        eccTerms: (Record<string, EccTerm[]> | null);
+        jointTerms: ({
+            terms: JointTerm[];
+        } | null);
+        derived: (DerivedCoefs | null);
+        tropicalHarmonics: Array<[number, number, number]>;
+        balancedYear: number;
+        meanSolarYearDays: number;
+        hJ2000: number;
+        tiltMeanDeg: number;
+        raAngleDeg: number;
+        inclAmplitudeDeg: number;
+    };
+    fns: {
+        cyclesBetween: (yearA: number, yearB: number, divisorN: number) => (number | null);
+        analyticTropicalDays: (year: number) => (number | null);
+        meanHAtAgeMa: (tMa: number) => (number | null);
+        meanYearRealLodDays: (tMa: number) => (number | null);
+        eccentricityAt: (year: number) => number;
+        eccentricityRateAt: (year: number) => number;
+    };
+}): {
+    computeSolsticeJD: (year: number, type?: string) => number;
+    computeSolsticeYearLength: (year: number, type?: string) => number;
+    computeSolsticeRA: (year: number, type?: string) => number;
+    computeTropicalYearLength: (year: number) => number;
+};
+/** @type {Record<string, number>} */
+export const JOINT_LAMBDA: Record<string, number>;

package/types/cardinal/one-source-structure.d.cts

@@ -0,0 +1,35 @@
+/**
+ * @param {object} opts
+ * @param {(year: number) => {e: number, periOfDateDeg: number}} opts.sampleAt
+ *   the one-source history sampler (createDeepOrbitalHistory build().at,
+ *   year-keyed by the caller)
+ * @param {(year: number) => number} opts.tropicalYearSecondsAtYearFn
+ *   the movement's mean tropical year of date, SI SECONDS (see header)
+ */
+export function createCardinalStructure({ sampleAt, tropicalYearSecondsAtYearFn }: {
+    sampleAt: (year: number) => {
+        e: number;
+        periOfDateDeg: number;
+    };
+    tropicalYearSecondsAtYearFn: (year: number) => number;
+}): {
+    eocOffsetSeconds: (year: number, type: "VE" | "SS" | "AE" | "WS") => number;
+    yearLengthSeconds: (year: number, type: "VE" | "SS" | "AE" | "WS") => number;
+    spreadSeconds: (year: number) => {
+        VE: number;
+        SS: number;
+        AE: number;
+        WS: number;
+        meanSeconds: number;
+    };
+    anomalisticYearSeconds: (year: number) => number;
+};
+/**
+ * Equation of center in degrees, to e⁴ (the computeSunPositionFast family).
+ * @param {number} e eccentricity
+ * @param {number} meanAnomalyDeg
+ * @returns {number} degrees
+ */
+export function equationOfCenterDeg(e: number, meanAnomalyDeg: number): number;
+/** Cardinal longitudes, equinox of date. @type {Record<string, number>} */
+export const CARDINAL_LONGITUDE_DEG: Record<string, number>;

package/types/chain-cycles/index.d.cts

@@ -0,0 +1,33 @@
+export type PeriodSecondsAtAge = (tMa: number) => (number | null);
+/**
+ * @typedef {(tMa: number) => (number | null)} PeriodSecondsAtAge
+ */
+/**
+ * @param {{
+ *   ageAnchorYear: number,
+ *   tropicalYearSecondsAtAge: (tMa: number) => (number | null),
+ *   tropicalYearJ2000Seconds: number,
+ *   isDeepTime: () => boolean,
+ *   gridMinYear?: number,
+ *   gridMaxYear?: number,
+ *   gridStepYears?: number,
+ *   gridAnchorYear?: number,
+ *   maxCacheEntries?: number,
+ * }} deps — ageAnchorYear is the year whose age is 0 in the period
+ *   functions' t_Ma coordinate (startmodelYear = 2000.5, the certified
+ *   convention); tropicalYearJ2000Seconds feeds the snapshot branch;
+ *   isDeepTime is read PER CALL so the engine's runtime toggle works.
+ */
+export function createChainCycleIntegrator({ ageAnchorYear, tropicalYearSecondsAtAge, tropicalYearJ2000Seconds, isDeepTime, gridMinYear, gridMaxYear, gridStepYears, gridAnchorYear, maxCacheEntries, }: {
+    ageAnchorYear: number;
+    tropicalYearSecondsAtAge: (tMa: number) => (number | null);
+    tropicalYearJ2000Seconds: number;
+    isDeepTime: () => boolean;
+    gridMinYear?: number;
+    gridMaxYear?: number;
+    gridStepYears?: number;
+    gridAnchorYear?: number;
+    maxCacheEntries?: number;
+}): {
+    cyclesBetween: (periodFnSeconds: PeriodSecondsAtAge, yearA: number, yearB: number) => number | null;
+};

package/types/climate/l1-orbital.d.cts

@@ -0,0 +1,32 @@
+export type ClimateL1Regime = {
+    /**
+     * - 8H-lattice
+     * harmonics (n = cycles per 8H)
+     */
+    l1Terms: Array<{
+        n: number;
+        a: number;
+        b: number;
+    }>;
+    /**
+     * - the fit's y_std scale-back
+     */
+    yStdDenormalization: number;
+    /**
+     * - 8H in kyr (the fit's period base)
+     */
+    eightHKyr: number;
+};
+/**
+ * @typedef {Object} ClimateL1Regime
+ * @property {Array<{n: number, a: number, b: number}>} l1Terms - 8H-lattice
+ *   harmonics (n = cycles per 8H)
+ * @property {number} yStdDenormalization - the fit's y_std scale-back
+ * @property {number} eightHKyr - 8H in kyr (the fit's period base)
+ */
+/**
+ * @param {number} year - calendar year
+ * @param {ClimateL1Regime} regime
+ * @returns {number} L1 orbital δ¹⁸O contribution, ‰
+ */
+export function evalClimateL1OrbitalPermil(year: number, regime: ClimateL1Regime): number;