oapython 0.7.0

OA — Vulkan GPU compute & ML foundation library (SUPER EXPERIMENTAL Python bindings)

OA — Realm Foundation Library

Vulkan 1.4 compute substrate. Types, memory, GPU engine, ML primitives, crypto. Shaders in Slang. No CUDA. No ROCm.

Quick Start

#include <Oa/Oa.h>                 // Everything
#include <Oa/Runtime/Engine.h>     // Compute engine only
#include <Oa/Core/Memory.h>        // e.g. AVX2 memcpy

int main() {
	auto rt = OaEngine::Create({.AppName = "MyApp"}).Unwrap();
	// ...
	rt.Destroy();
}

Install

Arch Linux (AUR)

Prebuilt (fast — pulls the release binaries):

yay -S oa-bin oa-sdk-bin        # or: paru -S oa-bin oa-sdk-bin

Or build from source (tracks the latest tagged release):

yay -S oa-git oa-sdk-git

oa-bin/oa-git install the runtime library; the -sdk-* packages add the headers, CMake config, and shader sources needed to build against OA.

Other Linux

Download from the latest release — a universal tarball plus .deb / .rpm / .pkg.tar.zst:

tar -xzf oa-<ver>-linux-x86_64.tar.gz -C /usr/local          # runtime
tar -xzf oa-sdk-<ver>-linux-x86_64.tar.gz -C /usr/local      # + dev files

The .deb / .rpm are convenience prebuilts and require glibc ≥ 2.39 (Ubuntu 24.04+ / Debian 13+ / Fedora 39+). Verify with sha256sum -c SHA256SUMS.txt.

Python (super experimental)

pip install oapython        # import oa

Build

cmake --preset release && ninja -C Build/Release
cd Build/Release && ctest --output-on-failure
cmake --install Build/Release --prefix ~/.local

Consumers link via vcpkg (find_package(oa CONFIG REQUIRED)) or CMAKE_PREFIX_PATH.

Layout (golden rule)

