Every form, operator and builtin

The exhaustive companion to the tour. The builtin tables below are generated by running the compiler. A script compiles a probe program for each entry through all three backends and records what each one did. As of 2026-10-18 there are 267 builtins; 266 work in all three (the interpreter, the C backend and the wasm backend) and 1 in some of them.

Lexical structure

Numbers

A number is a 64-bit float. 10 lexes as 10.0, scientific notation works (1e-10), and a 64-bit integer is an Int, declared with an annotation (n: Int). % and // follow Python's rules for floats (see operators); mod(a, b) is C's fmod, whose result takes the sign of a.

No implicit multiplication

A name cannot follow a number directly: 2x is an error that says to write 2 * x. The i of an imaginary literal (2.5i) and the e of an exponent (1e-10) are part of the number.

Names

A name starts with a letter or _ and continues with letters, digits and _. Letters are Unicode letters, so Δx and σ are names. Names that start with viv__ are used by the parser for the hidden variables of a[i] += x and the longer for forms.

The dot rule

A . is part of a number only with digits on both sides. So 1.5 is a float, x.y is field access, and 1. is neither.

Statements end at the newline

No semicolons. Inside parentheses or brackets the lexer suppresses newlines, so long expressions wrap freely.

Comments

# to end of line, dropped by the lexer. The annotation markers — #| what, #|| how, #||| why, #~ tags, #: variable glossary, #[/#] regions — are comments the compiler ignores and viv doc extracts. Above a def they form its structured doc.

Strings

"text", with the escapes \n \t \r \0 \\ \" \' and \u{1F600} (any other backslash is an error), and f-strings, f"x = {x:.3f}". A string is a value: see Strings.

Docstrings

A bare string as the first statement of a def documents it and compiles to nothing.

Statements

Output with print and fmt

print writes its arguments on one line with a space between them, as Python's does, then a newline. sep=", " puts other text between them and sep="" none; sep is a string literal or a variable. There is no end=: every print ends its line. An argument is a string (written as is), fmt(x, ...) (a value in a format), or any other value (as show writes it: six significant digits, the way C's %g does). Every value is computed before anything is written. The interpreter, C and wasm print the same bytes, checked over 10⁶ doubles (tools/print-fmt-sweep/).

A format is [width][.precision] then e, f, g or d, or empty for repr; precision and width are at most 40 and 100. The rest of Python's spec (fill, alignment, +, ,, %, a precision with no type) is refused with its location and what to write instead. The digit count and the format are written in the source, not computed. nan prints as nan whatever its sign, and fmt keeps the sign of a negative zero (-0.0, -0) where a bare value writes 0. A program's own def fmt or def print replaces the builtin, and no separator is added to its calls.

Until 2026-09-30 print put nothing between its arguments, and programs wrote print(a, " ", b). tools/migrate_print_sep.py rewrote every program in the repository to the new form, checked call by call to reach the engines unchanged, so each prints the bytes it printed before.

Operator precedence

Measured: 2.0 + 3.0 * 4.0 is 14, -7 % 3 is 2 and 7 // -2 is -4. Parentheses override everything.

Comprehensions, if expressions and keys

A comprehension builds an array, or a list of strings, from loops, as Python's does. Its for takes any head a for statement takes, and its if keeps the elements it holds for:

xs = [3, 1, 4, 1, 5, 9]
evens = [x for x in xs if x % 2 == 0]           # [4]
squares = [i * i for i to 5]                    # [0, 1, 4, 9, 16]
table = [[i * j for j from 1 to 4] for i from 1 to 4]
words = [upper(w) for w in split("a bb ccc")]   # ['A', 'BB', 'CCC']
print(" ".join(f"{x:.2f}" for x in xs[:3]))     # 3.00 1.00 4.00
print(all(x > 0 for x in xs), max(words, key=len))
sign = "neg" if xs[-1] < 0 else "pos"
print(sorted(words, key=len, reverse=true))

