universal-physics-tensor 9.0.0 → 10.0.0

package/dist/cli/commands/metric.js

@@ -2,6 +2,7 @@ import { registerCommand } from '../command.js';
 import { commandHelp, JSON_FLAG } from '../flag-help.js';
 import { emitJson } from '../output.js';
 import { CliError, UsageError } from '../errors.js';
+import { splitAssignments } from '../bindings.js';
 const FLAGS = [
     JSON_FLAG,
     {
@@ -34,6 +35,20 @@ const HELP = `upt metric <minkowski|schwarzschild|flrw|kerr> [key=value ...] [--
 function isMetric(s) {
     return NAMES.includes(s ?? '');
 }
+/**
+ * The metric library refuses a bad value (a non-positive mass, a point inside
+ * the horizon, an unknown parameter, a start the integrator cannot take, a
+ * parameter in the wrong unit) with `MetricMassError`, a `UnitError`, or a
+ * plain `Error`. Each is a bad value, exit 1. Any other class (a TypeError, a
+ * RangeError) is a defect and is not converted.
+ */
+function metricValueError(api, e) {
+    if (e instanceof api.MetricMassError || e instanceof api.UnitError)
+        return new CliError(`upt metric: ${e.message}`);
+    if (e instanceof Error && e.constructor === Error)
+        return new CliError(`upt metric: ${e.message}`);
+    return e;
+}
 async function run(ctx) {
     const { args, api, out } = ctx;
     const name = args.positionals[0];
@@ -41,15 +56,14 @@ async function run(ctx) {
         throw new UsageError(`upt metric needs one of ${NAMES.join(', ')}. See \`upt help metric\`.`);
     }
     const pairs = args.positionals.slice(1);