Public API lives under Source/Public/Oa/ (installed as #include <Oa/...>). Implementations and internal-only code under Source/Private/Oa/. Tests under Test/. On-disk public headers use PascalCase (e.g. OaVk.h, OaVma.h, Engine.h).

oa/
├── Source/Public/Oa/       # <Oa/Oa.h>, <Oa/Core/*.h>, <Oa/Runtime/*.h>, …
├── Source/Private/Oa/      # .cpp/.c, internal headers, Slang under Ml/Shaders/, Vma/, …
├── Test/
├── Apps/
└── CMakeLists.txt

Vulkan loader and allocator: Source/Private/Oa/Runtime/OaVk.c, OaVma.cpp (implementation); public headers Source/Public/Oa/Runtime/OaVk.h, OaVma.h.

Documentation

• Docs & guides: dev.realm.software
• Project home: realm.software
• Docs/Release.md — release-readiness status and roadmap (in-repo)

Supported hardware

Hardware	Status	Notes
NVIDIA (Turing+)	Full	bf16 cooperative-matrix tensor cores; CoopVec GEMV decode on Blackwell+
AMD RDNA3+ (RADV or proprietary)	Full	KHR cooperative-matrix bf16; RADV trusted on all gens
Intel Xe2+ (Lunar Lake / Battlemage)	Full	native coopmat + bf16
Intel Xe pre-Xe2 (Tiger Lake etc.) / other iGPU	Compute (fp32)	coopmat + native bf16 auto-disabled (driver-trust gated); tiled fp32 path
CPU (lavapipe / SwiftShader)	Works, slow	for CI and correctness testing, not performance

Cooperative-matrix and native bf16 are gated by a vendor/driver trust check (some drivers advertise support they miscompile). Override with OA_FORCE_COOPMAT=1 / OA_FORCE_BF16=1, or force them off with OA_DISABLE_COOPMAT=1 / OA_DISABLE_BF16=1. Bindless buffer capacity is capped per device (1M discrete / 256K integrated) and overridable with OA_BINDLESS_BUFFER_CAP=N.

Benchmarks — Python at C++ throughput

The nanobind bindings call the same compute kernels as the C++ engine, so the Python API pays no measurable tax. Byte-level NLP training, identical models, same Intel Xe iGPU:

Model	Python wall/step	C++ wall/step	Accuracy (Py / C++)
RNN	5.53 ms	6.77 ms	93.5 / 93.5
GRU	9.78 ms	14.58 ms	93.3 / 94.3
GRU (char)	9.03 ms	14.62 ms	93.5 / 94.2
Transformer	12.59 ms	19.71 ms	91.8 / 94.0
Mamba-3	27.21 ms	49.00 ms	92.8 / 93.8

Both suites are GPU-bound on identical dispatch sequences; the nanobind layer is ~100 ns/call, negligible against GPU-op latency. Wall-time gaps track async pipelining, not the binding. (Single run, n=5, iGPU GPU-timer sampling is ±20% indicative — read this as parity, not a Python-beats-C++ claim.)

Status & limitations (0.7 preview)

This is a preview. The following are experimental (may be unstable; off by default):

• bf16 on drivers outside the trust list (auto-routes to fp32 unless forced)
• Bidirectional SSM scan in MaskedTokenModel / EmpyrealmGen3dAnim (training-unstable; warns at runtime)
• SSM models (Mamba-3, Empyrealm) and the generative training apps (MotionGPT / Gen3dAnim) — demo-quality
• Vulkan Video decode (H.264 / H.265 / AV1) — functional, some tails + benchmarks not finished
• Python bindings (nanobind) — super experimental, OA_BUILD_PYTHON=OFF by default. Preview wheels publish to PyPI as oapython (pip install oapython; import stays import oa). Expect breakage — this is a tech preview, not a supported API.

Not in this preview (present but return an explicit error, not silently wrong):

• Multi-node distributed (OaCluster Send/Recv) — single-machine multi-GPU collectives work; cross-node returns Unimplemented
• MoE training — runs, but expert-FFN backward gradients are not precision-verified (don't rely on it for training)
• Video encode / transcode (OaVideoTranscoder) — returns an error

Test coverage is ~62% of ops. See Docs/Release.md for the full gap analysis.

License

Business Source License 1.1. Copyright (c) 2025-2026 Lukasz Biernat (trading as Realm).

Source-available: you may read, copy, modify, and make non-production use freely. Production use is permitted except offering OA as a competing commercial ML/GPU-compute/inference product or service (see the Additional Use Grant in LICENSE). Each version converts to Apache-2.0 four years after its release (Change Date 2030-07-09 for this one). For a commercial license, contact [e-mail].

Third-party trademarks and interop-data attributions (Epic Games MetaHuman / Unreal, Autodesk HumanIK / FBX, etc.) are recorded in NOTICE.md.

Support OA

OA is independent, self-funded work. If it's useful to you, funding helps keep development moving.

• GitHub Sponsors: github.com/sponsors/empyrealm
• Bitcoin (BTC): bc1q732ytlwnmwys2at4wyd46zewj20n3s55xwq5yt
• USD Coin (USDC, ERC-20 / Ethereum): 0x23Efe433cd0476b2d126120fEf4C1c5903b02250

Acknowledgments

OA stands on some excellent permissively-licensed work. In particular:

• volk by Arseny Kapoulkine (MIT) — OA's Vulkan function loader (OaVk) is a hard fork of it. A genuinely great piece of software.
• Vulkan Memory Allocator by AMD (MIT) — OA's GPU allocator (OaVma) is vendored from it.
• GLM (MIT), miniaudio by David Reid (public domain / MIT-0), and stb by Sean Barrett (public domain).

Full license text and per-component details are in NOTICE.md.