Shapes & Broadcasting

Core v1 treats tensor shapes as ordered lists of extents. This page explains the practical rules used by the compiler and runtime.

Ranks and shapes

[]

Rank 0

Scalars are rank-0 tensors with an empty shape [].

[3] · [2, 3]

Rank 1 and 2

Vectors and matrices are rank-1 and rank-2 respectively.

[2, 3, 4]

Higher rank

Higher-rank tensors are just longer shape lists, e.g. [2, 3, 4].

Broadcasting in practice

Most Core v1 operators are elementwise and follow numpy-style broadcasting:

Shapes are aligned from the right.
Each dimension must either match or be 1 on one side.
If neither side is 1 and the extents differ, broadcasting fails.

a23

b13

out23

[2, 3] with [1, 3]: broadcasts to [2, 3]The helper example below. The dashed 1 stretches to 2.

a23

b43

out×3

[2, 3] with [4, 3]: broadcasting fails (E2101)Neither side is 1 and the extents differ.

The reference implementation exposes the helper:

use mind::shapes::engine::broadcast_shapes;

let a = [2, 3];
let b = [1, 3];
let out = broadcast_shapes(&a, &b).unwrap();
assert_eq!(out, vec![2, 3]);

The Core v1 catalogue is 17 operators; mindc ops --core-v1 prints the authoritative list with each operator’s arity, admissible dtypes, and whether it is differentiable. Broadcast failures are E2101; rank / shape expectation mismatches, including invalid reductions, are E2102.

tensor.relu

Unary elementwise

Output shape equals input shape.

add, sub, mul, div

Binary elementwise

Output shape is the broadcasted shape of the two inputs.

tensor.sum, tensor.mean

Reductions

Take an explicit axis list plus a keepdims flag. An empty axis list reduces over every dimension to a scalar ([]); with keepdims the reduced axes become length-1 instead of being removed.

tensor.reshape

Reshape

Source and target shapes must have the same element count when all dimensions are known.

tensor.transpose

Transpose

An explicit permutation, defaulting to full reversal; the axis list must be valid and duplicate-free.

tensor.expand_dims, tensor.squeeze

Dimension edits

expand_dims inserts a length-1 dimension at the requested position (negative axes count from the end); squeeze removes the axes explicitly listed, or every size-1 axis when the list is omitted.

tensor.index, tensor.slice, tensor.gather

Indexing

index removes the selected axis; slice keeps it and updates its size to end - start when both bounds are static; gather splices the index tensor’s shape into the target axis.

tensor.matmul

2D matmul

Both inputs must be rank-2, and shapes must satisfy A: [M, K], B: [K, N], producing [M, N]. A mismatched inner dimension is E2103.

tensor.dot

Dot

1D dot product.

tensor.conv2d

Convolution

NHWC/HWCF 2D convolution with stride and padding.

Reference shape engine

The reference shape engine lives in the main compiler repository:

mind::shapes::engine

Module

shapes_engine.rs