universal-physics-tensor 0.47.1 → 1.0.2

package/dist/composition/buckingham-filter.js

@@ -0,0 +1,64 @@
+/**
+ * Buckingham filter for one target and the variables that govern it.
+ *
+ * Calls {@link dimensionallyDetermines} and {@link buckinghamPi}. It does
+ * not reimplement the null space and it does not call the probe generator.
+ * The determination fields are that engine's result: form only, no constant.
+ *
+ * A target outside the governing span is absent. A survivor names the
+ * `PhysJS.Dimensional` theorem for its shape. The covers line begins with
+ * `derivation-step:` and names the hypothesis that theorem leaves open.
+ *
+ * @module composition/buckingham-filter
+ */
+import { equals } from '../dimensional/algebra.js';
+import { buckinghamPi, dimensionallyDetermines } from '../dimensional/buckingham.js';
+import { DIMENSIONLESS } from '../dimensional/types.js';
+function formatExponents(monomial, order) {
+    return order.map((name) => `${name}^${monomial[name] ?? 0}`).join(' · ');
+}
+/** Two nonzero exponents of equal magnitude and opposite sign: a ratio. */
+function isPureRatio(exponents) {
+    const nonzero = Object.entries(exponents).filter(([, exp]) => exp !== 0);
+    if (nonzero.length !== 2)
+        return false;
+    return nonzero[0][1] === -nonzero[1][1];
+}
+function record(determination, theorem, covers) {
+    return { ...determination, theorem, kind: 'derivation-step', covers };
+}
+/**
+ * The dimensional shape of `target` given `governing`, or absent when the
+ * target's dimension is not in their span.
+ *
+ * @internal
+ */
+export function buckinghamFilter(target, governing) {
+    const determination = dimensionallyDetermines(target, governing);
+    const full = buckinghamPi(governing.length > 0 ? [target, ...governing] : [target]);
+    const governingResult = governing.length > 0 ? buckinghamPi(governing) : undefined;
+    const govCount = governingResult?.piGroupCount ?? 0;
+    if (full.piGroupCount === govCount)
+        return undefined;
+    if (determination.determined && determination.monomial !== undefined) {
+        const nonzero = Object.entries(determination.monomial).filter(([, exp]) => exp !== 0);
+        const product = nonzero.length === 2 && nonzero.every(([, exp]) => exp === 1);
+        const theorem = product
+            ? 'PhysJS.Dimensional.product_shape'
+            : 'PhysJS.Dimensional.monomial_form';
+        const exponents = formatExponents(determination.monomial, determination.governing);
+        const covers = product
+            ? `derivation-step: ${theorem}. Exponent vector ${exponents}. f(1,1) is unfixed.`
+            : `derivation-step: ${theorem}. Exponent vector ${exponents}. f(1,…,1) is unfixed. The exponent vector is a hypothesis. A unit change that can reach every positive tuple is a hypothesis.`;
+        return record(determination, theorem, covers);
+    }
+    if (govCount === 1 && full.piGroupCount === 2 && governingResult !== undefined) {
+        const group = governingResult.piGroups[0]?.exponents ?? {};
+        if (isPureRatio(group) && equals(target.dim, DIMENSIONLESS)) {
+            return record(determination, 'PhysJS.Dimensional.ratio_power_invariant', 'derivation-step: PhysJS.Dimensional.ratio_power_invariant. The real power p is unfixed.');
+        }
+        return record(determination, 'PhysJS.Dimensional.ratio_shape', 'derivation-step: PhysJS.Dimensional.ratio_shape. The function of the ratio is unfixed.');
+    }
+    return record(determination, null, 'derivation-step: a free π-group leaves no unique monomial.');
+}
+//# sourceMappingURL=buckingham-filter.js.map

package/dist/composition/buckingham-filter.js.map

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

package/dist/composition/canonical-compare.d.ts

