RBQN

A Rust implementation of the BQN array language that uses the whole machine: multicore CPU, GPU dispatch, typed arrays, a bytecode VM.

cargo install rbqn

Or download a binary for macOS, Linux or Windows from Releases.

   +´↕10
45
   3‿3⥊↕9
┌─       
╵ 0 1 2  
  3 4 5  
  6 7 8  
        ┘
   {𝕩≤1 ? 𝕩 ; (𝕊 𝕩-1)+𝕊 𝕩-2}¨ ↕10
⟨ 0 1 1 2 3 5 8 13 21 34 ⟩

Multicore, 1e8 elements, bench/wow/run.sh against CBQN (12-core Intel Mac, 2026-10-24, full output, which does not record the machine's load; a quiet-machine re-measure is #119):

Cells: median in-process seconds for the operation alone (median whole-process wall seconds).

RBQN passes the official BQN test suite and is self-hosting: it compiles its own compiler, runtime and formatter from the BQN sources, with no other BQN implementation involved. The goal is a BQN that leverages compute as far as it safely can. The language is Marshall Lochbaum's; the implementation goes its own way.

Status: pre-1.0, complete language, no known divergences from the specification. •file.Open is unspecified in BQN; here it raises not yet implemented.

What works

• The language. Every primitive, modifier and combinator; headers, predicates, multiple bodies, namespaces, ⁼ for the invertible primitives, ⌾ and ⚇. The official test suite passes in full (13 files, 1316 cases at the pinned BQN revision, see Testing). The workspace has 50 unsafe sites (bench/unsafe_census.sh); every unsafe site carries a // SAFETY: comment (or a # Safety doc section for unsafe fn), enforced by clippy::undocumented_unsafe_blocks = "deny" for blocks and by bench/unsafe_census.sh in CI for the rest; rbqn-core, rbqn-prim and rbqn-vm pass under Miri in CI (the miri job). Three cargo-fuzz targets (expr, fmt, bytes; bench/fuzz/) run a short smoke in CI, and expr has run for 4.1 hours with no open crash (log: bench/fuzz/logs/2026-10-24.txt; long run: bench/fuzz/run.sh expr 86400).
• Self-hosting. The compiler, runtimes and formatter are compiled by RBQN itself from c.bqn, r0.bqn, r1.bqn and f.bqn, embedded as bytecode. A fixpoint check confirms that the compiler compiled by itself produces identical bytecode.
• Typed arrays. Arrays are stored unboxed as bits, i8, i16, i32, f64, or 8/16/32-bit characters, squeezed to the narrowest exact type, with boxed arrays only for nested data; the primitives have specialised paths for each.
• GPU dispatch. Elementwise arithmetic, reductions, scans, sorting, selection, softmax and matrix multiply have wgpu kernels. Arithmetic, folds, scans, sorts and •math.MatMul dispatch automatically, per call, when a cost model calibrated on the machine says the GPU wins, using exact integer kernels only, so the result is the same on either path; the •gpu namespace gives explicit f32 kernels and device-resident arrays with lazy fusion. See GPU.
• •FFI. The full specification: numeric, pointer (*, mutable &), array and struct types, > and 𝕨/𝕩 argument markers, a for BQN values, pointer objects with Read Write Add Sub Cast Field, calls through libffi on the platform C ABI. f←"@" •FFI "&"‿"memset"‿"&u8"‿"i32"‿"u64" ⋄ F ⟨0‿0‿0‿0, 7, 3⟩ gives ⟨ 7 7 7 0 ⟩.
• Errors with position. Every error names the primitive and the shapes involved, then the file and line, the source line and a caret under the failing token.
• Recursion is bounded by the 512 MB interpreter stack, not a call count. Runaway recursion, and native recursion on deeply nested arrays, raise Stack overflow instead of crashing.
• System values. •BQN, •Import, •Show, •Out, •Fmt, •Repr, •Type, •Decompose, •Glyph, •Fill, •CurrentError, •Hash, •HashMap (Count Keys Has Get Set Delete Values), •ns (Keys Values Has Get; Keys and Values follow definition order), •ParseFloat, •FromUTF8, •ToUTF8, •UnixTime, •MonoTime, •Delay, •SH, •Exit, •args, •path, •name, •wdpath, •state, •rand, •MakeRand (a seed gives the same sequence in every process), •platform, •GroupLen, •GroupOrd, •FLines, •FChars, •FBytes, •PrimInd, •ReBQN.
• Namespaces. •math (Sin Cos Tan ASin ACos ATan Log Cbrt Hypot Erf ErfC Comb Fact GCD LCM MatMul Softmax Pi Sinh Cosh Tanh Asinh Acosh Atanh LogFact Sum Atan2 Expm1 Log1p Log2 Log10), •gpu, •file (Lines Chars Bytes List At Name Parent Exists Type CreateDir Remove Rename path Size Created Modified Accessed RealPath MapBytes), •term (RawMode CharB CharN Flush OutRaw ErrRaw), •bit (_cast _not _neg and the binary operations across widths).
• A REPL (-r, or rbqn with no arguments) that prints a header line (version, threads, GPU adapter, )help) on a terminal, with history, backslash glyph input (\r gives ↑, the standard BQN keymap), Tab completion of system values and session names, )help, )off or )exit or Ctrl-D to leave, and pasted multi-line programs evaluated line by line (crates/rbqn/tests/repl_first_contact.rs); plus script, expression and file modes.

