@danielsimonjr/mathts-tensor 0.2.19 → 0.2.20

package/dist/Tensor.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Tensor — rank-N, Float64Array-backed, row-major dense tensor. The
+ * compute primitive behind @danielsimonjr/mathts-tensor. Construction,
+ * elementwise, einsum, matMul, transpose, reshape live here.
+ *
+ * Element-wise and data-movement ops are straightforward O(n) loops (a
+ * correctness baseline). Heavy ops delegate to the standard packages rather
+ * than reinventing them: `matMul` uses matrix's backend-selected multiply
+ * (SIMD-WASM for large inputs), and the decompositions (in `operations/`)
+ * route through matrix's `svd`/`eig`/`lu`/`qr`/`cholesky`. Storage mirrors
+ * DenseMatrix (Float64Array, row-major), generalised to arbitrary rank.
+ */
+import { DenseMatrix } from '@danielsimonjr/mathts-matrix';
+import type { NestedArray as CoreNestedArray } from '@danielsimonjr/mathts-core/internal';
+import { Index } from './named-index.js';
+/**
+ * Consolidated onto `@danielsimonjr/mathts-core`'s generic `NestedArray<T>`,
+ * specialised to `number` (Tensor is Float64Array-backed) — see
+ * docs/Architecture/duplicate-symbols.json.
+ */
+export type NestedArray = CoreNestedArray<number>;
+export interface EinsumSpec {
+    readonly contractions: ReadonlyArray<{
+        readonly pair: readonly [readonly [number, number], readonly [number, number]];
+    }>;
+    readonly free: ReadonlyArray<{
+        readonly operand: number;
+        readonly axis: number;
+    }>;
+}
+export declare class Tensor {
+    readonly shape: ReadonlyArray<number>;
+    readonly data: Float64Array;
+    /** Optional per-axis Index labels. When set, enables `contract`, `replaceIndex`, `axisOf`. */
+    readonly axisLabels?: ReadonlyArray<Index>;
+    constructor(shape: ReadonlyArray<number>, data: Float64Array, axisLabels?: ReadonlyArray<Index>);
+    static sizeOf(shape: ReadonlyArray<number>): number;
+    static rowMajorStrides(shape: ReadonlyArray<number>): number[];
+    static fromNested(data: NestedArray, shape: ReadonlyArray<number>): Tensor;
+    static identity(n: number): Tensor;
+    toNested(): NestedArray;
+    /**
+     * Build a rank-2 Tensor from a native DenseMatrix. Bridges the tensor and
+     * matrix packages so matrix data can flow into rank-N / autodiff code.
+     */
+    static fromDenseMatrix(m: DenseMatrix): Tensor;
+    /**
+     * Convert a rank-2 Tensor to a native DenseMatrix. Throws for any other rank.
+     */
+    toDenseMatrix(): DenseMatrix;
+    private sameShape;
+    private elementwise;
+    add(other: Tensor | number): Tensor;
+    sub(other: Tensor | number): Tensor;
+    mul(other: Tensor | number): Tensor;
+    scale(k: number): Tensor;
+    normInf(): number;
+    /**
+     * Compute the broadcast output shape of two shapes following NumPy rules:
+     * right-align the two shapes; a dimension of 1 broadcasts against any size;
+     * missing leading axes are treated as length-1.
+     * Throws with message including both shape arrays on incompatibility.
+     */
+    static broadcastShape(a: ReadonlyArray<number>, b: ReadonlyArray<number>): number[];
+    /**
+     * Apply a binary elementwise op with NumPy-style broadcasting.
+     * Both tensors are read via virtual broadcast indices — no data is copied
+     * until the output is written.
+     */
+    private static broadcastOp;
+    /**
+     * Generic strided reduction over a set of axes.
+     *
+     * `init` is the neutral element; `combine` folds one new value into the
+     * accumulator; `finalise` (optional) post-processes the accumulator once
+     * all elements have been visited.
+     */
+    private reduceAxes;
+    /**
+     * Sum elements along the given axis/axes (or all axes if omitted).
+     * `keepDims: true` preserves reduced axes as length-1.
+     */
+    sum(axis?: number | ReadonlyArray<number>, opts?: {
+        keepDims?: boolean;
+    }): Tensor;
+    /**
+     * Arithmetic mean along the given axis/axes (or all axes if omitted).
+     */
+    mean(axis?: number | ReadonlyArray<number>, opts?: {
+        keepDims?: boolean;
+    }): Tensor;
+    /**
+     * Element-wise maximum along the given axis/axes (or all axes if omitted).
+     * NaN propagates (matches NumPy default behaviour).
+     */
+    max(axis?: number | ReadonlyArray<number>, opts?: {
+        keepDims?: boolean;
+    }): Tensor;
+    /**
+     * Element-wise minimum along the given axis/axes (or all axes if omitted).
+     * NaN propagates (matches NumPy default behaviour).
+     */
+    min(axis?: number | ReadonlyArray<number>, opts?: {
+        keepDims?: boolean;
+    }): Tensor;
+    /**
+     * Product of elements along the given axis/axes (or all axes if omitted).
+     */
+    prod(axis?: number | ReadonlyArray<number>, opts?: {
+        keepDims?: boolean;
+    }): Tensor;
+    /**
+     * p-norm of the tensor.
+     *
+     * - `p = 2` (default): Euclidean / Frobenius norm — `sqrt(sum x_i^2)`.
+     * - `p = 'fro'`: alias for p=2 (Frobenius).
+     * - `p = 'inf'`: max of absolute values.
+     * - `p = '-inf'`: min of absolute values.
+     * - numeric p: `(sum |x_i|^p)^(1/p)`.
+     *
+     * When `axis` is given, the norm is computed along that single axis and the
+     * result has rank reduced by 1 (or stays the same with `keepDims`).
+     * When `axis` is omitted, the norm is computed over all elements.
+     */
+    norm(opts?: {
+        p?: number | 'inf' | '-inf' | 'fro';
+        axis?: number;
+        keepDims?: boolean;
+    }): Tensor;
+    /**
+     * Generalised dot product (NumPy `tensordot`) over explicitly specified axis pairs.
+     *
+     * `axes[i] = [a, b]` contracts axis `a` of `this` with axis `b` of `other`.
+     * The result shape is `this`'s non-contracted axes followed by `other`'s
+     * non-contracted axes (NumPy convention).
+     *
+     * Delegates to `Tensor.einsum` under the hood.
+     */
+    tensordot(other: Tensor, axes: ReadonlyArray<readonly [number, number]>): Tensor;
+    /**
+     * Normalise an `axis` argument into a sorted list of axis indices.
+     * `undefined` ⇒ all axes (reduce everything to a rank-0 scalar).
+     */
+    private resolveAxes;
+    private static forEachIndex;
+    private static flatIndex;
+    reshape(shape: ReadonlyArray<number>): Tensor;
+    transpose(perm?: ReadonlyArray<number>): Tensor;
+    matMul(other: Tensor): Tensor;
+    static einsum(spec: EinsumSpec, ...operands: Tensor[]): Tensor;
+    /**
+     * Return the axis position (0-based) of a labelled index.
+     * Throws if the index is not found in `axisLabels`.
+     */
+    axisOf(index: Index): number;
+    /**
+     * Return a new Tensor with the same data and shape but with `oldIndex`
+     * swapped for `newIndex` in `axisLabels`.
+     * Throws if `oldIndex` is not found.
+     */
+    replaceIndex(oldIndex: Index, newIndex: Index): Tensor;
+    /**
+     * Contract this tensor with `other` over every shared index (matched by
+     * `Index.matches`). Both operands must carry `axisLabels`.
+     *
+     * The result tensor carries the non-shared axes from `this` followed by
+     * the non-shared axes from `other` as its `axisLabels`.
+     *
+     * Throws:
+     * - If either operand lacks `axisLabels`.
+     * - If there are no shared indices (use `einsum` or an explicit outer product).
+     * - If a shared index has mismatched dimensions on the two operands.
+     */
+    contract(other: Tensor): Tensor;
+}
+//# sourceMappingURL=Tensor.d.ts.map

