README.md

June 1, 2026 · View on GitHub

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.

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

Features

Tensors — create, slice, reshape, transpose, broadcast, map/reduce
Autograd — reverse-mode AD; arbitrary computational graphs
Neural networks — Sequential API; Linear, Conv2D, LSTM, Attention, …
Losses & optimizers — MSE, BCE, CrossEntropy, Huber; Adam, AdamW, SGD, …
Linear algebra — VSL-backed matmul, solve, QR, LU, Cholesky, SVD, pinv
Hardware — zero-copy Tensor.data for C libs; optional CUDA and Vulkan training paths

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, CUDA backward, activation chain, Adam slots
Vulkan	Experimental opt-in f32 Linear, Conv2D same-padding, ReLU/Sigmoid, 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
`vtl`	Core `Tensor[T]`; creation, slicing, broadcasting
`vtl.autograd`	`Context`, `Variable`, gates, `backprop()`
`vtl.la`	Linear algebra (wraps VSL)
`vtl.nn`	Layers, losses, optimizers
`vtl.nn.models`	`Sequential` model API
`vtl.nn.internal`	Weight init (Kaiming, Xavier)
`vtl.nn.gates`	Autograd gate implementations

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

v test ~/.vmodules/vtl

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
Use GPU paths safely	DEV_LIGHTWEIGHT.md, DEVICE_MEMORY.md

Tutorial	Topic
TUTORIAL_FIRST_STEPS.md	Tensor creation, indexing, slicing
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_ADVANCED_LA.md	QR, LU, Cholesky, pinv
TUTORIAL_BROADCASTING.md	Broadcasting rules
TUTORIAL_SLICING.md	Slicing and views

Full index: docs/README.md.

Contributors

Originally based on work by christopherzimmerman. The core was reimplemented while keeping that lineage and inspiration.

Made with contributors-img.

License

MIT