Performance

bench/compare.sh, hyperfine, mean wall time in ms including process startup, Apple M3 Pro, 2026-10-19, RBQN at commit 9595606. CBQN f4257c14 is shown as a reference point, not a target.

Scalar code through the VM (the fib row) is where the most room remains. bench/ holds the history of every measured step, and bench/pgo.sh builds a profile-guided binary that is 10 to 16% faster on VM-bound code (bench/pgo.md).

GPU

Two layers, kept separate so that nothing outside •gpu ever changes a result.

Automatic dispatch. Arithmetic, folds, scans, sorts and •math.MatMul may run on the GPU. Only integer kernels whose result is exact are used, so the answer is the same as the CPU path; f64 arithmetic stays on the CPU (Metal has no f64). A per-operation cost model compares the modelled GPU time (including any one-time device initialisation not yet paid) with the modelled CPU time and picks the cheaper on each call; RBQN_GPU_DEBUG=1 prints each decision. The model's constants are measured per machine at first device use (small GPU and host workloads timed at two sizes, crates/rbqn/src/calibrate.rs) and cached by adapter, driver and thread count under RBQN_CACHE_DIR (default: the platform cache directory); RBQN_GPU_CALIBRATE=1 measures again (crates/rbqn/tests/gpu_calibrate.rs). tests/gpu/corpus.txt runs 87 expressions under forced GPU and CPU-only and requires identical output (make gpu-corpus). make gpu-parity runs the stranger docs corpus and grid with RBQN_GPU=force and RBQN_GPU=off on the same binary and requires identical reports; it needs CBQN_BIN and BQN_SRC, and is run on a machine with a GPU, not in CI. The CBQN parity job in CI is a regression floor, not the goal: the spec is the target, and deliberate divergences beyond CBQN are recorded with a spec citation in bench/stranger/known_divergences.txt.

