universal-physics-tensor 0.4.5

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

@@ -0,0 +1,114 @@
+/**
+ * The TensorEngine contract — the compute interface both v0.3.5 engines
+ * (Float64ReferenceEngine, MathTSEngine) satisfy. See docs/planning/
+ * v0.3.5-Design.md §3, §5.
+ *
+ * `EngineTensor` is an opaque handle; consumers operate on it only through
+ * a TensorEngine. The lowering pass (lowering.ts) builds an `EinsumSpec`
+ * from `computeContraction()`'s `contractionPairs` and hands it to
+ * `engine.einsum()`.
+ *
+ * @module numerical/tensor-engine
+ */
+import type { NestedArray } from './types.js';
+import { EngineCapabilityError } from './errors.js';
+export { EngineCapabilityError };
+/** Opaque rank-N tensor handle. Each engine backs it with its own storage
+ *  (Float64Array, a MathTS Tensor, a future WASM offset); consumers see
+ *  only the shape.
+ *  @public */
+export interface EngineTensor {
+    readonly shape: ReadonlyArray<number>;
+}
+/** One contracted index: the two (operand, axis) coordinates that the
+ *  Einstein summation pairs and sums over.
+ *  @internal */
+export interface EinsumContraction {
+    readonly pair: readonly [readonly [number, number], readonly [number, number]];
+}
+/** One surviving (free) index in the einsum output, in output-axis order.
+ *  @internal */
+export interface EinsumFreeAxis {
+    readonly operand: number;
+    readonly axis: number;
+}
+/** The engine-agnostic einsum plan produced by lowering.ts.
+ *  @public */
+export interface EinsumSpec {
+    readonly contractions: ReadonlyArray<EinsumContraction>;
+    readonly free: ReadonlyArray<EinsumFreeAxis>;
+}
+/**
+ * Result of a forward-mode automatic differentiation pass.
+ * `value` is f(x); `jacobian` is the Jacobian of f at x (Jvp with tangent 1).
+ * @public
+ */
+export interface ForwardGradResult {
+    readonly value: EngineTensor;
+    readonly jacobian: EngineTensor;
+}
+/**
+ * Result of a reverse-mode automatic differentiation pass.
+ * `value` is f(x); `gradient` is ∂L/∂x for cotangent dL/df (ones-like by default).
+ * @public
+ */
+export interface ReverseGradResult {
+    readonly value: EngineTensor;
+    readonly gradient: EngineTensor;
+}
+/** The compute contract. Float64ReferenceEngine and MathTSEngine implement it.
+ *  @public */
+export interface TensorEngine {
+    readonly name: string;
+    fromNested(data: NestedArray, shape: ReadonlyArray<number>): EngineTensor;
+    toNested(t: EngineTensor): NestedArray;
+    einsum(spec: EinsumSpec, ...operands: EngineTensor[]): EngineTensor;
+    matMul(a: EngineTensor, b: EngineTensor): EngineTensor;
+    transpose(t: EngineTensor, perm?: ReadonlyArray<number>): EngineTensor;
+    reshape(t: EngineTensor, shape: ReadonlyArray<number>): EngineTensor;
+    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;
+    /** Optional — no-op for pure-JS engines; a future native engine implements
+     *  real disposal. evaluateNumerical() never relies on it. */
+    dispose?(t: EngineTensor): void;
+    /**
+     * Forward-mode AD (Jacobian-vector product). Always Promise-returning for
+     * uniform consumer semantics (S6 reconciliation fix — no T | Promise<T> union).
+     * Engines without AD support omit this method; call `hasAutogradSupport(engine)`
+     * before invoking.
+     * @public
+     */
+    forwardGrad?(fn: (x: EngineTensor) => EngineTensor, x: EngineTensor): Promise<ForwardGradResult>;
+    /**
+     * Reverse-mode AD (vector-Jacobian product). `cotangent` defaults to
+     * ones-like(value) when omitted. Always Promise-returning (S6).
+     * Engines without AD support omit this method; call `hasAutogradSupport(engine)`
+     * before invoking.
+     * @public
+     */
+    reverseGrad?(fn: (x: EngineTensor) => EngineTensor, x: EngineTensor, cotangent?: EngineTensor): Promise<ReverseGradResult>;
+}
+/**
+ * Returns `true` iff the engine implements both `forwardGrad` and `reverseGrad`.
+ * Use this before invoking AD methods so callers get a clear capability signal
+ * rather than a runtime TypeError.
+ *
+ * @example
+ * ```typescript
+ * if (!hasAutogradSupport(engine)) {
+ *   throw new EngineCapabilityError(engine.name, 'forwardGrad');
+ * }
+ * const { value, jacobian } = await engine.forwardGrad!(fn, x);
+ * ```
+ * @public
+ */
+export declare function hasAutogradSupport(engine: TensorEngine): boolean;
+/** Runtime guard for EinsumSpec — used at the lowering→engine boundary so a
+ *  malformed spec fails loudly rather than producing a wrong-shape tensor.
+ *  @internal */
+export declare function isEinsumSpec(x: unknown): x is EinsumSpec;
+//# sourceMappingURL=tensor-engine.d.ts.map

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

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

