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}