raptor

raptor: one manifest, any engine

A compiled GPU kernel ships with a small JSON file that says what it takes, what it returns and where it can run. raptor defines that file, so one package can build a kernel and another can run it.

Runs on: CPU, no GPU needed · You need: Python 3.9+, nothing else to install raptor itself

The RAPTOR family

raptor holds the shared contracts of the RAPTOR family: the manifest format and certification contracts that let a kernel built once work with the code you already have. See where RAPTOR fits for how the four pieces combine.

See it working: orbits from hand-written physics plus a small learned drag correction, trained in torch and compiled into one kernel — Demos points to the runnable examples.

Docs · the family site

For package authors

from raptor.schema import validate_manifest

manifest = {
    "schema_version": 2,
    "pattern": "pure",
    "aether_abi": "aether-abi/2",
    "exec_targets": ["host", "device"],
    "exec_access": "sample_local",
    "plugins": [{"id": "two_body_step", "order": 0, "enabled": True, "artifact": "two_body_step.ptx",
                "sidecar": "two_body_step.json", "format": "ptx"}],
}
validate_manifest(manifest)  # raises on a malformed or out-of-order document

Any class with a matching build(directory) method satisfies ManifestProvider — "duck typing": judged by which methods exist, checked with isinstance, never by which class it inherits from:

from raptor.protocols import ManifestProvider

class Bundle:
    def build(self, directory):
        return f"{directory}/manifest.json"

isinstance(Bundle(), ManifestProvider)  # True — duck-typed, no inheritance needed

Threading

Free-threaded CPython (3.13t/3.14t) is supported: the compiled modules declare GIL-free operation and the GIL stays disabled after import. Any number of threads may call module-level functions, build, compile, plan and cache concurrently. Distinct objects may be used from distinct threads without synchronisation. One stateful object (a stream, capture, launcher, graph, composer, plan, pipeline, active set, host kernel or arg block) shared by several threads is memory-safe — its calls serialise and a consumed object raises — but the ORDER of those calls is the caller's responsibility, exactly as for a NumPy array or a CuPy stream. CUDA adds two rules of its own: a stream capture is begun, filled and ended by one thread, and while any capture is open no thread may synchronise the whole device (stream-level synchronisation is fine). GPU routes are supported on free-threaded 3.14; on 3.13t the CPU route runs.

Install

pip install raptor-core      # Python 3.9+, no dependencies

The import name is raptor. The rest of the family (hawk, eagle) and the GPU extras: installation.

To work on the code, from a clone: git clone https://github.com/amasat01/raptor.git, then pip install -e .. Test with pip install pytest && pytest tests -m "not cross_repo" (-m "not cross_repo" leaves out the tests that check eagle against raptor's contracts — they need an eagle checkout next to this one, and fail rather than skip without it). To set up a development machine for the whole family, see tools/devbox/.

Demos

The runnable demos live with the packages they show off:

• hawk: the hybrid orbit (analytic physics plus a learned correction in one compiled kernel) and autodiff against torch.
• eagle: early termination with a conditional graph node, and zero-copy interop with NumPy, CuPy and PyTorch.

The measured headline, from eagle's committed performance cards:

hawk + eagle (eagle.simulate) integrates 1,000,000 RK4 oscillators, each stopping at its own step, in 613 µs on an NVIDIA H100 80GB HBM3 (199 µs for 100,000), 2.5×–600× faster than NVIDIA Warp (2.5×), JAX (76×), CuPy (600×), PyTorch with torch.compile (130×) at N = 1,000,000 (1.1×–1700× at N = 100,000), in 40 MiB of GPU memory

Going deeper (optional)

Package internals, none of it needed to install or use raptor.

hawk write it · eagle run it · aether the numerics core · raptor the shared contracts (this repo) — the RAPTOR family

Apache-2.0 (see LICENSE and NOTICE) · cite via "Cite this repository" (CITATION.cff; every tagged release is archived on Zenodo: doi:10.5281/zenodo.23250234) · built to make GPU computing accessible on modest hardware, for research and education. Collaboration is the point, and a citation is the currency — get in touch.