package/dist/numerical/tensor-engine.js

@@ -0,0 +1,64 @@
+/**
+ * The TensorEngine contract — the compute interface both v0.3.5 engines
+ * (Float64ReferenceEngine, MathTSEngine) satisfy. See docs/planning/
+ * v0.3.5-Design.md §3, §5.
+ *
+ * `EngineTensor` is an opaque handle; consumers operate on it only through
+ * a TensorEngine. The lowering pass (lowering.ts) builds an `EinsumSpec`
+ * from `computeContraction()`'s `contractionPairs` and hands it to
+ * `engine.einsum()`.
+ *
+ * @module numerical/tensor-engine
+ */
+import { EngineCapabilityError } from './errors.js';
+export { EngineCapabilityError };
+/**
+ * Returns `true` iff the engine implements both `forwardGrad` and `reverseGrad`.
+ * Use this before invoking AD methods so callers get a clear capability signal
+ * rather than a runtime TypeError.
+ *
+ * @example
+ * ```typescript
+ * if (!hasAutogradSupport(engine)) {
+ *   throw new EngineCapabilityError(engine.name, 'forwardGrad');
+ * }
+ * const { value, jacobian } = await engine.forwardGrad!(fn, x);
+ * ```
+ * @public
+ */
+export function hasAutogradSupport(engine) {
+    return typeof engine.forwardGrad === 'function'
+        && typeof engine.reverseGrad === 'function';
+}
+/** Runtime guard for EinsumSpec — used at the lowering→engine boundary so a
+ *  malformed spec fails loudly rather than producing a wrong-shape tensor.
+ *  @internal */
+export function isEinsumSpec(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    const s = x;
+    if (!Array.isArray(s.contractions) || !Array.isArray(s.free))
+        return false;
+    for (const c of s.contractions) {
+        if (typeof c !== 'object' || c === null)
+            return false;
+        const pair = c.pair;
+        if (!Array.isArray(pair) || pair.length !== 2)
+            return false;
+        for (const coord of pair) {
+            if (!Array.isArray(coord) || coord.length !== 2)
+                return false;
+            if (typeof coord[0] !== 'number' || typeof coord[1] !== 'number')
+                return false;
+        }
+    }
+    for (const f of s.free) {
+        if (typeof f !== 'object' || f === null)
+            return false;
+        const fa = f;
+        if (typeof fa.operand !== 'number' || typeof fa.axis !== 'number')
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=tensor-engine.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tensor-engine.js","sourceRoot":"","sources":["../../src/numerical/tensor-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAsGjC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAoB;IACrD,OAAO,OAAO,MAAM,CAAC,WAAW,KAAK,UAAU;WACxC,OAAO,MAAM,CAAC,WAAW,KAAK,UAAU,CAAC;AAClD,CAAC;AAED;;gBAEgB;AAChB,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,CAA+C,CAAC;IAC1D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3E,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACtD,MAAM,IAAI,GAAI,CAAwB,CAAC,IAAI,CAAC;QAC5C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC5D,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC9D,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;gBAAE,OAAO,KAAK,CAAC;QACjF,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACvB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACtD,MAAM,EAAE,GAAG,CAA0C,CAAC;QACtD,IAAI,OAAO,EAAE,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IAClF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/numerical/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared types for the numerical backend. Kept in a tiny module so the
+ * TensorEngine interface and the lowering pass share one definition.
+ *
+ * @module numerical/types
+ */
+/** A scalar, or arbitrarily nested arrays of scalars. The plain-JS shape
+ *  that crosses the public boundary of the numerical module.
+ *  @public */
+export type NestedArray = number | NestedArray[];
+import type { GridField } from './grid-field.js';
+/** Concrete inputs for a numerical evaluation. See v0.3.5-Design.md §5.
+ *  @public */
+export interface NumericalInputs {
+    /** Component values per tensor-symbol / metric-tensor / scalar-symbol, by name. */
+    readonly tensors: ReadonlyMap<string, NestedArray>;
+    /** Index dimensionality N for kronecker-delta (and any node whose size is
+     *  not otherwise determined). Defaults to 4 (spacetime) when omitted. */
+    readonly dimension?: number;
+    /** For 'numerical-fn' tensor-symbols (Task 10). */
+    readonly fields?: ReadonlyMap<string, (coords: ReadonlyArray<number>) => NestedArray>;
+    /** For 'grid' tensor-symbols (Task 10). */
+    readonly grids?: ReadonlyMap<string, GridField>;
+    /** Explicit pre-computed derivatives for 'symbolic' tensor-symbols under a
+     *  pderiv, keyed `${symbolName}/${coordLabel}` (Task 10). */
+    readonly derivatives?: ReadonlyMap<string, NestedArray>;
+    /** Coordinate values for partial-derivative evaluation (Task 10). */
+    readonly coords?: ReadonlyMap<string, number>;
+    /**
+     * v0.4.0: for metric-tensor nodes with derivativeStrategy='supplied' under
+     * a christoffel/covariant-derivative lowering. Keyed `${metricName}/${coordLabel}`
+     * (e.g., 'g/μ'). Each value is the full metric Jacobian slice — shape [N,N]
+     * for the partial derivative of an N×N metric w.r.t. one coordinate.
+     */
+    readonly metricDerivatives?: ReadonlyMap<string, NestedArray>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/numerical/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;cAEc;AACd,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,EAAE,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;cACc;AACd,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACnD;6EACyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,WAAW,CAAC,CAAC;IACtF,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAChD;iEAC6D;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACxD,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CAC/D"}

package/dist/numerical/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared types for the numerical backend. Kept in a tiny module so the
+ * TensorEngine interface and the lowering pass share one definition.
+ *
+ * @module numerical/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/numerical/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/numerical/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "universal-physics-tensor",
+  "version": "0.4.5",
+  "description": "Computational framework for exploring unified physics through tensor formalism",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./numerical/mathts-engine": {
+      "types": "./dist/numerical/mathts-engine.d.ts",
+      "import": "./dist/numerical/mathts-engine.js",
+      "default": "./dist/numerical/mathts-engine.js"
+    }
+  },
+  "directories": {
+    "doc": "docs",
+    "example": "examples",
+    "test": "tests"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "smoke": "node test-example.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "tsc && vitest run",
+    "bench": "vitest bench",
+    "bench:ci": "vitest bench --reporter=verbose"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "physics",
+    "tensor",
+    "unification",
+    "quantum-mechanics",
+    "general-relativity",
+    "bridge-equations",
+    "theoretical-physics",
+    "computational-physics"
+  ],
+  "author": "Daniel Simon Jr. <danielsimonjr@users.noreply.github.com>",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielsimonjr/universal-physics-tensor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/danielsimonjr/universal-physics-tensor/issues"
+  },
+  "homepage": "https://github.com/danielsimonjr/universal-physics-tensor#readme",
+  "devDependencies": {
+    "@types/node": "^24.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "optionalDependencies": {
+    "@danielsimonjr/mathts-tensor": "^0.1.0",
+    "@danielsimonjr/mathts-autograd": "^0.1.0"
+  }
+}