Viv

Viv is a small language for numerical programs. It compiles to C99 and to WebAssembly.

The program below finds √2 by Newton's method. deriv gives the exact derivative, and the test block checks the answer every time the program runs. Edit it and press Run; the compiler runs in your browser.

Viv [1]

# Newton's method for the square root of 2.
# deriv() is exact: the compiler differentiates the expression.
x = 1.0
for i to 6 {
    x = x - (x * x - 2.0) / deriv(fn(t) -> t * t - 2.0, x)
}
show fmt(x, ".16g")
residual = x * x - 2.0
show residual

test "x squared is 2, within one unit in the last place of 2" {
    assert_near(x * x, 2.0, 4.5e-16)
}

Learn Viv Workbench Explore a run

Numerical programs written in Viv, run from Python and checked against reference codes.

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

import vipyr as vp
# water in STO-3G; atoms= (atomic numbers) and coords=
# (angstrom) for another molecule
r = vp.scf.run(basis="sto-3g", method="rhf")
print(r.e_tot, r.converged, r.mo_energy[:3])
assert r.check()

Checked against PySCF 2.5.0 Full example →

import numpy as np
import vipyr as vp

# mtcars$mpg and mtcars$vs, from R's datasets package
mpg = np.array([21.0, 21.0, 22.8, 21.4, 18.7, 18.1, 14.3, 24.4,
                22.8, 19.2, 17.8, 16.4, 17.3, 15.2, 10.4, 10.4,
                14.7, 32.4, 30.4, 33.9, 21.5, 15.5, 15.2, 13.3,
                19.2, 27.3, 26.0, 30.4, 15.8, 19.7, 15.0, 21.4])
vs = np.array([0, 0, 1, 1, 0, 1, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0,
               0, 1, 1, 1, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 1],
              dtype=float)
X = np.column_stack([np.ones(32), mpg])
g = vp.stats.glm(vs, X, family="binomial", link="probit",
                 names=["(Intercept)", "mpg"])
print(g.summary())

Checked against R 4.3.3's glm Full example →

import numpy as np
import vipyr as vp

# Robertson's stiff kinetics: rates 0.04, 1e4 and 3e7,
# from t = 0 to 1e11
t_out = np.concatenate([[0.0], np.logspace(-5, 11, 161)])
# the Bari IVP test set's answer at t = 1e11
ref = np.array([0.2083340149701255e-07, 0.8333360770334713e-13,
                0.9999999791665050])
for method in ("radau", "bdf"):
    r = vp.ode.solve("robertson", (0.0, 1e11), [1.0, 0.0, 0.0],
                     method=method, rtol=1e-8, atol=1e-20,
                     params=[0.04, 1e4, 3e7], t_eval=t_out)
    err = np.abs(r.y[:, -1] - ref) / ref
    print("%-6s y(1e11) = %s   largest relative error %.1e"
          "   max |sum - 1| = %.1e"
          % (method, np.array2string(r.y[:, -1], precision=10),
             err.max(), np.abs(r.y.sum(axis=0) - 1).max()))

Checked against the Bari IVP test set and SciPy Full example →

import vipyr as vp
r = vp.power.runpf("case118")  # Newton-Raphson
print(r.success, r.iterations, r.vm.min(), r.va.max())
d = vp.power.runpf("case118", method="dc")  # the linear model
print(abs(d.va - r.va).max())  # degrees between the two
assert r.check()

Checked against a SciPy power flow Full example →

Start with vipyr Gallery

A programming language project that got out of hand

I started off wondering whether agents could develop a programming language that would be useful for deploying anywhere. I wanted instant calculations, so I chose WebAssembly. I wanted portability and performance, so C. And I wanted quicker debugging, so an interpreter.

Then I noticed I wasn't writing any of the language; an agent was. So the aim became making code understandable. That led to the code atlas, a mix of callgraph, debugger and documentation that turns tangled programs into something like slideshows you can explore. There's a lot of code out there I don't understand, including plenty on this site, and I hope Viv helps you untangle some of it.

N-version programming turned out to be a big part of the language, so I designed contracts: multiple paths to the same answer. The idea is that you can look at an atlas, pick a part, swap it for another method and see what happens; that demo is next.

As a test of the language, I had it port a set of scientific codes and check them against references, which gave me an atlas of a complicated program. I'd guess many of those programs have errors that closer inspection will find, the classic problem with AI-generated output, so they need review.

