Struct Device 

pub struct Device { /* private fields */ }

Represents a quantum device’s hardware characteristics and topology.

The Device struct is a fundamental component for compiler optimization, mapping, routing, and noise-aware scheduling. It encapsulates:

• The physical connectivity (Topology) between qubits.
• Available and faulty qubits.
• Device-wide default parameters (e.g., T1, T2, gate error rates).
• Specific physical properties and supported instructions for individual qubits and coupling edges.

This structure provides the necessary physical constraints and fidelity data required to simulate noise models or compile quantum circuits onto realistic backend hardware.

Example

use std::collections::HashSet;
use cqlib_core::device::{Device, PhysicalQubit, QubitProp, Topology};

// Create a 2-qubit topology
let q0 = PhysicalQubit::new(0);
let q1 = PhysicalQubit::new(1);
let topo = Topology::new(vec![q0, q1], vec![(q0, q1, "G1".to_string())]).unwrap();

// Initialize a device with defaults
let mut device = Device::new("mock_device", HashSet::from_iter([q0, q1]), topo).unwrap()
    .with_default_t1(50.0)
    .with_default_t2(25.0)
    .with_default_readout_error(0.01);

// Add specific properties for Qubit 0
let q0_prop = QubitProp::new(0.05).with_t1(40.0);
device.add_qubit_properties(q0, q0_prop).unwrap();

// Query T1, using specific properties if available, else fallback to defaults
assert_eq!(device.get_t1(q0), Some(40.0));
assert_eq!(device.get_t1(q1), Some(50.0));

Implementations

impl Device

pub fn new( name: impl Into<String>, qubits: HashSet<PhysicalQubit>, topology: Topology, ) -> Result<Self, DeviceError>

Creates a new Device with the specified name and topology.

pub fn line( name: impl Into<String>, num_qubits: u32, ) -> Result<Self, DeviceError>

Creates a device with physical qubits connected as a directed line.

The device contains physical qubits 0..num_qubits, all of which are online. Native gates and calibration data are left unset and may be configured with the builder-style setters.

pub fn line_from_qubits( name: impl Into<String>, physical_qubits: Vec<PhysicalQubit>, ) -> Result<Self, DeviceError>

Creates a device with the supplied physical qubits connected as a directed line.

The device contains every supplied physical qubit, all of which are online. Couplings follow the supplied order: qubits[i] -> qubits[i + 1].

Errors

Returns DeviceError::EmptyDevice if physical_qubits is empty.

pub fn bidirectional_line( name: impl Into<String>, num_qubits: u32, ) -> Result<Self, DeviceError>

Creates a device with physical qubits connected as a bidirectional line.

The device contains physical qubits 0..num_qubits, all of which are online. Adjacent qubits are connected in both directions.

pub fn ring( name: impl Into<String>, num_qubits: u32, ) -> Result<Self, DeviceError>

Creates a device with physical qubits connected as a bidirectional ring.

The device contains physical qubits 0..num_qubits, all of which are online. For two or more qubits, each qubit is connected to its successor modulo num_qubits in both directions.

pub fn star( name: impl Into<String>, num_qubits: u32, center: u32, ) -> Result<Self, DeviceError>

Creates a device with physical qubits connected as a bidirectional star.

The device contains physical qubits 0..num_qubits, all of which are online. Every non-center qubit is connected to center in both directions.

pub fn grid( name: impl Into<String>, rows: u32, cols: u32, ) -> Result<Self, DeviceError>

Creates a device with physical qubits connected as a bidirectional grid.

Qubit IDs are assigned in row-major order. Horizontal and vertical nearest-neighbor couplings are added in both directions.

pub fn from_edges( name: impl Into<String>, num_qubits: u32, edges: &[(u32, u32)], ) -> Result<Self, DeviceError>

Creates a device with physical qubits 0..num_qubits and explicit directed edges.

Each (control, target) pair in edges becomes one directed coupling.

pub fn with_invalid_qubits( self, invalid_qubits: HashSet<PhysicalQubit>, ) -> Result<Self, DeviceError>

