Razum (rzm)

A compiled programming language purpose-built for AI — with the speed of Rust and the feel of Python.

Razum (from Bulgarian разум — mind, intellect) is a next-generation language that makes tensors, automatic differentiation, and hardware abstraction first-class citizens of the language — not external libraries.

---

Why Razum?

Today's AI workflows split across Python (for ergonomics) and C++/CUDA (for performance). This split creates unnecessary complexity:

• Python is slow and requires C-extensions for throughput
• CUDA/C++ are fast but painful to write and hardware-specific
• Moving tensors between RAM and VRAM is manual and error-prone
• No compile-time checking for shape mismatches

Razum solves all of this in a single language.

---

Hello, Tensor

fn main() {
    let x = tensor([
        [1.0, 2.0, 3.0],
        [4.0, 5.0, 6.0],
    ]);
    let w = tensor([[0.1], [0.2], [0.3]]);
    let y = x @ w;   // Tensor[2, 1] — shape checked at compile time
    print(y);
}

cargo run -- run examples/hello.rz
cargo run -- jit examples/matmul.rz

Train from CSV

fn mse_loss(w, b, x, y) -> f32 {
    let pred = linear(x, w, b);
    let d = pred - y;
    mean(d * d)
}

fn main() {
    let x = csv_parse(read_file("examples/data/features.csv"), 8, 2);
    let y = csv_parse(read_file("examples/data/labels.csv"), 8, 1);
    let mut w = tensor([[0.0], [0.0]]);
    let mut b = tensor([0.0]);
    for epoch in 300 {
        let g = grads(mse_loss)(w, b, x, y);
        w = sgd_step(w, g[0], 0.02);
        b = sgd_step(b, g[1], 0.02);
    }
    save_tensor(w, "examples/data/w_trained.bin");
}

cargo run -- run examples/train_csv.rz
cargo run -- jit examples/train_csv.rz

Model DSL (ONNX export ready)

model Classifier {
    input: Tensor[Batch, 784, f32];
    output: Tensor[Batch, 10, f32];

    body {
        input
        |> Linear(128)
        |> ReLU()
        |> Linear(10)
        |> Softmax()
    }
}

rzmc export model.rz --onnx classifier.onnx

---

Key Features

Tensors as native types

Tensors are fundamental types like int or string. The compiler checks shapes before execution — ~90% of shape-mismatch bugs vanish.

let a: Tensor[32, 64, f32] = ...;
let b: Tensor[64, 128, f32] = ...;
let c = a @ b;             // ✅ 32×128
let d = a @ a;             // ❌ Compile error: 64 ≠ 32

Hardware agnostic — write once, run anywhere

Your code is the same. The compiler decides whether to execute on CPU, NVIDIA GPU, AMD GPU, Apple Neural Engine, or Google TPU.

// No #ifdef, no device-specific code
fn compute(x: Tensor[1024, 1024, f32]) -> Tensor[1024, 1024, f32] {
    x @ x.T()
}
// Razum picks the best device

Automatic differentiation — built into the grammar

Gradients are not a library — they are a first-class language construct:

fn loss(w: Tensor[512, f32], x: Tensor[512, f32]) -> f32 {
    sum((w * x) * (w * x))
}

let g = grad(loss)(w, x);       // single-param gradient
let gs = grads(loss)(w, x);     // all-param gradients

Dual-stage compilation: AOT + JIT

• AOT (Ahead-of-Time): Static type/shape checks, kernel fusion, machine-level optimization
• JIT (Just-in-Time): Recompiles on-the-fly for dynamic data dimensions

ARC + Static Tensor Arena — no GC pauses

Core design choice (Nim-style): deterministic free without a stop-the-world GC.

• ARC: each tensor handle has a strong refcount. The compiler inserts retain/release (reassignment + last-use). When the count hits zero, the tensor is destroyed immediately.
• Static Tensor Arena: freed host buffers return to a size-class freelist / fixed-shape slots and are reused across training epochs (arena_reset).
• Observability: arc_stats() / arena_stats() print live/peak handles and buffer reuse.