Most programming language projects fail, so I hedged right away: the whole language is usable from a Python package. My language has a user base of one, and maybe a Python layer will get a few more people to try it.

The project is also a home for scientific calculations I've always wanted to understand and to teach. I hope Viv helps both of us understand them, and that this site helps people adopt some of the ideas I've had along the way.

The whole project will come with Model Context Protocol and agent tooling, so you can take it for a spin.

Connect Viv to your agent

Next, in 0.0.2

Some kind of GPU support, and bootstrapping the compiler. It's written in Rust and needs untangling itself, which will probably take a lot of tokens.

Solving for the ground state of oxygen-16

Neutrons and protons settle into shells in the mean field they make together.

Checked against a published Skyrme Hartree-Fock code

The whole walk →

Run records the program in your browser, then the walk follows the recording call by call.

Water's electron density settles

Each frame is one Roothaan step from the core guess, and the contours are the density in the plane of the molecule.

Checked against PySCF, to 1e-9 hartree

Hartree-Fock for water →

The Ising model at its critical temperature

Spins flip by the Metropolis rule at T_c, where patches of every size form and dissolve.

Its page checks the sampled magnetization at T = 1.8, below T_c, against Onsager and Yang's exact value, and the run at every temperature against a reference Metropolis code

The Ising model →

Two solitons pass through each other

The taller, faster soliton overtakes the shorter one, and both come out with their shapes intact, shifted from where they would have been.

Checked against Hirota's exact two-soliton solution

The KdV equation →

The band structure of silicon

Plane-wave density functional theory in the local density approximation, along the path from L through Γ to X.

Checked against a NumPy plane-wave code

Density functional theory →

Landau damping of a Langmuir wave

Electrons moving near the wave's phase speed take its energy, and the field decays at the rate of the dispersion relation's root.

Checked against a 30-digit mpmath root

Landau damping →

A pole balanced on a moving cart

Released 25 degrees from upright, the pole is caught by gains from the Riccati equation.

Checked against SciPy's solve_continuous_are

The cart-pole →

Robertson's stiff chemical kinetics

Three species react at rates nine orders of magnitude apart, followed from 10⁻⁵ to 10¹¹ seconds.

Checked against the Bari test set

Robertson's kinetics →

Data

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

Customer features from a transaction log

Statistics

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

Special functions against mpmath, SciPy and R

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.

A small GPT trained on one paragraph

Finance

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

Implied volatility, binomial trees and Greeks of European options

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.

Water Hartree-Fock energies compared with PySCF

Math

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

Robertson's stiff kinetics over sixteen decades

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.

Balancing a cart-pole with LQR

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

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.

Voltage profile of the IEEE 118-bus system

Embed Viv in any web page

One script tag puts runnable, editable Viv on a web page. The compiler runs in the reader's browser, so there is no server to set up.

<script src="https://viv-lang.org/embed/viv-embed.js" defer></script>

<viv-cell>
n = 61
t = linspace(0.0, 6.0, n)
y = exp(-0.5 * t) * cos(3.0 * t)
figure("A damped cosine", "t", "y")
plot(t, y, "y")
</viv-cell>

The cell shown here is that markup, turned into a cell by the embed script as it would be on your own page. Press Run, or edit it first.

How the embed works →

n = 61 t = linspace(0.0, 6.0, n) y = exp(-0.5 * t) * cos(3.0 * t) figure("A damped cosine", "t", "y") plot(t, y, "y")

One program, three engines

An interpreter, a C99 backend and a wasm emitter run the same program and print the same digits. Edit it and all three update as you type.

your programprogram.viv

def sq(x) {
    return x * x
}

total = 0.0
for i to 10 {
    total = total + sq(i)
}
show total

the C99 it emitsafter a 3,615-line runtime

double i;
double total;

double sq(double x) {
    return (x * x);
}

int main(void) {
    total = 0.0;
    for (long long viv_k_i = 0; viv_k_i < 10LL; viv_k_i = (viv_k_i + 1)) {
        i = (double)(viv_k_i);
        VIV_POLL();
        total = (total + sq(i));
    }
    viv_show_num("total", total);
    return 0;
}

and as wasmcompiled directly, without C

351bytes of WebAssembly

the interpreter printstotal: 285

the wasm module printstotal: 285

all three, in your browsertimed on your first edit