universal-physics-tensor 0.4.5

package/dist/numerical/engine-registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Engine registry — selects the active TensorEngine. v0.4.0: when both
+ * @danielsimonjr/mathts-tensor AND @danielsimonjr/mathts-autograd are
+ * installed, getActiveEngine() returns MathTSEngine. Falls back to
+ * Float64ReferenceEngine (the zero-dep default) with a one-time
+ * console.warn (suppressible via UPT_QUIET_FALLBACK=1) when either dep
+ * is absent.
+ *
+ * HONEST FRAMING: both engines run the same naive O(n) algorithms in
+ * v0.4.0. This default flip is a dep-shape + code-path-signal change,
+ * NOT a performance win. MathTSEngine becomes the default because that
+ * is where the autograd capability (AD) lives.
+ *
+ * I4 fix (Promise-cache): the Promise itself is cached, not the resolved
+ * instance. Two concurrent first-time callers therefore observe the same
+ * in-flight Promise and never race to create separate engine instances.
+ *
+ * I5 fix (browser guard): `process` is undefined in browser bundlers.
+ * All access is guarded by `typeof process !== 'undefined'`.
+ *
+ * @module numerical/engine-registry
+ */
+import type { TensorEngine } from './tensor-engine.js';
+/**
+ * The TensorEngine currently used by the `evaluateNumerical*` entry points
+ * when no per-call `EvaluateOptions.engine` is supplied.
+ *
+ * v0.4.0: returns MathTSEngine when both @danielsimonjr/mathts-tensor AND
+ * @danielsimonjr/mathts-autograd are installed; otherwise Float64ReferenceEngine.
+ *
+ * I4: returns a cached Promise — concurrent first-time callers share the
+ * same in-flight resolution, so at most one MathTSEngine is ever constructed.
+ *
+ * @public
+ */
+export declare function getActiveEngine(): Promise<TensorEngine>;
+/**
+ * Set the process-wide active TensorEngine (e.g. to `MathTSEngine`).
+ * Wraps the engine in a resolved Promise to match the async getActiveEngine
+ * contract and invalidate any prior in-flight detection.
+ * @public
+ */
+export declare function setActiveEngine(engine: TensorEngine): void;
+/**
+ * Reset the Promise-cache and detection state for testing purposes only.
+ * Not part of the public API surface; NOT exported from the root barrel.
+ * @internal
+ */
+export declare function resetEngineForTesting(): void;
+//# sourceMappingURL=engine-registry.d.ts.map

package/dist/numerical/engine-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-registry.d.ts","sourceRoot":"","sources":["../../src/numerical/engine-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA+CvD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC,CAU7D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C"}

package/dist/numerical/engine-registry.js

