Tensors

Tensors are the fundamental data structure in Brain4J. All computations, models, and data transformations operate on tensors, which provide an efficient way to represent and manipulate high-dimensional data such as vectors, matrices, sequences, images, and text.

A tensor in Brain4J is defined by the following properties:

• Order (Rank): Number of indices required to uniquely identify an element. For example, scalars have order 0, vectors have order 1, and matrices have order 2. Note: In Brain4J scalars have rank 1, because they are.

• Shape: Number of elements along each dimension, or axis of the tensor. For example: an RGB image can be represented by a tensor with shape [color_channels, height, width].

• Stride: The number of elements to skip in order to access the next element in that dimension.

• Strides: A list containing the stride value for each dimension of the tensor.

Scalars in Brain4J have Rank = 1 because they are represented through a vector!

Device placement

In Brain4J, every tensor is associated with a specific execution device. A device defines where the tensor’s data is stored and where operations on that tensor are executed.

Currently, Brain4J supports the following devices:

• CPU (default)

• GPU (via OpenCL)

Creating tensors on a device

Tensors are created on the CPU by default. A tensor can be explicitly moved to another device when required.

Device device = Brain4J.firstDevice(); // gets the first device available
Tensor t = Tensors.random(1024, 1024); // CPU tensor

// moves the tensor to the GPU
Tensor gpuTensor = t.to(Device.GPU);

Whenever a tensor is located in the GPU, operations can be batched in a single command queue and planned for execution. Note: the data() method is not recommended for use when a tensor is hosted in the GPU.

Memory Layout

TODO

Broadcasting

Broadcasting allows tensors with compatible shapes to participate in the same operation without explicitly duplicating data.

A tensor can be broadcast along a dimension if its size in that dimension is either:

• equal to the target size, or

• equal to 1

Broadcasting is applied per-dimension, from the trailing axes.

Example

Tensor a = Tensors.random(4, 3);
Tensor b = Tensors.random(1, 3);

Tensor c = a.plus(b); // b is broadcast along the first dimension

Result shape: [4, 3]

Important notes

• Broadcasting does not allocate new memory for the broadcasted tensor.

• If shapes are not compatible, the operation fails with an error.

• Not all operations support broadcasting.

In-place operations & Mutability

TODO

Examples

Basic tensor creation

// Scalars, vectors and matrices
Tensor scalar = Tensors.scalar(10);          // order 0
Tensor vector = Tensors.vector(1, 2, 3, 4);  // shape [4]
Tensor matrix = Tensors.matrix(
    2, 3,
    0.1f, 0.2f, 0.3f,
    0.4f, 0.5f, 0.6f
); // shape [2, 3]

// Higher-order tensors
Tensor zeros = Tensors.zeros(1, 2, 3); // shape [1, 2, 3], order 3

int[] shape = { 28, 28 };
float[] data = new float[28 * 28];
// you can also create tensors by specifing both the shape and the data
Tensor full = Tensors.create(shape, data);

Random tensors and matrix multiplication

Tensor a = Tensors.random(2, 3);
Tensor b = Tensors.random(3, 4);

// Matrix multiplication (inner dimensions must match)
Tensor c = a.matmul(b); // shape [2, 4]

Copy vs in-place operations

Tensor x = Tensors.random(10);
Tensor y = Tensors.random(10);

// Creates a new tensor (x is not modified)
Tensor z = x.times(y);

// In-place operation (x is modified)
x.mul(y); // also returns x

Reshaping tensors (views)

Tensor t = Tensors.random(2, 3);

// Reshape does not copy values, it stores the reference
Tensor reshaped = t.reshape(3, 2);

// Modifying the view affects the original tensor
reshaped.set(42, 0, 0); // value 42 at 0, 0

Slicing tensors

Tensor m = Tensors.random(4, 4);

// Extracts a sub-tensor (view)
Tensor row = m.slice(Range.point(1), Range.all()); // second row (1), all columns

Mapping values

Tensor r = Tensors.random(24, 10); // shape doesn't matter here

// In-place modification
r.map(x -> x * 2); // multiplies each element by 2 with a lambda