@danielsimonjr/mathts-tensor 0.2.19 → 0.2.20

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAMxD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGzF,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AACvC,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1629,7 +1629,7 @@ function tensorCholesky(t, rowAxes, opts) {
     lData = matL.toFloat64Array();
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(msg.replace(/^cholesky:/, "tensorCholesky:"));
+    throw new Error(msg.replace(/^cholesky:/, "tensorCholesky:"), { cause: err });
   }
   const factorData = lower ? lData : transposeSquare(lData, n);
   let factorLabels;

package/dist/named-index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Index — an immutable value type carrying a unique identity, a dimension,
+ * optional tags, and a prime level. Two indices *match* (and will be
+ * contracted by `Tensor.contract`) iff their `id` and `primeLevel` agree.
+ * Dimension agreement is validated at contraction time, not at matching time.
+ *
+ * Inspired by ITensors.jl's `Index` primitive.
+ */
+export interface IndexOpts {
+    /** Human-readable name; not used for matching but useful in errors / debug. */
+    name?: string;
+    /**
+     * Free-form tag list. Two indices with the SAME id but DIFFERENT tags still
+     * match by id.
+     */
+    tags?: ReadonlyArray<string>;
+    /**
+     * Prime level (ITensor's "prime"). Two indices with the same id but different
+     * prime levels do NOT match.
+     */
+    primeLevel?: number;
+}
+/**
+ * A first-class index value. Each `new Index(...)` call mints a fresh `id`
+ * (Symbol) that can never collide with another. Methods that would mutate
+ * state instead return a new `Index` sharing the same `id`.
+ */
+export declare class Index {
+    readonly id: symbol;
+    readonly dim: number;
+    readonly name?: string;
+    readonly tags: ReadonlyArray<string>;
+    readonly primeLevel: number;
+    constructor(dim: number, opts?: IndexOpts);
+    /**
+     * Internal constructor used by mutating-style methods that need to share the
+     * same `id` with a different primeLevel / tags. Not exposed publicly.
+     */
+    private static _from;
+    /**
+     * Return a new Index with `primeLevel` incremented by `by` (default 1).
+     */
+    prime(by?: number): Index;
+    /**
+     * Return a new Index with `primeLevel` reset to 0.
+     */
+    noprime(): Index;
+    /**
+     * Return a new Index with `tag` added to its tag list (no-op if already present).
+     */
+    addTag(tag: string): Index;
+    /**
+     * Return a new Index with `tag` removed from its tag list (no-op if absent).
+     */
+    removeTag(tag: string): Index;
+    /**
+     * True if `tag` is in this index's tag list.
+     */
+    hasTag(tag: string): boolean;
+    /**
+     * Two indices match iff they share the same `id` AND the same `primeLevel`.
+     * Dimension is NOT used for matching — it is validated at contraction time.
+     */
+    matches(other: Index): boolean;
+    toString(): string;
+}
+/**
+ * Convenience factory: `const i = idx(3, 'i')`.
+ *
+ * ```ts
+ * const i = idx(3, 'i');            // dim=3, name='i', primeLevel=0
+ * const j = idx(4, 'j', { tags: ['site'] });
+ * ```
+ */
+export declare function idx(dim: number, name?: string, opts?: Omit<IndexOpts, 'name'>): Index;
+//# sourceMappingURL=named-index.d.ts.map

package/dist/named-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-index.d.ts","sourceRoot":"","sources":["../src/named-index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAY,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,EASxC;IAED;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,KAAK;IAgBpB;;OAEG;IACH,KAAK,CAAC,EAAE,SAAI,GAAG,KAAK,CAKnB;IAED;;OAEG;IACH,OAAO,IAAI,KAAK,CAEf;IAED;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAGzB;IAED;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAI5B;IAED;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3B;IAED;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAE7B;IAED,QAAQ,IAAI,MAAM,CAKjB;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,KAAK,CAErF"}

package/dist/operations/cholesky.d.ts

