Language tour

Hello Viv!

Every example below runs in your browser through the same wasm compiler the workbench uses. Running a cell runs it together with every cell above it, starting fresh each time. An edit to one cell changes the results of every cell below it, and nothing is left over from an earlier run.

Numbers

A number is a 64-bit float: 10 means 10.0, and division never truncates. For counters and indices there is Int, a 64-bit integer declared with n: Int. print gives the bare value; show labels a variable with its name and prints any other expression bare:

# A number in Viv is a 64-bit float unless it is declared an Int:
# 10 lexes as 10.0.
n = 10
show n
show n / 4.0

# print gives the bare value; show labels a variable with its name
# (n: 10 above) and prints any other expression bare:
print(sqrt(2.0))
show pow(2.0, 10.0)

# the math builtins: exp log sin cos tan sqrt pow abs floor ceil min max
show min(floor(2.7), ceil(1.2))

Control flow

Three forms: if/else, while, and the counted loop for i to n, which runs i from 0 to n−1. break and continue work as in C. Statements end at the newline (no semicolons), and a line continues automatically inside parentheses or brackets:

# if / else, while, and `for i to n` — i runs 0 .. n-1.
total1 = 0.0
for i to 10 {
    total1 = total1 + i
}
show total1

# while, growing to the first power of two past 1000:
p2 = 1.0
while p2 < 1000.0 {
    p2 = p2 * 2.0
}
show p2

# break works the way you expect:
q = 0.0
while 1.0 < 2.0 {
    q = q + 3.0
    if q > 10.0 { break }
}
show q

Functions

def defines a function, return returns, and a function can call itself. A bare string as the first statement is a docstring. Parameter and return types (Num, Arr) are optional annotations, checked when the program compiles.

A 64-bit float (a double) holds every integer up to 2⁵³ exactly, so counting down from 10.0 by 1.0 lands on 1.0, not near it: n <= 1.0 is an exact test. fact(20.0) is exact as well: 20! is past 2⁵³, but it has eighteen factors of 2, so what is left fits in a double's 53 bits. What a double cannot hold is a fraction like 0.1. That is where == fails and a tolerance belongs: 0.1 + 0.2 misses 0.3 by 5.6 × 10⁻¹⁷, and assert_near is how a Viv program says “equal, to within rounding.”

After you run this cell, look under its output. The interpreter records every user-function call, so each cell carries a collapsible call graph — open here so you can see it. fact calling itself is the self-loop with its count, and replay animates the recorded call sequence. In later cells the graph stays folded behind the "call graph" line until you want it:

def fact(n) {
    "n! by recursion. Every number is a double, and a double holds integers exactly."
    if n <= 1.0 {
        return 1.0
    }
    return n * fact(n - 1.0)
}
show fact(10.0)
# exact to the last unit, not merely close:
show fact(20.0) - 2432902008176640000.0

# What a double cannot hold exactly is a fraction like 0.1. THAT is where
# equality fails, and where a tolerance belongs:
s = 0.1 + 0.2
show s - 0.3
assert_near(s, 0.3, 1.0e-12)

# type annotations are optional and checked at lowering:
def hyp(a: Num, b: Num) -> Num {
    return sqrt(a * a + b * b)
}
show hyp(3.0, 4.0)

Arrays

Arrays hold floats. Literals nest into matrices, indexing takes comma-separated subscripts (M[i, j], up to rank 4), zeros allocates, len reads the leading dimension. Arithmetic is elementwise — * between arrays is the Hadamard product, and an array times a scalar scales. A show on a matrix indents its rows under the first one, so it reads as a matrix rather than as a label with a ragged list beneath it:

# Array literals, elementwise arithmetic, and indexing.
v = [3.0, 4.0]
w = [10.0, 20.0]
show v + w
show v * w
show v * 2.0
show len(v)

# matrices are arrays of rank 2; zeros() allocates up to rank 4:
M = [[2.0, 0.0], [0.0, 5.0]]
show M[1, 1]
Z = zeros(2, 2)
Z[0, 1] = 7.0
show Z

Plots

A figure is declared in the program. figure(title, xlabel, ylabel) says what the chart is, and plot(x, y, "label") adds a series to it. Both are emitted as structured records; whatever runs the program (this page, the workbench, a terminal) draws them, and the C backend prints the same records as text. Nothing outside the program adds to a figure: the title and axis labels you see below are the three strings in the cell, and a program that calls plot without declaring its figure first does not compile. Consecutive plot calls sharing the same x land in one chart as separate labeled series:

# A figure is declared IN the program: figure(title, xlabel, ylabel), then
# plot(x, y, "label"). The interpreter emits both as records and whatever is
# hosting the program draws them -- adding nothing of its own.
n_t = 61
wave_x = linspace(0.0, 6.0, n_t)
wave = zeros(n_t)
for i to n_t {
    wave[i] = exp(-0.5 * wave_x[i]) * cos(3.0 * wave_x[i])
}
figure("A damped cosine", "t", "exp(-t/2) cos(3t)")
plot(wave_x, wave, "decay x oscillation")

Linear algebra

@ is always the matrix product, never elementwise. Alongside it are transpose and eig_sym, a Jacobi eigensolver for symmetric matrices that fills a values vector (ascending) and a vectors matrix (eigenvectors in columns). The cell checks that the trace equals the sum of the eigenvalues:

