@thi.ng/tensors 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-05-10T08:50:06Z
+- **Last updated**: 2025-05-12T07:03:24Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,13 @@ 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.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.4.0) (2025-05-12)
+
+#### 🚀 Features
+
+- add release() handling for tensors ([da06312](https://github.com/thi-ng/umbrella/commit/da06312))
+- add data type support for range() options ([90d02bc](https://github.com/thi-ng/umbrella/commit/90d02bc))
+
 ## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tensors@0.3.0) (2025-05-08)
 
 #### 🚀 Features

package/README.md

@@ -44,54 +44,55 @@ 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): 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): 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): fill with random data from distribution fn
+- [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): 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): 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
 - [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
+- [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): componentwise `Math.sin`
+- [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): componentwise `Math.sqrt`
+- [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): 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
-- [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)
+- [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
+- [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
 
@@ -180,7 +181,7 @@ For Node.js REPL:
 const ten = await import("@thi.ng/tensors");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 8.06 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 8.08 KB
 
 ## Dependencies
 
@@ -206,10 +207,9 @@ TODO
 
 ```ts tangle:export/readme-1.ts
 import * as t from "@thi.ng/tensors";
-import { range } from "@thi.ng/transducers";
 
 // create 4x4x4 3D tensor and fill with values
-const a = t.tensor("f32", [4, 4, 4], { data: [...range(64)] });
+const a = t.range(64).reshape([4, 4, 4]);
 
 t.print(a);
 // --- 0: ---
@@ -247,7 +247,7 @@ t.print(a.pick([3, -1, 2]));
 
 // use `.pack()` to apply view to standalone densely packed tensor (own data)
 console.log(a.pick([3, 2]).pack().data);
-// Float32Array(4) [ 56, 57, 58, 59 ]
+// [ 56, 57, 58, 59 ]
 
 // only select every second value along each axis
 t.print(a.step([2, 2, 2]));

package/api.d.ts

@@ -1,11 +1,11 @@
-import type { Type as $Type, ICopy, IEqualsDelta, IEquiv, ILength, Maybe, NumericArray } from "@thi.ng/api";
+import type { Type as $Type, ICopy, IEqualsDelta, IEquiv, ILength, IRelease, 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;
     fill(x: T, start?: number, end?: number): TensorData<T>;
 }
 export type Type = $Type | "num" | "str";
-export type NumType = Type | "num";
+export type NumType = $Type | "num";
 export type Shape1 = [number];
 export type Shape2 = [number, number];
 export type Shape3 = [number, number, number];
@@ -58,7 +58,7 @@ export interface TensorFromArrayOpts<T extends Type, V> {
     type: T;
     storage?: ITensorStorage<V>;
 }
-export interface ITensor<T = number> extends ICopy<ITensor<T>>, IEquiv, IEqualsDelta<ITensor<T>> {
+export interface ITensor<T = number> extends ICopy<ITensor<T>>, IEquiv, IEqualsDelta<ITensor<T>>, IRelease {
     readonly type: Type;
     readonly storage: ITensorStorage<T>;
     readonly data: TensorData<T>;
@@ -118,8 +118,26 @@ export interface TensorCtor<T = number> {
     new (type: Type, storage: ITensorStorage<T>, data: TensorData<T>, shape: number[], stride: number[], offset?: number): ITensor<T>;
 }
 export interface ITensorStorage<T> {
+    /**
+     * Attempts to allocate/create an array for given number of items. Throws an
+     * error if unsuccessful.
+     *
+     * @param size
+     */
     alloc(size: number): TensorData<T>;
+    /**
+     * Attempts to allocate/create an array for given iterable. Throws an
+     * error if unsuccessful.
+     *
+     * @param iter
+     */
     from(iter: Iterable<T>): TensorData<T>;
+    /**
+     * Attempts to release the array/memory used by given buffer. Returns true
+     * if successful.
+     *
+     * @param buf
+     */
     release(buf: TensorData<T>): boolean;
 }
 export type StorageRegistry = Record<Type, ITensorStorage<any>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/tensors",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "1D/2D/3D/4D tensors with extensible polymorphic operations and customizable storage",
   "type": "module",
   "module": "./index.js",
@@ -301,5 +301,5 @@
     "status": "alpha",
     "year": 2018
   },
-  "gitHead": "e47e081cc7ef3a5adf0b6a92366eab1072c51fec\n"
+  "gitHead": "5ec76378887e4f55ad519e235e08a5dd0c53be51\n"
 }

package/range.d.ts

@@ -1,12 +1,20 @@
-import type { TensorOpts } from "./api.js";
+import type { NumType, TensorOpts } from "./api.js";
 import { Tensor1 } from "./tensor.js";
+export interface RangeOpts<T extends NumType> extends Pick<TensorOpts<T, [number]>, "storage"> {
+    /**
+     * Tensor data type.
+     *
+     * @defaultValue "num"
+     */
+    type: T;
+}
 /**
  * Creates a 1D tensor of monotonically increasing values in the interval `[0,max)`.
  *
  * @param max
  * @param opts
  */
-export declare function range(max: number, opts?: Pick<TensorOpts<number, any>, "storage">): Tensor1;
+export declare function range<T extends NumType>(max: number, opts?: RangeOpts<T>): Tensor1;
 /**
  * Creates a 1D tensor of monotonically increasing values in the interval
  * `[min,max)`, using optional `step` and `opts`. If `from <= to`, the default
@@ -16,5 +24,5 @@ export declare function range(max: number, opts?: Pick<TensorOpts<number, any>,
  * @param to
  * @param opts
  */
-export declare function range(from: number, to: number, step?: number, opts?: Pick<TensorOpts<number, any>, "storage">): Tensor1;
+export declare function range<T extends NumType>(from: number, to: number, step?: number, opts?: RangeOpts<T>): Tensor1;
 //# sourceMappingURL=range.d.ts.map

package/range.js

@@ -3,12 +3,13 @@ import { isPlainObject } from "@thi.ng/checks";
 import { tensor, Tensor1 } from "./tensor.js";
 function range(...args) {
   const opts = isPlainObject(peek(args)) ? args.pop() : void 0;
+  const type = opts?.type ?? "num";
   let [from, to, step] = args;
   if (to === void 0) {
     to = from;
     from = 0;
   }
-  step = step === void 0 ? from < to ? 1 : -1 : step;
+  step = step ?? (from < to ? 1 : -1);
   const data = [];
   if (step > 0) {
     while (from < to) {
@@ -21,7 +22,7 @@ function range(...args) {
       from += step;
     }
   }
-  return tensor("num", [data.length], { ...opts, data });
+  return tensor(type, [data.length], { ...opts, copy: type !== "num", data });
 }
 export {
   range

package/storage.js

@@ -1,21 +1,20 @@
-import {} from "@thi.ng/api";
 import { always } from "@thi.ng/api/fn";
 import { typedArray, TYPEDARRAY_CTORS } from "@thi.ng/api/typedarray";
-const impl = (type) => ({
+const __impl = (type) => ({
   alloc: (size) => typedArray(type, size),
   from: (iter) => TYPEDARRAY_CTORS[type].from(iter),
   release: always
 });
 const STORAGE = {
-  u8: impl("u8"),
-  u8c: impl("u8c"),
-  i8: impl("i8"),
-  u16: impl("u16"),
-  i16: impl("i16"),
-  u32: impl("u32"),
-  i32: impl("i32"),
-  f32: impl("f32"),
-  f64: impl("f64"),
+  u8: __impl("u8"),
+  u8c: __impl("u8c"),
+  i8: __impl("i8"),
+  u16: __impl("u16"),
+  i16: __impl("i16"),
+  u32: __impl("u32"),
+  i32: __impl("i32"),
+  f32: __impl("f32"),
+  f64: __impl("f64"),
   num: {
     alloc: (size) => new Array(size).fill(0),
     from: (iter) => [...iter],

package/tensor.d.ts

@@ -17,6 +17,10 @@ export declare abstract class ATensor<T = number> implements ITensor<T> {
     broadcast<S extends Shape>(shape: S, stride: S): ShapeTensor<S, T>;
     copy(): typeof this;
     empty(storage?: ITensorStorage<T>): typeof this;
+    /**
+     * Calls {@link ITensorStorage.release} with this tensor's data.
+     */
+    release(): boolean;
     equiv(o: any): boolean;
     eqDelta(o: ITensor<T>, eps?: number): boolean;
     abstract index(pos: NumericArray): number;

package/tensor.js

@@ -58,6 +58,12 @@ class ATensor {
       shapeToStride(this.shape)
     );
   }
+  /**
+   * Calls {@link ITensorStorage.release} with this tensor's data.
+   */
+  release() {
+    return this.storage.release(this.data);
+  }
   equiv(o) {
     return this === o || o instanceof ATensor && equiv(this.shape, o.shape) && equivArrayLike([...this], [...o]);
   }