@@ -0,0 +1,47 @@
+/**
+ * tensorCholesky — Cholesky decomposition for symmetric positive-definite
+ * rank-N tensors.
+ *
+ * Mirrors the `tensorSvd` pattern: partitions the axes of `t` into "row"
+ * axes and "col" axes, reshapes `t` into a 2-D matrix, performs the
+ * Cholesky decomposition via the matrix primitive (right-looking algorithm),
+ * and returns the factor as a Tensor.
+ *
+ * The 2-D reshaped input must be square and symmetric positive-definite;
+ * otherwise an error is thrown.
+ *
+ * Decomposition modes:
+ *   - default (`lower: true`):  returns L such that A = L · Lᵀ.
+ *   - `lower: false`:           returns U such that A = Uᵀ · U.
+ *
+ * `axisLabels` propagation: the returned factor receives the rowAxes labels
+ * on its leading dims and a fresh joining Index on its trailing axis
+ * (for L), or the joining Index on the leading axis and colAxes labels on
+ * the trailing dims (for U).
+ */
+import { Tensor } from '../Tensor.js';
+export interface TensorCholeskyOpts {
+    /** When true (default), return L such that A = L·Lᵀ. When false, return U such that A = Uᵀ·U. */
+    lower?: boolean;
+    /** Optional name for the joining index on the returned factor. Defaults to "cholesky". */
+    joiningIndexName?: string;
+}
+export interface TensorCholeskyResult {
+    /** Cholesky factor (lower or upper depending on `opts.lower`). */
+    L: Tensor;
+}
+/**
+ * Compute the Cholesky decomposition of tensor `t` by partitioning its
+ * axes into "row" and "col" groups. The reshaped 2-D matrix must be
+ * square and symmetric positive-definite.
+ *
+ * Delegates the core right-looking Cholesky algorithm to
+ * `@danielsimonjr/mathts-matrix`'s `cholesky` primitive.
+ *
+ * @param t        - Input tensor of any rank ≥ 1.
+ * @param rowAxes  - Axis indices forming the row dimension of the effective
+ *                   2-D matrix. The remaining axes form the column dimension.
+ * @param opts     - Optional triangle selector + naming.
+ */
+export declare function tensorCholesky(t: Tensor, rowAxes: ReadonlyArray<number>, opts?: TensorCholeskyOpts): TensorCholeskyResult;
+//# sourceMappingURL=cholesky.d.ts.map

package/dist/operations/cholesky.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cholesky.d.ts","sourceRoot":"","sources":["../../src/operations/cholesky.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAKtC,MAAM,WAAW,kBAAkB;IACjC,iGAAiG;IACjG,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,CAAC,EAAE,MAAM,CAAC;CACX;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAE,kBAAkB,GACxB,oBAAoB,CAgFtB"}

package/dist/operations/concatenate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * concatenate — join tensors along an existing axis (NumPy `concatenate`).
+ *
+ * All tensors must agree on every axis except the join axis. The output rank
+ * equals the input rank; only `shape[axis]` grows (sum of all input shapes
+ * along that axis).
+ *
+ * Axis-label semantics:
+ *   - All axis labels are taken from `tensors[0]`.
+ *   - If any `tensors[i].axisLabels[axis]` disagrees with `tensors[0]`'s label
+ *     on the join axis, `tensors[0]`'s label is used silently (matching the
+ *     principle that the first tensor is authoritative for label semantics).
+ *   - If `tensors[0]` carries no `axisLabels`, the output also carries none.
+ */
+import { Tensor } from '../Tensor.js';
+/**
+ * Concatenate tensors along an existing `axis`.
+ *
+ * @param tensors - Array of tensors. Must be non-empty. All must agree on every
+ *                  axis except `axis`.
+ * @param axis    - The axis along which to concatenate. Supports negative indexing.
+ * @returns A tensor with the same rank and with `shape[axis]` equal to the sum
+ *          of `tensors[i].shape[axis]`.
+ *
+ * @throws {Error} If `tensors` is empty, if any tensor has a different rank, or
+ *                 if shapes disagree on any non-join axis.
+ *
+ * @example
+ * // Vertically stack two 2×3 matrices → 4×3 matrix:
+ * const tall = concatenate([a, b], 0);
+ * // Horizontally stack two 2×3 matrices → 2×6 matrix:
+ * const wide = concatenate([a, b], 1);
+ */
+export declare function concatenate(tensors: Tensor[], axis: number): Tensor;
+//# sourceMappingURL=concatenate.d.ts.map

package/dist/operations/concatenate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concatenate.d.ts","sourceRoot":"","sources":["../../src/operations/concatenate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAsFnE"}

package/dist/operations/eig.d.ts

