universal-physics-tensor 10.0.0 → 12.0.0

package/dist/composition/evaluate-relation.d.ts

@@ -12,12 +12,29 @@
  */
 import type { Dimension } from '../dimensional/types.js';
 import { type EvaluatorSpec } from '../bridges/evaluators.js';
-import { type InputContract } from '../bridges/input-contract.js';
+import { type EvaluationWant, type InputContract } from '../bridges/input-contract.js';
 import { type BridgeEdge } from './edge.js';
+/**
+ * A further number an evaluator returns beside its value (be-52's
+ * `precession_arcsec_per_century`), with the unit and meaning its record states.
+ *
+ * @public
+ */
+export interface ExtraOutput {
+    readonly name: string;
+    readonly value: number;
+    readonly unit: string;
+    readonly meaning: string;
+}
 /**
  * A sourced number, or an unset coefficient.
  *
- * `dimension` is the edge target. `formula` is the edge label.
+ * A value carries what it is: `name` is the quantity the relation computes
+ * (its target), `unit` that quantity's SI unit written from `dimension` (the
+ * form `parseUnit` reads back), `meaning` the relation as its record states it
+ * (a sign convention included), and `extras` every further output whose inputs
+ * were given. `upt evaluate` prints and serializes this object; it computes no
+ * label of its own. `formula` is the edge label.
  *
  * @public
  */