A key is a def's name, a builtin's (len, abs), a variable holding a function, or a lambda fn(w) -> ..., which may read the program's variables. A comprehension's variables are its own: x outside it is neither read nor changed, as in Python 3. The parser writes each of these forms as the loop it stands for, computed just before the statement that uses it, so every engine runs code it already runs; what a statement computes before it (a call of a def, a print) still runs first, and in a while condition it is computed again each time. For that reason one cannot be the body of a fn(...) -> ... (except a key's): write a def.

Slices

A range inside the brackets selects a block of an array, and the result is a copy, never a view: b = a[1:3] is a new array, and writing b leaves a alone. (Assignment and parameter passing alias; slices do not.)

Bounds are read as an index is (a fraction is cut toward zero), and a negative index or bound counts from the end, as in Python: a[-1] is the last element, a[-3:] the last three, a[:-1] all but the last, A[-1, :] the last row. Nothing is clamped: after that a range needs 0 ≤ lo ≤ hi ≤ n, and anything else stops the run with its line in every engine, for example slice end 4 is past the end of dimension 0 (size 3), where NumPy would clamp. A step of 0 or less is an error, so a[::-1] is not a reversal of an array (it is of a string).

Four builtins go with slices. copy(a) is a new array with a's shape and elements. concat(a, b, ...) joins vectors end to end. vcat(A, B, ...) stacks rows and hcat(A, B, ...) puts matrices side by side; to vcat a vector is one row and to hcat it is one column, so hcat(u, v) is transpose(vcat(u, v)) and hcat(t) turns a vector into an n × 1 matrix. All of them work on complex arrays, and grad differentiates through slices, slice writes and all four.

The parser writes a slice as a call, a[lo:hi, j] as viv__slice_get(a, [1, lo, hi, 1, 0, j, 0, 1]), four numbers per index, so the interpreter, C and wasm share one set of rules (lang/viv/src/interp/slices.rs). Views that share storage would need their own rules for the arena and for aliasing, and are a separate design.

Growable arrays

[] is an empty vector, and a = append(a, x) is a with x on the end, so an output whose length is found while scanning needs neither a count pass nor a buffer sized by hand:

kept = []
for i to len(s) {
    if s[i] > 0.0 {
        kept = append(kept, s[i])
    }
}

An append gives back a new array, and it is written rebinding the name it grows, with the same name on both sides; b = append(a, x), an append inside an expression and one in a parallel for are refused before the program runs. An alias taken before the append keeps the array as it was: after b = a and a = append(a, 9.0), b has the old length, and a write into a does not reach it. Each engine grows the storage in place, doubling its room, when no other name, value or argument holds the array, and copies otherwise, so a loop of n appends costs O(n) and nothing a program prints depends on the room. grad differentiates through both. There is no pop: a = a[:-1] drops the last element (a copy). Adding a number to a matrix, a vector to a non-empty vector, or a row of the wrong length stops the run with its line, for example `append`: the row has 2 numbers, and the matrix has 3 columns.

Why rebinding, not push(a, x): an array handle is copied by value in C, so an in-place push would leave an alias with the old length, or pointing at freed memory after a reallocation.

Axes, broadcasting, and agreement with NumPy

The array builtins take NumPy's names and give NumPy's results: reshapes and transposes, eye, diag, arange, reductions along an axis, gathers and masks, cumsum, argsort, einsum, and solvers that return what they compute. Their tables are under Builtins; the rules they share are here.

X = reshape(arange(12), 3, 4)
Xc = X - mean(X, 0)                 # the column means, broadcast down the rows
C = transpose(Xc) @ Xc / 3.0
vals, vecs = eig_sym(C)
w = lin_solve(C + eye(4), ones(4))
top = argsort(vals)
picked = take(X, [2.0, 0.0], 0)     # X[[2, 0], :]
big = extract(X > 5.0, X)           # X[X > 5]

Broadcasting

+ - * /, the comparisons and two-array max and min between two arrays of different shapes (not complex ones) line up their last axes; each pair of lengths is equal, or one of them is 1 and repeats. So a row vector against a matrix repeats down its rows, reshape(v, n, 1) is a column that repeats across, and shapes that do not fit stop with the words they always did: array shape mismatch: [2, 3] vs [3, 2]. Complex arrays do not broadcast. grad sums a broadcast operand's gradient back to its shape.

Matrix products

A @ B is NumPy's matmul. Two matrices give their product; a vector on the left is a row and on the right a column, and the axis it adds is dropped. An array of rank 3 or 4 is a stack of matrices in its last two axes, and the axes before them broadcast, so X @ W with X of shape (4, 8, 16) and W (16, 8) multiplies each of the four matrices by W. Two vectors are refused (dot(u, v) is their product). Each entry adds its terms in order of the inner index from 0.0, skipping a term whose left factor is zero, with a separate multiply and add (no fused multiply-add); the loop is blocked for the cache without changing that order, so every engine gives the same bits (lang/viv/src/interp/matmul.rs). NumPy calls BLAS, which sums in its own order and agrees to rounding.

Axes

An axis is 0 to rank − 1, or −rank to −1 counted from the end, as in NumPy and as an index is. A reduction along an axis (axis=) drops it; with keepdims=true it keeps it with length 1, as NumPy's does, which is what lets A - mean(A, axis=1, keepdims=true) subtract each row's mean. A builtin's options are always given by name, with NumPy's names (axis=, keepdims=, k= for triu/tril/diag, offset= for trace, endpoint=, axes=); written by position they are refused. A reduction along the only axis of a vector would give a number, and is refused with the whole-array form to write instead (mean(v)).

Orders of summation

sum, mean, var and std, along an axis or of a whole array, and trace add in NumPy's order: from 0.0, a contiguous run in blocks of 8192 entries, each block by NumPy's pairwise sum; along an axis that is not the last, the slabs in order. They agree with NumPy to the bit (tools/py2viv/probe_numpy_order.py states the order), so mean(a) is sum(a) / numel(a) to the bit. The order binds the exact engines; fast mode may add in another. prod, cumsum and cumprod go left to right, as NumPy does. dot and norm go left to right; NumPy calls BLAS, which agrees to rounding. einsum loops over the output entries in row-major order and over the summed indices in their order of first appearance, adding each product to 0.0; NumPy's einsum has its own loops, so the two agree to rounding.

NaN and signed zeros

amax, amin, argmax and argmin are NumPy's: a NaN wins, and amax puts 0.0 above −0.0. (max(a) of one array is older and skips NaN, as C's fmax does.) argsort puts NaN last and keeps −0.0 and 0.0 in their order. clip keeps a NaN entry and treats a NaN bound as no bound.

