REPL & Diagnostics

The tables below are generated by reading the interpreter's own builtin dispatch table (fn call_builtin, engine/crates/qu-interp/src/lib.rs) directly — every row reflects a match arm that actually runs today, not aspirational API surface.

Output & Diagnostics

Overloads: write

Which form runs is decided entirely by the type of the first argument, not by argument count — passing a fileHandle as the sole argument, or a string as the first of several ordinary values, stays on the console-printing path.

write("a", 1, "b")
print("")
f = fopen("scratch_write_demo.txt", "w")
write(f, "hello file")
close(f)
g = fopen("scratch_write_demo.txt", "r")
print(read_all(g))
close(g)

a 1 b
hello file

a 1 b
hello file

Timers

MATLAB-style tic/toc for quick wall-clock timing, plus a timer/ preciseTimer object for cases where a single global slot isn't enough (nested or concurrent timing regions).

Qu actually has four distinct profiling/timing mechanisms, and picking the wrong one is an easy mistake, so here they are side by side: tic/toc is the single global lap timer — simplest, for timing one region at a time. timer()/preciseTimer() is a standalone object for nested, concurrent, or pausable timing, one per variable instead of one shared global. profile_start/profile_end (below) measures a single named region's wall-clock time *and* memory (RSS delta), returning a plain value rather than mutating shared state, so multiple regions can overlap or nest freely. profiling_mode/profile_stats is a different shape entirely — it attributes call count and cumulative time *per builtin function* across a whole recording window, with no memory tracking; reach for it to find which builtin is slow, not to time one block of your own code. See also profiling_mode/profile_stats further below in this chapter for that fourth mechanism.

timer.start() / timer.elapsed() / timer.stop() — Stopwatch-style sugar for tic/toc

