LIFT — Language for Intelligent Frameworks and Technologies

Unified intermediate representation for AI and quantum computing.

LIFT is a Rust compiler framework built around a single SSA-based intermediate representation that treats tensor operations (AI/ML), quantum gates, and classical–quantum hybrid computation as equal citizens in the same graph. One pipeline handles all three: define → verify → optimise → analyse → predict → export.

Why LIFT?

AI models run on GPUs, quantum circuits run on QPUs, and hybrid classical-quantum workloads (VQE, QAOA, quantum machine learning) need both — but today they live in separate IRs and separate toolchains with no shared way to reason about them.

1. One IR, two worlds — tensors and qubits share one SSA graph, so optimisation passes can reason across the classical/quantum boundary.
2. Noise in the type system — every quantum gate carries T1/T2, fidelity, and crosstalk metadata, so the compiler accounts for noise at every stage instead of after the fact.
3. Linear qubit types — the no-cloning theorem is enforced at compile time; reusing a qubit is a type error, not a runtime crash.
4. Analysis before hardware runs — FLOPs, peak memory, circuit depth, estimated fidelity, and energy cost are computed statically. Budget violations halt compilation with an actionable error.
5. One config file — a single .lith replaces the several configuration files typically scattered across separate frameworks.

Key Features

• 179 operations — 110 tensor ops (attention, convolutions, MoE, GNN, quantisation, diffusion), 48 quantum gates (Pauli, Clifford, parametric, IonQ-native), 21 hybrid ops (encoding, gradients, VQC/VQE/QAOA)
• 13 optimisation passes with preset O0–O3 pipelines, explicit-pass override, and per-pass enable/disable
• Semantic verification — SSA, well-formedness, qubit linearity, and operation arity checked against dialect signatures
• Hardware-native gate decomposition and real qubit routing — BFS-based SWAP insertion over device topologies, transpilation to IBM/Rigetti/IonQ/Quantinuum native gate sets
• Non-adjacent gate cancellation, rotation merging, and generic tensor fusion
• 3 export backends — LLVM IR, ONNX (opset 21), OpenQASM 3.0 (all 48 gates)
• Cost modelling and performance prediction — roofline analysis, GPU/QPU device profiles, energy/carbon estimation
• Programmatic model generation — a ModelBuilder Rust API and a lift-codegen binary for defining models in code

Architecture

The pipeline reads left to right: Frontend → Core (with semantic verification) → Dialects → Optimise → Analyse → Export.

flowchart LR
    subgraph Frontend["Frontend"]
        LIF[".lif source"]
        LITH[".lith config"]
        CODGEN["lift-codegen / ModelBuilder"]
    end

    subgraph Core["Core + Verify"]
        AST["lift-ast (lexer / parser)"]
        IR["lift-core — SSA IR, verifier"]
    end

    subgraph Dialects["Dialects"]
        TEN["lift-tensor (AI ops)"]
        QUA["lift-quantum (gates, noise)"]
        HYB["lift-hybrid (fusion)"]
    end

    subgraph Optimise["Optimise"]
        CFG["lift-config (O0-O3)"]
        OPT["lift-opt (13 passes)"]
    end

    subgraph Analyse["Analyse"]
        SIM["lift-sim (FLOPs, memory)"]
        PRED["lift-predict (roofline)"]
    end

    subgraph Export["Export"]
        LLVM["LLVM IR"]
        ONNX["ONNX"]
        QASM["OpenQASM 3.0"]
    end

    LIF --> AST
    LITH --> CFG
    CODGEN --> AST
    AST --> IR
    IR --> TEN & QUA & HYB
    IR --> OPT
    CFG --> OPT
    OPT --> SIM
    SIM --> PRED
    IR --> SIM
    IR --> LLVM & ONNX & QASM
    OPT --> LLVM & ONNX & QASM

    classDef stage fill:#e8f0fe,stroke:#1a73e8,color:#174ea6;
    class Frontend,Core,Dialects,Optimise,Analyse,Export stage;

Full architecture and the crate dependency graph: docs/LIFT_design.md.

Crates

All 13 are published to crates.io and versioned together.

Docs for any crate: https://docs.rs/<crate-name>.

Quick Start

Requires Rust 1.80+ (rustup).

cargo install lift-cli   # installs the `lift` binary

lift verify examples/phi3_mini.lif
lift analyse examples/phi3_mini.lif
lift optimise examples/phi3_mini.lif --config examples/phi3_optimize.lith
lift predict examples/phi3_mini.lif --device h100 --energy
lift predict examples/quantum_bell.lif --quantum superconducting
lift export examples/phi3_mini.lif --backend onnx --output model.onnx

Building from source instead: git clone this repo, then cargo build --release and substitute cargo run --release -p lift-cli -- for lift above.

As a library

[dependencies]
lift-core    = "0.4.8"
lift-ast     = "0.4.8"
lift-opt     = "0.4.8"
lift-export  = "0.4.8"

#![allow(unused)]
fn main() {
use lift_ast::{Lexer, Parser, IrBuilder};
use lift_core::{Context, verifier, pass::PassManager};

let source = std::fs::read_to_string("model.lif").unwrap();
let tokens = Lexer::new(&source).tokenize().to_vec();
let program = Parser::new(tokens).parse().unwrap();

let mut ctx = Context::new();
IrBuilder::new().build_program(&mut ctx, &program).unwrap();
verifier::verify(&ctx).unwrap();

let mut pm = PassManager::new();
pm.add_pass(Box::new(lift_opt::Canonicalize));
pm.add_pass(Box::new(lift_opt::TensorFusion));
// ... 13 passes total — see docs/LIFT_Guide.md for the full pipeline
pm.run_all(&mut ctx);

let onnx = lift_export::OnnxExporter::new().export(&ctx).unwrap();
}

Defining models programmatically instead of writing .lif by hand: see ModelBuilder in docs/LIFT_Guide.md or run cargo run --bin lift-codegen for a working end-to-end example.

Export Backends

• LLVM IR — --backend llvm. Emits IR with cuBLAS/cuDNN runtime call sites for all 110 tensor operations. Currently textual (not yet executable) — see docs/CAPABILITIES.md.
• ONNX — --backend onnx. Protobuf text, opset 21, 70+ operations mapped to standard ONNX and com.microsoft extensions (attention, MoE). Full op-mapping table in docs/LIFT_Guide.md.
• OpenQASM 3.0 — --backend qasm. All 48 gates, targeting IBM, Rigetti, IonQ, and Quantinuum native gate sets.

Examples

See examples/ — hand-written models (phi3_mini.lif, llama2_7b.lif, mistral_7b.lif, bert_base.lif, quantum_bell.lif) and programmatically generated ones (cargo run --bin lift-codegen). Validate the full pipeline end-to-end:

bash examples/validate_all.sh   # 105 checks across every example and backend

Documentation

• 📖 Online book — the full documentation set, searchable
• LIFT_Guide.md — feature guide with code examples for every crate
• LIFT_Manual.md — user manual with real-world use cases
• LIFT_design.md — architecture and design
• DIALECTS.md — full dialect reference (tensor, quantum, hybrid)
• CAPABILITIES.md — honest capabilities, limits, and roadmap
• STRATEGY.md — who uses LIFT and why
• CHANGELOG.md — version history

Contributing

Contributions are welcome — see CONTRIBUTING.md for the development workflow and PR process. This project follows a Code of Conduct; see SECURITY.md to report a vulnerability.

Roadmap

flowchart LR
    V3["v0.3 — IR, dialects, export"]
    V4["v0.4 — O0-O3 pipeline, 13 passes, crates.io"]
    V5["v0.5 — simulator, real backends, importers"]
    V6["v0.6 — autodiff, Python bindings, v1.0"]
    V3 --> V4 --> V5 --> V6

v0.4 (current) — optimisation pipeline with O0–O3 levels, semantic verification, 13 passes, all crates on crates.io.

v0.5 (next) — state-vector quantum simulator, tensor interpreter, real LLVM lowering with cuBLAS/cuDNN calls, functional ONNX/PyTorch FX/OpenQASM importers, SABRE-style dynamic qubit re-placement.

v0.6 — automatic differentiation, PyO3 Python bindings, multi-file support, v1.0 release.

Details: docs/ROADMAP-v0.5.md.

License

MIT

Complete LIFT Framework Guide — All Features

LIFT — Language for Intelligent Frameworks and Technologies Unified intermediate representation for AI and quantum computing.

This document describes every feature of the LIFT framework, numbered and organised by crate. For each feature: what it does, how to use it, and which other features to combine it with.

Table of Contents

1. General Architecture
2. lift-core — IR Core
3. lift-ast — Parsing the .lif Language
4. lift-tensor — Tensor Operations (110 ops)
5. lift-quantum — Quantum Gates and Noise (48 gates)
6. lift-hybrid — Classical-Quantum Hybrid Computation
7. lift-opt — Optimisation Passes (13 passes)
8. lift-sim — Simulation and Cost Analysis
9. lift-predict — Performance Prediction
10. lift-import — Model Import
11. lift-export — Backend Export (LLVM, ONNX, QASM)
12. lift-config — Configuration (.lith)
13. lift-cli — Command-Line Interface
14. lift-codegen — Programmatic Model Generation
15. Combinations and Complete Pipelines
16. Concrete Examples

1. General Architecture

LIFT is a modular compiler composed of 14 crates organised in layers:

                    ┌──────────┐
                    │ lift-cli │  ← User interface
                    └────┬─────┘
           ┌─────────────┼─────────────┐
           │             │             │
    ┌──────┴──────┐ ┌────┴────┐ ┌──────┴──────┐
    │ lift-import │ │lift-opt │ │ lift-export │
    └──────┬──────┘ └────┬────┘ └──────┬──────┘
           │             │             │
    ┌──────┴──────┐ ┌────┴────┐ ┌──────┴──────┐
    │  lift-ast   │ │lift-sim │ │lift-predict │
    └──────┬──────┘ └────┬────┘ └──────┬──────┘
           │             │             │
    ┌──────┴─────────────┴─────────────┴──────┐
    │              lift-core                    │
    ├──────────┬──────────┬───────────────────┤
    │lift-tensor│lift-quantum│  lift-hybrid    │
    └──────────┴──────────┴───────────────────┘

1.1 Compilation Pipeline

The standard workflow is:

Source (.lif) → Lexer → Parser → IR (SSA) → Verification → Optimisation → Simulation → Export

1.2 File Formats

1.3 Adding LIFT as a Dependency

[dependencies]
lift-core     = "0.4.8"
lift-ast      = "0.4.8"
lift-tensor   = "0.4.8"
lift-quantum  = "0.4.8"
lift-hybrid   = "0.4.8"
lift-opt      = "0.4.8"
lift-sim      = "0.4.8"
lift-predict  = "0.4.8"
lift-import   = "0.4.8"
lift-export   = "0.4.8"
lift-config   = "0.4.8"

2. lift-core — IR Core

The heart of the framework. Provides the SSA (Static Single Assignment) intermediate representation.

2.1 Context — The Central Container

#![allow(unused)]
fn main() {
use lift_core::Context;

let mut ctx = Context::new();
}

The Context stores all IR data: values, operations, blocks, regions, functions, modules, interned strings, and types.

Combine with: All other crates. The Context is the entry point for every pipeline.

2.2 Types — Type System

#![allow(unused)]
fn main() {
use lift_core::types::*;

// Data types
let fp32 = DataType::FP32;
let fp16 = DataType::FP16;
let bf16 = DataType::BF16;
let int8 = DataType::INT8;
let fp64 = DataType::FP64;

// Dimensions (static or symbolic)
let batch = Dimension::Constant(32);
let seq = Dimension::Symbolic("seq_len".to_string());

// Tensor type info
let tensor_info = TensorTypeInfo {
    shape: vec![Dimension::Constant(1), Dimension::Constant(784)],
    dtype: DataType::FP32,
    layout: MemoryLayout::Contiguous,
};

// Size in bytes (element count × dtype size — TensorTypeInfo has no
// size_bytes() method itself; lift-tensor's ShapeInference computes this
// for a given op, see §4.2)
let elems: usize = tensor_info.shape.iter().map(|d| d.static_value().unwrap_or(1)).product();
let bytes = elems * tensor_info.dtype.byte_size(); // 1*784*4 = 3136
}

Available data types:

Memory layouts: Contiguous, Strided.

2.3 Attributes — Operation Metadata

#![allow(unused)]
fn main() {
use lift_core::attributes::{Attribute, Attributes};

let mut attrs = Attributes::new();

// Different attribute types
attrs.set("num_heads", Attribute::Integer(8));
attrs.set("dropout", Attribute::Float(0.1));
attrs.set("causal", Attribute::Bool(true));

// Reading
let heads = attrs.get_integer("num_heads"); // Some(8)
let drop = attrs.get_float("dropout");       // Some(0.1)
let causal = attrs.get_bool("causal");       // Some(true)

// Checking
assert!(attrs.contains("num_heads"));
assert_eq!(attrs.len(), 3);

// Iteration
for (key, val) in attrs.iter() {
    println!("{}: {:?}", key, val);
}
}

Combine with: lift-opt (passes read/write attributes), lift-export (exporters read attributes).

2.4 Verifier — Invariant Checking

#![allow(unused)]
fn main() {
use lift_core::verifier;

let ctx = Context::new();
match verifier::verify(&ctx) {
    Ok(()) => println!("IR valid"),
    Err(errors) => {
        for e in &errors {
            eprintln!("Error: {}", e);
        }
    }
}
}

Checks:

• SSA: every value is defined exactly once
• Qubit linearity: every qubit is used exactly once
• Typing: type consistency between operations
• Structure: blocks, regions, terminators are correct

Combine with: Always use after import and after each optimisation pass.

2.5 Printer — IR Display

#![allow(unused)]
fn main() {
use lift_core::printer::print_ir;

let ctx = Context::new();
let output = print_ir(&ctx);
println!("{}", output);
}

Produces a human-readable textual representation of the IR, useful for debugging.

2.6 Pass Manager

#![allow(unused)]
fn main() {
use lift_core::pass::{PassManager, Pass, PassResult, AnalysisCache};

let mut pm = PassManager::new();
pm.add_pass(Box::new(lift_opt::Canonicalize));
pm.add_pass(Box::new(lift_opt::DeadCodeElimination));
pm.add_pass(Box::new(lift_opt::TensorFusion));

let results = pm.run_all(&mut ctx);
for (name, result) in &results {
    match result {
        PassResult::Changed => println!("{}: changed", name),
        PassResult::Unchanged => println!("{}: unchanged", name),
        PassResult::Error(e) => println!("{}: error: {}", name, e),
        PassResult::RolledBack => println!("{}: rolled back", name),
    }
}
}

Combine with: lift-opt (all 13 passes), lift-config (pass selection via configuration).

2.7 Dialect — Dialect System

#![allow(unused)]
fn main() {
use lift_core::dialect::{DialectRegistry, Dialect};
use lift_core::Context;

// A standalone registry starts empty.
let registry = DialectRegistry::new();

// Context::new() registers only the core dialect automatically
// (via register_builtin_dialects). Tensor/quantum/hybrid need explicit
// registration — this is what lift-cli's `verify` command does:
let mut ctx = Context::new();
lift_tensor::dialect::register_tensor_dialect(&mut ctx.dialects);
lift_quantum::dialect::register_quantum_dialect(&mut ctx.dialects);
lift_hybrid::dialect::register_hybrid_dialect(&mut ctx.dialects);
}

The three LIFT dialects:

• tensor: tensor operations (tensor.matmul, tensor.relu, etc.)
• quantum: quantum gates (quantum.h, quantum.cx, etc.)
• hybrid: hybrid operations (hybrid.encode, hybrid.vqc_layer, etc.)

3. lift-ast — Parsing the .lif Language

3.1 Lexer — Tokenisation

#![allow(unused)]
fn main() {
use lift_ast::Lexer;

let source = r#"
dialect tensor
module @mlp {
    func @forward(%x: tensor<1x784xf32>) -> tensor<1x10xf32> {
        %out = "tensor.relu"(%x) : (tensor<1x784xf32>) -> tensor<1x784xf32>
        return %out
    }
}
"#;

let mut lexer = Lexer::new(source);
let tokens = lexer.tokenize().to_vec();
assert!(lexer.errors().is_empty(), "Lexing errors: {:?}", lexer.errors());
}

3.2 Parser — Syntactic Analysis

#![allow(unused)]
fn main() {
use lift_ast::Parser;

let mut parser = Parser::new(tokens);
let program = parser.parse().expect("Parsing errors");
}

3.3 IrBuilder — IR Construction

#![allow(unused)]
fn main() {
use lift_ast::IrBuilder;
use lift_core::Context;

let mut ctx = Context::new();
let mut builder = IrBuilder::new();
builder.build_program(&mut ctx, &program).expect("IR construction errors");
}

3.4 Complete Parsing Pipeline

#![allow(unused)]
fn main() {
fn load_lif_file(path: &str) -> Result<Context, String> {
    let source = std::fs::read_to_string(path)
        .map_err(|e| format!("Read failed: {}", e))?;

    let mut lexer = Lexer::new(&source);
    let tokens = lexer.tokenize().to_vec();
    if !lexer.errors().is_empty() {
        return Err(format!("Lexer errors: {:?}", lexer.errors()));
    }

    let mut parser = Parser::new(tokens);
    let program = parser.parse().map_err(|e| format!("Parser errors: {:?}", e))?;

    let mut ctx = Context::new();
    let mut builder = IrBuilder::new();
    builder.build_program(&mut ctx, &program)?;
    Ok(ctx)
}
}

Combine with: lift-core (Context), then lift-opt (optimisation), lift-sim (analysis), lift-export (compilation).

4. lift-tensor — Tensor Operations (110 ops)

4.1 Complete Operation List by Category

4.1.1 Basic Arithmetic (5 ops)

#![allow(unused)]
fn main() {
use lift_tensor::ops::TensorOp;

let op = TensorOp::MatMul;
println!("Nom: {}", op.name());           // "tensor.matmul"
println!("Inputs: {:?}", op.num_inputs()); // (2, 2)
println!("FLOPs: {}", op.flops_formula()); // "2*M*N*K"
}

4.1.2 Linear Algebra (5 ops)

4.1.3 Activations (11 ops)

#![allow(unused)]
fn main() {
assert!(TensorOp::ReLU.is_activation());
assert!(!TensorOp::MatMul.is_activation());
}

4.1.4 Normalisation (5 ops)

#![allow(unused)]
fn main() {
assert!(TensorOp::LayerNorm.is_normalisation());
}

4.1.5 Attention (8 ops)

#![allow(unused)]
fn main() {
assert!(TensorOp::FlashAttention.is_attention());
}

4.1.6 Convolutions (6 ops)

4.1.7 Pooling (4 ops)

4.1.8 Shape Operations (13 ops)

#![allow(unused)]
fn main() {
assert!(TensorOp::Reshape.is_zero_flop());
}

4.1.9 Constants (5 ops)

4.1.10 Recurrent (3 ops)

4.1.11 Advanced Mathematics (11 ops)

4.1.12 Quantisation (6 ops)

4.1.13 Diffusion / Generative (3 ops)

4.1.14 GNN — Graph Neural Networks (2 ops)

4.1.15 MoE — Mixture of Experts (2 ops)

4.1.16 Memory and Gradient (11 ops)

4.1.17 Parallelism (4 ops)

4.1.18 Fused Operations (6 ops)

4.2 Shape Inference

#![allow(unused)]
fn main() {
use lift_core::types::*;
use lift_tensor::ops::TensorOp;
use lift_tensor::shape::ShapeInference;

fn mk(shape: Vec<usize>, dtype: DataType) -> TensorTypeInfo {
    TensorTypeInfo {
        shape: shape.into_iter().map(Dimension::Constant).collect(),
        dtype,
        layout: MemoryLayout::Contiguous,
    }
}

// Shape inference
let a = mk(vec![2, 3, 64], DataType::FP32);
let b = mk(vec![2, 64, 128], DataType::FP32);
let result = ShapeInference::infer_output_shape(&TensorOp::MatMul, &[&a, &b]).unwrap();
// result[0].shape = [2, 3, 128]

// FLOP computation
let flops = ShapeInference::compute_flops(&TensorOp::MatMul, &[&a, &b]);
println!("FLOPs: {:?}", flops); // Some(49152)

// Memory computation
let mem = ShapeInference::compute_memory_bytes(&TensorOp::MatMul, &[&a, &b]);
println!("Memory: {:?} bytes", mem);
}

Combine with: lift-sim (cost model uses FLOPs), lift-predict (roofline prediction).

4.3 Useful Predicates

#![allow(unused)]
fn main() {
let op = TensorOp::FlashAttention;

op.is_attention();      // true — attention variant?
op.is_convolution();    // false — convolution?
op.is_normalisation();  // false — normalisation?
op.is_activation();     // false — activation?
op.is_fused();          // false — fused operation?
op.is_gradient();       // false — gradient operation?
op.is_zero_flop();      // false — zero FLOPs (reshape, etc.)?
op.num_inputs();        // (3, 4) — min/max number of inputs
op.flops_formula();     // "2*B*H*(S^2*D + S*D^2)"
}

