[!NOTE] This is one of 210 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
• Built-in tensor operations
  • Broadcasting support
  • Convolution support
  • Conversions
• Status
• Installation
• Dependencies
• API
  • Basic usage
  • Matrix-matrix multiplication
  • Matrix-vector multiplication
• Authors
• License

About

0D/1D/2D/3D/4D tensors with extensible polymorphic operations and customizable storage.

[!NOTE] This package contains code originally written in 2017/18 and has been refactored to be stylistically more aligned with other thi.ng packages.

Built-in tensor operations

The ITensor interface shared by all tensor implementations provides the following methods (non-exhaustive list here):

• .crop(pos, size): Crop tensor region (zero copy)
• .get(pos): Get value at position
• .hi(pos): Crop tensor (high end, zero copy)
• .index(pos): Get index for position
• .lo(pos): Crop tensor (low end, zero copy)
• .pack(storage?): Copy tensor with data tightly packed
• .pick(axes): Select axes only (zero copy)
• .position(index): Get position for index
• .reshape(newShape, newStride?): Reshape tensor (zero copy)
• .set(pos): Set value at position
• .step(axes): Skip axes (zero copy)
• .transpose(order): 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 conventions are closely aligned to the ones used by the thi.ng/vectors package.

• abs: Componentwise Math.abs
• add: Tensor-tensor addition
• addN: Tensor-scalar addition
• argMax: Maximum component index/value
• argMin: Minimum component index/value
• clamp: Tensor-tensor interval clamping
• clampN: Tensor-scalar interval clamping
• convolve: Tensor convolution (1D/2D/3D only)
• cos: Componentwise Math.cos
• diagonal: Diagonal extraction
• div: Tensor-tensor division
• divN: Tensor-scalar division
• dot: Dot product
• exp: Componentwise Math.exp
• exp2: Componentwise 2^x
• identity: Square identity matrix tensor
• integrate: Integrate tensor along innermost dimension
• log: Componentwise Math.log
• log2: Componentwise Math.log2
• mag: Tensor magnitude
• magSq: Tensor squared magnitude
• max: Tensor-tensor maximum
• maxN: Tensor-scalar maximum
• mean: Tensor mean value
• min: Tensor-tensor minimum
• minN: Tensor-scalar maximum
• mul: Tensor-tensor multiplication
• mulN: Tensor-scalar multiplication
• mulM: Matrix-matrix product
• mulV: Matrix-vector product
• negativeIndices: Indices of negative component values
• nonZeroIndices: Indices of non-zero component values
• normalize: Tensor normalization (w/ optional length)
• ones: One-filled tensor creation
• positiveIndices: Indices of positive component values
• pow: Tensor-tensor Math.pow
• powN: Tensor-scalar Math.pow
• print: Formatted tensor output
• product: Component product
• randDistrib: Fill with random data from distribution fn
• range: Create 1D tensor of monotonically increasing/decreasing values
• relu: ReLU activation
• reluN: Leaky ReLU activation
• select: Generalization of argMin/Max
• set: Tensor setter
• setN: Tensor setter w/ uniform scalar
• sigmoid: Sigmoid activation
• sin: Componentwise Math.sin
• smoothStep: Smooth threshold function (as as GLSL smoothstep())
• smoothStepN: Smooth threshold function (as as GLSL smoothstep())
• softMax: Soft Max activation
• sqrt: Componentwise Math.sqrt
• step: Threshold function (as as GLSL step())
• stepN: Threshold function (as as GLSL step())
• sub: Tensor-tensor subtraction
• subN: Tensor-scalar subtraction
• sum: Component sum
• svd: Singular value decomposition
• swap: Swap tensor values
• tan: Componentwise Math.tan
• tanh: Componentwise Math.tanh
• trace: Matrix trace (diagonal component sum)
• zeroes: Zero-filled tensor creation

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:

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

Convolution support

Tensor convolution is only possible if both the domain tensor and the kernel tensor have same dimensionality. No broadcasting support.

The following kernel presets and tensor factories are included and can be used with convolve():

• BOX_BLUR2(radius): Box blur kernel factory
• GAUSSION2(radius): Gaussian blur kernel factory
• EDGE2(radius): Edge/ridge detection kernel factory
• SOBEL1: 1D Sobel kernel
• SOBEL2: 2D Sobel kernel
• SOBEL3: 3D Sobel kernel

For more generalized convolution-like functionality, the following kernel factories can be used with applyKernel():

• MAX2_POOL(width,height?): max pooling
• MIN2_POOL(width,height?): min pooling
• MAXIMA2(radius): local maxima detection
• MINIMA2(radius): local minima detection

Conversions

The following functions can be used to convert/coerce other data structures into tensors:

• asTensor(): Convert/wrap data as tensor
• fromFloatBuffer(): Coerce [thi.ng/pixel] float buffer/image (or compatible data structures) into a 2D/3D tensor

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Installation