@@ -0,0 +1,50 @@
+/**
+ * tensorEig — eigenvalue / eigenvector decomposition for rank-N tensors.
+ *
+ * Mirrors the `tensorSvd` pattern: partitions the axes of `t` into "row"
+ * axes and "col" axes, reshapes `t` into a 2-D matrix, and delegates to
+ * the DenseMatrix `eig` primitive.
+ *
+ * The 2-D reshaped input must be square.
+ *
+ * Routing:
+ *   - `symmetric: true`     — eigenvalues are real and eigenvectors are
+ *                             orthogonal (matrix routes the symmetric path
+ *                             internally).
+ *   - `symmetric: false` (default) — general eigensolver. If any eigenvalue
+ *                             has a non-zero imaginary part, the result
+ *                             includes an `eigenvaluesImaginary` Tensor;
+ *                             otherwise the field is undefined.
+ *   - `computeVectors: false` — only eigenvalues are returned (faster).
+ */
+import { Tensor } from '../Tensor.js';
+export interface TensorEigOpts {
+    /** Hint that the input is symmetric; routes through a stable real-eigenvalue path. */
+    symmetric?: boolean;
+    /** When false, only eigenvalues are computed. Default true. */
+    computeVectors?: boolean;
+}
+export interface TensorEigResult {
+    /** Real parts of the eigenvalues. 1-D Tensor of length n. */
+    eigenvalues: Tensor;
+    /** Eigenvectors as columns; shape [n, n]. Present only when computeVectors !== false. */
+    eigenvectors?: Tensor;
+    /**
+     * Imaginary parts of the eigenvalues. 1-D Tensor of length n.
+     * Only present when any eigenvalue has nonzero imaginary part (general
+     * non-symmetric case). Undefined when all eigenvalues are real.
+     */
+    eigenvaluesImaginary?: Tensor;
+}
+/**
+ * Tensor eigendecomposition using the pure-JS matrix eig primitive (synchronous).
+ */
+export declare function tensorEig(t: Tensor, rowAxes: ReadonlyArray<number>, opts?: TensorEigOpts): TensorEigResult;
+/**
+ * Tensor eigendecomposition routed through the AssemblyScript WASM eig kernel
+ * (`eigWasm`) — same result as {@link tensorEig}, accelerated for large
+ * matricisations. Async (WASM instantiation); `eigWasm` falls back to JS when no
+ * binary is available.
+ */
+export declare function tensorEigWasm(t: Tensor, rowAxes: ReadonlyArray<number>, opts?: TensorEigOpts): Promise<TensorEigResult>;
+//# sourceMappingURL=eig.d.ts.map

package/dist/operations/eig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eig.d.ts","sourceRoot":"","sources":["../../src/operations/eig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAItC,MAAM,WAAW,aAAa;IAC5B,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAuHD;;GAEG;AACH,wBAAgB,SAAS,CACvB,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAE,aAAa,GACnB,eAAe,CAKjB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,eAAe,CAAC,CAK1B"}

package/dist/operations/flip.d.ts

@@ -0,0 +1,35 @@
+/**
+ * flip — reverse element order along given axes.
+ *
+ * For each axis in `axes`, the index along that axis is reversed:
+ *
+ *   out[..., i, ...] = in[..., dim - 1 - i, ...]
+ *
+ * Multiple axes can be flipped in a single pass. An empty `axes` array is
+ * a no-op (returns a copy of the input).
+ *
+ * Axis-label semantics: reversing the iteration order of an axis does not
+ * change its semantic identity — it is still the same logical axis. All axis
+ * labels from the input are therefore preserved unchanged in the output.
+ */
+import { Tensor } from '../Tensor.js';
+/**
+ * Reverse element order along the specified axes.
+ *
+ * @param t    - Input tensor of any rank.
+ * @param axes - The axes to flip. Supports negative indexing. Duplicates are
+ *               ignored. An empty array returns a copy of `t`.
+ * @returns A new `Tensor` with the same shape as `t`, with axis labels
+ *          preserved from `t`.
+ *
+ * @throws {Error} If any axis value is out of range.
+ *
+ * @example
+ * // Flip rows (axis 0) of a 3×4 matrix:
+ * const flipped = flip(matrix, [0]);
+ *
+ * // Flip both axes simultaneously:
+ * const rotated180 = flip(matrix, [0, 1]);
+ */
+export declare function flip(t: Tensor, axes: readonly number[]): Tensor;
+//# sourceMappingURL=flip.d.ts.map

package/dist/operations/flip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flip.d.ts","sourceRoot":"","sources":["../../src/operations/flip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CA6C/D"}

