Skip to main content

Swage logo

Swage

ci-python ci-cpp GPU runtime

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, or float8_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 on sm_86. A kernel contains exactly one x + y or x * y value 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.2 wheel 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, over float32 or float64 values.
  • Segmented softmax. swage.segment_softmax(values, offsets, *, out=None) returns the softmax within every segment, over float32 values only: the device has no 64-bit exp2, so float64 is 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 sets SWAGE_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 --json reports the environment, and --check native, --check cpu, or --check cuda exits 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 pytorch extra declares numpy for 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-opt flags, and everything under swage._* 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.py emits MLIR and needs no GPU and no PyTorch.
  • examples/fixed_vector_add.py and examples/fixed_vector_multiply.py launch the fixed kernels and take --backend cpu|cuda and --dtype.
  • examples/segment_reduce.py runs 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

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)

Source distribution for swage-compiler 0.5.3
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)

Table of built distributions (wheels) for swage-compiler 0.5.3
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 5 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page