cqlib_core/compile/transform/mod.rs
1// This code is part of Cqlib.
2//
3// (C) Copyright China Telecom Quantum Group 2025-2026
4//
5// This code is licensed under the Apache License, Version 2.0. You may
6// obtain a copy of this license in the LICENSE.txt file in the root directory
7// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
8//
9// Any modifications or derivative works of this code must retain this
10// copyright notice, and modified files need to carry a notice indicating
11// that they have been altered from the originals.
12
13//! Circuit transforms used by the compiler workflow.
14//!
15//! This module contains reusable compiler algorithms that transform, analyze,
16//! place, or route a [`Circuit`](crate::circuit::Circuit). It is an algorithm
17//! boundary rather than a workflow manager: callers may compose individual
18//! transforms directly, while the public [`compile`](crate::compile::compile)
19//! entry point decides when each completed transform runs in the staged
20//! pipeline.
21//!
22//! # Transform Contract
23//!
24//! Circuit-to-circuit passes implement [`Transformer`]. A transformer takes an
25//! immutable circuit reference and returns a [`TransformOutcome`].
26//! [`TransformOutcome::Unchanged`] retains the input IR exactly as-is, while
27//! [`TransformOutcome::Changed`] carries its replacement. Standalone callers
28//! do not need to pre-scan a circuit: every transform still owns a complete
29//! correctness check over all operation forms it supports. The compiler
30//! workflow may additionally use revision-scoped structural facts to avoid
31//! invoking a transform when those facts prove it cannot change or reject the
32//! current circuit.
33//!
34//! Layout and routing algorithms expose richer result types because they
35//! return placement scores, final layouts, SWAP counts, and routing
36//! diagnostics. They are still transform-layer algorithms and do not make
37//! workflow policy decisions such as target-basis selection.
38//!
39//! # Module Roles
40//!
41//! - [`canonicalize`] validates and normalizes the compiler IR without doing
42//! semantic optimization or hardware lowering.
43//! - [`commutative_cancellation`] cancels self-inverse gate pairs through a
44//! global, unbounded commutation-set analysis.
45//! - [`decompose`] expands circuit-backed definitions, synthesizes
46//! matrix-backed unitaries, and lowers multi-controlled gates.
47//! - [`device_lowering`] maps routed physical gates to exact ordered device
48//! instructions, including direction and local capability overrides.
49//! - [`rewrite`] applies compiler knowledge rules for conservative
50//! optimization or explicit target-basis lowering.
51//! - [`layout`] selects an initial logical-to-physical mapping for a device but
52//! does not insert SWAPs.
53//! - [`routing`] rebuilds a physical circuit from an automatic or supplied
54//! initial layout and inserts SWAPs as needed.
55//!
56//! Direct use of this module is appropriate for tests, diagnostics, and custom
57//! pipelines. Most users should start with [`compile`](crate::compile::compile)
58//! so target constraints, resources, routing, and output canonicalization stay
59//! ordered consistently.
60
61pub mod analysis;
62pub mod canonicalize;
63pub mod commutative_cancellation;
64pub mod decompose;
65pub mod device_lowering;
66pub mod layout;
67pub(crate) mod lowering_support;
68pub mod native_optimization;
69mod native_quality;
70#[cfg(test)]
71mod native_quality_test;
72pub mod one_qubit_optimization;
73pub mod rebuild;
74pub mod resynthesis;
75pub mod rewrite;
76pub mod routing;
77pub mod routing_basis;
78pub mod target_basis;
79pub mod transformer;
80pub mod virtual_permutation;
81
82pub use analysis::CircuitAnalysis;
83pub use canonicalize::{
84 CanonicalizeConfig, CanonicalizeResult, Canonicalizer, canonicalize_circuit,
85};
86pub use commutative_cancellation::CommutativeCancellation;
87pub use device_lowering::DeviceLowerer;
88pub use layout::{
89 CircuitLayoutAnalysis, Interaction, InteractionGraph, LayoutDiagnostics, LayoutObjective,
90 LayoutResult, LayoutScore, PreparedSabreCircuit, PreparedSabreTarget, Vf2EdgeRequirement,
91 Vf2LayoutConfig, analyze_circuit_for_layout, greedy_layout, greedy_layout_prepared,
92 prepare_sabre_circuit, prepare_sabre_device_target, prepare_sabre_topology_target,
93 sabre_layout, sabre_layout_prepared, trivial_layout, trivial_layout_prepared,
94 vf2_perfect_layout, vf2_perfect_layout_prepared,
95};
96pub use native_optimization::{
97 NativeOptimizationResult, NativeOptimizationSummary, NativeOptimizer,
98};
99pub use native_quality::NativeQualityPolicy;
100pub use one_qubit_optimization::OptimizeOneQubitRuns;
101pub use resynthesis::{
102 DeviceResynthesisPlacement, ResynthesizeTwoQubitBlocks, TwoQubitBlockResynthesisConfig,
103 resynthesize_two_qubit_blocks, resynthesize_two_qubit_blocks_for_device,
104};
105pub use rewrite::{
106 KnowledgeRewriteDiagnostics, KnowledgeRewriteResult, KnowledgeRewriteStats, KnowledgeRewriter,
107 RewriteConfig, RewriteMode, rewrite_circuit,
108};
109pub(crate) use rewrite::{
110 KnowledgeRewriteSession, OperationReplacement, QubitBijection, RewriteEdits,
111 RewriteExecutionRecord,
112};
113pub use routing::{RoutedCircuit, SabreRouteResult, route_sabre, route_with_layout};
114pub(crate) use routing::{
115 SabreParetoRouteCandidate, prepare_sabre_pareto_routes_with_session_on_physical,
116 route_sabre_tracked_on_topology, route_sabre_tracked_with_session_on_physical,
117 route_with_layout_tracked_on_topology, route_with_layout_tracked_with_session_on_physical,
118};
119pub use routing_basis::LowerToRoutingBasis;
120pub use target_basis::{
121 TargetBasisCost, TargetBasisCostModel, TargetBasisLowerer, TargetBasisSignature,
122};
123#[cfg(test)]
124pub(crate) use transformer::{ResolvedTransform, TransformerTestExt, resolve_transform_for_test};
125pub use transformer::{TransformOutcome, Transformer};
126pub use virtual_permutation::{
127 VirtualPermutation, VirtualPermutationElisionResult, VirtualPermutationElisionStatus,
128 elide_virtual_permutations,
129};