cqlib_core/compile/transform/rewrite/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//! Knowledge-based local circuit rewrite.
14//!
15//! This pass consumes validated compiler knowledge rules and applies them as
16//! dependency-aware local rewrites. It is a local rewrite engine, not a global
17//! optimizer: it searches bounded operation windows, checks rule conditions,
18//! applies cost policy, and rebuilds the affected circuit regions.
19//!
20//! [`RewriteConfig::production`] selects the conservative optimization mode
21//! used by normal compiler cleanup. It enables simplification, cancellation,
22//! merge, and canonicalization rules and accepts rewrites only under the local
23//! cost model. [`RewriteConfig::lowering`] enables decomposition and
24//! hardware-native rules as well, allowing local expansion when the caller has
25//! requested explicit target-basis lowering.
26//!
27//! Target-basis translation is expressed by calling
28//! [`RewriteConfig::with_target_instructions`]. The rewriter then rejects a
29//! lowering result that still contains gate-like instructions outside the
30//! configured basis.
31//!
32//! The pass recurses into supported structured classical-control bodies. It
33//! does not synthesize arbitrary matrix-backed unitaries, choose layouts, route
34//! through device topology, or perform directed-coupling legalization.
35
36mod basis;
37mod config;
38mod diagnostics;
39mod edit;
40mod edit_validation;
41mod matcher;
42mod proof;
43mod rewriter;
44mod session;
45
46pub use config::{RewriteConfig, RewriteMode};
47pub use diagnostics::KnowledgeRewriteDiagnostics;
48pub(crate) use edit::resolved_params_are_equal;
49pub(crate) use edit::{OperationReplacement, QubitBijection, RewriteEdits};
50pub use rewriter::{
51 KnowledgeRewriteResult, KnowledgeRewriteStats, KnowledgeRewriter, rewrite_circuit,
52};
53pub(crate) use session::{KnowledgeRewriteSession, RewriteExecutionRecord};
54
55#[cfg(test)]
56#[path = "./rewrite_test.rs"]
57mod rewrite_test;
58
59#[cfg(test)]
60mod qcis_rules_test;