Sets the offline or faulty physical qubits using the builder pattern.

Errors

Returns DeviceError::QubitNotInDevice if any invalid qubit is not registered with the device.

pub fn set_invalid_qubits( &mut self, invalid_qubits: HashSet<PhysicalQubit>, ) -> Result<(), DeviceError>

Sets the offline or faulty physical qubits.

Errors

Returns DeviceError::QubitNotInDevice if any invalid qubit is not registered with the device. The existing set is preserved on error.

pub fn with_native_gates( self, gates: Vec<Instruction>, ) -> Result<Self, DeviceError>

Sets the device-wide default native gates.

This does not add, remove, or otherwise synchronize native instructions stored on individual qubits or directed edges.

Errors

Returns DeviceError if any entry is not a standard gate or acts on more than two qubits.

pub fn set_native_gates( &mut self, gates: Vec<Instruction>, ) -> Result<(), DeviceError>

Replaces the device-wide native defaults after validating the full list.

The existing defaults are preserved when any entry is invalid.

Errors

Returns DeviceError if any entry is not a standard gate or acts on more than two qubits.

pub fn with_calibration_time(self, time: OffsetDateTime) -> Self

Sets the system calibration timestamp.

pub fn set_calibration_time(&mut self, time: OffsetDateTime)

pub fn with_default_t1(self, t1: f64) -> Self

Sets the default T1 time (μs).

pub fn set_default_t1(&mut self, t1: f64)

pub fn with_default_t2(self, t2: f64) -> Self

Sets the default T2 time (μs).

pub fn set_default_t2(&mut self, t2: f64)

pub fn with_default_readout_error(self, error: f64) -> Self

Sets the default readout error rate.

pub fn set_default_readout_error(&mut self, error: f64)

pub fn with_default_single_qubit_error(self, error: f64) -> Self

Sets the default single-qubit gate error rate.

pub fn set_default_single_qubit_error(&mut self, error: f64)

pub fn with_default_two_qubit_error(self, error: f64) -> Self

Sets the default two-qubit gate error rate.

pub fn set_default_two_qubit_error(&mut self, error: f64)

pub fn add_qubit_properties( &mut self, qubit: PhysicalQubit, props: QubitProp, ) -> Result<(), DeviceError>

Adds properties for a specific qubit.

Errors

Returns DeviceError::QubitNotInDevice if the qubit is not registered with the device, or DeviceError::QubitNotInTopology if it is registered but absent from the topology. Properties may be retained for a registered qubit while it is marked invalid/offline.

pub fn add_edge_properties( &mut self, control: PhysicalQubit, target: PhysicalQubit, props: EdgeProp, ) -> Result<(), DeviceError>

Adds properties for a specific coupling edge.

Errors

Returns DeviceError::EdgeNotInTopology if the edge is not in the device’s topology.

pub fn name(&self) -> &str

Gets the name of the device.

pub fn qubits(&self) -> impl Iterator<Item = PhysicalQubit> + '_

Gets an iterator over the physical qubits registered with the device.

pub fn invalid_qubits(&self) -> impl Iterator<Item = PhysicalQubit> + '_

Gets an iterator over the invalid (offline/faulty) qubits.

pub fn is_usable_qubit(&self, qubit: PhysicalQubit) -> bool

Returns whether a physical qubit is registered and not marked invalid.

pub fn usable_qubits(&self) -> impl Iterator<Item = PhysicalQubit> + '_

Gets an iterator over registered physical qubits that are not invalid.

pub fn num_usable_qubits(&self) -> usize

Returns the number of registered physical qubits that are not invalid.

pub fn topology(&self) -> &Topology

Gets a reference to the device’s connectivity topology.

pub fn native_gates(&self) -> &[Instruction]

Gets the default native gates supported by the device.

pub fn qubit_properties(&self, qubit: PhysicalQubit) -> Option<&QubitProp>

Gets the properties of a specific qubit.

pub fn edge_properties( &self, control: PhysicalQubit, target: PhysicalQubit, ) -> Option<&EdgeProp>