Masks and indices

A mask is an array of 1.0 and 0.0, as a comparison gives, so an array cannot say whether it holds truth values or indices. NumPy's a[mask] is extract(mask, a), a[mask] = v is putmask(a, mask, v), a[idx] along an axis is take(a, idx, axis=k), and np.flatnonzero is flatnonzero. The indices take and put read are not negative: a[-1] counts from the end, take(a, [-1.0], 0) stops.

Solvers that return

x = lin_solve(A, b) (a matrix B solves for every column), inv(A), L = cholesky(A), vals, vecs = eig_sym(A), w, V = eig_herm(A) and U, s, Vt = svd(A) run the same code as the forms that fill arrays you pass, which still work, and give the same bits. The compiler writes an unpacking of eig_sym, eig_herm or svd as that call with arrays it allocates. svd is one-sided Jacobi (lib/svd.viv's algorithm); its vectors can have other signs than LAPACK's.

tools/arrays/numpy_cases.py writes 4,812 cases whose results NumPy computes in an order Viv follows, and 89 that agree with NumPy within a tolerance (einsum, the solvers, dot); cargo test --test arrays runs them in the interpreter, C and wasm, which print NumPy's results byte for byte.

Strings

A string is an immutable UTF-8 value. Length, indices and slices count code points, as Python's do (len("héllo") is 5), negative indices count from the end, and slice bounds are clamped (s[:80] of a short line is the line). Every function below is Python's, character for character: its whitespace, its Unicode tables (CPython 3.11's), its error messages. a.f(b) is f(a, b) for any call, so text code reads as it would in Python:

line = "O  0.000  0.757  -0.469"
parts = line.split()
z = float(parts[3])
label = f"{parts[0]}: z = {z:.3f}"
words = []
for w in "a b c".split() {
    words = append(words, w.upper())
}
print(join("-", words), label)

A list of strings ([Str]) comes from split, a literal ["a", "b"], or [] grown by a = append(a, s); it has len, indices, slices, +, in, sorted, unique, join and for. Strings and lists are never changed in place: s[0] = "x" and words[0] = "x" are refused, so no alias can see a change. A string can be a record field (sym: Str), a parameter, a result, one of several results, a figure title or a say caption. An index out of range, a text float cannot read and the other Python errors stop the run with CPython's words and the line.

Maps

map() is an empty map. Its keys are numbers or strings, and so are its values: one kind of key and one kind of value in each map, set by what the program stores. m[k] = v stores, m[k] reads, and the keys stay in the order they were first stored, so what a program prints never depends on how the keys hash:

counts = map()
for i to len(xs) {
    counts[xs[i]] = get(counts, xs[i], 0) + 1
}
ks = keys(counts)
for i to len(ks) {
    print(fmt(ks[i], "d"), fmt(counts[ks[i]], "d"))
}
words = map()
for w in split("the cat and the hat") {
    words[w] = get(words, w, 0) + 1
}
print(words)                   # {'the': 2, 'cat': 1, 'and': 1, 'hat': 1}

A map is one handle, changed in place: after b = m, a key stored through b is in m, and a def that stores into a map parameter stores into the caller's map, as a record field holding a map does. copy(m) is a second map. Keys compare with ==, so 0.0 and -0.0 are one key (the first stored is kept, as in Python); a NaN key stops the run (a map key cannot be NaN), and a lookup with a NaN finds nothing. A loop over a map is a loop over a snapshot of its keys, ks = keys(m), so the loop may change the map. Every operation is O(1) on average; 10⁶ stores and 10⁶ reads take about 0.07 s compiled to C, and with string keys about 0.3 s beyond making the strings. A string key hashes and compares by its UTF-8 bytes, so "é" and "e\u301" are two keys. A map owns a copy of each string stored in it, and a read gives a new string. A map that stores a number key and a string key (or both kinds of value), an array, a record or a map as a value, a map as an array element, a map inside grad or a parallel for, and two keys (m[i, j]) are refused before the run. The layout is CPython's compact dict.

Types

Num

f64, and the default: a literal is a Num. The other scalars are declared: Int (a 64-bit integer, n: Int), Float32 (IEEE binary32) and Cplx (below). A double holds every integer up to 2⁵³ exactly, so counters, indices and n == 1.0 are exact.

Bool

true or false: what a comparison yields and what if and while take. It can be stored, passed and returned (def f(x: Num) -> Bool), combined with and, or, not, and compared with == and !=. It is not a number: true + 1.0 and if count { are refused, identically, by the interpreter and the compiler. show prints it as true or false. Arrays hold numbers, so a mask is still an array of 1.0 and 0.0: a comparison with an array on either side makes one, and all(m) and any(m) turn one back into a Bool. See booleans.

Str

An immutable UTF-8 string, indexed by code point (Strings). A list of them is [Str].

Arr

Rank 1 to 4, row-major, f64 elements. Arrays pass into functions and return from them, and scalars broadcast against them from either side, and two arrays (not complex ones) broadcast as NumPy's do (Axes, broadcasting, NumPy). Assignment and parameter passing alias: b = a shares storage, and a function that writes into an array parameter writes into the caller's array. A real copy is copy(a), and a slice is a copy too — see scope & mutation. Indices count from 0, and an index outside its dimension stops the run in the interpreter and in C with the same message, index 2 out of bounds for dimension 0 (size 2), and the line it happened on. A negative index counts from the end, as in Python: a[-1] is the last element, and a[-3] of two elements stops the run. A fractional index is cut toward zero, so a[1.7] is a[1].

Map

Numbers under number keys, in the order the keys were first stored, made by map(). A handle: assignment, parameters and record fields share one map. A parameter may be annotated m: Map. See Maps.

Cplx

A first-class complex scalar: the i suffix on a numeric literal (2.0 + 3.0i), full arithmetic with real promotion, and complex overloads of abs/exp/log/sqrt/sin/cos/tan. Compiled to C99 double complex. Every engine computes these the same way, to the bit, with Viv's own formulas rather than C's operators or <complex.h>:

• A real operand is lifted to (x, 0.0) first, so 2.0 * z is the complex product with its zero terms.
• + and - work part by part.
• a * b is (ar br − ai bi) + i (ar bi + ai br), each product rounded on its own (no fused multiply-add).
• a / b is Smith's algorithm (1962): divide through by the larger part of b. If |br| ≥ |bi|, then with r = bi/br and d = br + bi r the quotient is ((ar + ai r)/d, (ai − ar r)/d); otherwise r = br/bi, d = bi + br r, and the quotient is ((ar r + ai)/d, (ai r − ar)/d). It never squares b, so it overflows only where the quotient does, not once |b| passes 1e154 as the textbook a conj(b) / |b|² does. A real divisor divides each part once, so (1 + 2i) / 3 is exactly 1/3 + (2/3)i. Dividing by zero gives nan + nan i.
• abs(z) is hypot(re, im). exp is e^re (cos im + i sin im). log is ln|z| + i atan2(im, re). sqrt is √|z| at half the argument. sin and cos use the cosh/sinh formulas, and tan is sin z / cos z by the division above. All of them use Viv's libm.

A complex array divided by a scalar divides each element the same way.

CArr

An array of complex numbers, rank 1 to 4: czeros(n), or a literal with a complex element in it ([1.0 + 2.0i, 3.0] — the reals promote). Indexing gives a Cplx; storing a real promotes it. It is packed: interleaved (re, im) doubles, which is exactly how C99 lays out double complex, so both engines walk the same memory and fft agrees between them to the byte. A complex and a real array are different types and do not mix silently — sin(a) on a complex array is an error. Annotate a parameter as CArr when you want to say so; otherwise it is inferred from the call site.

Records

User-defined structs with typed fields, copied by value: the C backend compiles them to C structs, the wasm backend to a block of memory, and the interpreter holds the fields. Array fields refer to the original array, so bundling a mesh into one value copies no array data. A def that takes or returns one annotates it (def f(p: P) -> P). Records have no operators and no show: compare and print their fields. The several results of return a, b are a record the compiler declares for the def, with one field per value and the field types inferred from the returns; the program never names it, because the caller unpacks it.

Function values

A def name or a lambda is a value. The compiled backends implement higher-order calls by monomorphization — run_it(sq, x) specializes to run_it__sq — with viv_fn function pointers for the cases where a function is held in a variable. Arrays of functions work in the interpreter and are a compile error in C.

A note on contracts

integrate and find_root are not builtins. They are contracts: functions named for the mathematical problem rather than the method, backed by several methods from different families of algorithms. By default they run every applicable method and check that the answers agree, and a disagreement stops the program with an error. viv run --release runs only the one method the contract selects (Gauss quadrature for integrate, a safeguarded secant for find_root).

The methods are ordinary Viv defs in lang/viv/std/contracts.viv, brought in with viv --use lang/viv/std/contracts.viv program.viv. The methods a contract chooses among are Viv code, not code in the compiler.

Interpreter only, today. A contract picks its method out of an array of functions, and the C backend implements higher-order calls by monomorphization — it specializes the callee per call site — which cannot express a callee chosen at runtime. So the contract library runs in the interpreter, and the C backend stops with a compile error naming the feature instead of producing wrong code.

Derivatives with deriv, grad and value_and_grad

deriv(fn(x) -> expr, x0) is forward mode: the derivative of one scalar expression at a point. grad and value_and_grad are reverse mode: the gradient of a whole def, loops, branches, calls and arrays included, with respect to its first argument, in one forward and one backward pass.

def loss(theta: Arr, X: Arr, y: Arr) {
    h = tanh(X @ theta)
    return sum((h - y) * (h - y)) / len(y)
}

g = grad(loss, theta, X, y)                  # the shape of theta
l, g = value_and_grad(loss, theta, X, y)     # the loss too

The first argument names a def; the others are passed to it unchanged and are constants for the derivative. The differentiated argument is a number or a real array, the gradient has its shape, and the def returns a number. value_and_grad gives two results, written a, b = value_and_grad(...) on its own line. A program that defines its own grad keeps it.

The compiler rewrites the program before any engine sees it (lang/viv/src/grad.rs), so the interpreter, C and wasm run the same generated code and print the same bytes. It adds one def per differentiated def: the def's statements, pushing every value an assignment overwrites onto a tape, then the adjoint statements in reverse order. A def called with a differentiated argument is inlined and differentiated with the caller; a call with constant arguments stays a call. Branches go back the way they came, and loops run backward over the recorded count. A def that returns several values (return a, b) or a record is inlined wherever it is called in differentiated code, and the record it builds becomes one variable per field, so y, dy = helper(w, x) inside a loss is differentiated like any other assignment; a record that only comes in (an argument, such as a model's configuration) is a constant.

Anything else is a compile error at its line, never a silent zero: a builtin without an adjoint (gamma, eig_sym, lin_solve, fft, sort, complex numbers, records) given a differentiated value; break and continue; return inside a loop; parallel for; recursion; a read of a variable before its first assignment on some path; b = a for an array that is written later through either name while both are in use (write b = a + 0.0); a write into a parameter or global array the def also reads; a call with a differentiated argument inside an if or while condition; and grad inside a def being differentiated. Clamp a value with two ifs to get torch.clamp's gradient, which passes at both ends of the interval.

The tape holds every value the forward pass overwrites, with no checkpointing. The six models in study/idioms that wrote their backward passes by hand each have a copy that uses value_and_grad, and the generated gradients match the hand-written ones to 1.1e-15 of the largest entry or better. lib/nn's RMSNorm, softmax and cross-entropy are whole-array expressions (reductions along the last axis with keepdims), and lib/gpt differentiates a whole batch of sequences in one value_and_grad. Derivatives through eig_sym and lin_solve, Hessians and checkpointing are not built yet.

Phrases

A phrase is an expression written the way a person says it. It starts with take followed by a word or a number, or with one of the verbs integrate, solve, differentiate, sum followed by a word or a number. The parser reads it as the call in the second column below, so the interpreter, C and wasm run only calls they already run, and a phrase prints what its call prints in all three.

c = 2.0
M = [[4.0, 1.0, 2.0], [1.5, 5.0, 3.0], [2.0, 3.5, 6.0]]
area = take the integral of x^2 from 1 to 2            # q_gauss(fn(x) -> x^2, 1, 2)
r = solve x^2 = c starting at 1 using newton           # r_newton(...), f' by forward-mode AD
s = solve x^2 = c between 0 and 2 using bisection      # r_bisect(fn(x) -> x^2 - c, 0, 2)
off = take the off-diagonal row sums of M              # sum(M - diag(diag(M)), 1)
x = solve M @ x = [1.0, 2.0, 3.0]                      # lin_solve(M, [1.0, 2.0, 3.0])

The rules:

• A phrase runs to the end of its line, or to a comma, a closing bracket, {, :, if or else outside brackets. So take the norm of u / n is the norm of u / n; write (take the norm of u) / n for the other reading.
• The parser tries every pattern and every way to split the words among its holes, and keeps the splits whose holes parse as whole expressions. One reading is the phrase. None is an error that names the closest patterns; two or more is an error that lists them. It does not choose between readings.
• In an integral, a root or a derivative, the expression is a function of its one free variable: the one name in it that the program does not assign at that point. With none or several, the phrase is refused until you name it: ... with respect to t or ... for t. An equation l = r is solved as l - r = 0.
• A part the call reads more than once (the median reads its argument four times) is computed once, into a hidden variable.
• take, the verbs and every builtin keep working as names: a phrase needs a word or a number right after its first word, which no other expression has.
• A phrase has the content address of its call, so rewording one (mean for average) does not make a def's intent stale. viv phrases file.viv prints each phrase of a program with the call it is.
• The quadratures and root finders are the defs of lang/viv/std/contracts.viv and lang/viv/std/phrases.viv. A program that uses one of them gets the def added; one that defines its own def of that name and uses the phrase is refused.

A program can declare its own phrase at the top level. A word of the phrase that is a name the body reads is a hole; the other words are the ones a use must contain:

phrase "the Rayleigh quotient of A at x" -> dot(x, A @ x) / dot(x, x)
q = take the Rayleigh quotient of M at e

The table has 142 patterns, 49 of them ported from Knot. Each example below is a test in lang/viv/tests/phrases/phrases.viv that checks the phrase against the value NumPy or a closed form gives; 148 of 148 passed in the browser compiler when this page was built, and the same file passes in the interpreter, as C and as wasm.

Aggregates

Matrices

Vectors

Sizes and elements

Elementary functions

Geometry and linear algebra

Construction

Probability and learning

Integrals, roots and derivatives

Builtins

Columns: I the interpreter, C the C99 backend, W the direct wasm backend. Each mark is a probe program that compiled (and, for I, ran) when this page was built.

A builtin's name is not reserved. A program that writes its own def band(lo, hi), def where(...) or def sin(a, b, c) calls its def everywhere it writes that name, in every engine, with the def's own arguments; the builtin is out of reach in that program. So a new builtin never changes what an existing program computes.

Real math

Every one-argument function here also maps elementwise over an array, so y = sin(x) needs no loop.

Bits

These take a number (a double), truncate it toward zero, wrap it into [0, 2^32) and hand back the result as an unsigned 32-bit value, so they compose without a cast. A shift of 32 or more gives 0, except that sar of a negative value gives all 32 bits set (4294967295, which i32 reads as -1). These are the operations a logic gate, an adder or a RISC-V instruction needs.

Ints

Int is a 64-bit integer. Overflow, // and % are checked and stop the run with the same words in every engine; these builtins are the unchecked forms an algorithm on 64-bit patterns needs (a random generator, a hash), with the pattern read as unsigned where the name says so.

Binary data

A file's bytes are an [Int], one element per byte, 0 to 255. The readers take that array and an offset and decode the bytes there, little-endian, as Python's struct with < does; an offset past the end, or an element that is not a byte, stops the run. In the browser read_bytes reads the files the page attaches to the run.

Arrays

Shapes and constructors

NumPy's names and results (interp/arrays.rs; each case checked against NumPy in tools/arrays/numpy_cases.py). Every result is a new array. An axis may be negative, as in NumPy: -1 is the last.

Reductions, products and broadcasting

Arithmetic and comparisons between two arrays (not complex ones) broadcast as NumPy's do: the last axes line up, and each pair of lengths is equal or one of them is 1, so A - mean(A, axis=0) subtracts the column means and A * transpose([w]) scales rows. sum, mean, var, std along an axis and trace add in NumPy's order (pairwise, in blocks of 8192), so they agree with NumPy to the bit; so does sum(a) of a whole array. keepdims=true keeps the reduced axis with length 1 (NumPy's keepdims).

Gathers, masks, sorting and scans

A mask is an array of 1.0 and 0.0, as a comparison gives, so an array cannot say whether it is a mask or a list of indices: selecting by a mask is extract, and by indices take.

Strings

Python's semantics, by code point; a.f(b) is f(a, b). See Strings above.

Databases (SQLite)

SQLite (third_party/sqlite, public domain) is built into viv and compiled beside a C program that uses these (viv export --with-sqlite); the browser does not have them yet. A database is a number, its handle. Parameters are ? in the SQL, bound from a list of strings (as text) or an array of numbers (NaN as NULL), never pasted into it. db_exec runs inside a savepoint: SQL that fails changes nothing. A query is one statement giving one column. NULL reads as NaN in db_col and is an error in db_col_int and db_col_str (select COALESCE(x, k)). SQLite's errors are VivError; a misuse (a bad handle, a wrong count of parameters, a NULL in an Int column) is ValueError.

Maps

A map holds numbers or strings under number keys or string keys (one kind of each per map), in the order the keys were first stored. It is one handle: b = m, a def's parameter and a record field all change the same map. See Maps above.

Group-by on Int keys

Written in Viv (lang/viv/std/groupby.viv) and added to a program that calls them, so every engine runs the same code. The keys stay Ints (no float conversion), hashed into an open-addressing table whose slot holds the key beside its group id. A group-by is factorize, then a dense loop: s[ids[i]] += v[i].

Linear algebra

In debug mode each solve checks its own result (a residual, a pivot check or a trace invariant) and stops with an error instead of returning a wrong answer.

Higher-order and contracts

A contract is named for what it computes, not for the method. In debug mode it runs every method that applies and asserts they agree; viv run --release runs the auto-selected one. The methods are ordinary Viv code, in lang/viv/std/contracts.viv.

Derivatives and records

grad and value_and_grad are reverse mode over a whole def (lang/viv/src/grad.rs): the compiler writes the gradient def before any engine runs, so the three engines run the same generated code.

Complex scalars

The i suffix works only on a number, so a loop variable named i is still a variable. For arrays of them, see the next group.

Complex arrays and the Fourier transform

A complex array is packed — interleaved (re, im) doubles, which is exactly how C99 lays out double complex, so both engines walk the same memory and agree to the byte. fft is radix-2 at a power of two, mixed radix (with dedicated radix-3 and radix-5 butterflies) when the primes of the length are all ≤ 7, and Bluestein everywhere else, so no length is a special case and 2·3·5-smooth ones are fast. The twiddle factors and factorization for each length are computed once and reused. Whole-array arithmetic works on complex arrays: a + b, a * b, a real array or a real or complex scalar on either side of *, / by a scalar, and @. Convention: fft is unscaled with exp(−2πikn/N); ifft carries the 1/N — the same as numpy and FFTW.

Randomness

Park–Miller MINSTD in pure f64, so the stream is bit-identical between the interpreter and compiled C — a seeded Monte Carlo gives the same answer either way. #! use lib/random adds randn, randn_matrix, randint, shuffle, randperm, choice, arange and pi, written in Viv over rand(), each documented as the formula it computes so Python can replay it (tools/random_replay.py); #! use lib/stats adds mean and std.

Figures and geometry

Each of these prints a structured record on stdout, and the page draws the chart from it. Compiled C prints the same record, so a figure is part of the program's output, not a call into a plotting library.

Animation

An animation is a Viv program. Objects are created hidden and named by a string id; transitions reveal, morph and move them. Each call prints one record, and the page plays the records with a scrubber.

Output and testing

A failed assert prints what failed (for assert_near, the two values, their difference and the tolerance), keeps running, and makes the process exit nonzero at the end, so a build can stop on it while you still see every failure in one run.

What a test prints

A test block is the unit that passes or fails, so it prints exactly one line under the name you gave it — not one line per assertion:

test "simpson integrates exp correctly" {
    assert_near(simpson(fn(x) -> exp(x), 0.0, 1.0, 60), exp(1.0) - 1.0, 1.0e-9)
}

$ viv run integrate.viv
PASS simpson integrates exp correctly

Several asserts in one block still give one line. A failure names the test and carries the first failing assertion's detail, and a block with no assertions says so instead of printing PASS:

PASS two asserts, one verdict
FAIL a failing one -- assert_near: |1 - 2| = 1 > 1e-09
PASS nothing asserted (no assertions)
assert_near PASS
1 assertion FAILED

That last assert_near PASS is an assertion at top level, outside any test — there is no name to report under, so it prints its own line as before. The trailing count is the summary, and it is what makes the process exit nonzero, so a build script can fail on the exit code. It goes to stderr, after everything the program printed, in the interpreter and in a compiled program alike, so stdout holds only the program's own output.

The backend matrix

The interpreter and the two compilers share one parser. Which features each one runs:

Every feature goes into both the interpreter and the C backend, and the example suite checks that it does. The direct wasm backend reaches wasm without C (a sum-of-squares program is a 348-byte module) and is checked beside them as a third engine (tools/three-engines.sh).

The CLI

An error at run time reads like one at compile time: the message, the file, line and column, the line itself, and a caret under the part that failed. A compiled program prints the same lines, byte for byte, because the compiler writes each indexing site's location into the C.

$ viv run last.viv
2
error: index -3 out of bounds for dimension 0 (size 2)
  --> last.viv:3:6
   3 | show a[-3]
            ^^^^^ here

The notes answer habits from Python, ** (write x ^ y) and for i in range(n) (write for i to n), and one from Julia, 2x (write 2 * x).

Every one of these commands also runs in the browser, on this site, at /cli — the wasm module exports the same library functions main.rs wraps.

The feature catalog

viv features lists what Viv has: 182 features written up in 9 areas, and 592 entries generated from the compiler's own tables (builtins263, phrases9, cli verbs40, lens kinds11, keywords55, modules214). Each written-up entry has a minimal example, and cargo test --test features runs every example in the interpreter, as C and as wasm and checks the output it records. The tables below are that catalog; viv features <name> prints one entry with its example and output, and viv features --search <words> finds entries by words. Agents writing Viv consult it before writing code, and run viv features --usage on what they wrote: it lists loops, sorts, roundings and copies written out where a feature does the work.

Syntax

Types

Arrays

Autodiff

Correctness

Program knowledge (lenses)

Tools

Performance

Libraries

The C runtime

Compiled programs carry their runtime with them. One struct,

typedef struct { int rank; int dims[8]; int size; double* data; } viv_arr;

plus a set of small viv_* functions — array ops, the eigensolvers, the LU and Cholesky factorizations, quadrature, the Park–Miller generator, and the show/plot/narrate printers — emitted only on demand. A program that never touches an array gets none of them; the nine-line example on the internals page pulls in exactly one. Building it takes only cc program.c -O2 -lm.

Every array read and write in the C is checked: the number of indices against the array's rank, then each index against its dimension. A wrong count or an index out of bounds stops a compiled program with the interpreter's error and location instead of reading memory the array does not own. The checks are on by default. Build with -DVIV_RELEASE to drop them along with the other debug-build checks, or with -DVIV_NO_BOUNDS to drop only them. What they cost, measured with tools/bounds-cost.sh (CPU time, best of 7 runs, cc -O2, Apple M2 Pro):

That is 27% to 84% on these programs, so a build you time for speed should pass -DVIV_RELEASE; a build you run to check a program should keep them. The WebAssembly modules this site serves (dft/wasm/, engines/wasm/) are built with -DVIV_RELEASE; the same programs run with the checks on in dft/check.sh and in the interpreter and in C. In those modules an index out of range is not caught: a write can land in another array of the same program (it cannot leave the module's memory). The interpreter and the module the compiler in your browser makes when you press Run (the direct wasm backend) check every index and stop with the same error as the C. -DVIV_RELEASE also trusts the disjoint pins of a memory lens instead of testing them; a checked build records which pass of a pinned parallel for writes each element and stops if two passes write the same one.

The location in a run-time error names the program as you gave it when the path is relative (lib/hf/scf.viv:12:5) and by its file name when the path is absolute (scf.viv:12:5), in the interpreter and in C. The C carries those locations, so a program compiled by absolute path gives the same C on every machine and in every checkout.

The builtin tables were probed at build time (2026-10-18).