Swage
Turn variable-sized dense segments into efficient GPU tile tasks.
Swage is an experimental Python-embedded MLIR/LLVM compiler with a
deliberately narrow public execution contract in two parts: the canonical
fixed vector add and multiply, launched on an explicitly selected CPU or CUDA
backend, and two segmented calls, swage.segment_reduce and
swage.segment_softmax, which run fixed programs over variable-sized
segments on one CUDA device. Everything else, including segment programs
that a caller writes, is private research: it is not public API, and it may
change or go away.
Current capability boundary
Version v0.5.2 introduced the native-wheel contract below, replacing the
pure Python packaging of v0.5.1. The v0.5.3 candidate updates build and
CI dependencies without changing compiler or runtime behavior. Check the
release page for published
artifacts. Release qualification requires the installed-wheel gates;
source changes alone do not establish it.
Public today
- Fixed vector add and multiply. Canonical fixed vector add and multiply
are the only kernels the kernel language launches. Contiguous rank-one
tensors may use
float32,float16,float8_e4m3fn, orfloat8_e5m2; both inputs and the output must match. Low-precision arithmetic widens to FP32 and rounds back to the storage dtype, and FP8 conversion runs in the compiled kernel, including onsm_86. A kernel contains exactly onex + yorx * yvalue operation; chains, floating vector and scalar arithmetic, broadcasting, and matrix multiplication are not accepted. - Compile-only emission. The restricted Python frontend emits verified
MLIR through the native bindings that the
v0.5.2wheel bundles, with no GPU and no PyTorch. - Explicit backends.
kernel.launch(..., backend="cuda")lowers through LLVM NVPTX and enqueues through the CUDA Driver API on the current PyTorch stream.kernel.launch(..., backend="cpu")lowers the same program to a synchronous, process-local Native LLVM JIT entry for CPU tensors. Selection is explicit and fail-closed: no backend falls back to the other. - Segmented reduction.
swage.segment_reduce(values, offsets, kind, *, out=None)returns the sum, maximum, minimum, or mean of every segment, overfloat32orfloat64values. - Segmented softmax.
swage.segment_softmax(values, offsets, *, out=None)returns the softmax within every segment, overfloat32values only: the device has no 64-bitexp2, sofloat64is refused. - Ahead-of-time artifacts.
python -m swage.compile --target <processor> --output <directory>writes the kernels of both segmented calls for one NVPTX processor without a GPU. A process that setsSWAGE_ARTIFACT_DIR=<directory>runs the two calls from that directory with no compiler loaded. The artifact runtime library is built for Linux x86-64 only. - Diagnostics.
python -m swage.env --jsonreports the environment, and--check native,--check cpu, or--check cudaexits non-zero when the selected component is unavailable.
Both segmented calls take values of rank one, or [N, D] rows that are
reduced or normalized per column (a reduction of [N, D] values returns
[S, D] for S segments). They take int32 or int64 offsets, with fewer
than 2**31 rows and fewer than 2**31 segments. They share these limits:
- They run on the current CUDA device only.
- They record a gradient for values that require grad, including second
derivatives;
out=is refused while a gradient is recorded. - They are refused under CUDA graph capture.
- They validate and classify the offsets on the host at every call. The
pytorchextra declaresnumpyfor this. - An empty segment gives the identity of its kind: a sum of
0, a maximum of negative infinity, a minimum of positive infinity, and a mean of NaN.
With offsets that change on every call, the committed record at 2cf88ae
on one RTX A6000 finds a reduction slower than torch.segment_reduce on
rank-one values and on [N, D] values whose segments have at most 32 rows,
and faster on most [N, D] rows with longer segments;
Benchmarks
reports it beside the older record at c6099ec.
Segmented Calls states the contract
and the cost, and
Running Without the Compiler states what an
artifact holds and when it is refused. The swage dialect and swage-opt
are available to compiler contributors through source builds.
Private qualification
Everything outside the public list is private research. The two segmented calls run fixed programs through part of this machinery with default limits and expose none of its controls.
- Canonical segmented sum, max, and stable ragged softmax run through sequential CPU oracles and one-CTA GPU paths.
- Capture-free, single-stage sum, max, and min programs over f32 or f64 values, including element expressions and map chains, run through host classification, direct warp and CTA work, one fused mixed kernel, and split-CTA partial and merge kernels. Prepared launches and split-CTA and mixed schedules chosen by hand stay private.
- A persistent task queue for the identity sum has correctness evidence, but its predeclared performance gate failed; it is neither qualified nor public.
- The planner and its passes, the
swage-optflags, and everything underswage._*are private.
The frozen NVIDIA RTX A6000 sm_86 mixed-policy record has a
mixed-to-best-pure ratio of 0.939394, below its predeclared 1.05 limit.
Exact and nontrivial f32 split sums match PyTorch and the CPU oracle on the
same GPU. Task Execution and
Benchmarks give the records and their
limits.
Planned
- Public segment syntax, and public launch of a segment program that the caller writes.
- Packing several short segments into one warp, split softmax, reusable device queues, qualified persistent scheduling, and broader policies.
Private qualification is not a public segmented runtime: the public calls expose two of its programs and none of its controls. Current status is backed by the repository's executable tests and committed benchmark records.
Native wheel and source builds
The v0.5.2 distribution, swage-compiler, is one native wheel per
CPython version, 3.10 to 3.13, for Linux x86-64 with glibc 2.28 or newer
(manylinux_2_28). Each wheel holds public swage with its type stubs, the
private mlir_swage compiler bindings, the libSwageRuntime.so runtime
library, and the private segmented modules that the two public calls
import. It needs no external MLIR installation and no CUDA toolkit compiler
at runtime. PyTorch is optional (torch>=2.6,<3 through the pytorch
extra, which also declares numpy). There are no macOS, Windows, musl,
other-architecture, or free-threaded wheels.
The release workflow checks CPU execution on every wheel ABI. The
continuously qualified CUDA configuration is the NVIDIA RTX A6000 (sm_86).
On that GPU, the release gpu job and the fixed-runtime-slo job of the
GPU workflow are configured to qualify the segmented calls and the artifact
path from the installed wheel with scripts/qualify_installed_segments.sh.
Other admitted NVIDIA targets are best effort.
The released 0.5.1 wheel on PyPI is pure Python. It has no native
bindings, no CPU backend, no multiply or low-precision dtypes, no segmented
calls, and no artifact path.
Installation lists the differences.
To install the published v0.5.2 release:
python -m pip install --only-binary=swage-compiler "swage-compiler[pytorch]==0.5.2"
python -m swage.env --json --check native
python -m swage.env --json --check cpu
# With a CUDA-enabled PyTorch build and an NVIDIA driver:
python -m swage.env --json --check cuda
Choose the backend explicitly. An unavailable backend raises
swage.BackendUnavailableError and never probes the other one. The
Quickstart walks through the
canonical kernels and the segmented calls. The
runtime environment reference
defines the build identity and the environment report, and
Troubleshooting lists the error
codes.
Until then, a native wheel is built from a clean checkout against the pinned LLVM, as the GPU workflow builds it. Installation gives the full command:
python -m build --wheel --no-isolation -Cbuild-dir=<build directory> \
-Ccmake.define.MLIR_DIR=<LLVM install>/lib/cmake/mlir \
-Ccmake.define.LLVM_DIR=<LLVM install>/lib/cmake/llvm \
-Ccmake.define.SWAGE_SOURCE_REVISION="$(git rev-parse HEAD)" \
-Ccmake.define.SWAGE_SOURCE_CLEAN=true
The wheel also ships python -m swage.bench vector-add --output result.json
for the frozen CUDA vector-add benchmark. The
benchmark CLI contract gives its
prerequisites, raw evidence, and --enforce; this command alone does not
qualify a release.
Compiler contributors can instead build exactly llvmorg-22.1.8 and use
the build tree:
python -m pip install --upgrade pip
python -m pip install -e ".[dev]" -Cwheel.cmake=false
./scripts/fetch_llvm.sh
LLVM_SRC="${SWAGE_LLVM_HOME:-$HOME/.swage/llvm}/src-$(cat cmake/llvm-version.txt)"
python -m pip install -r "$LLVM_SRC/mlir/python/requirements.txt"
./scripts/build_llvm.sh
./scripts/build_swage.sh
ninja -C build check-swage-python
Source builds keep build/python_packages/mlir_swage, which a script uses
through PYTHONPATH=build/python_packages. The frontend-only editable
install captures kernels and reports the environment, but does not emit or
launch without those bindings. Source distributions and the frontend-only
editable install need no CMake.
Installation gives the build
requirements and explains the health checks.
Examples
Four committed examples run from the installed wheel, or from a source
build with PYTHONPATH=build/python_packages:
examples/emit_fixed_vector_add.pyemits MLIR and needs no GPU and no PyTorch.examples/fixed_vector_add.pyandexamples/fixed_vector_multiply.pylaunch the fixed kernels and take--backend cpu|cudaand--dtype.examples/segment_reduce.pyruns both segmented calls on a CUDA GPU and compares every result with PyTorch:
import swage
import torch
# Six values in four segments: [1, 2], [], [3, 4, 5], and [6].
values = torch.tensor([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], device="cuda")
offsets = torch.tensor([0, 2, 2, 5, 6], dtype=torch.int32, device="cuda")
totals = swage.segment_reduce(values, offsets, "sum") # [3, 0, 12, 6]
weights = swage.segment_softmax(values, offsets) # six weights
The support matrix lists which Python, PyTorch, driver, and GPU combinations are tested.
Documentation
- Installation
- Quickstart
- User Guide, including Segmented Calls and Running Without the Compiler
- API Reference
- Support Matrix
- Compiler Pipeline
- Internals
- Verification
- Design, Roadmap, and Contributing
License
Swage source: MIT. Native wheels also redistribute LLVM under Apache-2.0 with LLVM exceptions and the other third-party code that THIRD_PARTY_NOTICES.md lists.
Metadata
Release files for swage-compiler 0.5.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| swage_compiler-0.5.3.tar.gz | 1.0 MB | With provenance | Details for swage_compiler-0.5.3.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| swage_compiler-0.5.3-cp313-cp313-manylinux_2_28_x86_64.whl | CPython 3.13 | CPython 3.13 | Linux glibc 2.28+ x86-64 | Details for swage_compiler-0.5.3-cp313-cp313-manylinux_2_28_x86_64.whl |
| swage_compiler-0.5.3-cp312-cp312-manylinux_2_28_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.28+ x86-64 | Details for swage_compiler-0.5.3-cp312-cp312-manylinux_2_28_x86_64.whl |
| swage_compiler-0.5.3-cp311-cp311-manylinux_2_28_x86_64.whl | CPython 3.11 | CPython 3.11 | Linux glibc 2.28+ x86-64 | Details for swage_compiler-0.5.3-cp311-cp311-manylinux_2_28_x86_64.whl |
| swage_compiler-0.5.3-cp310-cp310-manylinux_2_28_x86_64.whl | CPython 3.10 | CPython 3.10 | Linux glibc 2.28+ x86-64 | Details for swage_compiler-0.5.3-cp310-cp310-manylinux_2_28_x86_64.whl |
Total release size: 200.8 MB
Release files / swage_compiler-0.5.3.tar.gz
| Download URL | swage_compiler-0.5.3.tar.gz |
|---|---|
| Size | 1.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
10da7304c5a08e5b45daab75ae331e711499d269539d315139473920592f0c6e
|
|
BLAKE2b-256 checksum How to use checksums |
e2987023f23942e2876c335c98a4771bfca50f08777ef778176cea5ff9cf63e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logRelease files / swage_compiler-0.5.3-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | swage_compiler-0.5.3-cp313-cp313-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 49.9 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
190534c35482c372f87aae1310fcb329f0947108a569e1ad0bdf7383bf8944a8
|
|
BLAKE2b-256 checksum How to use checksums |
30b0841f48c8234afbb68b79935d9ccd0877465dfa317a0543ab094ed166e819
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logRelease files / swage_compiler-0.5.3-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | swage_compiler-0.5.3-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 49.9 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
ad19e083a0708cdbc3bd0e7e4f05dcec3e5c1b72ce47ade71452555df0414a98
|
|
BLAKE2b-256 checksum How to use checksums |
4549f01989a8adc51d87f75cc57a5ef1e2a055eaafc5a12776dd52aaf5c71e09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logRelease files / swage_compiler-0.5.3-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | swage_compiler-0.5.3-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 49.9 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
72e53be2a23aa1aa595d447aff31c19ee485aa63c5ac8fb93c6dc39feb1b5333
|
|
BLAKE2b-256 checksum How to use checksums |
7ea65f26c0072a7d7d84896c94c0e087af408f645556a6f9f96dd3fc07255bf3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logRelease files / swage_compiler-0.5.3-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | swage_compiler-0.5.3-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 49.9 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
cfb7e5ec42eddb5aae3e12c284a7491682cda528abda33f6aba75b3a0d9192bd
|
|
BLAKE2b-256 checksum How to use checksums |
9fef1275287829fd716424409ab06fef00323b27eed0b52c82ec1bf94871b805
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logSecurity for swage-compiler 0.5.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 5 files in this release have been uploaded with provenance metadata.
Attestation for swage_compiler-0.5.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.