SIMD Vector and Matrix Types in TornadoVM's Type System

TornadoVM’s vector and matrix types are lightweight value-class wrappers that map directly to GPU vector registers. Writing a kernel in terms of Float4 instead of four separate float variables lets the JIT compiler emit vectorized SIMD instructions on both GPU (OpenCL float4, CUDA float4) and CPU (AVX/NEON) backends without any intrinsic annotations. Every vector type lives in the package uk.ac.manchester.tornado.api.types.vectors, is annotated @Vector, and carries its payload in a small on-heap backing array tagged @Payload—a layout the TornadoVM compiler recognizes and maps to a vector register allocation. Matrix types in uk.ac.manchester.tornado.api.types.matrix follow the same principle but store their elements in a TornadoVM off-heap FloatArray / DoubleArray so the full matrix can be registered with a TaskGraph.

Why use vector types?

Register-width utilization

A single Float4.add maps to one 128-bit SIMD add instruction. Without vector types, the compiler may or may not auto-vectorize scalar loops.

GPU data-type parity

OpenCL and CUDA both define float2, float4, float8, float16 natively. TornadoVM vector types produce identical code to hand-written OpenCL C kernels.

Dot-product and norms

Float4.dot, Float4.length, Float4.normalise map to optimized math paths, avoiding manual intermediate stores.

Type safety

Mixing element widths (e.g. Float4 + Int4) is caught at compile time and handled via explicit overloads rather than implicit casts.

Float vector types

Float vectors cover widths 2, 3, 4, 8, and 16 lanes. Float2, Float3, and Float4 use named accessors (.getX(), .getY(), .getZ(), .getW()); Float8 and Float16 use lane indices .getS0() through .getS7() / .getS15().

`Float2`

Two single-precision floats: x and y.

import uk.ac.manchester.tornado.api.types.vectors.Float2;

Float2 a = new Float2(1.0f, 2.0f);
Float2 b = new Float2(3.0f, 4.0f);

Float2 sum  = Float2.add(a, b);   // (4.0, 6.0)
Float2 prod = Float2.mult(a, b);  // (3.0, 8.0)
float  dot  = Float2.dot(a, b);   // 1*3 + 2*4 = 11.0

new Float2()

constructor

Zero-initializes both lanes.

new Float2(float x, float y)

constructor

Initializes x and y lanes explicitly.

getX() / getY()

float

Returns the x (index 0) or y (index 1) lane value.

setX(float) / setY(float)

void

Sets the x or y lane.

Float2.add / sub / mult / div

static Float2

Element-wise arithmetic. Overloads accept (Float2, Float2), (Float2, float), and mixed (Float2, Int2) / (Int2, Float2).

Float2.min / max

static Float2

Element-wise minimum or maximum.

Float2.dot(Float2 a, Float2 b)

static float

Returns the scalar dot product a.x*b.x + a.y*b.y.

Float2.length(Float2 v)

static float

Euclidean length: sqrt(dot(v, v)).

`Float3`

Three single-precision floats: x, y, z. Commonly used in 3D geometry kernels.

Float3 v = new Float3(1.0f, 0.0f, 0.0f);
Float3 w = new Float3(0.0f, 1.0f, 0.0f);

Float3 cross  = Float3.cross(v, w);   // (0, 0, 1)
Float3 unit   = Float3.normalise(v);  // (1, 0, 0) — already unit
float  length = Float3.length(v);     // 1.0

new Float3(float x, float y, float z)

constructor

Initializes all three lanes.

getZ() / setZ(float)

float / void

Accessor for the z (index 2) lane.

Float3.cross(Float3 a, Float3 b)

static Float3

Returns the cross product a × b.

Float3.normalise(Float3 v)

static Float3

Returns v / length(v).

asFloat2()

Float2

Casts the first two lanes to a Float2.

`Float4`

Four single-precision floats: x, y, z, w. The most widely used vector type in TornadoVM—maps to a 128-bit register on every supported backend.

Float4 a = new Float4(1f, 2f, 3f, 4f);
Float4 b = new Float4(4f, 3f, 2f, 1f);

Float4 scaled = Float4.scale(a, 2.0f);          // (2, 4, 6, 8)
Float4 clamped = Float4.clamp(a, 1.5f, 3.5f);  // (1.5, 2, 3, 3.5)
float  dot    = Float4.dot(a, b);               // 1*4+2*3+3*2+4*1 = 20

