Module transform 

Circuit transforms used by the compiler workflow.

This module contains reusable compiler algorithms that transform, analyze, place, or route a Circuit. It is an algorithm boundary rather than a workflow manager: callers may compose individual transforms directly, while the public compile entry point decides when each completed transform runs in the staged pipeline.

Transform Contract

Circuit-to-circuit passes implement Transformer. A transformer takes an immutable circuit reference and returns a TransformOutcome. TransformOutcome::Unchanged retains the input IR exactly as-is, while TransformOutcome::Changed carries its replacement. Standalone callers do not need to pre-scan a circuit: every transform still owns a complete correctness check over all operation forms it supports. The compiler workflow may additionally use revision-scoped structural facts to avoid invoking a transform when those facts prove it cannot change or reject the current circuit.

Layout and routing algorithms expose richer result types because they return placement scores, final layouts, SWAP counts, and routing diagnostics. They are still transform-layer algorithms and do not make workflow policy decisions such as target-basis selection.

Module Roles

• canonicalize validates and normalizes the compiler IR without doing semantic optimization or hardware lowering.
• commutative_cancellation cancels self-inverse gate pairs through a global, unbounded commutation-set analysis.
• decompose expands circuit-backed definitions, synthesizes matrix-backed unitaries, and lowers multi-controlled gates.
• device_lowering maps routed physical gates to exact ordered device instructions, including direction and local capability overrides.
• rewrite applies compiler knowledge rules for conservative optimization or explicit target-basis lowering.
• layout selects an initial logical-to-physical mapping for a device but does not insert SWAPs.
• routing rebuilds a physical circuit from an automatic or supplied initial layout and inserts SWAPs as needed.

Direct use of this module is appropriate for tests, diagnostics, and custom pipelines. Most users should start with compile so target constraints, resources, routing, and output canonicalization stay ordered consistently.

Re-exports

pub use analysis::CircuitAnalysis;

pub use canonicalize::CanonicalizeConfig;

pub use canonicalize::CanonicalizeResult;

pub use canonicalize::Canonicalizer;

pub use canonicalize::canonicalize_circuit;

pub use commutative_cancellation::CommutativeCancellation;

pub use device_lowering::DeviceLowerer;

pub use layout::CircuitLayoutAnalysis;

pub use layout::Interaction;

pub use layout::InteractionGraph;

pub use layout::LayoutDiagnostics;

pub use layout::LayoutObjective;

pub use layout::LayoutResult;

pub use layout::LayoutScore;

pub use layout::PreparedSabreCircuit;

pub use layout::PreparedSabreTarget;

pub use layout::Vf2EdgeRequirement;

pub use layout::Vf2LayoutConfig;

pub use layout::analyze_circuit_for_layout;

pub use layout::greedy_layout;

pub use layout::greedy_layout_prepared;

pub use layout::prepare_sabre_circuit;

pub use layout::prepare_sabre_device_target;

pub use layout::prepare_sabre_topology_target;

pub use layout::sabre_layout;

pub use layout::sabre_layout_prepared;

pub use layout::trivial_layout;

pub use layout::trivial_layout_prepared;

pub use layout::vf2_perfect_layout;

pub use layout::vf2_perfect_layout_prepared;

pub use native_optimization::NativeOptimizationResult;

pub use native_optimization::NativeOptimizationSummary;

pub use native_optimization::NativeOptimizer;

pub use one_qubit_optimization::OptimizeOneQubitRuns;

pub use resynthesis::DeviceResynthesisPlacement;

pub use resynthesis::ResynthesizeTwoQubitBlocks;

pub use resynthesis::TwoQubitBlockResynthesisConfig;

pub use resynthesis::resynthesize_two_qubit_blocks;

pub use resynthesis::resynthesize_two_qubit_blocks_for_device;

pub use rewrite::KnowledgeRewriteDiagnostics;

pub use rewrite::KnowledgeRewriteResult;

pub use rewrite::KnowledgeRewriteStats;

pub use rewrite::KnowledgeRewriter;

pub use rewrite::RewriteConfig;

pub use rewrite::RewriteMode;

pub use rewrite::rewrite_circuit;

pub use routing::RoutedCircuit;

pub use routing::SabreRouteResult;

pub use routing::route_sabre;

pub use routing::route_with_layout;

pub use routing_basis::LowerToRoutingBasis;

pub use target_basis::TargetBasisCost;

pub use target_basis::TargetBasisCostModel;

pub use target_basis::TargetBasisLowerer;

pub use target_basis::TargetBasisSignature;

pub use transformer::TransformOutcome;

pub use transformer::Transformer;

pub use virtual_permutation::VirtualPermutation;

pub use virtual_permutation::VirtualPermutationElisionResult;

pub use virtual_permutation::VirtualPermutationElisionStatus;

pub use virtual_permutation::elide_virtual_permutations;

Modules

analysis

Structural circuit analysis shared by compiler transforms.

canonicalize

Circuit IR canonicalization for the new compiler.

commutative_cancellation

Global self-inverse gate cancellation over commutation sets.

decompose

Circuit decomposition transforms and synthesis building blocks.

device_lowering

Exact ordered-qargs lowering to a concrete device instruction set.

layout

Initial-layout algorithms for quantum compilation.

native_optimization

Exact physical optimization after device instruction lowering.

one_qubit_optimization

Target-neutral and target-basis-aware one-qubit optimization.

rebuild

Shared infrastructure for classical-safe circuit rebuilds.

resynthesis

Numeric block resynthesis transforms.

rewrite

Knowledge-based local circuit rewrite.

routing

Device-aware routing transforms.

routing_basis

Pre-routing legalization for SABRE’s gate-arity contract.

target_basis

Deterministic target-basis lowering.

transformer

virtual_permutation

Pre-layout elimination of logical wire permutations.

Enums

NativeQualityPolicy

Candidate acceptance and ranking policy used by super::NativeOptimizer.