Zirium

Zirium 0.0.9 is an experimental release. The API may change without a migration path.

Zirium is a Rust library for reading, inspecting, transforming, and writing textual MLIR. It also provides typed Python bindings. The parser keeps the original bytes, including comments, whitespace, malformed syntax, and invalid UTF-8. A separate semantic layer provides a compact representation for verification and editing.

The project is useful when a tool needs to understand MLIR without linking LLVM, and when source fidelity matters alongside semantic processing.

Zirium currently targets the textual syntax of MLIR 22.1. It has a deliberately narrow dialect surface and is not a replacement for all of MLIR's parser or ODS infrastructure.

The current release is intended for experimentation, tooling prototypes, and evaluation of the lossless syntax/semantic split. It does not promise broad dialect coverage, bytecode support, ODS/TableGen loading, or a stable API.

Command-line utility

The zirium binary queries and edits textual MLIR. Pass the query first, followed by any input files. With no input files, it reads from standard input. For example, this selects every arith.addi operation in input.mlir:

zirium 'filter(op("arith.addi"))' input.mlir

The query language reference lists every predicate and pipeline stage. The CLI examples show complete queries, dependency slices, and edits.

You can also run the binary from a source checkout with Cargo:

cargo run --quiet --bin zirium -- \
  'filter(op("arith.addi"))' input.mlir

What it provides

• A byte-oriented lexer and lossless concrete syntax tree (CST).
• Recovery from malformed input with ranged diagnostics and useful outer structure.
• Stable machine-readable categories on semantic diagnostics.
• Standard module handling and caller-provided func-like and call-like operation shapes.
• Structural recovery of unknown custom operations, including nested regions, SSA declarations and uses, and trailing attribute dictionaries.
• Strict and best-effort lowering into a separate semantic document.
• Operations, regions, blocks, SSA values, types, attributes, locations, symbols, and dominance queries.
• Python inspection of exact type and attribute spellings, scalar attributes, and stable value identity.
• Form-independent operation roles for symbol names, signatures, and callees.
• Deterministic generic MLIR output and structural round-trip comparison.
• Buffered semantic edits that commit atomically.
• Conservative source-preserving output for documents lowered with hybrid retention.
• Rust and Python APIs over the same core implementation.
• Explicit limits for file size, token count, nesting, and large payloads.

A small example

import zirium

source = '''\
"builtin.module"() ({
  %value = "example.make"() : () -> i32
  "example.consume"(%value) : (i32) -> ()
}) : () -> ()
'''

parsed = zirium.parse_text(source)
assert parsed.original_bytes() == source.encode()

lowered = parsed.lower_strict("semantic")
if lowered.document is None:
    for diagnostic in lowered.diagnostics:
        print(diagnostic.range, diagnostic.message)
    raise SystemExit(1)

document = lowered.document
document.validate_structure()
table = document.operation_table()
print([table.operation(index).name for index in range(table.count)])
print(document.canonical_bytes().decode(), end="")

Parsing and lowering are separate on purpose. A File owns the original bytes, tokens, CST, and syntax diagnostics. A Document owns resolved semantic data. This keeps malformed-source tooling from depending on a partly valid semantic model, while transformation code does not have to operate on syntax nodes.

Getting started

Zirium requires Rust 1.88 or newer. The Python package supports conventional CPython 3.11 through 3.14. Release artifacts are currently proven only for Linux x86_64 and macOS arm64 by CI; other platforms require a local source build with maturin and are not part of the platform promise. Wheels remain specific to each supported CPython version rather than using the stable ABI.

The getting-started guide covers:

• building and testing the Rust workspace;
• installing the Python extension into a virtual environment;
• parsing, lowering, verifying, and writing MLIR;
• choosing a retention profile and output mode.

For the shortest check from a fresh checkout:

cargo test --workspace

Install a published Python wheel with:

python -m pip install zirium

If a wheel is not available yet, build the extension locally using the getting-started guide.

Output modes

Zirium has three output paths, each with a different contract:

Canonical output intentionally does not preserve comments, whitespace, aliases, or SSA spelling. Use original output when no semantic edit is needed, and hybrid retention when edits should leave unrelated source text alone.

Dialect support

Generic quoted operations are handled without a dialect registry. Unknown dialect types and attributes keep their balanced bodies as opaque values.

Registered custom syntax is currently a proving surface rather than broad MLIR dialect coverage. The built-in proving registry covers a fixed subset of Builtin, Func, Arith, and CF operations. A declarative registry can select from that same fixed set. The named stablehlo preset adds an initial custom-syntax subset for binary elementwise operations and stablehlo.return; it is not complete StableHLO support. Zirium does not load LLVM dialect definitions, interpret arbitrary ODS/TableGen files, or run Python callbacks while parsing.

The custom-format guide explains operation shapes, registry ownership, and the differences between Rust, Python, and the binary.

See compatibility and local wheel checks for the exact toolchain and CPython matrix. The corpus notes explain how syntax compatibility is tied to llvmorg-22.1.0.

Repository layout

crates/zirium/          Core Rust library
crates/zirium-python/   PyO3 extension module
python/zirium/          Python package and type declarations
python/tests/           Python API tests
tests/corpus/           Versioned MLIR compatibility corpus
docs/                   Usage, compatibility, and architecture notes
fuzz/                   Lexer and parser fuzz targets

The architecture notes include the syntax representation baseline and processing benchmarks.

Development checks

The complete local quality gate, including the supported Rust and Python versions, is documented in the compatibility guide. The CI workflow runs those same commands.

Python development details are documented in the getting-started guide. The release guide records the registry setup, package checks, and publication order.

License

Zirium's original code is available under the MIT or Apache 2.0 license. Some MLIR-derived or adapted test material retains the provenance and licensing information recorded in the corpus manifest.

Release notes are recorded in the changelog.