5. lift-quantum — Quantum Gates and Noise (48 gates)

5.1 Quantum Gates

5.1.1 Standard 1-Qubit Gates (9 gates)

5.1.2 Parametric 1-Qubit Gates (9 gates)

5.1.3 2-Qubit Gates (14 gates)

5.1.4 3-Qubit and Multi-Control Gates (4 gates)

5.1.5 Special and Control Gates (10 gates)

5.1.6 IonQ Native Gates (2 gates)

#![allow(unused)]
fn main() {
use lift_quantum::gates::QuantumGate;

let gate = QuantumGate::H;
println!("Name: {}", gate.op_name());       // "quantum.h"
println!("Qubits: {}", gate.num_qubits());  // 1
println!("Clifford: {}", gate.is_clifford()); // true
println!("Parametric: {}", gate.is_parametric()); // false
println!("Self-inverse: {}", gate.is_self_inverse()); // true

// Look up a gate by its IR name
let gate = QuantumGate::from_name("quantum.cx"); // Some(CX)
}

5.2 Hardware Providers — Native Gate Sets

#![allow(unused)]
fn main() {
use lift_quantum::gates::{QuantumGate, Provider};

// Native gates per provider
let ibm_basis = QuantumGate::native_basis(Provider::IbmEagle);
let rigetti_basis = QuantumGate::native_basis(Provider::Rigetti);
let ionq_basis = QuantumGate::native_basis(Provider::IonQ);
let quant_basis = QuantumGate::native_basis(Provider::Quantinuum);
}

Combine with: lift-opt::GateDecomposition (native gate transpilation) and lift-opt::RealRouting (actual SWAP insertion using this topology).

5.3 Device Topology — Hardware Topology

#![allow(unused)]
fn main() {
use lift_quantum::topology::DeviceTopology;

// Predefined topologies
let linear = DeviceTopology::linear(10);         // Linear chain
let grid = DeviceTopology::grid(3, 3);           // 3x3 grid
let hex = DeviceTopology::heavy_hex(27);         // Heavy-hex IBM
let ion = DeviceTopology::all_to_all(32);        // All-to-all (trapped ions)
let tree = DeviceTopology::tree(15);             // Binary tree

// Custom topology
let custom = DeviceTopology::custom("my_chip",
    &[(0,1), (1,2), (2,3), (0,3)], 0.99);

// Querying
linear.are_connected(0, 1);           // true
linear.shortest_path(0, 4);           // Some([0, 1, 2, 3, 4])
linear.swap_distance(0, 4);           // Some(3)
linear.avg_connectivity();             // average connectivity
linear.diameter();                     // graph diameter
grid.neighbors(4);                     // neighbours of qubit 4
}

Combine with: lift-opt::LayoutMapping, lift-opt::NoiseAwareSchedule.

5.4 Noise Models

#![allow(unused)]
fn main() {
use lift_quantum::noise::{NoiseModel, GateNoise, CircuitNoise};

// Noise models
let ideal = NoiseModel::Ideal;
let depol = NoiseModel::Depolarizing { p: 0.01 };
let bitflip = NoiseModel::BitFlip { p: 0.001 };
let phaseflip = NoiseModel::PhaseFlip { p: 0.001 };

// Model fidelity
let fidelity = depol.fidelity(); // 0.99

// Per-gate noise
let gate_noise = GateNoise::with_depolarizing(0.999, 0.02);

// Full circuit analysis
let mut cn = CircuitNoise::new();
// ... noise accumulation
println!("Total fidelity: {}", cn.total_fidelity);
println!("2-qubit gates: {}", cn.two_qubit_count);
}

5.5 Kraus Channels — Quantum Noise Channels

#![allow(unused)]
fn main() {
use lift_quantum::kraus::{ComplexMatrix, KrausChannel};

// Predefined noise channels
let depol = KrausChannel::depolarizing(0.01, 1);     // 1-qubit depolarising
let amp = KrausChannel::amplitude_damping(0.02);      // Amplitude damping
let phase = KrausChannel::phase_damping(0.01);         // Phase damping

// Channel fidelity
let fidelity = depol.average_gate_fidelity();
println!("Fidelity: {:.6}", fidelity);

// Complex matrices
let mut m = ComplexMatrix::identity(2);
let dagger = m.dagger();    // Conjugate transpose
let product = m.mul(&dagger).unwrap();
let trace = m.trace().unwrap();
}

Combine with: lift-sim::QuantumCostModel (circuit fidelity estimation), lift-opt::NoiseAwareSchedule.

5.6 QEC — Quantum Error Correction

#![allow(unused)]
fn main() {
use lift_quantum::qec::{QecCode, QecAnalysis};

// Available QEC codes
let surface = QecCode::SurfaceCode { distance: 5 };   // 25 physical qubits/logical
let steane = QecCode::SteaneCode;                       // 7 physical qubits/logical
let shor = QecCode::ShorCode;                            // 9 physical qubits/logical
let rep = QecCode::RepetitionCode { distance: 7 };     // 7 physical qubits
let ldpc = QecCode::LdpcCode { n: 100, k: 10 };       // LDPC code

// Code properties
println!("Physical/logical: {}", surface.physical_per_logical()); // 25
println!("Distance: {}", surface.code_distance());                 // 5
println!("Syndrome depth: {}", surface.syndrome_circuit_depth()); // 5

// Full QEC analysis
let analysis = QecAnalysis::analyse(
    10,     // logical qubits
    100,    // circuit depth
    QecCode::SurfaceCode { distance: 5 },
    0.001,  // physical error rate
);
println!("Physical qubits: {}", analysis.physical_qubits);
println!("Logical error rate: {:.2e}", analysis.logical_error_rate);
println!("Overhead: {}", analysis.overhead_qubits);
}

Combine with: lift-sim::QuantumCostModel, lift-predict (fidelity budget).

6. lift-hybrid — Classical-Quantum Hybrid Computation

6.1 Hybrid Operations (21 ops)

6.1.1 Encoding/Decoding (2 ops)

6.1.2 Gradient Methods (6 ops)

#![allow(unused)]
fn main() {
use lift_hybrid::gradient::GradientMethod;

let method = GradientMethod::ParameterShift;
let evals = method.circuit_evaluations(100); // 200 evaluations for 100 params
assert!(method.is_exact()); // true
}

6.1.3 Processing (4 ops)

6.1.4 Variational Algorithms (4 ops)

6.1.5 Data Transfer (2 ops)

6.1.6 Co-Execution and Measurement (3 ops)

#![allow(unused)]
fn main() {
use lift_hybrid::ops::HybridOp;

let op = HybridOp::VqcLayer;
assert!(op.is_variational());
assert!(!op.is_gradient());
}

6.2 Encoding Strategies

#![allow(unused)]
fn main() {
use lift_hybrid::encoding::{EncodingStrategy, EncodingConfig};

let strategies = [
    EncodingStrategy::AngleEncoding,       // 1 qubit/feature, depth 1
    EncodingStrategy::AmplitudeEncoding,    // log2(n) qubits, depth n
    EncodingStrategy::BasisEncoding,        // 1 qubit/feature, depth 1
    EncodingStrategy::IQPEncoding,          // 1 qubit/feature, depth 2n
    EncodingStrategy::HamiltonianEncoding,  // 1 qubit/feature, depth n
    EncodingStrategy::KernelEncoding,       // 1 qubit/feature, depth 3n
];

// Encoding configuration
let config = EncodingConfig::new(EncodingStrategy::AmplitudeEncoding, 256);
println!("Qubits required: {}", config.num_qubits); // 8 = log2(256)
println!("Classical dimension: {}", config.classical_dim); // 256
}

6.3 Gradient Configuration — Joint Gradient Setup

#![allow(unused)]
fn main() {
use lift_hybrid::gradient::{GradientMethod, JointGradientConfig};

let config = JointGradientConfig {
    classical_method: GradientMethod::Backprop,
    quantum_method: GradientMethod::ParameterShift,
    num_classical_params: 1000,
    num_quantum_params: 50,
};
println!("Total evaluations: {}", config.total_evaluations());
// 1 (backprop) + 100 (2*50 parameter shift) = 101
}

6.4 Auxiliary Types

#![allow(unused)]
fn main() {
use lift_hybrid::ops::{AnsatzType, SyncPolicy, FeatureMap};

// Ansatz types for VQC
let ansatz = AnsatzType::HardwareEfficient; // HardwareEfficient, StronglyEntangling, TwoLocal, UCCSD, Custom

// Synchronisation policy
let sync = SyncPolicy::Blocking; // Blocking, Asynchronous, Pipeline

// Feature maps for quantum kernels
let fm = FeatureMap::ZZFeatureMap; // ZZFeatureMap, PauliFeatureMap, AngleEncoding, AmplitudeEncoding
}

7. lift-opt — Optimisation Passes (13 passes)

7.1 Classical Passes (5 passes)

7.1.1 Canonicalize — Canonical Form

#![allow(unused)]
fn main() {
use lift_opt::Canonicalize;
use lift_core::pass::Pass;

let pass = Canonicalize;
// Reorders operations into canonical form
// Normalises IR patterns to facilitate subsequent optimisations
}

Usage: Always run first in the pipeline.

7.1.2 ConstantFolding — Constant Folding

#![allow(unused)]
fn main() {
use lift_opt::ConstantFolding;

let pass = ConstantFolding;
// Evaluates operations whose operands are all compile-time constants
// Example: add(const(2), const(3)) → const(5)
}

7.1.3 DeadCodeElimination — Dead Code Elimination

#![allow(unused)]
fn main() {
use lift_opt::DeadCodeElimination;

let pass = DeadCodeElimination;
// Removes operations whose results are never used
// Respects operations with side effects (measurements, etc.)
}

7.1.4 TensorFusion — Tensor Fusion

#![allow(unused)]
fn main() {
use lift_opt::TensorFusion;

let pass = TensorFusion;
// Fuses consecutive operations into fused operations
// Example: MatMul + Bias + ReLU → FusedMatMulBiasReLU
// Reduces memory accesses and kernel launches
}

Combine with: Run after Canonicalize and ConstantFolding.

7.1.5 CommonSubexprElimination — Common Subexpression Elimination

#![allow(unused)]
fn main() {
use lift_opt::CommonSubexprElimination;

let pass = CommonSubexprElimination;
// Detects identical operations (same op, same operands)
// Replaces duplicates with references to the first occurrence
// Excludes operations with side effects
}

7.2 Quantum Passes (3 passes)

7.2.1 GateCancellation — Gate Cancellation

#![allow(unused)]
fn main() {
use lift_opt::GateCancellation;

let pass = GateCancellation;
// Removes gate pairs that cancel out
// Example: H H → identity, X X → identity
// Respects qubit linearity invariants
}

7.2.2 RotationMerge — Rotation Merging

#![allow(unused)]
fn main() {
use lift_opt::RotationMerge;

let pass = RotationMerge;
// Merges consecutive rotations on the same axis
// Example: RZ(0.3) RZ(0.5) → RZ(0.8)
// Removes identity rotations (angle ≈ 0)
}

7.2.3 NoiseAwareSchedule — Noise-Aware Scheduling

#![allow(unused)]
fn main() {
use lift_opt::NoiseAwareSchedule;

let pass = NoiseAwareSchedule;
// Reorders quantum gates to minimise decoherence
// Prioritises fast gates (1-qubit) before slow ones (2-qubit)
// Respects SSA dependencies
}

Combine with: lift-quantum::topology::DeviceTopology for the target topology.

7.3 Advanced AI Passes (3 passes)

7.3.1 FlashAttentionPass — FlashAttention Replacement

#![allow(unused)]
fn main() {
use lift_opt::FlashAttentionPass;

let pass = FlashAttentionPass::default(); // threshold = 512
let pass_custom = FlashAttentionPass { seq_len_threshold: 1024 };
// Replaces tensor.attention with tensor.flash_attention
// when sequence length exceeds the threshold
// Reduces memory complexity from O(N²) to O(N)
}

7.3.2 QuantisationPass — Quantisation Annotation

#![allow(unused)]
fn main() {
use lift_opt::QuantisationPass;
use lift_opt::quantisation_pass::{QuantTarget, QuantMode};

let pass = QuantisationPass::default(); // INT8, Dynamic
let pass_custom = QuantisationPass {
    target_dtype: QuantTarget::Fp8E4M3,
    mode: QuantMode::Static,
};
// Annotates heavy operations (MatMul, Conv, Linear, Attention)
// with quantisation metadata
// Inserts Quantize/Dequantize pairs around annotated ops
}

7.3.3 LayoutMapping — Qubit Mapping

#![allow(unused)]
fn main() {
use lift_opt::LayoutMapping;

let pass = LayoutMapping;
// Legacy annotation-only pass: marks 2-qubit gates whose qubits aren't
// adjacent in the target topology with needs_swap = true.
// Does NOT insert SWAP gates itself — that's RealRouting (§7.3.5), which
// actually inserts quantum.swap ops along a BFS shortest path.
}

Combine with: lift-quantum::topology::DeviceTopology.

7.3.4 GateDecomposition — Hardware-Native Gate Sets

#![allow(unused)]
fn main() {
use lift_opt::gate_decompose::GateDecomposition;
use lift_quantum::gates::Provider;

let pass = GateDecomposition::new(Provider::IbmEagle);
// Lowers high-level gates to hardware-native gate sets, replacing the
// original gate (not leaving it wired in alongside its decomposition):
//   H     → RZ(π/2) SX RZ(π/2)
//   T/Tdg → RZ(±π/4)
//   S/Sdg → RZ(±π/2)
//   Y     → RZ(π/2) X RZ(-π/2)
//   RX(θ) → RZ(π/2) SX RZ(π+θ) SX RZ(π/2)   (verified against the closed-form
//                                             RX(θ) matrix up to global phase)
// GateDecomposition::default() reads the provider from the "lift_provider"
// op metadata key instead, falling back to Provider::Simulator (a no-op)
// when it's unset — nothing in the CLI/config pipeline sets that key today,
// so use GateDecomposition::new(provider) explicitly, as above.
// Uses Context::insert_op_before to preserve SSA dominance
}

Combine with: lift-config [quantum] provider key.

7.3.5 RealRouting — SWAP-Based Qubit Routing

#![allow(unused)]
fn main() {
use lift_opt::real_routing::RealRouting;
use lift_quantum::topology::DeviceTopology;

let pass = RealRouting::new(DeviceTopology::linear(8));
// Inserts actual quantum.swap operations so every 2-qubit gate
// only acts on physically connected qubits.
// Strategy: identity initial placement, BFS shortest-path routing,
// logical↔physical placement maps updated after every swap.
}

Combine with: lift-config [quantum] topology / num_qubits keys.

7.4 Optimisation Levels (O0-O3)

lift-config provides preset pipelines so you don't have to enumerate passes by hand:

[optimisation]
level = "O3"                  # preset pipeline
passes = []                   # (optional) explicit overrides the level
disabled_passes = ["cse"]     # (optional) remove specific passes
max_iterations = 5

Explicit passes take priority over level; unknown pass names are reported by OptimisationConfig::validate().

7.5 Recommended Optimisation Pipeline

#![allow(unused)]
fn main() {
use lift_core::PassManager;

let mut pm = PassManager::new();

// Phase 1: Cleanup
pm.add_pass(Box::new(lift_opt::Canonicalize));
pm.add_pass(Box::new(lift_opt::ConstantFolding));
pm.add_pass(Box::new(lift_opt::DeadCodeElimination));
pm.add_pass(Box::new(lift_opt::CommonSubexprElimination));

// Phase 2: Fusion (AI)
pm.add_pass(Box::new(lift_opt::TensorFusion));
pm.add_pass(Box::new(lift_opt::FlashAttentionPass::default()));
pm.add_pass(Box::new(lift_opt::QuantisationPass::default()));

// Phase 3: Quantum
pm.add_pass(Box::new(lift_opt::GateCancellation));
pm.add_pass(Box::new(lift_opt::RotationMerge));
pm.add_pass(Box::new(lift_opt::NoiseAwareSchedule));
pm.add_pass(Box::new(lift_opt::LayoutMapping));

// Phase 3b: Hardware targeting
pm.add_pass(Box::new(lift_opt::gate_decompose::GateDecomposition::new(Provider::IbmEagle)));
pm.add_pass(Box::new(lift_opt::real_routing::RealRouting::new(DeviceTopology::linear(8))));

// Phase 4: Final cleanup
pm.add_pass(Box::new(lift_opt::DeadCodeElimination));

let results = pm.run_all(&mut ctx);
}

8. lift-sim — Simulation and Cost Analysis

8.1 CostModel — Classical Cost Model

#![allow(unused)]
fn main() {
use lift_sim::cost::CostModel;

// Predefined GPU profiles
let a100 = CostModel::a100();  // 312 TFLOPS, 2039 GB/s
let h100 = CostModel::h100();  // 989 TFLOPS, 3350 GB/s

// Time estimation
let flops = 2 * 1024 * 1024 * 1024_u64;
let bytes = 4 * 1024 * 1024_u64;

let compute_ms = a100.compute_time_ms(flops);      // Compute time
let memory_ms = a100.memory_time_ms(bytes);         // Memory time
let roofline_ms = a100.roofline_time_ms(flops, bytes); // Roofline model

// Analysis
let ai = a100.arithmetic_intensity(flops, bytes);   // FLOPs/byte
let bound = a100.is_compute_bound(flops, bytes);    // true = compute-bound
let fits = a100.fits_in_memory(bytes);               // Fits in memory?
let gpus = a100.num_gpus_needed(bytes);              // GPUs needed
}

8.2 QuantumCostModel — Quantum Cost Model

#![allow(unused)]
fn main() {
use lift_sim::cost::QuantumCostModel;

// Quantum processor profiles
let sc = QuantumCostModel::superconducting_default(); // IBM-like: 127 qubits
let ion = QuantumCostModel::trapped_ion_default();     // IonQ-like: 32 qubits
let atom = QuantumCostModel::neutral_atom_default();   // Atom-like: 256 qubits

// Circuit fidelity estimation
let fidelity = sc.circuit_fidelity(50, 20); // 50 1Q gates, 20 2Q gates
println!("Fidelity: {:.6}", fidelity);

// Circuit time
let time_us = sc.circuit_time_us(50, 20, 5, 10); // 50 1Q, 20 2Q, 5 measurements, 10 depth
println!("Time: {:.2} µs", time_us);

// Decoherence fidelity
let decoherence = sc.decoherence_fidelity(time_us);
println!("Decoherence fidelity: {:.6}", decoherence);
}

8.3 Budget — Resource Constraints

#![allow(unused)]
fn main() {
use lift_sim::cost::Budget;

let budget = Budget {
    max_flops: Some(1_000_000_000_000), // 1 TFLOP max
    max_memory_bytes: Some(80_000_000_000), // 80 GB
    max_time_ms: Some(100.0),           // 100 ms
    min_fidelity: Some(0.99),           // 99% min fidelity
    max_circuit_depth: Some(1000),      // 1000 layers max
};

budget.check_flops(500_000_000_000).unwrap();   // OK
budget.check_memory(40_000_000_000).unwrap();   // OK
budget.check_fidelity(0.995).unwrap();           // OK
}

8.4 EnergyModel — Energy and Carbon Estimation

#![allow(unused)]
fn main() {
use lift_sim::cost::EnergyModel;

let model = EnergyModel::a100();

// Energy for 1 second of computation on 4 GPUs
let joules = model.energy_joules(1000.0, 4);     // Joules
let kwh = model.energy_kwh(1000.0, 4);           // kWh
let carbon = model.carbon_grams(1000.0, 4);       // grams CO₂

println!("Energy: {:.2} J", joules);
println!("Carbon: {:.4} g CO₂", carbon);

// Quantum energy (cryogenic refrigeration)
let q_joules = model.quantum_energy_joules(100.0, 127); // 100 µs, 127 qubits
}

8.5 ReactiveBudget — Dynamic Budget

#![allow(unused)]
fn main() {
use lift_sim::cost::{Budget, ReactiveBudget};

let budget = Budget {
    max_flops: Some(1_000_000),
    max_memory_bytes: Some(1_000_000),
    max_time_ms: Some(50.0),
    min_fidelity: Some(0.9),
    max_circuit_depth: None,
};
let mut rb = ReactiveBudget::new(budget);

// Consume resources incrementally
rb.consume(100_000, 50_000, 5.0, 0.99); // flops, mem, time, fidelity
rb.consume(200_000, 80_000, 10.0, 0.98);

// Check remaining budget
rb.check_remaining().unwrap(); // OK if within limits

// Utilisation report
let util = rb.utilisation();
println!("FLOPs used: {:.1}%", util.flop_ratio.unwrap() * 100.0);
println!("Time used: {:.1}%", util.time_ratio.unwrap() * 100.0);

// Remaining budget
println!("Remaining FLOPs: {:?}", rb.remaining_flops());
println!("Remaining time: {:?} ms", rb.remaining_time_ms());
}