getW() / setW(float)

float / void

Accessor for the w (index 3) lane.

Float4.dot(Float4 a, Float4 b)

static float

Four-lane dot product.

Float4.sqrt(Float4 a)

static Float4

Element-wise square root.

Float4.floor(Float4 a)

static Float4

Element-wise floor.

Float4.fract(Float4 a)

static Float4

Element-wise fractional part.

Float4.clamp(Float4 x, float min, float max)

static Float4

Clamps each lane to [min, max].

Float4.normalise(Float4 v)

static Float4

Returns the unit vector in the same direction.

Float4.sum(Float4 a)

static float

Returns the scalar horizontal sum of all four lanes.

asFloat2() / asFloat3()

Float2 / Float3

Truncating casts to narrower vector types.

getLow() / getHigh()

Float2

Returns the low two lanes (x, y) or high two lanes (z, w) as a Float2.

`Float8` and `Float16`

Eight-lane and sixteen-lane float vectors. Lanes are accessed by index suffix: .getS0() through .getS7() (Float8) or .getS0() through .getS15() (Float16). All arithmetic operations (add, sub, mult, div, min, max, sqrt, dot) are available as static methods with the same signatures as Float4.

Float8 v = new Float8(1f, 2f, 3f, 4f, 5f, 6f, 7f, 8f);
float lane3 = v.getS3();         // 4.0
Float8 doubled = Float8.mult(v, 2.0f);
float dotProduct = Float8.dot(v, v); // sum of squares = 204.0

Float16 maps to a 512-bit register on AVX-512 CPUs and is particularly effective on CPU backends. On GPU backends it is split into two 256-bit or four 128-bit operations by the hardware.

Int vector types

Integer vectors follow the same lane-count progression: Int2, Int3, Int4, Int8, Int16. Named accessors .getX() / .getY() / .getZ() / .getW() apply to widths 2–4; lane-index accessors .getS0()–.getSN() apply to 8 and 16. Arithmetic operations match their Float counterparts.

import uk.ac.manchester.tornado.api.types.vectors.Int4;

Int4 idx  = new Int4(0, 1, 2, 3);
Int4 step = new Int4(4, 4, 4, 4);
Int4 next = Int4.add(idx, step);  // (4, 5, 6, 7)

Integer vector types do not have sqrt, normalise, or length methods—those are only defined on float and double types.

Double vector types

Double-precision vectors: Double2, Double3, Double4, Double8, Double16. They follow the same pattern as float vectors but use double lanes and DoubleBuffer as their NIO buffer type. Use these when FP64 precision is required (e.g. scientific simulations) and the target GPU has adequate FP64 throughput.

import uk.ac.manchester.tornado.api.types.vectors.Double4;

Double4 pos = new Double4(1.0, 2.0, 3.0, 4.0);
Double4 vel = new Double4(0.1, 0.2, 0.3, 0.4);
Double4 newPos = Double4.add(pos, vel);
double  norm   = Double4.length(pos);

Half-precision vector types

The Half2, Half3, Half4, Half8, and Half16 types in the vectors package hold HalfFloat lanes for FP16 arithmetic in GPU kernels. Element-wise add, sub, mult, and div are defined, each delegating to the HalfFloat arithmetic helpers.

import uk.ac.manchester.tornado.api.types.vectors.Half2;
import uk.ac.manchester.tornado.api.types.HalfFloat;

HalfFloat x = new HalfFloat(1.5f);
HalfFloat y = new HalfFloat(2.5f);
Half2 v = new Half2(x, y);
Half2 doubled = Half2.mult(v, new HalfFloat(2.0f));

Half2 is also used by HalfFloatArray.getHalf2(int) for packed 32-bit aligned loads from FP16 buffers.

Matrix types

TornadoVM provides 2D and 3D matrix types backed by off-heap FloatArray / DoubleArray storage in row-major order, making them compatible with TaskGraph data-transfer operations.

`Matrix2DFloat`

A rectangular float matrix stored in row-major order.

import uk.ac.manchester.tornado.api.types.matrix.Matrix2DFloat;

// 4×4 matrix, all zeros
Matrix2DFloat m = new Matrix2DFloat(4, 4);

// Set and get by (row, col)
m.set(0, 0, 1.0f);
m.set(1, 1, 1.0f);
float val = m.get(0, 0); // 1.0f