package/dist/operations/gather.d.ts

@@ -0,0 +1,33 @@
+/**
+ * gather — pull elements along one axis (NumPy `take` / JAX `gather`).
+ *
+ * For each index in `indices`, the output contains the corresponding "slice"
+ * of the input tensor along `axis`. The output has the same rank as the input;
+ * only `shape[axis]` changes to `indices.length`.
+ *
+ * Axis-label semantics: the gathered axis's label is **primed** (primeLevel
+ * incremented by 1 via `Index.prime()`) so it does not auto-match the original
+ * axis in `contract`. All other axis labels are preserved unchanged.
+ *
+ * The priming approach mirrors ITensors.jl's convention: after gathering, the
+ * index is the "selected" variant of the original, not the original itself.
+ */
+import { Tensor } from '../Tensor.js';
+/**
+ * Gather elements along `axis` using `indices`.
+ *
+ * @param t       - Input tensor of any rank.
+ * @param axis    - The axis along which to gather. Supports negative indexing.
+ * @param indices - The indices to gather. Duplicates are allowed.
+ * @returns A new `Tensor` with `shape[axis] === indices.length` and all other
+ *          dimensions unchanged. The gathered-axis label is primed.
+ *
+ * @throws {RangeError} If any index in `indices` is outside [0, shape[axis]).
+ * @throws {Error}      If `axis` is out of range.
+ *
+ * @example
+ * // Select rows 0 and 2 from a 3×4 matrix:
+ * const rows = gather(matrix, 0, [0, 2]);   // shape [2, 4]
+ */
+export declare function gather(t: Tensor, axis: number, indices: readonly number[]): Tensor;
+//# sourceMappingURL=gather.d.ts.map

package/dist/operations/gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gather.d.ts","sourceRoot":"","sources":["../../src/operations/gather.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAsElF"}

package/dist/operations/kron.d.ts

@@ -0,0 +1,38 @@
+/**
+ * tensorKron — Kronecker product for rank-N tensors.
+ *
+ * Computes the Kronecker product of tensors `a` and `b`. For rank-2 matrices
+ * this is the classical Kronecker product:
+ *
+ *   kron(A, B)[i0, j0] = A[i0 / B.rows, j0 / B.cols] * B[i0 % B.rows, j0 % B.cols]
+ *
+ * For higher-rank tensors, the same rule is applied axis-by-axis:
+ *
+ *   result.shape[k] = a.shape[k] * b.shape[k]
+ *   result[...i] = a[i[0]/b.shape[0], ..., i[r-1]/b.shape[r-1]]
+ *                * b[i[0]%b.shape[0], ..., i[r-1]%b.shape[r-1]]
+ *
+ * Rank alignment: if the tensors have different ranks, the smaller one is
+ * broadcast-aligned to the right by prepending size-1 dimensions (numpy-style).
+ *
+ * Axis labels: when both tensors carry `axisLabels`, the output axis labels
+ * are formed by concatenating each pair as `"<aName>_X_<bName>"` to avoid
+ * collisions. When only one tensor has labels, the output carries no labels.
+ */
+import { Tensor } from '../Tensor.js';
+export interface TensorKronOpts {
+    /**
+     * Separator string inserted between a's and b's axis-label names when
+     * building the output axisLabels. Default: "_X_".
+     */
+    separator?: string;
+}
+/**
+ * Compute the Kronecker product of tensors `a` and `b`.
+ *
+ * @param a    - Left operand tensor.
+ * @param b    - Right operand tensor.
+ * @param opts - Optional separator for axis-label naming.
+ */
+export declare function tensorKron(a: Tensor, b: Tensor, opts?: TensorKronOpts): Tensor;
+//# sourceMappingURL=kron.d.ts.map

package/dist/operations/kron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kron.d.ts","sourceRoot":"","sources":["../../src/operations/kron.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtC,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,MAAM,CA4G9E"}

package/dist/operations/lu.d.ts

