import vsl.la as la

mut a := la.Matrix.new[f64](2, 2)
a.set(0, 0, 1.0)
a.set(1, 1, 2.0)
println(a.get(1, 1))
// 2.0

VSL is a V library for AI and high-performance scientific computing.

📖 Documentation

Visit VSL Documentation to explore all supported features and APIs.

Start Here

Need	Go to
Scientific computing overview	Docs index
Working examples	Examples catalog
ML/GPU release status	ML roadmap
CUDA backend	cuda/README.md
Vulkan backend	vulkan/README.md
Benchmarks	benchmarks/README.md
Tensor/autograd/NN layer	VTL

VSL is a comprehensive Scientific Computing Library offering a rich ecosystem of mathematical and computational modules. The library provides both pure-V implementations and optional high-performance backends through established C and Fortran libraries.

🔬 Core Capabilities

• Linear Algebra: Complete matrix and vector operations, eigenvalue decomposition, linear solvers
• Machine Learning: Clustering algorithms (K-means), classification (KNN), regression, and NLP tools
• Numerical Methods: Differentiation, integration, root finding, polynomial operations
• Data Visualization: Advanced plotting with Plotly-style API supporting 2D/3D charts
• Scientific Computing: FFT, statistical analysis, probability distributions
• Parallel Computing: MPI support and OpenCL acceleration
• Data I/O: HDF5 integration for scientific data formats

⚡ Performance Architecture

VSL provides flexible performance options:

• Pure V Implementation: High-performance, dependency-free BLAS/LAPACK implementations
• Optimized Backends: Optional integration with OpenBLAS, LAPACK, MPI, OpenCL (VCL), Vulkan Compute, and CUDA (cuBLAS/cuDNN) for maximum performance
• GPU Acceleration: OpenCL/VCL, Vulkan Compute, and CUDA support for computationally intensive operations

Pure V BLAS/LAPACK implementations deliver competitive performance while eliminating external dependencies. Benchmark results demonstrate excellent performance characteristics across a wide range of problem sizes.

Each module clearly documents compilation flags and backend requirements, allowing users to choose the optimal configuration for their specific use case.

Compute Standardization

VSL compute backends are organized with a unified structure:

• vsl/compute — backend-agnostic dispatch API
• vsl/vcl/compute — OpenCL/VCL backend implementation
• vsl/vulkan/compute — Vulkan backend implementation
• vsl/cuda/compute — CUDA/cuBLAS/cuDNN backend (-d cuda; see cuda/README)

The recommended integration point for downstream libraries is vsl.compute.

Backend Status

For the V ML beta, the stable integration contract is the portable scientific and vsl.compute surface used by downstream libraries. CUDA, Vulkan, and VCL remain opt-in acceleration backends; they are valuable for early adopters, but are not required for the default CPU beta path.

Backend	Build flag	Highlights	Downstream use
Pure V	none	Portable BLAS/LAPACK-style routines, gemm/gemv, elementwise ops, softmax, LayerNorm	Default path
C BLAS/LAPACK	-d vsl_blas_cblas, -d vsl_lapack_lapacke	Optimized CPU kernels	Heavy linear algebra
OpenCL/VCL	module-specific	Cross-vendor GPU kernels and examples; not a beta gate	Experimental GPU path
CUDA	-d cuda	cuBLAS/cuDNN GEMM, activations, softmax, Conv2D, LayerNorm	VTL CUDA training
Vulkan	-d vulkan	GEMM, Conv2D im2col, elementwise ops, fused Adam shader	VTL f32 Vulkan training

For neural networks, use VTL: VSL owns the compute primitives, and VTL owns tensors, autograd, layers, losses, optimizers, datasets, and training loops.

🚀 Installation & Quick Start

VSL supports multiple installation methods and deployment options to fit different development workflows.

📦 Package Manager Installation

Via V's built-in package manager:

v install vsl

Via vpkg:

vpkg get https://github.com/vlang/vsl

🐳 Docker Development Environment

For a pre-configured development environment with optional scientific dependencies:

1. Install Docker on your system

2. Clone the starter template:

   git clone https://github.com/ulises-jeremias/hello-vsl
   cd hello-vsl
   

3. Follow the setup instructions in the template's README

This approach provides:

• Pre-configured environment with V, VSL, and all optional dependencies
• Cross-platform compatibility (Windows, Linux, macOS)
• Isolated development environment
• Access to optimized BLAS/LAPACK libraries

🔧 System Dependencies (Optional)

For enhanced performance, you can install optional system libraries:

• OpenBLAS/LAPACK: Linear algebra acceleration
• OpenMPI: Parallel computing support
• OpenCL: GPU acceleration
• HDF5: Scientific data format support

Refer to individual module documentation for specific compilation flags.

🧪 Testing

Use scoped tests during development to avoid compiling the whole scientific stack at once:

v test vsl/blas vsl/la vsl/compute
VSL_TEST_VULKAN=1 VJOBS=1 v -prod -d vulkan test vsl/vulkan/compute/adam_step_vulkan_test.v

For the repository test harness and optional GPU paths, see docs/ML_ROADMAP.md and vulkan/README.md.

📊 Performance Benchmarks

VSL includes comprehensive performance benchmarks using V's built-in benchmark module:

# Run all BLAS benchmarks
v run benchmarks/blas_bench.v

# Run all LAPACK benchmarks
v run benchmarks/lapack_bench.v

# Compare pure V vs C backends
v -d vsl_blas_cblas run benchmarks/compare_backends.v

Benchmark results show performance characteristics for:

• BLAS Level 1: Vector operations (dot product, norms, scaling)
• BLAS Level 2: Matrix-vector operations (GEMV, GER)
• BLAS Level 3: Matrix-matrix operations (GEMM, SYRK)
• LAPACK: Linear system solvers, factorizations, eigenvalue problems

See benchmarks/README.md for detailed benchmark documentation.

👥 Contributors

Made with contributors-img.