Combine with: lift-opt (stop optimisation if budget exhausted), lift-predict (verify prediction respects budget).

8.6 Module Analysis

#![allow(unused)]
fn main() {
use lift_sim::{analyze_module, analyze_quantum_ops};

let ctx = load_and_parse("model.lif").unwrap();

// Classical analysis
let report = analyze_module(&ctx);
println!("Total ops: {}", report.num_ops);
println!("Tensor ops: {}", report.num_tensor_ops);
println!("Quantum ops: {}", report.num_quantum_ops);
println!("Hybrid ops: {}", report.num_hybrid_ops);
println!("Total FLOPs: {}", report.total_flops);
println!("Total memory: {} bytes", report.total_memory_bytes);
println!("Peak memory: {} bytes", report.peak_memory_bytes);

// Quantum analysis
let quantum = analyze_quantum_ops(&ctx);
println!("Qubits: {}", quantum.num_qubits_used);
println!("Gates: {}", quantum.gate_count);
println!("1Q gates: {}", quantum.one_qubit_gates);
println!("2Q gates: {}", quantum.two_qubit_gates);
println!("Measurements: {}", quantum.measurements);
println!("Estimated fidelity: {:.6}", quantum.estimated_fidelity);
}

9. lift-predict — Performance Prediction

#![allow(unused)]
fn main() {
use lift_predict::predict_performance;
use lift_sim::{analyze_module, cost::CostModel};

let report = analyze_module(&ctx);
let cost_model = CostModel::h100();
let prediction = predict_performance(&report, &cost_model);

println!("Compute time: {:.4} ms", prediction.compute_time_ms);
println!("Memory time: {:.4} ms", prediction.memory_time_ms);
println!("Predicted time: {:.4} ms", prediction.predicted_time_ms);
println!("Arithmetic intensity: {:.2} FLOP/byte", prediction.arithmetic_intensity);
println!("Bottleneck: {}", prediction.bottleneck); // "compute" or "memory"
}

Combine with: lift-sim (provides the analysis report and cost model).

10. lift-import — Model Import

10.1 ONNX Import

#![allow(unused)]
fn main() {
use lift_import::OnnxImporter;

let importer = OnnxImporter::new();
let ctx = importer.import("model.onnx").expect("ONNX import failed");
}

10.2 PyTorch FX Import

#![allow(unused)]
fn main() {
use lift_import::PyTorchFxImporter;

let importer = PyTorchFxImporter::new();
let ctx = importer.import("model_fx.json").expect("FX import failed");
}

10.3 OpenQASM 3.0 Import

#![allow(unused)]
fn main() {
use lift_import::OpenQasm3Importer;

let importer = OpenQasm3Importer::new();
let ctx = importer.import("circuit.qasm").expect("QASM import failed");
}

Combine with: lift-core::verifier (verify imported IR), then lift-opt (optimise).

11. lift-export — Backend Export (LLVM, ONNX, QASM)

11.1 Export LLVM IR

#![allow(unused)]
fn main() {
use lift_export::LlvmExporter;

let exporter = LlvmExporter::new();
let llvm_ir = exporter.export(&ctx).expect("LLVM export failed");
std::fs::write("output.ll", &llvm_ir).unwrap();
}

Produces LLVM IR with runtime function calls for tensor operations (cuBLAS/cuDNN backend).

11.2 Export ONNX

#![allow(unused)]
fn main() {
use lift_export::OnnxExporter;

let exporter = OnnxExporter::new();
let onnx_text = exporter.export(&ctx).expect("ONNX export failed");
std::fs::write("output.onnx", &onnx_text).unwrap();

// Also available: JSON format
let onnx_json = exporter.export_json(&ctx).expect("ONNX JSON export failed");
std::fs::write("output_onnx.json", &onnx_json).unwrap();
}

Produces ONNX protobuf text format at opset version 21, IR version 9. Compatible with:

• PyTorch, TensorFlow, TensorRT, ONNX Runtime
• Microsoft extension ops for attention and MoE

ONNX op mapping (70+ operations):

Data type mapping:

11.3 Export OpenQASM 3.0

#![allow(unused)]
fn main() {
use lift_export::QasmExporter;

let exporter = QasmExporter::new();
let qasm = exporter.export(&ctx).expect("QASM export failed");
std::fs::write("output.qasm", &qasm).unwrap();
}

Produces OpenQASM 3.0 executable on IBM Quantum, Rigetti, IonQ, Quantinuum. Every one of the 48 QuantumGate variants has a match arm — 46 emit a real gate instruction, and IfElse/ParamGate (control-flow and generic wrappers, not literal gates) emit a descriptive comment instead. Qubit indices are resolved by following each gate's actual SSA operand back to its owning qubit, not assigned from a counter.

Combine with: lift-opt (optimise before export), lift-quantum::Provider (transpile to native gate set).

12. lift-config — Configuration (.lith)

12.1 .lith File Format

[target]
backend = "cuda"
device = "A100"
precision = "fp16"

[budget]
max_flops = 1000000000000
max_memory_bytes = 80000000000
max_time_ms = 100.0
min_fidelity = 0.99

[optimisation]
level = O2
max_iterations = 10

[simulation]
shape_propagation = true
flop_counting = true
memory_analysis = true
noise_simulation = true

[quantum]
topology = "heavy_hex"
num_qubits = 127
shots = 4096

12.2 Programmatic Loading

#![allow(unused)]
fn main() {
use lift_config::{ConfigParser, LithConfig};

// From a file
let source = std::fs::read_to_string("config.lith").unwrap();
let config = ConfigParser::new().parse(&source).unwrap();

// Default configuration
let default = LithConfig::default();
// Backend: llvm, Level: O2, Passes: canonicalize, constant-folding, dce, tensor-fusion

// With quantum
let hybrid = LithConfig::default().with_quantum("heavy_hex", 127);
}

12.3 Optimisation Levels

13. lift-cli — Command-Line Interface

13.1 Available Commands

13.1.1 lift verify — Verify a .lif file

lift verify model.lif
lift verify --verbose model.lif

Checks SSA invariants, qubit linearity, and typing.

13.1.2 lift analyse — Analyse a program

lift analyse model.lif
lift analyse model.lif --format json

Produces a report: op count, FLOPs, memory, quantum analysis.

13.1.3 lift print — Display the IR

lift print model.lif

Displays the IR in human-readable format.

13.1.4 lift optimise — Optimise

lift optimise model.lif
lift optimise model.lif --config config.lith --output optimised.lif

Applies the configured optimisation passes.

13.1.5 lift predict — Predict performance

lift predict model.lif --device a100
lift predict model.lif --device h100

Predicts execution time using the roofline model.

13.1.6 lift export — Export

lift export model.lif --backend llvm --output model.ll
lift export model.lif --backend onnx --output model.onnx
lift export quantum.lif --backend qasm --output circuit.qasm

Exports to LLVM IR, ONNX (opset 21), or OpenQASM 3.0.

14. lift-codegen — Programmatic Model Generation

The lift-codegen binary lets you define models directly from Rust code and automatically generate all export formats.

14.1 Running the Code Generator

cargo run --bin lift-codegen

This generates into examples/:

• 4 .lif models — Phi-3-mini, MLP, ResNet block, VQE circuit
• 4 .ll files — LLVM IR exports
• 4 .onnx files — ONNX exports
• 1 .qasm file — OpenQASM export (for quantum models only)
• 1 .lith config — H100 optimization configuration

Each model is automatically verified, analysed, optimised, and exported.

14.2 ModelBuilder API

#![allow(unused)]
fn main() {
use lift_core::model_builder::{ModelBuilder, tensor, tensor_2d, DataType};

let model = ModelBuilder::new("my_model")
    .function("forward")
        .param("x", tensor(&[1, 784], DataType::FP32))
        .param("w", tensor_2d(784, 256, DataType::FP32))
        .op("tensor.matmul", &["x", "w"], "h", tensor(&[1, 256], DataType::FP32))
        .op("tensor.relu", &["h"], "out", tensor(&[1, 256], DataType::FP32))
        .returns("out")
        .done();

// Write .lif source file
model.write_lif("my_model.lif").unwrap();

// Build IR context for verification/analysis/export
let ctx = model.build_context();
lift_core::verifier::verify(&ctx).unwrap();
}

14.3 Multi-Target Export from Code

#![allow(unused)]
fn main() {
let ctx = model.build_context();

// Optimise first
let mut pm = PassManager::new();
pm.add_pass(Box::new(lift_opt::Canonicalize));
pm.add_pass(Box::new(lift_opt::ConstantFolding));
pm.add_pass(Box::new(lift_opt::DeadCodeElimination));
pm.add_pass(Box::new(lift_opt::TensorFusion));
pm.run_all(&mut ctx);

// Export to all 3 backends
let llvm_ir = lift_export::LlvmExporter::new().export(&ctx).unwrap();
let onnx_ir = lift_export::OnnxExporter::new().export(&ctx).unwrap();
std::fs::write("my_model.ll", &llvm_ir).unwrap();
std::fs::write("my_model.onnx", &onnx_ir).unwrap();

// Export QASM only if quantum ops present
if ctx.ops.iter().any(|(_, op)| ctx.strings.resolve(op.name).starts_with("quantum.")) {
    let qasm_ir = lift_export::QasmExporter::new().export(&ctx).unwrap();
    std::fs::write("my_model.qasm", &qasm_ir).unwrap();
}
}

Combine with: All other crates. ModelBuilder is the programmatic entry point for defining models without .lif files.

15. Combinations and Complete Pipelines

15.1 Complete AI Pipeline (Transformer)

#![allow(unused)]
fn main() {
// 1. Import an ONNX model
let ctx = OnnxImporter::new().import("bert.onnx")?;

// 2. Verify
verifier::verify(&ctx)?;

// 3. Analyse
let report = analyze_module(&ctx);

// 4. Optimise
let mut pm = PassManager::new();
pm.add_pass(Box::new(Canonicalize));
pm.add_pass(Box::new(ConstantFolding));
pm.add_pass(Box::new(DeadCodeElimination));
pm.add_pass(Box::new(CommonSubexprElimination));
pm.add_pass(Box::new(TensorFusion));
pm.add_pass(Box::new(FlashAttentionPass { seq_len_threshold: 512 }));
pm.add_pass(Box::new(QuantisationPass {
    target_dtype: QuantTarget::Int8,
    mode: QuantMode::Dynamic,
}));
pm.add_pass(Box::new(DeadCodeElimination));
pm.run_all(&mut ctx);

// 5. Predict performance
let h100 = CostModel::h100();
let pred = predict_performance(&analyze_module(&ctx), &h100);

// 6. Export to LLVM and ONNX
let llvm = LlvmExporter::new().export(&ctx)?;
let onnx = OnnxExporter::new().export(&ctx)?;
std::fs::write("bert_optimised.ll", llvm)?;
std::fs::write("bert_optimised.onnx", onnx)?;
}

15.2 Complete Quantum Pipeline (Bell State)

#![allow(unused)]
fn main() {
// 1. Parse the circuit
let ctx = load_lif_file("quantum_bell.lif")?;

// 2. Analyse noise
let quantum = analyze_quantum_ops(&ctx);
let sc = QuantumCostModel::superconducting_default();
let fidelity = sc.circuit_fidelity(
    quantum.one_qubit_gates, quantum.two_qubit_gates
);

// 3. QEC if needed
if fidelity < 0.99 {
    let analysis = QecAnalysis::analyse(2, 5,
        QecCode::SurfaceCode { distance: 3 }, 0.001);
    println!("Physical qubits needed: {}", analysis.physical_qubits);
}

// 4. Optimise
let mut pm = PassManager::new();
pm.add_pass(Box::new(GateCancellation));
pm.add_pass(Box::new(RotationMerge));
pm.add_pass(Box::new(NoiseAwareSchedule));
pm.add_pass(Box::new(LayoutMapping));
pm.run_all(&mut ctx);

// 5. Export to QASM
let qasm = QasmExporter::new().export(&ctx)?;
std::fs::write("bell_optimised.qasm", qasm)?;
}

15.3 Complete Hybrid Pipeline (VQE)

#![allow(unused)]
fn main() {
// 1. Configure encoding
let encoding = EncodingConfig::new(EncodingStrategy::AngleEncoding, 4);

// 2. Configure gradient
let grad_config = JointGradientConfig {
    classical_method: GradientMethod::Backprop,
    quantum_method: GradientMethod::ParameterShift,
    num_classical_params: 100,
    num_quantum_params: 20,
};

// 3. Reactive budget to control resources
let budget = Budget {
    max_flops: Some(1_000_000_000),
    max_memory_bytes: Some(8_000_000_000),
    max_time_ms: Some(60_000.0),
    min_fidelity: Some(0.95),
    max_circuit_depth: Some(500),
};
let mut rb = ReactiveBudget::new(budget);

// 4. VQE optimisation loop
for iteration in 0..100 {
    // Execute the quantum circuit
    rb.consume(10_000, 1_000, 0.5, 0.999);
    
    if rb.check_remaining().is_err() {
        println!("Budget exhausted at iteration {}", iteration);
        break;
    }
    
    let util = rb.utilisation();
    println!("Iteration {}: FLOP {:.1}%, Time {:.1}%",
        iteration,
        util.flop_ratio.unwrap() * 100.0,
        util.time_ratio.unwrap() * 100.0
    );
}

// 5. Estimate carbon footprint
let energy = EnergyModel::a100();
let carbon = energy.carbon_grams(rb.elapsed_ms, 1);
println!("Carbon footprint: {:.4} g CO₂", carbon);
}

15.4 Complete CLI Pipeline

# Verify, analyse, optimise, predict and export in one sequence
lift verify model.lif
lift analyse model.lif --format json > analysis.json
lift optimise model.lif --config production.lith --output optimised.lif
lift predict optimised.lif --device h100
lift export optimised.lif --backend llvm --output model.ll
lift export optimised.lif --backend onnx --output model.onnx

16. Concrete Examples

16.1 MLP (Multi-Layer Perceptron)

File tensor_mlp.lif:

#dialect tensor

module @mlp {
    func @forward(%x: tensor<1x784xf32>, %w1: tensor<784x256xf32>,
                  %b1: tensor<256xf32>, %w2: tensor<256x10xf32>,
                  %b2: tensor<10xf32>) -> tensor<1x10xf32> {
        %h1 = "tensor.matmul"(%x, %w1) : (tensor<1x784xf32>, tensor<784x256xf32>) -> tensor<1x256xf32>
        %h2 = "tensor.add"(%h1, %b1) : (tensor<1x256xf32>, tensor<256xf32>) -> tensor<1x256xf32>
        %h3 = "tensor.relu"(%h2) : (tensor<1x256xf32>) -> tensor<1x256xf32>
        %h4 = "tensor.matmul"(%h3, %w2) : (tensor<1x256xf32>, tensor<256x10xf32>) -> tensor<1x10xf32>
        %h5 = "tensor.add"(%h4, %b2) : (tensor<1x10xf32>, tensor<10xf32>) -> tensor<1x10xf32>
        %out = "tensor.softmax"(%h5) : (tensor<1x10xf32>) -> tensor<1x10xf32>
        return %out
    }
}

16.2 Self-Attention (Transformer)

File attention.lif:

#dialect tensor

module @transformer {
    func @self_attention(%q: tensor<1x128x64xf32>, %k: tensor<1x128x64xf32>,
                         %v: tensor<1x128x64xf32>, %norm_w: tensor<64xf32>)
                         -> tensor<1x128x64xf32> {
        %attn = "tensor.attention"(%q, %k, %v) : (...) -> tensor<1x128x64xf32>
        %normed = "tensor.layernorm"(%attn, %norm_w) : (...) -> tensor<1x128x64xf32>
        return %normed
    }
}

16.3 Bell State (Quantum)

File quantum_bell.lif:

#dialect quantum

module @bell_state {
    func @bell(%q0: qubit, %q1: qubit) -> (qubit, qubit) {
        %q2 = "quantum.h"(%q0) : (qubit) -> qubit
        %q3, %q4 = "quantum.cx"(%q2, %q1) : (qubit, qubit) -> (qubit, qubit)
        return %q3, %q4
    }
}

16.4 Production Configuration

File production.lith:

[target]
backend = "cuda"
device = "H100"
precision = "fp16"

[budget]
max_flops = 1000000000000
max_memory_bytes = 80000000000
max_time_ms = 100.0

[optimisation]
level = O3
max_iterations = 20

[simulation]
shape_propagation = true
flop_counting = true
memory_analysis = true
noise_simulation = true

[quantum]
topology = "heavy_hex"
num_qubits = 127
shots = 4096

Summary of Combinations by Task

LIFT User Manual — Complete Usage Guide

LIFT — Language for Intelligent Frameworks and Technologies Version 0.4.8

This manual is the definitive reference for every use case of the LIFT compiler framework. It presents real-world problems, explains how LIFT solves them, and provides working code examples for each scenario.

Table of Contents

1. What is LIFT and Why Does It Exist?
2. Installation and Setup
3. Core Concepts
4. The .lif Source Language
5. Use Case 1 — Neural Network Optimisation
6. Use Case 2 — Transformer Attention and FlashAttention
7. Use Case 3 — Quantum Circuit Design and Noise Analysis
8. Use Case 4 — Hybrid Classical-Quantum (VQE)
9. Use Case 5 — Model Import
10. Use Case 6 — Performance Prediction
11. Use Case 7 — Quantised Inference
12. Use Case 8 — Backend Export (LLVM, ONNX, QASM)
13. Use Case 9 — Energy and Carbon Estimation
14. Use Case 10 — Device Topology and Routing
15. Use Case 11 — Diffusion and GNN Models
16. Use Case 12 — Budget-Constrained Compilation
17. Use Case 13 — End-to-End Pipelines
18. Configuration with .lith Files
19. CLI Reference
20. Programmatic Model Generation
21. Complete API Reference
22. Troubleshooting

1. What is LIFT and Why Does It Exist?

1.1 The Problem

Modern computing faces a fragmentation crisis:

• AI/ML frameworks (PyTorch, TensorFlow, ONNX) produce models in incompatible formats with no unified optimisation pipeline.
• Quantum computing (Qiskit, Cirq, OpenQASM) uses entirely separate toolchains with no connection to classical compilation.
• Hybrid algorithms (VQE, QAOA, Quantum ML) require ad-hoc glue code between classical and quantum systems.
• Performance analysis is fragmented — different tools for GPU profiling, quantum fidelity, and cost modelling.

1.2 How LIFT Solves It

LIFT provides a single SSA-based intermediate representation spanning three dialects:

The unified pipeline: import → verify → analyse → optimise → predict → export.

1.3 Architecture

                    ┌──────────┐
                    │ lift-cli │  ← User interface
                    └────┬─────┘
           ┌─────────────┼─────────────┐
    ┌──────┴──────┐ ┌────┴────┐ ┌──────┴──────┐
    │ lift-import │ │lift-opt │ │ lift-export │
    └──────┬──────┘ └────┬────┘ └──────┬──────┘
    ┌──────┴──────┐ ┌────┴────┐ ┌──────┴──────┐
    │  lift-ast   │ │lift-sim │ │lift-predict │
    └──────┬──────┘ └────┬────┘ └──────┬──────┘
    ┌──────┴─────────────┴─────────────┴──────┐
    │              lift-core                    │
    ├──────────┬──────────┬───────────────────┤
    │lift-tensor│lift-quantum│  lift-hybrid    │
    └──────────┴──────────┴───────────────────┘

2. Installation and Setup

2.1 Prerequisites

• Rust 1.80+ — install via rustup

2.2 Build

git clone https://github.com/rustnew/Lift.git
cd Lift
cargo build --release
cargo test --workspace   # 541 tests, all pass

2.3 Use as a Library

[dependencies]
lift-core    = { path = "crates/lift-core" }
lift-ast     = { path = "crates/lift-ast" }
lift-tensor  = { path = "crates/lift-tensor" }
lift-quantum = { path = "crates/lift-quantum" }
lift-hybrid  = { path = "crates/lift-hybrid" }
lift-opt     = { path = "crates/lift-opt" }
lift-sim     = { path = "crates/lift-sim" }
lift-predict = { path = "crates/lift-predict" }
lift-import  = { path = "crates/lift-import" }
lift-export  = { path = "crates/lift-export" }
lift-config  = { path = "crates/lift-config" }

3. Core Concepts

3.1 SSA IR

LIFT uses Static Single Assignment — every value is defined exactly once:

%h1 = "tensor.matmul"(%x, %w) : (tensor<1x784xf32>, tensor<784x256xf32>) -> tensor<1x256xf32>
%h2 = "tensor.relu"(%h1) : (tensor<1x256xf32>) -> tensor<1x256xf32>

3.2 The Context

The Context is the central data structure holding all IR elements:

