cqlib_core/circuit/gate/
directive.rs

1// This code is part of Cqlib.
2//
3// (C) Copyright China Telecom Quantum Group 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//! Non-Unitary Circuit Directives
14//!
15//! This module defines [`Directive`], an enum representing non-unitary operations
16//! that can appear in quantum circuits. Unlike unitary gates, these operations
17//! are generally irreversible and represent interactions with the classical world
18//! (measurement) or hardware-level instructions (barriers, resets).
19
20use std::fmt;
21
22/// Non-unitary operations in a quantum circuit.
23///
24/// Directives represent operations that cannot be described by unitary matrices
25/// and often involve classical outcomes or hardware-specific behavior.
26///
27/// # Variants
28///
29/// - `Barrier`: Prevents gate reordering across its boundary during optimization
30/// - `Measure`: Collapses qubit state to classical bit
31/// - `Reset`: Prepares qubit in |0⟩ state
32///
33/// # Examples
34///
35/// ```
36/// use cqlib_core::circuit::gate::Directive;
37///
38/// // Create a barrier directive
39/// let barrier = Directive::Barrier;
40///
41/// // Measurement directive
42/// let measure = Directive::Measure;
43///
44/// // Reset directive
45/// let reset = Directive::Reset;
46/// ```
47#[repr(u8)]
48#[derive(Eq, Hash, PartialEq, Debug, Clone, Copy)]
49pub enum Directive {
50    /// A synchronization barrier preventing gate reordering.
51    ///
52    /// Ensures that operations before and after the barrier cannot be
53    /// reordered during circuit optimization. Useful for timing-critical
54    /// sequences or hardware constraints.
55    Barrier,
56    /// Measurement operation collapsing quantum state to classical information.
57    ///
58    /// Measures the qubit in the computational basis and stores the
59    /// result (0 or 1) in a classical register.
60    Measure,
61    /// Reset operation preparing qubit in the |0⟩ state.
62    ///
63    /// Forces the qubit into the ground state regardless of its current state.
64    /// This is typically implemented via measurement followed by conditional
65    /// X gate or direct initialization.
66    Reset,
67}
68
69impl fmt::Display for Directive {
70    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
71        f.write_str(self.name())
72    }
73}
74
75impl Directive {
76    /// Returns the stable lowercase operation name.
77    pub const fn name(self) -> &'static str {
78        match self {
79            Self::Barrier => "barrier",
80            Self::Measure => "measure",
81            Self::Reset => "reset",
82        }
83    }
84
85    /// Returns the inverse of the directive if it exists.
86    ///
87    /// # Returns
88    ///
89    /// - `Some(Directive::Barrier)`: Barrier is self-inverse
90    /// - `None`: Measure and Reset have no inverse
91    ///
92    /// # Examples
93    ///
94    /// ```
95    /// use cqlib_core::circuit::gate::Directive;
96    ///
97    /// // Barrier is self-inverse
98    /// assert_eq!(Directive::Barrier.inverse(), Some(Directive::Barrier));
99    ///
100    /// // Measurement has no inverse
101    /// assert_eq!(Directive::Measure.inverse(), None);
102    ///
103    /// // Reset has no inverse
104    /// assert_eq!(Directive::Reset.inverse(), None);
105    /// ```
106    pub fn inverse(&self) -> Option<Self> {
107        match self {
108            Directive::Barrier => Some(Directive::Barrier),
109            _ => None,
110        }
111    }
112}
cqlib_core/circuit/gate/directive.rs

cqlib_core/circuit/gate/
directive.rs