package/dist/Tensor.d.ts.map

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

package/dist/contraction-sequence.d.ts

@@ -0,0 +1,93 @@
+/**
+ * contractNetwork — given an ordered list of Tensors (each carrying
+ * `axisLabels`), find the pairwise-contraction order minimising the total
+ * FLOP count and execute it. ITensor's `optimal_contraction_sequence`
+ * equivalent.
+ *
+ * Two algorithms are provided:
+ *
+ *   - 'exact' — bitmask dynamic programming. For every non-empty subset
+ *     S ⊂ {0..N-1} of input tensors, we compute `bestCost[S]` and the
+ *     partition (S₁, S₂) achieving it (S = S₁ ⊔ S₂, both non-empty).
+ *     Transition:
+ *
+ *         bestCost[S] = min over all proper subset pairs (S₁, S₂) of
+ *                       bestCost[S₁] + bestCost[S₂] + pairwiseCost(net(S₁), net(S₂))
+ *
+ *     Base: bestCost[{i}] = 0. Subset enumeration via the standard
+ *     submask trick `for (sub = (mask-1) & mask; sub > 0; sub = (sub-1) & mask)`
+ *     visits every non-empty proper subset in O(3^N) total.
+ *
+ *     Determinism: ties broken by preferring the lexicographically smaller
+ *     (subsetMask₁, subsetMask₂) where subsetMask₁ ≤ subsetMask₂.
+ *
+ *     Bitmask encoding: bit `i` of a 32-bit integer is set iff input tensor
+ *     index `i` is part of the subset. So `0b1011 = {0, 1, 3}`. We use
+ *     ordinary JavaScript numbers (safe up to 2^32 for bitwise ops; capped
+ *     at N ≤ 30 for headroom).
+ *
+ *   - 'greedy' — Hendrickson–Sundaram. Maintain a working list of
+ *     intermediate tensor shapes. At each step, choose the pair (i, j) with
+ *     the cheapest pairwise contraction cost and replace them with their
+ *     contraction. Repeat until one remains. O(N³) per step × O(N) steps.
+ *
+ * Cost model: for a pairwise contraction of two intermediate tensors with
+ * shared-axis dimension product `D_shared` and free-axis dimension products
+ * `D_free_left`, `D_free_right`, the contraction FLOP cost is
+ *
+ *     cost = D_shared * D_free_left * D_free_right
+ *
+ * which is the volume of the OUTPUT tensor times the contraction depth. If
+ * `D_shared = 1` (no shared axes — outer product) we use `D_free_left *
+ * D_free_right`; mathematically that is the same formula. We follow this
+ * convention but it never fires in practice because we drive the cost
+ * through pairs with at least one shared index when possible.
+ *
+ * Output-tensor size for `intermediateSizes`: `D_free_left * D_free_right`
+ * (the contracted-axis dimensions are summed away, not multiplied into the
+ * result).
+ *
+ * `contractionOrder` indexing convention: each pair `[i, j]` is in
+ * "virtual-index" space. Input tensors occupy slots 0..N-1; the first
+ * pairwise contraction produces virtual slot N, the second slot N+1, and
+ * so on. So a length-N input network has a length-(N-1) order array.
+ */
+import { Tensor } from './Tensor.js';
+export interface ContractNetworkOpts {
+    /** Cap intermediate-tensor element count to avoid blowups. Default: 2^31. */
+    maxIntermediateSize?: number;
+    /**
+     * 'exact'  = DP optimal (≤ ~16 tensors, slow beyond that).
+     * 'greedy' = Hendrickson–Sundaram heuristic (any N).
+     * 'auto'   = 'exact' when N ≤ 16, otherwise 'greedy'.
+     * Default: 'auto'.
+     */
+    algorithm?: 'exact' | 'greedy' | 'auto';
+}
+export interface ContractNetworkResult {
+    result: Tensor;
+    /** Pairwise contractions in (virtual) input-index space; see file header. */
+    contractionOrder: ReadonlyArray<readonly [number, number]>;
+    /** Sum of pairwise FLOP costs along the chosen order. */
+    totalFlops: number;
+    /** Element count of each intermediate, in creation order. */
+    intermediateSizes: ReadonlyArray<number>;
+}
+/**
+ * Contract a network of named-index tensors in the optimal pairwise order.
+ *
+ * Returns:
+ *   - `result` — the fully contracted final Tensor.
+ *   - `contractionOrder` — the chosen sequence of pairwise contractions in
+ *     virtual-slot space (slots 0..N-1 = inputs; each produced intermediate
+ *     takes the next free slot).
+ *   - `totalFlops` — sum of per-step FLOP costs along the chosen order.
+ *   - `intermediateSizes` — element count of each produced intermediate.
+ *
+ * Throws:
+ *   - on empty input.
+ *   - if any input lacks `axisLabels`.
+ *   - if `maxIntermediateSize` is so tight no valid order exists.
+ */
+export declare function contractNetwork(tensors: ReadonlyArray<Tensor>, opts?: ContractNetworkOpts): ContractNetworkResult;
+//# sourceMappingURL=contraction-sequence.d.ts.map

package/dist/contraction-sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contraction-sequence.d.ts","sourceRoot":"","sources":["../src/contraction-sequence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,gBAAgB,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,iBAAiB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC1C;AA4pBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAE,mBAAmB,GACzB,qBAAqB,CAgDvB"}