#![allow(unused)]
fn main() {
use lift_core::{Context, Attributes, Location};
use lift_core::types::{Dimension, DataType, MemoryLayout};

let mut ctx = Context::new();

// Create types
let tensor_ty = ctx.make_tensor_type(
    vec![Dimension::Constant(1), Dimension::Constant(784)],
    DataType::FP32, MemoryLayout::Contiguous,
);
let qubit_ty = ctx.make_qubit_type();

// Create block, add arguments
let block = ctx.create_block();
let x = ctx.create_block_arg(block, tensor_ty);

// Create operation
let (op, results) = ctx.create_op(
    "tensor.relu", "tensor",
    vec![x], vec![tensor_ty],
    Attributes::new(), Location::unknown(),
);
ctx.add_op_to_block(block, op);
}

3.3 Linear Qubit Types

Problem: Qubits cannot be copied (no-cloning theorem). Classical IRs allow reuse, violating physics.

Solution: LIFT enforces linear types for qubits — each consumed exactly once:

#![allow(unused)]
fn main() {
let mut ctx = Context::new();
let qubit_ty = ctx.make_qubit_type();
let block = ctx.create_block();
let q0 = ctx.create_block_arg(block, qubit_ty);

// First use — OK
let (op1, _) = ctx.create_op("quantum.x", "quantum",
    vec![q0], vec![qubit_ty], Attributes::new(), Location::unknown());
ctx.add_op_to_block(block, op1);

// Second use of same q0 — LINEARITY VIOLATION
let (op2, _) = ctx.create_op("quantum.h", "quantum",
    vec![q0], vec![qubit_ty], Attributes::new(), Location::unknown());
ctx.add_op_to_block(block, op2);

let result = lift_core::verifier::verify(&ctx);
assert!(result.is_err());  // VerifyError::LinearityViolation
}

3.4 Verification

The verifier checks SSA, dominance, and linearity:

#![allow(unused)]
fn main() {
use lift_core::verifier;

match verifier::verify(&ctx) {
    Ok(()) => println!("IR is valid"),
    Err(errors) => {
        for err in &errors {
            eprintln!("Error: {}", err);
        }
    }
}
}

3.5 Printing the IR

#![allow(unused)]
fn main() {
use lift_core::printer::print_ir;
let output = print_ir(&ctx);
println!("{}", output);
}

4. The .lif Source Language

4.1 Syntax

#dialect tensor

module @name {
    func @function(%arg0: type0, %arg1: type1) -> return_type {
        %result = "dialect.op"(%arg0, %arg1) {attr = value}
            : (type0, type1) -> return_type
        return %result
    }
}

4.2 Types

4.3 Parsing Programmatically

#![allow(unused)]
fn main() {
use lift_ast::{Lexer, Parser, IrBuilder};
use lift_core::Context;

let source = std::fs::read_to_string("examples/tensor_mlp.lif").unwrap();
let tokens = Lexer::new(&source).tokenize().to_vec();
let program = Parser::new(tokens).parse().unwrap();

let mut ctx = Context::new();
IrBuilder::new().build_program(&mut ctx, &program).unwrap();
lift_core::verifier::verify(&ctx).unwrap();
}

5. Use Case 1 — Neural Network Optimisation

5.1 Problem

You have a Multi-Layer Perceptron (MLP) and want to:

1. Represent it as LIFT IR
2. Verify correctness
3. Fuse MatMul + Bias + ReLU into a single kernel
4. Measure FLOPs and memory

5.2 The MLP in .lif

File: examples/tensor_mlp.lif

#dialect tensor

module @mlp {
    func @forward(%x: tensor<1x784xf32>, %w1: tensor<784x256xf32>, %b1: tensor<256xf32>,
                  %w2: tensor<256x10xf32>, %b2: tensor<10xf32>) -> tensor<1x10xf32> {
        %h1 = "tensor.matmul"(%x, %w1) : (tensor<1x784xf32>, tensor<784x256xf32>) -> tensor<1x256xf32>
        %h2 = "tensor.add"(%h1, %b1) : (tensor<1x256xf32>, tensor<256xf32>) -> tensor<1x256xf32>
        %h3 = "tensor.relu"(%h2) : (tensor<1x256xf32>) -> tensor<1x256xf32>
        %h4 = "tensor.matmul"(%h3, %w2) : (tensor<1x256xf32>, tensor<256x10xf32>) -> tensor<1x10xf32>
        %h5 = "tensor.add"(%h4, %b2) : (tensor<1x10xf32>, tensor<10xf32>) -> tensor<1x10xf32>
        %out = "tensor.softmax"(%h5) : (tensor<1x10xf32>) -> tensor<1x10xf32>
        return %out
    }
}

5.3 Build the IR Programmatically

#![allow(unused)]
fn main() {
use lift_core::{Context, Attributes, Location};
use lift_core::types::{Dimension, DataType, MemoryLayout};

let mut ctx = Context::new();

let input_ty = ctx.make_tensor_type(
    vec![Dimension::Constant(1), Dimension::Constant(784)],
    DataType::FP32, MemoryLayout::Contiguous,
);
let w1_ty = ctx.make_tensor_type(
    vec![Dimension::Constant(784), Dimension::Constant(256)],
    DataType::FP32, MemoryLayout::Contiguous,
);
let b1_ty = ctx.make_tensor_type(
    vec![Dimension::Constant(256)],
    DataType::FP32, MemoryLayout::Contiguous,
);
let h1_ty = ctx.make_tensor_type(
    vec![Dimension::Constant(1), Dimension::Constant(256)],
    DataType::FP32, MemoryLayout::Contiguous,
);

let block = ctx.create_block();
let x  = ctx.create_block_arg(block, input_ty);
let w1 = ctx.create_block_arg(block, w1_ty);
let b1 = ctx.create_block_arg(block, b1_ty);

// MatMul
let (mm_op, mm_res) = ctx.create_op(
    "tensor.matmul", "tensor", vec![x, w1], vec![h1_ty],
    Attributes::new(), Location::unknown(),
);
ctx.add_op_to_block(block, mm_op);

// Add bias
let (add_op, add_res) = ctx.create_op(
    "tensor.add", "tensor", vec![mm_res[0], b1], vec![h1_ty],
    Attributes::new(), Location::unknown(),
);
ctx.add_op_to_block(block, add_op);

// ReLU
let (relu_op, _relu_res) = ctx.create_op(
    "tensor.relu", "tensor", vec![add_res[0]], vec![h1_ty],
    Attributes::new(), Location::unknown(),
);
ctx.add_op_to_block(block, relu_op);

lift_core::verifier::verify(&ctx).expect("Verification failed");
}

5.4 Tensor Fusion: Fuse MatMul + Bias + ReLU

Problem: Three separate GPU kernels waste memory bandwidth on intermediate results.

Solution: The TensorFusion pass detects matmul → add → relu and fuses them:

#![allow(unused)]
fn main() {
use lift_core::pass::PassManager;
use lift_opt::{Canonicalize, ConstantFolding, TensorFusion, DeadCodeElimination};

let mut pm = PassManager::new();
pm.add_pass(Box::new(Canonicalize));        // x + 0 → x, x * 1 → x
pm.add_pass(Box::new(ConstantFolding));     // fold constants at compile time
pm.add_pass(Box::new(TensorFusion));        // matmul + bias + relu → fused
pm.add_pass(Box::new(DeadCodeElimination)); // remove dead ops

let results = pm.run_all(&mut ctx);
for (name, result) in &results {
    println!("  {}: {:?}", name, result);
}
}

Before fusion:

%h1 = "tensor.matmul"(%x, %w1)  : (...) -> tensor<1x256xf32>
%h2 = "tensor.add"(%h1, %b1)    : (...) -> tensor<1x256xf32>
%h3 = "tensor.relu"(%h2)        : (...) -> tensor<1x256xf32>

After fusion:

%h3 = "tensor.fused_matmul_bias_relu"(%x, %w1, %b1) : (...) -> tensor<1x256xf32>

5.5 Analyse Resource Usage

#![allow(unused)]
fn main() {
use lift_sim::analysis::analyze_module;

let report = analyze_module(&ctx);
println!("Total ops: {}", report.num_ops);
println!("Tensor ops: {}", report.num_tensor_ops);
println!("Total FLOPs: {}", report.total_flops);
println!("Total memory: {} bytes", report.total_memory_bytes);
println!("Peak memory: {} bytes", report.peak_memory_bytes);

for (op_name, count) in &report.op_breakdown {
    println!("  {}: {}", op_name, count);
}
}

5.6 Shape Inference and FLOPs Counting

LIFT computes shapes and FLOPs for every tensor operation:

#![allow(unused)]
fn main() {
use lift_tensor::{TensorOp, ShapeInference};
use lift_core::types::{TensorTypeInfo, Dimension, DataType, MemoryLayout};

let a = TensorTypeInfo {
    shape: vec![Dimension::Constant(2), Dimension::Constant(3)],
    dtype: DataType::FP32, layout: MemoryLayout::Contiguous,
};
let b = TensorTypeInfo {
    shape: vec![Dimension::Constant(3), Dimension::Constant(4)],
    dtype: DataType::FP32, layout: MemoryLayout::Contiguous,
};

// Shape inference
let output = ShapeInference::infer_output_shape(&TensorOp::MatMul, &[&a, &b]).unwrap();
// output[0].shape = [2, 4]

// FLOPs: 2*M*N*K = 2*2*4*3 = 48
let flops = ShapeInference::compute_flops(&TensorOp::MatMul, &[&a, &b]);
assert_eq!(flops, Some(48));

// Memory bytes: input A + input B + output
let mem = ShapeInference::compute_memory_bytes(&TensorOp::MatMul, &[&a, &b]);
println!("Memory: {:?} bytes", mem);
}

5.7 All 110 Tensor Operations

6. Use Case 2 — Transformer Attention and FlashAttention

6.1 Problem

Transformers use self-attention which scales O(n²) in memory. For long sequences (>512 tokens), this becomes the bottleneck.

6.2 Attention in .lif

File: examples/attention.lif

#dialect tensor

module @transformer {
    func @self_attention(%q: tensor<1x128x64xf32>, %k: tensor<1x128x64xf32>,
                         %v: tensor<1x128x64xf32>, %norm_w: tensor<64xf32>)
                         -> tensor<1x128x64xf32> {
        %attn = "tensor.attention"(%q, %k, %v)
            : (tensor<1x128x64xf32>, tensor<1x128x64xf32>, tensor<1x128x64xf32>)
            -> tensor<1x128x64xf32>
        %normed = "tensor.layernorm"(%attn, %norm_w)
            : (tensor<1x128x64xf32>, tensor<64xf32>) -> tensor<1x128x64xf32>
        return %normed
    }
}

6.3 FlashAttention Pass

The FlashAttentionPass replaces tensor.attention with tensor.flash_attention when sequence length exceeds a threshold:

#![allow(unused)]
fn main() {
use lift_opt::FlashAttentionPass;
use lift_core::pass::PassManager;

let mut pm = PassManager::new();
pm.add_pass(Box::new(FlashAttentionPass { seq_len_threshold: 512 }));
pm.run_all(&mut ctx);
// tensor.attention → tensor.flash_attention
// Same FLOPs, O(n) memory instead of O(n²)
}

6.4 Attention Variants

6.5 FLOPs Calculation

For attention: FLOPs = 4 × B × H × S² × D

#![allow(unused)]
fn main() {
use lift_tensor::{TensorOp, ShapeInference};
use lift_core::types::{TensorTypeInfo, Dimension, DataType, MemoryLayout};

let q = TensorTypeInfo {
    shape: vec![
        Dimension::Constant(1),    // batch
        Dimension::Constant(8),    // heads
        Dimension::Constant(2048), // seq_len
        Dimension::Constant(64),   // head_dim
    ],
    dtype: DataType::FP32, layout: MemoryLayout::Contiguous,
};

let flops = ShapeInference::compute_flops(&TensorOp::Attention, &[&q, &q, &q]);
println!("Attention FLOPs: {:?}", flops);
// 4 × 1 × 8 × 2048 × 2048 × 64 ≈ 8.6 billion
}

7. Use Case 3 — Quantum Circuit Design and Noise Analysis

7.1 Problem

Design a quantum circuit, understand which gates your hardware supports, model noise, and estimate fidelity before executing on real devices.

7.2 Bell State in .lif

File: examples/quantum_bell.lif

#dialect quantum

module @bell_state {
    func @bell(%q0: qubit, %q1: qubit) -> (qubit, qubit) {
        %q2 = "quantum.h"(%q0) : (qubit) -> qubit
        %q3, %q4 = "quantum.cx"(%q2, %q1) : (qubit, qubit) -> (qubit, qubit)
        return %q3, %q4
    }
}

7.3 Build a Circuit Programmatically

#![allow(unused)]
fn main() {
use lift_core::{Context, Attributes, Location};

let mut ctx = Context::new();
let qubit_ty = ctx.make_qubit_type();

let block = ctx.create_block();
let q0 = ctx.create_block_arg(block, qubit_ty);
let q1 = ctx.create_block_arg(block, qubit_ty);

// Hadamard on q0
let (h_op, h_res) = ctx.create_op(
    "quantum.h", "quantum",
    vec![q0], vec![qubit_ty],
    Attributes::new(), Location::unknown(),
);
ctx.add_op_to_block(block, h_op);

// CNOT on (q0', q1)
let (cx_op, cx_res) = ctx.create_op(
    "quantum.cx", "quantum",
    vec![h_res[0], q1], vec![qubit_ty, qubit_ty],
    Attributes::new(), Location::unknown(),
);
ctx.add_op_to_block(block, cx_op);

lift_core::verifier::verify(&ctx).expect("Valid circuit");
}

7.4 All 48 Quantum Gates

7.5 Hardware-Native Gate Sets

#![allow(unused)]
fn main() {
use lift_quantum::QuantumGate;
use lift_quantum::gates::Provider;

// IBM Eagle/Kyoto native: {RZ, SX, X, CX, ECR}
let ibm = QuantumGate::native_basis(Provider::IbmEagle);

// Rigetti native: {RZ, RX, CZ, CPhase, XY}
let rigetti = QuantumGate::native_basis(Provider::Rigetti);

// IonQ native: {GPI, GPI2, MS}
let ionq = QuantumGate::native_basis(Provider::IonQ);

// Quantinuum native: {RZ, RX, RY, ZZ}
let quantinuum = QuantumGate::native_basis(Provider::Quantinuum);

for gate in ibm {
    println!("{} ({} qubit, parametric: {}, clifford: {})",
        gate.op_name(), gate.num_qubits(),
        gate.is_parametric(), gate.is_clifford());
}
}

7.6 Noise Models

Problem: Real quantum hardware introduces errors. You need to model them before execution.

#![allow(unused)]
fn main() {
use lift_quantum::{NoiseModel, GateNoise, CircuitNoise};

// Depolarizing noise (1Q gate error p = 0.001)
let noise_1q = NoiseModel::Depolarizing { p: 0.001 };
println!("1Q fidelity: {:.6}", noise_1q.fidelity()); // 0.999000

// Thermal relaxation
let thermal = NoiseModel::ThermalRelaxation {
    t1_us: 100.0, t2_us: 80.0, gate_time_us: 0.3,
};
println!("Thermal fidelity: {:.6}", thermal.fidelity());

// Composed noise
let combined = noise_1q.compose(&thermal);
println!("Combined fidelity: {:.6}", combined.fidelity());

// Track noise across a full circuit
let mut circuit = CircuitNoise::new();
let g1q = GateNoise::with_depolarizing(0.999, 0.02);
let g2q = GateNoise::with_depolarizing(0.99, 0.3);

circuit.add_gate(&g1q, false);  // H  (1Q)
circuit.add_gate(&g2q, true);   // CX (2Q)

println!("Circuit fidelity: {:.6}", circuit.total_fidelity);
println!("Gate count: {}, 2Q gates: {}", circuit.gate_count, circuit.two_qubit_count);
println!("Meets 99% threshold: {}", circuit.meets_threshold(0.99));
}

All noise models:

7.7 Quantum Cost Model

#![allow(unused)]
fn main() {
use lift_sim::cost::QuantumCostModel;

// Superconducting (IBM-like): fast but lower fidelity
let sc = QuantumCostModel::superconducting_default();
// gate_time_1q: 0.02μs, gate_time_2q: 0.3μs, fidelity_1q: 0.999, fidelity_2q: 0.99

// Trapped-ion (IonQ-like): slow but very high fidelity
let ti = QuantumCostModel::trapped_ion_default();
// gate_time_1q: 10μs, gate_time_2q: 200μs, fidelity_1q: 0.9999, fidelity_2q: 0.999

// Neutral-atom: fast with moderate fidelity, many qubits
let na = QuantumCostModel::neutral_atom_default();
// gate_time_1q: 0.5μs, gate_time_2q: 1.0μs, fidelity_1q: 0.999, fidelity_2q: 0.995

// Compare fidelity for a 100-gate circuit (80×1Q + 20×2Q)
println!("Superconducting: {:.6}", sc.circuit_fidelity(80, 20));
println!("Trapped-ion:     {:.6}", ti.circuit_fidelity(80, 20));
println!("Neutral-atom:    {:.6}", na.circuit_fidelity(80, 20));
}

7.8 Gate Optimisation Passes

#![allow(unused)]
fn main() {
use lift_opt::{GateCancellation, RotationMerge, NoiseAwareSchedule, RealRouting};
use lift_core::pass::PassManager;
use lift_quantum::DeviceTopology;

let mut pm = PassManager::new();
pm.add_pass(Box::new(GateCancellation));     // H·H → I, X·X → I
pm.add_pass(Box::new(RotationMerge));        // Rz(a)·Rz(b) → Rz(a+b)
pm.add_pass(Box::new(NoiseAwareSchedule));   // schedule to minimise noise
pm.add_pass(Box::new(RealRouting::new(DeviceTopology::linear(4)))); // insert real SWAPs

let results = pm.run_all(&mut ctx);
for (name, result) in &results {
    println!("  {}: {:?}", name, result);
}
}

8. Use Case 4 — Hybrid Classical-Quantum (VQE)

8.1 Problem

VQE (Variational Quantum Eigensolver) is a hybrid algorithm requiring:

1. Encoding classical data into quantum states
2. Running a parametrised circuit (ansatz)
3. Computing gradients of quantum parameters
4. Iterating with a classical optimiser

8.2 Encoding Strategies

#![allow(unused)]
fn main() {
use lift_hybrid::encoding::{EncodingStrategy, EncodingConfig};

// Angle encoding: 1 qubit per feature, circuit depth 1
let angle = EncodingConfig::new(EncodingStrategy::AngleEncoding, 4);
println!("Qubits: {}, depth: {}", angle.num_qubits,
    angle.strategy.circuit_depth(4));
// 4 qubits, depth 1

// Amplitude encoding: log2(N) qubits, depth N
let amp = EncodingConfig::new(EncodingStrategy::AmplitudeEncoding, 16);
println!("Qubits: {}, depth: {}", amp.num_qubits,
    amp.strategy.circuit_depth(16));
// 4 qubits, depth 16

// IQP encoding: N qubits, depth 2N
let iqp = EncodingConfig::new(EncodingStrategy::IQPEncoding, 8);
println!("Qubits: {}, depth: {}", iqp.num_qubits,
    iqp.strategy.circuit_depth(8));
// 8 qubits, depth 16
}

8.3 Gradient Methods

#![allow(unused)]
fn main() {
use lift_hybrid::gradient::GradientMethod;

let num_params = 20;

// Parameter shift: exact, 2 evaluations per parameter
let ps = GradientMethod::ParameterShift;
println!("Evals: {}, exact: {}", ps.circuit_evaluations(num_params), ps.is_exact());
// 40, true

// SPSA: stochastic, only 2 evaluations total
let spsa = GradientMethod::SPSA;
println!("Evals: {}, exact: {}", spsa.circuit_evaluations(num_params), spsa.is_exact());
// 2, false

// Adjoint: exact, 1 evaluation (best for simulators)
let adj = GradientMethod::Adjoint;
println!("Evals: {}, exact: {}", adj.circuit_evaluations(num_params), adj.is_exact());
// 1, true
}

8.4 Joint Gradient (Classical + Quantum)

#![allow(unused)]
fn main() {
use lift_hybrid::gradient::{GradientMethod, JointGradientConfig};

let config = JointGradientConfig {
    classical_method: GradientMethod::Backprop,
    quantum_method: GradientMethod::ParameterShift,
    num_classical_params: 1000,
    num_quantum_params: 20,
};

println!("Total evaluations: {}", config.total_evaluations());
// 1 (backprop) + 40 (param shift) = 41
}

8.5 VQE Pipeline in .lif

#dialect tensor
#dialect quantum
#dialect hybrid

module @vqe {
    func @step(%data: tensor<1x4xf32>, %q0: qubit, %q1: qubit) -> f32 {
        // 1. Encode classical data
        %encoded = "hybrid.encode"(%data) : (tensor<1x4xf32>) -> tensor<1x4xf32>

        // 2. Variational ansatz
        %q2 = "quantum.ry"(%q0) {angle = 0.5} : (qubit) -> qubit
        %q3, %q4 = "quantum.cx"(%q2, %q1) : (qubit, qubit) -> (qubit, qubit)
        %q5 = "quantum.rz"(%q3) {angle = 1.2} : (qubit) -> qubit

        // 3. Measure expectation value
        %energy = "hybrid.measure_expectation"(%q5) : (qubit) -> f32

        // 4. Compute gradient
        %grad = "hybrid.parameter_shift"(%energy) : (f32) -> f32

        return %energy
    }
}

