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 introduces the native-wheel contract below, replacing the pure Python packaging of v0.5.1. 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 v0.5.2 once it appears on the release page:

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

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.2
File Size Uploaded Provenance Actions
swage_compiler-0.5.2.tar.gz 1.0 MB With provenance Details for swage_compiler-0.5.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for swage-compiler 0.5.2
File Actions
swage_compiler-0.5.2-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.2-cp313-cp313-manylinux_2_28_x86_64.whl
swage_compiler-0.5.2-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.2-cp312-cp312-manylinux_2_28_x86_64.whl
swage_compiler-0.5.2-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.2-cp311-cp311-manylinux_2_28_x86_64.whl
swage_compiler-0.5.2-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.2-cp310-cp310-manylinux_2_28_x86_64.whl

Total release size: 200.8 MB

Release files / swage_compiler-0.5.2.tar.gz

Download URL swage_compiler-0.5.2.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums
27eeed71d24b058253b6e77a6bf66eefe03377e33214fe13cee25101e8f10708
BLAKE2b-256 checksum
How to use checksums
475ec1d38b9bf49ab60aee29b5b1427bd23bc08cec41eec35f683e46bde6b41d
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 7, 2026.

Transparency log

Release files / swage_compiler-0.5.2-cp313-cp313-manylinux_2_28_x86_64.whl

Download URL swage_compiler-0.5.2-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
5c3abda981ab6f0577d55476d11800d4b6764466a388cf6cef26508531b913a5
BLAKE2b-256 checksum
How to use checksums
6287fe79702634f8fca6b5fcc47d880a4867c3f6acd930e4e2c6c53b642f2538
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 7, 2026.

Transparency log

Release files / swage_compiler-0.5.2-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL swage_compiler-0.5.2-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
eed70624abcbde6f06163efd4aece14a27a6e93383504e22a2fc89dd8572722e
BLAKE2b-256 checksum
How to use checksums
aed1f8e49653100f107b480d4953a85d9645a76efeafcbcbb85c5616d564a0a5
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 7, 2026.

Transparency log

Release files / swage_compiler-0.5.2-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL swage_compiler-0.5.2-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
ed4701337d9dd14bbca52dda8fa23fe1095a671d1370637f8820692177ce1b24
BLAKE2b-256 checksum
How to use checksums
7a9c31a62662b2df746ea382494faa9c52fbbc2f3d39ea445ab2eaeb9d14a249
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 7, 2026.

Transparency log

Release files / swage_compiler-0.5.2-cp310-cp310-manylinux_2_28_x86_64.whl

Download URL swage_compiler-0.5.2-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
858e345e1e8cad23f1b2aa31be7c4c687924d8a4b1c7ffa5687325ef827ca93c
BLAKE2b-256 checksum
How to use checksums
0fc7c3015d6b09920685b57d76d7076fa43f8e82a83d3dae91a165d04f5cd6f3
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 7, 2026.

Transparency log

Security for swage-compiler 0.5.2

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.2.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 7, 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