@@ -25,6 +42,10 @@ export type Evaluation = {
     readonly kind: 'value';
     readonly value: number;
     readonly dimension: Dimension;
+    readonly name: string;
+    readonly unit: string;
+    readonly meaning: string;
+    readonly extras: readonly ExtraOutput[];
 } | {
     readonly kind: 'unset';
     readonly formula: string;
@@ -38,15 +59,6 @@ export interface Evaluable {
     readonly edge?: BridgeEdge;
     readonly evaluator?: EvaluatorSpec;
 }
-/**
- * The output of a closed-form evaluator: the quantity it computes and that
- * quantity's dimension. An evaluator with no catalog dimension (a closed form
- * with no AST) names no dimension.
- */
-export declare function evaluatorOutput(spec: EvaluatorSpec): {
-    readonly name: string;
-    readonly dimension?: Dimension;
-};
 /**
  * The declared inputs of an evaluable id: the closed-form evaluator's contract
  * when it has one, else its edge's. {@link evaluateRelation} checks bindings
@@ -59,6 +71,15 @@ export declare function evaluableContract(found: Evaluable): InputContract;
  * An unknown id throws. An id with an evaluator and no edge is not unknown.
  */
 export declare function resolveEvaluable(id: string | number): Evaluable;
+/**
+ * The one result builder: evaluate a resolved id at `bindings`. A closed-form
+ * evaluator is its `run`; an edge with none is checked against its contract and
+ * evaluated. {@link evaluateRelation} calls it with `want` `'value'`;
+ * `upt evaluate` calls it with `'all'`, which also requires an input only an
+ * extra output reads. Both get the same {@link Evaluation}.
+ * @internal
+ */
+export declare function evaluateResolved(found: Evaluable, bindings: Readonly<Record<string, number>>, want: EvaluationWant): Evaluation;
 /**
  * Evaluate `id` at `bindings`.
  *
@@ -72,6 +93,9 @@ export declare function resolveEvaluable(id: string | number): Evaluable;
  * An unset coefficient returns `{ kind: 'unset', formula }` and no number.
  * A complete finite input whose closed form is not finite (a dropped factor,
  * a singularity) is the same unset result, not a missing input.
+ * A value carries its name, SI unit and meaning, and every extra output whose
+ * inputs were given (`extras`); an input only an extra output reads is not
+ * required.
  *
  * @public
  */

package/dist/composition/evaluate-relation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate-relation.d.ts","sourceRoot":"","sources":["../../src/composition/evaluate-relation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAM9F,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE,CAO9G;AAsCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,aAAa,CAGjE;AAYD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY/D;AAuBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,UAAU,CAcZ"}
+{"version":3,"file":"evaluate-relation.d.ts","sourceRoot":"","sources":["../../src/composition/evaluate-relation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,EAA8B,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAMnH,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAEjF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAClB;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;CACpC;AAsCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,aAAa,CAGjE;AAYD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY/D;AAoCD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC1C,IAAI,EAAE,cAAc,GACnB,UAAU,CAqBZ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,UAAU,CAEZ"}

package/dist/composition/evaluate-relation.js

@@ -11,6 +11,7 @@
  * @module composition/evaluate-relation
  */
 import { EXPECTED_DIMENSION_BY_BRIDGE } from '../dimensional/bridge-check.js';
+import { siUnitOf } from '../dimensional/algebra.js';
 import { BRIDGE_EVALUATORS } from '../bridges/evaluators.js';
 import { checkInputs, inputContract } from '../bridges/input-contract.js';
 import { catalogEdgeKey, parseBridgeId, primaryRelation } from '../bridges/catalog-load.js';
@@ -19,19 +20,6 @@ import { CANONICAL_GROUP_PREFACTORS } from './canonical-prefactors.js';
 import { CANONICAL_GRAPH } from './canonical-graph.js';
 import { CATALOG_GRAPH } from './catalog-graph.js';
 import { CoefficientUnsetError, evaluateEdge } from './edge.js';
-/**
- * The output of a closed-form evaluator: the quantity it computes and that
- * quantity's dimension. An evaluator with no catalog dimension (a closed form
- * with no AST) names no dimension.
- */
-export function evaluatorOutput(spec) {
-    const relation = primaryRelation(spec.bridgeId);
-    const dimension = EXPECTED_DIMENSION_BY_BRIDGE.get(spec.bridgeId);
-    return {
-        name: relation?.target ?? 'value',
-        ...(dimension === undefined ? {} : { dimension }),
-    };
-}
 /**
  * Names a canonical id may be bound under besides its sources: the equation's
  * governing names (a registered constant may be overridden), its formula
@@ -106,21 +94,67 @@ export function resolveEvaluable(id) {
     };
 }
 /**
- * The closed form's primary output, through the evaluator's `run`. A record's
- * `value` is the catalog signature; any other number it returns is an extra
- * output, named by `spec.outputs`. A non-finite value at finite inputs is an
- * unset result (a dropped factor, a singularity).
+ * The closed form through the evaluator's `run`, the one evaluation. A record's
+ * `value` is the catalog signature; every other number `run` returns is an
+ * extra output, labelled from `spec.outputs`. A non-finite value at finite
+ * inputs is an unset result (a dropped factor, a singularity).
  */
-function closedFormEvaluation(spec, edge, bindings) {
-    const { value } = spec.run(bindings, 'value');
+function closedFormEvaluation(spec, edge, bindings, want) {
+    const numbers = spec.run(bindings, want);
+    const relation = primaryRelation(spec.bridgeId);
     const dimension = edge?.target.dim ?? EXPECTED_DIMENSION_BY_BRIDGE.get(spec.bridgeId);
     if (dimension === undefined) {
         throw new Error(`evaluateRelation: be-${spec.bridgeId} has no catalog dimension`);
     }
-    if (Number.isFinite(value))
-        return { kind: 'value', value, dimension };
+    const value = numbers.value;
     // `run` refused a non-finite input, so a non-finite value here comes from the closed form.
-    return { kind: 'unset', formula: edge?.label ?? primaryRelation(spec.bridgeId)?.label ?? spec.name };
+    if (!Number.isFinite(value))
+        return { kind: 'unset', formula: edge?.label ?? relation?.label ?? spec.name };
+    return {
+        kind: 'value',
+        value,
+        dimension,
+        name: relation?.target ?? edge?.target.name ?? 'value',
+        unit: siUnitOf(dimension),
+        meaning: relation?.label ?? edge?.label ?? spec.name,
+        extras: spec.outputs
+            .filter((output) => numbers[output.name] !== undefined)
+            .map((output) => ({ name: output.name, value: numbers[output.name], unit: output.unit, meaning: output.meaning })),
+    };
+}
+/**
+ * The one result builder: evaluate a resolved id at `bindings`. A closed-form
+ * evaluator is its `run`; an edge with none is checked against its contract and
+ * evaluated. {@link evaluateRelation} calls it with `want` `'value'`;
+ * `upt evaluate` calls it with `'all'`, which also requires an input only an
+ * extra output reads. Both get the same {@link Evaluation}.
+ * @internal
+ */
+export function evaluateResolved(found, bindings, want) {
+    if (found.evaluator !== undefined)
+        return closedFormEvaluation(found.evaluator, found.edge, bindings, want);
+    const edge = found.edge;
+    const checked = checkInputs(evaluableContract(found), bindings, want);
+    try {
+        const value = evaluateEdge(edge, { ...checked });
+        // `checkInputs` refused a non-finite input, so a non-finite value comes from the formula.
+        if (!Number.isFinite(value))
+            return { kind: 'unset', formula: edge.label };
+        return {
+            kind: 'value',
+            value,
+            dimension: edge.target.dim,
+            name: edge.target.name,
+            unit: siUnitOf(edge.target.dim),
+            meaning: edge.label,
+            extras: [],
+        };
+    }
+    catch (error) {
+        if (error instanceof CoefficientUnsetError)
+            return { kind: 'unset', formula: error.formula };
+        throw error;
+    }
 }
 /**
  * Evaluate `id` at `bindings`.
@@ -135,26 +169,13 @@ function closedFormEvaluation(spec, edge, bindings) {
  * An unset coefficient returns `{ kind: 'unset', formula }` and no number.
  * A complete finite input whose closed form is not finite (a dropped factor,
  * a singularity) is the same unset result, not a missing input.
+ * A value carries its name, SI unit and meaning, and every extra output whose
+ * inputs were given (`extras`); an input only an extra output reads is not
+ * required.
  *
  * @public
  */
 export function evaluateRelation(id, bindings) {
-    const found = resolveEvaluable(id);
-    if (found.evaluator !== undefined)
-        return closedFormEvaluation(found.evaluator, found.edge, bindings);
-    const edge = found.edge;
-    const checked = checkInputs(evaluableContract(found), bindings);
-    try {
-        const value = evaluateEdge(edge, { ...checked });
-        // `checkInputs` refused a non-finite input, so a non-finite value comes from the formula.
-        if (!Number.isFinite(value))
-            return { kind: 'unset', formula: edge.label };
-        return { kind: 'value', value, dimension: edge.target.dim };
-    }
-    catch (error) {
-        if (error instanceof CoefficientUnsetError)
-            return { kind: 'unset', formula: error.formula };
-        throw error;
-    }
+    return evaluateResolved(resolveEvaluable(id), bindings, 'value');
 }
 //# sourceMappingURL=evaluate-relation.js.map

package/dist/composition/evaluate-relation.js.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate-relation.js","sourceRoot":"","sources":["../../src/composition/evaluate-relation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One public evaluation of a catalog id or a canonical id.\n *\n * A catalog id with a closed-form evaluator is that evaluator's `run`, the\n * same call `upt evaluate` makes, so the library and the CLI check the\n * bindings, the domain and the value in one place. A canonical id is its\n * graph edge, checked against the same {@link checkInputs} contract first.\n * A formula string is not parsed. An unset coefficient is `kind: 'unset'` and\n * is not a number.\n *\n * @module composition/evaluate-relation\n */\n\nimport { EXPECTED_DIMENSION_BY_BRIDGE } from '../dimensional/bridge-check.js';\nimport type { Dimension } from '../dimensional/types.js';\nimport { BRIDGE_EVALUATORS, type EvaluatorSpec } from '../bridges/evaluators.js';\nimport { checkInputs, inputContract, type InputContract } from '../bridges/input-contract.js';\nimport { catalogEdgeKey, parseBridgeId, primaryRelation } from '../bridges/catalog-load.js';\nimport { CANONICAL_EQUATIONS } from '../canonical/registry.js';\nimport { CANONICAL_GROUP_PREFACTORS } from './canonical-prefactors.js';\nimport { CANONICAL_GRAPH } from './canonical-graph.js';\nimport { CATALOG_GRAPH } from './catalog-graph.js';\nimport { CoefficientUnsetError, evaluateEdge, type BridgeEdge } from './edge.js';\n\n/**\n * A sourced number, or an unset coefficient.\n *\n * `dimension` is the edge target. `formula` is the edge label.\n *\n * @public\n */\nexport type Evaluation =\n  | { readonly kind: 'value'; readonly value: number; readonly dimension: Dimension }\n  | { readonly kind: 'unset'; readonly formula: string };\n\n/**\n * An id the library can evaluate: a graph edge, a closed-form evaluator, or both.\n * The CLI and {@link evaluateRelation} both call this. Neither looks the id up again.\n */\nexport interface Evaluable {\n  readonly id: string;\n  readonly edge?: BridgeEdge;\n  readonly evaluator?: EvaluatorSpec;\n}\n\n/**\n * The output of a closed-form evaluator: the quantity it computes and that\n * quantity's dimension. An evaluator with no catalog dimension (a closed form\n * with no AST) names no dimension.\n */\nexport function evaluatorOutput(spec: EvaluatorSpec): { readonly name: string; readonly dimension?: Dimension } {\n  const relation = primaryRelation(spec.bridgeId);\n  const dimension = EXPECTED_DIMENSION_BY_BRIDGE.get(spec.bridgeId);\n  return {\n    name: relation?.target ?? 'value',\n    ...(dimension === undefined ? {} : { dimension }),\n  };\n}\n\n/**\n * Names a canonical id may be bound under besides its sources: the equation's\n * governing names (a registered constant may be overridden), its formula\n * factors, and a bound dimensionless group such as `gamma`.\n */\nfunction canonicalNames(id: string): string[] {\n  const equation = CANONICAL_EQUATIONS.find((candidate) => candidate.id === id);\n  return [\n    ...(equation?.dimensional.governing.map((g) => g.name) ?? []),\n    ...CANONICAL_GROUP_PREFACTORS.filter((group) => group.id === id).map((group) => group.group),\n  ];\n}\n\n/**\n * The declared inputs of an edge with no evaluator: each source under its name\n * and aliases, required; and, optional, its formula factors, the canonical\n * equation's governing names and a bound dimensionless group. A name that\n * already spells a source binds that source, so it is not a second slot.\n */\nfunction edgeContract(id: string, edge: BridgeEdge): InputContract {\n  const sourceSlots = edge.sources.map((source) => ({\n    key: source.name,\n    spellings: [source.name, ...(edge.aliases?.[source.name] ?? [])],\n    alternates: [],\n    optional: false,\n    readBy: 'value' as const,\n    listed: true,\n  }));\n  const spelled = new Set(sourceSlots.flatMap((slot) => slot.spellings));\n  const optional = [...Object.keys(edge.formulaFactors ?? {}), ...canonicalNames(id)].filter((name) => !spelled.has(name));\n  return inputContract(id, [\n    ...sourceSlots,\n    ...[...new Set(optional)].map((name) => ({ key: name, spellings: [name], alternates: [], optional: true, readBy: 'value' as const, listed: false })),\n  ]);\n}\n\n/**\n * The declared inputs of an evaluable id: the closed-form evaluator's contract\n * when it has one, else its edge's. {@link evaluateRelation} checks bindings\n * against exactly this contract.\n * @internal\n */\nexport function evaluableContract(found: Evaluable): InputContract {\n  if (found.evaluator !== undefined) return found.evaluator.contract;\n  return edgeContract(found.id, found.edge!);\n}\n\nfunction idOf(id: string | number): { key: string; numeric: number | undefined } {\n  if (typeof id === 'number') return { key: catalogEdgeKey(id), numeric: id };\n  try {\n    const numeric = parseBridgeId(id);\n    return { key: catalogEdgeKey(numeric), numeric };\n  } catch {\n    return { key: id, numeric: undefined };\n  }\n}\n\n/**\n * The edge and the closed-form evaluator for `id`, when either exists.\n * An unknown id throws. An id with an evaluator and no edge is not unknown.\n */\nexport function resolveEvaluable(id: string | number): Evaluable {\n  const { key, numeric } = idOf(id);\n  const edge = [...CATALOG_GRAPH, ...CANONICAL_GRAPH].find((candidate) => candidate.id === key);\n  const evaluator = numeric === undefined ? undefined : BRIDGE_EVALUATORS.get(numeric);\n  if (edge === undefined && evaluator === undefined) {\n    throw new Error(`evaluateRelation: unknown id '${key}'`);\n  }\n  return {\n    id: key,\n    ...(edge === undefined ? {} : { edge }),\n    ...(evaluator === undefined ? {} : { evaluator }),\n  };\n}\n\n/**\n * The closed form's primary output, through the evaluator's `run`. A record's\n * `value` is the catalog signature; any other number it returns is an extra\n * output, named by `spec.outputs`. A non-finite value at finite inputs is an\n * unset result (a dropped factor, a singularity).\n */\nfunction closedFormEvaluation(\n  spec: EvaluatorSpec,\n  edge: BridgeEdge | undefined,\n  bindings: Readonly<Record<string, number>>,\n): Evaluation {\n  const { value } = spec.run(bindings, 'value');\n  const dimension = edge?.target.dim ?? EXPECTED_DIMENSION_BY_BRIDGE.get(spec.bridgeId);\n  if (dimension === undefined) {\n    throw new Error(`evaluateRelation: be-${spec.bridgeId} has no catalog dimension`);\n  }\n  if (Number.isFinite(value)) return { kind: 'value', value, dimension };\n  // `run` refused a non-finite input, so a non-finite value here comes from the closed form.\n  return { kind: 'unset', formula: edge?.label ?? primaryRelation(spec.bridgeId)?.label ?? spec.name };\n}\n\n/**\n * Evaluate `id` at `bindings`.\n *\n * A catalog id is `be-70` or `70`. A canonical id is `CE-sound-speed`.\n * Binding keys are the inputs' keys, quantity names or aliases.\n * The bindings are checked before the domain: an unknown key throws\n * `UnknownInputError`, a non-number `InputTypeError` (a `TypeError`), a\n * `NaN` or an infinity `NonFiniteInputError`, a key given twice\n * `DuplicateInputError`, an absent input `MissingInputError`.\n * A domain failure throws `DomainViolationError`.\n * An unset coefficient returns `{ kind: 'unset', formula }` and no number.\n * A complete finite input whose closed form is not finite (a dropped factor,\n * a singularity) is the same unset result, not a missing input.\n *\n * @public\n */\nexport function evaluateRelation(\n  id: string | number,\n  bindings: Readonly<Record<string, number>>,\n): Evaluation {\n  const found = resolveEvaluable(id);\n  if (found.evaluator !== undefined) return closedFormEvaluation(found.evaluator, found.edge, bindings);\n  const edge = found.edge!;\n  const checked = checkInputs(evaluableContract(found), bindings);\n  try {\n    const value = evaluateEdge(edge, { ...checked });\n    // `checkInputs` refused a non-finite input, so a non-finite value comes from the formula.\n    if (!Number.isFinite(value)) return { kind: 'unset', formula: edge.label };\n    return { kind: 'value', value, dimension: edge.target.dim };\n  } catch (error) {\n    if (error instanceof CoefficientUnsetError) return { kind: 'unset', formula: error.formula };\n    throw error;\n  }\n}\n"]}
+{"version":3,"file":"evaluate-relation.js","sourceRoot":"","sources":["../../src/composition/evaluate-relation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One public evaluation of a catalog id or a canonical id.\n *\n * A catalog id with a closed-form evaluator is that evaluator's `run`, the\n * same call `upt evaluate` makes, so the library and the CLI check the\n * bindings, the domain and the value in one place. A canonical id is its\n * graph edge, checked against the same {@link checkInputs} contract first.\n * A formula string is not parsed. An unset coefficient is `kind: 'unset'` and\n * is not a number.\n *\n * @module composition/evaluate-relation\n */\n\nimport { EXPECTED_DIMENSION_BY_BRIDGE } from '../dimensional/bridge-check.js';\nimport { siUnitOf } from '../dimensional/algebra.js';\nimport type { Dimension } from '../dimensional/types.js';\nimport { BRIDGE_EVALUATORS, type EvaluatorSpec } from '../bridges/evaluators.js';\nimport { checkInputs, inputContract, type EvaluationWant, type InputContract } from '../bridges/input-contract.js';\nimport { catalogEdgeKey, parseBridgeId, primaryRelation } from '../bridges/catalog-load.js';\nimport { CANONICAL_EQUATIONS } from '../canonical/registry.js';\nimport { CANONICAL_GROUP_PREFACTORS } from './canonical-prefactors.js';\nimport { CANONICAL_GRAPH } from './canonical-graph.js';\nimport { CATALOG_GRAPH } from './catalog-graph.js';\nimport { CoefficientUnsetError, evaluateEdge, type BridgeEdge } from './edge.js';\n\n/**\n * A further number an evaluator returns beside its value (be-52's\n * `precession_arcsec_per_century`), with the unit and meaning its record states.\n *\n * @public\n */\nexport interface ExtraOutput {\n  readonly name: string;\n  readonly value: number;\n  readonly unit: string;\n  readonly meaning: string;\n}\n\n/**\n * A sourced number, or an unset coefficient.\n *\n * A value carries what it is: `name` is the quantity the relation computes\n * (its target), `unit` that quantity's SI unit written from `dimension` (the\n * form `parseUnit` reads back), `meaning` the relation as its record states it\n * (a sign convention included), and `extras` every further output whose inputs\n * were given. `upt evaluate` prints and serializes this object; it computes no\n * label of its own. `formula` is the edge label.\n *\n * @public\n */\nexport type Evaluation =\n  | {\n      readonly kind: 'value';\n      readonly value: number;\n      readonly dimension: Dimension;\n      readonly name: string;\n      readonly unit: string;\n      readonly meaning: string;\n      readonly extras: readonly ExtraOutput[];\n    }\n  | { readonly kind: 'unset'; readonly formula: string };\n\n/**\n * An id the library can evaluate: a graph edge, a closed-form evaluator, or both.\n * The CLI and {@link evaluateRelation} both call this. Neither looks the id up again.\n */\nexport interface Evaluable {\n  readonly id: string;\n  readonly edge?: BridgeEdge;\n  readonly evaluator?: EvaluatorSpec;\n}\n\n/**\n * Names a canonical id may be bound under besides its sources: the equation's\n * governing names (a registered constant may be overridden), its formula\n * factors, and a bound dimensionless group such as `gamma`.\n */\nfunction canonicalNames(id: string): string[] {\n  const equation = CANONICAL_EQUATIONS.find((candidate) => candidate.id === id);\n  return [\n    ...(equation?.dimensional.governing.map((g) => g.name) ?? []),\n    ...CANONICAL_GROUP_PREFACTORS.filter((group) => group.id === id).map((group) => group.group),\n  ];\n}\n\n/**\n * The declared inputs of an edge with no evaluator: each source under its name\n * and aliases, required; and, optional, its formula factors, the canonical\n * equation's governing names and a bound dimensionless group. A name that\n * already spells a source binds that source, so it is not a second slot.\n */\nfunction edgeContract(id: string, edge: BridgeEdge): InputContract {\n  const sourceSlots = edge.sources.map((source) => ({\n    key: source.name,\n    spellings: [source.name, ...(edge.aliases?.[source.name] ?? [])],\n    alternates: [],\n    optional: false,\n    readBy: 'value' as const,\n    listed: true,\n  }));\n  const spelled = new Set(sourceSlots.flatMap((slot) => slot.spellings));\n  const optional = [...Object.keys(edge.formulaFactors ?? {}), ...canonicalNames(id)].filter((name) => !spelled.has(name));\n  return inputContract(id, [\n    ...sourceSlots,\n    ...[...new Set(optional)].map((name) => ({ key: name, spellings: [name], alternates: [], optional: true, readBy: 'value' as const, listed: false })),\n  ]);\n}\n\n/**\n * The declared inputs of an evaluable id: the closed-form evaluator's contract\n * when it has one, else its edge's. {@link evaluateRelation} checks bindings\n * against exactly this contract.\n * @internal\n */\nexport function evaluableContract(found: Evaluable): InputContract {\n  if (found.evaluator !== undefined) return found.evaluator.contract;\n  return edgeContract(found.id, found.edge!);\n}\n\nfunction idOf(id: string | number): { key: string; numeric: number | undefined } {\n  if (typeof id === 'number') return { key: catalogEdgeKey(id), numeric: id };\n  try {\n    const numeric = parseBridgeId(id);\n    return { key: catalogEdgeKey(numeric), numeric };\n  } catch {\n    return { key: id, numeric: undefined };\n  }\n}\n\n/**\n * The edge and the closed-form evaluator for `id`, when either exists.\n * An unknown id throws. An id with an evaluator and no edge is not unknown.\n */\nexport function resolveEvaluable(id: string | number): Evaluable {\n  const { key, numeric } = idOf(id);\n  const edge = [...CATALOG_GRAPH, ...CANONICAL_GRAPH].find((candidate) => candidate.id === key);\n  const evaluator = numeric === undefined ? undefined : BRIDGE_EVALUATORS.get(numeric);\n  if (edge === undefined && evaluator === undefined) {\n    throw new Error(`evaluateRelation: unknown id '${key}'`);\n  }\n  return {\n    id: key,\n    ...(edge === undefined ? {} : { edge }),\n    ...(evaluator === undefined ? {} : { evaluator }),\n  };\n}\n\n/**\n * The closed form through the evaluator's `run`, the one evaluation. A record's\n * `value` is the catalog signature; every other number `run` returns is an\n * extra output, labelled from `spec.outputs`. A non-finite value at finite\n * inputs is an unset result (a dropped factor, a singularity).\n */\nfunction closedFormEvaluation(\n  spec: EvaluatorSpec,\n  edge: BridgeEdge | undefined,\n  bindings: Readonly<Record<string, number>>,\n  want: EvaluationWant,\n): Evaluation {\n  const numbers = spec.run(bindings, want);\n  const relation = primaryRelation(spec.bridgeId);\n  const dimension = edge?.target.dim ?? EXPECTED_DIMENSION_BY_BRIDGE.get(spec.bridgeId);\n  if (dimension === undefined) {\n    throw new Error(`evaluateRelation: be-${spec.bridgeId} has no catalog dimension`);\n  }\n  const value = numbers.value!;\n  // `run` refused a non-finite input, so a non-finite value here comes from the closed form.\n  if (!Number.isFinite(value)) return { kind: 'unset', formula: edge?.label ?? relation?.label ?? spec.name };\n  return {\n    kind: 'value',\n    value,\n    dimension,\n    name: relation?.target ?? edge?.target.name ?? 'value',\n    unit: siUnitOf(dimension),\n    meaning: relation?.label ?? edge?.label ?? spec.name,\n    extras: spec.outputs\n      .filter((output) => numbers[output.name] !== undefined)\n      .map((output) => ({ name: output.name, value: numbers[output.name]!, unit: output.unit, meaning: output.meaning })),\n  };\n}\n\n/**\n * The one result builder: evaluate a resolved id at `bindings`. A closed-form\n * evaluator is its `run`; an edge with none is checked against its contract and\n * evaluated. {@link evaluateRelation} calls it with `want` `'value'`;\n * `upt evaluate` calls it with `'all'`, which also requires an input only an\n * extra output reads. Both get the same {@link Evaluation}.\n * @internal\n */\nexport function evaluateResolved(\n  found: Evaluable,\n  bindings: Readonly<Record<string, number>>,\n  want: EvaluationWant,\n): Evaluation {\n  if (found.evaluator !== undefined) return closedFormEvaluation(found.evaluator, found.edge, bindings, want);\n  const edge = found.edge!;\n  const checked = checkInputs(evaluableContract(found), bindings, want);\n  try {\n    const value = evaluateEdge(edge, { ...checked });\n    // `checkInputs` refused a non-finite input, so a non-finite value comes from the formula.\n    if (!Number.isFinite(value)) return { kind: 'unset', formula: edge.label };\n    return {\n      kind: 'value',\n      value,\n      dimension: edge.target.dim,\n      name: edge.target.name,\n      unit: siUnitOf(edge.target.dim),\n      meaning: edge.label,\n      extras: [],\n    };\n  } catch (error) {\n    if (error instanceof CoefficientUnsetError) return { kind: 'unset', formula: error.formula };\n    throw error;\n  }\n}\n\n/**\n * Evaluate `id` at `bindings`.\n *\n * A catalog id is `be-70` or `70`. A canonical id is `CE-sound-speed`.\n * Binding keys are the inputs' keys, quantity names or aliases.\n * The bindings are checked before the domain: an unknown key throws\n * `UnknownInputError`, a non-number `InputTypeError` (a `TypeError`), a\n * `NaN` or an infinity `NonFiniteInputError`, a key given twice\n * `DuplicateInputError`, an absent input `MissingInputError`.\n * A domain failure throws `DomainViolationError`.\n * An unset coefficient returns `{ kind: 'unset', formula }` and no number.\n * A complete finite input whose closed form is not finite (a dropped factor,\n * a singularity) is the same unset result, not a missing input.\n * A value carries its name, SI unit and meaning, and every extra output whose\n * inputs were given (`extras`); an input only an extra output reads is not\n * required.\n *\n * @public\n */\nexport function evaluateRelation(\n  id: string | number,\n  bindings: Readonly<Record<string, number>>,\n): Evaluation {\n  return evaluateResolved(resolveEvaluable(id), bindings, 'value');\n}\n"]}

package/dist/composition/explain.d.ts

@@ -29,20 +29,11 @@ import type { IdentifiabilityResult } from './identifiability.js';
 import type { RetrodictionResult } from './retrodiction.js';
 import type { Dimension } from '../dimensional/types.js';
 /**
- * Text form of a recovered quantity: `digits` significant digits (15 by default, the precision an
- * evaluator input is already passed at; a statistic such as a residual in σ asks for 3). JSON keeps
- * the number; this is only the printed form. An integer stays an integer (`1`, not `1.0000e+0`).
- * Every command prints a number through this function or through {@link formatExact}.
+ * The printed forms of a number, owned by `core/format` and re-exported here so the commands'
+ * imports stay as they were: every command prints a number through `formatQuantity` or `formatExact`.
  * @internal
  */
-export declare function formatQuantity(value: number, digits?: number): string;
-/**
- * Text form of a computed value that a reader may need to reproduce bit for bit: the shortest
- * decimal that round-trips to the same double (`upt evaluate`'s outputs). A recovered or compared
- * quantity prints through {@link formatQuantity} instead.
- * @internal
- */
-export declare function formatExact(value: number): string;
+export { formatQuantity, formatExact } from '../core/format.js';
 import type { DimensionalDeterminationResult } from '../dimensional/buckingham.js';
 /** One structural derivation of the target, with the recovered value when
  *  ground-truth values were supplied. @public */

package/dist/composition/explain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../src/composition/explain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../src/composition/explain.ts"],"names":[],"mappings":"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"}

package/dist/composition/explain.js

@@ -25,28 +25,17 @@
  */
 import { QUANTITY_IDENTIFICATIONS } from './compose.js';
 import { classifyIdentifiability, forwardClosure } from './identifiability.js';
+import { fixedPoint } from '../canonical/fixed-points.js';
 import { retrodictNode } from './retrodiction.js';
 import { CANONICAL_GROUP_PREFACTORS } from './canonical-prefactors.js';
 import { canonicalById } from '../canonical/registry.js';
+import { formatQuantity } from '../core/format.js';
 /**
- * Text form of a recovered quantity: `digits` significant digits (15 by default, the precision an
- * evaluator input is already passed at; a statistic such as a residual in σ asks for 3). JSON keeps
- * the number; this is only the printed form. An integer stays an integer (`1`, not `1.0000e+0`).
- * Every command prints a number through this function or through {@link formatExact}.
+ * The printed forms of a number, owned by `core/format` and re-exported here so the commands'
+ * imports stay as they were: every command prints a number through `formatQuantity` or `formatExact`.
  * @internal
  */
-export function formatQuantity(value, digits = 15) {
-    return String(Number(value.toPrecision(digits)));
-}
-/**
- * Text form of a computed value that a reader may need to reproduce bit for bit: the shortest
- * decimal that round-trips to the same double (`upt evaluate`'s outputs). A recovered or compared
- * quantity prints through {@link formatQuantity} instead.
- * @internal
- */
-export function formatExact(value) {
-    return String(value);
-}
+export { formatQuantity, formatExact } from '../core/format.js';
 import { dimensionallyDetermines } from '../dimensional/buckingham.js';
 import { collapseSynonymGovernors } from './aliases.js';
 import { formulaShape } from './formula-shape.js';
@@ -61,10 +50,8 @@ import { formulaShape } from './formula-shape.js';
 function encodedMatchesMonomial(edges, target, knownNames, monomial, identifications) {
     if (knownNames.length === 0)
         return true;
-    const base = {};
-    knownNames.forEach((name, i) => {
-        base[name] = 1.7 + 0.3 * i;
-    });
+    // Known i takes 1.7 + 0.3 i: this check's own scheme, stated here; each is then scaled by 4.
+    const base = fixedPoint(knownNames, 1, { base: 1.7, step: 0.3 });
     const read = (values) => {
         const retro = retrodictNode(edges, values, target, { identifications });
         const hit = retro.predictions.find((prediction) => Number.isFinite(prediction.value) && prediction.value !== 0);