8.6 All 21 Hybrid Operations

9. Use Case 5 — Model Import

9.1 Problem

You have existing models in ONNX, PyTorch FX, or OpenQASM format and want to bring them into LIFT for unified optimisation and analysis.

These three importers are skeletons today (see docs/CAPABILITIES.md): they parse the source format enough to find the top-level node list, but they do not convert a single node into a LIFT operation — you get back a valid, empty module+function. The APIs below are real and tested; the conversion they're described as doing is the v0.5 roadmap item, not today's behaviour.

9.2 ONNX Import

#![allow(unused)]
fn main() {
use lift_import::OnnxImporter;
use lift_core::Context;

let json: serde_json::Value = serde_json::from_str(
    &std::fs::read_to_string("model.onnx.json").unwrap()
).unwrap();

let mut ctx = Context::new();
OnnxImporter::new()
    .import_from_json(&mut ctx, &json)
    .expect("ONNX import failed");
}

import_from_json takes an existing &mut Context and a pre-parsed serde_json::Value (not a file path, and it doesn't return a Context).

9.3 PyTorch FX Import

#![allow(unused)]
fn main() {
use lift_import::PyTorchFxImporter;
use lift_core::Context;

let json: serde_json::Value = serde_json::from_str(
    &std::fs::read_to_string("model_fx.json").unwrap()
).unwrap();

let mut ctx = Context::new();
PyTorchFxImporter::new()
    .import_from_json(&mut ctx, &json)
    .expect("FX import failed");
}

9.4 OpenQASM 3.0 Import

#![allow(unused)]
fn main() {
use lift_import::OpenQasm3Importer;
use lift_core::Context;
use lift_core::pass::PassManager;

let source = std::fs::read_to_string("circuit.qasm").unwrap();

let mut ctx = Context::new();
OpenQasm3Importer::new()
    .import_from_source(&mut ctx, &source)
    .expect("QASM import failed");

// Optimise the (currently empty) circuit
let mut pm = PassManager::new();
pm.add_pass(Box::new(lift_opt::GateCancellation));
pm.add_pass(Box::new(lift_opt::RotationMerge));
pm.run_all(&mut ctx);
}

import_from_source checks for a valid OPENQASM 3/OPENQASM 2 version header and creates an empty circuit function — it does not yet parse gates.

9.5 Import → Analyse → Compare

A common workflow: import a model, analyse it, optimise, then compare before/after:

#![allow(unused)]
fn main() {
use lift_sim::analysis::analyze_module;

// Before optimisation
let report_before = analyze_module(&ctx);
println!("Before: {} ops, {} FLOPs", report_before.num_ops, report_before.total_flops);

// Run passes...
pm.run_all(&mut ctx);

// After optimisation
let report_after = analyze_module(&ctx);
println!("After:  {} ops, {} FLOPs", report_after.num_ops, report_after.total_flops);
println!("Ops reduced: {:.1}%",
    (1.0 - report_after.num_ops as f64 / report_before.num_ops as f64) * 100.0);
}

10. Use Case 6 — Performance Prediction

10.1 Problem

Before running a model on expensive hardware, you need to know:

• How long will it take?
• Is it compute-bound or memory-bound?
• Will it fit in GPU memory?
• How many GPUs are needed?

10.2 Roofline Model (Classical)

#![allow(unused)]
fn main() {
use lift_sim::analysis::analyze_module;
use lift_sim::cost::CostModel;
use lift_predict::roofline::predict_performance;

let report = analyze_module(&ctx);

// NVIDIA A100
let a100 = CostModel::a100();
let pred_a100 = predict_performance(&report, &a100);

println!("=== A100 Prediction ===");
println!("Compute time: {:.4} ms", pred_a100.compute_time_ms);
println!("Memory time:  {:.4} ms", pred_a100.memory_time_ms);
println!("Predicted:    {:.4} ms", pred_a100.predicted_time_ms);
println!("Arithmetic intensity: {:.2} FLOP/byte", pred_a100.arithmetic_intensity);
println!("Bottleneck: {}", pred_a100.bottleneck); // "compute" or "memory"

// NVIDIA H100
let h100 = CostModel::h100();
let pred_h100 = predict_performance(&report, &h100);

println!("\n=== H100 Prediction ===");
println!("Predicted: {:.4} ms", pred_h100.predicted_time_ms);
println!("Speedup vs A100: {:.2}x",
    pred_a100.predicted_time_ms / pred_h100.predicted_time_ms);
}

10.3 GPU Profiles

10.4 Memory Fit and Multi-GPU Planning

#![allow(unused)]
fn main() {
let model = CostModel::a100();
let bytes = report.total_memory_bytes;

println!("Model size: {:.2} GB", bytes as f64 / 1e9);
println!("Fits in 1 GPU: {}", model.fits_in_memory(bytes));
println!("GPUs needed: {}", model.num_gpus_needed(bytes));

// Arithmetic intensity analysis
let ai = model.arithmetic_intensity(report.total_flops, bytes);
let ridge = model.flops_per_second / (model.memory_bandwidth_gb_s * 1e9);
println!("Arithmetic intensity: {:.2} FLOP/byte", ai);
println!("Ridge point: {:.2} FLOP/byte", ridge);
println!("Regime: {}", if ai >= ridge { "compute-bound" } else { "memory-bound" });
}

10.5 Quantum Performance Prediction

#![allow(unused)]
fn main() {
use lift_predict::roofline::predict_quantum;
use lift_sim::quantum_sim::QuantumAnalysis;
use lift_sim::cost::QuantumCostModel;

let analysis = QuantumAnalysis {
    num_qubits_used: 10,
    gate_count: 200,
    one_qubit_gates: 150,
    two_qubit_gates: 50,
    measurements: 10,
    circuit_depth: 30,
    estimated_fidelity: 0.92,
    ..Default::default() // covers three_qubit_gates and noise
};

let sc = QuantumCostModel::superconducting_default();
let prediction = predict_quantum(&analysis, &sc, 0.01); // 1% precision

println!("Estimated fidelity: {:.6}", prediction.estimated_fidelity);
println!("Circuit time: {:.2} μs", prediction.circuit_time_us);
println!("Shots for 1%% precision: {}", prediction.num_shots_for_precision);
println!("Total execution: {:.2} ms", prediction.total_execution_time_ms);

// Compare technologies
let ti = QuantumCostModel::trapped_ion_default();
let pred_ti = predict_quantum(&analysis, &ti, 0.01);
println!("\nTrapped-ion fidelity: {:.6} (vs {:.6} superconducting)",
    pred_ti.estimated_fidelity, prediction.estimated_fidelity);
println!("Trapped-ion time: {:.2} ms (vs {:.2} ms)",
    pred_ti.total_execution_time_ms, prediction.total_execution_time_ms);
}

11. Use Case 7 — Quantised Inference

11.1 Problem

FP32 models are too large and slow for deployment. You want INT8, INT4, or FP8 for faster inference.

11.2 Quantisation Operations

11.3 Quantised Inference in .lif

#dialect tensor

module @quantised_inference {
    func @forward(%x: tensor<1x784xf32>,
                  %w1_q: tensor<784x256xi8>,
                  %b1: tensor<256xf32>) -> tensor<1x256xf32> {
        // Dequantize INT8 weights to FP32
        %w1 = "tensor.dequantize"(%w1_q) : (tensor<784x256xi8>) -> tensor<784x256xf32>

        // Compute in FP32
        %h1 = "tensor.matmul"(%x, %w1) : (tensor<1x784xf32>, tensor<784x256xf32>) -> tensor<1x256xf32>
        %h2 = "tensor.add"(%h1, %b1) : (tensor<1x256xf32>, tensor<256xf32>) -> tensor<1x256xf32>
        %out = "tensor.relu"(%h2) : (tensor<1x256xf32>) -> tensor<1x256xf32>
        return %out
    }
}

11.4 Automatic Quantisation Pass

The QuantisationPass annotates ops that are safe to quantise:

#![allow(unused)]
fn main() {
use lift_opt::QuantisationPass;
use lift_core::pass::PassManager;

let mut pm = PassManager::new();
pm.add_pass(Box::new(QuantisationPass));
pm.run_all(&mut ctx);
}

11.5 Memory Savings

11.6 FP8 Formats

LIFT supports both FP8 variants:

#![allow(unused)]
fn main() {
use lift_tensor::ops::Fp8Format;

// E4M3: 4 exponent, 3 mantissa — higher precision, smaller range
// Best for: weights and activations in forward pass
let e4m3 = Fp8Format::E4M3;

// E5M2: 5 exponent, 2 mantissa — lower precision, larger range
// Best for: gradients in backward pass
let e5m2 = Fp8Format::E5M2;
}

12. Use Case 8 — Backend Export (LLVM, ONNX, QASM)

12.1 Problem

After optimisation, you need to compile the IR to executable code for GPU/CPU or quantum hardware.

12.2 Export to LLVM IR

Skeleton today (see docs/CAPABILITIES.md): the exporter emits function signatures with each tensor op as an LLVM comment (; tensor.matmul), not a real computation — no cuBLAS/cuDNN calls, no memory management. clang/llc will happily compile the output, but the resulting binary does nothing; it isn't yet a path to a working executable.

#![allow(unused)]
fn main() {
use lift_export::LlvmExporter;

let exporter = LlvmExporter::new();
let llvm_ir = exporter.export(&ctx).expect("LLVM export failed");

std::fs::write("output.ll", &llvm_ir).unwrap();
println!("Written {} bytes of LLVM IR", llvm_ir.len());
}

The output is syntactically valid LLVM IR, so tooling accepts it:

# Compiles cleanly — but runs as a no-op today, see the note above
clang -O3 output.ll -o model

# Or to object file
llc -O3 output.ll -filetype=obj -o model.o

12.3 Export to ONNX

#![allow(unused)]
fn main() {
use lift_export::OnnxExporter;

let exporter = OnnxExporter::new();
let onnx = exporter.export(&ctx).expect("ONNX export failed");

std::fs::write("model.onnx", &onnx).unwrap();

// JSON format also available
let onnx_json = exporter.export_json(&ctx).expect("ONNX JSON export failed");
std::fs::write("model_onnx.json", &onnx_json).unwrap();
}

The output is ONNX protobuf text format at opset version 21 — human-readable and diffable, using the same operator set (standard ops plus Microsoft extensions for attention/MoE/fused ops) that PyTorch, TensorFlow/tf2onnx, TensorRT, and ONNX Runtime all understand. Most of those tools load the binary protobuf .onnx format by default, though; export_json gives you JSON, and text-to-binary conversion (e.g. via onnx.load+save in Python, or protoc --encode) is a separate step this exporter doesn't do yet.

Key ONNX op mappings:

12.4 Export to OpenQASM 3.0

#![allow(unused)]
fn main() {
use lift_export::QasmExporter;

let exporter = QasmExporter::new();
let qasm = exporter.export(&ctx).expect("QASM export failed");

std::fs::write("circuit.qasm", &qasm).unwrap();
}

The output is standard OpenQASM 3.0 executable on:

• IBM Quantum (via Qiskit)
• Rigetti (via pyQuil)
• IonQ (via native API)
• Quantinuum (via TKET)
• Any OpenQASM 3.0 compatible platform

12.5 Full Export Pipeline

#![allow(unused)]
fn main() {
use lift_core::printer::print_ir;

// Print human-readable IR (for debugging)
let ir_text = print_ir(&ctx);
std::fs::write("debug.lif", &ir_text).unwrap();

// Export to LLVM (for tensor/classical ops)
let llvm = LlvmExporter::new().export(&ctx).expect("LLVM failed");
std::fs::write("model.ll", &llvm).unwrap();

// Export to ONNX (for PyTorch/TensorFlow/TensorRT interop)
let onnx = OnnxExporter::new().export(&ctx).expect("ONNX failed");
std::fs::write("model.onnx", &onnx).unwrap();

// Export to QASM (for quantum ops)
let qasm = QasmExporter::new().export(&ctx).expect("QASM failed");
std::fs::write("circuit.qasm", &qasm).unwrap();
}

13. Use Case 9 — Energy and Carbon Estimation

13.1 Problem

AI training and inference consume significant energy. You want to estimate the environmental impact before committing resources.

13.2 Classical Energy Model

#![allow(unused)]
fn main() {
use lift_sim::cost::{CostModel, EnergyModel};
use lift_sim::analysis::analyze_module;
use lift_predict::roofline::predict_performance;

let report = analyze_module(&ctx);
let cost = CostModel::h100();
let prediction = predict_performance(&report, &cost);

let energy = EnergyModel::h100();

// Single inference
let joules = energy.energy_joules(prediction.predicted_time_ms, 1);
let kwh = energy.energy_kwh(prediction.predicted_time_ms, 1);
let co2 = energy.carbon_grams(prediction.predicted_time_ms, 1);

println!("Single inference:");
println!("  Energy: {:.4} J ({:.8} kWh)", joules, kwh);
println!("  CO₂: {:.6} g", co2);

// Training: 8 GPUs for 72 hours
let train_ms = 72.0 * 3600.0 * 1000.0;
let train_kwh = energy.energy_kwh(train_ms, 8);
let train_co2_kg = energy.carbon_grams(train_ms, 8) / 1000.0;

println!("\nTraining (8× H100, 72h):");
println!("  Energy: {:.2} kWh", train_kwh);
println!("  CO₂: {:.2} kg", train_co2_kg);
println!("  Equivalent to: {:.0} km driven", train_co2_kg / 0.21);
}

13.3 Energy Profiles

13.4 Quantum Energy Estimation

#![allow(unused)]
fn main() {
let energy = EnergyModel::h100();

// Quantum circuit: dominated by cryogenic cooling
let circuit_time_us = 100.0;
let num_qubits = 127;
let quantum_joules = energy.quantum_energy_joules(circuit_time_us, num_qubits);

println!("Quantum energy: {:.4} J", quantum_joules);
println!("  Cryogenics: ~25 kW (dilution refrigerator)");
println!("  Control electronics: ~{:.0} W ({} qubits × 10W)", num_qubits as f64 * 10.0, num_qubits);
}

13.5 Compare Classical vs Quantum Energy

#![allow(unused)]
fn main() {
// Classical: matmul 1000×1000 on H100
let classical_time_ms = cost.compute_time_ms(2 * 1000 * 1000 * 1000);
let classical_j = energy.energy_joules(classical_time_ms, 1);

// Quantum: 100-gate circuit
let quantum_j = energy.quantum_energy_joules(100.0, 50);

println!("Classical (1000×1000 matmul): {:.4} J", classical_j);
println!("Quantum (100-gate circuit):   {:.4} J", quantum_j);
println!("Note: Quantum energy is dominated by cryogenic overhead,");
println!("not by the computation itself.");
}

14. Use Case 10 — Device Topology and Routing

14.1 Problem

Quantum hardware has limited connectivity — not all qubits can directly interact. Two-qubit gates between non-adjacent qubits require SWAP operations, increasing circuit depth and noise.

14.2 Built-in Topologies

#![allow(unused)]
fn main() {
use lift_quantum::DeviceTopology;

// Linear chain (nearest-neighbour)
let linear = DeviceTopology::linear(10);
println!("Linear: {} qubits, {} edges, diameter {}",
    linear.num_qubits, linear.edges.len(), linear.diameter());

// 2D Grid (superconducting chips)
let grid = DeviceTopology::grid(4, 4);
println!("Grid 4×4: {} qubits, avg connectivity {:.2}",
    grid.num_qubits, grid.avg_connectivity());

// IBM Heavy-hex (Eagle/Heron processors)
let heavy_hex = DeviceTopology::heavy_hex(127);
println!("Heavy-hex: {} qubits, {} edges",
    heavy_hex.num_qubits, heavy_hex.edges.len());

// All-to-all (trapped-ion systems)
let ion = DeviceTopology::all_to_all(32);
println!("All-to-all: {} qubits, {} edges, diameter {}",
    ion.num_qubits, ion.edges.len(), ion.diameter());

// Binary tree
let tree = DeviceTopology::tree(15);

// Custom topology
let custom = DeviceTopology::custom("my_chip",
    &[(0,1), (1,2), (2,3), (0,3), (1,3)], 0.995);
}

14.3 Routing and SWAP Cost

#![allow(unused)]
fn main() {
let topo = DeviceTopology::grid(5, 5);

// Are two qubits directly connected?
println!("0↔1 connected: {}", topo.are_connected(0, 1));  // true
println!("0↔6 connected: {}", topo.are_connected(0, 6));  // false

// Find shortest path between qubits
if let Some(path) = topo.shortest_path(0, 24) {
    println!("Path 0→24: {:?}", path);
    println!("SWAPs needed: {}", path.len() - 2);
}

// Number of SWAPs between any two qubits
let swaps = topo.swap_distance(0, 24);
println!("SWAP distance 0→24: {:?}", swaps);

// Neighbours of a qubit
println!("Neighbours of qubit 12: {:?}", topo.neighbors(12));

// Graph metrics
println!("Diameter: {}", topo.diameter());
println!("Avg connectivity: {:.2}", topo.avg_connectivity());
}

14.4 Real Routing Pass

The RealRouting pass inserts real quantum.swap operations so every 2-qubit gate ends up on connected physical qubits, using BFS shortest paths over your device's topology:

#![allow(unused)]
fn main() {
use lift_opt::RealRouting;
use lift_core::pass::PassManager;

let mut pm = PassManager::new();
pm.add_pass(Box::new(RealRouting::new(DeviceTopology::grid(5, 5))));
pm.run_all(&mut ctx);
}

(LayoutMapping is an older, annotation-only pass — it flags non-adjacent gates with needs_swap = true but never inserts a SWAP itself. RealRouting does the actual routing and supersedes it.)

15. Use Case 11 — Diffusion and GNN Models

15.1 Diffusion Models (Stable Diffusion)

Problem: Diffusion models use UNet architectures with timestep conditioning and cross-attention. Standard tensor frameworks lack first-class support.

#dialect tensor

module @unet_step {
    func @denoise(%x: tensor<1x4x64x64xf32>, %t: tensor<1xf32>,
                  %context: tensor<1x77x768xf32>) -> tensor<1x4x64x64xf32> {
        // Timestep embedding
        %t_emb = "tensor.timestep_embedding"(%t)
            : (tensor<1xf32>) -> tensor<1x320xf32>

        // UNet down block (conv + attention)
        %d1 = "tensor.unet_down_block"(%x, %t_emb)
            : (tensor<1x4x64x64xf32>, tensor<1x320xf32>) -> tensor<1x320x32x32xf32>

        // Cross-attention with text context
        %attn = "tensor.cross_attention"(%d1, %context, %context)
            : (tensor<1x320x32x32xf32>, tensor<1x77x768xf32>, tensor<1x77x768xf32>)
            -> tensor<1x320x32x32xf32>

        // UNet up block (transpose conv + skip connections)
        %u1 = "tensor.unet_up_block"(%attn, %t_emb)
            : (tensor<1x320x32x32xf32>, tensor<1x320xf32>) -> tensor<1x4x64x64xf32>

        return %u1
    }
}

Diffusion-specific ops:

15.2 Graph Neural Networks (GNN)

Problem: GNNs operate on irregular graph structures. Message passing between nodes requires specialised aggregation operations.

#dialect tensor

module @gcn {
    func @forward(%nodes: tensor<100x64xf32>,
                  %edges: tensor<2x500xi64>,
                  %w: tensor<64x32xf32>) -> tensor<100x32xf32> {
        // Message passing: aggregate neighbour features
        %msg = "tensor.gnn_message_passing"(%nodes, %edges)
            {aggregation = "mean"}
            : (tensor<100x64xf32>, tensor<2x500xi64>) -> tensor<100x64xf32>

        // Linear transform
        %h = "tensor.matmul"(%msg, %w)
            : (tensor<100x64xf32>, tensor<64x32xf32>) -> tensor<100x32xf32>
        %out = "tensor.relu"(%h)
            : (tensor<100x32xf32>) -> tensor<100x32xf32>
        return %out
    }

    func @graph_classify(%nodes: tensor<100x32xf32>) -> tensor<1x32xf32> {
        // Global pooling: graph-level representation
        %graph = "tensor.gnn_global_pooling"(%nodes)
            {aggregation = "mean"}
            : (tensor<100x32xf32>) -> tensor<1x32xf32>
        return %graph
    }
}

GNN operations:

16. Use Case 12 — Budget-Constrained Compilation

16.1 Problem

You have hard resource constraints: maximum FLOPs, memory, time, or minimum quantum fidelity. You want to enforce these during compilation.

16.2 Static Budget

#![allow(unused)]
fn main() {
use lift_sim::cost::Budget;
use lift_sim::analysis::analyze_module;

let budget = Budget {
    max_flops: Some(1_000_000_000),          // 1 GFLOP
    max_memory_bytes: Some(1_073_741_824),   // 1 GB
    max_time_ms: Some(100.0),                // 100 ms
    min_fidelity: Some(0.99),                // 99% fidelity
    max_circuit_depth: Some(100),
};

let report = analyze_module(&ctx);

match budget.check_flops(report.total_flops) {
    Ok(()) => println!("FLOP budget OK"),
    Err(e) => println!("WARNING: {}", e),
}

match budget.check_memory(report.total_memory_bytes) {
    Ok(()) => println!("Memory budget OK"),
    Err(e) => println!("WARNING: {}", e),
}
}

16.3 Reactive Budget (Dynamic Tracking)

For iterative algorithms (VQE, QAOA) where resources are consumed over time:

#![allow(unused)]
fn main() {
use lift_sim::cost::{Budget, ReactiveBudget};

let budget = Budget {
    max_flops: Some(10_000_000_000),       // 10 GFLOP
    max_memory_bytes: Some(4_294_967_296), // 4 GB
    max_time_ms: Some(5000.0),             // 5 seconds
    min_fidelity: Some(0.90),              // 90% fidelity
    max_circuit_depth: None,
};

let mut tracker = ReactiveBudget::new(budget);

for iteration in 0..100 {
    // Simulate consuming resources each iteration
    tracker.consume(
        100_000_000,  // 100M FLOPs
        500_000_000,  // 500MB memory
        50.0,         // 50ms
        0.999,        // fidelity factor
    );

    match tracker.check_remaining() {
        Ok(()) => {
            let util = tracker.utilisation();
            if iteration % 10 == 0 {
                println!("Iter {}: FLOP {:.0}%, time {:.0}%",
                    iteration,
                    util.flop_ratio.unwrap_or(0.0) * 100.0,
                    util.time_ratio.unwrap_or(0.0) * 100.0,
                );
            }
        }
        Err(e) => {
            println!("Budget exceeded at iteration {}: {}", iteration, e);
            break;
        }
    }
}

// Query remaining budget
if let Some(remaining) = tracker.remaining_flops() {
    println!("Remaining FLOPs: {}", remaining);
}
if let Some(remaining) = tracker.remaining_time_ms() {
    println!("Remaining time: {:.2} ms", remaining);
}
}

17. Use Case 13 — End-to-End Pipelines

17.1 AI Pipeline: Import → Verify → Optimise → Predict → Export

#![allow(unused)]
fn main() {
use lift_import::OnnxImporter;
use lift_core::{Context, verifier, pass::PassManager};
use lift_sim::analysis::analyze_module;
use lift_sim::cost::CostModel;
use lift_predict::roofline::predict_performance;
use lift_export::LlvmExporter;

// ── 1. Import (skeleton today — produces an empty module+function,
//    see docs/CAPABILITIES.md) ──
let onnx_json: serde_json::Value = serde_json::from_str(
    &std::fs::read_to_string("model.onnx.json").unwrap()
).unwrap();
let mut ctx = Context::new();
OnnxImporter::new()
    .import_from_json(&mut ctx, &onnx_json)
    .expect("Import failed");

// ── 2. Verify ──
verifier::verify(&ctx).expect("Verification failed");

// ── 3. Analyse (before) ──
let before = analyze_module(&ctx);

// ── 4. Optimise ──
let mut pm = PassManager::new();
pm.add_pass(Box::new(lift_opt::Canonicalize));
pm.add_pass(Box::new(lift_opt::ConstantFolding));
pm.add_pass(Box::new(lift_opt::TensorFusion));
pm.add_pass(Box::new(lift_opt::FlashAttentionPass::default()));
pm.add_pass(Box::new(lift_opt::CommonSubexprElimination));
pm.add_pass(Box::new(lift_opt::DeadCodeElimination));

for (name, result) in pm.run_all(&mut ctx) {
    println!("  {}: {:?}", name, result);
}

// ── 5. Analyse (after) ──
let after = analyze_module(&ctx);
println!("Ops: {} → {} ({:.1}% reduction)",
    before.num_ops, after.num_ops,
    (1.0 - after.num_ops as f64 / before.num_ops as f64) * 100.0);

// ── 6. Predict ──
let h100 = CostModel::h100();
let prediction = predict_performance(&after, &h100);
println!("H100: {:.4} ms ({}-bound)", prediction.predicted_time_ms, prediction.bottleneck);

// ── 7. Export ──
let llvm = LlvmExporter::new().export(&ctx).expect("Export failed");
std::fs::write("model.ll", &llvm).unwrap();
println!("Exported {} bytes of LLVM IR", llvm.len());
}

17.2 Quantum Pipeline: Parse → Verify → Optimise → Predict → Export

#![allow(unused)]
fn main() {
use lift_ast::{Lexer, Parser, IrBuilder};
use lift_core::{Context, verifier, pass::PassManager};
use lift_quantum::DeviceTopology;
use lift_sim::cost::QuantumCostModel;
use lift_export::QasmExporter;

// ── 1. Parse ──
let source = std::fs::read_to_string("circuit.lif").unwrap();
let tokens = Lexer::new(&source).tokenize().to_vec();
let program = Parser::new(tokens).parse().unwrap();
let mut ctx = Context::new();
IrBuilder::new().build_program(&mut ctx, &program).unwrap();

// ── 2. Verify (SSA + linearity) ──
verifier::verify(&ctx).expect("Circuit verification failed");

// ── 3. Optimise ──
let mut pm = PassManager::new();
pm.add_pass(Box::new(lift_opt::GateCancellation));
pm.add_pass(Box::new(lift_opt::RotationMerge));
pm.add_pass(Box::new(lift_opt::NoiseAwareSchedule));
pm.add_pass(Box::new(lift_opt::RealRouting::new(DeviceTopology::linear(8))));

for (name, result) in pm.run_all(&mut ctx) {
    println!("  {}: {:?}", name, result);
}

// ── 4. Predict fidelity ──
let sc = QuantumCostModel::superconducting_default();
let fidelity = sc.circuit_fidelity(30, 10); // 30×1Q + 10×2Q
println!("Predicted fidelity: {:.6}", fidelity);

// ── 5. Export to OpenQASM 3.0 ──
let qasm = QasmExporter::new().export(&ctx).unwrap();
std::fs::write("circuit.qasm", &qasm).unwrap();
}

17.3 Hybrid Pipeline: VQE with Energy Estimation

#![allow(unused)]
fn main() {
use lift_core::{Context, Attributes, Location};
use lift_sim::cost::{CostModel, QuantumCostModel, EnergyModel, Budget, ReactiveBudget};
use lift_hybrid::gradient::GradientMethod;
use lift_hybrid::encoding::{EncodingStrategy, EncodingConfig};

// ── Setup ──
let encoding = EncodingConfig::new(EncodingStrategy::AngleEncoding, 4);
let gradient = GradientMethod::ParameterShift;
let num_params = 12;

println!("Encoding: {} qubits, depth {}",
    encoding.num_qubits, encoding.strategy.circuit_depth(4));
println!("Gradient: {} evaluations per iteration",
    gradient.circuit_evaluations(num_params));

// ── Budget ──
let budget = Budget {
    max_flops: None,
    max_memory_bytes: None,
    max_time_ms: Some(60_000.0),  // 60 seconds
    min_fidelity: Some(0.80),
    max_circuit_depth: None,
};
let mut tracker = ReactiveBudget::new(budget);

// ── Cost models ──
let qcm = QuantumCostModel::superconducting_default();
let energy = EnergyModel::a100();

// ── VQE loop ──
let evals_per_iter = gradient.circuit_evaluations(num_params);
let time_per_eval_us = qcm.circuit_time_us(10, 5, 1, 8);
let fidelity_per_eval = qcm.circuit_fidelity(10, 5);

for iter in 0..100 {
    let iter_time_ms = (evals_per_iter as f64 * time_per_eval_us) / 1000.0;
    tracker.consume(0, 0, iter_time_ms, fidelity_per_eval);

    if let Err(e) = tracker.check_remaining() {
        println!("Stopped at iteration {}: {}", iter, e);
        break;
    }
}

println!("Total time: {:.2} ms", tracker.elapsed_ms);
println!("Final fidelity: {:.6}", tracker.current_fidelity);
let total_energy_j = energy.quantum_energy_joules(
    tracker.elapsed_ms * 1000.0, encoding.num_qubits);
println!("Energy: {:.2} J", total_energy_j);
}

18. Configuration with .lith Files

18.1 Overview

LIFT uses .lith configuration files to control the compilation pipeline. The format is INI-like with [section] headers and key = value pairs. Comments use # or //.

18.2 Full .lith Example

# my_project.lith — LIFT compilation configuration

[target]
backend = "llvm"        # llvm | qasm
device = "H100"         # A100 | H100
precision = "fp16"      # fp32 | fp16 | bf16 | fp8 | int8

[budget]
max_flops = 1000000000000    # 1 TFLOP
max_memory_bytes = 80000000000  # 80 GB
max_time_ms = 100.0          # 100 ms
min_fidelity = 0.95          # 95% quantum fidelity

[optimisation]
level = O3                   # O0 | O1 | O2 | O3
max_iterations = 20

[simulation]
shape_propagation = true
flop_counting = true
memory_analysis = true
noise_simulation = true

[quantum]
topology = "heavy_hex"
num_qubits = 127
shots = 4096
error_mitigation = "zne"     # zero-noise extrapolation

18.3 Configuration Sections

18.4 Optimisation Levels

18.5 Loading Configuration Programmatically

#![allow(unused)]
fn main() {
use lift_config::{ConfigParser, LithConfig};

// From .lith file
let source = std::fs::read_to_string("project.lith").unwrap();
let config = ConfigParser::new().parse(&source).expect("Config parse error");

println!("Backend: {}", config.target.backend);
println!("Opt level: {:?}", config.optimisation.level);

if let Some(q) = &config.quantum {
    println!("Quantum: {} qubits, {} topology", q.num_qubits, q.topology);
}

// From JSON
let json = r#"{"target":{"backend":"qasm","device":null,"precision":"fp32"},
               "budget":{"max_flops":null,"max_memory_bytes":null,
                         "max_time_ms":null,"min_fidelity":0.99,
                         "max_circuit_depth":null},
               "optimisation":{"level":"O2","passes":["canonicalize","dce"],
                               "disabled_passes":[],"max_iterations":10},
               "simulation":{"enable_shape_propagation":true,
                             "enable_flop_counting":true,
                             "enable_memory_analysis":true,
                             "enable_noise_simulation":true},
               "quantum":{"topology":"grid","num_qubits":27,
                          "error_mitigation":null,"shots":4096}}"#;

let config = ConfigParser::new().parse_json(json).expect("JSON parse error");
}