arc_reset_stats();
// ... train loop with grad + sgd_step ...
arena_stats();  // allocs / reuses / fixed_hits
arc_stats();    // live / peak / retains / releases / frees

See examples/arc_memory.rz and docs/architecture.md.

Automatic kernel fusion

The compiler fuses consecutive ops into single kernels, eliminating redundant data movement between memory and compute units.

Package manager built in

rzmc pkg handles dependencies — git and local path deps with a simple rzm.toml manifest.

ONNX export

Export Razum models to standard ONNX format for interoperability with PyTorch, TensorFlow, ONNX Runtime, and more.

---

Comparison

	Python+PyTorch	Rust (tch/burn)	Razum
Tensors	Library	Library	Native
Auto-diff	Library	Library	Native
Compile shapes	No	No	Yes
Sparse / GNN	Library	Library	Native ops
Prob / Dist ops	Library	Library	Native ops
Neural ODE	Library	Library	odeint
GPU agnostic	No	No	Yes
Memory	GC	Borrow checker	ARC
Kernel fusion	Manual	Manual	Auto
Speed	Slow	Fast	Fast
Ease of use	Easy	Hard	Easy

---

Installation

Razum is in active development. First alpha release coming soon.

# From source (requires Rust toolchain)
git clone https://github.com/your-org/rzm.git
cd rzm
cargo build --release
cargo install --path crates/rzmc

# Using the package manager (working)
rzmc pkg init myproject
rzmc pkg add somelib --git https://github.com/user/somelib --tag v0.1.0
rzmc pkg install

---

Architecture

Source (.rz)  →  Lexer  →  Parser  →  AST
    →  Semantic Analysis (types + shapes)
    →  Auto-Diff Transform
    →  Optimizer (kernel fusion, DCE, tiling)
    →  MIR (Mid-level IR) →  LIR (Low-level IR)
    →  Code Gen ──→  CPU (Cranelift JIT / AOT)
                └─→  GPU (wgpu compute shaders)
    →  Runtime (Static Tensor Arena, JIT, Device Manager)

Full architecture: PLAN.md · More detail: docs/architecture.md

---

Progress

Component	Status
Lexer / Parser / AST	Done
Type Checker + Shapes	Done — const / named / unknown dims, dynamic load
Interpreter (CPU)	Done — rzmc run
Reverse-mode AD	Done — if/for/while (const + data-dep) + MIR adjoint codegen
Dense / activations	Done — linear, relu, softmax, mean, log, abs, sqrt, exp
Train loops	Done — SGD, MLP, CSV batch, per-sample rows
Cranelift JIT + AOT	Done — tensors + AD + .o object files
Kernel fusion	Done — 7 patterns with fixpoint chain fusion
Static Tensor Arena	Done — freelist + fixed-shape slots + auto-reserve
Batch specialization	Done — JIT specialization for dynamic batch dims
Dual dtype	Done — f32 default + full f64 host (GPU f32)
File I/O	Done — read_file, csv_parse, save_tensor, load_tensor
Tensor indexing	Done — t[i], tensor([a,b]) on JIT
Multi-file compilation	Done — rzmc jit a.rz b.rz
Model DSL	Done — model { body { |> } }
GPU (wgpu)	Done — ML ops + elemwise + fused kernels + resident + weight cache
Math builtins	Done — abs / sqrt / exp (interp + JIT + AD + GPU)
Pretty diagnostics	Done — ariadne (CLI source highlights)
LSP	Done — diagnostics + hover + go-to-def + completion
Formatter / REPL	Done — rzmc fmt, rzmc repl
VS Code extension	Done — editors/vscode (LSP client + syntax)
Package manager	Done — rzmc pkg init/add/install/list + rzm.toml + git/path deps
ONNX export	Done — rzmc export --onnx + model DSL + checker validation
Hardening (Phase 6)	Done — AD math VJP, fail-loud AD, golden examples, ops matrix
ARC memory	Done — Nim-style refcount + MIR insert_arc + static arena
Adam optimizer	Done — exp_avg / exp_avg_sq / adam_update + examples/adam.rz
Gather / scatter_add	Done — GNN message-passing + AD (examples/gnn_scatter.rz)
Probabilistic primitives	Done — normal_log_prob (AD) + normal_sample (examples/normal_fit.rz)
Neural ODE (odeint)	Done — fixed-step RK4 + AD unroll (examples/neural_ode.rz)
COO spmm	Done — sparse×dense + AD (examples/spmm.rz)
Dist helpers	Done — softplus, kl_normal_std (examples/vae_kl.rz)
Projected constraints	Done — project_box / clip_by_value (examples/project_sgd.rz)
Math paradigms (idea/4)	Vertical slices complete — type-level Dist/CSR/adaptive ODE later

