universal-physics-tensor 10.0.0 → 12.0.0

package/dist/diff/bridge-ast-gradient.js

@@ -1,69 +1,45 @@
 /**
- * Exact bridge-gradients via reverse-mode AD over the symbolic RHS AST.
+ * Exact bridge-gradients over the symbolic RHS AST.
  *
  * The catalog's plain-JS evaluators cannot be differentiated by AD (they run
  * raw `Math.*` arithmetic and return a number, which carries no tape; see
  * `bridge-gradient.ts`). But each bridge also carries a faithful symbolic
  * encoding of its RHS (`*_RHS: ExprNode`). This module lowers that scalar AST
- * through `@danielsimonjr/mathts-autograd`'s `TapedTensor` ops — binding the
- * chosen variable to a traced input and every other symbol to a constant tape
- * leaf — so `reverseGrad` returns the EXACT derivative (machine precision), with
- * the plain-JS evaluators left untouched (P8 Decision #1).
+ * with the MathTS scalar builder and differentiates it with MathTS
+ * `compileScalarGradient`: the chosen variable is the one parameter, and every
+ * other symbol is a constant. The result is the EXACT derivative (machine
+ * precision); the plain-JS evaluators stay untouched (P8 Decision #1).
  *
- * Scope: the dimensional scalar grammar is `symbol` + `op(+ − * / ^)` (the
- * transcendentals of a bridge are absorbed into typed-stub *symbols*, so they
- * appear as opaque constants here). A bridge encoded with a typed stub therefore
- * differentiates with respect to the stub, not the physics inside it — faithful,
- * fully-expanded encodings (e.g. BE-42 `ℏc³/(8πGM·k_B)`) differentiate exactly.
- * `^` exponents must be constant (the differentiation variable may not appear in
- * an exponent).
+ * Scope: the scalar grammar is `symbol` + `op(+ − * / ^)` + `transcendental` +
+ * `abs`. A bridge encoded with a typed stub differentiates with respect to the
+ * stub, not the physics inside it; fully-expanded encodings (e.g. BE-42
+ * `ℏc³/(8πGM·k_B)`) differentiate exactly. A `^` exponent must be constant: a
+ * UPT pre-check refuses the differentiation variable in an exponent before
+ * MathTS sees the tree.
  *
- * Loads `@danielsimonjr/mathts-autograd` at the call and throws
- * `EngineCapabilityError` when that import fails.
+ * A point where the value overflows gives `NaN` for the value and the
+ * gradient (MathTS marks the row invalid), not `±Infinity`.
  *
  * @module diff/bridge-ast-gradient
  */
+import { ScalarBuildError } from '@danielsimonjr/mathts-expression';
+import { compileScalarGradient } from '@danielsimonjr/mathts-functions';
+import { forEachScalarLeaf, isDecimalLiteral } from '../dimensional/ast-leaves.js';
 import { constantScope } from '../dimensional/symbolic-constants.js';
-import { EngineCapabilityError } from '../numerical/errors.js';
+import { toScalarNode } from '../dimensional/scalar-lowering.js';
 import { BRIDGE_RHS_BY_ID, parseBridgeId } from '../bridges/rhs-registry.js';