@@ -0,0 +1,48 @@
+/**
+ * tensorLU — LU decomposition with partial pivoting for rank-N tensors.
+ *
+ * Mirrors the `tensorSvd` pattern: partitions the axes of `t` into "row"
+ * axes and "col" axes, reshapes `t` into a 2-D matrix, performs LU with
+ * partial pivoting (Doolittle's algorithm via the matrix primitive), and
+ * returns the factors as Tensors.
+ *
+ * The 2-D-reshaped input must be square; otherwise an error is thrown.
+ *
+ * Decomposition: P · A = L · U, where L is unit lower-triangular and U is
+ * upper-triangular. P is returned as the row-permutation array (P[i] is
+ * the row index of the original A that was moved to position i).
+ *
+ * `axisLabels` propagation: L receives the rowAxes labels on its leading
+ * dims and a fresh joining Index on its trailing axis; U receives the
+ * joining Index on its leading axis and the colAxes labels on its trailing
+ * dims.
+ */
+import { Tensor } from '../Tensor.js';
+export interface TensorLUResult {
+    /** Unit lower-triangular L. Shape [...rowDims, n]. */
+    L: Tensor;
+    /** Upper-triangular U. Shape [n, ...colDims]. */
+    U: Tensor;
+    /** Row permutation array of length n. P[i] is the original-row index now at position i. */
+    P: Int32Array;
+    /** Sign of the permutation (+1 for even, -1 for odd) — useful for det(). */
+    parity: 1 | -1;
+}
+export interface TensorLUOpts {
+    /** Optional name for the joining index between L and U. Defaults to "lu". */
+    joiningIndexName?: string;
+}
+/**
+ * Compute the LU decomposition of tensor `t` by partitioning its axes into
+ * "row" and "col" groups. The reshaped 2-D matrix must be square.
+ *
+ * Delegates the core Doolittle algorithm to `@danielsimonjr/mathts-matrix`'s
+ * `lu` primitive.
+ *
+ * @param t        - Input tensor of any rank ≥ 1.
+ * @param rowAxes  - Axis indices forming the row dimension of the effective
+ *                   2-D matrix. The remaining axes form the column dimension.
+ * @param opts     - Optional joining-index name.
+ */
+export declare function tensorLU(t: Tensor, rowAxes: ReadonlyArray<number>, opts?: TensorLUOpts): TensorLUResult;
+//# sourceMappingURL=lu.d.ts.map

package/dist/operations/lu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lu.d.ts","sourceRoot":"","sources":["../../src/operations/lu.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAKtC,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,CAAC,EAAE,MAAM,CAAC;IACV,iDAAiD;IACjD,CAAC,EAAE,MAAM,CAAC;IACV,2FAA2F;IAC3F,CAAC,EAAE,UAAU,CAAC;IACd,4EAA4E;IAC5E,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,cAAc,CA6FhB"}

package/dist/operations/pad.d.ts

@@ -0,0 +1,50 @@
+/**
+ * pad — pad each axis by [before, after] amounts.
+ *
+ * Three modes are supported, mirroring NumPy's `np.pad`:
+ *
+ * - `'constant'` (default): Fill padded cells with `constantValue` (default 0).
+ * - `'edge'`:    Repeat the boundary element along each padded slice.
+ * - `'reflect'`: Mirror the data across the boundary, excluding the boundary
+ *                element itself. Requires that each padding amount is strictly
+ *                less than the corresponding axis size.
+ *
+ * Axis-label semantics: output rank equals input rank and axis identities do
+ * not change (padding is just extension, not transformation). All axis labels
+ * from the input are preserved unchanged in the output.
+ */
+import { Tensor } from '../Tensor.js';
+export interface PadOptions {
+    /**
+     * Padding mode.
+     * - `'constant'` (default): fill with `constantValue`.
+     * - `'edge'`:    repeat boundary element.
+     * - `'reflect'`: mirror across boundary, excluding boundary itself.
+     */
+    mode?: 'constant' | 'edge' | 'reflect';
+    /** Value used when `mode === 'constant'`. Default `0`. */
+    constantValue?: number;
+}
+/**
+ * Pad a tensor along each axis by specified widths.
+ *
+ * @param t         - Input tensor of any rank.
+ * @param padWidths - Array of `[before, after]` pairs, one per axis. Length
+ *                    must equal `t.shape.length`. Each value must be >= 0.
+ * @param opts      - Optional padding options (mode and constantValue).
+ * @returns A new `Tensor` with `shape[k] = t.shape[k] + before_k + after_k`
+ *          and axis labels preserved from `t`.
+ *
+ * @throws {Error}      If `padWidths.length !== t.shape.length`, any pad
+ *                      value is negative, or `mode === 'reflect'` is used
+ *                      with a pad amount >= the corresponding axis size.
+ *
+ * @example
+ * // Constant-pad a 3×4 tensor with 1 cell of zeros on each side:
+ * const padded = pad(t, [[1, 1], [1, 1]]);  // shape [5, 6]
+ *
+ * // Edge-pad with asymmetric widths:
+ * const ep = pad(t, [[2, 0], [0, 1]], { mode: 'edge' });
+ */
+export declare function pad(t: Tensor, padWidths: readonly (readonly [number, number])[], opts?: PadOptions): Tensor;
+//# sourceMappingURL=pad.d.ts.map

