Repository navigation
NeuroBrix 0.5.4 — NVIDIA (CUDA) and CPU
The published version has been 0.5.3 since 2026-09-03, and main is 850 commits
past it. Testers have been running an engine we know is wrong on points that are
fixed here.
Apple Silicon is not in this release. Its work lives on metal-first-light,
unmerged, and its CUDA-side proofs are not all measured yet. Apple ships in 0.5.5,
with its numbers already published upstream.
Read this first: installing on an NVIDIA machine
pip install neurobrix alone will give you a CPU-only engine if your driver is
CUDA 12.x, because pip resolves the newest PyTorch from PyPI and that is built for
CUDA 13. Install PyTorch from the index that matches your driver first:
# Volta (V100) and other CUDA 12.x drivers — see the README for the full table
pip install torch --index-url https://download.pytorch.org/whl/cu126
pip install neurobrix
neurobrix doctorneurobrix doctor is the check, and it names this exact mistake rather than letting
you discover it at the first run:
PyTorch: 2.14.0+cu130
built for: CUDA 13.0
NVIDIA driver: 535.309.01
GPU visible: NO
But the driver DOES see: Tesla V100-SXM2-16GB (7.0), ...
So PyTorch was installed for a CUDA version this driver or GPU cannot serve.
1 problem(s) that will block a real run
Run neurobrix doctor before anything else. If it is green, the engine is ready.
What does not work, said plainly
A tester who knows what to avoid leaves satisfied; one who finds out alone does not.
The video family is under investigation
Wan2.1-T2V-1.3B-Diffusers produces a degenerate output — a textured field with no
scene. The cause is not found, and these axes are already excluded by
measurement, so nobody needs to repeat them:
- three engine commits, including the one whose artefact was coherent two days before
- two stacks: torch 2.14.0+cu126 and torch 2.5.1+cu121
- autotune on, and
NBX_DISABLE_AUTOTUNE=1 - the local replay cache emptied
- the certified autotune directory switched off
- both execution modes, including the compiled oracle
- the container's bytes — CRC-checked against its archive, 45 members, the only
difference a build timestamp
Another video model, CogVideoX-2b, renders coherently at 9, 13 and 17 frames, and
no other family is affected.
A warning that generalises beyond this bug: degeneracy statistics did not catch
it. Per-frame standard deviation 26-59, 163-248 distinct values, frame-to-frame
change 1.7-15.9, zero flat rows — every mechanical number reads healthy and the
picture is noise, because a fine dither supplies variance, distinct values and
inter-frame motion all at once. Judge a video by looking at it.
Automatic op-level tiling is not wired
A request too large for your card is refused with its figures — how many tiles
the work would fit in, what each would cost, and what that is as an input scale —
and is not reshaped for you:
model: 16,794 MB of activations against 32 MB of weights — it fits in 2 tiles of
about 8,629 MB each, inside a 9,952 MB budget (a floor: a real tiling's halo costs
more); the same reduction from the input side is each spatial dimension at 0.71x
Prism's cascade now contains the tiling rung and consults it before falling back to
the host. The detector it asks decides overflow from an op's own footprint against
the card, rather than against what is left of the card at that point in the
schedule, so it declines on the case that motivated it. Use a smaller input, or the
tile count the refusal names.
The memory estimate is not exact, and its error has two signs
Measured on a four-V100 rack, planned against the drained watermark:
| shape | example | |
|---|---|---|
| activations dominate | real-esrgan-x4, swin2SR-x4 | 1.4x-2.3x short |
| all components persistent | TinyLlama 0.99x, whisper-v3-turbo 1.06x | near exact |
| a transient component counted as co-resident | canary-qwen-2.5b 1.69x, Sana-1600M 2.20x | over |
An over-estimate is safe against a crash and can place a model on a heavier rung
than it needs. No single multiplier corrects both signs.
What does work, and how it was checked
Each family below was judged by an instrument outside the engine, on the release
commit:
| family | model | the instrument | result |
|---|---|---|---|
| llm | TinyLlama-1.1B-Chat | the Python it wrote, executed against 15 cases it never saw | all 15 correct |
| stt | whisper-large-v3-turbo | a transcript written before the run | word for word |
| upscaler | real-esrgan-x4 | the 1792x1792 image, looked at | sharp, coherent |
| video | CogVideoX-2b | the frames, looked at one by one | coherent at 9, 13, 17 |
For NeuroBrix Studio
Checked by reaching the code, not by reading the request list.
Delivered
--jsonon every read command —info,list,hub,inspect,coverage,
doctor,autotune status,autotune check,run --explain-plan. Exactly one
JSON record on stdout (schemaneurobrix.<command>/<version>plusengine),
every human line on stderr, so stdout can be piped without filtering. Contract:
docs/reference/json-output.md.- Discovery without loading a model —
neurobrix info --jsonand the daemon's
statusshare one identity record: engine, protocol, endpoint, operations. - A compatibility handshake — every response envelope carries
protocol
(currently 1) andengine, so a client refuses an engine it does not know. - The install lifecycle stays in the engine — NDJSON phases with real byte
counts, and an install that cannot leave a half-written model behind: a per-model
lock, a staging tree carrying host and pid, and a swap done in one syscall where
the kernel allows it.
Still open, and not promised here
- Decoded text deltas: the stream emits
{"step","n","token","done"}with a token
ID, not decoded text. - Acknowledged cancellation: there is no cancel operation.
- A daemon responsive during inference: the server accepts one connection at a time.
- Windows instance isolation:
NBX_SOCKET_PATHisolates the Unix socket; the
default Windows loopback port is still fixed.
Upgrading
Nothing in the .nbx container format changed, and no model was re-traced for this
release, so your existing containers work unchanged and nothing needs re-downloading
from the hub.