// From a 2D Java array
float[][] data = {{1,2},{3,4}};
Matrix2DFloat fromJava = new Matrix2DFloat(data);

// In-place square transpose
Matrix2DFloat.transpose(m);

// Scale all elements
Matrix2DFloat.scale(m, 2.0f);

Matrix2DFloat(int rows, int columns)

constructor

Allocates an off-heap float matrix of the given dimensions.

Matrix2DFloat(int rows, int columns, FloatArray array)

constructor

Wraps an existing FloatArray as a matrix view; no copy is made.

get(int i, int j)

float

Returns the element at row i, column j.

set(int i, int j, float value)

void

Sets the element at row i, column j.

clear()

void

Zeros all elements of the underlying FloatArray.

Similar classes exist for Matrix2DDouble, Matrix2DInt, Matrix3DFloat, Matrix3DDouble, Matrix3DInt, Matrix3DLong, Matrix3DShort, and Matrix2DFloat4 (elements are Float4 vectors).

Using vector types in parallel kernels

Vector types work in both @Parallel index-space kernels and KernelContext kernels. The example below shows a parallel RGBA image desaturation using Float4 to process four channel values per pixel in one SIMD operation.

import uk.ac.manchester.tornado.api.annotations.Parallel;
import uk.ac.manchester.tornado.api.types.arrays.FloatArray;
import uk.ac.manchester.tornado.api.types.vectors.Float4;

public class ImageKernels {

    // Each element of 'pixels' holds RGBA as (r, g, b, a) packed in four floats.
    // 'out' receives the greyscale-weighted luminance replicated to R, G, B.
    public static void desaturate(FloatArray pixels, FloatArray out) {
        for (@Parallel int i = 0; i < pixels.getSize() / 4; i++) {
            int base = i * 4;
            Float4 rgba = new Float4(
                pixels.get(base),
                pixels.get(base + 1),
                pixels.get(base + 2),
                pixels.get(base + 3)
            );
            // BT.601 luminance weights
            Float4 weights = new Float4(0.2989f, 0.5870f, 0.1140f, 0.0f);
            float luma = Float4.dot(rgba, weights);
            out.set(base,     luma);
            out.set(base + 1, luma);
            out.set(base + 2, luma);
            out.set(base + 3, rgba.getW()); // keep alpha
        }
    }
}

Vector and matrix type summary

Float family

Float2 · Float3 · Float4 · Float8 · Float16
Collections: VectorFloat2–VectorFloat16

Int family

Int2 · Int3 · Int4 · Int8 · Int16
Collections: VectorInt2–VectorInt16

Double family

Double2 · Double3 · Double4 · Double8 · Double16
Collections: VectorDouble2–VectorDouble16

Half family

Half2 · Half3 · Half4 · Half8 · Half16
Collections: VectorHalf2–VectorHalf16

Byte / Short

Byte3 · Byte4 · Short2 · Short3

Matrix types

Matrix2DFloat · Matrix2DDouble · Matrix2DInt
Matrix3DFloat · Matrix3DDouble · Matrix2DFloat4

Core API

Data Types

Library Tasks

SIMD Vector and Matrix Types in TornadoVM's Type System

Why use vector types?

Register-width utilization

GPU data-type parity

Dot-product and norms

Type safety

Float vector types

`Float2`

`Float3`

`Float4`

`Float8` and `Float16`

Int vector types

Double vector types

Half-precision vector types

Matrix types

`Matrix2DFloat`

Using vector types in parallel kernels

Vector and matrix type summary

Float family

Int family

Double family

Half family

Byte / Short

Matrix types

Build docs developers (and LLMs) love

Core API

Data Types

Library Tasks

Documentation Index

​Why use vector types?

Register-width utilization

GPU data-type parity

Dot-product and norms

Type safety

​Float vector types

​Float2

​Float3

​Float4

​Float8 and Float16

​Int vector types

​Double vector types

​Half-precision vector types

​Matrix types

​Matrix2DFloat

​Using vector types in parallel kernels

​Vector and matrix type summary

Float family

Int family

Double family

Half family

Byte / Short

Matrix types

Build docs developers (and LLMs) love

Why use vector types?

Float vector types

`Float2`

`Float3`

`Float4`

`Float8` and `Float16`

Int vector types

Double vector types

Half-precision vector types

Matrix types

`Matrix2DFloat`

Using vector types in parallel kernels

Vector and matrix type summary