yarn add @thi.ng/tensors

ESM import:

import * as ten from "@thi.ng/tensors";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/tensors"></script>

JSDelivr documentation

For Node.js REPL:

const ten = await import("@thi.ng/tensors");

Package sizes (brotli'd, pre-treeshake): ESM: 11.49 KB

Dependencies

• @thi.ng/api
• @thi.ng/arrays
• @thi.ng/checks
• @thi.ng/equiv
• @thi.ng/errors
• @thi.ng/math
• @thi.ng/random
• @thi.ng/strings
• @thi.ng/vectors

Note: @thi.ng/api is in most cases a type-only import (not used at runtime)

API

Generated API docs

TODO

Basic usage

import * as t from "@thi.ng/tensors";

// create 4x4x4 3D tensor and fill with values
const a = t.range(64).reshape([4, 4, 4]);

t.print(a);
// --- 0: ---
//         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
// --- 1: ---
//   16.0000   17.0000   18.0000   19.0000
//   20.0000   21.0000   22.0000   23.0000
//   24.0000   25.0000   26.0000   27.0000
//   28.0000   29.0000   30.0000   31.0000
// --- 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
// --- 3: ---
//   48.0000   49.0000   50.0000   51.0000
//   52.0000   53.0000   54.0000   55.0000
//   56.0000   57.0000   58.0000   59.0000
//   60.0000   61.0000   62.0000   63.0000

// pick a tensor slice/axis (view only, 2d tensor)
t.print(a.pick([3]));
//   48.0000   49.0000   50.0000   51.0000
//   52.0000   53.0000   54.0000   55.0000
//   56.0000   57.0000   58.0000   59.0000
//   60.0000   61.0000   62.0000   63.0000

// any axis set to -1 will be skipped
// here we select slice 3 and column 2 only (1d tensor)
t.print(a.pick([3, -1, 2]));
//   50.0000   54.0000   58.0000   62.0000

// use `.pack()` to apply view to standalone densely packed tensor (own data)
console.log(a.pick([3, 2]).pack().data);
// [ 56, 57, 58, 59 ]

// only select every second value along each axis
t.print(a.step([2, 2, 2]));
// --- 0: ---
//         0    2.0000
//    8.0000   10.0000
// --- 1: ---
//   32.0000   34.0000
//   40.0000   42.0000

// extract an axis range (view only, use `.pack()` to extract)
t.print(a.lo([1, 1, 1]).hi([2, 2, 2]));
// --- 0: ---
//   21.0000   22.0000
//   25.0000   26.0000
// --- 1: ---
//   37.0000   38.0000
//   41.0000   42.0000

// read & write elements (no bounds checking!)
a.set([1, 2, 3], 100);

console.log(a.get([1, 2, 3]));
// 100

// or via direct array access
console.log(a.data[a.index([1, 2, 3])]);
// 100

// tensors are iterables (in current stride order)
console.log([...a]);
// [ 0, 1, 2, 3, 4, ... 60, 61, 62, 63 ]

// create a 2D tensor w/ random values (by default normal distribution, bias=0, std=1)
const b = t.randDistrib(t.tensor("f64", [4, 2]));

t.print(b);
//    0.3854    0.6597
//    0.5775    0.9201
//   -0.7276   -0.1069
//    1.0550    0.4903

// apply sigmoid
// (null as output arg means mutate original [in 99% of all provided ops])
t.print(t.sigmoid(null, b));
//    0.5952    0.6592
//    0.6405    0.7151
//    0.3257    0.4733
//    0.7417    0.6202

Matrix-matrix multiplication

import { tensor, mulM, print } from "@thi.ng/tensors";

// create 2x3 matrix
const m1 = tensor([[1, 2, 3], [4, 5, 6]]);

print(m1);
//    1.0000    2.0000    3.0000
//    4.0000    5.0000    6.0000

// create transposed view (view only, zero-copy)
const m2 = m1.transpose([1, 0]);

print(m2);
//    1.0000    4.0000
//    2.0000    5.0000
//    3.0000    6.0000

// matrix multiplication
// (here if 1st arg is null, a new tensor will be created)
print(mulM(null, m1, m2));
//   14.0000   32.0000
//   32.0000   77.0000

Matrix-vector multiplication

import { tensor, mulV, print } from "@thi.ng/tensors";

// create 2x3 transformation matrix (row-major)
const mat = tensor([[10, 0, 100], [0, 5, 200]]);

print(mat);
//   10.0000         0  100.0000
//         0    5.0000  200.0000

// create vector
const vec = tensor([1, 1, 1]);

// matrix-vector multiply
print(mulV(null, mat, vec));
//  110.0000  205.0000

Authors

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-tensors,
  title = "@thi.ng/tensors",
  author = "Karsten Schmidt",
  note = "https://thi.ng/tensors",
  year = 2018
}

License

© 2018 - 2025 Karsten Schmidt // Apache License 2.0