cqlib_core/compile/transform/decompose/
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 decomposition transforms and synthesis building blocks.
14//!
15//! This module separates decomposition by the representation that is available
16//! for an operation:
17//!
18//! - [`definition`] expands gates that already carry an implementation circuit.
19//!   Use this first for [`CircuitGate`](crate::circuit::gate::CircuitGate) and
20//!   circuit-backed [`UnitaryGate`](crate::circuit::UnitaryGate) operations.
21//! - [`unitary`] synthesizes remaining custom `UnitaryGate` operations from
22//!   fixed numeric matrices. It currently supports one- and two-qubit matrices.
23//! - [`mc_gate`] provides explicit algorithmic synthesis primitives for
24//!   multi-controlled gates, plus the circuit-level resource-aware
25//!   `decompose_mc_gates` entry point.
26//!
27//! The workflow-facing adapters [`DecomposeDefinitions`],
28//! [`DecomposeUnitaries`], and [`DecomposeMcGates`] implement
29//! [`Transformer`](crate::compile::transform::Transformer). They are expected
30//! to report `changed = false` when no operation in their scope was lowered.
31//!
32//! # Recommended Order
33//!
34//! Run definition expansion before matrix synthesis so circuit-backed unitary
35//! gates are expanded before the matrix-only [`decompose_unitaries`] stage is
36//! reached. Run multi-controlled gate decomposition after unitary synthesis so
37//! the circuit-level planner can apply resource policy and control-flow
38//! traversal to the remaining high-level controlled operations.
39//!
40//! These are decomposition entry points, not a complete compiler pipeline.
41//! Target-basis lowering belongs to [`rewrite`](crate::compile::transform::rewrite),
42//! initial placement belongs to [`layout`](crate::compile::transform::layout),
43//! and SWAP insertion belongs to [`routing`](crate::compile::transform::routing).
44//! Directed-coupling legalization and scheduling are separate compiler
45//! concerns.
46
47pub mod definition;
48pub mod mc_gate;
49pub mod rule;
50pub mod unitary;
51
52pub use definition::{DecomposeDefinitions, expand_definitions};
53pub use mc_gate::{
54    DecomposeMcGates, McGateDecomposeConfig, decompose_mc_gates, decompose_mc_gates_with_rule_stats,
55};
56pub use rule::{
57    DecompositionAlgorithm, DecompositionRule, DecompositionRuleCache, DecompositionRuleStats,
58    McGateRuleRequest, NumericUnitaryRuleRequest, NumericUnitarySynthesisKey, ResourceSignature,
59    RuntimeAncillaKind,
60};
61pub use unitary::decompose::{
62    DecomposeUnitaries, UnitaryDecomposeConfig, decompose_unitaries,
63    decompose_unitaries_with_rule_stats,
64};
cqlib_core/compile/transform/decompose/mod.rs

cqlib_core/compile/transform/decompose/
mod.rs