Part of the same small, closed table./timer. "namespace-dot" alias set as table.load/table.write (§ ergonomic API layer, 2026-08-31): the parser recognizes exactly timer.start(/timer.elapsed(/timer.stop( and rewrites each, at parse time, straight to tic()/toc()/toc() — so evaluation is byte-identical to calling those directly. timer is not a namespace value; it still works as an ordinary variable (timer = 5), and this is completely unrelated to the real timer([interval]) object constructor above (a bare timer.start() never constructs one).

timer.start()               # same as tic()

heavy_computation()
mid = timer.elapsed()       # peek — does NOT reset, callable again

more_work()
total = timer.stop()        # same as toc() — also a non-resetting read

A small reverse-mode autodiff tape. param/track are the same underlying operation; param is the spec's name for trainable weights and track is for "differentiate through this too" on an ordinary intermediate value — the distinction is documentation, not mechanism, until optimizers exist to read it.

Overloads: grad

x = track(3.0)
y = track(2.0)
loss = x * x + y * y
dloss_dx = grad(loss, wrt=x)          # 2*x = 6

grads = grad(loss, x, y)              # [2*x, 2*y] = (6, 4)

print("wrt=x form: {dloss_dx}")
print("positional form: {grads}")

wrt=x form: 6
positional form: (6, 4)

wrt=x form: 6
positional form: (6, 4)

RNG Control

The base random-number-generator controls. The named distributions built on top of these (rand/randn shape helpers, and the wider distribution library) are documented in the Statistics & ML chapter — not duplicated here.

Overloads: rand / randn

a = rand(3)
print("shape a: {size(a)}")

seed(5)
p = rand(2, 2)
junk = rand(2, 2, seed=42)
q = rand(2, 2)

seed(5)
p2 = rand(2, 2)
q2 = rand(2, 2)

print("q == q2: {q == q2}")

shape a: [3, 1]
q == q2: [1, 1; 1, 1]

shape a: [3, 1]
q == q2: [1, 1; 1, 1]

The seed=42 draw of junk never touches the persistent stream: q (drawn after it) still matches q2, drawn from a freshly-reseeded stream with no interloping seed= call at all.

Units

Qu numeric literals can carry a physical-unit suffix directly (e.g. 5 kHz), which normalizes the value to SI base units at parse/eval time — opt-in dimensional bookkeeping on plain numbers, not a wrapper type. This table lists every suffix the interpreter's apply_unit function actually recognizes and its normalization scale; anything not listed (dB, degC, cycles, samples, ...) passes through unscaled (factor 1), as confirmed by 3 dB evaluating to plain 3.

User-defined units

unit <name> = <expr> declares a named scale factor, for a physical unit this table doesn't already cover (ppm, a lab-specific calibration constant, ...). unit is contextual, not a reserved word — a plain identifier everywhere else, only parsed as this declaration when it's immediately followed by another bare identifier and then =.

unit ppm = 1e-6
x = 5 * ppm            # 5e-6 -- ordinary arithmetic, works immediately

y = 5 ppm               # 5e-6 -- literal-suffix adjacency also works

print(unit_scale("ppm"))   # 0.000001 -- reads the declaration back

1e-6

The grammar already parses <number> <identifier> for any trailing identifier, not just the statically-known spellings in this chapter's table above (that widening — and why a truly unknown unit is a runtime error naming it, not a parse failure — predates user-defined units). unit name = value is what makes a PREVIOUSLY-unknown identifier resolve instead of erroring "unknown unit": it registers name in a runtime table that 5 <name> literal adjacency, ordinary * arithmetic, and unit_scale(name) all consult.

LaTeX Formatting

General LaTeX-formatting of any value — distinct from the plotting subsystem's own figure-export formats. tex mirrors str; printtex mirrors print.

Overloads: tex

Case: scalar

x a real number. Small/large magnitudes get split into \times 10^{n} scientific notation; otherwise it's printed as an ordinary decimal.

print(tex(4.7e-8))

$4.7 \times 10^{-8}$

Case: complex

x a Complex value. Each component is formatted the same way a real scalar would be (including the scientific-notation split when a component is small/large), then joined as re + im i.

print(tex(3 + 4j))

$3 + 4j$

Case: vector or matrix

x a Vec/Mat. Returns a bmatrix environment instead of a bare number, with & separating entries.

print(tex([1, 2, 3]))

$\begin{bmatrix} 1 & 2 & 3 \end{bmatrix}$

printtex follows the exact same three cases — it just prints instead of returning the string.

Examples

tic/toc are the quickest way to answer "how long did that take": start the single global stopwatch with tic(), run the code, then read elapsed seconds with toc(). Because toc() is a non-resetting peek, the same tic() can be read multiple times to lap a loop without restarting the clock each iteration. The example below times a million square-root calls and prints the elapsed seconds:

tic()
for i in 1 to 1000000
    x = sqrt(i)
end
elapsed_s = toc()
print("took {elapsed_s:.4f}s")

took 0.0079s

track and grad are the entry points to Qu's reverse-mode autodiff tape: wrap the inputs you want a derivative with respect to in track (or its alias param), build an ordinary arithmetic expression from them, and then call grad on the result to walk the tape backwards. Here x is tracked, y = x^2 + 2x is computed from it, and grad returns dy/dx evaluated at x = 3 (analytically 2x + 2 = 8), which is then printed:

x = track(3.0)
y = x * x + 2 * x
dy_dx = grad(y, wrt=x)      # 2*x + 2 = 8

print("dy/dx = {dy_dx}")

A numeric literal followed directly by a recognized suffix is normalized to its SI base value at the moment it is parsed — no explicit conversion call needed. 5 kHz becomes 5000 (hertz, the base unit) and 50m uses the bare SI-magnitude prefix form (no base unit attached) to mean 50 * 1e-3. Both results are ordinary numbers from that point on, so they print like any other value:

Fs = 5 kHz        # normalizes to 5000

dt = 50m          # bare SI-magnitude prefix: 50 * 1e-3 = 0.05 (no base unit)

print("Fs = {Fs}, dt = {dt}")

Fs = 5000, dt = 0.05

estimate_complexity turns a handful of (size, time) measurements into an empirical Big-O label, which is the natural finishing move after lap-timing a sweep with tic/toc. The example below times summing the first n integers at four increasing sizes, collecting each elapsed time into a times list with append, iterating the sizes list by value with for n in sizes rather than by index. estimate_complexity prints its own fit summary as a side effect and also returns the label string, which is printed again explicitly here for clarity:

sizes = [100, 1000, 10000, 100000]
times = []
for n in sizes
    tic()
    total = 0
    for j in 1 to n
        total = total + j
    end
    dt = toc()
    times = append(times, dt)
end
label = estimate_complexity(sizes, times)   # e.g. "O(n)"

print("estimated complexity label = {label}")

echo prints several values space-joined on one line, which is handy for quick ad-hoc labeled output without building an interpolated string. warn is for a non-fatal notice: it prints a warning:-prefixed line and execution continues immediately afterward, unlike error, which aborts the current call unless caught:

echo("temperature =", 23.5, "C")
warn("input clipped to [0, 1]")
print("done")

error is how a function signals "this input is invalid" in a way a caller can recover from with try/catch. The raised exception's .message field carries the exact interpolated string passed to error, which is pulled out and printed in the catch block below:

function check_positive(x)
    if x < 0
        error("check_positive: x must be >= 0, got {x}")
    end
    return x
end

try
    check_positive(-3)
catch err
    print("caught: {err.message}")
end

explain is the transparency tool for the soft-compile tier: point it at the name of a user-defined function to find out whether calls to it are running the fast register-only path or falling back to the tree-walking interpreter, and why. Here a trivial numeric function is defined and then explained, printing its soft-compile report:

function double(x)
    return x * 2
end
print(explain("double"))

A standalone timer() object is the tool for lap-timing when a single global tic/toc slot isn't enough — for example, timing nested or concurrent regions independently. restart returns the elapsed time for the lap that just finished and immediately starts a new one, while pause simply freezes the running total in place without resetting it:

t = timer()
start(t)
lap1 = restart(t)
lap2 = restart(t)
pause(t)
print("lap1={lap1}, lap2={lap2}")

stop_grad detaches a tracked value from the autodiff tape so gradients stop flowing through it — the typical use is holding a label or target value steady while still letting gradients flow through the prediction it is compared against. Below, target is tracked and then immediately detached with stop_grad, so only x (the prediction) contributes to dloss/dx:

target = stop_grad(track(5.0))
x = track(2.0)
loss = (x - target) * (x - target)
dloss_dx = grad(loss, wrt=x)
print("dloss/dx = {dloss_dx}")

seed makes the persistent random stream reproducible: reseeding with the same number before each draw guarantees the same sequence of values out of rand/randn. The example below draws two 1x3 uniform vectors around a re-seed and prints both to show they match exactly:

seed(42)
a = rand(1, 3)
seed(42)
b = rand(1, 3)
print("a = {a}")
print("b = {b}")

tex/printtex are for dropping a Qu value straight into a LaTeX document. A very small or large magnitude number gets rendered in \times 10^{n} scientific notation, and a vector or matrix becomes a bmatrix environment. The example prints the LaTeX string for a tiny number with tex, then prints a vector's LaTeX form directly with printtex:

c = 4.7e-8
print("tex string: {tex(c)}")
printtex([1, 2, 3])

builtins, apropos, and help are the engine's own self-description tools — useful when you know roughly what you want but not the exact name. builtins() lists every name the engine answers to, apropos filters that list by a substring, and help reports what is known about one specific name. The example counts the total builtin surface, searches it for anything filter-related, and asks for help on curve_fit:

names = builtins()
print("total builtins: {len(names)}")
hits = apropos("filter")
print("filter-related: {hits}")
help("curve_fit")

device_used and gpu_probe_info answer "did that actually run on the GPU?" after a computation that's eligible for GPU dispatch, such as a large matrix multiply. device_used reports where the last dispatch actually went; gpu_probe_info reports what the one-time startup probe found about the hardware. Together they catch the failure mode of a GPU that silently fell back to the CPU:

A = randn(200, 200)
B = randn(200, 200)
C = A * B
d = device_used()
print("device = {d.device}, gpu_dispatches = {d.gpu_dispatches}")
p = gpu_probe_info()
print("gpu available = {p.available}, crossover = {p.crossover}")

More functions