@@ -0,0 +1,82 @@
+import { Float64ReferenceEngine } from './float64-engine.js';
+// Module-level cache. Stores a Promise so that concurrent first-time calls
+// to getActiveEngine() both await the same in-flight detection, never racing
+// to construct two separate engine instances (I4 fix).
+let _activeEngineP;
+// Cache the detection result so we don't re-import on every getActiveEngine()
+// call after the first. Reset by resetEngineForTesting() in tests.
+let _resolvedDefault;
+/**
+ * Attempt to import both optional peer deps. Returns 'mathts' when both are
+ * present; 'float64' otherwise. Emits a one-time console.warn on fallback
+ * (suppressible via UPT_QUIET_FALLBACK=1).
+ */
+async function detectDefault() {
+    if (_resolvedDefault !== undefined)
+        return _resolvedDefault;
+    try {
+        await import('@danielsimonjr/mathts-tensor');
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore — @danielsimonjr/mathts-autograd is an optional peer dep with
+        // no bundled type declarations; the try-catch handles the absent case.
+        await import('@danielsimonjr/mathts-autograd');
+        _resolvedDefault = 'mathts';
+    }
+    catch {
+        // I5 fix: `process` is undefined in browser bundlers; guard before reading.
+        const quiet = typeof process !== 'undefined' && process.env?.UPT_QUIET_FALLBACK === '1';
+        if (!quiet) {
+            console.warn('[universal-physics-tensor v0.4.0] @danielsimonjr/mathts-tensor and/or '
+                + '@danielsimonjr/mathts-autograd not installed. '
+                + 'Falling back to Float64ReferenceEngine. '
+                + 'Install both peers for MathTS-default + autograd (AD) support. '
+                + '(Suppress this warning with UPT_QUIET_FALLBACK=1.)');
+        }
+        _resolvedDefault = 'float64';
+    }
+    return _resolvedDefault;
+}
+// @public: getActiveEngine/setActiveEngine are part of the consumer-facing
+// engine-switching contract (re-exported from the root barrel).
+/**
+ * The TensorEngine currently used by the `evaluateNumerical*` entry points
+ * when no per-call `EvaluateOptions.engine` is supplied.
+ *
+ * v0.4.0: returns MathTSEngine when both @danielsimonjr/mathts-tensor AND
+ * @danielsimonjr/mathts-autograd are installed; otherwise Float64ReferenceEngine.
+ *
+ * I4: returns a cached Promise — concurrent first-time callers share the
+ * same in-flight resolution, so at most one MathTSEngine is ever constructed.
+ *
+ * @public
+ */
+export async function getActiveEngine() {
+    _activeEngineP ??= (async () => {
+        const choice = await detectDefault();
+        if (choice === 'mathts') {
+            const { MathTSEngine } = await import('./mathts-engine.js');
+            return new MathTSEngine();
+        }
+        return new Float64ReferenceEngine();
+    })();
+    return _activeEngineP;
+}
+/**
+ * Set the process-wide active TensorEngine (e.g. to `MathTSEngine`).
+ * Wraps the engine in a resolved Promise to match the async getActiveEngine
+ * contract and invalidate any prior in-flight detection.
+ * @public
+ */
+export function setActiveEngine(engine) {
+    _activeEngineP = Promise.resolve(engine);
+}
+/**
+ * Reset the Promise-cache and detection state for testing purposes only.
+ * Not part of the public API surface; NOT exported from the root barrel.
+ * @internal
+ */
+export function resetEngineForTesting() {
+    _activeEngineP = undefined;
+    _resolvedDefault = undefined;
+}
+//# sourceMappingURL=engine-registry.js.map

package/dist/numerical/engine-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-registry.js","sourceRoot":"","sources":["../../src/numerical/engine-registry.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,2EAA2E;AAC3E,6EAA6E;AAC7E,uDAAuD;AACvD,IAAI,cAAiD,CAAC;AAEtD,8EAA8E;AAC9E,mEAAmE;AACnE,IAAI,gBAAkD,CAAC;AAEvD;;;;GAIG;AACH,KAAK,UAAU,aAAa;IAC1B,IAAI,gBAAgB,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAC;IAC5D,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,8BAA8B,CAAC,CAAC;QAC7C,6DAA6D;QAC7D,2EAA2E;QAC3E,uEAAuE;QACvE,MAAM,MAAM,CAAC,gCAAgC,CAAC,CAAC;QAC/C,gBAAgB,GAAG,QAAQ,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,MAAM,KAAK,GACT,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,kBAAkB,KAAK,GAAG,CAAC;QAC5E,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CACV,wEAAwE;kBACtE,gDAAgD;kBAChD,0CAA0C;kBAC1C,iEAAiE;kBACjE,oDAAoD,CACvD,CAAC;QACJ,CAAC;QACD,gBAAgB,GAAG,SAAS,CAAC;IAC/B,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,2EAA2E;AAC3E,gEAAgE;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,cAAc,KAAK,CAAC,KAAK,IAAI,EAAE;QAC7B,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;QACrC,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;YAC5D,OAAO,IAAI,YAAY,EAAE,CAAC;QAC5B,CAAC;QACD,OAAO,IAAI,sBAAsB,EAAE,CAAC;IACtC,CAAC,CAAC,EAAE,CAAC;IACL,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB;IACnC,cAAc,GAAG,SAAS,CAAC;IAC3B,gBAAgB,GAAG,SAAS,CAAC;AAC/B,CAAC"}