18.6 Default Configuration

When no .lith file is provided, LIFT uses these defaults:

#![allow(unused)]
fn main() {
let config = LithConfig::default();
// target.backend = "llvm"
// target.precision = "fp32"
// optimisation.level = O2
// optimisation.passes = ["canonicalize", "constant-folding", "dce", "tensor-fusion"]
// simulation: all enabled
// quantum: None
}

19. CLI Reference

19.1 Installation

After building with cargo build --release, the binary is at target/release/lift-cli (the crate's package name — there's no [[bin]] override to shorten it to lift, and the same is true after cargo install lift-cli). Every lift <command> example below is exactly what you'd run, substituting lift-cli for lift — or cargo run --release -p lift-cli -- <command> from a source checkout, which is what examples/validate_all.sh and this repo's other docs use.

19.2 Commands

lift verify — Verify a .lif file

Checks SSA invariants, type correctness, and qubit linearity.

lift verify examples/tensor_mlp.lif

Output:

Verification passed: examples/tensor_mlp.lif
  Values: 11
  Operations: 7
  Blocks: 1
  Regions: 1

# Verbose mode
lift -v verify examples/quantum_bell.lif

lift analyse — Analyse resource usage

Computes FLOPs, memory, gate counts, and fidelity estimates.

lift analyse examples/tensor_mlp.lif

Output:

=== LIFT Analysis Report ===
File: examples/tensor_mlp.lif

Operations: 7
  Tensor ops: 6
  Quantum ops: 0
  Hybrid ops: 0

Compute:
  Total FLOPs: 407.10 KFLOP
  Total memory: 802.22 KiB
  Peak memory: 801.22 KiB

Op breakdown:
  tensor.matmul: 2
  tensor.add: 2
  core.return: 1
  tensor.softmax: 1
  tensor.relu: 1

JSON output:

lift analyse examples/tensor_mlp.lif --format json

lift print — Print human-readable IR

lift print examples/quantum_bell.lif

Output:

module @bell_state {
    func @bell(%v0: qubit, %v1: qubit) -> (qubit, qubit) {
        %v2 = "quantum.h"(%v0) : (qubit) -> qubit
        %v3, %v4 = "quantum.cx"(%v2, %v1) : (qubit, qubit) -> (qubit, qubit)
        "core.return"(%v3, %v4) : (qubit, qubit) -> ()
    }
}