package/dist/operations/pad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pad.d.ts","sourceRoot":"","sources":["../../src/operations/pad.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtC,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,GAAG,CACjB,CAAC,EAAE,MAAM,EACT,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,EACjD,IAAI,CAAC,EAAE,UAAU,GAChB,MAAM,CA6GR"}

package/dist/operations/pinv.d.ts

@@ -0,0 +1,39 @@
+/**
+ * tensorPinv — Moore-Penrose pseudoinverse for rank-N tensors.
+ *
+ * Partitions the axes of `t` into "row" axes (the axes that form the
+ * numerically "tall" side of the matrix) and the remaining "col" axes.
+ * Then:
+ *   1. Permutes + reshapes `t` to a 2-D matrix M (numRows × numCols).
+ *   2. Computes the full SVD:  M = U · diag(S) · V^T.
+ *   3. Thresholds small singular values using `rcond`: keep s_i if
+ *      s_i > rcond · max(S), else treat as zero.
+ *   4. Computes pinv(M) = V · diag(S^+) · U^T   (shape: numCols × numRows).
+ *   5. Reshapes the result back into a Tensor with swapped row/col dims.
+ *
+ * Axis labels: if the input carries `axisLabels`, the output tensor's
+ * leading axes get the original col-axis labels and the trailing axes get
+ * the original row-axis labels (because the pseudoinverse swaps rows ↔ cols).
+ */
+import { Tensor } from '../Tensor.js';
+import { Index } from '../named-index.js';
+export interface TensorPinvOpts {
+    /**
+     * Relative condition threshold for singular-value truncation.
+     * A singular value s_i is treated as zero when s_i ≤ rcond · max(S).
+     * Default: 1e-10.
+     */
+    rcond?: number;
+}
+/**
+ * Compute the Moore-Penrose pseudoinverse of tensor `t` by partitioning its
+ * axes into "row" and "col" groups.
+ *
+ * @param t        - Input tensor of any rank ≥ 1.
+ * @param rowAxes  - Axis indices (integers) or Index objects whose dimensions
+ *                   form the row dimension of the effective 2-D matrix. The
+ *                   remaining axes form the column dimension.
+ * @param opts     - Optional rcond threshold.
+ */
+export declare function tensorPinv(t: Tensor, rowAxes: ReadonlyArray<number | Index>, opts?: TensorPinvOpts): Tensor;
+//# sourceMappingURL=pinv.d.ts.map

package/dist/operations/pinv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinv.d.ts","sourceRoot":"","sources":["../../src/operations/pinv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG1C,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,aAAa,CAAC,MAAM,GAAG,KAAK,CAAC,EACtC,IAAI,CAAC,EAAE,cAAc,GACpB,MAAM,CAiGR"}

package/dist/operations/qr.d.ts

@@ -0,0 +1,49 @@
+/**
+ * tensorQr — QR decomposition for rank-N tensors.
+ *
+ * Mirrors the `tensorSvd` pattern: partitions the axes of `t` into "row" axes
+ * (joining with Q) and "col" axes (joining with R), permutes + reshapes `t`
+ * into a 2-D matrix, calls the DenseMatrix `qr` primitive, then reshapes Q
+ * and R back into Tensors.
+ *
+ * In 'reduced' mode (default, thin QR):
+ *   Q has shape [...rowDims, k]   where k = min(numRows, numCols)
+ *   R has shape [k, ...colDims]
+ *
+ * In 'full' mode:
+ *   Q has shape [...rowDims, numRows]   (square in the row direction)
+ *   R has shape [numRows, ...colDims]
+ *
+ * `axisLabels` propagation: when the input carries labels, the row-axis
+ * labels are forwarded to Q's leading dims and the col-axis labels to R's
+ * trailing dims. A fresh "joining" Index of dimension `k` (or `numRows` in
+ * full mode) is inserted between them.
+ */
+import { Tensor } from '../Tensor.js';
+export interface TensorQrOpts {
+    /** 'reduced' (default, thin QR) or 'full'. */
+    mode?: 'reduced' | 'full';
+    /**
+     * Optional name for the joining index between Q and R. Used only when
+     * input axisLabels are present to label the new joining axis. Defaults
+     * to "qr".
+     */
+    joiningIndexName?: string;
+}
+export interface TensorQrResult {
+    /** Q factor with orthonormal columns reshaped to [...rowDims, k]. */
+    Q: Tensor;
+    /** R factor (upper-triangular) reshaped to [k, ...colDims]. */
+    R: Tensor;
+}
+/**
+ * Compute the QR decomposition of tensor `t` by partitioning its axes into
+ * "row" and "col" groups.
+ *
+ * @param t        - Input tensor of any rank ≥ 1.
+ * @param rowAxes  - Axis indices forming the row dimension of the effective
+ *                   2-D matrix. The remaining axes form the column dimension.
+ * @param opts     - Optional mode + naming settings.
+ */
+export declare function tensorQr(t: Tensor, rowAxes: ReadonlyArray<number>, opts?: TensorQrOpts): TensorQrResult;
+//# sourceMappingURL=qr.d.ts.map