@@ -35,36 +35,49 @@ export interface CanonicalComparison {
     readonly detail?: string;
     /** `[yours, canonical]` for each variable paired by dimension, not by name (persona finding N1). */
     readonly paired?: readonly (readonly [string, string])[];
+    /**
+     * True when neither side has a free variable (every name is a registered constant, persona
+     * finding W5): the two sides are compared once, at the SI constant values, so the form is not
+     * tested, only the value.
+     */
+    readonly constantsOnly?: true;
+    /**
+     * Present when your target matched through the catalog bridge this entry restates
+     * (`restatesBridge`), not by the entry's own target name: that bridge's id and the entry's target.
+     */
+    readonly targetVia?: {
+        readonly bridge: string;
+        readonly its: string;
+    };
+    /**
+     * Set when the comparison evaluated c, ħ, h or G at a non-SI value
+     * (`--natural` / `--geometrized`). Absent on an SI comparison.
+     */
+    readonly evaluatedAt?: string;
 }
 /** A user source variable; with a dimension it may pair with a differently named canonical variable. */
 export type ComparisonSource = string | {
     readonly name: string;
     readonly dim: Dimension;
 };
-/**
- * Compare a user formula with every canonical equation that has the same
- * target and the same non-constant variables. The target must match by name
- * (after `_` → `-`): pairing it by dimension would reach every law of that
- * dimension. Each source matches a variable by name, or, when the source
- * carries a dimension, by a dimension exactly one remaining variable carries
- * (`velocity` → CE-kinetic-energy's `speed`); such pairs are listed in
- * `paired`. A non-unique pairing is reported as `not-compared`, never guessed.
- * `evaluateUser` receives values keyed by the user's (normalized) source names.
- * Returns one comparison per matching entry, in registry order; empty when
- * no entry matches.
- *
- * @internal
- */
-export declare function compareWithCanonical(target: string, sources: readonly ComparisonSource[], evaluateUser: (values: Readonly<Record<string, number>>) => number, entries?: readonly CanonicalEquation[]): CanonicalComparison[];
+export declare function compareWithCanonical(target: string, sources: readonly ComparisonSource[], evaluateUser: (values: Readonly<Record<string, number>>) => number, entries?: readonly CanonicalEquation[], constantOverrides?: Readonly<Record<string, number>>): CanonicalComparison[];
 /**
  * Compare a `TARGET = EXPR` user equation (the `upt map --equation` input) with
  * the canonical registry. Names resolve onto `catalogDims` the way
  * `analyzeUserEquation` resolves them; `pi` and `tau` are the only named numbers.
+ * The right-hand side is dimension-checked through `parsePhysics` and evaluated by
+ * the active formula parser, the one `upt eval` uses, so a comparison accepts every
+ * function `eval` accepts (`ln(2)`, `asin`, `atan2`; persona finding W7). A registered
+ * constant takes its SI value, as in the canonical AST, unless
+ * `constantOverrides` replaces c, ħ, h or G (`--natural` / `--geometrized`).
  * Returns `[]` when the equation does not parse or no entry matches.
  *
  * @internal
  */
-export declare function compareUserEquation(equation: string, catalogDims: ReadonlyMap<string, Dimension>): Promise<CanonicalComparison[]>;
+export declare function compareUserEquation(equation: string, catalogDims: ReadonlyMap<string, Dimension>, options?: {
+    readonly bindShortNames?: boolean;
+    readonly constantOverrides?: Readonly<Record<string, number>>;
+}): Promise<CanonicalComparison[]>;
 /**
  * The report lines for a comparison result, shared by `upt map --equation` and
  * `upt derive`. An empty result is itself a line: a dimensional MATCH never

package/dist/composition/canonical-compare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canonical-compare.d.ts","sourceRoot":"","sources":["../../src/composition/canonical-compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAsB5E,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,qBAAqB,GAAG,cAAc,CAAC;IACrF,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oGAAoG;IACpG,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;CAC1D;AAED,wGAAwG;AACxG,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,CAAC;AA+G3F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,YAAY,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,MAAM,EAClE,OAAO,GAAE,SAAS,iBAAiB,EAAwB,GAC1D,mBAAmB,EAAE,CAqFvB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GAC1C,OAAO,CAAC,mBAAmB,EAAE,CAAC,CA0BhC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,SAAS,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAIhF;AAED,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAgBjE"}
+{"version":3,"file":"canonical-compare.d.ts","sourceRoot":"","sources":["../../src/composition/canonical-compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AA4C5E,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,qBAAqB,GAAG,cAAc,CAAC;IACrF,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oGAAoG;IACpG,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;IACzD;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wGAAwG;AACxG,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,CAAC;AA8R3F,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,YAAY,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,MAAM,EAClE,OAAO,GAAE,SAAS,iBAAiB,EAAwB,EAC3D,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACnD,mBAAmB,EAAE,CA4MvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EAC3C,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GAC7G,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAiDhC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,SAAS,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAIhF;AAED,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAwBjE"}