@thi.ng/tensors 0.6.4 → 0.8.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-06-24T21:39:38Z
+- **Last updated**: 2025-07-10T14:20:23Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,24 @@ 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.8.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.8.0) (2025-07-10)
+
+#### 🚀 Features
+
+- add `step()`/`smoothStep()` variations ([b433462](https://github.com/thi-ng/umbrella/commit/b433462))
+- add ITensor.crop() ([77e294d](https://github.com/thi-ng/umbrella/commit/77e294d))
+
+## [0.7.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.7.0) (2025-07-09)
+
+#### 🚀 Features
+
+- add `integrate()` tensor op ([fe39a4a](https://github.com/thi-ng/umbrella/commit/fe39a4a))
+- add `TensorLike` and `asTensor()` ([f76d9a6](https://github.com/thi-ng/umbrella/commit/f76d9a6))
+
+#### ♻️ Refactoring
+
+- migrate `asTensor()` to convert.ts ([fcb83c5](https://github.com/thi-ng/umbrella/commit/fcb83c5))
+
 ## [0.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.6.0) (2025-06-05)
 
 #### 🚀 Features

package/README.md

@@ -40,6 +40,24 @@
 
 ## Built-in tensor operations
 
+The [`ITensor`
+interface](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html) shared
+by all tensor implementations provides the following methods (non-exhaustive
+list here):
+
+- [.crop(pos, size)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#get-1): Crop tensor region (zero copy)
+- [.get(pos)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#get-1): Get value at position
+- [.hi(pos)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#hi-1): Crop tensor (high end, zero copy)
+- [.index(pos)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#index-1): Get index for position
+- [.lo(pos)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#lo-1): Crop tensor (low end, zero copy)
+- [.pack(storage?)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#pack-1): Copy tensor with data tightly packed
+- [.pick(axes)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#pick-1): Select axes only (zero copy)
+- [.position(index)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#position-1): Get position for index
+- [.reshape(newShape, newStride?)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#reshape-1): Reshape tensor (zero copy)
+- [.set(pos)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#set-1): Set value at position
+- [.step(axes)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#step-1): Skip axes (zero copy)
+- [.transpose(order)](https://docs.thi.ng/umbrella/tensors/interfaces/ITensor.html#transpose-1): Re-order axes (zero copy)
+
 The set of tensor polymorphic component-wise ops is easily extensible via
 provided higher-order functions in the `defOpXX()` family. Most of the ops
 listed below are also based on this approach. The function signatures and naming
@@ -49,53 +67,66 @@ conventions are closely aligned to the ones used by the
 - [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
+- [argMax](https://docs.thi.ng/umbrella/tensors/functions/argMax.html): Maximum component index/value
+- [argMin](https://docs.thi.ng/umbrella/tensors/functions/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
 - [convolve](https://docs.thi.ng/umbrella/tensors/variables/convolve.html): Tensor convolution (1D/2D/3D only)
 - [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
+- [diagonal](https://docs.thi.ng/umbrella/tensors/functions/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`
+- [identity](https://docs.thi.ng/umbrella/tensors/functions/identity.html): Square identity matrix tensor
+- [integrate](https://docs.thi.ng/umbrella/tensors/functions/integrate.html): Integrate tensor along innermost dimension
 - [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
+- [mag](https://docs.thi.ng/umbrella/tensors/functions/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
+- [mean](https://docs.thi.ng/umbrella/tensors/functions/mean.html): Tensor mean value
+- [min](https://docs.thi.ng/umbrella/tensors/functions/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): Tensor normalization (w/ optional length)
+- [mulM](https://docs.thi.ng/umbrella/tensors/functions/mulM.html): Matrix-matrix product
+- [mulV](https://docs.thi.ng/umbrella/tensors/functions/mulV.html): Matrix-vector product
+- [negativeIndices](https://docs.thi.ng/umbrella/tensors/variables/negativeIndices.html): Indices of negative component values
+- [nonZeroIndices](https://docs.thi.ng/umbrella/tensors/variables/nonZeroIndices.html): Indices of non-zero component values
+- [normalize](https://docs.thi.ng/umbrella/tensors/functions/normalize.html): Tensor normalization (w/ optional length)
+- [ones](https://docs.thi.ng/umbrella/tensors/functions/ones.html): One-filled tensor creation
+- [positiveIndices](https://docs.thi.ng/umbrella/tensors/variables/positiveIndices.html): Indices of positive component values
 - [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`
+- [print](https://docs.thi.ng/umbrella/tensors/functions/print.html): Formatted tensor output
 - [product](https://docs.thi.ng/umbrella/tensors/variables/product.html): Component product
 - [randDistrib](https://docs.thi.ng/umbrella/tensors/variables/randDistrib.html): Fill with random data from distribution fn
-- [range](https://docs.thi.ng/umbrella/tensors/variables/range.html): Create 1D tensor of monotonically increasing/decreasing values
+- [range](https://docs.thi.ng/umbrella/tensors/functions/range.html): Create 1D tensor of monotonically increasing/decreasing values
 - [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
+- [select](https://docs.thi.ng/umbrella/tensors/functions/select.html): Generalization of argMin/Max
+- [set](https://docs.thi.ng/umbrella/tensors/functions/set.html): Tensor setter
+- [setN](https://docs.thi.ng/umbrella/tensors/functions/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): Componentwise `Math.sin`
-- [softMax](https://docs.thi.ng/umbrella/tensors/variables/softMax.html): Soft Max activation
+- [smoothStep](https://docs.thi.ng/umbrella/tensors/variables/smoothStep.html): Smooth threshold function (as as GLSL `smoothstep()`)
+- [smoothStepN](https://docs.thi.ng/umbrella/tensors/variables/smoothStepN.html): Smooth threshold function (as as GLSL `smoothstep()`)
+- [softMax](https://docs.thi.ng/umbrella/tensors/functions/softMax.html): Soft Max activation
 - [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()`)
+- [stepN](https://docs.thi.ng/umbrella/tensors/variables/stepN.html): Threshold function (as as GLSL `step()`)
 - [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
-- [svd](https://docs.thi.ng/umbrella/tensors/variables/sum.html): Singular value decomposition
+- [svd](https://docs.thi.ng/umbrella/tensors/functions/svd.html): Singular value decomposition
+- [swap](https://docs.thi.ng/umbrella/tensors/functions/swap.html): Swap tensor values
 - [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)
+- [trace](https://docs.thi.ng/umbrella/tensors/functions/trace.html): Matrix trace (diagonal component sum)
+- [zeroes](https://docs.thi.ng/umbrella/tensors/functions/zeroes.html): Zero-filled tensor creation
 
 ### Broadcasting support
 
@@ -182,6 +213,8 @@ factories can be used with
 The following functions can be used to convert/coerce other data structures into
 tensors:
 
+- [`asTensor()`](https://docs.thi.ng/umbrella/tensors/functions/asTensor.html):
+  Convert/wrap data as tensor
 - [`fromFloatBuffer()`](https://docs.thi.ng/umbrella/tensors/functions/fromFloatBuffer.html):
   Coerce [thi.ng/pixel] float buffer/image (or compatible data structures) into
   a 2D/3D tensor
@@ -218,7 +251,7 @@ For Node.js REPL:
 const ten = await import("@thi.ng/tensors");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 9.48 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 9.75 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -58,6 +58,21 @@ export interface TensorFromArrayOpts<T extends Type, V> {
     type: T;
     storage?: ITensorStorage<V>;
 }
+/**
+ * Source data type for tensor conversion via {@link asTensor}.
+ */
+export interface TensorLike<T extends Type, S extends Shape> {
+    /** Data type */
+    type: T;
+    /** Tensor data/values (MUST match `type`) */
+    data: TensorData<TypeMap[T]>;
+    /** Tensor shape */
+    shape: S;
+    /** Stride/layout information of data */
+    stride: S;
+    /** Start index (default: 0) */
+    offset?: number;
+}
 export interface ITensor<T = number> extends ICopy<ITensor<T>>, IEquiv, IEqualsDelta<ITensor<T>>, IRelease {
     readonly type: Type;
     readonly storage: ITensorStorage<T>;
@@ -81,6 +96,13 @@ export interface ITensor<T = number> extends ICopy<ITensor<T>>, IEquiv, IEqualsD
      * @internal
      */
     broadcast<S extends Shape>(shape: S, stride: S): ShapeTensor<S, T>;
+    /**
+     * Returns a new tensor of same shape, but all values zeroed. Unless
+     * `storage` is given, the new data will be allocated using this tensor's
+     * storage provider.
+     *
+     * @param storage
+     */
     empty(storage?: ITensorStorage<T>): this;
     /**
      * Computes linear array index from given grid position. Reverse-op of
@@ -102,15 +124,286 @@ export interface ITensor<T = number> extends ICopy<ITensor<T>>, IEquiv, IEqualsD
      * @param index
      */
     position(index: number): number[];
+    /**
+     * Returns value at given grid position. No bounds checking.
+     *
+     * @param pos
+     */
     get(pos: NumericArray): T;
+    /**
+     * Sets value at given grid position. No bounds checking.
+     *
+     * @param pos
+     * @param value
+     */
     set(pos: NumericArray, value: T): this;
+    /**
+     * Returns a new tensor of the bottom-right region starting from given
+     * `pos`. View transform only, no data will be copied.
+     *
+     * @remarks
+     * Also see {@link Itensor.hi}, {@link ITensor.crop}.
+     *
+     * @example
+     * ```ts tangle:../export/itensor-lo.ts
+     * import { print, range } from "@thi.ng/tensors";
+     *
+     * const a = range(16).reshape([4, 4]);
+     * print(a);
+     * //        0    1.0000    2.0000    3.0000
+     * //   4.0000    5.0000    6.0000    7.0000
+     * //   8.0000    9.0000   10.0000   11.0000
+     * //  12.0000   13.0000   14.0000   15.0000
+     *
+     * const b = a.lo([2, 1]);
+     * print(b);
+     * //   9.0000   10.0000   11.0000
+     * //  13.0000   14.0000   15.0000
+     * ```
+     *
+     * @param pos
+     */
     lo(pos: NumericArray): this;
+    /**
+     * Returns a new tensor of the top-left region until given `pos` (excluded).
+     * View transform only, no data will be copied.
+     *
+     * @remarks
+     * Also see {@link Itensor.lo}, {@link ITensor.crop}.
+     *
+     * @example
+     * ```ts tangle:../export/itensor-hi.ts
+     * import { print, range } from "@thi.ng/tensors";
+     *
+     * const a = range(16).reshape([4, 4]);
+     * print(a);
+     * //        0    1.0000    2.0000    3.0000
+     * //   4.0000    5.0000    6.0000    7.0000
+     * //   8.0000    9.0000   10.0000   11.0000
+     * //  12.0000   13.0000   14.0000   15.0000
+     *
+     * const b = a.hi([2, 3]);
+     * print(b);
+     * //        0    1.0000    2.0000
+     * //   4.0000    5.0000    6.0000
+     * ```
+     *
+     * @param pos
+     */
     hi(pos: NumericArray): this;
+    /**
+     * Returns a new tensor of the extracted region defined by `pos` and `size`.
+     * This op is a combination of {@link ITensor.lo} and {@link ITensor.hi}.
+     * View transform only, no data will be copied.
+     *
+     * @example
+     * ```ts tangle:../export/itensor-crop.ts
+     * import { print, range } from "@thi.ng/tensors";
+     *
+     * const a = range(16).reshape([4, 4]);
+     * print(a);
+     * //        0    1.0000    2.0000    3.0000
+     * //   4.0000    5.0000    6.0000    7.0000
+     * //   8.0000    9.0000   10.0000   11.0000
+     * //  12.0000   13.0000   14.0000   15.0000
+     *
+     * const b = a.crop([1, 1], [2, 2]);
+     * print(b);
+     * //   5.0000    6.0000
+     * //   9.0000   10.0000
+     * ```
+     *
+     * @param pos
+     * @param size
+     */
+    crop(pos: NumericArray, size: NumericArray): this;
+    /**
+     * Returns a new tensor with step sizes adjusted for selected axes (Using
+     * zero for an axis will keep its current step size). View transform only,
+     * no data will be copied.
+     *
+     * @example
+     * ```ts tangle:../export/itensor-step.ts
+     * import { print, range } from "@thi.ng/tensors";
+     *
+     * const a = range(16).reshape([4, 4]);
+     * print(a);
+     * //        0    1.0000    2.0000    3.0000
+     * //   4.0000    5.0000    6.0000    7.0000
+     * //   8.0000    9.0000   10.0000   11.0000
+     * //  12.0000   13.0000   14.0000   15.0000
+     *
+     * // only select every 2nd row
+     * const b = a.step([2, 1]);
+     * print(b);
+     * //        0    1.0000    2.0000    3.0000
+     * //   8.0000    9.0000   10.0000   11.0000
+     *
+     * // keep rows as is (zero), only select every 2nd column
+     * print(b.step([0, 2]));
+     * //        0    2.0000
+     * //   8.0000   10.0000
+     * ```
+     *
+     * @param select
+     */
     step(select: NumericArray): this;
+    /**
+     * Returns a new tensor with only the `select`ed axes. A -1 will select all
+     * value in that axis. View transform only, no data will be copied.
+     *
+     * @example
+     * ```ts tangle:../export/itensor-pick.ts
+     * import { print, range } from "@thi.ng/tensors";
+     *
+     * // 3D 4x4x4 tensor with values in [0,64) range
+     * const a = range(64).reshape([4, 4, 4]);
+     *
+     * // pick entire slice #2
+     * print(a.pick([2]));
+     * //  32.0000   33.0000   34.0000   35.0000
+     * //  36.0000   37.0000   38.0000   39.0000
+     * //  40.0000   41.0000   42.0000   43.0000
+     * //  44.0000   45.0000   46.0000   47.0000
+     *
+     * // pick slice #2, row #2 (1D tensor)
+     * print(a.pick([2, 2]));
+     * //  40.0000   41.0000   42.0000   43.0000
+     *
+     * // pick slice #2, column #2 (1D tensor)
+     * print(a.pick([2, -1, 2]));
+     * //  34.0000   38.0000   42.0000   46.0000
+     * ```
+     *
+     * @param select
+     */
     pick(select: NumericArray): ITensor<T>;
+    /**
+     * Creates a "packed" copy of this tensor with dense striding and the new
+     * data array only holding the values actually referenced by this tensor.
+     * Unless `storage` is given, the new data will be allocated using this
+     * tensor's storage provider.
+     *
+     * @remarks
+     * Since most other `ITensor` ops are zero-copy, view-only transforms, often
+     * resulting in "sparse" views which are only addressing a subset of the
+     * values stored, using `.pack()` is useful to extract data into a dense
+     * tensor/buffer.
+     *
+     * @example
+     * ```ts tangle:../export/itensor-pack.ts
+     * import { range } from "@thi.ng/tensors";
+     *
+     * const a = range(16).reshape([4, 4]);
+     * console.log("a data", a.data);
+     * // a data [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ]
+     *
+     * // only select every 2nd row & column
+     * const b = a.step([2, 2]);
+     * console.log("b values", [...b]);
+     * // b values [ 0, 2, 8, 10 ]
+     * console.log("b data", b.data);
+     * // b data [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ]
+     *
+     * // create packed version of `b`
+     * const c = b.pack();
+     * console.log("c data", c.data);
+     * // c data [ 0, 2, 8, 10 ]
+     * ```
+     *
+     * @param storage
+     */
     pack(storage?: ITensorStorage<T>): this;
+    /**
+     * Returns a new tensor with same data but given new shape (and optionally
+     * new strides). The total number of elements of the new shape MUST match
+     * that of the current shape (otherwise an error will be thrown).
+     *
+     * @remarks
+     * Also see {@link ITensor.crop} and {@link ITensor.resize}
+     *
+     * @example
+     * ```ts tangle:../export/itensor-reshape.ts
+     * import { print, range } from "@thi.ng/tensors";
+     *
+     * // 1D tensor
+     * const a = range(16);
+     *
+     * // reshape as 2D tensor
+     * print(a.reshape([4, 4]));
+     * //         0    1.0000    2.0000    3.0000
+     * //    4.0000    5.0000    6.0000    7.0000
+     * //    8.0000    9.0000   10.0000   11.0000
+     * //   12.0000   13.0000   14.0000   15.0000
+     *
+     * // reshape as 3D tensor
+     * print(a.reshape([2, 2, 4]));
+     * // --- 0: ---
+     * //         0    1.0000    2.0000    3.0000
+     * //    4.0000    5.0000    6.0000    7.0000
+     * // --- 1: ---
+     * //    8.0000    9.0000   10.0000   11.0000
+     * //   12.0000   13.0000   14.0000   15.0000
+     * ```
+     *
+     * @param newShape
+     * @param newStride
+     */
     reshape<S extends Shape>(newShape: S, newStride?: S): ShapeTensor<S, T>;
+    /**
+     * Returns a copy of the tensor resized to `newShape`. If the new shape is
+     * larger than the current shape, the extra data values will be initialized
+     * to `fill` (default: zero). Values will be copied in current iteration
+     * order (same logic as numpy). Unless `storage` is given, the new data will
+     * be allocated using this tensor's storage provider.
+     *
+     * @remarks
+     * Also see {@link ITensor.crop}, {@link ITensor.reshape}.
+     *
+     * @example
+     * ```ts tangle:../export/itensor-resize.ts
+     * import { print, range } from "@thi.ng/tensors";
+     *
+     * // 2D 4x4 tensor with values in [0,16) range
+     * const a = range(16).reshape([4, 4]);
+     *
+     * print(a.resize([4, 8]));
+     * //        0    1.0000    2.0000    3.0000    4.0000    5.0000    6.0000    7.0000
+     * //   8.0000    9.0000   10.0000   11.0000   12.0000   13.0000   14.0000   15.0000
+     * //        0         0         0         0         0         0         0         0
+     * //        0         0         0         0         0         0         0         0
+     * ```
+     *
+     * @param newShape
+     * @param fill
+     * @param storage
+     */
     resize<S extends Shape>(newShape: S, fill?: T, storage?: ITensorStorage<T>): ShapeTensor<S, T>;
+    /**
+     * Returns a new tensor with the given new axis `order`. View transform
+     * only, no data will be copied.
+     *
+     * @example
+     * ```ts tangle:../export/itensor-transpose.ts
+     * import { print, range } from "@thi.ng/tensors";
+     *
+     * const a = range(12).reshape([3, 4]);
+     * print(a);
+     * //        0    1.0000    2.0000    3.0000
+     * //   4.0000    5.0000    6.0000    7.0000
+     * //   8.0000    9.0000   10.0000   11.0000
+     *
+     * // swap row & column order
+     * const b = a.transpose([1, 0]);
+     * print(b);
+     * //        0    4.0000    8.0000
+     * //   1.0000    5.0000    9.0000
+     * //   2.0000    6.0000   10.0000
+     * //   3.0000    7.0000   11.0000
+     * ```
+     *
+     * @param order
+     */
     transpose(order: NumericArray): this;
     toJSON(): any;
 }

package/convert.d.ts

@@ -1,4 +1,29 @@
 import type { NumericArray } from "@thi.ng/api";
+import type { Shape, ShapeTensor, TensorLike, TensorOpts, Type, TypeMap } from "./api.js";
+/**
+ * Converts/wraps given {@link TensorLike} `src` into a matching tensor
+ * implementation. By default the source data is NOT copied.
+ *
+ * @example
+ * ```ts tangle:../export/as-tensor.ts
+ * import { asTensor, print } from "@thi.ng/tensors";
+ *
+ * const src = {
+ *   data: [1, 2, 3, 4],
+ *   type: <const>"num",
+ *   shape: <[number,number]>[2, 2],
+ *   stride: <[number,number]>[2, 1],
+ * };
+ *
+ * print(asTensor(src));
+ * //    1.0000    2.0000
+ * //    3.0000    4.0000
+ * ```
+ *
+ * @param src
+ * @param opts
+ */
+export declare const asTensor: <T extends Type, S extends Shape>(src: TensorLike<T, S>, opts?: Pick<TensorOpts<TypeMap[T], S>, "storage" | "copy">) => ShapeTensor<S, TypeMap[T]>;
 /**
  * Simplified interface of thi.ng/pixel `FloatBuffer`, only defining parts
  * relevant to the conversion.

package/convert.js

@@ -1,5 +1,12 @@
 import { typedArrayType } from "@thi.ng/api/typedarray";
 import { tensor } from "./tensor.js";
+const asTensor = (src, opts) => tensor(src.type, src.shape, {
+  copy: false,
+  data: src.data,
+  stride: src.stride,
+  offset: src.offset,
+  ...opts
+});
 const fromFloatBuffer = ({
   size: [sx, sy],
   stride: [tx, ty],
@@ -18,5 +25,6 @@ const fromFloatBuffer = ({
   });
 };
 export {
+  asTensor,
   fromFloatBuffer
 };

package/index.d.ts

@@ -27,6 +27,7 @@ export * from "./exp2.js";
 export * from "./filtered-indices.js";
 export * from "./format.js";
 export * from "./identity.js";
+export * from "./integrate.js";
 export * from "./kernels.js";
 export * from "./log.js";
 export * from "./log2.js";
@@ -54,10 +55,13 @@ export * from "./set.js";
 export * from "./setn.js";
 export * from "./sigmoid.js";
 export * from "./sin.js";
+export * from "./smoothstep.js";
+export * from "./smoothstepn.js";
 export * from "./softmax.js";
 export * from "./softplus.js";
 export * from "./sqrt.js";
 export * from "./step.js";
+export * from "./stepn.js";
 export * from "./storage.js";
 export * from "./sub.js";
 export * from "./subn.js";

package/index.js

@@ -27,6 +27,7 @@ export * from "./exp2.js";
 export * from "./filtered-indices.js";
 export * from "./format.js";
 export * from "./identity.js";
+export * from "./integrate.js";
 export * from "./kernels.js";
 export * from "./log.js";
 export * from "./log2.js";
@@ -54,10 +55,13 @@ export * from "./set.js";
 export * from "./setn.js";
 export * from "./sigmoid.js";
 export * from "./sin.js";
+export * from "./smoothstep.js";
+export * from "./smoothstepn.js";
 export * from "./softmax.js";
 export * from "./softplus.js";
 export * from "./sqrt.js";
 export * from "./step.js";
+export * from "./stepn.js";
 export * from "./storage.js";
 export * from "./sub.js";
 export * from "./subn.js";

package/integrate.d.ts

@@ -0,0 +1,34 @@
+import type { Fn } from "@thi.ng/api";
+import type { ITensor } from "./api.js";
+import { Tensor1 } from "./tensor.js";
+/**
+ * Integrates given tensor along innermost dimension and writes result to 1D
+ * tensor `out` (or creates new one).
+ *
+ * @remarks
+ * The output tensor shape must match the innermost shape of the input: e.g. if
+ * input shape is `[2,3,4]`, then the output tensor must have a shape of `[4]`.
+ *
+ * @example
+ * ```ts tangle:../export/integrate.ts
+ * import { integrate, print, product, sum, tensor } from "@thi.ng/tensors";
+ *
+ * const input = tensor([[1, 2], [10, 20], [100, 200]]);
+ *
+ * // integrate using `sum()` (also default)
+ * // i.e. [1 + 10 + 100, 2 + 20 + 200]
+ * print(integrate(null, input, sum));
+ * //  111.0000  222.0000
+ *
+ * // integrate using `product()`
+ * // i.e. [1 * 10 * 100, 2 * 20 * 200]
+ * print(integrate(null, input, product));
+ * // 1000.0000 8000.0000
+ * ```
+ *
+ * @param out
+ * @param a
+ * @param fn
+ */
+export declare const integrate: (out: Tensor1 | null, a: ITensor, fn?: Fn<ITensor, number>) => Tensor1;
+//# sourceMappingURL=integrate.d.ts.map

package/integrate.js

@@ -0,0 +1,31 @@
+import { ensureShape } from "./errors.js";
+import { Tensor1 } from "./tensor.js";
+import { sum } from "./sum.js";
+const integrate = (out, a, fn = sum) => {
+  const { shape, dim } = a;
+  const odim = shape[shape.length - 1];
+  if (!out) {
+    out = new Tensor1(
+      a.type,
+      a.storage,
+      a.storage.alloc(odim),
+      [odim],
+      [1]
+    );
+  }
+  ensureShape(out, [odim]);
+  const {
+    data: odata,
+    stride: [tx],
+    offset: ox
+  } = out;
+  const select = new Array(dim).fill(-1);
+  for (let i = 0; i < odim; i++) {
+    select[dim - 1] = i;
+    odata[ox + i * tx] = fn(a.pick(select));
+  }
+  return out;
+};
+export {
+  integrate
+};

package/normalize.d.ts

@@ -7,5 +7,5 @@ import type { ITensor } from "./api.js";
  * @param a
  * @param n
  */
-export declare const normalize: (out: ITensor | null, a: ITensor, n?: number) => import("./tensor.js").Tensor1<any> | ITensor<number>;
+export declare const normalize: (out: ITensor | null, a: ITensor, n?: number) => ITensor<number> | import("./tensor.js").Tensor1<any>;
 //# sourceMappingURL=normalize.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/tensors",
-  "version": "0.6.4",
+  "version": "0.8.0",
   "description": "1D/2D/3D/4D tensors with extensible polymorphic operations and customizable storage",
   "type": "module",
   "module": "./index.js",
@@ -39,19 +39,19 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.29",
-    "@thi.ng/arrays": "^2.13.1",
-    "@thi.ng/checks": "^3.7.9",
-    "@thi.ng/equiv": "^2.1.85",
-    "@thi.ng/errors": "^2.5.35",
-    "@thi.ng/math": "^5.11.29",
-    "@thi.ng/random": "^4.1.20",
-    "@thi.ng/strings": "^3.9.15",
-    "@thi.ng/vectors": "^8.3.1"
+    "@thi.ng/api": "^8.11.30",
+    "@thi.ng/arrays": "^2.13.2",
+    "@thi.ng/checks": "^3.7.10",
+    "@thi.ng/equiv": "^2.1.86",
+    "@thi.ng/errors": "^2.5.36",
+    "@thi.ng/math": "^5.11.30",
+    "@thi.ng/random": "^4.1.21",
+    "@thi.ng/strings": "^3.9.16",
+    "@thi.ng/vectors": "^8.3.2"
   },
   "devDependencies": {
-    "esbuild": "^0.25.5",
-    "typedoc": "^0.28.5",
+    "esbuild": "^0.25.6",
+    "typedoc": "^0.28.7",
     "typescript": "^5.8.3"
   },
   "keywords": [
@@ -64,6 +64,7 @@
     "array",
     "blur",
     "broadcast",
+    "conversion",
     "convolution",
     "data-oriented",
     "datastructure",
@@ -85,6 +86,7 @@
     "pool",
     "presets",
     "random",
+    "smoothstep",
     "step",
     "svd",
     "tensor",
@@ -197,6 +199,9 @@
     "./identity": {
       "default": "./identity.js"
     },
+    "./integrate": {
+      "default": "./integrate.js"
+    },
     "./kernels": {
       "default": "./kernels.js"
     },
@@ -278,6 +283,12 @@
     "./sin": {
       "default": "./sin.js"
     },
+    "./smoothstep": {
+      "default": "./smoothstep.js"
+    },
+    "./smoothstepn": {
+      "default": "./smoothstepn.js"
+    },
     "./softmax": {
       "default": "./softmax.js"
     },
@@ -290,6 +301,9 @@
     "./step": {
       "default": "./step.js"
     },
+    "./stepn": {
+      "default": "./stepn.js"
+    },
     "./storage": {
       "default": "./storage.js"
     },
@@ -325,5 +339,5 @@
     "status": "alpha",
     "year": 2018
   },
-  "gitHead": "45e91ee75236e39fc87ea10fbabac1272bef62e3\n"
+  "gitHead": "56d8f088389b22192a06e9a395b5eecebf47697a\n"
 }

package/smoothstep.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Componentwise computes smoothstep function for given nD tensor and thresholds
+ * `b` (low edge) and `c` (high edge). Writes result to `out`. If `out` is null,
+ * mutates `a`. Multi-method. Also see {@link step}.
+ *
+ * @remarks
+ * Same as GLSL `smoothstep()` (but with changed order of arguments).
+ *
+ * Reference:
+ *
+ * - https://registry.khronos.org/OpenGL-Refpages/gl4/html/smoothstep.xhtml
+ *
+ * @param out - output tensor
+ * @param a - input tensor
+ * @param b - input tensor (low edge)
+ * @param b - input tensor (high edge)
+ */
+export declare const smoothStep: import("./api.js").TensorOpTTT<number>;
+//# sourceMappingURL=smoothstep.d.ts.map

package/smoothstep.js

@@ -0,0 +1,6 @@
+import { smoothStep as $ } from "@thi.ng/math/step";
+import { defOpTTT } from "./defopttt.js";
+const smoothStep = defOpTTT((a, b, c) => $(b, c, a));
+export {
+  smoothStep
+};

package/smoothstepn.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Componentwise computes smoothstep function for given nD tensor and uniform
+ * scalar thresholds `b` (low edge) and `c` (high edge). Writes result to `out`.
+ * If `out` is null, mutates `a`. Multi-method. Also see {@link stepN}.
+ *
+ * @remarks
+ * Same as GLSL `smoothstep()` (but with changed order of arguments).
+ *
+ * Reference:
+ *
+ * - https://registry.khronos.org/OpenGL-Refpages/gl4/html/smoothstep.xhtml
+ *
+ * @param out - output tensor
+ * @param a - input tensor
+ * @param b - scalar (low edge)
+ * @param c - scalar (high edge)
+ */
+export declare const smoothStepN: import("./api.js").MultiTensorOpImpl<import("./api.js").TensorOpTNN<number>>;
+//# sourceMappingURL=smoothstepn.d.ts.map

package/smoothstepn.js

@@ -0,0 +1,6 @@
+import { smoothStep as $ } from "@thi.ng/math/step";
+import { defOpTNN } from "./defoptnn.js";
+const smoothStepN = defOpTNN((a, b, c) => $(b, c, a));
+export {
+  smoothStepN
+};

package/step.d.ts

@@ -1,16 +1,18 @@
 /**
- * Componentwise computes step function for given nD tensor and uniform scalar
- * threshold `n`. Writes result to `out`. If `out` is null, mutates `a`.
- * Multi-method.
+ * Componentwise computes step function for given nD tensor and threshold `b`.
+ * Writes result to `out`. If `out` is null, mutates `a`. Multi-method. Also see
+ * {@link stepN} and {@link smoothStep}.
  *
  * @remarks
- * Same logic as GLSL `step()` (but with different order of arguments). If
- * `n=0`, the op becomes the Heaviside function:
- * https://en.wikipedia.org/wiki/Heaviside_step_function
+ * Same logic as GLSL `step()` (but with swapped order of arguments).
+ *
+ * Reference:
+ *
+ * - https://registry.khronos.org/OpenGL-Refpages/gl4/html/step.xhtml
  *
  * @param out - output tensor
  * @param a - input tensor
- * @param n - scalar
+ * @param b - input tensor (threshold)
  */
-export declare const stepN: import("./api.js").MultiTensorOpImpl<import("./api.js").TensorOpTN<number>>;
+export declare const step: import("./api.js").TensorOpTT<number>;
 //# sourceMappingURL=step.d.ts.map

package/step.js

@@ -1,5 +1,5 @@
-import { defOpTN } from "./defoptn.js";
-const stepN = defOpTN((a, b) => a >= b ? 1 : 0);
+import { defOpTT } from "./defoptt.js";
+const step = defOpTT((a, b) => a >= b ? 1 : 0);
 export {
-  stepN
+  step
 };

package/stepn.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Componentwise computes step function for given nD tensor and uniform scalar
+ * threshold `n`. Writes result to `out`. If `out` is null, mutates `a`.
+ * Multi-method. Also see {@link step} and {@link smoothStep}.
+ *
+ * @remarks
+ * Same logic as GLSL `step()` (but with different order of arguments). If
+ * `n=0`, the op becomes the Heaviside function:
+ * https://en.wikipedia.org/wiki/Heaviside_step_function
+ *
+ * @param out - output tensor
+ * @param a - input tensor
+ * @param n - scalar
+ */
+export declare const stepN: import("./api.js").MultiTensorOpImpl<import("./api.js").TensorOpTN<number>>;
+//# sourceMappingURL=stepn.d.ts.map

package/stepn.js

@@ -0,0 +1,5 @@
+import { defOpTN } from "./defoptn.js";
+const stepN = defOpTN((a, b) => a >= b ? 1 : 0);
+export {
+  stepN
+};

package/tensor.d.ts

@@ -29,6 +29,7 @@ export declare abstract class ATensor<T = number> implements ITensor<T> {
     abstract set(pos: NumericArray, v: T): this;
     hi(pos: NumericArray): this;
     lo(pos: NumericArray): this;
+    crop(pos: NumericArray, size: NumericArray): this;
     step(select: NumericArray): typeof this;
     pick(select: NumericArray): ITensor<T>;
     pack(storage?: ITensorStorage<T>): typeof this;

package/tensor.js

@@ -101,6 +101,17 @@ class ATensor {
       offset
     );
   }
+  crop(pos, size) {
+    const { shape, offset } = __crop(pos, size, this);
+    return new this.constructor(
+      this.type,
+      this.storage,
+      this.data,
+      shape,
+      this.stride,
+      offset
+    );
+  }
   step(select) {
     const { shape, stride, offset } = __step(select, this);
     return new this.constructor(
@@ -500,6 +511,7 @@ const __lo = (select, { shape, stride, offset }) => {
   const newShape = [];
   for (let i = 0, n = shape.length; i < n; i++) {
     const x = select[i];
+    if (x > shape[i]) illegalShape(select);
     newShape.push(
       x >= 0 ? (offset += stride[i] * x, shape[i] - x) : shape[i]
     );
@@ -510,10 +522,16 @@ const __hi = (select, { shape }) => {
   const newShape = [];
   for (let i = 0, n = shape.length; i < n; i++) {
     const x = select[i];
+    if (x > shape[i]) illegalShape(select);
     newShape.push(x > 0 ? x : shape[i]);
   }
   return newShape;
 };
+const __crop = (lo, hi, src) => {
+  const res = __lo(lo, src);
+  const shape = __hi(hi, res);
+  return { ...res, shape };
+};
 const __step = (select, { shape, stride, offset }) => {
   const newShape = shape.slice();
   const newStride = stride.slice();