Enum KetError 

#[repr(i32)]
pub enum KetError {
    Success = 0,
    DuplicateControlQubit = 1,
    ControlTargetConflict = 2,
    ControlParameterizedGate = 3,
    QubitLimitExceeded = 4,
    QubitIndexOutOfRange = 5,
    ProcessTerminated = 6,
    GateAppendForbidden = 7,
    MeasurementUnavailableInBatch = 8,
    SamplingUnavailable = 9,
    ExpectationValueUnavailable = 10,
    DumpUnavailableInBatch = 11,
    NoPendingMeasurement = 12,
    ExplicitExecuteInLiveMode = 13,
    ExecutionFailed = 14,
    ShotCountInvalid = 15,
    NativeGateUnsupported = 16,
    GateUnsupported = 17,
    ExpValueNotSupported = 18,
    SerdeError = 19,
    InvalidBias = 20,
    NativeGradientUnsuported = 21,
    UnknownError = 22,
}

The exhaustive set of errors that Libket operations can produce.

Every variant has a stable, non-zero integer discriminant (with the sole exception of KetError::Success, which is always 0) so that the enum can be used as a C-compatible status code.

Variants

Success = 0

No error occurred. This variant is only used as a sentinel value in FFI contexts where an integer 0 signals success.

DuplicateControlQubit = 1

A qubit was specified as a control qubit more than once in the same gate instruction. Each physical qubit may only appear once in the control set.

Returned by crate::ir::gate::GateInstruction::control (and transitively by crate::ir::block::BasicBlock::control) when control_qubits contains a duplicate entry or overlaps with the existing control set of the instruction.

Example

Calling gate.control(&[q0, q0]) would trigger this error.

ControlTargetConflict = 2

A qubit was used as both a control and the target of the same gate instruction, which is physically undefined.

Returned by crate::ir::gate::GateInstruction::control (and transitively by crate::ir::block::BasicBlock::control) when one of the provided control_qubits equals self.target.

Example

Calling gate.control(&[gate.target]) would trigger this error.

ControlParameterizedGate = 3

An attempt was made to add control qubits to a parameterized gate.

Adding control qubits to gates with Param::Ref parameters is not supported.

QubitLimitExceeded = 4

The process has already allocated the maximum number of qubits permitted by the QPU configuration and no additional qubits can be created.

Returned by crate::process::Process::alloc when qubit_counter == qpu_config.num_qubits.

QubitIndexOutOfRange = 5

A gate or measurement referenced a qubit index that exceeds the number of qubits allocated so far by the current process.

Returned by crate::process::Process::append_block when the maximum qubit index referenced inside the block is ≥ qubit_counter. Call crate::process::Process::alloc to allocate the required qubits before appending the block.

ProcessTerminated = 6

An attempt was made to allocate a qubit on a process that has already been executed and is in the Terminated state.

Returned by crate::process::Process::alloc when process.state == ProcessState::Terminated. Create a new crate::process::Process to run additional circuits.

GateAppendForbidden = 7

An attempt was made to append a gate block to a process that is not in the AcceptingGate state.

Returned by crate::process::Process::append_block when the process state is anything other than crate::process::ProcessState::AcceptingGate, for example, after sample or exp_value has already been registered in batch mode (which advancesthe state to crate::process::ProcessState::ReadyToExecute or crate::process::ProcessState::AcceptingHamiltonian).

MeasurementUnavailableInBatch = 8

A single-shot mid-circuit measurement was requested but the process is not configured for live execution.

Returned by crate::process::Process::measure when qpu_config.quantum_execution is Some(QuantumExecution::Batch { .. }) or None. Measurements that collapse qubit state and return a result inline are only available in crate::execution::QuantumExecution::Live mode. Use sample for batch-mode histograms.

SamplingUnavailable = 9

A sample request was made but cannot be registered in the current process state.

Returned by crate::process::Process::sample in batch mode when the process state is not crate::process::ProcessState::AcceptingGate (i.e., a sample or exp_value request has already been registered), or when no execution backend is configured (qpu_config.quantum_execution == None). Only one sample call is permitted per batch execution.

ExpectationValueUnavailable = 10

An exp_value request was made but cannot be registered in the current process state.

Returned by crate::process::Process::exp_value in batch mode when the process state is not crate::process::ProcessState::AcceptingGate or crate::process::ProcessState::AcceptingHamiltonian, for example, after the process has transitioned to ReadyToExecute because a sample request or a gradient-enabled exp_value was already registered, or when no execution backend is configured.

DumpUnavailableInBatch = 11

A quantum state dump was requested but the process is not configured for live execution.

