---

Why Vx?

Modern high-performance programs are rarely confined to a single CPU. They orchestrate work across host DRAM, PCIe buses, GPU high-bandwidth memory (HBM), and specialized accelerators like NPUs or the Apple Neural Engine (ANE).

In conventional languages (CUDA, C++, Python), hardware topology and memory spaces are invisible to the compiler. If host code reads a device pointer, or if an asynchronous transfer is not awaited, your program fails at runtime: with a silent corruption, a fatal segmentation fault, or an out-of-memory (OOM) crash hours into a distributed training job.

Vx eliminates this class of bugs at compile time.

Where a value lives (Memory::CPU_DRAM, Memory::GPU_HBM, Memory::NPU_HBM) and where code executes (Topology::GPU[0], Topology::NPU[0], Topology::ANE) are first-class types. The compiler checks memory capacity, bus bandwidth, and address visibility before code ever touches silicon:

---

The 30-Second Demo

Here is a complete matrix multiplication that prepares data on the host, stages it into an accelerator's HBM, executes on the device, and brings the result back:

fn main() -> i32 {
  // 1. Allocate and initialize host matrices
  let a = Tensor<f32, [4, 4]>::fill(2.0);
  let b = Tensor<f32, [4, 4]>::fill(3.0);
  let mut c = Tensor<f32, [4, 4], Memory::NPU_HBM>::uninit();

  // 2. Explicitly stage data across the interconnect into accelerator HBM
  let a_npu = transfer(a, Memory::NPU_HBM);
  let b_npu = transfer(b, Memory::NPU_HBM);

  // 3. Dispatch execution onto the declared topology
  spawn on(Topology::NPU[0]) {
    c = a_npu @ b_npu;
  }

  // 4. Retrieve result back to host DRAM
  let c_host = transfer(c, Memory::CPU_DRAM);
  print(c_host[0][0]); // 24
  return 0;
}

Run it with the built-in JIT:

$ vxc matmul.vx
24

What happens when you make a mistake?

If you forget to transfer the input a and attempt to read it inside the spawn on(Topology::NPU[0]) block, the compiler refuses the program immediately:

Error[E6003] at matmul.vx:12:9: 'a' lives in CPU_DRAM but NPU[0] sees only [NPU_HBM];
insert an explicit transfer to NPU_HBM (cost 50 on the declared path)

The compiler proves that NPU[0] cannot address CPU_DRAM, finds the cheapest legal route across the declared bus edges, calculates the transfer cost, and provides the fix.

---

Quickstart

Prerequisites

• macOS: brew install llvm z3 cmake
• Linux (Ubuntu/Debian): Install LLVM 22 from apt.llvm.org, then apt install z3 lld cmake
• Rust: Stable toolchain (Rust 2021)

1. Build the Compiler

# Clone the repository
git clone https://github.com/vx-lang/Vx.git
cd Vx

# Locate LLVM and write local configuration
./setup.sh

# Source environment variables (required before running cargo)
source config.local

# Build the release compiler
cargo build --release

2. Run Programs

# Run a smoke test with the JIT compiler (default action)
./target/release/vxc examples/docker_smoke.vx

# Compile and check against a declared NVIDIA H100 machine (works on any host!)
./target/release/vxc --host default --machine fleet/h100-sxm.vx examples/docker_smoke.vx -o smoke_h100

# Inspect capacity admission and routing costs as JSON
./target/release/vxc --host default --machine fleet/h100-sxm.vx examples/docker_smoke.vx --diagnostics-json out.json

# Inspect the generated MLIR
./target/release/vxc examples/docker_smoke.vx --action emit-mlir

3. Run the Test Suite

source config.local
cargo test

Over 530 unit tests and 40 integration suites verify placement rules, differential CUDA checks, and determinism.

---

Four Core Pillars

1. Placement and Capacity in the Type System

A tensor's type in Vx carries its element type, dimensions, and its residency domain: Tensor<f32, [4, 4], Memory::GPU_HBM>.

The compiler enforces strict invariants before codegen:

A differential test suite pairs each check against CUDA on an NVIDIA A100: errors that CUDA detects as runtime aborts, failed cudaMalloc allocations, or segfaults are caught by Vx at compile time.

2. Declarative Hardware Topologies (fleet/)

Instead of hardcoding memory sizes and bus links, machines are declared as clean specification files:

Memory HBM  { capacity: 80 GiB, bandwidth: 3.35 TB/s, managed: explicit, scope: device }
Memory L2   { within: Memory::HBM, capacity: 50 MiB, bandwidth: 12 TB/s, managed: cached }
Memory SMEM { within: Memory::L2, capacity: 228 KiB, bandwidth: 128 B/cyc,
              clock: 1.98 GHz, replicas: 132, granule: 1 KiB, scope: sm }

Topology Device {
    arch: nvptx64,
    memory: Memory::HBM,
    transfer Memory::CPU_DRAM -> Memory::HBM : 63 GB/s,
}

The fleet/ directory includes 12 validated specifications:

• Accelerators: NVIDIA A100 (40GB & 80GB), H100 SXM, H200, B200, AMD Instinct MI300X, Apple M4 UMA, ARM Cortex-M7.
• Nodes & Systems: 2-GPU and 8-GPU interconnected systems, Intel Xeon compute targets, and x86 host profiles.

Because vxc cross-compiles against declared machines (--machine fleet/<sku>.vx), you can verify and compile binaries for an 8-GPU H100 cluster directly from an M4 MacBook Air without renting cloud GPUs.