package/dist/operations/qr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr.d.ts","sourceRoot":"","sources":["../../src/operations/qr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAItC,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,CAAC,EAAE,MAAM,CAAC;IACV,+DAA+D;IAC/D,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CACtB,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,cAAc,CAwEhB"}

package/dist/operations/random.d.ts

@@ -0,0 +1,61 @@
+/**
+ * randomTensor — construct a Tensor filled with pseudo-random values.
+ *
+ * Supported distributions:
+ *   'uniform'    — U(0, 1) via the seeded PRNG or Math.random().
+ *   'normal'     — N(0, 1) via Box–Muller transform on the underlying PRNG.
+ *   'orthogonal' — Uniform on the orthogonal group O(n) via QR decomposition
+ *                  of a normal random matrix. Rank-2 shapes only.
+ *
+ * Seeded RNG: Mulberry32 — a small, fast, high-quality 32-bit PRNG.
+ * Reference: Tommy Ettinger, https://gist.github.com/tommyettinger/46a874533244883189143505d203312c
+ *
+ * WARNING: The seeded path is NOT cryptographically secure. Do not use for
+ * security-sensitive purposes (key generation, nonces, etc.).
+ */
+import { Tensor } from '../Tensor.js';
+import { Index } from '../named-index.js';
+export interface RandomTensorOpts {
+    /**
+     * Distribution to sample from.
+     *
+     * - `'uniform'`     — U(0, 1).
+     * - `'normal'`      — N(0, 1) via Box–Muller transform.
+     * - `'orthogonal'`  — uniform on the orthogonal group; rank-2 shape only.
+     *
+     * @default 'uniform'
+     */
+    distribution?: 'uniform' | 'normal' | 'orthogonal';
+    /**
+     * Integer seed for the Mulberry32 PRNG. When omitted, Math.random() is
+     * used (non-reproducible). NOT cryptographically secure.
+     */
+    seed?: number;
+    /**
+     * Optional axis labels forwarded into the new Tensor's constructor.
+     * Requires Phase-1 `axisLabels` support in the Tensor constructor
+     * (constructor signature: `Tensor(shape, data, axisLabels?)`).
+     */
+    axisLabels?: ReadonlyArray<Index>;
+}
+/**
+ * Construct a Tensor of the given `shape` filled with pseudo-random values.
+ *
+ * @param shape  - Array of positive integers defining the tensor dimensions.
+ * @param opts   - Optional configuration (distribution, seed, axisLabels).
+ * @returns A new Tensor.
+ *
+ * @example
+ * ```ts
+ * // 3x4 uniform random tensor
+ * const t = randomTensor([3, 4]);
+ *
+ * // Seeded normal random vector (reproducible)
+ * const v = randomTensor([100], { distribution: 'normal', seed: 42 });
+ *
+ * // 8x8 random orthogonal matrix
+ * const O = randomTensor([8, 8], { distribution: 'orthogonal', seed: 7 });
+ * ```
+ */
+export declare function randomTensor(shape: ReadonlyArray<number>, opts?: RandomTensorOpts): Tensor;
+//# sourceMappingURL=random.d.ts.map

package/dist/operations/random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../../src/operations/random.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAO1C,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,YAAY,CAAC;IAEnD;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;CACnC;AAqED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAuE1F"}