-import { GAUSS_LEGENDRE_16 } from '../numerical/quadrature.js';
-/** Map a transcendental fn name to the TapedTensor method that traces it. */
-function applyTranscendental(fn, t) {
-    switch (fn) {
-        case 'exp':
-            return t.exp();
-        case 'ln':
-            return t.log();
-        case 'log2':
-            return t.log2();
-        case 'log10':
-            return t.log10();
-        case 'sin':
-            return t.sin();
-        case 'cos':
-            return t.cos();
-        case 'tan':
-            return t.tan();
-        case 'sinh':
-            return t.sinh();
-        case 'cosh':
-            return t.cosh();
-        case 'tanh':
-            return t.tanh();
-    }
-}
 /**
  * Named physical constants the bridge encodings reference as bare symbols:
  * every registered spelling, from the constant registry, plus π and its
- * registered multiples, so a traced AST evaluates to the SAME number as the
+ * registered multiples, so the AST evaluates to the SAME number as the
  * numeric evaluator. Callers can override or extend via the `bindings` argument.
  */
 const NAMED_CONSTANTS = constantScope();
 /** Resolve a symbol's numeric value: caller bindings → named constants → numeric literal. */
 function resolveConstant(name, bindings) {
-    if (Object.prototype.hasOwnProperty.call(bindings, name))
+    if (Object.hasOwn(bindings, name))
         return bindings[name];
-    if (Object.prototype.hasOwnProperty.call(NAMED_CONSTANTS, name))
+    if (Object.hasOwn(NAMED_CONSTANTS, name))
         return NAMED_CONSTANTS[name];
     const asNumber = Number(name);
     if (name.trim() !== '' && Number.isFinite(asNumber))
@@ -75,9 +51,8 @@ function resolveConstant(name, bindings) {
  *
  * The exponent may contain scalar arithmetic over constants/bindings (for
  * example `-1/z`) as long as it is independent of the differentiation
- * variable. Variable exponents require a traced `pow(base, exponent)` op,
- * which the current MathTS tape surface does not expose, so they are rejected
- * explicitly rather than being silently detached from AD.
+ * variable. UPT keeps the constant-power contract, so the differentiation
+ * variable in an exponent is refused before MathTS reads the tree.
  */
 function resolveExponent(node, varName, bindings) {
     if (node.kind === 'symbol') {
@@ -103,125 +78,60 @@ function resolveExponent(node, varName, bindings) {
     throw new TypeError(`bridgeGradientAST: '^' exponent must be a constant scalar expression, got node kind '${node.kind}'.`);
 }
 /**
- * Differentiate a scalar bridge RHS AST with respect to one symbol via
- * reverse-mode AD. Every symbol other than `varName` is resolved to a constant
- * (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric literal); the
- * `bindings` must contain `varName` (its value sets the point of evaluation).
+ * Refuse the differentiation variable in any `^` exponent, and check that every
+ * exponent is a constant scalar expression. MathTS would differentiate a
+ * variable exponent; UPT keeps the constant-power contract.
+ */
+function checkExponents(node, varName, bindings) {
+    if (node.kind === 'op') {
+        if (node.op === '^' && node.args.length === 2)
+            resolveExponent(node.args[1], varName, bindings);
+        for (const arg of node.args)
+            checkExponents(arg, varName, bindings);
+    }
+    else if (node.kind === 'transcendental' || node.kind === 'abs') {
+        checkExponents(node.arg, varName, bindings);
+    }
+}
+/**
+ * Differentiate a scalar bridge RHS AST with respect to one symbol through
+ * MathTS `compileScalarGradient`. Every symbol other than `varName` is resolved
+ * to a constant (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric
+ * literal); the `bindings` must contain `varName` (its value sets the point of
+ * evaluation).
  *
+ * @throws TypeError when `varName` is not bound, a symbol cannot be resolved,
+ * `varName` appears in an exponent, or a node kind is outside the scalar grammar.
  * @public
  */
-export async function bridgeGradientAST(rhs, varName, bindings) {
-    if (!Object.prototype.hasOwnProperty.call(bindings, varName)) {
+export function bridgeGradientAST(rhs, varName, bindings) {
+    if (!Object.hasOwn(bindings, varName)) {
         throw new TypeError(`bridgeGradientAST: bindings must contain the differentiation variable '${varName}'.`);
     }
-    let autograd;
-    let tensorMod;
+    checkExponents(rhs, varName, bindings);
+    let lowered;
     try {
-        // The two modules are typed by the structural views above (the members
-        // this lowering calls: reverseGrad, TapedTensor, Tensor.fromNested …).
-        // The casts state that those members exist on the imported modules, which
-        // their own type declarations guarantee; the full MathTS types are not
-        // imported so this file compiles without the autograd types at hand.
-        autograd =
-            (await import('@danielsimonjr/mathts-autograd'));
-        tensorMod =
-            (await import('@danielsimonjr/mathts-tensor'));
+        lowered = toScalarNode(rhs);
     }
-    catch {
-        throw new EngineCapabilityError('mathts-autograd', 'reverseGrad');
+    catch (err) {
+        if (!(err instanceof ScalarBuildError))
+            throw err;
+        throw new TypeError(`bridgeGradientAST: unsupported node kind — ${err.message}. The differentiable grammar is ` +
+            `symbol + op(+ − * / ^) + transcendental + abs. Other encodings (tensor/curvature, integrals, ` +
+            `or physics hidden in a typed-stub symbol) are not exactly differentiable.`);
     }
-    const { reverseGrad, TapedTensor } = autograd;
-    const { Tensor } = tensorMod;
-    // Build the (traced var) → scalar function reverseGrad expects. `x` arrives as
-    // a TapedTensor; constants become extra tape leaves (their gradients are
-    // computed and ignored — only `x`'s gradient is returned).
-    const fn = (x) => {
-        const constLeaf = (v) => TapedTensor.fromTensorAsInput(Tensor.fromNested(v, []), x.tape);
-        // `boundVars` maps an integration variable name to its current (traced)
-        // quadrature point; it is checked BEFORE the diff-var / constants so an
-        // integration variable correctly shadows an outer symbol of the same name.
-        const walk = (node, boundVars) => {
-            if (node.kind === 'symbol') {
-                const bound = boundVars.get(node.name);
-                if (bound !== undefined)
-                    return bound;
-                return node.name === varName
-                    ? x
-                    : constLeaf(resolveConstant(node.name, bindings));
-            }
-            if (node.kind === 'op') {
-                switch (node.op) {
-                    case '+':
-                        return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.add(b));
-                    case '-': {
-                        const terms = node.args.map((a) => walk(a, boundVars));
-                        // Unary minus (0 − t); n-ary subtract folds left.
-                        return terms.length === 1
-                            ? constLeaf(0).sub(terms[0])
-                            : terms.reduce((a, b) => a.sub(b));
-                    }
-                    case '*':
-                        return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.mul(b));
-                    case '/':
-                        return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.divide(b));
-                    case '^':
-                        return walk(node.args[0], boundVars).pow(resolveExponent(node.args[1], varName, bindings));
-                    default:
-                        throw new TypeError(`bridgeGradientAST: unsupported operator '${node.op}'.`);
-                }
-            }
-            if (node.kind === 'transcendental') {
-                return applyTranscendental(node.fn, walk(node.arg, boundVars));
-            }
-            if (node.kind === 'abs') {
-                return walk(node.arg, boundVars).abs();
-            }
-            if (node.kind === 'integral') {
-                // Definite integral via 16-point Gauss–Legendre quadrature, built from
-                // traced ops so reverse-mode AD yields the gradient w.r.t. integrand
-                // parameters (Leibniz: ∫ ∂f/∂θ) and w.r.t. bounds (∂Q/∂b ≈ f(b)).
-                // NOTE: the gradient is EXACT for the quadrature, which APPROXIMATES the
-                // true integral for non-polynomial integrands (exact for constant /
-                // polynomial-degree ≤ 31 integrands).
-                if (!node.lower || !node.upper) {
-                    throw new TypeError(`bridgeGradientAST: an abstract (bound-less) integral is not differentiable; ` +
-                        `supply lower/upper bounds for a definite integral.`);
-                }
-                if (node.over.kind !== 'symbol') {
-                    throw new TypeError(`bridgeGradientAST: integral 'over' must be a symbol.`);
-                }
-                const overName = node.over.name;
-                if (overName === varName) {
-                    throw new TypeError(`bridgeGradientAST: cannot differentiate w.r.t. the integration variable '${overName}'.`);
-                }
-                const lo = walk(node.lower, boundVars);
-                const hi = walk(node.upper, boundVars);
-                const half = hi.sub(lo).scale(0.5); // (b − a)/2
-                const mid = lo.add(hi).scale(0.5); // (a + b)/2
-                let sum = null;
-                for (const gl of GAUSS_LEGENDRE_16) {
-                    const xPoint = mid.add(half.scale(gl.node)); // (b−a)/2·ξ + (a+b)/2
-                    const env = new Map(boundVars);
-                    env.set(overName, xPoint);
-                    const term = walk(node.integrand, env).scale(gl.weight);
-                    sum = sum === null ? term : sum.add(term);
-                }
-                // GAUSS_LEGENDRE_16 is non-empty, so `sum` is set.
-                return half.mul(sum);
-            }
-            throw new TypeError(`bridgeGradientAST: unsupported node kind '${node.kind}' — the differentiable ` +
-                `grammar is symbol + op(+ − * / ^) + transcendental + abs + definite integral. ` +
-                `Other encodings (tensor/curvature, bound-less integrals, or physics hidden in ` +
-                `a typed-stub symbol) are not exactly differentiable.`);
-        };
-        return walk(rhs, new Map());
-    };
-    const xLeaf = Tensor.fromNested(bindings[varName], []);
-    const { value, gradient } = reverseGrad(fn, xLeaf);
-    return {
-        value: value.toNested(),
-        gradient: gradient.toNested(),
-    };
+    const constants = {};
+    forEachScalarLeaf(rhs, (leaf) => {
+        if (leaf.name === varName)
+            return;
+        // A literal spelling stays MathTS's literal unless the caller bound that name.
+        if (isDecimalLiteral(leaf.name) && !Object.hasOwn(bindings, leaf.name))
+            return;
+        constants[leaf.name] = resolveConstant(leaf.name, bindings);
+    }, { transcendental: true, abs: true });
+    const compiled = compileScalarGradient(lowered, { variables: [], parameters: [varName], constants });
+    const { values, grad } = compiled.evaluate([], [bindings[varName]]);
+    return { value: values[0], gradient: grad[0] };
 }
 /**
  * Convenience wrapper around {@link bridgeGradientAST} that looks the RHS AST up
@@ -229,7 +139,7 @@ export async function bridgeGradientAST(rhs, varName, bindings) {
  *
  * Throws if the id has no encoded RHS in {@link BRIDGE_RHS_BY_ID} (e.g. BE-51/52,
  * which are closed-form evaluators without an AST). If the bridge's RHS is not in
- * the differentiable scalar grammar (a tensor/integral/curvature encoding), the
+ * the differentiable scalar grammar (a tensor, integral or curvature encoding), the
  * delegated `bridgeGradientAST` throws the "unsupported node kind" error — use
  * {@link astDifferentiableBridgeIds} to discover which ids are AD-eligible.
  *
@@ -244,7 +154,7 @@ export function bridgeGradientASTById(bridgeId, varName, bindings) {
     }
     return bridgeGradientAST(rhs, varName, bindings);
 }
-/** Whether an AST consists solely of the differentiable scalar grammar (symbol + op(+ − * / ^)). */
+/** Whether an AST consists solely of the differentiable scalar grammar (symbol + op(+ − * / ^) + transcendental + abs). */
 function isDifferentiableScalarAST(node) {
     if (node.kind === 'symbol')
         return true;
@@ -253,24 +163,16 @@ function isDifferentiableScalarAST(node) {
             return false;
         return node.args.every(isDifferentiableScalarAST);
     }
-    if (node.kind === 'transcendental')
+    if (node.kind === 'transcendental' || node.kind === 'abs')
         return isDifferentiableScalarAST(node.arg);
-    if (node.kind === 'abs')
-        return isDifferentiableScalarAST(node.arg);
-    if (node.kind === 'integral') {
-        return (!!node.lower &&
-            !!node.upper &&
-            node.over.kind === 'symbol' &&
-            isDifferentiableScalarAST(node.integrand) &&
-            isDifferentiableScalarAST(node.lower) &&
-            isDifferentiableScalarAST(node.upper));
-    }
     return false;
 }
 /**
  * The catalog bridge ids whose encoded RHS lies entirely in the differentiable
- * scalar grammar — i.e. those `bridgeGradientASTById` can differentiate exactly.
- * Bridges encoded with tensor/integral/curvature nodes (or whose physics is
+ * scalar grammar. `bridgeGradientASTById` differentiates each of them exactly
+ * with respect to any variable that is not in an exponent; a variable in an
+ * exponent is refused (`checkExponents`).
+ * Bridges encoded with tensor, integral or curvature nodes (or whose physics is
  * hidden behind a typed-stub symbol) are excluded from EXACT differentiation
  * (a stub still differentiates w.r.t. the stub symbol, but not the physics
  * inside it). Returned sorted ascending.

package/dist/diff/bridge-ast-gradient.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-ast-gradient.js","sourceRoot":"","sources":["../../src/diff/bridge-ast-gradient.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Exact bridge-gradients via reverse-mode AD over the symbolic RHS AST.\n *\n * The catalog's plain-JS evaluators cannot be differentiated by AD (they run\n * raw `Math.*` arithmetic and return a number, which carries no tape; see\n * `bridge-gradient.ts`). But each bridge also carries a faithful symbolic\n * encoding of its RHS (`*_RHS: ExprNode`). This module lowers that scalar AST\n * through `@danielsimonjr/mathts-autograd`'s `TapedTensor` ops — binding the\n * chosen variable to a traced input and every other symbol to a constant tape\n * leaf — so `reverseGrad` returns the EXACT derivative (machine precision), with\n * the plain-JS evaluators left untouched (P8 Decision #1).\n *\n * Scope: the dimensional scalar grammar is `symbol` + `op(+ − * / ^)` (the\n * transcendentals of a bridge are absorbed into typed-stub *symbols*, so they\n * appear as opaque constants here). A bridge encoded with a typed stub therefore\n * differentiates with respect to the stub, not the physics inside it — faithful,\n * fully-expanded encodings (e.g. BE-42 `ℏc³/(8πGM·k_B)`) differentiate exactly.\n * `^` exponents must be constant (the differentiation variable may not appear in\n * an exponent).\n *\n * Loads `@danielsimonjr/mathts-autograd` at the call and throws\n * `EngineCapabilityError` when that import fails.\n *\n * @module diff/bridge-ast-gradient\n */\n\nimport type { ExprNode, TranscendentalFn } from '../dimensional/validator.js';\nimport { constantScope } from '../dimensional/symbolic-constants.js';\nimport { EngineCapabilityError } from '../numerical/errors.js';\nimport { BRIDGE_RHS_BY_ID, parseBridgeId } from '../bridges/rhs-registry.js';\nimport { GAUSS_LEGENDRE_16 } from '../numerical/quadrature.js';\n\n/**\n * Result of {@link bridgeGradientAST}: the bridge's scalar `value` at the\n * supplied point and the exact `gradient` d(value)/d(varName).\n *\n * @public\n */\nexport interface ASTGradientResult {\n  readonly value: number;\n  readonly gradient: number;\n}\n\n// --- Structural views of the autograd/tensor packages (required dependencies; the\n// dynamic import keeps the AD path off the module's load, and its result is narrowed\n// to the call-site shape). ---\n\ntype TapeHandle = unknown;\n\ninterface TapedScalar {\n  readonly tape: TapeHandle;\n  add(o: TapedScalar): TapedScalar;\n  sub(o: TapedScalar): TapedScalar;\n  mul(o: TapedScalar): TapedScalar;\n  divide(o: TapedScalar): TapedScalar;\n  scale(k: number): TapedScalar;\n  pow(k: number): TapedScalar;\n  exp(): TapedScalar;\n  log(): TapedScalar;\n  log2(): TapedScalar;\n  log10(): TapedScalar;\n  sin(): TapedScalar;\n  cos(): TapedScalar;\n  tan(): TapedScalar;\n  sinh(): TapedScalar;\n  cosh(): TapedScalar;\n  tanh(): TapedScalar;\n  abs(): TapedScalar;\n}\n\n/** Map a transcendental fn name to the TapedTensor method that traces it. */\nfunction applyTranscendental(fn: TranscendentalFn, t: TapedScalar): TapedScalar {\n  switch (fn) {\n    case 'exp':\n      return t.exp();\n    case 'ln':\n      return t.log();\n    case 'log2':\n      return t.log2();\n    case 'log10':\n      return t.log10();\n    case 'sin':\n      return t.sin();\n    case 'cos':\n      return t.cos();\n    case 'tan':\n      return t.tan();\n    case 'sinh':\n      return t.sinh();\n    case 'cosh':\n      return t.cosh();\n    case 'tanh':\n      return t.tanh();\n  }\n}\n\ninterface MathTSTensorLike {\n  toNested(): unknown;\n}\n\ninterface AutogradModuleLike {\n  reverseGrad(\n    fn: (x: TapedScalar) => TapedScalar,\n    x: MathTSTensorLike,\n    cotangent?: MathTSTensorLike,\n  ): { value: MathTSTensorLike; gradient: MathTSTensorLike };\n  TapedTensor: {\n    fromTensorAsInput(t: MathTSTensorLike, tape: TapeHandle): TapedScalar;\n  };\n}\n\ninterface TensorModuleLike {\n  Tensor: { fromNested(data: number, shape: number[]): MathTSTensorLike };\n}\n\n/**\n * Named physical constants the bridge encodings reference as bare symbols:\n * every registered spelling, from the constant registry, plus π and its\n * registered multiples, so a traced AST evaluates to the SAME number as the\n * numeric evaluator. Callers can override or extend via the `bindings` argument.\n */\nconst NAMED_CONSTANTS: Readonly<Record<string, number>> = constantScope();\n\n/** Resolve a symbol's numeric value: caller bindings → named constants → numeric literal. */\nfunction resolveConstant(\n  name: string,\n  bindings: Record<string, number>,\n): number {\n  if (Object.prototype.hasOwnProperty.call(bindings, name))\n    return bindings[name];\n  if (Object.prototype.hasOwnProperty.call(NAMED_CONSTANTS, name))\n    return NAMED_CONSTANTS[name];\n  const asNumber = Number(name);\n  if (name.trim() !== '' && Number.isFinite(asNumber)) return asNumber;\n  throw new TypeError(\n    `bridgeGradientAST: unknown symbol '${name}' — not a binding, a named constant ` +\n      `(${Object.keys(NAMED_CONSTANTS).join(', ')}), or a numeric literal. Supply it in bindings.`,\n  );\n}\n\n/** Resolve a `^` exponent to a numeric constant expression.\n *\n * The exponent may contain scalar arithmetic over constants/bindings (for\n * example `-1/z`) as long as it is independent of the differentiation\n * variable. Variable exponents require a traced `pow(base, exponent)` op,\n * which the current MathTS tape surface does not expose, so they are rejected\n * explicitly rather than being silently detached from AD.\n */\nfunction resolveExponent(\n  node: ExprNode,\n  varName: string,\n  bindings: Record<string, number>,\n): number {\n  if (node.kind === 'symbol') {\n    if (node.name === varName) {\n      throw new TypeError(\n        `bridgeGradientAST: differentiation variable '${varName}' appears as an exponent — ` +\n          `variable exponents are not supported (only constant powers).`,\n      );\n    }\n    return resolveConstant(node.name, bindings);\n  }\n  if (node.kind === 'op') {\n    const values = node.args.map((arg) => resolveExponent(arg, varName, bindings));\n    if (values.length === 0) {\n      throw new TypeError(`bridgeGradientAST: '${node.op}' exponent expression has no operands.`);\n    }\n    switch (node.op) {\n      case '+': return values.reduce((a, b) => a + b);\n      case '-': return values.length === 1 ? -values[0] : values.slice(1).reduce((a, b) => a - b, values[0]);\n      case '*': return values.reduce((a, b) => a * b);\n      case '/': return values.slice(1).reduce((a, b) => a / b, values[0]);\n      case '^': return values.slice(1).reduce((a, b) => a ** b, values[0]);\n    }\n  }\n  throw new TypeError(\n    `bridgeGradientAST: '^' exponent must be a constant scalar expression, got node kind '${node.kind}'.`,\n  );\n}\n\n/**\n * Differentiate a scalar bridge RHS AST with respect to one symbol via\n * reverse-mode AD. Every symbol other than `varName` is resolved to a constant\n * (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric literal); the\n * `bindings` must contain `varName` (its value sets the point of evaluation).\n *\n * @public\n */\nexport async function bridgeGradientAST(\n  rhs: ExprNode,\n  varName: string,\n  bindings: Record<string, number>,\n): Promise<ASTGradientResult> {\n  if (!Object.prototype.hasOwnProperty.call(bindings, varName)) {\n    throw new TypeError(\n      `bridgeGradientAST: bindings must contain the differentiation variable '${varName}'.`,\n    );\n  }\n\n  let autograd: AutogradModuleLike;\n  let tensorMod: TensorModuleLike;\n  try {\n    // The two modules are typed by the structural views above (the members\n    // this lowering calls: reverseGrad, TapedTensor, Tensor.fromNested …).\n    // The casts state that those members exist on the imported modules, which\n    // their own type declarations guarantee; the full MathTS types are not\n    // imported so this file compiles without the autograd types at hand.\n    autograd =\n      (await import('@danielsimonjr/mathts-autograd')) as unknown as AutogradModuleLike;\n    tensorMod =\n      (await import('@danielsimonjr/mathts-tensor')) as unknown as TensorModuleLike;\n  } catch {\n    throw new EngineCapabilityError('mathts-autograd', 'reverseGrad');\n  }\n  const { reverseGrad, TapedTensor } = autograd;\n  const { Tensor } = tensorMod;\n\n  // Build the (traced var) → scalar function reverseGrad expects. `x` arrives as\n  // a TapedTensor; constants become extra tape leaves (their gradients are\n  // computed and ignored — only `x`'s gradient is returned).\n  const fn = (x: TapedScalar): TapedScalar => {\n    const constLeaf = (v: number): TapedScalar =>\n      TapedTensor.fromTensorAsInput(Tensor.fromNested(v, []), x.tape);\n\n    // `boundVars` maps an integration variable name to its current (traced)\n    // quadrature point; it is checked BEFORE the diff-var / constants so an\n    // integration variable correctly shadows an outer symbol of the same name.\n    const walk = (node: ExprNode, boundVars: ReadonlyMap<string, TapedScalar>): TapedScalar => {\n      if (node.kind === 'symbol') {\n        const bound = boundVars.get(node.name);\n        if (bound !== undefined) return bound;\n        return node.name === varName\n          ? x\n          : constLeaf(resolveConstant(node.name, bindings));\n      }\n      if (node.kind === 'op') {\n        switch (node.op) {\n          case '+':\n            return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.add(b));\n          case '-': {\n            const terms = node.args.map((a) => walk(a, boundVars));\n            // Unary minus (0 − t); n-ary subtract folds left.\n            return terms.length === 1\n              ? constLeaf(0).sub(terms[0])\n              : terms.reduce((a, b) => a.sub(b));\n          }\n          case '*':\n            return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.mul(b));\n          case '/':\n            return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.divide(b));\n          case '^':\n            return walk(node.args[0], boundVars).pow(\n              resolveExponent(node.args[1], varName, bindings),\n            );\n          default:\n            throw new TypeError(\n              `bridgeGradientAST: unsupported operator '${node.op}'.`,\n            );\n        }\n      }\n      if (node.kind === 'transcendental') {\n        return applyTranscendental(node.fn, walk(node.arg, boundVars));\n      }\n      if (node.kind === 'abs') {\n        return walk(node.arg, boundVars).abs();\n      }\n      if (node.kind === 'integral') {\n        // Definite integral via 16-point Gauss–Legendre quadrature, built from\n        // traced ops so reverse-mode AD yields the gradient w.r.t. integrand\n        // parameters (Leibniz: ∫ ∂f/∂θ) and w.r.t. bounds (∂Q/∂b ≈ f(b)).\n        // NOTE: the gradient is EXACT for the quadrature, which APPROXIMATES the\n        // true integral for non-polynomial integrands (exact for constant /\n        // polynomial-degree ≤ 31 integrands).\n        if (!node.lower || !node.upper) {\n          throw new TypeError(\n            `bridgeGradientAST: an abstract (bound-less) integral is not differentiable; ` +\n              `supply lower/upper bounds for a definite integral.`,\n          );\n        }\n        if (node.over.kind !== 'symbol') {\n          throw new TypeError(`bridgeGradientAST: integral 'over' must be a symbol.`);\n        }\n        const overName = node.over.name;\n        if (overName === varName) {\n          throw new TypeError(\n            `bridgeGradientAST: cannot differentiate w.r.t. the integration variable '${overName}'.`,\n          );\n        }\n        const lo = walk(node.lower, boundVars);\n        const hi = walk(node.upper, boundVars);\n        const half = hi.sub(lo).scale(0.5); // (b − a)/2\n        const mid = lo.add(hi).scale(0.5); // (a + b)/2\n        let sum: TapedScalar | null = null;\n        for (const gl of GAUSS_LEGENDRE_16) {\n          const xPoint = mid.add(half.scale(gl.node)); // (b−a)/2·ξ + (a+b)/2\n          const env = new Map(boundVars);\n          env.set(overName, xPoint);\n          const term = walk(node.integrand, env).scale(gl.weight);\n          sum = sum === null ? term : sum.add(term);\n        }\n        // GAUSS_LEGENDRE_16 is non-empty, so `sum` is set.\n        return half.mul(sum as TapedScalar);\n      }\n      throw new TypeError(\n        `bridgeGradientAST: unsupported node kind '${node.kind}' — the differentiable ` +\n          `grammar is symbol + op(+ − * / ^) + transcendental + abs + definite integral. ` +\n          `Other encodings (tensor/curvature, bound-less integrals, or physics hidden in ` +\n          `a typed-stub symbol) are not exactly differentiable.`,\n      );\n    };\n\n    return walk(rhs, new Map());\n  };\n\n  const xLeaf = Tensor.fromNested(bindings[varName], []);\n  const { value, gradient } = reverseGrad(fn, xLeaf);\n  return {\n    value: value.toNested() as number,\n    gradient: gradient.toNested() as number,\n  };\n}\n\n/**\n * Convenience wrapper around {@link bridgeGradientAST} that looks the RHS AST up\n * by catalog bridge id. `bridgeId` accepts a number, `'42'`, or `'BE-42'`.\n *\n * Throws if the id has no encoded RHS in {@link BRIDGE_RHS_BY_ID} (e.g. BE-51/52,\n * which are closed-form evaluators without an AST). If the bridge's RHS is not in\n * the differentiable scalar grammar (a tensor/integral/curvature encoding), the\n * delegated `bridgeGradientAST` throws the \"unsupported node kind\" error — use\n * {@link astDifferentiableBridgeIds} to discover which ids are AD-eligible.\n *\n * @public\n */\nexport function bridgeGradientASTById(\n  bridgeId: number | string,\n  varName: string,\n  bindings: Record<string, number>\n): Promise<ASTGradientResult> {\n  const id = parseBridgeId(bridgeId);\n  const rhs = BRIDGE_RHS_BY_ID.get(id);\n  if (rhs === undefined) {\n    throw new TypeError(\n      `bridgeGradientASTById: BE-${id} has no encoded RHS AST in the registry ` +\n        `(BE-51/52 are closed-form; ${BRIDGE_RHS_BY_ID.size} bridges have an encoded AST).`\n    );\n  }\n  return bridgeGradientAST(rhs, varName, bindings);\n}\n\n/** Whether an AST consists solely of the differentiable scalar grammar (symbol + op(+ − * / ^)). */\nfunction isDifferentiableScalarAST(node: ExprNode): boolean {\n  if (node.kind === 'symbol') return true;\n  if (node.kind === 'op') {\n    if (!['+', '-', '*', '/', '^'].includes(node.op)) return false;\n    return node.args.every(isDifferentiableScalarAST);\n  }\n  if (node.kind === 'transcendental') return isDifferentiableScalarAST(node.arg);\n  if (node.kind === 'abs') return isDifferentiableScalarAST(node.arg);\n  if (node.kind === 'integral') {\n    return (\n      !!node.lower &&\n      !!node.upper &&\n      node.over.kind === 'symbol' &&\n      isDifferentiableScalarAST(node.integrand) &&\n      isDifferentiableScalarAST(node.lower) &&\n      isDifferentiableScalarAST(node.upper)\n    );\n  }\n  return false;\n}\n\n/**\n * The catalog bridge ids whose encoded RHS lies entirely in the differentiable\n * scalar grammar — i.e. those `bridgeGradientASTById` can differentiate exactly.\n * Bridges encoded with tensor/integral/curvature nodes (or whose physics is\n * hidden behind a typed-stub symbol) are excluded from EXACT differentiation\n * (a stub still differentiates w.r.t. the stub symbol, but not the physics\n * inside it). Returned sorted ascending.\n *\n * @public\n */\nexport function astDifferentiableBridgeIds(): number[] {\n  const ids: number[] = [];\n  for (const [id, rhs] of BRIDGE_RHS_BY_ID) {\n    if (isDifferentiableScalarAST(rhs)) ids.push(id);\n  }\n  return ids.sort((a, b) => a - b);\n}\n"]}
+{"version":3,"file":"bridge-ast-gradient.js","sourceRoot":"","sources":["../../src/diff/bridge-ast-gradient.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Exact bridge-gradients over the symbolic RHS AST.\n *\n * The catalog's plain-JS evaluators cannot be differentiated by AD (they run\n * raw `Math.*` arithmetic and return a number, which carries no tape; see\n * `bridge-gradient.ts`). But each bridge also carries a faithful symbolic\n * encoding of its RHS (`*_RHS: ExprNode`). This module lowers that scalar AST\n * with the MathTS scalar builder and differentiates it with MathTS\n * `compileScalarGradient`: the chosen variable is the one parameter, and every\n * other symbol is a constant. The result is the EXACT derivative (machine\n * precision); the plain-JS evaluators stay untouched (P8 Decision #1).\n *\n * Scope: the scalar grammar is `symbol` + `op(+ − * / ^)` + `transcendental` +\n * `abs`. A bridge encoded with a typed stub differentiates with respect to the\n * stub, not the physics inside it; fully-expanded encodings (e.g. BE-42\n * `ℏc³/(8πGM·k_B)`) differentiate exactly. A `^` exponent must be constant: a\n * UPT pre-check refuses the differentiation variable in an exponent before\n * MathTS sees the tree.\n *\n * A point where the value overflows gives `NaN` for the value and the\n * gradient (MathTS marks the row invalid), not `±Infinity`.\n *\n * @module diff/bridge-ast-gradient\n */\n\nimport { ScalarBuildError } from '@danielsimonjr/mathts-expression';\nimport { compileScalarGradient } from '@danielsimonjr/mathts-functions';\nimport type { ExprNode } from '../dimensional/validator.js';\nimport { forEachScalarLeaf, isDecimalLiteral } from '../dimensional/ast-leaves.js';\nimport { constantScope } from '../dimensional/symbolic-constants.js';\nimport { toScalarNode } from '../dimensional/scalar-lowering.js';\nimport { BRIDGE_RHS_BY_ID, parseBridgeId } from '../bridges/rhs-registry.js';\n\n/**\n * Result of {@link bridgeGradientAST}: the bridge's scalar `value` at the\n * supplied point and the exact `gradient` d(value)/d(varName).\n *\n * @public\n */\nexport interface ASTGradientResult {\n  readonly value: number;\n  readonly gradient: number;\n}\n\n/**\n * Named physical constants the bridge encodings reference as bare symbols:\n * every registered spelling, from the constant registry, plus π and its\n * registered multiples, so the AST evaluates to the SAME number as the\n * numeric evaluator. Callers can override or extend via the `bindings` argument.\n */\nconst NAMED_CONSTANTS: Readonly<Record<string, number>> = constantScope();\n\n/** Resolve a symbol's numeric value: caller bindings → named constants → numeric literal. */\nfunction resolveConstant(\n  name: string,\n  bindings: Record<string, number>,\n): number {\n  if (Object.hasOwn(bindings, name))\n    return bindings[name];\n  if (Object.hasOwn(NAMED_CONSTANTS, name))\n    return NAMED_CONSTANTS[name];\n  const asNumber = Number(name);\n  if (name.trim() !== '' && Number.isFinite(asNumber)) return asNumber;\n  throw new TypeError(\n    `bridgeGradientAST: unknown symbol '${name}' — not a binding, a named constant ` +\n      `(${Object.keys(NAMED_CONSTANTS).join(', ')}), or a numeric literal. Supply it in bindings.`,\n  );\n}\n\n/** Resolve a `^` exponent to a numeric constant expression.\n *\n * The exponent may contain scalar arithmetic over constants/bindings (for\n * example `-1/z`) as long as it is independent of the differentiation\n * variable. UPT keeps the constant-power contract, so the differentiation\n * variable in an exponent is refused before MathTS reads the tree.\n */\nfunction resolveExponent(\n  node: ExprNode,\n  varName: string,\n  bindings: Record<string, number>,\n): number {\n  if (node.kind === 'symbol') {\n    if (node.name === varName) {\n      throw new TypeError(\n        `bridgeGradientAST: differentiation variable '${varName}' appears as an exponent — ` +\n          `variable exponents are not supported (only constant powers).`,\n      );\n    }\n    return resolveConstant(node.name, bindings);\n  }\n  if (node.kind === 'op') {\n    const values = node.args.map((arg) => resolveExponent(arg, varName, bindings));\n    if (values.length === 0) {\n      throw new TypeError(`bridgeGradientAST: '${node.op}' exponent expression has no operands.`);\n    }\n    switch (node.op) {\n      case '+': return values.reduce((a, b) => a + b);\n      case '-': return values.length === 1 ? -values[0] : values.slice(1).reduce((a, b) => a - b, values[0]);\n      case '*': return values.reduce((a, b) => a * b);\n      case '/': return values.slice(1).reduce((a, b) => a / b, values[0]);\n      case '^': return values.slice(1).reduce((a, b) => a ** b, values[0]);\n    }\n  }\n  throw new TypeError(\n    `bridgeGradientAST: '^' exponent must be a constant scalar expression, got node kind '${node.kind}'.`,\n  );\n}\n\n/**\n * Refuse the differentiation variable in any `^` exponent, and check that every\n * exponent is a constant scalar expression. MathTS would differentiate a\n * variable exponent; UPT keeps the constant-power contract.\n */\nfunction checkExponents(node: ExprNode, varName: string, bindings: Record<string, number>): void {\n  if (node.kind === 'op') {\n    if (node.op === '^' && node.args.length === 2) resolveExponent(node.args[1], varName, bindings);\n    for (const arg of node.args) checkExponents(arg, varName, bindings);\n  } else if (node.kind === 'transcendental' || node.kind === 'abs') {\n    checkExponents(node.arg, varName, bindings);\n  }\n}\n\n/**\n * Differentiate a scalar bridge RHS AST with respect to one symbol through\n * MathTS `compileScalarGradient`. Every symbol other than `varName` is resolved\n * to a constant (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric\n * literal); the `bindings` must contain `varName` (its value sets the point of\n * evaluation).\n *\n * @throws TypeError when `varName` is not bound, a symbol cannot be resolved,\n * `varName` appears in an exponent, or a node kind is outside the scalar grammar.\n * @public\n */\nexport function bridgeGradientAST(\n  rhs: ExprNode,\n  varName: string,\n  bindings: Record<string, number>,\n): ASTGradientResult {\n  if (!Object.hasOwn(bindings, varName)) {\n    throw new TypeError(\n      `bridgeGradientAST: bindings must contain the differentiation variable '${varName}'.`,\n    );\n  }\n  checkExponents(rhs, varName, bindings);\n\n  let lowered: ReturnType<typeof toScalarNode>;\n  try {\n    lowered = toScalarNode(rhs);\n  } catch (err) {\n    if (!(err instanceof ScalarBuildError)) throw err;\n    throw new TypeError(\n      `bridgeGradientAST: unsupported node kind — ${err.message}. The differentiable grammar is ` +\n        `symbol + op(+ − * / ^) + transcendental + abs. Other encodings (tensor/curvature, integrals, ` +\n        `or physics hidden in a typed-stub symbol) are not exactly differentiable.`,\n    );  }\n\n  const constants: Record<string, number> = {};\n  forEachScalarLeaf(\n    rhs,\n    (leaf) => {\n      if (leaf.name === varName) return;\n      // A literal spelling stays MathTS's literal unless the caller bound that name.\n      if (isDecimalLiteral(leaf.name) && !Object.hasOwn(bindings, leaf.name)) return;\n      constants[leaf.name] = resolveConstant(leaf.name, bindings);\n    },\n    { transcendental: true, abs: true },\n  );\n\n  const compiled = compileScalarGradient(lowered, { variables: [], parameters: [varName], constants });\n  const { values, grad } = compiled.evaluate([], [bindings[varName]]);\n  return { value: values[0]!, gradient: grad[0]! };\n}\n\n/**\n * Convenience wrapper around {@link bridgeGradientAST} that looks the RHS AST up\n * by catalog bridge id. `bridgeId` accepts a number, `'42'`, or `'BE-42'`.\n *\n * Throws if the id has no encoded RHS in {@link BRIDGE_RHS_BY_ID} (e.g. BE-51/52,\n * which are closed-form evaluators without an AST). If the bridge's RHS is not in\n * the differentiable scalar grammar (a tensor, integral or curvature encoding), the\n * delegated `bridgeGradientAST` throws the \"unsupported node kind\" error — use\n * {@link astDifferentiableBridgeIds} to discover which ids are AD-eligible.\n *\n * @public\n */\nexport function bridgeGradientASTById(\n  bridgeId: number | string,\n  varName: string,\n  bindings: Record<string, number>\n): ASTGradientResult {\n  const id = parseBridgeId(bridgeId);\n  const rhs = BRIDGE_RHS_BY_ID.get(id);\n  if (rhs === undefined) {\n    throw new TypeError(\n      `bridgeGradientASTById: BE-${id} has no encoded RHS AST in the registry ` +\n        `(BE-51/52 are closed-form; ${BRIDGE_RHS_BY_ID.size} bridges have an encoded AST).`\n    );\n  }\n  return bridgeGradientAST(rhs, varName, bindings);\n}\n\n/** Whether an AST consists solely of the differentiable scalar grammar (symbol + op(+ − * / ^) + transcendental + abs). */\nfunction isDifferentiableScalarAST(node: ExprNode): boolean {\n  if (node.kind === 'symbol') return true;\n  if (node.kind === 'op') {\n    if (!['+', '-', '*', '/', '^'].includes(node.op)) return false;\n    return node.args.every(isDifferentiableScalarAST);\n  }\n  if (node.kind === 'transcendental' || node.kind === 'abs') return isDifferentiableScalarAST(node.arg);\n  return false;\n}\n\n/**\n * The catalog bridge ids whose encoded RHS lies entirely in the differentiable\n * scalar grammar. `bridgeGradientASTById` differentiates each of them exactly\n * with respect to any variable that is not in an exponent; a variable in an\n * exponent is refused (`checkExponents`).\n * Bridges encoded with tensor, integral or curvature nodes (or whose physics is\n * hidden behind a typed-stub symbol) are excluded from EXACT differentiation\n * (a stub still differentiates w.r.t. the stub symbol, but not the physics\n * inside it). Returned sorted ascending.\n *\n * @public\n */\nexport function astDifferentiableBridgeIds(): number[] {\n  const ids: number[] = [];\n  for (const [id, rhs] of BRIDGE_RHS_BY_ID) {\n    if (isDifferentiableScalarAST(rhs)) ids.push(id);\n  }\n  return ids.sort((a, b) => a - b);\n}\n"]}

package/dist/diff/bridge-gradient.d.ts

@@ -46,6 +46,14 @@ export interface BridgeDiffSpec<Input> {
     readonly defaults: Partial<Input>;
     /** The bridge's scalar evaluator. */
     readonly evaluate: (input: Input) => number;
+    /**
+     * The smallest magnitude the relative step is taken against, per parameter:
+     * for `|x| < floor` the step is `floor·relStep`. A parameter that is zero at
+     * a point of interest (an eccentricity on a circular orbit) needs its scale
+     * stated here, because a relative step at zero is no step. A parameter not
+     * named here has no floor: the step is `|x|·relStep`, and `x = 0` is refused.
+     */
+    readonly stepFloors?: Readonly<Partial<Record<keyof Input & string, number>>>;
 }
 /**
  * Result of {@link bridgeGradientNumerical}: the bridge's scalar `value`
@@ -63,12 +71,17 @@ export interface BridgeNumericalGradientResult {
  * way to differentiate the catalog's plain-JS closed forms without
  * rewriting them. Needs no engine and is synchronous.
  *
- * For each differentiable param with value `x` it uses a relative step
- * `h = max(|x|, 1)·cbrt(eps)` and the ACTUAL representable denominator
- * `dx = (x + h) − (x − h)` — so the perturbation survives floating-point
- * rounding even at astrophysical scales (e.g. `M ≈ 2e30 kg`). The supplied
- * `params` must contain every key in `spec.paramNames`; non-differentiable
- * fields come from `spec.defaults`.
+ * For each differentiable param with value `x` it uses the relative step
+ * `h = max(|x|, floor)·cbrt(eps)`, where `floor` is the spec's
+ * {@link BridgeDiffSpec.stepFloors} entry for that param (0 when the spec
+ * states none), and the ACTUAL representable denominator
+ * `dx = (x + h) − (x − h)` (`numerical/finite-difference`) — so the
+ * perturbation survives floating-point rounding at astrophysical scales
+ * (`M ≈ 2e30 kg`) and stays relative at atomic ones (a charge of 1.6e-19
+ * takes a step of 1e-24, not the 6e-6 an absolute floor of 1 gave). A param
+ * at exactly 0 with no stated floor is refused with a `RangeError`: there is
+ * no scale to step by. The supplied `params` must contain every key in
+ * `spec.paramNames`; non-differentiable fields come from `spec.defaults`.
  *
  * @public
  */

package/dist/diff/bridge-gradient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-gradient.d.ts","sourceRoot":"","sources":["../../src/diff/bridge-gradient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK;IACnC,2GAA2G;IAC3G,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAClC,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAC3C,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnC,6BAA6B,CA6C/B"}
+{"version":3,"file":"bridge-gradient.d.ts","sourceRoot":"","sources":["../../src/diff/bridge-gradient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK;IACnC,2GAA2G;IAC3G,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAClC,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CAC/E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAUD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAC3C,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnC,6BAA6B,CAiD/B"}

package/dist/diff/bridge-gradient.js

@@ -18,6 +18,7 @@
  *
  * @module diff/bridge-gradient
  */
+import { centralPartial } from '../numerical/finite-difference.js';
 /**
  * Relative step for central differences: `cbrt(eps)` balances the `O(h²)`
  * truncation error against the `O(eps/h)` round-off error (the central-diff
@@ -30,12 +31,17 @@ const CENTRAL_DIFF_REL_STEP = Math.cbrt(Number.EPSILON); // ≈ 6.06e-6
  * way to differentiate the catalog's plain-JS closed forms without
  * rewriting them. Needs no engine and is synchronous.
  *
- * For each differentiable param with value `x` it uses a relative step
- * `h = max(|x|, 1)·cbrt(eps)` and the ACTUAL representable denominator
- * `dx = (x + h) − (x − h)` — so the perturbation survives floating-point
- * rounding even at astrophysical scales (e.g. `M ≈ 2e30 kg`). The supplied
- * `params` must contain every key in `spec.paramNames`; non-differentiable
- * fields come from `spec.defaults`.
+ * For each differentiable param with value `x` it uses the relative step
+ * `h = max(|x|, floor)·cbrt(eps)`, where `floor` is the spec's
+ * {@link BridgeDiffSpec.stepFloors} entry for that param (0 when the spec
+ * states none), and the ACTUAL representable denominator
+ * `dx = (x + h) − (x − h)` (`numerical/finite-difference`) — so the
+ * perturbation survives floating-point rounding at astrophysical scales
+ * (`M ≈ 2e30 kg`) and stays relative at atomic ones (a charge of 1.6e-19
+ * takes a step of 1e-24, not the 6e-6 an absolute floor of 1 gave). A param
+ * at exactly 0 with no stated floor is refused with a `RangeError`: there is
+ * no scale to step by. The supplied `params` must contain every key in
+ * `spec.paramNames`; non-differentiable fields come from `spec.defaults`.
  *
  * @public
  */
@@ -70,11 +76,13 @@ export function bridgeGradientNumerical(spec, params, opts) {
     const gradient = {};
     for (const k of spec.paramNames) {
         const x = params[k];
-        const h = Math.max(Math.abs(x), 1) * relStep;
-        const dx = x + h - (x - h); // actual representable step (huge-x safe)
-        const fp = spec.evaluate(buildInput({ key: k, val: x + h }));
-        const fm = spec.evaluate(buildInput({ key: k, val: x - h }));
-        gradient[k] = (fp - fm) / dx;
+        const floor = spec.stepFloors?.[k] ?? 0;
+        const h = Math.max(Math.abs(x), floor) * relStep;
+        if (!(h > 0)) {
+            throw new RangeError(`bridgeGradientNumerical: ${spec.bridgeId}: param '${k}' is ${x} and the spec states no stepFloors['${k}'], ` +
+                `so a relative central-difference step has no scale; state the parameter's scale in the spec's stepFloors.`);
+        }
+        gradient[k] = centralPartial((p) => spec.evaluate(buildInput({ key: k, val: p[k] })), { [k]: x }, k, h);
     }
     return { value, gradient };
 }

package/dist/diff/bridge-gradient.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-gradient.js","sourceRoot":"","sources":["../../src/diff/bridge-gradient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA4CH;;;;;GAKG;AACH,MAAM,qBAAqB,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY;AAErE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAA2B,EAC3B,MAA8B,EAC9B,IAAoC;IAEpC,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,qBAAqB,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,UAAU,CAClB,4BAA4B,IAAI,CAAC,QAAQ,mDAAmD,OAAO,GAAG;YACtG,6FAA6F,CAC9F,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,SAAS,CACjB,4BAA4B,IAAI,CAAC,QAAQ,kCAAkC,CAAC,IAAI;gBAChF,QAAQ,MAAM,CAAC,CAAC,CAAC,gEAAgE,CAClF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,oEAAoE;IACpE,0EAA0E;IAC1E,uEAAuE;IACvE,yEAAyE;IACzE,MAAM,UAAU,GAAG,CAAC,QAAuC,EAAS,EAAE;QACpE,MAAM,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAA6B,CAAC;QAC9D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU;YAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACtD,IAAI,QAAQ;YAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC;QACjD,OAAO,KAAyB,CAAC;IACnC,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC;QAC7C,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,0CAA0C;QACtE,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7D,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;IAC/B,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC","sourcesContent":["/**\n * Bridge-parameter differentiation by central finite differences.\n *\n * A {@link BridgeDiffSpec} wraps one catalog closed form (a plain-JS scalar\n * function over a named-field struct) and names which fields vary.\n * {@link bridgeGradientNumerical} perturbs those fields and returns the\n * gradient keyed by field name.\n *\n * There is no engine-AD path over a spec. `evaluate` returns a `number`, and\n * a number carries no autograd tape, so reverse- or forward-mode AD of a spec\n * is unreachable by construction; the function that once offered it\n * (`bridgeGradient`) threw for every shipped spec and was removed. The exact\n * AD path is {@link bridgeGradientAST} in `bridge-ast-gradient.ts`, which\n * lowers the bridge's symbolic RHS through `@danielsimonjr/mathts-autograd`.\n *\n * This module lives in `src/diff/` (P8 Decision #1), not in `src/bridges/`,\n * so the catalog closed forms stay untouched.\n *\n * @module diff/bridge-gradient\n */\n\n/**\n * Specification of a differentiable bridge: which parameters can vary, in\n * what order the gradient reports them, the fixed inputs, and the bridge's\n * scalar evaluator.\n *\n * `paramNames` is the report order. For a Shapiro-delay spec with\n * `paramNames: ['M_kg', 'R_far_m', 'R_near_m']`, the gradient returned by\n * `bridgeGradientNumerical` has keys in that insertion order.\n *\n * @public\n */\nexport interface BridgeDiffSpec<Input> {\n  /** Catalog id used in error messages (for example the relation that uses the covariant-eikonal method). */\n  readonly bridgeId: string;\n  /** Display name (e.g., 'Shapiro time delay'). */\n  readonly name: string;\n  /**\n   * Which Input keys vary, in report order. All names must be present in the\n   * frozen `Input` struct as `number`-valued keys.\n   */\n  readonly paramNames: ReadonlyArray<keyof Input & string>;\n  /**\n   * The non-differentiable input fields (those NOT in `paramNames`). The\n   * evaluator receives `defaults` merged with the varying params.\n   */\n  readonly defaults: Partial<Input>;\n  /** The bridge's scalar evaluator. */\n  readonly evaluate: (input: Input) => number;\n}\n\n/**\n * Result of {@link bridgeGradientNumerical}: the bridge's scalar `value`\n * at the supplied point, plus the `gradient` of partial derivatives keyed\n * by `paramName` (insertion follows `spec.paramNames` order).\n *\n * @public\n */\nexport interface BridgeNumericalGradientResult {\n  readonly value: number;\n  readonly gradient: Readonly<Record<string, number>>;\n}\n\n/**\n * Relative step for central differences: `cbrt(eps)` balances the `O(h²)`\n * truncation error against the `O(eps/h)` round-off error (the central-diff\n * optimum). `sqrt(eps)` — the FORWARD-diff optimum — would leave precision on\n * the table for central differences.\n */\nconst CENTRAL_DIFF_REL_STEP = Math.cbrt(Number.EPSILON); // ≈ 6.06e-6\n\n/**\n * Gradient of a bridge evaluator by **central finite differences** — the\n * way to differentiate the catalog's plain-JS closed forms without\n * rewriting them. Needs no engine and is synchronous.\n *\n * For each differentiable param with value `x` it uses a relative step\n * `h = max(|x|, 1)·cbrt(eps)` and the ACTUAL representable denominator\n * `dx = (x + h) − (x − h)` — so the perturbation survives floating-point\n * rounding even at astrophysical scales (e.g. `M ≈ 2e30 kg`). The supplied\n * `params` must contain every key in `spec.paramNames`; non-differentiable\n * fields come from `spec.defaults`.\n *\n * @public\n */\nexport function bridgeGradientNumerical<Input>(\n  spec: BridgeDiffSpec<Input>,\n  params: Record<string, number>,\n  opts?: { readonly relStep?: number },\n): BridgeNumericalGradientResult {\n  const relStep = opts?.relStep ?? CENTRAL_DIFF_REL_STEP;\n  if (!Number.isFinite(relStep) || relStep <= 0) {\n    throw new RangeError(\n      `bridgeGradientNumerical: ${spec.bridgeId}: relStep must be a positive finite number, got ${relStep} ` +\n      `(a zero/non-finite step collapses the central-difference denominator to 0 → NaN gradients).`,\n    );\n  }\n\n  // Every paramName must be a FINITE number. (`typeof NaN === 'number'`, so a\n  // bare typeof check let NaN/∞ flow into a silently non-finite gradient.)\n  for (const k of spec.paramNames) {\n    if (!Number.isFinite(params[k])) {\n      throw new TypeError(\n        `bridgeGradientNumerical: ${spec.bridgeId}: missing or non-finite param '${k}' ` +\n        `(got ${params[k]}). All paramNames must be finite numbers in the params object.`,\n      );\n    }\n  }\n\n  // Build the full Input struct (defaults + differentiable params), with an\n  // optional single-param override for the perturbed evaluations. The\n  // `Input` generic has no runtime schema: `spec.paramNames` is declared as\n  // keys of `Input`, and `defaults` is a `Partial<Input>`, so the merged\n  // record is an `Input` by the spec's own contract; the cast states that.\n  const buildInput = (override?: { key: string; val: number }): Input => {\n    const input = { ...spec.defaults } as Record<string, unknown>;\n    for (const k of spec.paramNames) input[k] = params[k];\n    if (override) input[override.key] = override.val;\n    return input as unknown as Input;\n  };\n\n  const value = spec.evaluate(buildInput());\n\n  const gradient: Record<string, number> = {};\n  for (const k of spec.paramNames) {\n    const x = params[k];\n    const h = Math.max(Math.abs(x), 1) * relStep;\n    const dx = x + h - (x - h); // actual representable step (huge-x safe)\n    const fp = spec.evaluate(buildInput({ key: k, val: x + h }));\n    const fm = spec.evaluate(buildInput({ key: k, val: x - h }));\n    gradient[k] = (fp - fm) / dx;\n  }\n\n  return { value, gradient };\n}\n"]}
+{"version":3,"file":"bridge-gradient.js","sourceRoot":"","sources":["../../src/diff/bridge-gradient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAoDnE;;;;;GAKG;AACH,MAAM,qBAAqB,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAA2B,EAC3B,MAA8B,EAC9B,IAAoC;IAEpC,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,qBAAqB,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,UAAU,CAClB,4BAA4B,IAAI,CAAC,QAAQ,mDAAmD,OAAO,GAAG;YACtG,6FAA6F,CAC9F,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,SAAS,CACjB,4BAA4B,IAAI,CAAC,QAAQ,kCAAkC,CAAC,IAAI;gBAChF,QAAQ,MAAM,CAAC,CAAC,CAAC,gEAAgE,CAClF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,oEAAoE;IACpE,0EAA0E;IAC1E,uEAAuE;IACvE,yEAAyE;IACzE,MAAM,UAAU,GAAG,CAAC,QAAuC,EAAS,EAAE;QACpE,MAAM,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAA6B,CAAC;QAC9D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU;YAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACtD,IAAI,QAAQ;YAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC;QACjD,OAAO,KAAyB,CAAC;IACnC,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC;QACjD,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACb,MAAM,IAAI,UAAU,CAClB,4BAA4B,IAAI,CAAC,QAAQ,YAAY,CAAC,QAAQ,CAAC,uCAAuC,CAAC,MAAM;gBAC7G,2GAA2G,CAC5G,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3G,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC","sourcesContent":["/**\n * Bridge-parameter differentiation by central finite differences.\n *\n * A {@link BridgeDiffSpec} wraps one catalog closed form (a plain-JS scalar\n * function over a named-field struct) and names which fields vary.\n * {@link bridgeGradientNumerical} perturbs those fields and returns the\n * gradient keyed by field name.\n *\n * There is no engine-AD path over a spec. `evaluate` returns a `number`, and\n * a number carries no autograd tape, so reverse- or forward-mode AD of a spec\n * is unreachable by construction; the function that once offered it\n * (`bridgeGradient`) threw for every shipped spec and was removed. The exact\n * AD path is {@link bridgeGradientAST} in `bridge-ast-gradient.ts`, which\n * lowers the bridge's symbolic RHS through `@danielsimonjr/mathts-autograd`.\n *\n * This module lives in `src/diff/` (P8 Decision #1), not in `src/bridges/`,\n * so the catalog closed forms stay untouched.\n *\n * @module diff/bridge-gradient\n */\n\nimport { centralPartial } from '../numerical/finite-difference.js';\n\n/**\n * Specification of a differentiable bridge: which parameters can vary, in\n * what order the gradient reports them, the fixed inputs, and the bridge's\n * scalar evaluator.\n *\n * `paramNames` is the report order. For a Shapiro-delay spec with\n * `paramNames: ['M_kg', 'R_far_m', 'R_near_m']`, the gradient returned by\n * `bridgeGradientNumerical` has keys in that insertion order.\n *\n * @public\n */\nexport interface BridgeDiffSpec<Input> {\n  /** Catalog id used in error messages (for example the relation that uses the covariant-eikonal method). */\n  readonly bridgeId: string;\n  /** Display name (e.g., 'Shapiro time delay'). */\n  readonly name: string;\n  /**\n   * Which Input keys vary, in report order. All names must be present in the\n   * frozen `Input` struct as `number`-valued keys.\n   */\n  readonly paramNames: ReadonlyArray<keyof Input & string>;\n  /**\n   * The non-differentiable input fields (those NOT in `paramNames`). The\n   * evaluator receives `defaults` merged with the varying params.\n   */\n  readonly defaults: Partial<Input>;\n  /** The bridge's scalar evaluator. */\n  readonly evaluate: (input: Input) => number;\n  /**\n   * The smallest magnitude the relative step is taken against, per parameter:\n   * for `|x| < floor` the step is `floor·relStep`. A parameter that is zero at\n   * a point of interest (an eccentricity on a circular orbit) needs its scale\n   * stated here, because a relative step at zero is no step. A parameter not\n   * named here has no floor: the step is `|x|·relStep`, and `x = 0` is refused.\n   */\n  readonly stepFloors?: Readonly<Partial<Record<keyof Input & string, number>>>;\n}\n\n/**\n * Result of {@link bridgeGradientNumerical}: the bridge's scalar `value`\n * at the supplied point, plus the `gradient` of partial derivatives keyed\n * by `paramName` (insertion follows `spec.paramNames` order).\n *\n * @public\n */\nexport interface BridgeNumericalGradientResult {\n  readonly value: number;\n  readonly gradient: Readonly<Record<string, number>>;\n}\n\n/**\n * Relative step for central differences: `cbrt(eps)` balances the `O(h²)`\n * truncation error against the `O(eps/h)` round-off error (the central-diff\n * optimum). `sqrt(eps)` — the FORWARD-diff optimum — would leave precision on\n * the table for central differences.\n */\nconst CENTRAL_DIFF_REL_STEP = Math.cbrt(Number.EPSILON); // ≈ 6.06e-6\n\n/**\n * Gradient of a bridge evaluator by **central finite differences** — the\n * way to differentiate the catalog's plain-JS closed forms without\n * rewriting them. Needs no engine and is synchronous.\n *\n * For each differentiable param with value `x` it uses the relative step\n * `h = max(|x|, floor)·cbrt(eps)`, where `floor` is the spec's\n * {@link BridgeDiffSpec.stepFloors} entry for that param (0 when the spec\n * states none), and the ACTUAL representable denominator\n * `dx = (x + h) − (x − h)` (`numerical/finite-difference`) — so the\n * perturbation survives floating-point rounding at astrophysical scales\n * (`M ≈ 2e30 kg`) and stays relative at atomic ones (a charge of 1.6e-19\n * takes a step of 1e-24, not the 6e-6 an absolute floor of 1 gave). A param\n * at exactly 0 with no stated floor is refused with a `RangeError`: there is\n * no scale to step by. The supplied `params` must contain every key in\n * `spec.paramNames`; non-differentiable fields come from `spec.defaults`.\n *\n * @public\n */\nexport function bridgeGradientNumerical<Input>(\n  spec: BridgeDiffSpec<Input>,\n  params: Record<string, number>,\n  opts?: { readonly relStep?: number },\n): BridgeNumericalGradientResult {\n  const relStep = opts?.relStep ?? CENTRAL_DIFF_REL_STEP;\n  if (!Number.isFinite(relStep) || relStep <= 0) {\n    throw new RangeError(\n      `bridgeGradientNumerical: ${spec.bridgeId}: relStep must be a positive finite number, got ${relStep} ` +\n      `(a zero/non-finite step collapses the central-difference denominator to 0 → NaN gradients).`,\n    );\n  }\n\n  // Every paramName must be a FINITE number. (`typeof NaN === 'number'`, so a\n  // bare typeof check let NaN/∞ flow into a silently non-finite gradient.)\n  for (const k of spec.paramNames) {\n    if (!Number.isFinite(params[k])) {\n      throw new TypeError(\n        `bridgeGradientNumerical: ${spec.bridgeId}: missing or non-finite param '${k}' ` +\n        `(got ${params[k]}). All paramNames must be finite numbers in the params object.`,\n      );\n    }\n  }\n\n  // Build the full Input struct (defaults + differentiable params), with an\n  // optional single-param override for the perturbed evaluations. The\n  // `Input` generic has no runtime schema: `spec.paramNames` is declared as\n  // keys of `Input`, and `defaults` is a `Partial<Input>`, so the merged\n  // record is an `Input` by the spec's own contract; the cast states that.\n  const buildInput = (override?: { key: string; val: number }): Input => {\n    const input = { ...spec.defaults } as Record<string, unknown>;\n    for (const k of spec.paramNames) input[k] = params[k];\n    if (override) input[override.key] = override.val;\n    return input as unknown as Input;\n  };\n\n  const value = spec.evaluate(buildInput());\n\n  const gradient: Record<string, number> = {};\n  for (const k of spec.paramNames) {\n    const x = params[k];\n    const floor = spec.stepFloors?.[k] ?? 0;\n    const h = Math.max(Math.abs(x), floor) * relStep;\n    if (!(h > 0)) {\n      throw new RangeError(\n        `bridgeGradientNumerical: ${spec.bridgeId}: param '${k}' is ${x} and the spec states no stepFloors['${k}'], ` +\n        `so a relative central-difference step has no scale; state the parameter's scale in the spec's stepFloors.`,\n      );\n    }\n    gradient[k] = centralPartial((p) => spec.evaluate(buildInput({ key: k, val: p[k]! })), { [k]: x }, k, h);\n  }\n\n  return { value, gradient };\n}\n"]}

package/dist/diff/bridge-specs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-specs.d.ts","sourceRoot":"","sources":["../../src/diff/bridge-specs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAGnE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAKlE;AAsBD,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,+GAA+G;AAC/G,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAUD,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,YAAY,CAM3D,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,eAAe,CAMnE,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,EAAE,cAAc,CAAC,YAAY,CAMjE,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,gBAAgB,CAMlE,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB,0IAK3B,CAAC"}
+{"version":3,"file":"bridge-specs.d.ts","sourceRoot":"","sources":["../../src/diff/bridge-specs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAGnE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAKlE;AAsBD,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,+GAA+G;AAC/G,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAUD,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,YAAY,CAM3D,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,eAAe,CASnE,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,EAAE,cAAc,CAAC,YAAY,CAMjE,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,gBAAgB,CAMlE,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB,0IAK3B,CAAC"}

package/dist/diff/bridge-specs.js

@@ -60,6 +60,9 @@ export const PERIHELION_ADVANCE_DIFF = {
     paramNames: ['M_kg', 'a_m', 'eccentricity'],
     defaults: {},
     evaluate: (input) => evaluateAliased(perihelion, input),
+    // The eccentricity is a dimensionless number in [0, 1): its scale is 1, so a circular orbit
+    // (eccentricity 0) still takes the step 1·∛ε, the step every orbit took before the floor was stated.
+    stepFloors: { eccentricity: 1 },
 };
 /** Hawking temperature. Differentiable in mass. @public */
 export const HAWKING_TEMPERATURE_DIFF = {