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 throughuse 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
| Module | Purpose |
|---|---|
vcore | Time, sleep, platform, input, string builder, process/memory info, realtime telemetry. |
vmath | Trig, exp/log, rounding, sigmoid/relu, clamp, PCG32 random, constants. |
vmem | Arena checkpoints, peak/live accounting, commit/stream stats, diagnostics. |
vfs | Filesystem read/write, lines, bytes, walk, glob, mkdir, path operations. |
arduino | AVR-only: 110 bindings for serial, GPIO, ADC, I2C/SPI, EEPROM, bits, interrupts, watchdog, realtime. |
esp32 | ESP32 firmware: shared MCU calls plus Wi-Fi/HTTP, NVS, display/sprites, touch, IMU, and power. |
Numerical libraries
| Library | What it gives you |
|---|---|
vlin | Dense matrices and vectors, arithmetic, products, reductions, activations, in-place training kernels. |
vml | CPU dense/MLP layers, Sequential, activations, losses, and optimizer helpers over vlin matrices. |
vfft | Radix-2 FFT with cached twiddle factors, inverse, magnitude/phase. |
vrand | Continuous/discrete distributions and sampling. |
vstat | Descriptive statistics, correlation, regression, histograms, streaming moments, PSNR/SSIM. |
vcomplex | Complex scalars, elementary functions, polar helpers, split-array kernels. |
vinterp | 1-D curves and 2-D grids: nearest, linear, cubic, spline, bicubic. |
voptim | SGD, momentum, Nesterov, Adam, AdamW, RMSProp, Adagrad, schedules. |
vsparse | CSR, SpMV, residuals, conjugate gradient. |
vdecomp | LU, QR, Cholesky, Jacobi eigen, singular values, direct solves. |
vtensor | Region-local device handle plus HWC shape metadata and crop staging. |
vnn | Explicit device CNN forward/backward, MSE, pixel shuffle, and AdamW blocks. |
DSP & control
| Library | What it gives you |
|---|---|
vsignal | Moving averages, exponential/FIR/median/biquad filters, windows, resampling, spectra. |
vcontrol | PID, complementary filter, scalar and constant-velocity Kalman, state-space models. |
Data & plotting
| Library | What it gives you |
|---|---|
vcsv | RFC 4180 CSV/TSV parse/write, typed columns, vfs-backed I/O. |
vjson | JSON parse, serialize, validate, path access. |
vtermplot | Line, scatter, bar, histogram, heatmap, sparkline in the terminal. |
vplot | Universal colorful charts, managed quick starts, bounded live series, ESP32 and image surfaces. |
Image & vision
| Library | What it gives you |
|---|---|
vimage | PNG/JPEG/BMP/TGA I/O, bilinear resize, crop, grayscale. |
vconv | Conv2d, activations, pixel shuffle, backward kernels, weight bundles. |
Graphics & audio
| Library / guide | What it gives you |
|---|---|
| Managed vraylib | App-owned typed resources, frame lifetimes, cameras, shader uniforms, render targets, music, and Sound. |
| vraylib native reference | Vendored 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
| Library | What it gives you |
|---|---|
vi2c | Typed, range-checked I2C master helpers. |
vspi | Typed, range-checked SPI master helpers. |
Domain libraries
| Library | What it gives you |
|---|---|
vbio | DNA/RNA/protein types, codon table, translation, composition, melting temperature. |
vchem | Periodic-table constants and element properties, CSR graph construction, BFS/DFS/Dijkstra. |
Helpers
| File | What it gives you |
|---|---|
vcolors.vy | ANSI color and terminal styling constants. |
vconvert.vy | Temperature, distance, and unit conversions. |
vplot.vy | A minimal bar chart helper. |
vplot/vplot.vy | Universal colorful charts, bounded live series, ESP32 and image surfaces. |
vstring.vy | Small string helpers (upper, lower, and similar). |
Import conventions
A facade imports its leaves and ends with deploy:
Kernel/wrapper pattern
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.
vstatandvinterpkeep a typed buffer and its length together in aSeries/Curve.vsignalandvcontrolkeep streaming state in anArray<Float64>field, so a step updates shared state instead of returning a new struct.voptimkeeps parameters and moments in typed arrays and exposes native update kernels plus pure schedules.vsparsestores CSR values/indices/row pointers in typed arrays;cgreuses oneApbuffer so peak memory is O(rows) independent of iteration count.vdecomptakes flat row-major arrays plus dimensions in raw routines and addsMatrixwrappers 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) orexamples/libs/<lib>_test.vy(newer libraries).examples/benchmark/<lib>_bench.vyorexamples/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.