Returned by crate::process::Process::dump when qpu_config.quantum_execution is Some(QuantumExecution::Batch { .. }) or None. Full state-vector inspection is only available in crate::execution::QuantumExecution::Live mode.

NoPendingMeasurement = 12

execute was called on a process that has no pending measurement or expectation-value request.

Returned by crate::process::Process::execute when the process state is crate::process::ProcessState::AcceptingGate, meaning neither sample nor exp_value has been called since the last execution. Register at least one sample or exp_value request before calling execute in batch mode.

ExplicitExecuteInLiveMode = 13

execute (or an internal compile) was called on a process configured for live execution.

Returned by crate::process::Process::execute when qpu_config.quantum_execution is Some(QuantumExecution::Live { .. }). In live mode every gate is dispatched to the backend immediately as it is appended; there is no deferred compilation step.

ExecutionFailed = 14

The quantum execution backend reported an unrecoverable failure.

This is a generic error code that backend implementations should return for hardware faults, decoherence events, calibration errors, or simulator assertion failures. It surfaces in Rust through KetError::from_error_code after the C callback returns a non-zero status. Consult the backend’s own error channel for a more detailed diagnostic.

ShotCountInvalid = 15

The requested number of measurement shots is out of range for the active backend.

Backend implementations should return this error code from their sample callback when shots is zero, exceeds an implementation-defined maximum, or otherwise falls outside the backend’s accepted range. It reaches Rust via KetError::from_error_code.

NativeGateUnsupported = 16

A gate produced by the crate::execution::NativeGateSet translation is not supported by the backend.

Custom crate::execution::NativeGateSet implementations should return this error from translate, cnot, or swap when the requested operation cannot be expressed in the hardware’s instruction set. It is also the recommended return code for batch-execution C callbacks that receive an unrecognized gate name.

GateUnsupported = 17

A gate instruction from the Libket IR was received by a backend that does not accept IR-level gates.

Returned as the default implementation of crate::execution::BatchExecution::sample and crate::execution::BatchExecution::exp_value when the backend only supports native gates. Implementors that accept IR-level gates should override those methods instead of propagating this error.

ExpValueNotSupported = 18

The backend does not support native expectation-value computation but crate::execution::ExpValueStrategy::Native was selected.

Backend callbacks should return this error code from their exp_value callback when the hardware or simulator cannot compute expectation values directly. Switch to crate::execution::ExpValueStrategy::QubitWiseCommutation or crate::execution::ExpValueStrategy::ClassicalShadows to estimate expectation values through repeated sampling instead.

SerdeError = 19

JSON serialization or deserialization failed in the C API layer.

Emitted when serde_json fails to serialize a Rust value to a C string, or when a JSON string received from a C callback cannot be parsed into the expected Rust type. Verify that the JSON payload conforms to the schema expected by the called function.

InvalidBias = 20

The classical shadows bias tuple (X, Y, Z) has all three weights set to zero, making it impossible to sample a measurement basis.

Returned by crate::process::Process::execute (via execute_classical_shadows) when crate::execution::ExpValueStrategy::ClassicalShadows is configured with bias = (0, 0, 0). At least one of the three weights must be non-zero.

NativeGradientUnsuported = 21

The backend does not support native gradient computation but crate::execution::GradientStrategy::Native was selected.

Returned as the default implementation of crate::execution::BatchExecution::gradient. Switch to crate::execution::GradientStrategy::ParameterShiftRule to estimate gradients analytically via repeated circuit evaluations.

UnknownError = 22

An unrecognized error code was received from a C callback.

Returned by KetError::from_error_code as a catch-all when the integer code does not match any known variant. This typically means a C-side backend returned a non-standard status code. Treat it as an unrecoverable backend error.

Implementations

impl KetError

pub const fn error_code(&self) -> i32

Returns the integer discriminant of this error variant.

The returned value is stable and suitable for FFI use. Success always returns 0; all other variants return a positive non-zero value.

pub fn from_error_code(error_code: i32) -> Self

Reconstructs a KetError from its integer discriminant.

Variants that carry additional context (such as qubit indices) are reconstructed with sentinel values (0 for usize fields) because the context is not preserved in the raw integer code.

Safety

The caller must guarantee that error_code was produced by a prior call to KetError::error_code. Passing an arbitrary integer is undefined behaviour because this function uses std::mem::transmute internally for the simple variants and pattern-matches for the contextual ones.

Trait Implementations

impl Clone for KetError

fn clone(&self) -> KetError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KetError

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

Formats the value using the given formatter.

impl Display for KetError

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

Formats the value using the given formatter.

impl Eq for KetError

impl Error for KetError

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 PartialEq for KetError

fn eq(&self, other: &KetError) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for KetError