The device is used only when the cost model expects it to win, and results are identical either way. Median of 3 in-process seconds on an AMD Radeon Pro 5300M (Metal), from bench/wow/results/2026-10-24-bench-matmul-cpu-166.md (bench/wow/run.sh; that file records the load and foreign CPU of the run, which was shared with other builds: load1 16 at start, foreign CPU peaked at 533%, so the large ratios are the evidence, not the small ones; a quiet-machine re-measure is #119):

•math.MatMul and the idiom +˝∘×⎉1‿∞ run a blocked, packed, multicore f64 kernel on the host (#166): 4096² takes 15.6 s at -t 1 and 2.6 s on 12 threads against 42.8 s for CBQN's +˝∘×⎉1‿∞ (a heavily loaded machine; see the results file), up from 704 s for the earlier naive loop (bench/wow/results/2026-10-24-bench-gpu-rows-radeon5300m.md). The calibrated model keeps these sizes on the host on this machine; the exact-integer GPU kernel (4096² in 5.8 s when forced here) is chosen only where the model predicts it faster, for example at -t 1. Sort and row sums stay on the CPU here. The forced GPU sort (upload and download included) is slower than the host radix sort at 1e6 and about as fast from 1e7 to 1e8, and CBQN's own sort is faster than both (2.462 s at 1e8). There is no batched row-reduce kernel, so a forced +´˘ runs one reduction per row and takes 19.261 s at 1e4×1e4 against 0.254 s on the host. RBQN_GPU=force produces those GPU numbers and RBQN_GPU_DEBUG=1 prints the model's predicted times next to each decision.

•gpu. Explicit f32 kernels and device-resident arrays, for code that accepts f32 rounding in exchange for speed.

Contract:

• Inputs are numeric arrays of any element type; every element is rounded to f32 before upload (values beyond f32 range become ∞).
• MatMul and Softmax take resident or host arguments and return resident results, so •gpu.Fetch a •gpu.MatMul b •gpu.MatMul c uploads each input once and downloads once. Any other primitive (and •Show/•Fmt) downloads a resident value on first use and keeps the host copy; ≢, ≠ and = read the shape without a download.
• Tensor stores f32 when every element is exact in f32, else i32 when every element is an i32 integer, else f32 (rounded). So •gpu.Fetch •gpu.Tensor x ≡ x for i32 integers and f32-exact floats. An empty x stays on the host. MatMul/Softmax on an i32 tensor convert it through the host (one logged download and upload). Resident device buffers are kept until the process exits (host arrays are freed once nothing references them; the array store is #124).
• Arithmetic on a resident value (+ - × ÷ ⌊ ⌈ |, monadic or dyadic, with a number or a same-shape resident operand) is f32 and stays lazy. The chain runs as one kernel when Fetch, MatMul, Softmax or any other primitive needs it, and +´ ×´ ⌊´ ⌈´ on a resident list runs it inside the reduce kernel: +´ 1+2וgpu.Tensor x is one dispatch with nothing downloaded except the sum. A host-array operand downloads, as before.
• Downloaded values are ordinary arrays holding the f32 values. They differ from •math.MatMul / •math.Softmax (exact f64, CPU) by rounding: (2‿2⥊0.1) •gpu.MatMul 2‿2⥊3 gives 0.6000000238418579 where •math.MatMul gives 0.6000000000000001.
• No size threshold and no exactness gate: every call dispatches, so small inputs pay the transfer cost.
• With no device (a CPU-only build via --no-default-features, --no-gpu, RBQN_GPU=off, or no adapter) MatMul, Softmax and Tensor error with no GPU available, and Available returns 0.
• RBQN_GPU_DEBUG=1 logs each upload, download and (f32, resident) dispatch.

Usage

rbqn [options] [file.bqn [arguments]]

Options:
  -f file    execute the contents of the file with all further arguments as •args
  -e code    execute the argument as BQN
  -p code    execute the argument as BQN and print its result pretty-printed
  -o code    execute the argument as BQN and print its raw result
  -M num     accepted for CBQN compatibility; no heap limit is enforced yet
  -t num     use num threads for large array arithmetic (default: RBQN_THREADS or all cores; 1 = serial)
  -r         start the REPL after executing all arguments
  -s         start a silent REPL
  --no-gpu   disable GPU acceleration
  --help     show this help text
  --version  display version information (including `gpu:` adapter name, `off` or `none`)

Environment: RBQN_GPU=off|force overrides the dispatch decision (force bypasses the cost model only); RBQN_GPU_DEBUG=1 traces it; RBQN_GPU_CALIBRATE=1 re-measures the cost model and RBQN_CACHE_DIR moves its cache; RBQN_THREADS sets the thread count.

Build

cargo build --release          # target/release/rbqn
cargo build --release --no-default-features   # CPU-only, no wgpu

Rust 1.88 or later (edition 2024). The only dynamic dependencies beyond the C runtime are libffi (libffi.so.8 on Linux, e.g. apt install libffi8; part of the system on macOS) and libgcc_s; ldd target/release/rbqn on Linux lists libffi.so.8 libgcc_s.so.1 libm.so.6 libc.so.6. The BQN compiler and runtime are embedded as bytecode, so nothing else is needed to build or run. Or install from crates.io: cargo install rbqn.

Architecture

About 34K lines of Rust outside tests/ directories, in five crates:

Bootstrap

Bytecode files in crates/rbqn/bins/ are compiled from the BQN sources (c.bqn, r0.bqn, r1.bqn, f.bqn) by RBQN itself and loaded with include_bytes!.

# Regenerate bins from updated BQN sources
BQN_SRC=/path/to/BQN/src cargo run -p rbqn --features gen-tools --bin rbqn-gen -- --self

# Verify fixpoint: the compiler compiled by itself produces identical bytecode
BQN_SRC=/path/to/BQN/src cargo run -p rbqn --features gen-tools --bin rbqn-gen -- --self --fixpoint-check

Testing

cargo test --workspace --release                  # unit and integration tests (•FFI tests compile tests/ffi/lib.c with cc)
BQN_TEST_DIR=/path/to/BQN/test ./test_suite.sh    # official BQN test suite
make gpu-corpus                                   # GPU kernels vs CPU, 87 expressions

CI (.github/workflows/ci.yml, on every push to main and every pull request) runs cargo test --release --workspace (job test, Linux), the official suite and clippy with -D warnings (job build-test, macOS, against a pinned BQN revision), the docs and grid comparison against a pinned CBQN (job parity) and Miri (job miri); make gpu-corpus and make gpu-parity run on a machine with a GPU. The suite result at this commit:

simple       PASS|20|0      fill         PASS|62|0
literal      PASS|52|0      header       PASS|156|0
syntax       PASS|156|0     under        PASS|64|0
bytecode     PASS|37|0      undo         PASS|68|0
token        PASS|29|0      namespace    PASS|50|0
identity     PASS|14|0      unhead       PASS|44|0
prim         PASS|564|0

Acknowledgements

BQN was designed by Marshall Lochbaum. The language specification, the compiler and runtime sources (c.bqn, r0.bqn, r1.bqn, f.bqn) and the test suite are his work, under the ISC License. RBQN embeds bytecode compiled from those sources.

CBQN, by dzaima and the BQN community, provided the first bytecode RBQN ran before it became self-hosting, and its documented internals were reference material for the bytecode format and runtime structure.

• BQN: https://mlochbaum.github.io/BQN/
• BQN community: https://mlochbaum.github.io/BQN/community/
• CBQN: https://github.com/dzaima/CBQN