The V Tensor Library

VTL is a pure-V tensor library for numerical computing and machine learning — n-dimensional arrays, autograd, linear algebra via VSL, and a full neural network module.

Train small neural networks, experiment with autograd, and use VSL-backed CPU, CUDA, and Vulkan compute paths from one V-native API.

vlang.io | Docs | Tutorials | Histograms | PyTorch parity | Burn comparison | ML Roadmap | Contributing | VSL

VTL and VSL architecture

View SVG source · PNG

import vtl
t := vtl.from_array([1.0, 2, 3, 4], [2, 2])!
t.get([1, 1])
// 4.0

Features

• Tensors — create, slice, indexed take/take_nd/take_flat/put, choose/select, round_decimals, nan_to_num, compress, indices, pad, set membership, reshape, transpose, move/roll axes, N-D diagonal views, NumPy-style Kronecker products, broadcast, map/reduce, einsum, and complex128 storage with elementwise and matrix products
• Autograd — reverse-mode AD; arbitrary computational graphs
• Neural networks — Sequential API; Linear, Conv2D, LSTM, Attention, …
• Losses & optimizers — MSE, MAE, BCE, Hinge, Focal, CrossEntropy, Huber; Adam, AdamW, NAdam, RAdam, SGD, …
• Linear algebra — VSL-backed real matmul and general eigensolvers, pure-V complex128 matmul, solve, QR, LU, Cholesky, SVD, pinv
• Hardware — zero-copy Tensor.data for C libs; optional CUDA and Vulkan training paths

ML Release Highlights

The ML beta scope is the high-level VTL API: tensors, autograd, layers, losses, optimizers, datasets, and CPU training. CUDA and Vulkan paths are available for opt-in validation and early adopters, but remain experimental backend accelerators rather than stable user contracts.

Area	Status
f32 training	Sequential + MSE + Adam smoke tests
CUDA	Experimental opt-in Linear/Conv2D forward; f64 Linear/Conv2D/Dropout backward; activation chain and Adam slots
Vulkan	Experimental opt-in f32 Linear, Conv2D same-padding, ReLU/Sigmoid/Softplus/SELU/HardSwish, fused Adam shader
Datasets	MNIST, IMDB, CIFAR-10 loaders plus CI-safe synthetic examples
Benchmarks	VTL vs NumPy/PyTorch scripts and PR benchmark workflow

For memory-safe local commands, see DEV_LIGHTWEIGHT.md.

Quick start

import vtl
import vtl.autograd
import vtl.nn.layers
import vtl.nn.models
import vtl.nn.optimizers

mut ctx := autograd.ctx[f32]()
mut model := models.sequential_from_ctx[f32](ctx)
model.input([784])
model.linear(256)
model.linear(10)
model.mse_loss()

input_tensor := vtl.zeros[f32]([64, 784])
mut x := ctx.variable(input_tensor)
y_pred := model.forward(x)!

target := vtl.zeros[f32]([64, 10])
mut loss_val := model.loss(y_pred, target)!
loss_val.backprop()!

mut opt := optimizers.adam_optimizer[f32](optimizers.AdamOptimizerConfig{
	learning_rate: 0.001
})
opt.build_params(model.info.layers)
opt.update()!

Module overview

Module	Purpose	Guide
vtl	Tensor creation, slicing, broadcasting, reductions	First steps
Complex tensors	math.complex.Complex storage and elementwise arithmetic	Complex tensors
vtl.fft	Real and complex FFTs via VSL PocketFFT	FFT
vtl.csv	Numeric CSV tensor input and output	NumPy I/O
vtl.npy / vtl.npz	Typed NumPy array and archive I/O	NumPy I/O
vtl.autograd	Differentiable operations and backpropagation	Autograd
vtl.autograd_cuda	Optional CUDA autograd	Device memory
vtl.la	VSL-backed linear algebra	Linear algebra
vtl.nn	Layers, losses, optimizers, and training	Neural networks
vtl.nn.models	Model construction, training, serialization	Neural networks
vtl.nn.layers	Dense, convolutional, recurrent, and attention layers	Neural networks
vtl.nn.loss	Regression and classification losses	Neural networks
vtl.nn.optimizers	Optimizers and learning-rate schedulers	Optimizers
vtl.nn.data	Neural-network data loaders	Examples
vtl.nn.internal	Internal tensor and activation operations	Source
vtl.nn.gates	Neural-network autograd gates	Autograd
vtl.datasets	MNIST, CIFAR-10, and IMDB loaders	Datasets
vtl.stats	Averages, descriptive statistics, and summaries	Reductions
Core lookup	Unique values, indexing, and set operations	Indexing
vtl.ml.metrics	Machine-learning metrics and evaluation	Source
vtl.storage	CPU, CUDA, VCL, and Vulkan storage	Device memory

Installation

VTL uses VSL for linear algebra. The core vtl module works without optional system BLAS/LAPACK, but LA features need VSL.

Follow VSL install instructions, then:

v install vtl

Testing

# Run the full scoped suite from ~/.vmodules; compiler parallelism is disabled
# to keep the local memory ceiling predictable.
cd ~/.vmodules
systemd-run --user --scope --property=MemoryMax=4G --property=MemorySwapMax=0 \
	env VJOBS=2 VTL_NO_PARALLEL=1 ./vtl/bin/test

See DEV_LIGHTWEIGHT.md for memory-safe subsets in CI.

Documentation

Start Here

Goal	Read
Learn tensors	First steps
Learn autograd	Autograd tutorial
Build neural networks	Neural networks
Pick optimizers	Optimizers
Run examples	Examples catalog
Use datasets	Datasets
Exchange NumPy .npy arrays	.npy input/output
Quantize tensors for INT8 inference	Quantization API, example
Load numeric CSV data	CSV and NumPy I/O
Use GPU paths safely	DEV_LIGHTWEIGHT.md, DEVICE_MEMORY.md

Tutorial	Topic
TUTORIAL_FIRST_STEPS.md	Tensor creation, indexing, slicing
TUTORIAL_MATH_UFUNCS.md	NumPy-style elementwise math and binary decomposition
TUTORIAL_MAP_REDUCE.md	map / nmap and reductions
TUTORIAL_AUTOGRAD.md	Variable, gates, backprop
TUTORIAL_REDUCTIONS.md	argmax / argmin / cumsum
TUTORIAL_NEURAL_NETWORKS.md	Layers, losses, Sequential
TUTORIAL_OPTIMIZERS.md	Adam, AdamW, RMSProp, schedulers
TUTORIAL_LINEAR_ALGEBRA.md	LA basics via VSL
TUTORIAL_FFT.md	One-dimensional real Fourier transforms via PocketFFT
TUTORIAL_ADVANCED_LA.md	QR, LU, Cholesky, pinv
TUTORIAL_BROADCASTING.md	Broadcasting rules
TUTORIAL_SLICING.md	Slicing and views

Full index: docs/README.md.

Contributors

VTL's early development was inspired by vnum, part of the Vlang Num group, and the work of Christopher Zimmerman. The core was reimplemented while keeping that lineage and inspiration. The original vnum work carried a BSD 3-Clause license with attribution to vlang-num contributors; the historical license text is preserved in the VTL repository history. This acknowledgment records that history and does not change VTL's current license, shown below.

Made with contributors-img.

License

MIT