cqlib_core/qis/
error.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
13use crate::circuit::CircuitError;
14use thiserror::Error;
15
16/// Comprehensive error type for the `qis` (Quantum Information Science) module.
17///
18/// This enum captures errors that can occur during statevector simulation,
19/// density matrix simulation, observables, Hamiltonians, and Pauli operator manipulations.
20#[derive(Debug, Error)]
21pub enum QisError {
22    /// Errors originating from quantum circuit operations, such as unsupported gates
23    /// or symbolic parameters.
24    #[error(transparent)]
25    CircuitError(#[from] CircuitError),
26
27    /// Thrown when the number of qubits of an operator (e.g., Hamiltonian) does not match
28    /// the number of qubits of the quantum state being measured.
29    #[error("Qubit count mismatch: expected {expected}, got {actual}")]
30    QubitMismatch { expected: usize, actual: usize },
31
32    /// Thrown when the dimensions of matrices or vectors do not match expectations
33    /// (e.g., when multiplying matrices of incompatible shapes).
34    #[error("Dimension mismatch: expected {expected}, got {actual}")]
35    DimensionMismatch { expected: usize, actual: usize },
36
37    /// Thrown when a state vector or density matrix has an invalid length
38    /// (e.g., its length is not a power of 2).
39    #[error("Invalid state dimension: length {0} is not a power of 2")]
40    InvalidStateDimension(usize),
41
42    /// Thrown when a probability value is mathematically invalid (e.g., < 0 or > 1).
43    #[error("Invalid probability value: {0}")]
44    InvalidProbability(f64),
45
46    /// Thrown when attempting to access a qubit or amplitude index that is out of bounds.
47    #[error("Index out of bounds: index {index}, max {max}")]
48    IndexOutOfBounds { index: usize, max: usize },
49
50    /// Thrown when an operation is requested but not supported by the simulation backend.
51    #[error("Unsupported simulation operation: {0}")]
52    UnsupportedOperation(String),
53
54    /// Thrown when parsing a Pauli string fails.
55    #[error(transparent)]
56    PauliStringParseError(#[from] PauliStringParseError),
57
58    /// Thrown when an explicitly provided quantum state is not normalized
59    /// (i.e., trace or norm is not 1).
60    #[error("State is not normalized")]
61    NotNormalized,
62
63    /// Thrown when an operator is expected to be Hermitian but is not
64    /// (e.g., a non-Hermitian Hamiltonian or density matrix).
65    #[error("Operator is not Hermitian")]
66    NotHermitian,
67
68    /// Thrown when a density matrix is expected to be positive semidefinite but is not.
69    #[error("Density matrix is not positive semidefinite")]
70    NotPositiveSemidefinite,
71
72    /// Thrown when a parameter value is invalid.
73    #[error("Invalid parameter value: {0}")]
74    InvalidParameterValue(String),
75
76    /// Thrown when a subsystem specification is invalid for entanglement calculations.
77    #[error("Invalid subsystem: {0}")]
78    InvalidSubsystem(String),
79
80    /// Thrown when an operation requires a specific dimension that is not met.
81    #[error("Unsupported dimension: expected {expected}, got {actual}")]
82    UnsupportedDimension { expected: usize, actual: usize },
83
84    /// Thrown when a gate is applied to a [`StabilizerState`] but is not a Clifford gate
85    /// (i.e., it does not map the Pauli group to itself under conjugation).
86    /// Examples: T, T†, Rx(θ) for generic θ.
87    ///
88    /// Use [`crate::qis::Statevector`] for universal (non-Clifford) simulation.
89    #[error("Non-Clifford gate: {0}")]
90    NonCliffordGate(String),
91}
92
93/// Error type for parsing PauliString from a string representation.
94#[derive(Debug, Clone, PartialEq, Eq, Error)]
95pub enum PauliStringParseError {
96    /// The string provided for parsing is empty.
97    #[error("empty string")]
98    EmptyString,
99
100    /// The string contains an invalid or unrecognized character.
101    #[error("invalid character '{0}'")]
102    InvalidCharacter(char),
103
104    /// The string only contains a phase but lacks any Pauli operators.
105    #[error("no Pauli operators specified")]
106    NoOperators,
107}
cqlib_core/qis/error.rs

cqlib_core/qis/
error.rs