3. Zero-Lock Parallel Compiler Frontend

Traditional compiler frontends frequently bottleneck on single-threaded symbol resolution or lock contention (Mutex/RwLock). Vx introduces an 8-phase parallel architecture:

• 256-bit Global Identifiers (GIDs): Every symbol, nominal type, and monomorphized instantiation is a flat [u64; 4] content hash. Symbol lookup involves zero pointer chasing or string hashing.
• Lock-Free Phases: Rayon worker threads parse and type-check modules in complete isolation. An immutable frozen epoch (GlobalSession) guarantees that worker threads never contend.
• SIMD Type Patching: Vectorized sweeps patch local deferred type parameters to absolute global indices in microseconds.
• Deterministic Output: Generated MLIR is byte-identical whether compiled on 1 thread, 16 threads, or with multi-threading disabled.

For a deep dive into the design, see the Parallel Compiler Architecture.

4. Native ML Primitives & Automatic Differentiation

Vx includes native tensor abstractions with rank and extent tracking, dynamic dimensions (Tensor<f32, [?, ?]>), matrix multiplication (@), and built-in automatic differentiation (grad, vjp, jvp) lowering through an optional Enzyme MLIR plugin:

fn loss(x: f32) -> f32 {
    return x * x;
}

fn main() -> i32 {
    let dx: f32 = grad(loss, 3.0); // 6.0
    print(dx);
    return 0;
}

For a full real-world demonstration, explore examples/llama.vx, which implements a complete, clean Llama 2 forward pass with tensor abstractions.

---

How it Compiles

flowchart TD
    SRC["Source Program (*.vx)"] --> PARSER["Parallel Frontend\n(256-bit GID content hashes)"]
    FLEET["Machine Declaration (fleet/*.vx)"] --> CHECKER["Topology & Memory Algebra Engine\n(Capacity E6009, Visibility E6003, Z3 Seams)"]
    PARSER --> CHECKER
    CHECKER --> HIR["Flat HIR Instruction Stream"]
    HIR --> MLIR["MLIR (Custom vx Dialect)"]

    MLIR --> CPU["Host CPU (LLVM IR -> JIT or Object File)"]
    MLIR --> GPU["NVIDIA GPU (NVVM -> PTX -> cuBLAS)"]
    MLIR --> ANE["Apple Silicon (CoreML Plugin -> Neural Engine)"]
    MLIR --> REMOTE["Remote Nodes (Wire Protocol over SSH / TCP)"]

Supported Execution Backends

---

Current Status & Known Limitations

Release Version: Vx is currently in v0.0.2. The syntax and core type-system checks are stable. The placement, routing, and memory algebra systems are verified by active test suites. However, as an early research systems compiler, several language features are actively being built.

What is working vs. in progress

Full tracking is available on our GitHub Issue Tracker.

---

Developer Tooling & Ecosystem

• vx-analyzer: Language Server Protocol (LSP) providing diagnostics, hover tooltips, and go-to-definition.
• vscode-vx: Official VS Code extension providing syntax highlighting and LSP integration.
• vx-format: Official AST-aware code formatter for .vx files.
• vx-opt: Specialized driver for testing and inspecting passes on the custom vx MLIR dialect.

---

Repository Layout

src/                  Compiler implementation in Rust
  lexer, parser/      Source parsing and interface extraction
  syntax/             AST, type system, and topology declarations
  hir/                Parallel type checking, borrow checking, memory algebra
  codegen/            MLIR generation
  dialect/            Custom vx MLIR dialect and lowering passes (C++)
  gid.rs              256-bit content-hashed Global Identifiers
  pipeline.rs         Zero-lock 8-phase parallel frontend
runtime/              Dispatch runtimes (Host CPU, NVIDIA CUDA, Apple CoreML, Remote Worker)
fleet/                Declarative machine descriptions (A100, H100, B200, MI300X, M4, etc.)
stdlib/               Standard library modules (tensor, simd, vec, io, math, fs, etc.)
examples/             Example programs (including Llama 2 forward pass in llama.vx)
docs/                 Language specification, tutorials, and architecture designs
vx-analyzer/          Language server (LSP)
vscode-vx/            VS Code extension
tests/                Unit, integration, middle-end, and differential CUDA test suites

---

Documentation & Learning More

• The Vx Book (vxlang.org/docs): The official comprehensive guide covering installation, a language tour, ownership, topologies, the standard library, and compiler error diagnostics.
• Language Tutorial: In-repo introductory walkthrough of syntax, tensors, and topologies.
• Memory Algebra Specification: In-depth model of capacities, bandwidths, and routing costs.
• Parallel Compiler Architecture: Technical deep-dive into the 256-bit GID and zero-lock pipeline.
• Project Roadmap: Feature tracking against our core architectural goals.

---

Community

• Discord: chat with the Vx community, ask questions, and discuss the language and compiler.
• r/vxlang: questions, design discussion, and anything that is not a bug report.
• Issue tracker: bugs, and diagnostics that fired when they should not have. A program that reproduces it is worth more than a description of it.

---

Citing Vx

If you use Vx in your research or systems work, please cite:

@misc{vx2026,
  author       = {Aditya Kumar},
  title        = {{Vx}: a systems programming language for heterogeneous computing},
  year         = {2026},
  howpublished = {\url{https://vxlang.org}},
  note         = {Version 0.0.2. Source at \url{https://github.com/vx-lang/Vx}}
}

---

License

Vx is distributed under the Apache License 2.0 with LLVM Exceptions. See LICENSE for details.