package/dist/numerical/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Numerical-backend error type. Subclass of UPTError so downstream
+ * consumers discriminate UPT-source errors uniformly with `instanceof`.
+ *
+ * @module numerical/errors
+ */
+import { UPTError } from '../dimensional/errors.js';
+/**
+ * Error type thrown by the numerical-contraction backend. Subclass of
+ * `UPTError` so consumers can discriminate UPT-source errors with `instanceof`.
+ * @public
+ */
+export declare class NumericalBackendError extends UPTError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a TensorEngine method required for an operation is not
+ * implemented by the active engine (e.g. forwardGrad/reverseGrad on
+ * Float64ReferenceEngine). Call `hasAutogradSupport(engine)` before
+ * invoking AD methods to avoid this error.
+ * @public
+ */
+export declare class EngineCapabilityError extends NumericalBackendError {
+    readonly engineName: string;
+    readonly missingMethod: string;
+    constructor(engineName: string, missingMethod: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/numerical/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/numerical/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;gBACrC,OAAO,EAAE,MAAM;CAK5B;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,qBAAqB;aAE5C,UAAU,EAAE,MAAM;aAClB,aAAa,EAAE,MAAM;gBADrB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM;CASxC"}

package/dist/numerical/errors.js

@@ -0,0 +1,39 @@
+/**
+ * Numerical-backend error type. Subclass of UPTError so downstream
+ * consumers discriminate UPT-source errors uniformly with `instanceof`.
+ *
+ * @module numerical/errors
+ */
+import { UPTError } from '../dimensional/errors.js';
+/**
+ * Error type thrown by the numerical-contraction backend. Subclass of
+ * `UPTError` so consumers can discriminate UPT-source errors with `instanceof`.
+ * @public
+ */
+export class NumericalBackendError extends UPTError {
+    constructor(message) {
+        super(message);
+        this.name = 'NumericalBackendError';
+        Object.setPrototypeOf(this, NumericalBackendError.prototype);
+    }
+}
+/**
+ * Thrown when a TensorEngine method required for an operation is not
+ * implemented by the active engine (e.g. forwardGrad/reverseGrad on
+ * Float64ReferenceEngine). Call `hasAutogradSupport(engine)` before
+ * invoking AD methods to avoid this error.
+ * @public
+ */
+export class EngineCapabilityError extends NumericalBackendError {
+    engineName;
+    missingMethod;
+    constructor(engineName, missingMethod) {
+        super(`Engine "${engineName}" does not implement "${missingMethod}". ` +
+            `Call \`hasAutogradSupport(engine)\` to detect support before invoking.`);
+        this.engineName = engineName;
+        this.missingMethod = missingMethod;
+        this.name = 'EngineCapabilityError';
+        Object.setPrototypeOf(this, EngineCapabilityError.prototype);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/numerical/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/numerical/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,QAAQ;IACjD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,qBAAsB,SAAQ,qBAAqB;IAE5C;IACA;IAFlB,YACkB,UAAkB,EAClB,aAAqB;QAErC,KAAK,CACH,WAAW,UAAU,yBAAyB,aAAa,KAAK;YAChE,wEAAwE,CACzE,CAAC;QANc,eAAU,GAAV,UAAU,CAAQ;QAClB,kBAAa,GAAb,aAAa,CAAQ;QAMrC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/numerical/float64-engine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Float64ReferenceEngine — the pure-TypeScript, Float64Array-backed
+ * TensorEngine implementation. v0.3.5's default engine. Zero runtime
+ * dependencies. Naive O(n) algorithms: a correctness baseline, not a
+ * performance target (v0.3.5-Design.md §13). MathTSEngine (Task 11) is
+ * the performance answer.
+ *
+ * @module numerical/float64-engine
+ */
+import type { EngineTensor, TensorEngine, EinsumSpec, ForwardGradResult, ReverseGradResult } from './tensor-engine.js';
+import type { NestedArray } from './types.js';
+/**
+ * The pure-TypeScript, zero-dependency `TensorEngine` — v0.3.5's default
+ * engine and the correctness baseline for the conformance suite.
+ * @public
+ */
+export declare class Float64ReferenceEngine implements TensorEngine {
+    readonly name = "Float64ReferenceEngine";
+    fromNested(data: NestedArray, shape: ReadonlyArray<number>): EngineTensor;
+    toNested(t: EngineTensor): NestedArray;
+    add(a: EngineTensor, b: EngineTensor): EngineTensor;
+    sub(a: EngineTensor, b: EngineTensor): EngineTensor;
+    mul(a: EngineTensor, b: EngineTensor): EngineTensor;
+    scale(t: EngineTensor, k: number): EngineTensor;
+    identity(n: number): EngineTensor;
+    normInf(t: EngineTensor): number;
+    reshape(t: EngineTensor, shape: ReadonlyArray<number>): EngineTensor;
+    transpose(t: EngineTensor, perm?: ReadonlyArray<number>): EngineTensor;
+    matMul(a: EngineTensor, b: EngineTensor): EngineTensor;
+    einsum(spec: EinsumSpec, ...operands: EngineTensor[]): EngineTensor;
+    /**
+     * Compute the value and full Jacobian of `fn` at point `x` using
+     * forward-mode automatic differentiation (dual numbers).
+     *
+     * Returns `{ value, jacobian }` where `jacobian.shape = [...value.shape, ...x.shape]`
+     * (row-major). `jacobian.data[kY * xSize + kX] = ∂y[kY] / ∂x[kX]`.
+     *
+     * Guard: if `fn` returns a non-EngineDualTensor, throws a clear error
+     * ("AD-traceable" guard, reconciliation fix S6/I2).
+     */
+    forwardGrad(fn: (x: EngineTensor) => EngineTensor, x: EngineTensor): Promise<ForwardGradResult>;
+    /**
+     * Compute the value and gradient (VJP) of `fn` at point `x` using
+     * reverse-mode automatic differentiation (tape).
+     *
+     * `cotangent` defaults to ones-like(value). For non-scalar outputs,
+     * cotangent.shape must match value.shape.
+     *
+     * Guard: if `fn` returns a non-EngineTapedTensor, throws a clear error.
+     */
+    reverseGrad(fn: (x: EngineTensor) => EngineTensor, x: EngineTensor, cotangent?: EngineTensor): Promise<ReverseGradResult>;
+}
+//# sourceMappingURL=float64-engine.d.ts.map

package/dist/numerical/float64-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"float64-engine.d.ts","sourceRoot":"","sources":["../../src/numerical/float64-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAyW9C;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,YAAY;IACzD,QAAQ,CAAC,IAAI,4BAA4B;IAEzC,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,YAAY;IAIzE,QAAQ,CAAC,CAAC,EAAE,YAAY,GAAG,WAAW;IAItC,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,YAAY;IAWnD,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,YAAY;IAWnD,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,YAAY;IAWnD,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY;IAe/C,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY;IAMjC,OAAO,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM;IAUhC,OAAO,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,YAAY;IAWpE,SAAS,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,YAAY;IAoBtE,MAAM,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,YAAY;IAwBtD,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY;IAsFnE;;;;;;;;;OASG;IACG,WAAW,CACf,EAAE,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,YAAY,EACrC,CAAC,EAAE,YAAY,GACd,OAAO,CAAC,iBAAiB,CAAC;IAgD7B;;;;;;;;OAQG;IACG,WAAW,CACf,EAAE,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,YAAY,EACrC,CAAC,EAAE,YAAY,EACf,SAAS,CAAC,EAAE,YAAY,GACvB,OAAO,CAAC,iBAAiB,CAAC;CA2C9B"}