This site is version 0.0.1. Most of the code on this site is drafted by an agent and needs review. I apologize for the AI-speak, we are working on rewriting it!
viv-lang.org

vipyr vipyr

vipyr runs numerical code written in Viv from Python. Your own functions compile to C and come back as Python functions on NumPy arrays, and a library of programs checked against their reference codes is one import away.

63 functions run today. Each has a reference page with its signature, every parameter's type, default, range and units, the fields of its result, an example that ran when the page was built, and what it is checked against.

Data

Check feature code for future leakage, get the same numbers in training and serving, and compile custom per-group logic to C.

  • vp.features Per-entity features with state, called on a pandas DataFrame.
  • vp.check_point_in_time, vp.check_parity and vp.compile: the tools described under Getting started.

Customer features from a transaction log

Statistics

Probability distributions, summary statistics and regression, with the names and results of SciPy, statsmodels and R.

  • vp.stats Probability distributions, the special functions under them, descriptive statistics, least squares with inference, and generalized linear models.

Special functions against mpmath, SciPy and R

NIST's certified linear regressions, digit by digit

A probit GLM, R's way

Machine learning

A small GPT trained in compiled Viv and returned to Python as named arrays, matching a NumPy program and PyTorch step for step; scikit-learn pipelines compiled to one C file.

  • vp.gpt A small GPT (nanoGPT's shape, the speedrun's Muon and Adam) trained on text, sampled, and returned as named arrays.

A small GPT trained on one paragraph

Look inside this program

  • Atlas

    The program’s map: every function and which calls which.

  • Explore

    Run it and step through what each part did, with the code, values and plots beside it.

A quantized model file, read in Viv

A scikit-learn pipeline as one C file

Finance

Option pricing by closed form, binomial trees, Fourier inversion and finite differences, each checked against published values or SciPy.

  • vp.finance Black-Scholes, binomial trees, Heston by Fourier-cosine series, finite differences.

Implied volatility, binomial trees and Greeks of European options

The Heston model's volatility smile

Early exercise of an American put, priced two ways

Science

Classic research codes, callable from Python and checked against their originals: PySCF Hartree-Fock, BIGSTICK shell model, plane-wave DFT, Vlasov plasma, Monte Carlo.

  • vp.scf Hartree-Fock for molecules in Gaussian basis sets.
  • vp.dft Plane-wave density-functional theory of crystals.
  • vp.nuclear Mean-field and shell-model calculations of nuclei.
  • vp.plasma Kinetic simulations of a collisionless plasma.
  • vp.statmech Lattice models sampled by Monte Carlo, checked against exact solutions.

Water Hartree-Fock energies compared with PySCF

Look inside this program

  • Atlas

    The program’s map: every function and which calls which.

  • Explore

    Run it and step through what each part did, with the code, values and plots beside it.

Orbital energy levels of water and its cation

Look inside this program

  • Atlas

    The program’s map: every function and which calls which.

  • Explore

    Run it and step through what each part did, with the code, values and plots beside it.

The Boys function, the integral behind Gaussian basis sets

Atoms from hydrogen to uranium, against NIST

All 14 in Science →

Math

Differential equations, linear algebra, special functions and randomized sketches written as readable algorithms, checked against SciPy and mpmath.

  • vp.linalg The Euclidean norm, and SciPy-named aliases of vp.control's solvers.
  • vp.special Functions with no closed form that physics codes call in their inner loops.
  • vp.randla Low-rank approximations and trace estimates from random sketches.
  • vp.ode Stiff and non-stiff initial value problems: Dormand-Prince, Radau IIA and BDF, with events, exact Jacobians and batches.

Robertson's stiff kinetics over sixteen decades

Ten thousand epidemics in one call

Randomized trace estimation and low-rank kernel approximation

Thurber's electron mobility, a NIST certified fit

Look inside this program

  • Atlas

    The program’s map: every function and which calls which.

  • Explore

    Run it and step through what each part did, with the code, values and plots beside it.

All 5 in Math →

Dynamics and control

Riccati and Lyapunov solvers on the Schur form, LQR design and closed-loop simulation; every solution is checked by the residual of its equation.

  • vp.control LQR gains, Riccati and Lyapunov solvers, and closed-loop simulation of a cart-pole.

Balancing a cart-pole with LQR

A stability map for the cart-pole's feedback gains

Hardware

Logic built from NAND gates up, simulated gate by gate; a C compiler, an assembler and an RV32IM simulator, each written in Viv.

A four-bit adder from NAND gates, simulated exhaustively

A C compiler, an assembler and a RISC-V processor, all in Viv

Power systems

AC and DC power flow on MATPOWER cases, Newton-Raphson and fast-decoupled, with a sparse LU written in Viv, checked against MATPOWER's own solution of case9 and against an independent SciPy power flow on every case.

  • vp.power AC and DC power flow on MATPOWER cases: Newton-Raphson, fast-decoupled and DC.

Voltage profile of the IEEE 118-bus system

Power flow convergence and timing from 9 to 9241 buses

An interconnection study on the IEEE 118-bus system

The PV curve of a transfer into bus 38 of the IEEE 118-bus system

Install

git clone https://github.com/AdamZettel/viv && cd viv
cargo build --release -p viv
PYTHONPATH=python python3 -c "import vipyr as vp"

vipyr runs from a checkout of the repository and needs NumPy and a C compiler. The packages are not on PyPI yet; pip install vipyr is planned. Install has the details and the distributions each domain will ship in.

A first call

import numpy as np
import vipyr as vp

# the optimal gain for a cart-pole, and the system run under it
A, B = vp.control.cartpole_model(h=1e-5)
r = vp.control.lqr(A=A, B=B, Q=np.diag([1.0, 1.0, 20.0, 1.0]), R=np.array([[0.05]]))
r.K          # array([[ -4.4721,  -8.2239, -63.0331, -16.0163]])
r.check()    # CheckReport(passed=True, ...): the program's own tests on this run

Arguments are keywords and are checked before anything compiles: a matrix of the wrong shape or a value outside its range raises vipyr.ParameterError naming the parameter. The result is a frozen object whose fields are documented on the function's page, with units. Your own Viv works the same way: 

k = vp.load("kernels.viv")     # your own Viv file, compiled to C once and cached
k.sumsq(np.arange(4.0))          # each annotated def is a Python function on NumPy arrays

Getting started →

How results are checked

Each function's page says what it is checked against, under Checked against: a reference code (PySCF, BIGSTICK, SciPy, mpmath), a published value, or an identity the answer has to satisfy, with the tolerance and the reason for it.

  • check() on a result runs the program's own tests on that run.
  • The default build is designed to give the same bits on every machine: fused multiply-add is off and the math functions are Viv's own rather than the platform's. fast=True trades that for speed.
  • Every example on these pages ran when the pages were built, and the output shown is what it printed.

The Viv language

The programs are written in Viv, a small numerical language that compiles to C99 and to WebAssembly. You can use vipyr without reading any of it, and step through any of it when you want to see how a result was computed. The Viv language tour →