Skip to content

Tensor Math

This reference provides a deep dive into the mathematical operations available in Zigma. Powered by the dimal engine, Zigma treats all data—from single numbers to N-dimensional matrices—as Tensors, applying strict dimensional safety to every calculation.

Standard Arithmetic (Element-wise)

Standard operators work on scalars, vectors, and matrices. When applied to tensors of the same shape, these operations are performed element-wise.

Operator Description Dimension Rule
+ Addition Dimensions must match.
- Subtraction Dimensions must match.
* Multiplication Dimensions are multiplied.
/ Division Dimensions are divided.

Unary Operations

Operator Description Dimension Rule
|x| Absolute Value No change.
-x Negate Value No change.
x^2 Square Exponents are doubled.
/x Square Root Exponents must be even.

Linear Algebra

Zigma provides specialized operators for standard tensor contractions and transformations.

Operator Description Usage
. Dot Product scalar = vec_a . vec_b
@ Matrix Multiplication C = A @ B
.* Cross Product torque = r .* F (3D vectors only)
||v|| Magnitude/Length len = ||v||
A' Transpose A_T = A'
as (shape) Reshape B = A as (2, 3)

Einstein Summation (Einsum)

For complex tensor contractions that don't fit standard operators, Zigma supports einsum notation. This allows you to specify exactly how indices should be combined.

// Matrix multiplication equivalent: C_ij = Σ(A_ik * B_kj)
C = "ik,kj->ij" over A, B

// Trace of a matrix (sum of diagonals)
t = "ii->" over A

// Batched matrix multiplication
result = "ijk,kl->ijl" over T, U

Reductions

Reduction functions collapse one or more axes of a tensor into a smaller shape (or a scalar).

Available Functions

  • sum, prod
  • mean, median
  • std, var
  • min, max
  • quantile
  • all, any (Boolean logic)

Usage

You can reduce the entire tensor or specify axes.

A = [[1, 2], [3, 4]] m

total  = sum A          // Returns 10 m (Scalar)
by_col = sum A on 0     // Returns [4, 6] m (Vector)
by_row = sum A on 1     // Returns [3, 7] m (Vector)

// Multi-axis reduction
result = sum Tensor_4D on [0, 2]

Dimensional & Scale Rules

The Smallest Scale Rule

When performing math between different scales, Zigma automatically converts the result to the smallest involved scale to preserve precision.

d_0 = 5 mm
d_1 = 1 m

d = d_0 + d_1 // Result: 1005 mm

Broadcasting

Scalars can be operated against tensors of any shape. The scalar is "broadcast" across every element of the tensor.

gravity = [0, -9.81, 0] m/s2
mass = 10 kg

// Scalar 10 is multiplied by each element of the gravity vector
force = mass * gravity // Result: [0, -98.1, 0] kg.m/s2

SIMD Acceleration

Behind the scenes, Zigma transpiles these operations into Zig's @Vector intrinsics. This ensures that your tensor math utilizes SIMD (Single Instruction, Multiple Data) hardware acceleration on your CPU automatically, with no extra code required.