Neuro Documentation
Status: Alpha. Per-phase status lives in one place, the Quick Roadmap; what each release changed is in CHANGELOG.md.
This file is an index. It describes where things are, not what they do: every feature is defined once, in the page that owns it.
What is Neuro?
A compiled language for high-performance AI workloads. It generates native code through an LLVM 23
backend, and it checks tensor shapes and differentiates tensor code while compiling. GPU
acceleration through MLIR GPU dialects has begun: a @gpu function runs as NVIDIA or AMD kernels, a
@kernel function is one you write per thread, and .to(Device::GPU(n)) keeps a tensor on a GPU
between calls.
Design goals:
- Static typing with inference, for safety and performance
- Tensor primitives as first-class language types
- Compile-time AD as a source-to-source transform over typed HIR, with no runtime gradient tape
- GPU acceleration via the MLIR GPU dialects,
nvvmfor NVIDIA androcdlfor AMD - Zero-copy Python interop via DLPack
Getting Started
- Installation Guide: install Neuro on Linux, macOS or Windows
- Quick Start: basic usage and workflow
- Your First Program: step-by-step tutorial
- examples/: runnable programs, each pinned to its exact exit code and output
Language Reference
| Page | Covers |
|---|---|
| Types | Primitives, literals and suffixes, casts, arrays, slices, tuples, newtypes, aliases, borrows, type inference |
| Strings | The string slice type and its escape sequences, the growable StringBuilder buffer, interpolation, triple-quoted literals, codepoint iteration |
| Tensors | Tensor<T, [dims]>, construction, element-wise arithmetic and broadcasting, matrix multiplication, indexing and slicing, shape generics, named dimensions, reshaping, reductions, sorting, Einstein notation, functional traversals, elementwise math, dynamic shapes, devices |
| Automatic Differentiation | @grad on functions and methods, wrt: selection of parameters and receiver fields, the derivative it generates, .backward() / .grad() / .zero_grad() and the borrows they end, second derivatives with order: 2 and .hessian(), the .detach() and @no_grad fences, its signature rules, which constructs a differentiated body may use, and how the derivative follows branches, loops, calls, function values and elementwise math |
| Variables | val, mut, reassignment, scoping |
| Functions | Declarations, parameters, named arguments, returns, generics, dispatch, closures |
| Expressions | Expression syntax and evaluation order |
| Control Flow | if/else, while, loop, for, break/continue, match, val-else, pool arena blocks |
| Operators | Arithmetic, comparison, logical, bitwise, cast, overloading, assignment places, ??, ?, |>, >> |
| Structs | User-defined types, impl methods, generic methods, associated functions, derives and the derivable traits as bounds, enums |
| Memory Model | What is reclaimed and when: stack values, collections, reassigned bindings, pool blocks, and what still leaks in alpha |
| Modules | Multi-file programs, mod.nr directories, qualified paths, import, inline module blocks, export import re-exports, visibility |
User Guides
- CLI Usage:
neurc check,neurc run,neurc compile, flags,--emit objand the NumPy interop recipe - Editor Support: syntax highlighting for
.nrfiles, and keeping the grammar in step with the lexer - Troubleshooting: common problems and solutions
- Known Bugs: the open defect register
Compiler Architecture
- Compilation Pipeline: end-to-end, source file to native binary
- Lexical Analysis: tokenizer
- Syntax Parsing: AST generation
- Module Resolution: multi-file expansion, imports, visibility
- Argument Binding: named arguments resolved to declaration order
- Semantic Analysis: type checking
- HIR Lowering: AST to typed High-Level IR (
neuro-hir) - LLVM Backend: native code generation from HIR
- MLIR Backend: experimental HIR to MLIR linalg and GPU path
The typed High-Level IR (neuro-hir) is the backend-agnostic contract: every backend lowers from
it. Each slice also keeps a CONTEXT.md beside its source, which is the authority on that slice's
current entry points when this directory disagrees.
Backend stack
| Component | Library | Status |
|---|---|---|
| CPU codegen | inkwell (LLVM 23) | In use |
| MLIR construction | melior (LLVM/MLIR 23) | Every tensor operation to linalg, bufferized through to LLVM IR and linked into every compiled program |
| Autodiff | Neuro's own reverse-mode HIR transform | Generates @grad derivatives, checked against finite differences |
| GPU | MLIR gpu to nvvm (PTX) or rocdl (code object) | @gpu functions compiled on Linux run as NVIDIA kernels, or AMD ones with --gpu-arch gfxNNN, with an opt-in CPU fallback chosen at startup; @kernel functions launch their own per-thread body over a grid; .to(Device::GPU(n)) keeps tensors on any of the machine's GPUs between calls, and a call or a tensor operation runs on the GPU its tensors are on |
Exact dependency versions live in the workspace Cargo.toml files, not here.
File Extensions
| Extension | Purpose |
|---|---|
.nr | Neuro source files |
.nrp | Package definitions (planned) |
Model weights are planned to use the standard .safetensors format rather than a Neuro-specific one.
Project Resources
- README.md: project overview and roadmap
- CHANGELOG.md: version history
- CONTRIBUTING.md: contribution guidelines and the full architecture rules
- VSA.md: the Vertical Slice Architecture ruleset the compiler is built to
- LICENSE: Neuro Shared Source License v2.1