Gets the properties of a specific coupling edge.

pub fn supports_native_instruction( &self, instruction: &Instruction, qargs: &[PhysicalQubit], ) -> bool

Returns whether a native hardware instruction can execute on the exact ordered physical qargs.

This query evaluates capability only; calibration error rates and durations do not affect the result. Standard one- and two-qubit gates follow the device default/local-override contract, and two-qubit qargs are directional. Structured control flow, runtime operations, and composite gates are not atomic device capabilities; validate them with Self::validate_operation or Self::validate_circuit instead.

pub fn validate_operation( &self, operation: &Operation, ) -> Result<(), DeviceValidationError>

Validates one operation interpreted in the physical-qubit ID space.

Structured control-flow bodies are checked recursively. This method is read-only and never performs layout, routing, lowering, or direction correction.

pub fn validate_value_operation( &self, operation: &ValueOperation, ) -> Result<(), DeviceValidationError>

Validates one value-level operation interpreted in the physical-qubit ID space.

This is the construction-IR counterpart of Self::validate_operation. Structured control-flow bodies are checked recursively without first converting the operation into a Circuit, so circuit-owned classical variables and values are not required solely for device validation.

pub fn validate_circuit( &self, circuit: &Circuit, ) -> Result<(), DeviceValidationError>

Validates a circuit interpreted in the physical-qubit ID space.

Validation stops at the first unsupported operation. The circuit is not modified and must already have completed logical-to-physical mapping and hardware lowering.

pub fn single_qubit_error( &self, qubit: PhysicalQubit, instruction: &Instruction, ) -> Option<f64>

Gets the error rate for instruction on a single physical qubit.

Returns None if the qubit is not usable or does not support the instruction. A non-empty local native-instruction list is a complete capability override; otherwise device-wide one-qubit defaults apply. The default error rate is used only for an inherited supported gate.

pub fn two_qubit_error( &self, control: PhysicalQubit, target: PhysicalQubit, instruction: &Instruction, ) -> Option<f64>

Gets the error rate for instruction on a directed coupling.

Returns None if either endpoint is not usable, the exact directed coupling does not exist, or that edge does not support the instruction. A non-empty local native-instruction list is a complete capability override; otherwise device-wide two-qubit defaults apply. The default error rate is used only for an inherited supported gate.

pub fn edge_error( &self, control: PhysicalQubit, target: PhysicalQubit, ) -> Option<f64>

Gets a direction-specific coupling error suitable for routing costs.

Returns the best available native two-qubit instruction error on the edge, or the default two-qubit error if no per-edge calibration exists.

This instruction-agnostic calibration query does not prove that any two-qubit instruction is supported, even when it returns Some. It must not be used as a capability predicate. Use Self::supports_native_instruction or Self::two_qubit_error when a concrete instruction capability matters.

pub fn get_t1(&self, qubit: PhysicalQubit) -> Option<f64>

Gets the T1 relaxation time for a qubit (μs).

Falls back to the default T1 time if not specified for the qubit.

pub fn get_t2(&self, qubit: PhysicalQubit) -> Option<f64>

Gets the T2 dephasing time for a qubit (μs).

Falls back to the default T2 time if not specified for the qubit.

pub fn get_readout_error(&self, qubit: PhysicalQubit) -> Option<f64>

Gets the readout error rate for a qubit.

Falls back to the default readout error if not specified for the qubit.

pub fn default_single_qubit_error(&self) -> Option<f64>

Gets the default single-qubit gate error rate.

pub fn default_two_qubit_error(&self) -> Option<f64>

Gets the default two-qubit gate error rate.

pub fn default_t1(&self) -> Option<f64>

Gets the default T1 relaxation time.

pub fn default_t2(&self) -> Option<f64>

Gets the default T2 dephasing time.

pub fn default_readout_error(&self) -> Option<f64>

Gets the default readout error rate.

pub fn calibration_time(&self) -> Option<OffsetDateTime>

Gets the system calibration timestamp.

Trait Implementations

impl Clone for Device

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Device

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

Formats the value using the given formatter.