(The entry block's arguments are printed once, in the function signature — not repeated as a separate ^bb0(...): label, since the .lif grammar has no block-label syntax.)

lift optimise — Run optimisation passes

# Default passes (O2)
lift optimise examples/tensor_mlp.lif -o optimised.lif

# With custom config
lift optimise examples/tensor_mlp.lif --config project.lith -o optimised.lif

Output:

Optimisation results:
  canonicalize -> unchanged
  constant-folding -> unchanged
  dce -> unchanged
  common-subexpr-elimination -> unchanged
  tensor-fusion -> changed
Output written to: optimised.lif

(O2, the default level, runs 5 passes: canonicalize, constant-folding, dce, cse, and tensor-fusion — see 18.4.)

lift predict — Predict performance

# Predict on A100 (default)
lift predict examples/tensor_mlp.lif

# Predict on H100
lift predict examples/tensor_mlp.lif --device h100

Output:

=== LIFT Performance Prediction ===
Device: H100

Compute time: 0.0000 ms
Memory time: 0.0002 ms
Predicted time: 0.0002 ms
Arithmetic intensity: 0.50 FLOP/byte
Bottleneck: memory

lift export — Export to backend

# Export to LLVM IR
lift export examples/tensor_mlp.lif --backend llvm -o model.ll

# Export to ONNX (opset 21)
lift export examples/tensor_mlp.lif --backend onnx -o model.onnx

# Export to OpenQASM 3.0
lift export examples/quantum_bell.lif --backend qasm -o circuit.qasm

# Print to stdout
lift export examples/quantum_bell.lif --backend qasm

19.3 Global Flags

20. Programmatic Model Generation

20.1 Using lift-codegen

The lift-codegen binary generates models from Rust code and exports all formats automatically:

cargo run --bin lift-codegen

Output:

╔═════════════════════════════════════════════════════════════╗
║  LIFT Code Generator — Models from Rust                      ║
╚═════════════════════════════════════════════════════════════╝

── Generating Phi-3-mini ──
  [WRITE] examples/phi3_generated.lif (2703 bytes)
  [VERIFY] OK — 20 ops, 32 values
  [ANALYSE] FLOPs=54.43 GFLOP, Memory=1.23 GiB, Ops=20
  [OPTIMISE] No changes
  [EXPORT] examples/phi3_generated.ll (5918 bytes)
  [EXPORT] examples/phi3_generated.onnx (10563 bytes)

── Generating VQE Circuit ──
  [WRITE] examples/vqe_generated.lif (345 bytes)
  [VERIFY] OK — 5 ops, 6 values
  [ANALYSE] FLOPs=0 FLOP, Memory=0 B, Ops=5
  [OPTIMISE] No changes
  [EXPORT] examples/vqe_generated.ll (3248 bytes)
  [EXPORT] examples/vqe_generated.onnx (2023 bytes)
  [EXPORT] examples/vqe_generated.qasm (120 bytes)

20.2 ModelBuilder API

Define models programmatically without writing .lif files:

#![allow(unused)]
fn main() {
use lift_core::model_builder::{ModelBuilder, tensor, tensor_2d, DataType};

let model = ModelBuilder::new("my_mlp")
    .function("forward")
        .param("x", tensor(&[1, 784], DataType::FP32))
        .param("w1", tensor_2d(784, 256, DataType::FP32))
        .param("b1", tensor(&[256], DataType::FP32))
        .op("tensor.matmul", &["x", "w1"], "h1", tensor(&[1, 256], DataType::FP32))
        .op("tensor.add", &["h1", "b1"], "h2", tensor(&[1, 256], DataType::FP32))
        .op("tensor.relu", &["h2"], "out", tensor(&[1, 256], DataType::FP32))
        .returns("out")
        .done();

// Write .lif source (parseable by lift-cli)
model.write_lif("my_mlp.lif").unwrap();

// Build IR context for full pipeline
let ctx = model.build_context();
lift_core::verifier::verify(&ctx).unwrap();

// Export to all backends
let llvm = lift_export::LlvmExporter::new().export(&ctx).unwrap();
let onnx = lift_export::OnnxExporter::new().export(&ctx).unwrap();
std::fs::write("my_mlp.ll", &llvm).unwrap();
std::fs::write("my_mlp.onnx", &onnx).unwrap();
}

21. Complete API Reference

21.1 Crate Overview

21.2 lift-core API

Context — central IR container:

Verifier:

Printer:

Pass Manager:

Types:

Attributes:

21.3 lift-tensor API

21.4 lift-quantum API

21.5 lift-hybrid API

21.6 lift-opt Passes

21.7 lift-sim API

21.8 lift-predict API

22. Troubleshooting

22.1 Common Verification Errors

22.2 Common Parse Errors

22.3 Optimisation Issues

22.4 Performance Debugging

#![allow(unused)]
fn main() {
// Check if compute-bound or memory-bound
let model = CostModel::a100();
let report = analyze_module(&ctx);

if model.is_compute_bound(report.total_flops, report.total_memory_bytes) {
    println!("Compute-bound: reduce FLOPs (quantise, prune, fuse)");
} else {
    println!("Memory-bound: reduce data movement (fusion, recomputation)");
}

// Check per-op breakdown
for (op, count) in &report.op_breakdown {
    println!("  {}: {} instances", op, count);
}
}

22.5 Quantum Debugging

#![allow(unused)]
fn main() {
use lift_quantum::{CircuitNoise, GateNoise};

// Track where fidelity drops
let mut circuit = CircuitNoise::new();
let g1q = GateNoise::with_depolarizing(0.999, 0.02);
let g2q = GateNoise::with_depolarizing(0.99, 0.3);

// After each gate, check fidelity
circuit.add_gate(&g1q, false);
println!("After H: fidelity = {:.6}", circuit.total_fidelity);

circuit.add_gate(&g2q, true);
println!("After CX: fidelity = {:.6}", circuit.total_fidelity);

// 2Q gates dominate fidelity loss!
}

Appendix A — Summary of All Operations

Total: 179 operations (110 + 48 + 21) across three dialects in a single unified IR.

Appendix B — Quick Reference Card

# Parse and verify
lift verify input.lif

# Analyse (FLOPs, memory, gates)
lift analyse input.lif

# Optimise with default passes
lift optimise input.lif -o optimised.lif

# Optimise with config
lift optimise input.lif --config project.lith -o optimised.lif

# Predict performance on H100
lift predict input.lif --device h100

# Export to LLVM
lift export input.lif --backend llvm -o model.ll

# Export to OpenQASM
lift export input.lif --backend qasm -o circuit.qasm

LIFT v0.4.8 — MIT License — https://github.com/rustnew/Lift

LIFT — Features, Capabilities, Limits, and Goals

Complete analysis based on the actual source code (67 Rust files, 13 crates, 541 tests).

Table of Contents

1. Overview
2. Processing Pipeline
3. Implemented Features
4. Partial Features
5. Missing Features
6. Current Limitations
7. Analysis Accuracy
8. What's Missing to Reach the Goals
9. Roadmap

1. Overview

LIFT is a unified IR compiler for classical AI + quantum computing, written in Rust (13 crates):

2. Processing Pipeline

.lif → Lexer → Parser → Builder → Context IR → Verification → Analysis → Optimisation → Export

Stage 1 — Lexer (COMPLETE)

Splits .lif text into tokens: keywords, #dialect directives, identifiers (@name/%var), literals, punctuation. Includes error handling.

Stage 2 — Parser (COMPLETE)

Builds the AST: dialect directives, modules, functions, operations with operands/attributes/type signatures. Tensor types (tensor<1x784xf32>), qubit, bit, hamiltonian. Error recovery.

Stage 3 — Builder (COMPLETE)

Converts the AST into internal IR inside the Context: SSA values, operations, blocks, regions, functions, modules.

Stage 4 — Context IR (COMPLETE)

Central structure with SlotMaps for values, ops, blocks, regions, types + StringInterner. Types: Integer (i1-i64), Float (f16-f64, fp8), Boolean, Void, Tuple, Function, Opaque (tensor, qubit, bit, hamiltonian).

Stage 5 — Verification (COMPLETE, 4 passes)

• SSA: every value defined exactly once, every use after its definition
• Well-formedness: no dangling references (ops ↔ values ↔ blocks ↔ regions)
• Linearity: every qubit consumed exactly once (no-cloning)
• Semantic: input arity of every operation checked against dialect signatures (core + tensor + quantum + hybrid), via verify_semantics() / verify_with_dialects()

13 error types: UndefinedValue, MultipleDefinition, DominanceViolation, TypeMismatch, LinearityViolation, QubitLeaked, BranchLinearityMismatch, DanglingReference, MissingTerminator, OrphanedOperation, OrphanedBlock, InvalidOperation, SemanticError.

Stage 6 — Static Analysis (COMPLETE)

Produces: total_flops, total_memory_bytes, peak_memory, num_ops per dialect, op_breakdown. Quantum: qubits, 1Q/2Q/3Q gates, measurements, circuit_depth, estimated_fidelity, accumulated noise.

Stage 7 — Optimisation (13 passes)

Level pipelines ([optimisation] level = O0|O1|O2|O3):

• O0: no passes
• O1: canonicalize, constant-folding, dce
• O2: O1 + cse, tensor-fusion
• O3: all 13 passes, including gate-decomposition and real-routing

Explicit passes take priority over the level; disabled_passes removes passes; unknown passes trigger a warning (OptimisationConfig::validate()). All passes are reachable from the CLI.

Stage 8 — Prediction (COMPLETE)

• GPU roofline: compute_time_ms, memory_time_ms, bottleneck. A100 (312 TFLOPS) and H100 (989 TFLOPS) models.
• Quantum: fidelity, circuit_time_us, shots needed. 3 models: superconducting, trapped ion, neutral atom.
• Budget: checks max FLOPs, max memory, max time, min fidelity. ReactiveBudget for real-time tracking.
• Both are reachable from the CLI via predict --energy and predict --quantum <hardware>.

Stage 9 — Export (3 backends)

• LLVM IR: ops emitted as comments with cuBLAS/cuDNN runtime calls
• ONNX: protobuf text, opset 21, 70+ operations mapped (standard + com.microsoft)
• OpenQASM 3.0: all 48 QuantumGate variants have a match arm (verified: no wildcard/unsupported fallback exists in the exporter) — 46 emit a real QASM gate instruction, and IfElse/ParamGate (control-flow/generic wrappers, not literal gates) emit a descriptive comment. Qubit indices are resolved by following each gate's actual SSA operand back to its owning qubit, not assigned from a counter

3. Implemented Features

3.1 Tensor Dialect — 110 operations

All 110 operations are defined in the TensorOp enum with name↔enum conversion, input count, classification. Working shape inference for: MatMul, Linear, Conv2D, Conv1D, DepthwiseConv2D, Attention, FlashAttention, MaxPool2D, GlobalAvgPool, BatchNorm, LayerNorm, RMSNorm, InstanceNorm, SparseMatMul, elementwise, ELU, LeakyReLU, Mish, HardSwish. Exact FLOP counting for MatMul, Linear, Conv2D, Attention, ReLU, elementwise, fused ops.

3.2 Quantum Dialect — 50+ gates

Gates: 9 standard 1Q + 7 parametric 1Q + 2 fixed-angle + 13 2Q gates + 2 3Q gates + 2 multi-controlled + 8 measurement/control + IonQ gates. Per-gate properties: num_qubits, is_parametric, is_self_inverse, is_clifford, is_entangling. 5 native sets (IBM, Rigetti, IonQ, Quantinuum, Simulator). Noise: GateNoise, CircuitNoise, KrausChannel (6 channels). Topology: linear, grid, heavy_hex, all_to_all, tree, custom + BFS. QEC: Surface, Steane, Shor, Repetition, LDPC.

3.3 Hybrid Dialect — 21 operations

Encode/Decode, 5 gradients, 4 variational algorithms, 2 transfers, 4 processing ops, CoExecute, 2 measurements. AnsatzType, SyncPolicy, FeatureMap, EncodingStrategy.

3.4 CLI — 6 commands

verify, analyse (text/JSON), print, optimise (with .lith), predict (A100/H100, --energy, --quantum), export (llvm/onnx/qasm).

3.5 Programmatic Generation — lift-codegen

lift-codegen binary: defines models from Rust via ModelBuilder, automatically generates .lif, .ll, .onnx, .qasm, .lith. 4 predefined models (Phi-3-mini, MLP, ResNet, VQE).

3.6 Energy Models

A100/H100 EnergyModel: energy in joules/kWh, CO2 grams, quantum energy (cryogenics). Connected to the CLI via predict --energy.

3.7 Tests — 541 tests, 0 failures

Types, operations, shapes, FLOPs, memory, gates, noise, topology, QEC, Kraus, benchmarks (GPT-2, LLaMA-7B, ResNet-50, BERT-base), O0-O3 pipeline, semantic verification, generic fusions, gate decomposition, non-consecutive cancellation/merge, real SWAP routing, printer/parser round-tripping. End-to-end validation: examples/validate_all.sh (105 checks, including all 13 passes).

4. Partial Features (code exists, incomplete)

4.1 LLVM IR Export — SKELETON

The exporter produces define void @func(ptr %arg0) { entry: ; tensor.matmul ret void }. Operations are emitted as comments, not real LLVM IR. No cuBLAS/cuDNN calls, no memory management.

4.2 ONNX Export — OPERATIONAL

The ONNX exporter produces protobuf text (opset 21) with 70+ operations mapped to standard ONNX and com.microsoft ops. Data types, shapes, and initializer nodes are generated. Missing: binary protobuf serialisation (currently text only), connected node graphs (nodes are emitted sequentially without explicit edges).

4.3 OpenQASM Export — all 48 gates handled, 2 as comments

Every QuantumGate variant has a match arm; 46 produce a real QASM gate instruction (including less-common ones like MCX, CSWAP, GPI/GPI2, XX/YY/ZZ). IfElse and ParamGate are control-flow/generic wrappers rather than fixed gates, so they emit a descriptive comment instead of a gate line. Gate order follows the real circuit order (block.ops) and qubit indices are resolved from each gate's actual operand chain, not a counter.

4.4 ONNX/PyTorch/QASM Import — SKELETONS

All 3 importers read the source format but create an empty module+function. No node/operation is actually converted into LIFT operations.

4.5 Layout Mapping — ANNOTATION ONLY

Adds needs_swap = true on non-adjacent 2Q gates. Does not actually insert SWAPs or route. (real-routing does the real work; layout-mapping remains a legacy annotation-only pass.)

4.6 Shape Inference — PARTIAL

Works for about 20 of the 110 operations. Missing: Conv3D, ConvTranspose2D, Reshape, Permute, Concat, Split, Slice, LSTM, GRU, RNN, FFT, SVD, Einsum, GNN, MoE, diffusion, quantisation, parallelism.

5. Missing Features

5.1 No Semantic Verification of Operand Shapes

The verifier checks SSA/well-formedness/linearity but does NOT check that tensor.matmul has 2 tensor inputs, that dimensions are compatible, that tensor.conv2d receives a 4D tensor, etc.

5.2 No Real Execution

LIFT cannot execute a program. It is purely an analysis compiler. There is no runtime, no interpreter, no GPU/QPU execution backend.

5.3 No Real Quantum Simulation

The quantum_sim module does static analysis (gate counting, fidelity estimation). It does NOT simulate quantum state (no state vector, no density matrix, no Monte Carlo simulation).

5.4 No Machine Code Generation

LLVM export does not produce executable code. This would require: lowering tensor operations to library calls (cuBLAS, cuDNN, oneDNN), memory management (allocation/deallocation), kernel scheduling, GPU launch code.

5.5 No Multi-File Support

A LIFT program is a single .lif file. No import/include system, no separate modules, no linking.

5.6 Limited Gate Decomposition Table

gate-decomposition correctly replaces the gates it knows about (H, T, Tdg, S, Sdg, Y, RX), but the decomposition table only covers those seven — every other non-native gate silently passes through unchanged, even when targeting hardware whose native set doesn't include it.

5.7 No GPU Scheduling

No placement of operations on CUDA streams, no compute/memory overlap, no operation parallelism.

5.8 No Automatic Differentiation

Gradient operations are declared (grad_matmul, grad_relu, etc.) but there is no autodiff system that automatically builds the backward graph from the forward graph.

5.9 No Data Handling

No data loading (datasets), no data loaders, no preprocessing. LIFT works purely on the computation graph.

6. Current Limitations

6.1 Structural Limitations

6.2 Cost Model Limitations

• The roofline model is a coarse approximation: it does not account for cache effects, kernel launch latency, or compute/memory overlap
• The quantum model uses average default noise parameters, not the real properties of the target device
• Fidelity estimation assumes independent noise per gate (no spatial/temporal correlations)

6.3 Verifier Limitations

• No operand type checking (input types vs. signature)
• No dimension-compatibility checking (tensor shapes)
• No complete dominance checking (CFG)
• Linearity verification does not exhaustively handle conditional branches
• Semantic verification checks arity but not tensor dimensions

6.4 Optimiser Limitations

• tensor-fusion recognises 5 patterns (matmul+bias+relu, matmul+bias, linear+gelu/silu, conv+bn+relu) but not attention+softmax or layernorm fusions
• gate-cancellation/rotation-merge detect non-consecutive pairs via the SSA chain, but not cross patterns (e.g. H·Rz)
• noise-aware-schedule sorts by gate time, not a real constrained scheduling algorithm
• real-routing inserts SWAPs (BFS) with an identity initial placement; no SABRE-style dynamic re-placement, no SWAP-direction correction for directionality

7. Analysis Accuracy

7.1 FLOP Counting

Overall accuracy: for pure Transformer models (GPT, BERT, LLaMA), FLOP-counting accuracy is excellent (error < 1%). For CNN models, it's good for Conv2D but misses other convolutions. For recurrent models (LSTM), FLOPs are not counted.

7.2 Memory Estimation

Computes element_count × byte_size(dtype) per tensor. Accurate for static memory but does not model: dynamically allocated intermediate activations, GPU memory fragmentation, workspace buffers (cuDNN), KV cache for LLM inference.

7.3 Time Prediction (Roofline)

7.4 Quantum Fidelity

Fidelity is estimated as the product of individual fidelities: F = ∏ f_gate × f_decoherence. This is an upper bound (real fidelity is often worse due to noise correlations, crosstalk, and readout errors).

8. What's Missing to Reach the Goals

LIFT's goal is: "Simulate → Predict → Optimise → Compile". Current state:

8.1 To Reach Simulate (100%)

1. Quantum state-vector simulator: multiply gate matrices onto a 2^n vector. Needed to validate quantum circuits.
2. Tensor interpreter: execute tensor ops with real, numpy-like values. Needed to validate AI models.
3. Monte Carlo simulation: to estimate the measurement distribution under noise.

8.2 To Reach Predict (100%)

1. Refined cost model: incorporate launch latency, L2 cache effects, overlapped scheduling.
2. Real hardware profiles: load real QPU properties (IBM Quantum calibration, per-qubit gate times).
3. Multi-GPU: inter-GPU communication model (NVLink, PCIe).
4. Advanced quantum prediction: correlated noise model, crosstalk, readout errors.

8.3 To Reach Optimise (100%)

1. More fusion patterns: matmul+gelu, conv+bn+relu, attention+layernorm.
2. Non-local gate cancellation: cancel pairs separated by operations on other qubits (commutation).
3. Real routing: implement SABRE or A* for layout mapping with SWAP insertion.
4. Broader gate decomposition: cover more than the current 7-gate table.
5. Pattern-based rewrite system: allow declarative transformation rules.

8.4 To Reach Compile (100%)

1. Tensor → LLVM lowering: generate real calls to cuBLAS/cuDNN/oneDNN.
2. Memory management: GPU memory allocator (allocation, deallocation, reuse).
3. Launch code: generate host code that orchestrates GPU kernels.
4. Quantum backend: generate code for IBM Qiskit Runtime, Amazon Braket, or Google Cirq.
5. Real import: convert real ONNX/PyTorch graphs into LIFT operations.

9. Roadmap (by priority)

Priority 1 — Quick fixes (low effort, immediate impact) — done

• Wire all 13 passes into the CLI (cmd_optimise, main.rs)
• Wire EnergyModel into the CLI (predict --energy, --num-gpus)
• Wire predict_quantum into the CLI (predict --quantum <hardware> --precision)
• crates/lift-demo/src/config.rs present and compiling (cargo build -p lift-demo)
• Fix the printer/parser round trip (optimise --output produced a .lif the parser couldn't read back)
• Fix QASM qubit indexing (counter → real SSA operand chain), gate order (slotmap → block.ops), and per-function qubit counting
• Fix gate-decomposition leaving the original gate in place next to its own decomposition

Priority 2 — Functional Import/Export (medium effort, high impact)

• Real ONNX import: map ONNX nodes to TensorOp
• Real PyTorch FX import: map FX nodes to TensorOp
• Full QASM export: all 48 gates handled (done — see §4.3)
• Real QASM import: parse gates and create quantum operations

Priority 3 — Advanced Optimisation (medium effort)

• More tensor fusion patterns
• Non-local gate cancellation (commutation)
• Broader gate decomposition table
• Real routing (SABRE)

Priority 4 — Simulation (high effort)

• State-vector simulator (up to ~25 qubits)
• Simplified tensor interpreter
• Shape inference for the remaining 90 operations

Priority 5 — Real Compilation (very high effort)

• Tensor → LLVM lowering with cuBLAS calls
• GPU memory management
• Quantum backend (Qiskit/Braket)

Final Summary

LIFT is a solid, well-tested IR analysis and optimisation framework, with excellent dialect coverage (tensor, quantum, hybrid) and a clean architecture. Its strength is static analysis (FLOPs, memory, fidelity, noise, cost). The addition of ONNX export (opset 21) and the lift-codegen binary now makes it possible to generate models programmatically and export them to 3 backends (LLVM, ONNX, QASM). What it mainly lacks is the ability to actually execute code: LLVM export is a skeleton, imports are empty, and there is no runtime. To become a complete "Simulate → Predict → Optimise → Compile" compiler, it needs real lowering, functional imports, and a simulator.

This document is a complete and honest analysis of LIFT's current state.

LIFT Dialect Reference — Complete Guide

The definitive reference for every dialect, type, operation, and syntax rule in LIFT.

After reading this document you will be able to write, read, configure, and assemble any .lif file for any model — classical AI, quantum circuits, or hybrid — without errors.

Table of Contents

• Part I — File Structure, Grammar, and Type System
• Part II — The tensor Dialect (Classical AI)
• Part III — The quantum Dialect (Quantum Computing)
• Part IV — The hybrid Dialect (Classical + Quantum Bridge)
• Part V — Configuration (.lith Files)
• Part VI — Assembling Dialects Together

Part I — File Structure, Grammar, and Type System

1.1 The .lif File

Every LIFT program is a .lif text file with this structure:

#dialect tensor            ← 1. Dialect declarations (one or more)

module @name {             ← 2. Module
    func @fn(%x: type) -> type {   ← 3. Function
        %y = "op"(%x) : (type) -> type   ← 4. Operations
        return %y                          ← 5. Return
    }
}

Rules

1. At least one #dialect directive at the top.
2. At least one module block.
3. Each module contains one or more func declarations.
4. Each function has parameters, optional return types, and a body of operations.
5. The body ends with a return statement.

1.2 Grammar Rules

Dialect Directive

#dialect tensor
#dialect quantum
#dialect hybrid

You can declare multiple dialects in one file.

Module

module @my_model {
    ...
}

Function

func @forward(%x: tensor<1x784xf32>, %w: tensor<784x256xf32>) -> tensor<1x256xf32> {
    ...
    return %out
}

Multiple return types use parentheses:

func @bell(%q0: qubit, %q1: qubit) -> (qubit, qubit) {
    ...
    return %q2, %q3
}

Operation (Assignment)

%result = "dialect.operation"(%input1, %input2) : (input_type1, input_type2) -> output_type

Multiple results:

%r1, %r2 = "quantum.cx"(%q0, %q1) : (qubit, qubit) -> (qubit, qubit)

With attributes:

%y = "quantum.ry"(%q) {angle = 1.5708} : (qubit) -> qubit

1.3 Identifiers

SSA Rule

Every %name is assigned exactly once. No reassignment allowed.

1.4 The Type System

Tensor Types

tensor<shape x dtype>

Data Types (dtype)

Quantum Types

Scalar Types

f32, f64, i32, i64, bool, void, index

1.5 Attributes

Compile-time constants attached to operations:

%y = "tensor.conv2d"(%x, %w) {stride = 2, padding = 1} : ...

1.6 Comments

// This is a comment (ignored by the parser)

Part II — The tensor Dialect (Classical AI)

Declare with #dialect tensor. Provides 107 operations for ML/AI.

2.1 Arithmetic (9)

%out = "tensor.matmul"(%x, %w) : (tensor<1x784xf32>, tensor<784x256xf32>) -> tensor<1x256xf32>
%out = "tensor.linear"(%x, %w, %b) : (tensor<1x784xf32>, tensor<784x256xf32>, tensor<256xf32>) -> tensor<1x256xf32>
%feat = "tensor.conv2d"(%img, %k) : (tensor<1x3x224x224xf32>, tensor<64x3x7x7xf32>) -> tensor<1x64x112x112xf32>

2.2 Activations (11)

All: 1 input → 1 output, same shape.

%a = "tensor.relu"(%x) : (tensor<1x256xf32>) -> tensor<1x256xf32>
%p = "tensor.softmax"(%logits) : (tensor<1x10xf32>) -> tensor<1x10xf32>

Which to use: CNN → ReLU. Transformer/LLM → GeLU/SiLU. Classifier → Softmax/Sigmoid. Edge → HardSwish.

2.3 Normalisation (5)

// LayerNorm — Transformers (input + scale)
%n1 = "tensor.layernorm"(%x, %scale) : (tensor<1x128x64xf32>, tensor<64xf32>) -> tensor<1x128x64xf32>

// LayerNorm with bias — (input + scale + bias)
%n2 = "tensor.layernorm"(%x, %scale, %bias) : (tensor<1x128x64xf32>, tensor<64xf32>, tensor<64xf32>) -> tensor<1x128x64xf32>

// RMSNorm — LLaMA, Mistral (input + scale)
%n3 = "tensor.rmsnorm"(%x, %scale) : (tensor<1x128x4096xf32>, tensor<4096xf32>) -> tensor<1x128x4096xf32>

// BatchNorm — CNN training (input + scale + bias)
%n4 = "tensor.batchnorm"(%x, %scale, %bias) : (tensor<8x64x32x32xf32>, tensor<64xf32>, tensor<64xf32>) -> tensor<8x64x32x32xf32>

// GroupNorm — Diffusion models (input + scale)
%n5 = "tensor.groupnorm"(%x, %scale) : (tensor<1x256x32x32xf32>, tensor<256xf32>) -> tensor<1x256x32x32xf32>

// InstanceNorm — Style transfer (input + scale)
%n6 = "tensor.instancenorm"(%x, %scale) : (tensor<1x64x256x256xf32>, tensor<64xf32>) -> tensor<1x64x256x256xf32>

2.4 Shape Operations (13) — Zero FLOPs

// Reshape: flatten a 4D image tensor to 2D
%flat = "tensor.reshape"(%x) : (tensor<1x3x224x224xf32>) -> tensor<1x150528xf32>

// Transpose: swap last two dimensions
%t = "tensor.transpose"(%x) : (tensor<128x64xf32>) -> tensor<64x128xf32>

// Concat: join two tensors along batch dimension
%cat = "tensor.concat"(%a, %b) : (tensor<1x128xf32>, tensor<1x128xf32>) -> tensor<2x128xf32>

// Squeeze: remove dimension of size 1
%sq = "tensor.squeeze"(%x) : (tensor<1x64x1x1xf32>) -> tensor<1x64xf32>

// Unsqueeze: add a batch dimension
%us = "tensor.unsqueeze"(%x) : (tensor<64xf32>) -> tensor<1x64xf32>

// Permute: reorder dimensions (e.g. NCHW → NHWC)
%p = "tensor.permute"(%x) : (tensor<1x3x224x224xf32>) -> tensor<1x224x224x3xf32>

// Slice: extract a sub-tensor
%sl = "tensor.slice"(%x) : (tensor<1x100x64xf32>) -> tensor<1x50x64xf32>

// Pad: add zero-padding
%padded = "tensor.pad"(%x) : (tensor<1x3x224x224xf32>) -> tensor<1x3x226x226xf32>

// Gather: index-based selection
%sel = "tensor.gather"(%x, %indices) : (tensor<1000x64xf32>, tensor<10xi32>) -> tensor<10x64xf32>

// Expand: broadcast a tensor
%exp = "tensor.expand"(%x) : (tensor<1x1x64xf32>) -> tensor<8x128x64xf32>

2.5 Attention (8)

All take 3-5 inputs (Q, K, V, optional mask). FLOPs = 2BH*(S²D + SD²).

// Standard scaled dot-product attention: Q, K, V
%attn = "tensor.attention"(%q, %k, %v) : (tensor<1x128x64xf32>, tensor<1x128x64xf32>, tensor<1x128x64xf32>) -> tensor<1x128x64xf32>

// Multi-head attention (standard Transformer)
%mha = "tensor.multi_head_attention"(%q, %k, %v) : (tensor<1x8x128x64xf32>, tensor<1x8x128x64xf32>, tensor<1x8x128x64xf32>) -> tensor<1x8x128x64xf32>

// Flash attention: same API, O(n) memory, for long sequences
%flash = "tensor.flash_attention"(%q, %k, %v) : (tensor<1x8x4096x64xf32>, tensor<1x8x4096x64xf32>, tensor<1x8x4096x64xf32>) -> tensor<1x8x4096x64xf32>

// Grouped-query attention (LLaMA 2 style): fewer K/V heads
%gqa = "tensor.grouped_query_attention"(%q, %k, %v) : (tensor<1x32x128x64xf32>, tensor<1x8x128x64xf32>, tensor<1x8x128x64xf32>) -> tensor<1x32x128x64xf32>

// Cross attention (encoder-decoder, e.g. translation)
%cross = "tensor.cross_attention"(%decoder_q, %encoder_k, %encoder_v) : (tensor<1x8x64x64xf32>, tensor<1x8x128x64xf32>, tensor<1x8x128x64xf32>) -> tensor<1x8x64x64xf32>

// Sliding window attention (Mistral): local context window
%swa = "tensor.sliding_window_attention"(%q, %k, %v) : (tensor<1x8x4096x64xf32>, tensor<1x8x4096x64xf32>, tensor<1x8x4096x64xf32>) -> tensor<1x8x4096x64xf32>

// Paged attention (vLLM): paged KV cache for efficient serving
%paged = "tensor.paged_attention"(%q, %k_cache, %v_cache) : (tensor<1x8x1x64xf32>, tensor<1x8x4096x64xf32>, tensor<1x8x4096x64xf32>) -> tensor<1x8x1x64xf32>

2.6 Convolution (6)

// Conv1D: audio processing [B, Cin, Length] * [Cout, Cin, K]
%audio_feat = "tensor.conv1d"(%audio, %kernel) : (tensor<1x1x16000xf32>, tensor<64x1x80xf32>) -> tensor<1x64x15921xf32>

// Conv2D: image feature extraction [B, Cin, H, W] * [Cout, Cin, Kh, Kw]
%img_feat = "tensor.conv2d"(%img, %kernel) : (tensor<1x3x224x224xf32>, tensor<64x3x7x7xf32>) -> tensor<1x64x112x112xf32>

// Conv3D: video processing [B, Cin, D, H, W] * [Cout, Cin, Kd, Kh, Kw]
%vid_feat = "tensor.conv3d"(%video, %kernel) : (tensor<1x3x16x112x112xf32>, tensor<64x3x3x3x3xf32>) -> tensor<1x64x14x110x110xf32>

// ConvTranspose2D: upsampling (decoder/generator)
%up = "tensor.conv_transpose2d"(%x, %kernel) : (tensor<1x64x16x16xf32>, tensor<64x32x4x4xf32>) -> tensor<1x32x32x32xf32>

// DepthwiseConv2D: MobileNet-style per-channel conv
%dw = "tensor.depthwise_conv2d"(%x, %kernel) : (tensor<1x64x32x32xf32>, tensor<64x1x3x3xf32>) -> tensor<1x64x32x32xf32>

// DilatedConv2D: large receptive field (segmentation)
%dilated = "tensor.dilated_conv2d"(%x, %kernel) : (tensor<1x64x64x64xf32>, tensor<64x64x3x3xf32>) -> tensor<1x64x64x64xf32>

2.7 Pooling (4)

// MaxPool2D: downsample by taking maximum in each window
%p1 = "tensor.maxpool2d"(%x, %params) : (tensor<1x64x32x32xf32>, tensor<2xi32>) -> tensor<1x64x16x16xf32>

// AvgPool2D: downsample by averaging each window
%p2 = "tensor.avgpool2d"(%x, %params) : (tensor<1x64x32x32xf32>, tensor<2xi32>) -> tensor<1x64x16x16xf32>

// AdaptiveAvgPool2D: output always has fixed spatial size (e.g. 7x7)
%p3 = "tensor.adaptive_avgpool2d"(%x) : (tensor<1x512x14x14xf32>) -> tensor<1x512x7x7xf32>

// GlobalAvgPool: average all spatial dimensions → 1x1
%p4 = "tensor.global_avgpool"(%x) : (tensor<1x64x7x7xf32>) -> tensor<1x64x1x1xf32>

2.8 Recurrent (3)

// LSTMCell: takes current input + previous hidden state, returns new hidden + cell state
%h_new, %c_new = "tensor.lstm_cell"(%x_t, %h_prev) : (tensor<1x128xf32>, tensor<1x256xf32>) -> (tensor<1x256xf32>, tensor<1x256xf32>)

// GRUCell: simpler than LSTM, single hidden state
%h_new = "tensor.gru_cell"(%x_t, %h_prev) : (tensor<1x128xf32>, tensor<1x256xf32>) -> tensor<1x256xf32>

// RNNCell: basic recurrent cell
%h_new = "tensor.rnn_cell"(%x_t, %h_prev) : (tensor<1x128xf32>, tensor<1x256xf32>) -> tensor<1x256xf32>

2.9 Advanced Math (11)

// Einsum: flexible tensor contraction (e.g. batch matmul)
%result = "tensor.einsum"(%a, %b) : (tensor<8x128x64xf32>, tensor<8x64x256xf32>) -> tensor<8x128x256xf32>

// FFT: Fast Fourier Transform (signal processing)
%freq = "tensor.fft"(%signal) : (tensor<1x1024xf32>) -> tensor<1x1024xf32>

// IFFT: Inverse FFT (frequency → time domain)
%time = "tensor.ifft"(%freq) : (tensor<1x1024xf32>) -> tensor<1x1024xf32>

// SVD: Singular Value Decomposition (compression, PCA)
%u = "tensor.svd"(%matrix) : (tensor<100x50xf32>) -> tensor<100x50xf32>

// TopK: get top-10 scores from 1000 classes
%top = "tensor.topk"(%scores) : (tensor<1x1000xf32>) -> tensor<1x10xf32>

// Sort: sort a tensor along last dimension
%sorted = "tensor.sort"(%x) : (tensor<1x100xf32>) -> tensor<1x100xf32>

// Cumsum: cumulative sum (prefix sum)
%cs = "tensor.cumsum"(%x) : (tensor<1x10xf32>) -> tensor<1x10xf32>

// Where: conditional selection (like numpy.where)
%selected = "tensor.where"(%cond, %a, %b) : (tensor<4xi1>, tensor<4xf32>, tensor<4xf32>) -> tensor<4xf32>

// Clamp: restrict values to [min, max] range
%clamped = "tensor.clamp"(%x, %min_val, %max_val) : (tensor<4xf32>, tensor<1xf32>, tensor<1xf32>) -> tensor<4xf32>

// Solve: solve linear system Ax = b
%solution = "tensor.solve"(%A, %b) : (tensor<64x64xf32>, tensor<64x1xf32>) -> tensor<64x1xf32>

// Eig: eigenvalue decomposition
%eigenvalues = "tensor.eig"(%matrix) : (tensor<32x32xf32>) -> tensor<32xf32>

2.10 Sparse (2)

"tensor.sparse_matmul", "tensor.sparse_embedding"

// SparseMatMul: sparse × dense matrix multiply (efficient for sparse models)
%result = "tensor.sparse_matmul"(%sparse_w, %x) : (tensor<10000x768xf32>, tensor<768x1xf32>) -> tensor<10000x1xf32>

// SparseEmbedding: sparse lookup (recommendation systems with huge vocab)
%emb = "tensor.sparse_embedding"(%sparse_ids, %table) : (tensor<1x50xi32>, tensor<1000000x128xf32>) -> tensor<1x50x128xf32>

2.11 Quantisation (6)

// INT8 Quantisation: reduce model size 4x
%q8 = "tensor.quantize"(%weights) : (tensor<256x256xf32>) -> tensor<256x256xi8>
%dq8 = "tensor.dequantize"(%q8) : (tensor<256x256xi8>) -> tensor<256x256xf32>

// INT4 Quantisation: reduce model size 8x (GPTQ, AWQ style)
%q4 = "tensor.quantize_int4"(%weights) : (tensor<4096x4096xf32>) -> tensor<4096x4096xi4>
%dq4 = "tensor.dequantize_int4"(%q4) : (tensor<4096x4096xi4>) -> tensor<4096x4096xf32>

// FP8 Quantisation: H100 native format
%qfp8 = "tensor.quantize_fp8"(%weights) : (tensor<4096x4096xf32>) -> tensor<4096x4096xfp8e4m3>
%dqfp8 = "tensor.dequantize_fp8"(%qfp8) : (tensor<4096x4096xfp8e4m3>) -> tensor<4096x4096xf32>

2.12 Diffusion/Generative (3)

"tensor.unet_down_block" (2-3 in), "tensor.unet_up_block" (2-3 in), "tensor.timestep_embedding" (1 in)

// TimestepEmbedding: encode diffusion timestep as a vector
%t_emb = "tensor.timestep_embedding"(%timestep) : (tensor<1xi32>) -> tensor<1x256xf32>

// UNetDownBlock: encoder block of UNet (input + timestep embedding)
%down = "tensor.unet_down_block"(%x, %t_emb) : (tensor<1x64x64x64xf32>, tensor<1x256xf32>) -> tensor<1x128x32x32xf32>

// UNetUpBlock: decoder block of UNet (input + skip connection + timestep)
%up = "tensor.unet_up_block"(%x, %skip, %t_emb) : (tensor<1x128x32x32xf32>, tensor<1x128x32x32xf32>, tensor<1x256xf32>) -> tensor<1x64x64x64xf32>

2.13 GNN (2)

"tensor.gnn_message_passing" (2-3 in), "tensor.gnn_global_pooling" (1 in)

// GNNMessagePassing: propagate node features along edges
%h1 = "tensor.gnn_message_passing"(%nodes, %adj) : (tensor<50x16xf32>, tensor<50x50xf32>) -> tensor<50x16xf32>

// With edge features (3 inputs)
%h2 = "tensor.gnn_message_passing"(%nodes, %adj, %edge_feat) : (tensor<50x16xf32>, tensor<50x50xf32>, tensor<50x50x8xf32>) -> tensor<50x16xf32>

// GNNGlobalPooling: aggregate all node features into a single graph vector
%graph = "tensor.gnn_global_pooling"(%h2) : (tensor<50x16xf32>) -> tensor<1x16xf32>

2.14 MoE (2)

"tensor.moe_dispatch" (2-3 in), "tensor.moe_combine" (2-3 in)

// MoEDispatch: router sends tokens to top-k experts
%dispatched = "tensor.moe_dispatch"(%tokens, %router_logits) : (tensor<8x128x512xf32>, tensor<8x128x8xf32>) -> tensor<8x128x512xf32>

// MoECombine: merge expert outputs weighted by router
%combined = "tensor.moe_combine"(%expert_outputs, %router_weights) : (tensor<8x128x512xf32>, tensor<8x128x8xf32>) -> tensor<8x128x512xf32>

2.15 Constants (5) — Zero inputs

"tensor.constant", "tensor.zeros", "tensor.ones", "tensor.arange", "tensor.full"

// Zeros: create an all-zero tensor (e.g. initial hidden state)
%z = "tensor.zeros"() : () -> tensor<1x256xf32>

// Ones: create an all-one tensor (e.g. attention mask)
%mask = "tensor.ones"() : () -> tensor<1x128xi32>

// Arange: create [0, 1, 2, ..., 127] (e.g. position IDs)
%pos = "tensor.arange"() : () -> tensor<128xi32>

// Full: create a tensor filled with a specific value
%filled = "tensor.full"() : () -> tensor<1x64xf32>

// Constant: arbitrary constant tensor
%c = "tensor.constant"() : () -> tensor<3xf32>

2.16 Memory (3)

"tensor.checkpoint" (activation recompute), "tensor.offload" (to CPU), "tensor.grad_accumulate" (micro-batches)

// Checkpoint: recompute activations during backward instead of storing them
// Saves GPU memory at the cost of extra compute (critical for large models)
%ckpt = "tensor.checkpoint"(%activations) : (tensor<1x4096x4096xf32>) -> tensor<1x4096x4096xf32>

// Offload: move tensor from GPU to CPU memory (for very large models)
%offloaded = "tensor.offload"(%weights) : (tensor<8192x8192xf32>) -> tensor<8192x8192xf32>

// GradAccumulate: accumulate gradients over multiple micro-batches
// Used when actual batch doesn't fit in GPU memory
%acc = "tensor.grad_accumulate"(%grads) : (tensor<256x256xf32>) -> tensor<256x256xf32>

2.17 Gradient/Backward (8)

// GradMatMul: backward pass for matrix multiplication
%grad_x = "tensor.grad_matmul"(%upstream_grad, %w) : (tensor<1x256xf32>, tensor<256x784xf32>) -> tensor<1x784xf32>

// GradReLU: backward pass for ReLU (zero where input was negative)
%grad_r = "tensor.grad_relu"(%upstream_grad, %relu_input) : (tensor<1x256xf32>, tensor<1x256xf32>) -> tensor<1x256xf32>

// GradSoftmax: backward pass for softmax
%grad_s = "tensor.grad_softmax"(%upstream_grad, %softmax_output) : (tensor<1x10xf32>, tensor<1x10xf32>) -> tensor<1x10xf32>

// GradLayerNorm: backward pass for layer normalisation
%grad_ln = "tensor.grad_layernorm"(%upstream_grad, %ln_input) : (tensor<1x128x64xf32>, tensor<1x128x64xf32>) -> tensor<1x128x64xf32>

// GradAttention: backward pass for attention
%grad_attn = "tensor.grad_attention"(%upstream_grad, %q, %k) : (tensor<1x128x64xf32>, tensor<1x128x64xf32>, tensor<1x128x64xf32>) -> tensor<1x128x64xf32>

// GradConv2D: backward pass for 2D convolution
%grad_conv = "tensor.grad_conv2d"(%upstream_grad, %conv_input) : (tensor<1x64x112x112xf32>, tensor<1x3x224x224xf32>) -> tensor<1x3x224x224xf32>

// GradLinear: backward pass for linear layer
%grad_lin = "tensor.grad_linear"(%upstream_grad, %w, %b) : (tensor<1x256xf32>, tensor<784x256xf32>, tensor<256xf32>) -> tensor<1x784xf32>

// GradGeLU: backward pass for GeLU activation
%grad_g = "tensor.grad_gelu"(%upstream_grad, %gelu_input) : (tensor<1x256xf32>, tensor<1x256xf32>) -> tensor<1x256xf32>

2.18 Parallelism (4)

"tensor.parallel_split", "tensor.parallel_allreduce", "tensor.pipeline_send", "tensor.pipeline_receive"

// ParallelSplit: split a batch across multiple GPUs (data parallelism)
%shard = "tensor.parallel_split"(%batch) : (tensor<32x128xf32>) -> tensor<8x128xf32>

// ParallelAllReduce: synchronise gradients across all GPUs
%synced = "tensor.parallel_allreduce"(%local_grad) : (tensor<256x256xf32>) -> tensor<256x256xf32>

// PipelineSend: send activation to the next pipeline stage (model parallelism)
%sent = "tensor.pipeline_send"(%activation) : (tensor<1x128x4096xf32>) -> tensor<1x128x4096xf32>

// PipelineReceive: receive activation from the previous pipeline stage
%recv = "tensor.pipeline_receive"(%placeholder) : (tensor<1x128x4096xf32>) -> tensor<1x128x4096xf32>

2.19 Fused Operations (6)

// FusedMatMulBiasReLU: 3 ops in 1 kernel (most common for MLP hidden layers)
%h = "tensor.fused_matmul_bias_relu"(%x, %w, %b) : (tensor<1x256xf32>, tensor<256x128xf32>, tensor<128xf32>) -> tensor<1x128xf32>

// FusedMatMulBias: matmul + bias only (no activation)
%h2 = "tensor.fused_matmul_bias"(%x, %w, %b) : (tensor<1x128xf32>, tensor<128x64xf32>, tensor<64xf32>) -> tensor<1x64xf32>

// FusedLinearGeLU: used in Transformer FFN (LLM inference)
%ffn = "tensor.fused_linear_gelu"(%x, %w, %b) : (tensor<1x128x4096xf32>, tensor<4096x16384xf32>, tensor<16384xf32>) -> tensor<1x128x16384xf32>

// FusedAttentionLayerNorm: attention + normalisation in one pass
%attn_ln = "tensor.fused_attention_layernorm"(%q, %k, %v, %scale) : (tensor<1x128x64xf32>, tensor<1x128x64xf32>, tensor<1x128x64xf32>, tensor<64xf32>) -> tensor<1x128x64xf32>

// FusedLinearSiLU: used in LLaMA/Mistral gate projections
%gate = "tensor.fused_linear_silu"(%x, %w, %b) : (tensor<1x128x4096xf32>, tensor<4096x11008xf32>, tensor<11008xf32>) -> tensor<1x128x11008xf32>

// FusedConvBatchNormReLU: standard CNN inference fusion
%feat = "tensor.fused_conv_batchnorm_relu"(%img, %w, %bn_s, %bn_b, %bn_m) : (tensor<1x3x224x224xf32>, tensor<64x3x7x7xf32>, tensor<64xf32>, tensor<64xf32>, tensor<64xf32>) -> tensor<1x64x112x112xf32>

Part III — The quantum Dialect (Quantum Computing)

Declare with #dialect quantum. Provides 50+ operations for quantum circuits.

Critical rule: all qubits follow the linearity rule — each qubit value must be consumed exactly once.

3.1 Standard 1-Qubit Gates (9)

All take 1 qubit, return 1 qubit: %q_out = "quantum.gate"(%q_in) : (qubit) -> qubit

%q1 = "quantum.h"(%q0) : (qubit) -> qubit
%q2 = "quantum.x"(%q1) : (qubit) -> qubit
%q3 = "quantum.t"(%q2) : (qubit) -> qubit

3.2 Parametric 1-Qubit Gates (7)

Take 1 qubit + angle attributes, return 1 qubit.

%q1 = "quantum.ry"(%q0) {angle = 1.5708} : (qubit) -> qubit
%q1 = "quantum.rz"(%q0) {angle = 0.785} : (qubit) -> qubit
%q1 = "quantum.u3"(%q0) {theta = 1.57, phi = 0.0, lambda = 3.14} : (qubit) -> qubit

3.3 Fixed-Angle 1-Qubit Gates (2)

// Rx90: fixed pi/2 rotation around X (commonly used in hardware)
%q1 = "quantum.rx90"(%q0) : (qubit) -> qubit

// Rx180: fixed pi rotation around X (equivalent to X gate)
%q2 = "quantum.rx180"(%q1) : (qubit) -> qubit

3.4 2-Qubit Gates (13)

All take 2 qubits, return 2 qubits: %a, %b = "quantum.gate"(%q0, %q1) : (qubit, qubit) -> (qubit, qubit)

IonQ native gates (3)

// CX (CNOT): controlled NOT, fundamental entangling gate (IBM native)
%q2, %q3 = "quantum.cx"(%q0, %q1) : (qubit, qubit) -> (qubit, qubit)

// CZ: controlled-Z (Google Sycamore native)
%q2, %q3 = "quantum.cz"(%q0, %q1) : (qubit, qubit) -> (qubit, qubit)

// SWAP: exchange two qubit states
%q2, %q3 = "quantum.swap"(%q0, %q1) : (qubit, qubit) -> (qubit, qubit)

// ECR: echoed cross-resonance (IBM Eagle/Heron native)
%q2, %q3 = "quantum.ecr"(%q0, %q1) : (qubit, qubit) -> (qubit, qubit)

// ZZ: parametric Ising ZZ (Quantinuum native)
%q2, %q3 = "quantum.zz"(%q0, %q1) {angle = 0.5} : (qubit, qubit) -> (qubit, qubit)

// XX: parametric Ising XX (IonQ native)
%q2, %q3 = "quantum.xx"(%q0, %q1) {angle = 1.5708} : (qubit, qubit) -> (qubit, qubit)

// CP: controlled-phase gate (parametric)
%q2, %q3 = "quantum.cp"(%q0, %q1) {angle = 0.7854} : (qubit, qubit) -> (qubit, qubit)

// CPhase: Rigetti native controlled-phase
%q2, %q3 = "quantum.cphase"(%q0, %q1) {angle = 1.5708} : (qubit, qubit) -> (qubit, qubit)

// XY: Rigetti native XY interaction
%q2, %q3 = "quantum.xy"(%q0, %q1) {angle = 0.5} : (qubit, qubit) -> (qubit, qubit)

// iSWAP: imaginary SWAP (Google Sycamore)
%q2, %q3 = "quantum.iswap"(%q0, %q1) : (qubit, qubit) -> (qubit, qubit)

3.5 3-Qubit Gates (2)