Docs: getting-started · language · autodiff · ops matrix · limitations · idea/4 math paradigms · PLAN

---

Try it now

cargo build --release

# Killer demos — batch CSV train + per-sample row SGD
cargo run -- run examples/train_csv.rz
cargo run -- jit examples/train_csv.rz
cargo run -- jit examples/train_rows.rz

# GPU (wgpu; resident buffers between ops; CPU fallback)
RZM_DEVICE=gpu cargo run -- jit examples/gpu_chain.rz
RZM_DEVICE=gpu cargo run -- jit examples/gpu_softmax_sgd.rz
RZM_DEVICE=cpu cargo run -- jit examples/matmul.rz

# Auto-diff: nested helpers, differentiable if / while, math builtins
cargo run -- jit examples/nested_grad.rz
cargo run -- jit examples/if_grad.rz
cargo run -- jit examples/while_grad.rz
cargo run -- jit examples/math.rz

# Static arena + batch specialization + dual dtype
cargo run -- jit examples/arena_train.rz
cargo run -- jit examples/batch_spec.rz
cargo run -- jit examples/dual_dtype.rz

# REPL
cargo run -- repl

# Classic examples
cargo run -- run examples/mlp.rz
cargo run -- jit examples/grad.rz
cargo run -- jit examples/sgd.rz
cargo run -- jit examples/adam.rz
cargo run -- jit examples/normal_fit.rz
cargo run -- jit examples/gnn_scatter.rz
cargo run -- jit examples/neural_ode.rz
cargo run -- jit examples/spmm.rz
cargo run -- jit examples/vae_kl.rz
cargo run -- jit examples/project_sgd.rz
cargo run -- jit examples/linear.rz

# AOT object file
cargo run -- build examples/hello.rz -o hello.o

# Package manager
cargo run -- pkg init myproject
cargo run -- pkg add somelib --path ../somelib
cargo run -- pkg install
cargo run -- pkg list

# Model export
cargo run -- export examples/model.rz --onnx model.onnx

# Tests & tools
cargo test
cargo run -- lsp          # Language server (stdio)
cargo run -- fmt file.rz  # Formatter
cargo run -- repl         # Interactive REPL

---

Documentation

• Getting Started — installation and first steps
• Language Guide — syntax, types, tensors, Dist, sparse, ODE, optimizers
• Auto-Differentiation — grad/grads, differentiable control flow
• Ops matrix — run / JIT / AD / GPU support per op
• GPU Programming — wgpu backend, resident tensors, device selection
• Package Manager — rzmc pkg, rzm.toml, dependencies
• ONNX Export — model DSL → ONNX graph
• Architecture — compiler pipeline, crate structure
• Limitations — known gaps (honest)
• idea/4 — math paradigms beyond tensors (BG design notes)
• Plan — full architectural plan (Bulgarian)

---

Contributing

The project is in active development. To contribute:

1. Read PLAN.md for the detailed architecture
2. Check idea/ for original design discussions
3. Open an issue or PR

Core technologies: Rust, Cranelift, wgpu, ONNX.

---

License

This project is licensed under the MIT License — see LICENSE for the full text.