@thi.ng/tensors 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-04-30T12:52:32Z
+- **Last updated**: 2025-05-02T08:39:24Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,31 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.2.0) (2025-05-02)
+
+#### 🚀 Features
+
+- add `zeroes()`/`ones()` ([eb6f82d](https://github.com/thi-ng/umbrella/commit/eb6f82d))
+- add singular value decomp `svd()` ([8902157](https://github.com/thi-ng/umbrella/commit/8902157))
+- add `diagonal()` and `trace()` fns ([47a0e73](https://github.com/thi-ng/umbrella/commit/47a0e73))
+- add broadcast(), add ITensor.broadcast() ([b9b2dfc](https://github.com/thi-ng/umbrella/commit/b9b2dfc))
+- update all tensor ops & op generators ([47b3e4e](https://github.com/thi-ng/umbrella/commit/47b3e4e))
+  - add broadcasting support where possible
+  - update all `defOpXXX` HOF generators
+  - replace & remove various `TensorOpXXX` function types
+  - update all tensor ops, only keep one version per op
+  - update doc strings
+
+#### 🩹 Bug fixes
+
+- add missing `randDistrib4()` ([eb2ded2](https://github.com/thi-ng/umbrella/commit/eb2ded2))
+
+#### ♻️ Refactoring
+
+- update internal local var handling in various tensor ops ([c02c2a6](https://github.com/thi-ng/umbrella/commit/c02c2a6))
+- internal updates dot(), identity(), select() ([c0ed334](https://github.com/thi-ng/umbrella/commit/c0ed334))
+- update top() return type ([dcab223](https://github.com/thi-ng/umbrella/commit/dcab223))
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.1.0) (2025-04-30)
 
 #### 🚀 Features

package/README.md

@@ -16,6 +16,7 @@
 
 - [About](#about)
 - [Built-in tensor operations](#built-in-tensor-operations)
+  - [Broadcasting support](#broadcasting-support)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -43,51 +44,109 @@ listed below are also based on this approach. The function signatures and naming
 conventions are closely aligned to the ones used by the
 [thi.ng/vectors](https://thi.ng/vectors) package.
 
-- [abs](https://docs.thi.ng/umbrella/tensors/variables/abs.html)
-- [add](https://docs.thi.ng/umbrella/tensors/variables/add.html)
-- [addN](https://docs.thi.ng/umbrella/tensors/variables/addN.html)
-- [argMax](https://docs.thi.ng/umbrella/tensors/variables/argMax.html)
-- [argMin](https://docs.thi.ng/umbrella/tensors/variables/argMin.html)
-- [clamp](https://docs.thi.ng/umbrella/tensors/variables/clamp.html)
-- [clampN](https://docs.thi.ng/umbrella/tensors/variables/clampN.html)
-- [cos](https://docs.thi.ng/umbrella/tensors/variables/cos.html)
-- [div](https://docs.thi.ng/umbrella/tensors/variables/div.html)
-- [divN](https://docs.thi.ng/umbrella/tensors/variables/divN.html)
-- [dot](https://docs.thi.ng/umbrella/tensors/variables/dot.html)
-- [exp](https://docs.thi.ng/umbrella/tensors/variables/exp.html)
-- [exp2](https://docs.thi.ng/umbrella/tensors/variables/exp2.html)
-- [log](https://docs.thi.ng/umbrella/tensors/variables/log.html)
-- [log2](https://docs.thi.ng/umbrella/tensors/variables/log2.html)
-- [mag](https://docs.thi.ng/umbrella/tensors/variables/mag.html)
-- [magSq](https://docs.thi.ng/umbrella/tensors/variables/magSq.html)
-- [max](https://docs.thi.ng/umbrella/tensors/variables/max.html)
-- [maxN](https://docs.thi.ng/umbrella/tensors/variables/maxN.html)
-- [min](https://docs.thi.ng/umbrella/tensors/variables/min.html)
-- [minN](https://docs.thi.ng/umbrella/tensors/variables/minN.html)
-- [mul](https://docs.thi.ng/umbrella/tensors/variables/mul.html)
-- [mulN](https://docs.thi.ng/umbrella/tensors/variables/mulN.html)
+- [abs](https://docs.thi.ng/umbrella/tensors/variables/abs.html): componentwise `Math.abs`
+- [add](https://docs.thi.ng/umbrella/tensors/variables/add.html): tensor-tensor addition
+- [addN](https://docs.thi.ng/umbrella/tensors/variables/addN.html): tensor-scalar addition
+- [argMax](https://docs.thi.ng/umbrella/tensors/variables/argMax.html): maximum component index/value
+- [argMin](https://docs.thi.ng/umbrella/tensors/variables/argMin.html): minimum component index/value
+- [clamp](https://docs.thi.ng/umbrella/tensors/variables/clamp.html): tensor-tensor interval clamping
+- [clampN](https://docs.thi.ng/umbrella/tensors/variables/clampN.html): tensor-scalar interval clamping
+- [cos](https://docs.thi.ng/umbrella/tensors/variables/cos.html): componentwise `Math.cos`
+- [diagonal](https://docs.thi.ng/umbrella/tensors/variables/diagonal.html): diagonal extraction
+- [div](https://docs.thi.ng/umbrella/tensors/variables/div.html): tensor-tensor division
+- [divN](https://docs.thi.ng/umbrella/tensors/variables/divN.html): tensor-scalar division
+- [dot](https://docs.thi.ng/umbrella/tensors/variables/dot.html): dot product
+- [exp](https://docs.thi.ng/umbrella/tensors/variables/exp.html): componentwise `Math.exp`
+- [exp2](https://docs.thi.ng/umbrella/tensors/variables/exp2.html): componentwise `2^x`
+- [log](https://docs.thi.ng/umbrella/tensors/variables/log.html): componentwise `Math.log`
+- [log2](https://docs.thi.ng/umbrella/tensors/variables/log2.html): componentwise `Math.log2`
+- [mag](https://docs.thi.ng/umbrella/tensors/variables/mag.html): tensor magnitude
+- [magSq](https://docs.thi.ng/umbrella/tensors/variables/magSq.html): tensor squared magnitude
+- [max](https://docs.thi.ng/umbrella/tensors/variables/max.html): tensor-tensor maximum
+- [maxN](https://docs.thi.ng/umbrella/tensors/variables/maxN.html): tensor-scalar maximum
+- [min](https://docs.thi.ng/umbrella/tensors/variables/min.html): tensor-tensor minimum
+- [minN](https://docs.thi.ng/umbrella/tensors/variables/minN.html): tensor-scalar maximum
+- [mul](https://docs.thi.ng/umbrella/tensors/variables/mul.html): tensor-tensor multiplication
+- [mulN](https://docs.thi.ng/umbrella/tensors/variables/mulN.html): tensor-scalar multiplication
 - [mulM](https://docs.thi.ng/umbrella/tensors/variables/mulM.html): matrix-matrix product
 - [mulV](https://docs.thi.ng/umbrella/tensors/variables/mulV.html): matrix-vector product
-- [normalize](https://docs.thi.ng/umbrella/tensors/variables/normalize.html)
-- [pow](https://docs.thi.ng/umbrella/tensors/variables/pow.html)
-- [powN](https://docs.thi.ng/umbrella/tensors/variables/powN.html)
+- [normalize](https://docs.thi.ng/umbrella/tensors/variables/normalize.html): tensor normalization (w/ optional length)
+- [pow](https://docs.thi.ng/umbrella/tensors/variables/pow.html): tensor-tensor `Math.pow`
+- [powN](https://docs.thi.ng/umbrella/tensors/variables/powN.html): tensor-scalar `Math.pow`
 - [product](https://docs.thi.ng/umbrella/tensors/variables/product.html): component product
-- [randDistrib](https://docs.thi.ng/umbrella/tensors/variables/randDistrib.html)
+- [randDistrib](https://docs.thi.ng/umbrella/tensors/variables/randDistrib.html): fill with random data from distribution fn
 - [relu](https://docs.thi.ng/umbrella/tensors/variables/relu.html): ReLU activation
 - [reluN](https://docs.thi.ng/umbrella/tensors/variables/reluN.html): leaky ReLU activation
 - [select](https://docs.thi.ng/umbrella/tensors/variables/select.html): generalization of argMin/Max
 - [set](https://docs.thi.ng/umbrella/tensors/variables/set.html): tensor setter
 - [setN](https://docs.thi.ng/umbrella/tensors/variables/setN.html): tensor setter w/ uniform scalar
 - [sigmoid](https://docs.thi.ng/umbrella/tensors/variables/sigmoid.html): Sigmoid activation
-- [sin](https://docs.thi.ng/umbrella/tensors/variables/sin.html)
+- [sin](https://docs.thi.ng/umbrella/tensors/variables/sin.html): componentwise `Math.sin`
 - [softMax](https://docs.thi.ng/umbrella/tensors/variables/softMax.html): Soft Max activation
-- [sqrt](https://docs.thi.ng/umbrella/tensors/variables/sqrt.html)
+- [sqrt](https://docs.thi.ng/umbrella/tensors/variables/sqrt.html): componentwise `Math.sqrt`
 - [step](https://docs.thi.ng/umbrella/tensors/variables/step.html): Threshold function (as as GLSL `step()`)
-- [sub](https://docs.thi.ng/umbrella/tensors/variables/sub.html)
-- [subN](https://docs.thi.ng/umbrella/tensors/variables/subN.html)
+- [sub](https://docs.thi.ng/umbrella/tensors/variables/sub.html): tensor-tensor subtraction
+- [subN](https://docs.thi.ng/umbrella/tensors/variables/subN.html): tensor-scalar subtraction
 - [sum](https://docs.thi.ng/umbrella/tensors/variables/sum.html): component sum
-- [tan](https://docs.thi.ng/umbrella/tensors/variables/tan.html)
-- [tanh](https://docs.thi.ng/umbrella/tensors/variables/tanh.html)
+- [svd](https://docs.thi.ng/umbrella/tensors/variables/sum.html): singular value decomposition
+- [tan](https://docs.thi.ng/umbrella/tensors/variables/tan.html): componentwise `Math.tan`
+- [tanh](https://docs.thi.ng/umbrella/tensors/variables/tanh.html): componentwise `Math.tanh`
+- [trace](https://docs.thi.ng/umbrella/tensors/variables/trace.html): matrix trace (diagonal component sum)
+
+### Broadcasting support
+
+Most of the built-in functions taking two or more tensors as input are
+supporting broadcasting, i.e. the shapes of the individual arguments only need
+to be compatible, not identical. The operators attempt to adjust the tensor
+shape & stride configurations to be compatible, applying the steps and rules
+below:
+
+- If the dimensions are unequal, the smaller tensor's dimensions will be
+  increased as needed. The size of each added dimension will be set to 1 and its
+  stride set to zero.
+- The size of each dimension will be compared and only the following cases are
+  accepted (otherwise will throw an error): sizes are equal or one side is 1
+- Any of the tensors requiring shape adjustments will be shallow copied with
+  new shape/stride config applied.
+
+Some examples:
+
+```ts tangle:export/readme-broadcast.ts
+import { add, sub, print, tensor } from "@thi.ng/tensors";
+
+// 2D + 1D
+print(add(null, tensor([[1,2], [3,4]]), tensor([10, 20])));
+//   11.0000   22.0000
+//   13.0000   24.0000
+
+// 2D + 1D (as column vector)
+print(add(null, tensor([[1, 2], [3, 4]]), tensor([10, 20]).reshape([2,1])));
+//   11.0000   12.0000
+//   23.0000   24.0000
+
+// 1D - 2D
+print(sub(null, tensor([10, 20]), tensor([[1,2], [3,4]])));
+//    9.0000   18.0000
+//    7.0000   16.0000
+
+// 1D + 3D
+print(add(null, tensor([10, 20]), tensor([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])));
+// --- 0: ---
+//   11.0000   22.0000
+//   13.0000   24.0000
+// --- 1: ---
+//   15.0000   26.0000
+//   17.0000   28.0000
+
+// 2D + 3D
+print(add(null, tensor([[10, 20], [100, 200]]), tensor([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])));
+// --- 0: ---
+//   11.0000   22.0000
+//  103.0000  204.0000
+// --- 1: ---
+//   15.0000   26.0000
+//  107.0000  208.0000
+```
 
 ## Status
 
@@ -121,7 +180,7 @@ For Node.js REPL:
 const ten = await import("@thi.ng/tensors");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 7.07 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 7.72 KB
 
 ## Dependencies
 

package/abs.d.ts

@@ -5,33 +5,5 @@
  * @param out - output tensor
  * @param a - input tensor
  */
-export declare const abs: import("./api.js").MultiTensorOpT<number>;
-/**
- * Same as {@link abs} for 1D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- */
-export declare const abs1: import("./api.js").TensorOpT<number, number, import("./tensor.js").Tensor1<number>, import("./tensor.js").Tensor1<number>>;
-/**
- * Same as {@link abs} for 2D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- */
-export declare const abs2: import("./api.js").TensorOpT<number, number, import("./tensor.js").Tensor2<number>, import("./tensor.js").Tensor2<number>>;
-/**
- * Same as {@link abs} for 3D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- */
-export declare const abs3: import("./api.js").TensorOpT<number, number, import("./tensor.js").Tensor3<number>, import("./tensor.js").Tensor3<number>>;
-/**
- * Same as {@link abs} for 4D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- */
-export declare const abs4: import("./api.js").TensorOpT<number, number, import("./tensor.js").Tensor4<number>, import("./tensor.js").Tensor4<number>>;
+export declare const abs: import("./api.js").MultiTensorOpImpl<import("./api.js").TensorOpT<number>>;
 //# sourceMappingURL=abs.d.ts.map

package/abs.js

@@ -1,14 +1,5 @@
 import { defOpT } from "./defopt.js";
-const [a, b, c, d, e] = defOpT(Math.abs);
-const abs = a;
-const abs1 = b;
-const abs2 = c;
-const abs3 = d;
-const abs4 = e;
+const abs = defOpT(Math.abs);
 export {
-  abs,
-  abs1,
-  abs2,
-  abs3,
-  abs4
+  abs
 };

package/add.d.ts

@@ -1,42 +1,11 @@
 /**
  * Componentwise nD tensor addition. Writes result to `out`. If `out` is null,
- * mutates `a`. Multi-method.
+ * creates a new tensor using `a`'s type and storage provider and shape as
+ * determined by broadcasting rules (see {@link broadcast} for details).
  *
  * @param out - output tensor
  * @param a - input tensor
- * @param n - scalar
+ * @param b - input tensor
  */
-export declare const add: import("./api.js").MultiTensorOpTT<number>;
-/**
- * Same as {@link add} for 1D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- * @param n - scalar
- */
-export declare const add1: import("./api.js").TensorOpTT<number, number, import("./tensor.js").Tensor1<number>, import("./tensor.js").Tensor1<number>>;
-/**
- * Same as {@link add} for 2D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- * @param n - scalar
- */
-export declare const add2: import("./api.js").TensorOpTT<number, number, import("./tensor.js").Tensor2<number>, import("./tensor.js").Tensor2<number>>;
-/**
- * Same as {@link add} for 3D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- * @param n - scalar
- */
-export declare const add3: import("./api.js").TensorOpTT<number, number, import("./tensor.js").Tensor3<number>, import("./tensor.js").Tensor3<number>>;
-/**
- * Same as {@link add} for 4D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- * @param n - scalar
- */
-export declare const add4: import("./api.js").TensorOpTT<number, number, import("./tensor.js").Tensor4<number>, import("./tensor.js").Tensor4<number>>;
+export declare const add: import("./api.js").TensorOpTT<number>;
 //# sourceMappingURL=add.d.ts.map

package/add.js

@@ -1,15 +1,6 @@
 import { $add } from "@thi.ng/vectors/ops";
 import { defOpTT } from "./defoptt.js";
-const [a, b, c, d, e] = defOpTT($add);
-const add = a;
-const add1 = b;
-const add2 = c;
-const add3 = d;
-const add4 = e;
+const add = defOpTT($add);
 export {
-  add,
-  add1,
-  add2,
-  add3,
-  add4
+  add
 };

package/addn.d.ts

@@ -6,37 +6,5 @@
  * @param a - input tensor
  * @param n - scalar
  */
-export declare const addN: import("./api.js").MultiTensorOpTN<number>;
-/**
- * Same as {@link addN} for 1D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- * @param n - scalar
- */
-export declare const addN1: import("./api.js").TensorOpTN<number, number, import("./tensor.js").Tensor1<number>, import("./tensor.js").Tensor1<number>>;
-/**
- * Same as {@link addN} for 2D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- * @param n - scalar
- */
-export declare const addN2: import("./api.js").TensorOpTN<number, number, import("./tensor.js").Tensor2<number>, import("./tensor.js").Tensor2<number>>;
-/**
- * Same as {@link addN} for 3D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- * @param n - scalar
- */
-export declare const addN3: import("./api.js").TensorOpTN<number, number, import("./tensor.js").Tensor3<number>, import("./tensor.js").Tensor3<number>>;
-/**
- * Same as {@link addN} for 4D tensors.
- *
- * @param out - output tensor
- * @param a - input tensor
- * @param n - scalar
- */
-export declare const addN4: import("./api.js").TensorOpTN<number, number, import("./tensor.js").Tensor4<number>, import("./tensor.js").Tensor4<number>>;
+export declare const addN: import("./api.js").MultiTensorOpImpl<import("./api.js").TensorOpTN<number>>;
 //# sourceMappingURL=addn.d.ts.map

package/addn.js

@@ -1,15 +1,6 @@
 import { $add } from "@thi.ng/vectors/ops";
 import { defOpTN } from "./defoptn.js";
-const [a, b, c, d, e] = defOpTN($add);
-const addN = a;
-const addN1 = b;
-const addN2 = c;
-const addN3 = d;
-const addN4 = e;
+const addN = defOpTN($add);
 export {
-  addN,
-  addN1,
-  addN2,
-  addN3,
-  addN4
+  addN
 };

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { Type as $Type, Fn2, Fn3, Fn4, ICopy, IEqualsDelta, IEquiv, ILength, Maybe, NumericArray } from "@thi.ng/api";
+import type { Type as $Type, ICopy, IEqualsDelta, IEquiv, ILength, Maybe, NumericArray } from "@thi.ng/api";
 import type { Tensor1, Tensor2, Tensor3, Tensor4 } from "./tensor.js";
 export interface TensorData<T = number> extends Iterable<T>, ILength {
     [id: number]: T;
@@ -71,6 +71,16 @@ export interface ITensor<T = number> extends ICopy<ITensor<T>>, IEquiv, IEqualsD
     orderedShape: number[];
     orderedStride: number[];
     [Symbol.iterator](): IterableIterator<T>;
+    /**
+     * Internal use only. Creates a shallow view used for broadcasting
+     * operators. See {@link broadcast} for details.
+     *
+     * @param shape
+     * @param stride
+     *
+     * @internal
+     */
+    broadcast(shape: number[], stride: number[]): this;
     empty(storage?: ITensorStorage<T>): this;
     index(pos: NumericArray): number;
     get(pos: NumericArray): T;
@@ -94,12 +104,114 @@ export interface ITensorStorage<T> {
     release(buf: TensorData<T>): boolean;
 }
 export type StorageRegistry = Record<Type, ITensorStorage<any>>;
-export type TensorOpN<A = number, B = A, TB extends ITensor<B> = ITensor<B>> = Fn2<TB, A, TB>;
-export type TensorOpT<A = number, B = A, TA extends ITensor<A> = ITensor<A>, TB extends ITensor<B> = ITensor<B>> = Fn2<TB | null, TA, TB>;
-export type TensorOpTN<A = number, B = A, TA extends ITensor<A> = ITensor<A>, TB extends ITensor<B> = ITensor<B>> = Fn3<TB | null, TA, A, TB>;
-export type TensorOpTNN<A = number, B = A, TA extends ITensor<A> = ITensor<A>, TB extends ITensor<B> = ITensor<B>> = Fn4<TB | null, TA, A, A, TB>;
-export type TensorOpTT<A = number, B = A, TA extends ITensor<A> = ITensor<A>, TB extends ITensor<B> = ITensor<B>> = Fn3<TB | null, TA, TA, TB>;
-export type TensorOpTTT<A = number, B = A, TA extends ITensor<A> = ITensor<A>, TB extends ITensor<B> = ITensor<B>> = Fn4<TB | null, TA, TA, TA, TB>;
+export interface TensorOpT<T = number> {
+    (out: Tensor1<T> | null, a: Tensor1<T>): Tensor1<T>;
+    (out: Tensor2<T> | null, a: Tensor2<T>): Tensor2<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>): Tensor4<T>;
+}
+export interface TensorOpTT<T = number> {
+    (out: Tensor1<T> | null, a: Tensor1<T>, b: Tensor1<T>): Tensor1<T>;
+    (out: Tensor2<T> | null, a: Tensor1<T>, b: Tensor2<T>): Tensor2<T>;
+    (out: Tensor3<T> | null, a: Tensor1<T>, b: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor1<T>, b: Tensor4<T>): Tensor4<T>;
+    (out: Tensor2<T> | null, a: Tensor2<T>, b: Tensor1<T>): Tensor2<T>;
+    (out: Tensor2<T> | null, a: Tensor2<T>, b: Tensor2<T>): Tensor2<T>;
+    (out: Tensor3<T> | null, a: Tensor2<T>, b: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor2<T>, b: Tensor4<T>): Tensor4<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor1<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor2<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor3<T>, b: Tensor4<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor1<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor2<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor3<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor4<T>): Tensor4<T>;
+}
+export interface TensorOpTTT<T = number> {
+    (out: Tensor1<T> | null, a: Tensor1<T>, b: Tensor1<T>, c: Tensor1<T>): Tensor1<T>;
+    (out: Tensor2<T> | null, a: Tensor1<T>, b: Tensor1<T>, c: Tensor2<T>): Tensor2<T>;
+    (out: Tensor3<T> | null, a: Tensor1<T>, b: Tensor1<T>, c: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor1<T>, b: Tensor1<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor2<T> | null, a: Tensor1<T>, b: Tensor2<T>, c: Tensor1<T>): Tensor2<T>;
+    (out: Tensor2<T> | null, a: Tensor1<T>, b: Tensor2<T>, c: Tensor2<T>): Tensor2<T>;
+    (out: Tensor3<T> | null, a: Tensor1<T>, b: Tensor2<T>, c: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor1<T>, b: Tensor2<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor3<T> | null, a: Tensor1<T>, b: Tensor3<T>, c: Tensor1<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor1<T>, b: Tensor3<T>, c: Tensor2<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor1<T>, b: Tensor3<T>, c: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor1<T>, b: Tensor3<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor1<T>, b: Tensor4<T>, c: Tensor1<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor1<T>, b: Tensor4<T>, c: Tensor2<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor1<T>, b: Tensor4<T>, c: Tensor3<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor1<T>, b: Tensor4<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor2<T> | null, a: Tensor2<T>, b: Tensor1<T>, c: Tensor1<T>): Tensor2<T>;
+    (out: Tensor2<T> | null, a: Tensor2<T>, b: Tensor1<T>, c: Tensor2<T>): Tensor2<T>;
+    (out: Tensor3<T> | null, a: Tensor2<T>, b: Tensor1<T>, c: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor2<T>, b: Tensor1<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor2<T> | null, a: Tensor2<T>, b: Tensor2<T>, c: Tensor1<T>): Tensor2<T>;
+    (out: Tensor2<T> | null, a: Tensor2<T>, b: Tensor2<T>, c: Tensor2<T>): Tensor2<T>;
+    (out: Tensor3<T> | null, a: Tensor2<T>, b: Tensor2<T>, c: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor2<T>, b: Tensor2<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor3<T> | null, a: Tensor2<T>, b: Tensor3<T>, c: Tensor1<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor2<T>, b: Tensor3<T>, c: Tensor2<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor2<T>, b: Tensor3<T>, c: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor2<T>, b: Tensor3<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor2<T>, b: Tensor4<T>, c: Tensor1<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor2<T>, b: Tensor4<T>, c: Tensor2<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor2<T>, b: Tensor4<T>, c: Tensor3<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor2<T>, b: Tensor4<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor1<T>, c: Tensor1<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor1<T>, c: Tensor2<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor1<T>, c: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor3<T>, b: Tensor1<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor2<T>, c: Tensor1<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor2<T>, c: Tensor2<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor2<T>, c: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor3<T>, b: Tensor2<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor3<T>, c: Tensor1<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor3<T>, c: Tensor2<T>): Tensor3<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, b: Tensor3<T>, c: Tensor3<T>): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor3<T>, b: Tensor3<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor3<T>, b: Tensor4<T>, c: Tensor1<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor3<T>, b: Tensor4<T>, c: Tensor2<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor3<T>, b: Tensor4<T>, c: Tensor3<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor3<T>, b: Tensor4<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor1<T>, c: Tensor1<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor1<T>, c: Tensor2<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor1<T>, c: Tensor3<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor1<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor2<T>, c: Tensor1<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor2<T>, c: Tensor2<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor2<T>, c: Tensor3<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor2<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor3<T>, c: Tensor1<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor3<T>, c: Tensor2<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor3<T>, c: Tensor3<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor3<T>, c: Tensor4<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor4<T>, c: Tensor1<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor4<T>, c: Tensor2<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor4<T>, c: Tensor3<T>): Tensor4<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, b: Tensor4<T>, c: Tensor4<T>): Tensor4<T>;
+}
+export interface TensorOpN<A = number, B = A> {
+    (out: Tensor1<B>, n: A): Tensor1<B>;
+    (out: Tensor2<B>, n: A): Tensor2<B>;
+    (out: Tensor3<B>, n: A): Tensor3<B>;
+    (out: Tensor4<B>, n: A): Tensor4<B>;
+}
+export interface TensorOpTN<T = number> {
+    (out: Tensor1<T> | null, a: Tensor1<T>, n: T): Tensor1<T>;
+    (out: Tensor2<T> | null, a: Tensor2<T>, n: T): Tensor2<T>;
+    (out: Tensor3<T> | null, a: Tensor3<T>, n: T): Tensor3<T>;
+    (out: Tensor4<T> | null, a: Tensor4<T>, n: T): Tensor4<T>;
+}
+export interface TensorOpTNN<T = number> {
+    (out: Tensor1<T>, a: Tensor1<T>, n: T, m: T): Tensor1<T>;
+    (out: Tensor2<T>, a: Tensor2<T>, n: T, m: T): Tensor2<T>;
+    (out: Tensor3<T>, a: Tensor3<T>, n: T, m: T): Tensor3<T>;
+    (out: Tensor4<T>, a: Tensor4<T>, n: T, m: T): Tensor4<T>;
+}
 export type TensorOpRT<A, B, TA extends ITensor<A> = ITensor<A>> = (a: TA) => B;
 export type TensorOpRTT<A, B, TA extends ITensor<A> = ITensor<A>> = (a: TA, b: TA) => B;
 export interface MultiTensorOp<TOP> {
@@ -126,12 +238,4 @@ export interface MultiTensorOp<TOP> {
     impl(dim?: number): Maybe<TOP>;
 }
 export type MultiTensorOpImpl<T> = T & MultiTensorOp<T>;
-export type MultiTensorOpN<A = number, B = A> = MultiTensorOpImpl<TensorOpN<A, B>>;
-export type MultiTensorOpT<A = number, B = A> = MultiTensorOpImpl<TensorOpT<A, B>>;
-export type MultiTensorOpTN<A = number, B = A> = MultiTensorOpImpl<TensorOpTN<A, B>>;
-export type MultiTensorOpTNN<A = number, B = A> = MultiTensorOpImpl<TensorOpTNN<A, B>>;
-export type MultiTensorOpTT<A = number, B = A> = MultiTensorOpImpl<TensorOpTT<A, B>>;
-export type MultiTensorOpTTT<A = number, B = A> = MultiTensorOpImpl<TensorOpTTT<A, B>>;
-export type MultiTensorOpRT<A = number, B = A> = MultiTensorOpImpl<TensorOpRT<A, B>>;
-export type MultiTensorOpRTT<A = number, B = A> = MultiTensorOpImpl<TensorOpRTT<A, B>>;
 //# sourceMappingURL=api.d.ts.map

package/broadcast.d.ts

@@ -0,0 +1,24 @@
+import type { ITensor, Shape } from "./api.js";
+/**
+ * Helper function for various tensor operators which support broadcasting.
+ * Takes two tensors and attempts to adjust their shape & stride configurations
+ * to be compatible, applying the steps and rules below. Returns an object of
+ * adjusted shape and possibly adjusted shallow copies of both tensors.
+ *
+ * - if the dimensions are unequal, the smaller tensor's dimensions will be
+ *   increased as needed. The size of each added dimension will be set to 1 and
+ *   its stride to zero.
+ * - Size of each dimension will be compared and only the following cases are
+ *   accepted (otherwise will throw an error): sizes are equal or one side is 1
+ * - Any of the tensors requiring shape adjustments will be shallow copied with
+ *   new shape/stride config applied (via {@link ITensor.broadcast}).
+ *
+ * @param a
+ * @param b
+ */
+export declare const broadcast: <T = number>(a: ITensor<T>, b: ITensor<T>) => {
+    shape: Shape;
+    a: ITensor<T>;
+    b: ITensor<T>;
+};
+//# sourceMappingURL=broadcast.d.ts.map

package/broadcast.js

@@ -0,0 +1,54 @@
+import { illegalArgs } from "@thi.ng/errors";
+import { equals } from "@thi.ng/vectors";
+import { max } from "@thi.ng/vectors/max";
+const broadcast = (a, b) => {
+  if (equals(a.shape, b.shape)) return { shape: a.shape, a, b };
+  const ashape = a.shape.slice();
+  const astride = a.stride.slice();
+  const bshape = b.shape.slice();
+  const bstride = b.stride.slice();
+  let da = a.dim;
+  let db = b.dim;
+  let bcastA = da < db;
+  let bcastB = db < da;
+  if (bcastA) {
+    while (da < db) {
+      ashape.unshift(1);
+      astride.unshift(0);
+      da++;
+    }
+  } else if (bcastB) {
+    while (db < da) {
+      bshape.unshift(1);
+      bstride.unshift(0);
+      db++;
+    }
+  }
+  for (let i = 0; i < da; i++) {
+    const sa = ashape[i];
+    const sb = bshape[i];
+    if (sa < sb) {
+      if (sa > 1) __broadcastError(ashape, bshape);
+      astride[i] = 0;
+      bcastA = true;
+    } else if (sb < sa) {
+      if (sb > 1) __broadcastError(ashape, bshape);
+      bstride[i] = 0;
+      bcastB = true;
+    }
+  }
+  const shape = max([], ashape, bshape);
+  return {
+    shape,
+    a: bcastA ? a.broadcast(shape, astride) : a,
+    b: bcastB ? b.broadcast(shape, bstride) : b
+  };
+};
+const __broadcastError = (ashape, bshape) => illegalArgs(
+  `incompatible shapes: ${JSON.stringify(ashape)} vs ${JSON.stringify(
+    bshape
+  )}`
+);
+export {
+  broadcast
+};