Standard Library

Library Overview

The module map, import conventions, kernel/wrapper pattern, and every library in the repository.

Vyne has two library layers:

  • Native modules implemented in C++ for the interpreter or C/C++ for compiled desktop and embedded targets. They are available through use native <name>.
  • External libraries written in Vyne itself under vyne/modules/external/. They are imported through use external "<lib>/<facade>.vy".

The external layer is where most numerical work lives. Numerical libraries typically separate typed kernels, interfaces, validation/allocation, and a facade. Some external libraries are hybrid native-backed facades: vplot uses a shared native rendering core, vraylib wraps vendored graphics/audio, and vtensor/vnn compose explicit device intrinsics. Their import syntax is still use external; their native storage has its own ownership/lifetime rules.

Native modules

ModulePurpose
vcoreTime, sleep, platform, input, string builder, process/memory info, realtime telemetry.
vmathTrig, exp/log, rounding, sigmoid/relu, clamp, PCG32 random, constants.
vmemArena checkpoints, peak/live accounting, commit/stream stats, diagnostics.
vfsFilesystem read/write, lines, bytes, walk, glob, mkdir, path operations.
arduinoAVR-only: 110 bindings for serial, GPIO, ADC, I2C/SPI, EEPROM, bits, interrupts, watchdog, realtime.
esp32ESP32 firmware: shared MCU calls plus Wi-Fi/HTTP, NVS, display/sprites, touch, IMU, and power.
 vyne snippetvyne
use native vmath; use native vfs; use native vmem; out(vmath.sqrt(9.0)); out(vfs.read("data/input.txt")); out(vmem.total_allocated());

Numerical libraries

LibraryWhat it gives you
vlinDense matrices and vectors, arithmetic, products, reductions, activations, in-place training kernels.
vmlCPU dense/MLP layers, Sequential, activations, losses, and optimizer helpers over vlin matrices.
vfftRadix-2 FFT with cached twiddle factors, inverse, magnitude/phase.
vrandContinuous/discrete distributions and sampling.
vstatDescriptive statistics, correlation, regression, histograms, streaming moments, PSNR/SSIM.
vcomplexComplex scalars, elementary functions, polar helpers, split-array kernels.
vinterp1-D curves and 2-D grids: nearest, linear, cubic, spline, bicubic.
voptimSGD, momentum, Nesterov, Adam, AdamW, RMSProp, Adagrad, schedules.
vsparseCSR, SpMV, residuals, conjugate gradient.
vdecompLU, QR, Cholesky, Jacobi eigen, singular values, direct solves.
vtensorRegion-local device handle plus HWC shape metadata and crop staging.
vnnExplicit device CNN forward/backward, MSE, pixel shuffle, and AdamW blocks.

DSP & control

LibraryWhat it gives you
vsignalMoving averages, exponential/FIR/median/biquad filters, windows, resampling, spectra.
vcontrolPID, complementary filter, scalar and constant-velocity Kalman, state-space models.

Data & plotting

LibraryWhat it gives you
vcsvRFC 4180 CSV/TSV parse/write, typed columns, vfs-backed I/O.
vjsonJSON parse, serialize, validate, path access.
vtermplotLine, scatter, bar, histogram, heatmap, sparkline in the terminal.
vplotUniversal colorful charts, managed quick starts, bounded live series, ESP32 and image surfaces.

Image & vision

LibraryWhat it gives you
vimagePNG/JPEG/BMP/TGA I/O, bilinear resize, crop, grayscale.
vconvConv2d, activations, pixel shuffle, backward kernels, weight bundles.

Graphics & audio

Library / guideWhat it gives you
Managed vraylibApp-owned typed resources, frame lifetimes, cameras, shader uniforms, render targets, music, and Sound.
vraylib native referenceVendored raylib 6.2, raymath, and rlgl; checked native resources and pointer adapters.

vraylib needs the compiled desktop backend and platform graphics tools. vtensor and vnn require active device regions for device helpers. They do not turn the CPU vml API into automatic GPU tensor AD.

Embedded buses

LibraryWhat it gives you
vi2cTyped, range-checked I2C master helpers.
vspiTyped, range-checked SPI master helpers.

Domain libraries

LibraryWhat it gives you
vbioDNA/RNA/protein types, codon table, translation, composition, melting temperature.
vchemPeriodic-table constants and element properties, CSR graph construction, BFS/DFS/Dijkstra.

Helpers

FileWhat it gives you
vcolors.vyANSI color and terminal styling constants.
vconvert.vyTemperature, distance, and unit conversions.
vplot.vyA minimal bar chart helper.
vplot/vplot.vyUniversal colorful charts, bounded live series, ESP32 and image surfaces.
vstring.vySmall string helpers (upper, lower, and similar).

Import conventions

 vyne snippetvyne
use native vmath; # native module use external "vlin/vlin.vy"; # external library facade use external "voptim/voptim.vy"; use "model.vy"; # project-local source file

A facade imports its leaves and ends with deploy:

 vyne/modules/external/vsignal/vsignal.vyvyne
use "Types.vy"; use "Constructors.vy"; use "Kernels.vy"; use "Iir.vy"; use "Fir.vy"; use "Windows.vy"; use "Resample.vy"; ruleset { dynamic_casting }; module vsignal; deploy vsignal;

Kernel/wrapper pattern

 snippettext
Kernels.vy # unboxed loops over Array<Float64>; native-array ABI Types.vy # interfaces: Matrix, Series, Dense, filter/controller state Ops.vy / ... # validation, allocation, dispatch <lib>.vy # facade: imports leaves, declares module, deploys

Kernels have the shape (Array<Float64>, Int64) -> Float64 or (Array<Float64>, Array<Float64>, Int64) -> Int64. The transpiler recognizes the shape and emits a direct C function. Wrappers handle shape validation, allocation, and dispatch.

  • vstat and vinterp keep a typed buffer and its length together in a Series / Curve.
  • vsignal and vcontrol keep streaming state in an Array<Float64> field, so a step updates shared state instead of returning a new struct.
  • voptim keeps parameters and moments in typed arrays and exposes native update kernels plus pure schedules.
  • vsparse stores CSR values/indices/row pointers in typed arrays; cg reuses one Ap buffer so peak memory is O(rows) independent of iteration count.
  • vdecomp takes flat row-major arrays plus dimensions in raw routines and adds Matrix wrappers for solves and factorisations.

BLAS dispatch

vlin.multiply and vlin.multiply_trans_b lower to cblas_dgemm when the compiler is invoked with --blas. The dispatch table lives in compiler/codegen/blas_dispatch.h; the runtime bridge is runtime/detail/blas_bridge.h. Source is unchanged between modes; only the matched call lowering differs. --blas is desktop-only.

Tests and benchmarks

Each library ships tests and at least one benchmark:

  • examples/test/<lib>_test.vy (older libraries) or examples/libs/<lib>_test.vy (newer libraries).
  • examples/benchmark/<lib>_bench.vy or examples/libs/<lib>_bench.vy.

Run them with vynec --compile <file> followed by the produced executable, or vynec run <file> for interpreter-friendly tests.

Legacy modules

vglib, vaudio, vserv, vnet, vcv, and vurage are no longer maintained. The language's purpose has shifted to scientific numerical computing with a first-class embedded target. The code may still exist for archival purposes, but it is not part of the supported surface, is not tested in CI, and is not documented here. Pin to a pre-0.4 tag if you depend on them.

See also