A = [[2.0, 1.0], [1.0, 3.0]]
show A @ transpose(A)

# eig_sym: Jacobi eigendecomposition of a symmetric matrix, ascending:
vals = zeros(2)
vecs = zeros(2, 2)
eig_sym(A, vals, vecs)
show vals

# the trace equals the sum of the eigenvalues — 2 + 3 = 5:
show vals[0] + vals[1]

Lambdas, quadrature and exact derivatives

fn(x) -> expr is a value: assign it, pass it. The higher-order builtins take one — simpson and trapezoid integrate, and deriv differentiates exactly, by forward-mode autodiff at compile time rather than by finite differences. Its vocabulary is arithmetic plus exp/sqrt/pow/sin/cos/log/tan; ask it to differentiate through a def you wrote and it stops with an error that says so:

# fn(x) -> expr is a value; call it like anything else:
square_fn = fn(x) -> x * x
show square_fn(7.0)

# quadrature takes a lambda — integral of x^2 over [0,1], exact 1/3:
show simpson(fn(x) -> x * x, 0.0, 1.0, 40)

# deriv is exact forward-mode autodiff, not finite differences.
# d/dx [x sin(x)] at 2, against the product rule sin(2) + 2 cos(2):
show deriv(fn(x) -> x * sin(x), 2.0)
show sin(2.0) + 2.0 * cos(2.0)

Tests

A test block names a claim and asserts it with assert_near — and what it prints is the name you wrote: one line per test, however many assertions are inside. A failure names the test and carries the failing assertion's detail, and makes the whole run exit nonzero, so a build script can fail on it:

# A test block runs its body and prints PASS/FAIL — programs grade themselves.
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)
}

Progress lines

narrate "text" prints a progress line, kept separate from data output. A program can print "building hamiltonian" or "calculating ERIs" as it reaches each step. Every backend prints it: the interpreter styles the lines, and compiled C prints the same narrate: text.

Two other kinds of text print nothing. Comments (#) are dropped by the lexer, and annotation markers (#| what, #|| how, #||| why) are comments the compiler ignores but viv doc extracts for code browsers:

# narrate is the program narrating its own progress — a live channel,
# separate from data output, in every backend:
narrate "setting up"
answer = 6.0 * 7.0
narrate "answer computed"

#| Annotation markers stay ordinary comments to the compiler;
#| `viv doc` extracts them for code browsers.
show answer

Parallel loops

parallel for declares a loop parallelizable. The interpreter runs it sequentially; the C backend emits an OpenMP pragma, so the compiled program spreads it across cores. On a 12-core laptop the Hartree–Fock calculation on a chain of 20 hydrogen atoms (hchain_sto3g.viv) goes from 2.67 s on one thread to 0.35 s on twelve:

# `parallel for` runs sequentially here in the interpreter;
# the C backend emits an OpenMP pragma for it.
psum = 0.0
parallel for i to 1000 {
    psum = psum + i
}
show psum

Records

A record is a named bundle of numbers, arrays and other records. It is built with every field named, read with a dot, and passed to and returned from a def like any value. Copying a record copies its numbers, while an array field still refers to the original array, so bundling a mesh into one value copies no array data. The fields themselves are fixed once the record is built: to change one, build a new record. A def that returns several values, return a, b, hands back a record the compiler makes for it, and the caller unpacks it with lo, hi = extent(v).

# A record bundles named numbers and arrays into one value.
record Point { x: Num, y: Num }
record Polyline { xs: Arr, ys: Arr }

def norm2(p: Point) -> Num {
    return sqrt(p.x * p.x + p.y * p.y)
}

pt = Point { x: 3.0, y: 4.0 }
show norm2(pt)

# Copying a record copies its numbers; an array field is the same array.
line = Polyline { xs: zeros(3), ys: zeros(3) }
line2 = line
line2.xs[1] = 5.0
show line.xs

# A def can return several values; the caller unpacks them.
def extent(v: Arr) {
    return min(v), max(v)
}
lo, hi = extent(line.xs)
show hi - lo

One Gaussian for the hydrogen atom

A def with a docstring, deriv and a test, used together for the first step of a Hartree–Fock calculation: the best single-Gaussian approximation to the hydrogen atom. The energy comes out −0.4244 hartree, and deriv returns zero at the analytic optimum, which confirms it is a stationary point of the energy:

# Everything above, in one physics one-liner: the single-Gaussian
# hydrogen-atom energy from the SCF notebook, E(a) = 3a/2 - 2 sqrt(2a/pi).
pi_c = 3.141592653589793
best_a = 8.0 / (9.0 * pi_c)

def E_h(alpha) {
    "single-Gaussian variational energy for the hydrogen atom"
    return 1.5 * alpha - 2.0 * sqrt(2.0 * alpha / pi_c)
}
show E_h(best_a)

# at a true minimum the derivative vanishes — deriv checks it exactly:
show deriv(fn(a) -> 1.5 * a - 2.0 * sqrt(2.0 * a / pi_c), best_a)

test "the analytic optimum -4/(3 pi)" {
    assert_near(E_h(best_a), 0.0 - 4.0 / (3.0 * pi_c), 1.0e-12)
}

Or open the workbench and write something of your own — the full Hartree–Fock, the neutron star and the FEM solver are all in its examples menu.