Enum CircuitError 

pub enum CircuitError {
    DuplicateQubits,
    QubitNotFound(u32),
    QubitCountMismatch {
        expected: usize,
        actual: usize,
    },
    ParameterCountMismatch {
        expected: usize,
        actual: usize,
    },
    InvalidParameter(ParameterError),
    NoMatrixRepresentation,
    ParamEvaluationFailed(EvalError),
    IrreversibleOperation,
    InvalidControlOperation(String),
    SymbolicParameterError,
    UnresolvedParameter(String),
    InvalidParameterIndex(u32),
    OperationIndexOutOfBounds {
        index: usize,
        len: usize,
    },
    ClassicalValueStillInUse {
        index: u32,
        context: String,
    },
    InvalidParameterValue(usize, f64),
    InvalidControlFlow(String),
    InvalidDag(String),
    ForeignClassicalHandle {
        kind: &'static str,
        index: u32,
    },
    UndefinedClassicalValue {
        index: u32,
        context: String,
    },
    DuplicateClassicalValueDefinition {
        index: u32,
        first: String,
        second: String,
    },
    ClassicalValueOutOfScope {
        index: u32,
        context: String,
    },
    NonTerminalControlTransfer {
        operation: &'static str,
        context: String,
    },
    ControlFlowPresent,
    InvalidOperation(String),
}

A comprehensive error type for operations involving Quantum Circuits.

This enum aggregates errors from circuit construction, validation, and manipulation. It serves as the primary error type for the Circuit struct and its related methods.

Variants

DuplicateQubits

Thrown when attempting to add qubits that share the same unique identifier (index).

Qubit indices within a circuit must be unique to ensure unambiguous addressing.

QubitNotFound(u32)

Thrown when an operation references a qubit that is not part of the circuit.

All qubits used in operations (gates, measurements) must be explicitly added to the circuit via add_qubits or new before use.

QubitCountMismatch

Thrown when the number of qubits provided for an operation does not match its definition.

For example, applying a 2-qubit CNOT gate to 3 qubits, or a 1-qubit Custom Unitary to 2 qubits.

Fields

expected: usize

Required qubit count.

actual: usize

Supplied qubit count.

ParameterCountMismatch

Thrown when the number of parameters supplied to a fixed-arity instruction does not match its definition.

Fields

expected: usize

Required parameter count.

actual: usize

Supplied parameter count.

InvalidParameter(ParameterError)

Wraps errors raised while simplifying or evaluating symbolic parameters.

NoMatrixRepresentation

Thrown when an operation is requested to provide a unitary matrix, but none exists.

This typically happens when calling .matrix() on non-unitary instructions such as:

• Measure
• Barrier
• Reset

ParamEvaluationFailed(EvalError)

Wraps errors that occur during the evaluation of circuit parameters.

This variant propagates EvalErrors up the stack when operations like matrix generation or gate inversion fail due to invalid parameter bindings.

IrreversibleOperation

Thrown when inversion is requested for a non-unitary operation or circuit.

InvalidControlOperation(String)

Thrown when an instruction cannot be promoted to a controlled operation.

SymbolicParameterError

Thrown when a numeric result is requested from an operation whose circuit-local symbolic parameters have not been resolved.

UnresolvedParameter(String)

Thrown when a parameter cannot be resolved during circuit decomposition.

This occurs when a sub-circuit or control flow body contains symbolic parameters that are not bound to concrete values and cannot be evaluated.

InvalidParameterIndex(u32)

Thrown when a parameter index is out of range.

This indicates internal data corruption or an inconsistency between the circuit’s parameter table and the indices stored in operations.

OperationIndexOutOfBounds

Thrown when an operation index is outside the circuit operation list.

index is the requested zero-based index and len is the operation count at the time of the request.

Fields

index: usize

Requested zero-based operation index.

len: usize

Number of operations in the circuit.

ClassicalValueStillInUse

Thrown when deleting an operation would remove a classical value that is still read by another operation.

Fields

index: u32

Circuit-local value index.

context: String

Description of the remaining use site.

InvalidParameterValue(usize, f64)

Thrown when a gate parameter has an invalid value (NaN or Infinity).

This occurs when appending or evaluating a gate with a non-finite fixed parameter. The tuple stores the parameter position and rejected value.

InvalidControlFlow(String)

Thrown when the control flow graph (CFG) has an invalid or inconsistent structure.

This error indicates that the DAG representation of the circuit is malformed, which can occur when:

• A Branch terminator lacks required TrueBranch or FalseBranch edges
• A Jump terminator references a non-existent block
• The entry block is not set
• Edges reference nodes that don’t exist in the graph

Examples

This error is returned when converting an invalid CircuitDag back to a Circuit if the DAG structure was manually modified and left in an inconsistent state.

InvalidDag(String)

Thrown when the circuit dependency DAG has an invalid or inconsistent structure.

ForeignClassicalHandle

Thrown when a classical handle was created by a different circuit.

Fields

kind: &'static str

Human-readable handle kind.

index: u32

Circuit-local handle index.

UndefinedClassicalValue

Thrown when a classical value is read before it is available at a use site.

Fields

index: u32

Circuit-local value index.

context: String

Description of the invalid use site.

DuplicateClassicalValueDefinition

Thrown when validation finds multiple producers for one immutable value.

Fields

index: u32

Circuit-local value index.

first: String

Description of the first definition site.

second: String

Description of the conflicting definition site.

ClassicalValueOutOfScope

Thrown when a classical value is used outside its defining control-flow region.

Fields

index: u32

Circuit-local value index.

context: String

Description of the invalid use site.

NonTerminalControlTransfer

Thrown when break or continue is followed by another operation in the same body.

Fields

operation: &'static str

Control-transfer operation name.

context: String

Description of the containing body.

ControlFlowPresent

Thrown when Circuit::depth(recurse=false) is called on a circuit that contains any classical control-flow operation (if/while/for/ switch/break/continue) at any nesting depth. Pass recurse = true to obtain an estimated depth that unfolds control flow.

InvalidOperation(String)

Catch-all for an invalid operation that has no more specific error variant.

Trait Implementations

impl Debug for CircuitError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for CircuitError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for CircuitError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<CircuitError> for CompilerError

fn from(source: CircuitError) -> Self

Converts to this type from the input type.

impl From<CircuitError> for VerifyError

fn from(source: CircuitError) -> Self

Converts to this type from the input type.

impl From<CircuitError> for ErrorMitigationError

fn from(source: CircuitError) -> Self

Converts to this type from the input type.

impl From<CircuitError> for QasmParseError

fn from(value: CircuitError) -> Self

Converts to this type from the input type.

impl From<CircuitError> for Qasm3ParseError

fn from(value: CircuitError) -> Self

Converts to this type from the input type.

impl From<CircuitError> for QisError

fn from(source: CircuitError) -> Self

Converts to this type from the input type.

impl From<CircuitError> for VisualizationError

fn from(source: CircuitError) -> Self

Converts to this type from the input type.

impl From<EvalError> for CircuitError

fn from(source: EvalError) -> Self

Converts to this type from the input type.

impl From<ParameterError> for CircuitError

fn from(source: ParameterError) -> Self

Converts to this type from the input type.