scirs2_core/quantum/
error.rs

1//! Error types for the quantum simulation module.
2
3use thiserror::Error;
4
5/// Errors that can arise from quantum simulation operations.
6#[derive(Debug, Clone, PartialEq, Error)]
7pub enum QuantumError {
8    /// The statevector has zero norm and cannot be normalised.
9    #[error("Quantum state vector has zero norm — unphysical state")]
10    ZeroStateVector,
11
12    /// A qubit index was out of range for the register size.
13    #[error("Qubit index {index} is out of range for a {n_qubits}-qubit register")]
14    QubitIndexOutOfRange {
15        /// The supplied index.
16        index: usize,
17        /// Number of qubits in the register.
18        n_qubits: usize,
19    },
20
21    /// The statevector dimension did not match 2^n_qubits.
22    #[error("Dimension mismatch: expected {expected}, got {actual}")]
23    DimensionMismatch {
24        /// Expected dimension.
25        expected: usize,
26        /// Actual dimension encountered.
27        actual: usize,
28    },
29
30    /// A basis-state index exceeded the Hilbert-space dimension.
31    #[error("Basis index {index} is out of range for dim={dim}")]
32    BasisIndexOutOfRange {
33        /// Supplied index.
34        index: usize,
35        /// Hilbert-space dimension 2^n.
36        dim: usize,
37    },
38
39    /// Too many qubits were requested (would overflow usize).
40    #[error("Too many qubits requested: {0} would exceed usize capacity")]
41    TooManyQubits(usize),
42
43    /// An invalid qubit count was supplied (e.g. 0).
44    #[error("Invalid qubit count: {0}")]
45    InvalidQubitCount(usize),
46
47    /// Gate arity does not match the number of target qubits supplied.
48    #[error("Gate arity mismatch: gate acts on {gate_qubits} qubit(s) but {supplied} target(s) were provided")]
49    GateArityMismatch {
50        /// Number of qubits the gate acts on.
51        gate_qubits: usize,
52        /// Number of target indices supplied by the caller.
53        supplied: usize,
54    },
55
56    /// Two target-qubit indices in a gate application were identical.
57    #[error("Duplicate qubit index {index} in gate target list")]
58    DuplicateQubitIndex {
59        /// The repeated index.
60        index: usize,
61    },
62
63    /// The gate matrix is not unitary (failed validation).
64    #[error("Gate matrix is not unitary (max deviation = {deviation:.3e})")]
65    NonUnitaryGate {
66        /// Maximum entry-wise deviation from U†U = I.
67        deviation: f64,
68    },
69
70    /// A circuit operation was applied to a register with the wrong qubit count.
71    #[error(
72        "Circuit was built for {circuit_qubits} qubit(s) but the register has {register_qubits}"
73    )]
74    CircuitRegisterMismatch {
75        /// Circuit qubit count.
76        circuit_qubits: usize,
77        /// Register qubit count.
78        register_qubits: usize,
79    },
80
81    /// A general domain / parameter error.
82    #[error("Domain error: {0}")]
83    DomainError(String),
84}
85
86/// Convenience result alias for quantum functions.
87pub type QuantumResult<T> = Result<T, QuantumError>;
scirs2_core/quantum/error.rs

scirs2_core/quantum/
error.rs
