Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
OA
GPU-first semantic computing in Rust. Compute, ML, media, and presentation on Vulkan behind one explicit Engine.
OA is an experimental, executable engine: typed values and domain operations
build on one owner of devices, memory, queues, scheduling, kernels, and
profiling without exposing backend machinery through the public API. The
Cargo package is oarust; the library and Python import namespace are
oa.
This repository is the primary OA implementation. The earlier C++ codebase continues separately as the donor and compatibility reference. OA is a preview: capability claims are tied to the compatibility ledger, independent oracles, and recorded hardware evidence rather than to API surface alone.
Install
[]
= "0.14"
Rust code uses use oa::...; Python uses import oa.
A few lines of compute
use matrix;
let one = ones?;
let two = full?;
let total = add?;
assert_eq!;
# Ok::
No Engine value appears: each thread has a lazy default engine that owns
the device work. Python resolves the same default:
=
=
=
assert == * 6
Default and explicit engines
Every engine-first value constructor ships in a pair. The short form resolves
the thread's default engine; the _on form selects one explicitly.
Engine::set_default(engine) is the multi-device path: install the node's
engine once per thread and ordinary calls resolve to it.
| Purpose | Defaulted | Explicit engine |
|---|---|---|
| Allocate | matrix::ones(shape) |
matrix::ones_on(&engine, shape) |
| Upload | Matrix::new_from_f32(shape, data) |
Matrix::new_from_f32_on(&engine, shape, data) |
| Layer | nn::Linear::new_with_seed(in, out, seed) |
nn::Linear::new_with_seed_on(&engine, in, out, seed) |
| Decode | audio::decode_file(path) |
audio::decode_file_on(&engine, path) |
Operations on existing values infer their owner from storage and never take
an engine. Sessions—training, capture, codec, presentation—keep an explicit
&Engine: ownership is part of their contract, not a convenience.
Python uses the same convention with an optional trailing engine keyword
instead of _on: oa.matrix.ones([2, 3]) or
oa.matrix.ones([2, 3], engine=engine), and oa.Engine.set_default(engine)
installs the thread's default.
What works today
Checked vertical slices include:
- Vulkan device selection constrained to the compiled Core 1.3 or bounded Compatibility 1.2 profile, VMA-backed storage, profile-specific descriptors, asynchronous retirement, timeline events, eager batching, semantic capture, immutable execution plans, replay, rebinding, hazard analysis, and Vulkan timestamp evidence;
- schema-owned Matrix elementwise, reduction, indexing, RNG, transpose, gather, tiled FP32 matrix multiplication, broadcasting, and reverse-mode operations;
- ML modules, autograd, Adam/AdamW/SGD/Muon, training iterators, callbacks, checkpoints, RNN/GRU/Transformer/MoE/Mamba-3 NLP tutorials, reinforcement learning, VQ, and the in-progress Animation Language Model stack;
- Image operations and codecs, planar Audio and codecs/DSP/sessions, Video containers/decoding/encoding, Vision detection/metrics, Render value foundations, cryptographic hashes/Merkle/PQC, secure memory, and Vulkan batch hashing;
- native PyO3 bindings for Engine/Event, typed dense Matrix construction and operations, the functional ML spine, Image codecs/transforms, Audio codecs/DSP/features, metadata, and explicit synchronized host observation.
No GPU operation is classified as stable yet.
Architecture
semantic values and operations
│
▼
semantic operation graph
│ private lowering
▼
executable Vulkan graph
│
▼
Engine-owned queues, memory, events, profiling
- Values carry semantics; shared storage does not erase type identity.
- Operations are stateless. Stateful external or iterative work is a session.
- The semantic graph stays separate from executable backend work.
- Eager operations return values; explicit submit/wait is reserved for capture, orchestration, profiling, multi-device, and distributed work.
- One operation schema owns derivable Rust, Python, validation, autograd, registry, documentation, and test surfaces.
- Slang kernels are embedded in the binary; runtime users do not ship loose
.spvfiles.
Distribution names
The project and API namespace are oa. The language-specific distribution
names are oarust on crates.io and oapython on PyPI; Python uses import oa.
The crate contains the library and its required build inputs, including the
source support modules exposed through oa::sdk. Runnable SDK programs are
separate release downloads; they are not part of the registry package.
Tagged CI verifies and publishes both packages, the SDK executables and native
Linux packages, source and Rust API documentation archives, and checksums.
The old oarust 0.0.1 package is a documentation-only name reservation.
Build
Requirements: Rust 1.98, Python 3, rustfmt, CMake, slangc 2026.14,
spirv-val, native audio/window-system development libraries, and a compatible
Vulkan driver. The default Core build requires Vulkan 1.3 and the required
bindless features. An explicit Compatibility build supports admitted Vulkan 1.2
devices with bounded bindings. Compatibility presentation is
not yet qualified. Linux builds use Clang/LLD for native linking while rustc
and LLVM compile Rust. SDL3 builds statically from the pinned Cargo source
by default (bundled-sdl); --no-default-features uses system SDL3 instead.
The compact media applications share OA's GPU viewer:
oa record previews the selected camera; Space or the on-screen controls
record and finish, Ctrl+S saves a copy under Videos/OA. The first camera route
requires hardware H.264 encoding and records video without microphone audio.
Camera and screen previews share the GPU 2D canvas—drag to pan, Ctrl+wheel to
zoom, 1–5 for channel views. oa capture records a desktop-selected screen
through the portal/PipeWire route; DMA-BUF zero-copy capture remains planned.
For older hardware, use OA_BUILD_PROFILE=compatibility cargo build --release.
Each build compiles and embeds one shader catalog and one binding backend;
the variable selects at compile time, not runtime.
The repository workflow stages executables under bin/<profile>/:
--python creates the repository-root .venv, installs Maturin, and installs
the matching native extension.
Python preview
Python follows the Rust module graph directly, with the engine explicit:
The native PyO3 implementation lives in src/py/pyo3, the importable oa
package in src/py/oa, and Python tutorials in sdk/py. Neither creates a
second runtime or CPU implementation.
Release artifacts
Every public release is assembled by the tagged CI workflow and publishes:
- an exact Rust source archive with the resolved
Cargo.lock; - a Linux x86-64 SDK archive containing the runnable tutorials, benchmarks, and applications staged from the same Release build;
- matching
oa-sdkpackages for Debian, RPM, and Arch Linux; - one portable CPython 3.10+ ABI3 wheel, published to PyPI and then downloaded back from PyPI before attachment to GitHub;
- dependency and toolchain evidence plus one checksum manifest covering every downloadable artifact.
The Rust crate currently links into its consumers and does not expose a stable C ABI; the Python wheel contains and tests its native ABI3 extension. GitHub-hosted validation proves the host and compilation contracts. Tests that require a real GPU remain explicit capability gates and are not silently reclassified as CPU-Vulkan validation.
Verification
Hardware tests are explicitly ignored by the default harness and run serially on admitted devices. See test organization.
SDK and source reference
OA is licensed under the Business Source License 1.1. See LICENSE.