cqlib_core/compile/knowledge/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//! Compiler knowledge-base rules.
14//!
15//! This module contains the data model and runtime helpers used by the active
16//! compiler rule system. A knowledge rule describes an ordered match pattern,
17//! optional symbolic-parameter conditions, and a rewrite target.
18//!
19//! The main layers are:
20//! - [`rule`]: runtime rule structures and structural validation.
21//! - [`rule_dsl`]: parser, loader, lowering, and dumper for `.rule` files.
22//! - [`library`]: validated rule storage, stable rule ids, metadata, and gate
23//! indexes for candidate selection.
24//! - [`matcher`]: adjacent-operation structural matching, binding, condition
25//! checks, and target instantiation.
26//! - [`rule_equivalence`]: symbolic and sampling-based equivalence validation.
27//!
28//! Transform passes should use [`RuleLibrary`] to select candidate rules, then
29//! use matcher helpers to bind a specific operation window. Search policy,
30//! commutation-aware scans, cost decisions, and circuit patching live outside
31//! this module.
32
33pub mod library;
34pub mod matcher;
35pub mod rule;
36pub mod rule_dsl;
37pub mod rule_equivalence;
38
39pub use library::{RuleId, RuleKind, RuleLibrary, RuleLibraryError, RuleMetadata};
40pub use matcher::{
41 ConcreteOperationView, KnowledgeInstructionKey, MatchBindings, MatchError, MatchedReplacement,
42 conditions_hold, instantiate_target, match_rule_item, rule_matches_operations,
43};