+    // A token with no `=` is usage (exit 2); a parameter given twice is refused (exit 1).
+    splitAssignments('metric', pairs, 'key=value');
     let report;
     try {
         report = api.curvatureReport(name, pairs);
     }
     catch (e) {
-        // A mass that is not positive is a bad value (exit 1), as for --geodesic. The rest is a point off the chart.
-        if (e instanceof api.MetricMassError)
-            throw new CliError(e.message);
-        throw new UsageError(e.message);
+        throw metricValueError(api, e);
     }
     let geodesic;
     if (args.flags.has('geodesic')) {
@@ -74,19 +88,38 @@ async function run(ctx) {
                 const aOverM = a / Mgeom;
                 if (!(Math.abs(aOverM) <= 1))
                     throw new CliError('Kerr geodesic wants |a| ≤ GM/c²');
-                const shared = { M: Mgeom, aOverM, rOverM, fraction: 0.005, steps: 40 };
-                geodesic =
-                    Math.abs(theta - Math.PI / 2) < 1e-6
-                        ? { kind: 'circular', ...api.kerrEquatorialCircular(shared) }
-                        : {
-                            kind: 'inclined',
-                            ...api.kerrGeodesic({
-                                ...shared,
-                                theta,
-                                ...api.kerrTurningPointOrbit({ M: Mgeom, aOverM, rOverM, theta }),
-                                mu2: 1,
-                            }),
-                        };
+                const equatorial = Math.abs(theta - Math.PI / 2) < 1e-6;
+                if (a === 0) {
+                    // At a = 0 the Kerr metric is Schwarzschild. The Boyer–Lindquist integrator refuses the
+                    // circular start there ("radial potential is negative at the start"): the two terms of
+                    // its radial potential cancel to below its tolerance at a = 0, and only at a = 0. The
+                    // equatorial circular orbit is the Schwarzschild one and is integrated as that, so the
+                    // default parameters (a = 0) run. An inclined start has no Schwarzschild routine here.
+                    if (!equatorial) {
+                        throw new CliError('upt metric: at a = 0 an inclined Kerr orbit is a tilted Schwarzschild circular orbit, and this integrator needs a ≠ 0 for an inclined start; give a, or theta=pi/2');
+                    }
+                    const M = report.parameters.M;
+                    geodesic = {
+                        kind: 'circular',
+                        note: 'a = 0: the Kerr metric is Schwarzschild; the equatorial circular orbit is integrated by the Schwarzschild routine',
+                        ...api.schwarzschildCircularOrbit({ ...(M === undefined ? {} : { M }), ...(r === undefined ? {} : { r }) }),
+                    };
+                }
+                else {
+                    const shared = { M: Mgeom, aOverM, rOverM, fraction: 0.005, steps: 40 };
+                    geodesic =
+                        equatorial
+                            ? { kind: 'circular', ...api.kerrEquatorialCircular(shared) }
+                            : {
+                                kind: 'inclined',
+                                ...api.kerrGeodesic({
+                                    ...shared,
+                                    theta,
+                                    ...api.kerrTurningPointOrbit({ M: Mgeom, aOverM, rOverM, theta }),
+                                    mu2: 1,
+                                }),
+                            };
+                }
             }
             else {
                 throw new UsageError('upt metric: --geodesic is for schwarzschild or kerr.');
@@ -95,7 +128,7 @@ async function run(ctx) {
         catch (e) {
             if (e instanceof UsageError || e instanceof CliError)
                 throw e;
-            throw new UsageError(e.message);
+            throw metricValueError(api, e);
         }
     }
     if (args.flags.has('json')) {
@@ -129,6 +162,8 @@ async function run(ctx) {
         const polar = geodesic.theta0 === undefined ? '' : ` θ ${geodesic.theta0}→${geodesic.thetaEnd}`;
         const label = geodesic.kind === 'inclined' ? 'inclined orbit' : 'circular orbit';
         out(`  geodesic: ${label} r0=${geodesic.r0} rEnd=${geodesic.rEnd}${polar} Δφ=${geodesic.phiAdvance} over ${geodesic.steps} steps${cons}`);
+        if (geodesic.note !== undefined)
+            out(`    ${geodesic.note}`);
     }
     return 0;
 }

package/dist/cli/commands/metric.js.map

@@ -1 +1 @@
-{"version":3,"file":"metric.js","sourceRoot":"","sources":["../../../src/cli/commands/metric.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"metric.js","sourceRoot":"","sources":["../../../src/cli/commands/metric.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `upt metric` — Christoffel symbols and curvature scalars for a named metric.\n *\n * `--geodesic` integrates a short Schwarzschild circular orbit, or a Kerr\n * geodesic. θ = π/2 is equatorial and circular. Any other θ is an inclined\n * spherical orbit with that polar turning point.\n *\n * @module cli/commands/metric\n */\nimport type { FlagSpec } from '../args.js';\nimport { registerCommand, type Command, type CommandCtx } from '../command.js';\nimport { commandHelp, JSON_FLAG } from '../flag-help.js';\nimport { emitJson } from '../output.js';\nimport { CliError, UsageError } from '../errors.js';\nimport { splitAssignments } from '../bindings.js';\nimport type { MetricId } from '../../cli-api.js';\n\nconst FLAGS: FlagSpec[] = [\n  JSON_FLAG,\n  {\n    name: '--geodesic',\n    valueStyle: 'none',\n    description: 'Integrate a short Schwarzschild circular orbit, or a Kerr geodesic at the given θ.',\n  },\n];\n\nconst NAMES = ['minkowski', 'schwarzschild', 'flrw', 'kerr'] as const;\n\nconst HELP = `upt metric <minkowski|schwarzschild|flrw|kerr> [key=value ...] [--geodesic] [--json]\n        Christoffel symbols, the Ricci tensor, the Ricci scalar and the\n        Kretschmann scalar of one exact metric. Alias: upt curvature.\n        Signature of the line element is (-,+,+,+), the same mostly-plus\n        signature as the canonical Einstein-equation metric node.\n        Schwarzschild Kretschmann is checked against 48 G² M² / (c⁴ r⁶).\n        FLRW prints the Friedmann equation including the curvature term\n        −k c²/a² and Λ. Kerr Kretschmann uses the Boyer–Lindquist closed form.\n        --geodesic integrates a short Schwarzschild circular orbit, or a Kerr\n        geodesic (equatorial and circular at θ = π/2; inclined, with that\n        polar turning point, at any other θ). Kerr's a is a length in metres;\n        the report prints a/M = a/(GM/c²). A Ricci scalar that has a closed\n        form is that form; a vacuum finite-difference residual is not listed\n        as Ricci. A parameter is a number, a unit (M=1Msun, r=1km) or a\n        constant expression (theta=pi/2). A bare number is already in the\n        parameter's SI unit; a dimensioned quantity must match it.\n        \\`upt help metric\\` describes every flag.\n        e.g.  upt metric schwarzschild M=1Msun r=1e8 theta=pi/2\n              upt metric flrw k=1 t=2\n              upt curvature kerr a=1000 r=1e8 theta=1.2`;\n\nfunction isMetric(s: string | undefined): s is MetricId {\n  return (NAMES as readonly string[]).includes(s ?? '');\n}\n\n/**\n * The metric library refuses a bad value (a non-positive mass, a point inside\n * the horizon, an unknown parameter, a start the integrator cannot take, a\n * parameter in the wrong unit) with `MetricMassError`, a `UnitError`, or a\n * plain `Error`. Each is a bad value, exit 1. Any other class (a TypeError, a\n * RangeError) is a defect and is not converted.\n */\nfunction metricValueError(api: CommandCtx['api'], e: unknown): unknown {\n  if (e instanceof api.MetricMassError || e instanceof api.UnitError) return new CliError(`upt metric: ${e.message}`);\n  if (e instanceof Error && e.constructor === Error) return new CliError(`upt metric: ${e.message}`);\n  return e;\n}\n\nasync function run(ctx: CommandCtx): Promise<number> {\n  const { args, api, out } = ctx;\n  const name = args.positionals[0];\n  if (!isMetric(name)) {\n    throw new UsageError(\n      `upt metric needs one of ${NAMES.join(', ')}. See \\`upt help metric\\`.`,\n    );\n  }\n  const pairs = args.positionals.slice(1);\n  // A token with no `=` is usage (exit 2); a parameter given twice is refused (exit 1).\n  splitAssignments('metric', pairs, 'key=value');\n  let report;\n  try {\n    report = api.curvatureReport(name, pairs);\n  } catch (e) {\n    throw metricValueError(api, e);\n  }\n  let geodesic:\n    | {\n        readonly kind: 'circular' | 'inclined';\n        readonly r0: number;\n        readonly rEnd: number;\n        readonly theta0?: number;\n        readonly thetaEnd?: number;\n        readonly phiAdvance: number;\n        readonly steps: number;\n        readonly E0?: number;\n        readonly EEnd?: number;\n        readonly L0?: number;\n        readonly LEnd?: number;\n        readonly Q0?: number;\n        readonly QEnd?: number;\n        readonly norm0?: number;\n        readonly normEnd?: number;\n        readonly note?: string;\n      }\n    | undefined;\n  if (args.flags.has('geodesic')) {\n    try {\n      if (name === 'schwarzschild') {\n        const M = report.parameters.M;\n        const r = report.parameters.r;\n        const orbit = api.schwarzschildCircularOrbit({\n          ...(M === undefined ? {} : { M }),\n          ...(r === undefined ? {} : { r }),\n        });\n        geodesic = { kind: 'circular', ...orbit };\n      } else if (name === 'kerr') {\n        const Mgeom = report.parameters.M_geom_m;\n        const a = report.parameters.a ?? 0;\n        const r = report.parameters.r;\n        const theta = report.parameters.theta ?? Math.PI / 2;\n        if (Mgeom === undefined || !(Mgeom > 0)) throw new CliError('Kerr geodesic needs a positive mass');\n        const rOverM = (r ?? 10 * Mgeom) / Mgeom;\n        const aOverM = a / Mgeom;\n        if (!(Math.abs(aOverM) <= 1)) throw new CliError('Kerr geodesic wants |a| ≤ GM/c²');\n        const equatorial = Math.abs(theta - Math.PI / 2) < 1e-6;\n        if (a === 0) {\n          // At a = 0 the Kerr metric is Schwarzschild. The Boyer–Lindquist integrator refuses the\n          // circular start there (\"radial potential is negative at the start\"): the two terms of\n          // its radial potential cancel to below its tolerance at a = 0, and only at a = 0. The\n          // equatorial circular orbit is the Schwarzschild one and is integrated as that, so the\n          // default parameters (a = 0) run. An inclined start has no Schwarzschild routine here.\n          if (!equatorial) {\n            throw new CliError(\n              'upt metric: at a = 0 an inclined Kerr orbit is a tilted Schwarzschild circular orbit, and this integrator needs a ≠ 0 for an inclined start; give a, or theta=pi/2',\n            );\n          }\n          const M = report.parameters.M;\n          geodesic = {\n            kind: 'circular' as const,\n            note: 'a = 0: the Kerr metric is Schwarzschild; the equatorial circular orbit is integrated by the Schwarzschild routine',\n            ...api.schwarzschildCircularOrbit({ ...(M === undefined ? {} : { M }), ...(r === undefined ? {} : { r }) }),\n          };\n        } else {\n        const shared = { M: Mgeom, aOverM, rOverM, fraction: 0.005, steps: 40 };\n        geodesic =\n          equatorial\n            ? { kind: 'circular' as const, ...api.kerrEquatorialCircular(shared) }\n            : {\n                kind: 'inclined' as const,\n                ...api.kerrGeodesic({\n                  ...shared,\n                  theta,\n                  ...api.kerrTurningPointOrbit({ M: Mgeom, aOverM, rOverM, theta }),\n                  mu2: 1,\n                }),\n              };\n        }\n      } else {\n        throw new UsageError('upt metric: --geodesic is for schwarzschild or kerr.');\n      }\n    } catch (e) {\n      if (e instanceof UsageError || e instanceof CliError) throw e;\n      throw metricValueError(api, e);\n    }\n  }\n  if (args.flags.has('json')) {\n    emitJson({ command: 'metric', result: { ...report, ...(geodesic === undefined ? {} : { geodesic }) } }, ctx.write);\n    return 0;\n  }\n  out(`\\n${report.metric}  signature ${report.signature}`);\n  out(`  ${report.signatureNote}`);\n  out(`  coordinates ${report.coordinates}`);\n  out('  parameters: ' + Object.entries(report.parameters).map(([k, v]) => `${k}=${v}`).join(' '));\n  out('  point: ' + Object.entries(report.point).map(([k, v]) => `${k}=${v}`).join(' '));\n  for (const note of report.notes) out(`  ${note}`);\n  out('  Christoffel (nonzero):');\n  if (report.christoffel.length === 0) out('    (none)');\n  for (const c of report.christoffel) out(`    ${c.index} = ${c.value}`);\n  out('  Ricci (nonzero):');\n  if (report.ricci.length === 0) out('    (none)');\n  for (const c of report.ricci) out(`    ${c.index} = ${c.value}`);\n  out(`  Ricci scalar R = ${report.ricciScalar}`);\n  out(`  Kretschmann K = ${report.kretschmann}`);\n  out('  closed form: ' + Object.entries(report.closedForm).map(([k, v]) => `${k}=${v}`).join(' '));\n  if (geodesic) {\n    const cons =\n      geodesic.E0 === undefined\n        ? ''\n        : ` E ${geodesic.E0}→${geodesic.EEnd} L ${geodesic.L0}→${geodesic.LEnd} Q ${geodesic.Q0}→${geodesic.QEnd} norm ${geodesic.norm0}→${geodesic.normEnd}`;\n    const polar =\n      geodesic.theta0 === undefined ? '' : ` θ ${geodesic.theta0}→${geodesic.thetaEnd}`;\n    const label = geodesic.kind === 'inclined' ? 'inclined orbit' : 'circular orbit';\n    out(\n      `  geodesic: ${label} r0=${geodesic.r0} rEnd=${geodesic.rEnd}${polar} Δφ=${geodesic.phiAdvance} over ${geodesic.steps} steps${cons}`,\n    );\n    if (geodesic.note !== undefined) out(`    ${geodesic.note}`);\n  }\n  return 0;\n}\n\nexport const command: Command = {\n  name: 'metric',\n  aliases: ['curvature'],\n  flags: FLAGS,\n  help: commandHelp(HELP, FLAGS),\n  summary: 'Print Christoffel symbols and curvature scalars for one exact metric.',\n  example: 'upt metric schwarzschild M=1Msun r=1e8 theta=pi/2',\n  group: 'evaluate',\n  run,\n};\n\nregisterCommand(command);\n"]}

package/dist/cli/commands/path.js

@@ -672,7 +672,7 @@ function runSweep(ctx, s) {
     for (const r of rows) {
         const a = r.adequacy === undefined ? '' : `${r.adequacy.padEnd(13)} `;
         const w = s.translation === null ? '' : `${(r.pointWitness?.status ?? '—').padEnd(14)} `;
-        out(`  ${String(Number(r.value.toPrecision(6))).padEnd(12)} ${String(r.regime).padEnd(10)} ${String(r.horizon).padEnd(14)} ${a}${w}${r.error === null ? `— ${r.reason ?? ''}` : r.error}`);
+        out(`  ${ctx.api.formatQuantity(r.value, 6).padEnd(12)} ${String(r.regime).padEnd(10)} ${String(r.horizon).padEnd(14)} ${a}${w}${r.error === null ? `— ${r.reason ?? ''}` : ctx.api.formatQuantity(r.error, 6)}`);
     }
     out(`  in regime: ${tally('regime', 'holds')} · outside: ${tally('regime', 'violated')} · unknown: ${tally('regime', 'unknown')} · ` +
         `past the horizon: ${tally('horizon', 'violated')} of ${rows.length}`);
@@ -774,9 +774,9 @@ function runCompare(ctx, from, point, spec, sides) {
     const w = Math.max(30, ...heads.map((h) => h.length));
     out(`  ${sweep.name.padEnd(12)} ${heads.map((h) => h.padEnd(w)).join(' ')} covered by`);
     for (const r of rows) {
-        const cells = r.paths.map((p) => `${p.regime}/${p.horizon} ${p.error === null ? '—' : Number(p.error.toPrecision(6))}`.padEnd(w));
+        const cells = r.paths.map((p) => `${p.regime}/${p.horizon} ${p.error === null ? '—' : ctx.api.formatQuantity(p.error, 6)}`.padEnd(w));
         const cov = r.coverage === 'covered' ? r.claimedBy.join(' + ') : r.coverage === 'neither' ? `NEITHER — ${neitherNote}` : 'UNSETTLED — a coordinate or t was not supplied';
-        out(`  ${String(Number(r.value.toPrecision(6))).padEnd(12)} ${cells.join(' ')} ${cov}`);
+        out(`  ${ctx.api.formatQuantity(r.value, 6).padEnd(12)} ${cells.join(' ')} ${cov}`);
     }
     out(`  covered: ${tally.covered} (${sides.map((sd) => `${sd.to}: ${tally.claimedBy[sd.to]}`).join(', ')}; by all: ${tally.claimedByAll}) · ` +
         `NEITHER: ${tally.neither} · unsettled: ${tally.unsettled} of ${rows.length}`);
@@ -816,7 +816,7 @@ function makeEvaluator(api, bridges, result) {
         const regimeCollisions = api.collidingRegimeGroups(bridges.map((b) => b.regime));
         const blockedGroups = new Set(regimeCollisions.map((c) => c.group));
         const regimes = bridges.map((b) => {
-            const { values } = resolveAtPoint(at, [b.regime]);
+            const { values } = resolveAtPoint(api, at, [b.regime]);
             for (const name of blockedGroups)
                 delete values[name];
             const check = api.regimeHolds(b.regime, values);