@thi.ng/tensors 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-06-09T17:24:08Z
+- **Last updated**: 2025-07-09T09:42:08Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,17 @@ 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.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,23 @@
 
 ## 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):
+
+- [.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
@@ -51,6 +68,7 @@ conventions are closely aligned to the ones used by the
 - [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
+- [asTensor](https://docs.thi.ng/umbrella/tensors/variables/asTensor.html): Convert/wrap data as tensor
 - [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)
@@ -61,6 +79,7 @@ conventions are closely aligned to the ones used by the
 - [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`
+- [integrate](https://docs.thi.ng/umbrella/tensors/variables/dot.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
@@ -218,7 +237,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.63 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>;

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";

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";

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/tensors",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "1D/2D/3D/4D tensors with extensible polymorphic operations and customizable storage",
   "type": "module",
   "module": "./index.js",
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.11.29",
-    "@thi.ng/arrays": "^2.13.0",
+    "@thi.ng/arrays": "^2.13.1",
     "@thi.ng/checks": "^3.7.9",
     "@thi.ng/equiv": "^2.1.85",
     "@thi.ng/errors": "^2.5.35",
@@ -197,6 +197,9 @@
     "./identity": {
       "default": "./identity.js"
     },
+    "./integrate": {
+      "default": "./integrate.js"
+    },
     "./kernels": {
       "default": "./kernels.js"
     },
@@ -325,5 +328,5 @@
     "status": "alpha",
     "year": 2018
   },
-  "gitHead": "b076434a497b291ad33e81b1a15f6a71e2c82cc2\n"
+  "gitHead": "e657c2d66574c18343a6797aef4585945729093e\n"
 }