Skip to main content

tpt_sci_quantum/
error.rs

1//! Errors produced by state construction and gate application.
2
3use thiserror::Error;
4
5/// Errors produced by state construction and gate application.
6///
7/// Note: `Eq` is intentionally not derived (some variants carry an `f64`,
8/// which has no total equality), only `PartialEq`.
9#[derive(Debug, Error, PartialEq)]
10pub enum StateError {
11    /// The requested number of qubits exceeds the supported limit.
12    #[error("cannot simulate {0} qubits: state vector would be too large (max 20)")]
13    TooManyQubits(usize),
14
15    /// A gate referenced a qubit index that does not exist.
16    #[error("qubit index {qubit} is invalid for a {n}-qubit state")]
17    InvalidQubit {
18        /// The offending qubit index.
19        qubit: usize,
20        /// The number of qubits in the state.
21        n: usize,
22    },
23
24    /// A two-qubit gate was given the same qubit for control and target.
25    #[error("control and target must differ, but both were {0}")]
26    SameQubits(usize),
27
28    /// A unitary matrix supplied to [`crate::State::apply_unitary`] had the wrong
29    /// dimension for this state's qubit count.
30    #[error(
31        "unitary must be {expected}x{expected} (2^(n+1) for an n-qubit state), but got {got}x{got}"
32    )]
33    UnitarySizeMismatch {
34        /// The required row/column count.
35        expected: usize,
36        /// The row count that was actually supplied.
37        got: usize,
38    },
39
40    /// A flat data vector supplied to [`crate::density::Matrix::from_row_major`]
41    /// (or a Kraus operator passed to
42    /// [`crate::density::DensityMatrix::apply_kraus`]) had the wrong number of
43    /// entries/dimension.
44    #[error("matrix must be {expected}x{expected}, but got {got}x{got}")]
45    MatrixSizeMismatch {
46        /// The required row/column count.
47        expected: usize,
48        /// The row/column count that was actually supplied.
49        got: usize,
50    },
51
52    /// [`crate::density::DensityMatrix::from_mixture`] was given an empty list
53    /// of states.
54    #[error("a mixture must contain at least one state")]
55    EmptyMixture,
56
57    /// [`crate::density::DensityMatrix::from_mixture`] was given mismatched
58    /// numbers of states and probabilities.
59    #[error("mixture has {states} states but {probs} probabilities")]
60    MixtureSizeMismatch {
61        /// The number of states supplied.
62        states: usize,
63        /// The number of probabilities supplied.
64        probs: usize,
65    },
66
67    /// [`crate::density::DensityMatrix::from_mixture`] was given states with
68    /// differing qubit counts.
69    #[error("mixture states must all have {expected} qubits, but found one with {got}")]
70    QubitCountMismatch {
71        /// The qubit count of the first state in the mixture.
72        expected: usize,
73        /// The qubit count of the offending state.
74        got: usize,
75    },
76
77    /// [`crate::density::DensityMatrix::from_mixture`] was given probabilities
78    /// that do not sum to `1` (within tolerance).
79    #[error("mixture probabilities must sum to 1, but summed to {0}")]
80    ProbabilitiesNotNormalized(f64),
81
82    /// [`crate::density::DensityMatrix::from_mixture`] was given a negative
83    /// probability.
84    #[error("mixture probabilities must be non-negative")]
85    NegativeProbability,
86
87    /// A noise-channel constructor (e.g.
88    /// [`crate::density::DensityMatrix::bit_flip_kraus`] or
89    /// [`crate::density::DensityMatrix::depolarizing_kraus`]) was given an
90    /// error probability outside `[0, 1]`.
91    #[error("error probability must be in [0, 1], but got {0}")]
92    InvalidProbability(f64),
93}