Circuits API Reference¶

Unverified examples

This page predates the current release and parts of it describe planned or older API. Only 0 of 13 code snippets on this page run as-is today. For verified, runnable code see the Quick Start, the Showcase and the Backends guide.

SuperQuantX provides comprehensive quantum circuit construction, manipulation, and execution capabilities. This API reference covers quantum circuits, gates, measurements, and noise modeling.

Quantum Circuits¶

Quantum Circuit¶

superquantx.circuits.QuantumCircuit ¶

QuantumCircuit(num_qubits: int, num_classical_bits: int | None = None, name: str | None = None)

Quantum circuit representation with gate operations and measurements

This class provides a high-level interface for building and manipulating quantum circuits compatible with multiple quantum computing frameworks.

Initialize a quantum circuit

Parameters:

Name	Type	Description	Default
`num_qubits`	`int`	Number of qubits in the circuit	required
`num_classical_bits`	`int \| None`	Number of classical bits (defaults to num_qubits)	`None`
`name`	`str \| None`	Optional circuit name	`None`

Source code in src/superquantx/circuits.py

def __init__(
    self,
    num_qubits: int,
    num_classical_bits: int | None = None,
    name: str | None = None
):
    """Initialize a quantum circuit

    Args:
        num_qubits: Number of qubits in the circuit
        num_classical_bits: Number of classical bits (defaults to num_qubits)
        name: Optional circuit name

    """
    self.num_qubits = num_qubits
    self.num_classical_bits = num_classical_bits or num_qubits
    self.name = name or f"circuit_{id(self)}"

    self.quantum_registers: list[QuantumRegister] = [
        QuantumRegister(name="q", size=num_qubits)
    ]
    self.classical_registers: list[ClassicalRegister] = [
        ClassicalRegister(name="c", size=self.num_classical_bits)
    ]

    self.gates: list[QuantumGate] = []
    self.measurements: list[tuple[int, int]] = []  # (qubit_index, classical_bit_index)
    self.barriers: list[list[int]] = []  # Barrier positions

Functions¶

copy ¶

copy() -> QuantumCircuit

Create a deep copy of the circuit

Source code in src/superquantx/circuits.py

def copy(self) -> "QuantumCircuit":
    """Create a deep copy of the circuit"""
    return deepcopy(self)

add_register ¶

add_register(register: QuantumRegister | ClassicalRegister) -> None

Add a quantum or classical register to the circuit

Source code in src/superquantx/circuits.py

def add_register(self, register: QuantumRegister | ClassicalRegister) -> None:
    """Add a quantum or classical register to the circuit"""
    if isinstance(register, QuantumRegister):
        self.quantum_registers.append(register)
        self.num_qubits += register.size
    elif isinstance(register, ClassicalRegister):
        self.classical_registers.append(register)
        self.num_classical_bits += register.size

h ¶

h(qubit: int) -> QuantumCircuit

Apply Hadamard gate

Source code in src/superquantx/circuits.py

def h(self, qubit: int) -> "QuantumCircuit":
    """Apply Hadamard gate"""
    self.gates.append(QuantumGate(name="H", qubits=[qubit]))
    return self

x ¶

x(qubit: int) -> QuantumCircuit

Apply Pauli-X gate

Source code in src/superquantx/circuits.py

def x(self, qubit: int) -> "QuantumCircuit":
    """Apply Pauli-X gate"""
    self.gates.append(QuantumGate(name="X", qubits=[qubit]))
    return self

y ¶

y(qubit: int) -> QuantumCircuit

Apply Pauli-Y gate

Source code in src/superquantx/circuits.py

def y(self, qubit: int) -> "QuantumCircuit":
    """Apply Pauli-Y gate"""
    self.gates.append(QuantumGate(name="Y", qubits=[qubit]))
    return self

z ¶

z(qubit: int) -> QuantumCircuit

Apply Pauli-Z gate

Source code in src/superquantx/circuits.py

def z(self, qubit: int) -> "QuantumCircuit":
    """Apply Pauli-Z gate"""
    self.gates.append(QuantumGate(name="Z", qubits=[qubit]))
    return self

s ¶

s(qubit: int) -> QuantumCircuit

Apply S gate (phase gate)

Source code in src/superquantx/circuits.py

def s(self, qubit: int) -> "QuantumCircuit":
    """Apply S gate (phase gate)"""
    self.gates.append(QuantumGate(name="S", qubits=[qubit]))
    return self

sdg ¶

sdg(qubit: int) -> QuantumCircuit

Apply S† gate (inverse phase gate)

Source code in src/superquantx/circuits.py

def sdg(self, qubit: int) -> "QuantumCircuit":
    """Apply S† gate (inverse phase gate)"""
    self.gates.append(QuantumGate(name="SDG", qubits=[qubit]))
    return self

t ¶

t(qubit: int) -> QuantumCircuit

Apply T gate

Source code in src/superquantx/circuits.py

def t(self, qubit: int) -> "QuantumCircuit":
    """Apply T gate"""
    self.gates.append(QuantumGate(name="T", qubits=[qubit]))
    return self

tdg ¶

tdg(qubit: int) -> QuantumCircuit

Apply T† gate

Source code in src/superquantx/circuits.py

def tdg(self, qubit: int) -> "QuantumCircuit":
    """Apply T† gate"""
    self.gates.append(QuantumGate(name="TDG", qubits=[qubit]))
    return self

rx ¶

rx(theta: float, qubit: int) -> QuantumCircuit

Apply rotation around X-axis

Source code in src/superquantx/circuits.py

def rx(self, theta: float, qubit: int) -> "QuantumCircuit":
    """Apply rotation around X-axis"""
    self.gates.append(QuantumGate(name="RX", qubits=[qubit], parameters=[theta]))
    return self

ry ¶

ry(theta: float, qubit: int) -> QuantumCircuit

Apply rotation around Y-axis

Source code in src/superquantx/circuits.py

def ry(self, theta: float, qubit: int) -> "QuantumCircuit":
    """Apply rotation around Y-axis"""
    self.gates.append(QuantumGate(name="RY", qubits=[qubit], parameters=[theta]))
    return self

rz ¶

rz(theta: float, qubit: int) -> QuantumCircuit

Apply rotation around Z-axis

Source code in src/superquantx/circuits.py

def rz(self, theta: float, qubit: int) -> "QuantumCircuit":
    """Apply rotation around Z-axis"""
    self.gates.append(QuantumGate(name="RZ", qubits=[qubit], parameters=[theta]))
    return self

u ¶

u(theta: float, phi: float, lam: float, qubit: int) -> QuantumCircuit

Apply general unitary gate U(θ,φ,λ)

Source code in src/superquantx/circuits.py

def u(self, theta: float, phi: float, lam: float, qubit: int) -> "QuantumCircuit":
    """Apply general unitary gate U(θ,φ,λ)"""
    self.gates.append(
        QuantumGate(name="U", qubits=[qubit], parameters=[theta, phi, lam])
    )
    return self

cx ¶

cx(control: int, target: int) -> QuantumCircuit

Apply CNOT gate

Source code in src/superquantx/circuits.py

def cx(self, control: int, target: int) -> "QuantumCircuit":
    """Apply CNOT gate"""
    self.gates.append(QuantumGate(name="CNOT", qubits=[control, target]))
    return self

cnot ¶

cnot(control: int, target: int) -> QuantumCircuit

Apply CNOT gate (alias for cx)

Source code in src/superquantx/circuits.py

def cnot(self, control: int, target: int) -> "QuantumCircuit":
    """Apply CNOT gate (alias for cx)"""
    return self.cx(control, target)

cy ¶

cy(control: int, target: int) -> QuantumCircuit

Apply controlled-Y gate

Source code in src/superquantx/circuits.py

def cy(self, control: int, target: int) -> "QuantumCircuit":
    """Apply controlled-Y gate"""
    self.gates.append(QuantumGate(name="CY", qubits=[control, target]))
    return self

cz ¶

cz(control: int, target: int) -> QuantumCircuit

Apply controlled-Z gate

Source code in src/superquantx/circuits.py

def cz(self, control: int, target: int) -> "QuantumCircuit":
    """Apply controlled-Z gate"""
    self.gates.append(QuantumGate(name="CZ", qubits=[control, target]))
    return self

swap ¶

swap(qubit1: int, qubit2: int) -> QuantumCircuit

Apply SWAP gate

Source code in src/superquantx/circuits.py

def swap(self, qubit1: int, qubit2: int) -> "QuantumCircuit":
    """Apply SWAP gate"""
    self.gates.append(QuantumGate(name="SWAP", qubits=[qubit1, qubit2]))
    return self

crx ¶

crx(theta: float, control: int, target: int) -> QuantumCircuit

Apply controlled rotation around X-axis

Source code in src/superquantx/circuits.py

def crx(self, theta: float, control: int, target: int) -> "QuantumCircuit":
    """Apply controlled rotation around X-axis"""
    self.gates.append(
        QuantumGate(name="CRX", qubits=[control, target], parameters=[theta])
    )
    return self

cry ¶

cry(theta: float, control: int, target: int) -> QuantumCircuit

Apply controlled rotation around Y-axis

Source code in src/superquantx/circuits.py

def cry(self, theta: float, control: int, target: int) -> "QuantumCircuit":
    """Apply controlled rotation around Y-axis"""
    self.gates.append(
        QuantumGate(name="CRY", qubits=[control, target], parameters=[theta])
    )
    return self

crz ¶

crz(theta: float, control: int, target: int) -> QuantumCircuit

Apply controlled rotation around Z-axis

Source code in src/superquantx/circuits.py

def crz(self, theta: float, control: int, target: int) -> "QuantumCircuit":
    """Apply controlled rotation around Z-axis"""
    self.gates.append(
        QuantumGate(name="CRZ", qubits=[control, target], parameters=[theta])
    )
    return self

ccx ¶

ccx(control1: int, control2: int, target: int) -> QuantumCircuit

Apply Toffoli (CCNOT) gate

Source code in src/superquantx/circuits.py

def ccx(self, control1: int, control2: int, target: int) -> "QuantumCircuit":
    """Apply Toffoli (CCNOT) gate"""
    self.gates.append(
        QuantumGate(name="TOFFOLI", qubits=[control1, control2, target])
    )
    return self

toffoli ¶

toffoli(control1: int, control2: int, target: int) -> QuantumCircuit

Apply Toffoli gate (alias for ccx)

Source code in src/superquantx/circuits.py

def toffoli(self, control1: int, control2: int, target: int) -> "QuantumCircuit":
    """Apply Toffoli gate (alias for ccx)"""
    return self.ccx(control1, control2, target)

cswap ¶

cswap(control: int, target1: int, target2: int) -> QuantumCircuit

Apply controlled SWAP (Fredkin) gate

Source code in src/superquantx/circuits.py

def cswap(self, control: int, target1: int, target2: int) -> "QuantumCircuit":
    """Apply controlled SWAP (Fredkin) gate"""
    self.gates.append(
        QuantumGate(name="FREDKIN", qubits=[control, target1, target2])
    )
    return self

fredkin ¶

fredkin(control: int, target1: int, target2: int) -> QuantumCircuit

Apply Fredkin gate (alias for cswap)

Source code in src/superquantx/circuits.py

def fredkin(self, control: int, target1: int, target2: int) -> "QuantumCircuit":
    """Apply Fredkin gate (alias for cswap)"""
    return self.cswap(control, target1, target2)

measure ¶

measure(qubit: int, classical_bit: int) -> QuantumCircuit

Measure a qubit into a classical bit

Source code in src/superquantx/circuits.py

def measure(self, qubit: int, classical_bit: int) -> "QuantumCircuit":
    """Measure a qubit into a classical bit"""
    self.measurements.append((qubit, classical_bit))
    return self

measure_all ¶

measure_all() -> QuantumCircuit

Measure all qubits into classical bits

Source code in src/superquantx/circuits.py

def measure_all(self) -> "QuantumCircuit":
    """Measure all qubits into classical bits"""
    for i in range(min(self.num_qubits, self.num_classical_bits)):
        self.measure(i, i)
    return self

barrier ¶

barrier(qubits: list[int] | None = None) -> QuantumCircuit

Add a barrier (prevents gate reordering across barrier)

Source code in src/superquantx/circuits.py

def barrier(self, qubits: list[int] | None = None) -> "QuantumCircuit":
    """Add a barrier (prevents gate reordering across barrier)"""
    if qubits is None:
        qubits = list(range(self.num_qubits))
    self.barriers.append(qubits)
    return self

compose ¶

compose(other: QuantumCircuit, qubits: list[int] | None = None) -> QuantumCircuit

Compose this circuit with another circuit

Parameters:

Name	Type	Description	Default
`other`	`QuantumCircuit`	Circuit to compose with	required
`qubits`	`list[int] \| None`	Qubit mapping for the other circuit	`None`

Returns:

Type	Description
`QuantumCircuit`	New composed circuit

Source code in src/superquantx/circuits.py

def compose(self, other: "QuantumCircuit", qubits: list[int] | None = None) -> "QuantumCircuit":
    """Compose this circuit with another circuit

    Args:
        other: Circuit to compose with
        qubits: Qubit mapping for the other circuit

    Returns:
        New composed circuit

    """
    if qubits is None:
        qubits = list(range(other.num_qubits))

    if len(qubits) != other.num_qubits:
        raise ValueError("Qubit mapping must match other circuit size")

    new_circuit = self.copy()

    # Map gates from other circuit
    for gate in other.gates:
        mapped_qubits = [qubits[q] for q in gate.qubits]
        new_gate = QuantumGate(
            name=gate.name,
            qubits=mapped_qubits,
            parameters=gate.parameters,
            classical_condition=gate.classical_condition
        )
        new_circuit.gates.append(new_gate)

    # Map measurements
    for qubit, cbit in other.measurements:
        new_circuit.measurements.append((qubits[qubit], cbit))

    return new_circuit

inverse ¶

inverse() -> QuantumCircuit

Return the inverse (adjoint) of the circuit

Source code in src/superquantx/circuits.py

def inverse(self) -> "QuantumCircuit":
    """Return the inverse (adjoint) of the circuit"""
    inv_circuit = QuantumCircuit(self.num_qubits, self.num_classical_bits)

    # Reverse gates and apply inverse
    for gate in reversed(self.gates):
        inv_gate = self._inverse_gate(gate)
        inv_circuit.gates.append(inv_gate)

    return inv_circuit

to_dict ¶

to_dict() -> dict[str, Any]

Convert circuit to dictionary representation

Source code in src/superquantx/circuits.py

def to_dict(self) -> dict[str, Any]:
    """Convert circuit to dictionary representation"""
    return {
        "name": self.name,
        "num_qubits": self.num_qubits,
        "num_classical_bits": self.num_classical_bits,
        "quantum_registers": [reg.dict() for reg in self.quantum_registers],
        "classical_registers": [reg.dict() for reg in self.classical_registers],
        "gates": [gate.to_dict() for gate in self.gates],
        "measurements": self.measurements,
        "barriers": self.barriers
    }

to_json ¶

to_json(indent: int = 2) -> str

Convert circuit to JSON string

Source code in src/superquantx/circuits.py

def to_json(self, indent: int = 2) -> str:
    """Convert circuit to JSON string"""
    return json.dumps(self.to_dict(), indent=indent)

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> QuantumCircuit

Create circuit from dictionary representation

Source code in src/superquantx/circuits.py

@classmethod
def from_dict(cls, data: dict[str, Any]) -> "QuantumCircuit":
    """Create circuit from dictionary representation"""
    circuit = cls(
        num_qubits=data["num_qubits"],
        num_classical_bits=data["num_classical_bits"],
        name=data.get("name")
    )

    circuit.quantum_registers = [
        QuantumRegister(**reg) for reg in data.get("quantum_registers", [])
    ]
    circuit.classical_registers = [
        ClassicalRegister(**reg) for reg in data.get("classical_registers", [])
    ]
    circuit.gates = [QuantumGate.from_dict(gate) for gate in data.get("gates", [])]
    circuit.measurements = data.get("measurements", [])
    circuit.barriers = data.get("barriers", [])

    return circuit

from_json `classmethod` ¶

from_json(json_str: str) -> QuantumCircuit

Create circuit from JSON string

Source code in src/superquantx/circuits.py

@classmethod
def from_json(cls, json_str: str) -> "QuantumCircuit":
    """Create circuit from JSON string"""
    data = json.loads(json_str)
    return cls.from_dict(data)

draw ¶

draw(output: str = 'text') -> str

Draw the circuit in text format

Parameters:

Name	Type	Description	Default
`output`	`str`	Output format ("text" only for now)	`'text'`

Returns:

Type	Description
`str`	String representation of the circuit

Source code in src/superquantx/circuits.py

def draw(self, output: str = "text") -> str:
    """Draw the circuit in text format

    Args:
        output: Output format ("text" only for now)

    Returns:
        String representation of the circuit

    """
    if output != "text":
        raise NotImplementedError("Only text output is currently supported")

    lines = []
    for i in range(self.num_qubits):
        line = f"q{i} |0⟩─"
        lines.append(line)

    for gate in self.gates:
        max(gate.qubits)
        gate_repr = gate.name

        if len(gate.qubits) == 1:
            # Single-qubit gate
            qubit = gate.qubits[0]
            lines[qubit] += f"─{gate_repr}─"
            for i in range(self.num_qubits):
                if i != qubit:
                    lines[i] += "─" * (len(gate_repr) + 2)
        elif len(gate.qubits) == 2:
            # Two-qubit gate
            control, target = gate.qubits
            for i in range(self.num_qubits):
                if i == control:
                    lines[i] += "─●─"
                elif i == target:
                    lines[i] += "─⊕─"
                elif min(control, target) < i < max(control, target):
                    lines[i] += "─│─"
                else:
                    lines[i] += "───"

    # Add measurements
    for qubit, cbit in self.measurements:
        lines[qubit] += f"─M{cbit}"

    return "\n".join(lines)

Quantum Gate¶

superquantx.circuits.QuantumGate ¶

Bases: BaseModel

Represents a quantum gate operation

Functions¶

to_dict ¶

to_dict() -> dict[str, Any]

Convert gate to dictionary representation

Source code in src/superquantx/circuits.py

def to_dict(self) -> dict[str, Any]:
    """Convert gate to dictionary representation"""
    return {
        "name": self.name,
        "qubits": self.qubits,
        "parameters": self.parameters,
        "classical_condition": self.classical_condition
    }

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> QuantumGate

Create gate from dictionary representation

Source code in src/superquantx/circuits.py

@classmethod
def from_dict(cls, data: dict[str, Any]) -> "QuantumGate":
    """Create gate from dictionary representation"""
    return cls(**data)

Classical Register¶

superquantx.circuits.ClassicalRegister ¶

ClassicalRegister(name: str | None = None, size: int | None = None, **data: Any)

Bases: BaseModel

Represents a classical register for measurements

Source code in src/superquantx/circuits.py

def __init__(self, name: str | None = None, size: int | None = None, **data: Any) -> None:
    if name is not None:
        data["name"] = name
    if size is not None:
        data["size"] = size
    super().__init__(**data)

Quantum Gates¶

Gate Matrix Library¶

superquantx.gates.GateMatrix ¶

Quantum gate matrix representations and operations

Functions¶

rx `staticmethod` ¶

rx(theta: float) -> np.ndarray

Rotation around X-axis

Source code in src/superquantx/gates.py

@staticmethod
def rx(theta: float) -> np.ndarray:
    """Rotation around X-axis"""
    c = math.cos(theta / 2)
    s = math.sin(theta / 2)
    return np.array([[c, -1j * s], [-1j * s, c]], dtype=complex)

ry `staticmethod` ¶

ry(theta: float) -> np.ndarray

Rotation around Y-axis

Source code in src/superquantx/gates.py

@staticmethod
def ry(theta: float) -> np.ndarray:
    """Rotation around Y-axis"""
    c = math.cos(theta / 2)
    s = math.sin(theta / 2)
    return np.array([[c, -s], [s, c]], dtype=complex)

rz `staticmethod` ¶

rz(theta: float) -> np.ndarray

Rotation around Z-axis

Source code in src/superquantx/gates.py

@staticmethod
def rz(theta: float) -> np.ndarray:
    """Rotation around Z-axis"""
    return np.array([
        [np.exp(-1j * theta / 2), 0],
        [0, np.exp(1j * theta / 2)]
    ], dtype=complex)

u `staticmethod` ¶

u(theta: float, phi: float, lam: float) -> np.ndarray

General single-qubit unitary gate U(θ,φ,λ)

Source code in src/superquantx/gates.py

@staticmethod
def u(theta: float, phi: float, lam: float) -> np.ndarray:
    """General single-qubit unitary gate U(θ,φ,λ)"""
    return np.array([
        [math.cos(theta / 2), -np.exp(1j * lam) * math.sin(theta / 2)],
        [np.exp(1j * phi) * math.sin(theta / 2),
         np.exp(1j * (phi + lam)) * math.cos(theta / 2)]
    ], dtype=complex)

phase `staticmethod` ¶

phase(phi: float) -> np.ndarray

Phase gate

Source code in src/superquantx/gates.py

@staticmethod
def phase(phi: float) -> np.ndarray:
    """Phase gate"""
    return np.array([[1, 0], [0, np.exp(1j * phi)]], dtype=complex)

cnot `staticmethod` ¶

cnot() -> np.ndarray

CNOT gate matrix

Source code in src/superquantx/gates.py

@staticmethod
def cnot() -> np.ndarray:
    """CNOT gate matrix"""
    return np.array([
        [1, 0, 0, 0],
        [0, 1, 0, 0],
        [0, 0, 0, 1],
        [0, 0, 1, 0]
    ], dtype=complex)

cz `staticmethod` ¶

cz() -> np.ndarray

Controlled-Z gate matrix

Source code in src/superquantx/gates.py

@staticmethod
def cz() -> np.ndarray:
    """Controlled-Z gate matrix"""
    return np.array([
        [1, 0, 0, 0],
        [0, 1, 0, 0],
        [0, 0, 1, 0],
        [0, 0, 0, -1]
    ], dtype=complex)

swap `staticmethod` ¶

swap() -> np.ndarray

SWAP gate matrix

Source code in src/superquantx/gates.py

@staticmethod
def swap() -> np.ndarray:
    """SWAP gate matrix"""
    return np.array([
        [1, 0, 0, 0],
        [0, 0, 1, 0],
        [0, 1, 0, 0],
        [0, 0, 0, 1]
    ], dtype=complex)

iswap `staticmethod` ¶

iswap() -> np.ndarray

ISWAP gate matrix

Source code in src/superquantx/gates.py

@staticmethod
def iswap() -> np.ndarray:
    """ISWAP gate matrix"""
    return np.array([
        [1, 0, 0, 0],
        [0, 0, 1j, 0],
        [0, 1j, 0, 0],
        [0, 0, 0, 1]
    ], dtype=complex)

crx `staticmethod` ¶

crx(theta: float) -> np.ndarray

Controlled rotation around X-axis

Source code in src/superquantx/gates.py

@staticmethod
def crx(theta: float) -> np.ndarray:
    """Controlled rotation around X-axis"""
    c = math.cos(theta / 2)
    s = math.sin(theta / 2)
    return np.array([
        [1, 0, 0, 0],
        [0, 1, 0, 0],
        [0, 0, c, -1j * s],
        [0, 0, -1j * s, c]
    ], dtype=complex)

cry `staticmethod` ¶

cry(theta: float) -> np.ndarray

Controlled rotation around Y-axis

Source code in src/superquantx/gates.py

@staticmethod
def cry(theta: float) -> np.ndarray:
    """Controlled rotation around Y-axis"""
    c = math.cos(theta / 2)
    s = math.sin(theta / 2)
    return np.array([
        [1, 0, 0, 0],
        [0, 1, 0, 0],
        [0, 0, c, -s],
        [0, 0, s, c]
    ], dtype=complex)

crz `staticmethod` ¶

crz(theta: float) -> np.ndarray

Controlled rotation around Z-axis

Source code in src/superquantx/gates.py

@staticmethod
def crz(theta: float) -> np.ndarray:
    """Controlled rotation around Z-axis"""
    return np.array([
        [1, 0, 0, 0],
        [0, 1, 0, 0],
        [0, 0, np.exp(-1j * theta / 2), 0],
        [0, 0, 0, np.exp(1j * theta / 2)]
    ], dtype=complex)

xx `staticmethod` ¶

xx(theta: float) -> np.ndarray

XX interaction gate

Source code in src/superquantx/gates.py

@staticmethod
def xx(theta: float) -> np.ndarray:
    """XX interaction gate"""
    c = math.cos(theta / 2)
    s = math.sin(theta / 2)
    return np.array([
        [c, 0, 0, -1j * s],
        [0, c, -1j * s, 0],
        [0, -1j * s, c, 0],
        [-1j * s, 0, 0, c]
    ], dtype=complex)

yy `staticmethod` ¶

yy(theta: float) -> np.ndarray

YY interaction gate

Source code in src/superquantx/gates.py

@staticmethod
def yy(theta: float) -> np.ndarray:
    """YY interaction gate"""
    c = math.cos(theta / 2)
    s = math.sin(theta / 2)
    return np.array([
        [c, 0, 0, 1j * s],
        [0, c, -1j * s, 0],
        [0, -1j * s, c, 0],
        [1j * s, 0, 0, c]
    ], dtype=complex)

zz `staticmethod` ¶

zz(theta: float) -> np.ndarray

ZZ interaction gate

Source code in src/superquantx/gates.py

@staticmethod
def zz(theta: float) -> np.ndarray:
    """ZZ interaction gate"""
    return np.array([
        [np.exp(-1j * theta / 2), 0, 0, 0],
        [0, np.exp(1j * theta / 2), 0, 0],
        [0, 0, np.exp(1j * theta / 2), 0],
        [0, 0, 0, np.exp(-1j * theta / 2)]
    ], dtype=complex)

toffoli `staticmethod` ¶

toffoli() -> np.ndarray

Toffoli (CCNOT) gate matrix

Source code in src/superquantx/gates.py

@staticmethod
def toffoli() -> np.ndarray:
    """Toffoli (CCNOT) gate matrix"""
    matrix = np.eye(8, dtype=complex)
    matrix[6, 6] = 0
    matrix[7, 7] = 0
    matrix[6, 7] = 1
    matrix[7, 6] = 1
    return matrix

fredkin `staticmethod` ¶

fredkin() -> np.ndarray

Fredkin (CSWAP) gate matrix

Source code in src/superquantx/gates.py

@staticmethod
def fredkin() -> np.ndarray:
    """Fredkin (CSWAP) gate matrix"""
    matrix = np.eye(8, dtype=complex)
    matrix[5, 5] = 0
    matrix[6, 6] = 0
    matrix[5, 6] = 1
    matrix[6, 5] = 1
    return matrix

Pauli String Operations¶

superquantx.gates.PauliString ¶

PauliString(pauli_ops: str, coefficient: complex = 1.0)

Represents a Pauli string for Hamiltonian construction

Initialize Pauli string

Parameters:

Name	Type	Description	Default
`pauli_ops`	`str`	String of Pauli operators (e.g., "IXZY")	required
`coefficient`	`complex`	Complex coefficient	`1.0`

Source code in src/superquantx/gates.py

def __init__(self, pauli_ops: str, coefficient: complex = 1.0):
    """Initialize Pauli string

    Args:
        pauli_ops: String of Pauli operators (e.g., "IXZY")
        coefficient: Complex coefficient

    """
    self.pauli_ops = pauli_ops.upper()
    self.coefficient = coefficient
    self.num_qubits = len(pauli_ops)

    # Validate Pauli string
    valid_ops = set("IXYZ")
    if not all(op in valid_ops for op in self.pauli_ops):
        raise ValueError("Pauli string must contain only I, X, Y, Z operators")

Functions¶

matrix ¶

matrix() -> np.ndarray

Get the matrix representation of the Pauli string

Source code in src/superquantx/gates.py

def matrix(self) -> np.ndarray:
    """Get the matrix representation of the Pauli string"""
    matrices = {
        'I': GateMatrix.identity,
        'X': GateMatrix.X,
        'Y': GateMatrix.Y,
        'Z': GateMatrix.Z
    }

    result = np.array([[1]], dtype=complex)
    for op in self.pauli_ops:
        result = np.kron(result, matrices[op])

    return self.coefficient * result

commutes_with ¶

commutes_with(other: PauliString) -> bool

Check if this Pauli string commutes with another

Source code in src/superquantx/gates.py

def commutes_with(self, other: "PauliString") -> bool:
    """Check if this Pauli string commutes with another"""
    if len(self.pauli_ops) != len(other.pauli_ops):
        return False

    anti_commuting_pairs = {('X', 'Y'), ('Y', 'X'), ('X', 'Z'), ('Z', 'X'), ('Y', 'Z'), ('Z', 'Y')}
    anti_commutations = 0

    for op1, op2 in zip(self.pauli_ops, other.pauli_ops, strict=False):
        if (op1, op2) in anti_commuting_pairs:
            anti_commutations += 1

    return anti_commutations % 2 == 0

Hamiltonian Operations¶

superquantx.gates.Hamiltonian ¶

Hamiltonian(pauli_strings: list[PauliString])

Quantum Hamiltonian represented as sum of Pauli strings

Initialize Hamiltonian

Parameters:

Name	Type	Description	Default
`pauli_strings`	`list[PauliString]`	List of Pauli strings that sum to form the Hamiltonian	required

Source code in src/superquantx/gates.py

def __init__(self, pauli_strings: list[PauliString]):
    """Initialize Hamiltonian

    Args:
        pauli_strings: List of Pauli strings that sum to form the Hamiltonian

    """
    self.pauli_strings = pauli_strings
    if pauli_strings:
        self.num_qubits = pauli_strings[0].num_qubits
        # Validate all strings have same length
        if not all(p.num_qubits == self.num_qubits for p in pauli_strings):
            raise ValueError("All Pauli strings must have same length")
    else:
        self.num_qubits = 0

Functions¶

matrix ¶

matrix() -> np.ndarray

Get matrix representation of the Hamiltonian

Source code in src/superquantx/gates.py

def matrix(self) -> np.ndarray:
    """Get matrix representation of the Hamiltonian"""
    if not self.pauli_strings:
        return np.zeros((1, 1), dtype=complex)

    dim = 2 ** self.num_qubits
    result = np.zeros((dim, dim), dtype=complex)

    for pauli_string in self.pauli_strings:
        result += pauli_string.matrix()

    return result

expectation_value ¶

expectation_value(state: ndarray) -> complex

Calculate expectation value ⟨ψ|H|ψ⟩

Source code in src/superquantx/gates.py

def expectation_value(self, state: np.ndarray) -> complex:
    """Calculate expectation value ⟨ψ|H|ψ⟩"""
    H = self.matrix()
    return np.conj(state).T @ H @ state

ground_state_energy ¶

ground_state_energy() -> float

Calculate ground state energy (lowest eigenvalue)

Source code in src/superquantx/gates.py

def ground_state_energy(self) -> float:
    """Calculate ground state energy (lowest eigenvalue)"""
    eigenvals = np.linalg.eigvals(self.matrix())
    return float(np.min(np.real(eigenvals)))

time_evolution ¶

time_evolution(time: float) -> np.ndarray

Generate time evolution operator U(t) = exp(-iHt)

Source code in src/superquantx/gates.py

def time_evolution(self, time: float) -> np.ndarray:
    """Generate time evolution operator U(t) = exp(-iHt)"""
    H = self.matrix()
    return expm(-1j * H * time)

from_dict `classmethod` ¶

from_dict(hamiltonian_dict: dict[str, complex]) -> Hamiltonian

Create Hamiltonian from dictionary

Parameters:

Name	Type	Description	Default
`hamiltonian_dict`	`dict[str, complex]`	Dictionary mapping Pauli strings to coefficients	required

Example

{"IXZI": 0.5, "YZII": -0.3, "ZXYX": 1.2j}

Source code in src/superquantx/gates.py

@classmethod
def from_dict(cls, hamiltonian_dict: dict[str, complex]) -> "Hamiltonian":
    """Create Hamiltonian from dictionary

    Args:
        hamiltonian_dict: Dictionary mapping Pauli strings to coefficients

    Example:
        {"IXZI": 0.5, "YZII": -0.3, "ZXYX": 1.2j}

    """
    pauli_strings = []
    for pauli_ops, coeff in hamiltonian_dict.items():
        pauli_strings.append(PauliString(pauli_ops, coeff))
    return cls(pauli_strings)

heisenberg_model `staticmethod` ¶

heisenberg_model(num_qubits: int, Jx: float = 1.0, Jy: float = 1.0, Jz: float = 1.0, periodic: bool = False) -> Hamiltonian

Create Heisenberg model Hamiltonian

H = Σᵢ (Jₓ XᵢXᵢ₊₁ + Jᵧ YᵢYᵢ₊₁ + Jᵤ ZᵢZᵢ₊₁)

Source code in src/superquantx/gates.py

@staticmethod
def heisenberg_model(
    num_qubits: int,
    Jx: float = 1.0,
    Jy: float = 1.0,
    Jz: float = 1.0,
    periodic: bool = False
) -> "Hamiltonian":
    """Create Heisenberg model Hamiltonian

    H = Σᵢ (Jₓ XᵢXᵢ₊₁ + Jᵧ YᵢYᵢ₊₁ + Jᵤ ZᵢZᵢ₊₁)
    """
    pauli_strings = []

    max_i = num_qubits if periodic else num_qubits - 1

    for i in range(max_i):
        j = (i + 1) % num_qubits

        # XX term
        xx_ops = ['I'] * num_qubits
        xx_ops[i] = 'X'
        xx_ops[j] = 'X'
        pauli_strings.append(PauliString(''.join(xx_ops), Jx))

        # YY term
        yy_ops = ['I'] * num_qubits
        yy_ops[i] = 'Y'
        yy_ops[j] = 'Y'
        pauli_strings.append(PauliString(''.join(yy_ops), Jy))

        # ZZ term
        zz_ops = ['I'] * num_qubits
        zz_ops[i] = 'Z'
        zz_ops[j] = 'Z'
        pauli_strings.append(PauliString(''.join(zz_ops), Jz))

    return Hamiltonian(pauli_strings)

ising_model `staticmethod` ¶

ising_model(num_qubits: int, J: float = 1.0, h: float = 0.0, periodic: bool = False) -> Hamiltonian

Create transverse field Ising model Hamiltonian

H = -J Σᵢ ZᵢZᵢ₊₁ - h Σᵢ Xᵢ

Source code in src/superquantx/gates.py

@staticmethod
def ising_model(
    num_qubits: int,
    J: float = 1.0,
    h: float = 0.0,
    periodic: bool = False
) -> "Hamiltonian":
    """Create transverse field Ising model Hamiltonian

    H = -J Σᵢ ZᵢZᵢ₊₁ - h Σᵢ Xᵢ
    """
    pauli_strings = []

    # ZZ interactions
    max_i = num_qubits if periodic else num_qubits - 1
    for i in range(max_i):
        j = (i + 1) % num_qubits
        zz_ops = ['I'] * num_qubits
        zz_ops[i] = 'Z'
        zz_ops[j] = 'Z'
        pauli_strings.append(PauliString(''.join(zz_ops), -J))

    # X fields
    for i in range(num_qubits):
        x_ops = ['I'] * num_qubits
        x_ops[i] = 'X'
        pauli_strings.append(PauliString(''.join(x_ops), -h))

    return Hamiltonian(pauli_strings)

Measurements¶

Measurement Result¶

superquantx.measurements.MeasurementResult ¶

Bases: BaseModel

Represents the result of quantum measurements

Attributes¶

probabilities `property` ¶

probabilities: dict[str, float]

Get measurement probabilities

most_frequent `property` ¶

most_frequent: tuple[str, int]

Get most frequent measurement outcome

Functions¶

model_post_init ¶

model_post_init(__context)

Validate measurement result

Source code in src/superquantx/measurements.py

def model_post_init(self, __context):
    """Validate measurement result"""
    if sum(self.counts.values()) != self.shots:
        raise ValueError("Sum of counts must equal total shots")

marginal_counts ¶

marginal_counts(qubits: list[int]) -> dict[str, int]

Get marginal counts for specific qubits

Parameters:

Name	Type	Description	Default
`qubits`	`list[int]`	List of qubit indices to marginalize over	required

Returns:

Type	Description
`dict[str, int]`	Marginal counts dictionary

Source code in src/superquantx/measurements.py

def marginal_counts(self, qubits: list[int]) -> dict[str, int]:
    """Get marginal counts for specific qubits

    Args:
        qubits: List of qubit indices to marginalize over

    Returns:
        Marginal counts dictionary

    """
    marginal = defaultdict(int)

    for outcome, count in self.counts.items():
        # Extract bits for specified qubits (reverse order due to endianness)
        marginal_outcome = ''.join(outcome[-(i+1)] for i in qubits)
        marginal[marginal_outcome] += count

    return dict(marginal)

expectation_value ¶

expectation_value(observable: str) -> float

Calculate expectation value for Pauli observable

Parameters:

Name	Type	Description	Default
`observable`	`str`	Pauli string (e.g., "ZZI")	required

Returns:

Type	Description
`float`	Expectation value

Source code in src/superquantx/measurements.py

def expectation_value(self, observable: str) -> float:
    """Calculate expectation value for Pauli observable

    Args:
        observable: Pauli string (e.g., "ZZI")

    Returns:
        Expectation value

    """
    if len(observable) == 0:
        return 1.0

    expectation = 0.0

    for outcome, count in self.counts.items():
        # Calculate parity for non-identity Pauli operators
        parity = 1
        for i, pauli_op in enumerate(observable):
            if pauli_op == 'Z' and i < len(outcome):
                bit = int(outcome[-(i+1)])  # Reverse order
                parity *= (-1) ** bit
            elif pauli_op in ['X', 'Y']:
                # X and Y measurements require basis rotation
                raise ValueError(f"Cannot compute expectation for {pauli_op} from Z-basis measurements")

        expectation += parity * count / self.shots

    return expectation

entropy ¶

entropy() -> float

Calculate measurement entropy

Source code in src/superquantx/measurements.py

def entropy(self) -> float:
    """Calculate measurement entropy"""
    entropy = 0.0
    for prob in self.probabilities.values():
        if prob > 0:
            entropy -= prob * np.log2(prob)
    return entropy

plot_histogram ¶

plot_histogram(title: str = 'Measurement Results', figsize: tuple[int, int] = (10, 6), max_outcomes: int = 20) -> plt.Figure

Plot measurement histogram

Parameters:

Name	Type	Description	Default
`title`	`str`	Plot title	`'Measurement Results'`
`figsize`	`tuple[int, int]`	Figure size	`(10, 6)`
`max_outcomes`	`int`	Maximum number of outcomes to show	`20`

Returns:

Type	Description
`Figure`	Matplotlib figure

Source code in src/superquantx/measurements.py

def plot_histogram(
    self,
    title: str = "Measurement Results",
    figsize: tuple[int, int] = (10, 6),
    max_outcomes: int = 20
) -> plt.Figure:
    """Plot measurement histogram

    Args:
        title: Plot title
        figsize: Figure size
        max_outcomes: Maximum number of outcomes to show

    Returns:
        Matplotlib figure

    """
    fig, ax = plt.subplots(figsize=figsize)

    # Sort outcomes by count (descending)
    sorted_outcomes = sorted(self.counts.items(), key=lambda x: x[1], reverse=True)

    # Take top outcomes
    if len(sorted_outcomes) > max_outcomes:
        sorted_outcomes = sorted_outcomes[:max_outcomes]

    outcomes, counts = zip(*sorted_outcomes, strict=False) if sorted_outcomes else ([], [])

    ax.bar(range(len(outcomes)), counts)
    ax.set_xlabel('Measurement Outcome')
    ax.set_ylabel('Count')
    ax.set_title(title)
    ax.set_xticks(range(len(outcomes)))
    ax.set_xticklabels(outcomes, rotation=45, ha='right')

    plt.tight_layout()
    return fig

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary

Source code in src/superquantx/measurements.py

def to_dict(self) -> dict[str, Any]:
    """Convert to dictionary"""
    return {
        "counts": self.counts,
        "shots": self.shots,
        "memory": self.memory,
        "metadata": self.metadata
    }

to_json ¶

to_json(indent: int = 2) -> str

Convert to JSON string

Source code in src/superquantx/measurements.py

def to_json(self, indent: int = 2) -> str:
    """Convert to JSON string"""
    return json.dumps(self.to_dict(), indent=indent)

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> MeasurementResult

Create from dictionary

Source code in src/superquantx/measurements.py

@classmethod
def from_dict(cls, data: dict[str, Any]) -> "MeasurementResult":
    """Create from dictionary"""
    return cls(**data)

from_json `classmethod` ¶

from_json(json_str: str) -> MeasurementResult

Create from JSON string

Source code in src/superquantx/measurements.py

@classmethod
def from_json(cls, json_str: str) -> "MeasurementResult":
    """Create from JSON string"""
    data = json.loads(json_str)
    return cls.from_dict(data)

Quantum Measurement¶

superquantx.measurements.QuantumMeasurement ¶

QuantumMeasurement(backend: str | None = 'simulator')

Quantum measurement operations and analysis

Initialize measurement system

Parameters:

Name	Type	Description	Default
`backend`	`str \| None`	Quantum backend for measurements	`'simulator'`

Source code in src/superquantx/measurements.py

def __init__(self, backend: str | None = "simulator"):
    """Initialize measurement system

    Args:
        backend: Quantum backend for measurements

    """
    self.backend = backend
    self.measurement_history: list[MeasurementResult] = []

Functions¶

measure_circuit ¶

measure_circuit(circuit: QuantumCircuit, shots: int = 1024, memory: bool = False) -> MeasurementResult

Measure quantum circuit

Parameters:

Name	Type	Description	Default
`circuit`	`QuantumCircuit`	Quantum circuit to measure	required
`shots`	`int`	Number of measurement shots	`1024`
`memory`	`bool`	Whether to store individual shot outcomes	`False`

Returns:

Type	Description
`MeasurementResult`	Measurement result

Source code in src/superquantx/measurements.py

def measure_circuit(
    self,
    circuit: "QuantumCircuit",
    shots: int = 1024,
    memory: bool = False
) -> MeasurementResult:
    """Measure quantum circuit

    Args:
        circuit: Quantum circuit to measure
        shots: Number of measurement shots
        memory: Whether to store individual shot outcomes

    Returns:
        Measurement result

    """
    # This would interface with actual quantum hardware/simulator
    # For now, create simulated results


    # Simulate measurement outcomes
    if self.backend == "simulator":
        counts = self._simulate_measurements(circuit, shots)
    else:
        counts = self._execute_measurements(circuit, shots)

    # Generate memory if requested
    shot_memory = None
    if memory:
        shot_memory = []
        for outcome, count in counts.items():
            shot_memory.extend([outcome] * count)
        np.random.shuffle(shot_memory)  # Randomize order

    result = MeasurementResult(
        counts=counts,
        shots=shots,
        memory=shot_memory,
        metadata={"backend": self.backend, "circuit_name": circuit.name}
    )

    self.measurement_history.append(result)
    return result

measure_observable ¶

measure_observable(circuit: QuantumCircuit, observable: str, shots: int = 1024) -> float

Measure expectation value of Pauli observable

Parameters:

Name	Type	Description	Default
`circuit`	`QuantumCircuit`	Quantum circuit (without measurements)	required
`observable`	`str`	Pauli string observable	required
`shots`	`int`	Number of shots	`1024`

Returns:

Type	Description
`float`	Expectation value

Source code in src/superquantx/measurements.py

def measure_observable(
    self,
    circuit: "QuantumCircuit",
    observable: str,
    shots: int = 1024
) -> float:
    """Measure expectation value of Pauli observable

    Args:
        circuit: Quantum circuit (without measurements)
        observable: Pauli string observable
        shots: Number of shots

    Returns:
        Expectation value

    """
    # Create measurement circuit with basis rotations
    measurement_circuit = self._prepare_observable_measurement(circuit, observable)

    # Measure circuit
    result = self.measure_circuit(measurement_circuit, shots)

    # Calculate expectation value
    return result.expectation_value('Z' * len(observable))

tomography_measurements ¶

tomography_measurements(circuit: QuantumCircuit, qubits: list[int] | None = None, shots_per_measurement: int = 1024) -> dict[str, MeasurementResult]

Perform quantum state tomography measurements

Parameters:

Name	Type	Description	Default
`circuit`	`QuantumCircuit`	Quantum circuit to tomographically reconstruct	required
`qubits`	`list[int] \| None`	Qubits to perform tomography on (default: all)	`None`
`shots_per_measurement`	`int`	Shots per Pauli measurement	`1024`

Returns:

Type	Description
`dict[str, MeasurementResult]`	Dictionary of measurement results for each Pauli basis

Source code in src/superquantx/measurements.py

def tomography_measurements(
    self,
    circuit: "QuantumCircuit",
    qubits: list[int] | None = None,
    shots_per_measurement: int = 1024
) -> dict[str, MeasurementResult]:
    """Perform quantum state tomography measurements

    Args:
        circuit: Quantum circuit to tomographically reconstruct
        qubits: Qubits to perform tomography on (default: all)
        shots_per_measurement: Shots per Pauli measurement

    Returns:
        Dictionary of measurement results for each Pauli basis

    """
    if qubits is None:
        qubits = list(range(circuit.num_qubits))

    num_qubits = len(qubits)
    pauli_bases = ['I', 'X', 'Y', 'Z']

    # Generate all Pauli measurement settings
    measurements = {}

    def generate_pauli_strings(n):
        if n == 0:
            yield ''
        else:
            for base in pauli_bases:
                for rest in generate_pauli_strings(n - 1):
                    yield base + rest

    for pauli_string in generate_pauli_strings(num_qubits):
        if 'I' in pauli_string:
            continue  # Skip identity measurements

        measurement_circuit = self._prepare_tomography_measurement(
            circuit, pauli_string, qubits
        )

        result = self.measure_circuit(measurement_circuit, shots_per_measurement)
        measurements[pauli_string] = result

    return measurements

reconstruct_state ¶

reconstruct_state(tomography_results: dict[str, MeasurementResult]) -> np.ndarray

Reconstruct quantum state from tomography measurements

Parameters:

Name	Type	Description	Default
`tomography_results`	`dict[str, MeasurementResult]`	Results from tomography_measurements	required

Returns:

Type	Description
`ndarray`	Reconstructed density matrix

Source code in src/superquantx/measurements.py

def reconstruct_state(
    self,
    tomography_results: dict[str, MeasurementResult]
) -> np.ndarray:
    """Reconstruct quantum state from tomography measurements

    Args:
        tomography_results: Results from tomography_measurements

    Returns:
        Reconstructed density matrix

    """
    # This is a simplified implementation
    # Full tomography would use maximum likelihood estimation

    num_qubits = len(next(iter(tomography_results.keys())))
    dim = 2 ** num_qubits

    # Initialize density matrix
    rho = np.eye(dim, dtype=complex) / dim

    # This is a placeholder implementation
    # Real tomography would involve solving a constrained optimization problem

    return rho

fidelity ¶

fidelity(state1: ndarray, state2: ndarray) -> float

Calculate quantum state fidelity

Parameters:

Name	Type	Description	Default
`state1`	`ndarray`	First quantum state (vector or density matrix)	required
`state2`	`ndarray`	Second quantum state (vector or density matrix)	required

Returns:

Type	Description
`float`	Fidelity between states

Source code in src/superquantx/measurements.py

def fidelity(
    self,
    state1: np.ndarray,
    state2: np.ndarray
) -> float:
    """Calculate quantum state fidelity

    Args:
        state1: First quantum state (vector or density matrix)
        state2: Second quantum state (vector or density matrix)

    Returns:
        Fidelity between states

    """
    # Convert to density matrices if needed
    if state1.ndim == 1:
        rho1 = np.outer(state1, np.conj(state1))
    else:
        rho1 = state1

    if state2.ndim == 1:
        rho2 = np.outer(state2, np.conj(state2))
    else:
        rho2 = state2

    # Calculate fidelity using proper matrix square root
    eigenvals_rho1, eigenvecs_rho1 = np.linalg.eigh(rho1)
    eigenvals_rho1 = np.maximum(eigenvals_rho1, 0)  # Ensure non-negative
    sqrt_rho1 = eigenvecs_rho1 @ np.diag(np.sqrt(eigenvals_rho1)) @ eigenvecs_rho1.conj().T

    product = sqrt_rho1 @ rho2 @ sqrt_rho1
    eigenvals = np.linalg.eigvals(product)
    eigenvals = np.maximum(eigenvals.real, 0)  # Take real part and ensure non-negative

    return float(np.sum(np.sqrt(eigenvals)))

trace_distance ¶

trace_distance(state1: ndarray, state2: ndarray) -> float

Calculate trace distance between quantum states

Parameters:

Name	Type	Description	Default
`state1`	`ndarray`	First quantum state	required
`state2`	`ndarray`	Second quantum state	required

Returns:

Type	Description
`float`	Trace distance

Source code in src/superquantx/measurements.py

def trace_distance(
    self,
    state1: np.ndarray,
    state2: np.ndarray
) -> float:
    """Calculate trace distance between quantum states

    Args:
        state1: First quantum state
        state2: Second quantum state

    Returns:
        Trace distance

    """
    # Convert to density matrices if needed
    if state1.ndim == 1:
        rho1 = np.outer(state1, np.conj(state1))
    else:
        rho1 = state1

    if state2.ndim == 1:
        rho2 = np.outer(state2, np.conj(state2))
    else:
        rho2 = state2

    diff = rho1 - rho2
    eigenvals = np.linalg.eigvals(diff)

    return 0.5 * np.sum(np.abs(eigenvals))

quantum_volume ¶

quantum_volume(num_qubits: int, depth: int, trials: int = 100, shots_per_trial: int = 1024) -> dict[str, Any]

Perform quantum volume benchmark

Parameters:

Name	Type	Description	Default
`num_qubits`	`int`	Number of qubits	required
`depth`	`int`	Circuit depth	required
`trials`	`int`	Number of random circuits to test	`100`
`shots_per_trial`	`int`	Shots per circuit	`1024`

Returns:

Type	Description
`dict[str, Any]`	Quantum volume benchmark results

Source code in src/superquantx/measurements.py

def quantum_volume(
    self,
    num_qubits: int,
    depth: int,
    trials: int = 100,
    shots_per_trial: int = 1024
) -> dict[str, Any]:
    """Perform quantum volume benchmark

    Args:
        num_qubits: Number of qubits
        depth: Circuit depth
        trials: Number of random circuits to test
        shots_per_trial: Shots per circuit

    Returns:
        Quantum volume benchmark results

    """
    import random

    from .circuits import QuantumCircuit

    successes = 0

    for trial in range(trials):
        # Generate random quantum volume circuit
        circuit = QuantumCircuit(num_qubits)

        for layer in range(depth):
            # Random SU(4) gates on random qubit pairs
            available_qubits = list(range(num_qubits))
            random.shuffle(available_qubits)

            for i in range(0, num_qubits - 1, 2):
                q1, q2 = available_qubits[i], available_qubits[i + 1]

                # Random single-qubit gates
                circuit.u(
                    random.uniform(0, 2*np.pi),
                    random.uniform(0, 2*np.pi),
                    random.uniform(0, 2*np.pi),
                    q1
                )
                circuit.u(
                    random.uniform(0, 2*np.pi),
                    random.uniform(0, 2*np.pi),
                    random.uniform(0, 2*np.pi),
                    q2
                )

                # CNOT gate
                circuit.cnot(q1, q2)

        # Measure circuit
        circuit.measure_all()
        result = self.measure_circuit(circuit, shots_per_trial)

        # Check if heavy output (simplified check)
        # Real quantum volume would compute ideal probabilities
        most_frequent = result.most_frequent
        if most_frequent[1] > shots_per_trial // 4:  # Simplified threshold
            successes += 1

    success_rate = successes / trials

    return {
        "num_qubits": num_qubits,
        "depth": depth,
        "trials": trials,
        "successes": successes,
        "success_rate": success_rate,
        "passed": success_rate > 2/3,  # Standard QV threshold
        "quantum_volume": 2 ** num_qubits if success_rate > 2/3 else 0
    }

Result Analyzer¶

superquantx.measurements.ResultAnalyzer ¶

Advanced analysis of quantum measurement results

Functions¶

compare_results `staticmethod` ¶

compare_results(results1: MeasurementResult, results2: MeasurementResult) -> dict[str, float]

Compare two measurement results

Parameters:

Name	Type	Description	Default
`results1`	`MeasurementResult`	First measurement result	required
`results2`	`MeasurementResult`	Second measurement result	required

Returns:

Type	Description
`dict[str, float]`	Comparison metrics

Source code in src/superquantx/measurements.py

@staticmethod
def compare_results(
    results1: MeasurementResult,
    results2: MeasurementResult
) -> dict[str, float]:
    """Compare two measurement results

    Args:
        results1: First measurement result
        results2: Second measurement result

    Returns:
        Comparison metrics

    """
    # Hellinger distance between probability distributions
    prob1 = results1.probabilities
    prob2 = results2.probabilities

    all_outcomes = set(prob1.keys()) | set(prob2.keys())

    hellinger = 0.0
    kl_divergence = 0.0

    for outcome in all_outcomes:
        p1 = prob1.get(outcome, 0)
        p2 = prob2.get(outcome, 0)

        # Hellinger distance
        hellinger += (np.sqrt(p1) - np.sqrt(p2)) ** 2

        # KL divergence (with smoothing to avoid log(0))
        p1_smooth = p1 + 1e-10
        p2_smooth = p2 + 1e-10
        kl_divergence += p1_smooth * np.log(p1_smooth / p2_smooth)

    hellinger = np.sqrt(hellinger / 2)

    # Total variation distance
    tv_distance = 0.5 * sum(abs(prob1.get(outcome, 0) - prob2.get(outcome, 0))
                          for outcome in all_outcomes)

    return {
        "hellinger_distance": hellinger,
        "kl_divergence": kl_divergence,
        "total_variation_distance": tv_distance
    }

error_mitigation_zero_noise_extrapolation `staticmethod` ¶

error_mitigation_zero_noise_extrapolation(noise_levels: list[float], measurement_results: list[MeasurementResult], observable: str = 'Z') -> tuple[float, dict[str, Any]]

Perform zero-noise extrapolation error mitigation

Parameters:

Name	Type	Description	Default
`noise_levels`	`list[float]`	List of noise levels (e.g., [1, 2, 3])	required
`measurement_results`	`list[MeasurementResult]`	Results for each noise level	required
`observable`	`str`	Observable to extrapolate	`'Z'`

Returns:

Type	Description
`tuple[float, dict[str, Any]]`	Zero-noise extrapolated value and fitting info

Source code in src/superquantx/measurements.py

@staticmethod
def error_mitigation_zero_noise_extrapolation(
    noise_levels: list[float],
    measurement_results: list[MeasurementResult],
    observable: str = "Z"
) -> tuple[float, dict[str, Any]]:
    """Perform zero-noise extrapolation error mitigation

    Args:
        noise_levels: List of noise levels (e.g., [1, 2, 3])
        measurement_results: Results for each noise level
        observable: Observable to extrapolate

    Returns:
        Zero-noise extrapolated value and fitting info

    """
    if len(noise_levels) != len(measurement_results):
        raise ValueError("Noise levels and results must have same length")

    # Extract expectation values
    expectation_values = []
    for result in measurement_results:
        exp_val = result.expectation_value(observable)
        expectation_values.append(exp_val)

    # Fit exponential decay model: f(x) = a * exp(-b * x) + c
    from scipy.optimize import curve_fit

    def exponential_model(x, a, b, c):
        return a * np.exp(-b * x) + c

    try:
        popt, pcov = curve_fit(
            exponential_model,
            noise_levels,
            expectation_values,
            p0=[expectation_values[0], 0.1, 0]
        )

        # Extrapolate to zero noise
        zero_noise_value = exponential_model(0, *popt)

        # Calculate fit quality
        fitted_values = [exponential_model(x, *popt) for x in noise_levels]
        r_squared = 1 - np.sum((np.array(expectation_values) - fitted_values)**2) / \
                       np.sum((np.array(expectation_values) - np.mean(expectation_values))**2)

        return zero_noise_value, {
            "fit_parameters": popt,
            "fit_covariance": pcov,
            "r_squared": r_squared,
            "fitted_values": fitted_values,
            "raw_values": expectation_values
        }

    except Exception as e:
        # Fallback to linear extrapolation
        coeffs = np.polyfit(noise_levels, expectation_values, 1)
        zero_noise_value = coeffs[1]  # y-intercept

        return zero_noise_value, {
            "method": "linear_fallback",
            "coefficients": coeffs,
            "error": str(e)
        }

readout_error_mitigation `staticmethod` ¶

readout_error_mitigation(calibration_results: dict[str, MeasurementResult], measurement_result: MeasurementResult) -> MeasurementResult

Apply readout error mitigation

Parameters:

Name	Type	Description	Default
`calibration_results`	`dict[str, MeasurementResult]`	Results from measuring \|0⟩ and \|1⟩ states	required
`measurement_result`	`MeasurementResult`	Result to correct	required

Returns:

Type	Description
`MeasurementResult`	Error-mitigated result

Source code in src/superquantx/measurements.py

@staticmethod
def readout_error_mitigation(
    calibration_results: dict[str, MeasurementResult],
    measurement_result: MeasurementResult
) -> MeasurementResult:
    """Apply readout error mitigation

    Args:
        calibration_results: Results from measuring |0⟩ and |1⟩ states
        measurement_result: Result to correct

    Returns:
        Error-mitigated result

    """
    # Build calibration matrix
    len(next(iter(calibration_results.keys())))

    # This is a simplified implementation
    # Full readout error mitigation would build complete confusion matrix

    corrected_counts = dict(measurement_result.counts)

    # Apply simple correction (placeholder)
    # Real implementation would invert the calibration matrix

    return MeasurementResult(
        counts=corrected_counts,
        shots=measurement_result.shots,
        memory=measurement_result.memory,
        metadata={**measurement_result.metadata, "error_mitigated": True}
    )

Noise Models¶

Noise Channel Base¶

superquantx.noise.NoiseChannel ¶

NoiseChannel(probability: float)

Bases: ABC

Abstract base class for quantum noise channels

Initialize noise channel

Parameters:

Name	Type	Description	Default
`probability`	`float`	Noise probability (0 <= p <= 1)	required

Source code in src/superquantx/noise.py

def __init__(self, probability: float):
    """Initialize noise channel

    Args:
        probability: Noise probability (0 <= p <= 1)

    """
    if not 0 <= probability <= 1:
        raise ValueError("Probability must be between 0 and 1")
    self.probability = probability

Functions¶

kraus_operators `abstractmethod` ¶

kraus_operators() -> list[np.ndarray]

Return Kraus operators for the noise channel

Source code in src/superquantx/noise.py

@abstractmethod
def kraus_operators(self) -> list[np.ndarray]:
    """Return Kraus operators for the noise channel"""
    pass

apply_to_density_matrix `abstractmethod` ¶

apply_to_density_matrix(rho: ndarray) -> np.ndarray

Apply noise channel to density matrix

Source code in src/superquantx/noise.py

@abstractmethod
def apply_to_density_matrix(self, rho: np.ndarray) -> np.ndarray:
    """Apply noise channel to density matrix"""
    pass

is_unital ¶

is_unital() -> bool

Check if channel is unital (maps identity to identity)

Source code in src/superquantx/noise.py

def is_unital(self) -> bool:
    """Check if channel is unital (maps identity to identity)"""
    identity = np.eye(2, dtype=complex)
    noisy_identity = self.apply_to_density_matrix(identity)
    return np.allclose(noisy_identity, identity)

Specific Noise Channels¶

superquantx.noise.BitFlipChannel ¶

BitFlipChannel(probability: float)

Bases: NoiseChannel

Bit flip (X) noise channel

Source code in src/superquantx/noise.py

def __init__(self, probability: float):
    """Initialize noise channel

    Args:
        probability: Noise probability (0 <= p <= 1)

    """
    if not 0 <= probability <= 1:
        raise ValueError("Probability must be between 0 and 1")
    self.probability = probability

Functions¶

kraus_operators ¶

kraus_operators() -> list[np.ndarray]

Kraus operators for bit flip channel

Source code in src/superquantx/noise.py

def kraus_operators(self) -> list[np.ndarray]:
    """Kraus operators for bit flip channel"""
    sqrt_p = np.sqrt(self.probability)
    sqrt_1_p = np.sqrt(1 - self.probability)

    return [
        sqrt_1_p * GateMatrix.I,  # No error
        sqrt_p * GateMatrix.X     # Bit flip
    ]

apply_to_density_matrix ¶

apply_to_density_matrix(rho: ndarray) -> np.ndarray

Apply bit flip noise to density matrix

Source code in src/superquantx/noise.py

def apply_to_density_matrix(self, rho: np.ndarray) -> np.ndarray:
    """Apply bit flip noise to density matrix"""
    kraus_ops = self.kraus_operators()
    result = np.zeros_like(rho, dtype=complex)

    for kraus in kraus_ops:
        result += kraus @ rho @ kraus.conj().T

    return result

superquantx.noise.PhaseFlipChannel ¶

PhaseFlipChannel(probability: float)

Bases: NoiseChannel

Phase flip (Z) noise channel

Source code in src/superquantx/noise.py

def __init__(self, probability: float):
    """Initialize noise channel

    Args:
        probability: Noise probability (0 <= p <= 1)

    """
    if not 0 <= probability <= 1:
        raise ValueError("Probability must be between 0 and 1")
    self.probability = probability

Functions¶

kraus_operators ¶

kraus_operators() -> list[np.ndarray]

Kraus operators for phase flip channel

Source code in src/superquantx/noise.py

def kraus_operators(self) -> list[np.ndarray]:
    """Kraus operators for phase flip channel"""
    sqrt_p = np.sqrt(self.probability)
    sqrt_1_p = np.sqrt(1 - self.probability)

    return [
        sqrt_1_p * GateMatrix.I,  # No error
        sqrt_p * GateMatrix.Z     # Phase flip
    ]

apply_to_density_matrix ¶

apply_to_density_matrix(rho: ndarray) -> np.ndarray

Apply phase flip noise to density matrix

Source code in src/superquantx/noise.py

def apply_to_density_matrix(self, rho: np.ndarray) -> np.ndarray:
    """Apply phase flip noise to density matrix"""
    kraus_ops = self.kraus_operators()
    result = np.zeros_like(rho, dtype=complex)

    for kraus in kraus_ops:
        result += kraus @ rho @ kraus.conj().T

    return result

superquantx.noise.DepolarizingChannel ¶

DepolarizingChannel(probability: float)

Bases: NoiseChannel

Depolarizing noise channel

Source code in src/superquantx/noise.py

def __init__(self, probability: float):
    """Initialize noise channel

    Args:
        probability: Noise probability (0 <= p <= 1)

    """
    if not 0 <= probability <= 1:
        raise ValueError("Probability must be between 0 and 1")
    self.probability = probability

Functions¶

kraus_operators ¶

kraus_operators() -> list[np.ndarray]

Kraus operators for depolarizing channel

Source code in src/superquantx/noise.py

def kraus_operators(self) -> list[np.ndarray]:
    """Kraus operators for depolarizing channel"""
    p = self.probability

    return [
        np.sqrt(1 - 3*p/4) * GateMatrix.I,  # No error
        np.sqrt(p/4) * GateMatrix.X,        # X error
        np.sqrt(p/4) * GateMatrix.Y,        # Y error
        np.sqrt(p/4) * GateMatrix.Z         # Z error
    ]

apply_to_density_matrix ¶

apply_to_density_matrix(rho: ndarray) -> np.ndarray

Apply depolarizing noise to density matrix

Source code in src/superquantx/noise.py

def apply_to_density_matrix(self, rho: np.ndarray) -> np.ndarray:
    """Apply depolarizing noise to density matrix"""
    p = self.probability

    # Direct formula: ρ → (1-p)ρ + p*I/2
    identity = np.eye(rho.shape[0], dtype=complex)
    return (1 - p) * rho + (p / rho.shape[0]) * identity

superquantx.noise.AmplitudeDampingChannel ¶

AmplitudeDampingChannel(probability: float)

Bases: NoiseChannel

Amplitude damping noise channel (T1 decay)

Source code in src/superquantx/noise.py

def __init__(self, probability: float):
    """Initialize noise channel

    Args:
        probability: Noise probability (0 <= p <= 1)

    """
    if not 0 <= probability <= 1:
        raise ValueError("Probability must be between 0 and 1")
    self.probability = probability

Functions¶

kraus_operators ¶

kraus_operators() -> list[np.ndarray]

Kraus operators for amplitude damping channel

Source code in src/superquantx/noise.py

def kraus_operators(self) -> list[np.ndarray]:
    """Kraus operators for amplitude damping channel"""
    gamma = self.probability

    E0 = np.array([
        [1, 0],
        [0, np.sqrt(1 - gamma)]
    ], dtype=complex)

    E1 = np.array([
        [0, np.sqrt(gamma)],
        [0, 0]
    ], dtype=complex)

    return [E0, E1]

apply_to_density_matrix ¶

apply_to_density_matrix(rho: ndarray) -> np.ndarray

Apply amplitude damping noise to density matrix

Source code in src/superquantx/noise.py

def apply_to_density_matrix(self, rho: np.ndarray) -> np.ndarray:
    """Apply amplitude damping noise to density matrix"""
    kraus_ops = self.kraus_operators()
    result = np.zeros_like(rho, dtype=complex)

    for kraus in kraus_ops:
        result += kraus @ rho @ kraus.conj().T

    return result

Noise Model¶

superquantx.noise.NoiseModel ¶

Bases: BaseModel

Comprehensive noise model for quantum circuits

Functions¶

add_single_qubit_error ¶

add_single_qubit_error(gate_name: str, error_rate: float) -> None

Add single-qubit gate error rate

Source code in src/superquantx/noise.py

def add_single_qubit_error(self, gate_name: str, error_rate: float) -> None:
    """Add single-qubit gate error rate"""
    self.single_qubit_error_rates[gate_name] = error_rate

add_two_qubit_error ¶

add_two_qubit_error(gate_name: str, error_rate: float) -> None

Add two-qubit gate error rate

Source code in src/superquantx/noise.py

def add_two_qubit_error(self, gate_name: str, error_rate: float) -> None:
    """Add two-qubit gate error rate"""
    self.two_qubit_error_rates[gate_name] = error_rate

add_readout_error ¶

add_readout_error(qubit: int, error_rate: float) -> None

Add readout error rate for qubit

Source code in src/superquantx/noise.py

def add_readout_error(self, qubit: int, error_rate: float) -> None:
    """Add readout error rate for qubit"""
    self.readout_error_rates[qubit] = error_rate

set_coherence_time ¶

set_coherence_time(qubit: int, t1: float, t2: float) -> None

Set T1 and T2 coherence times for qubit

Source code in src/superquantx/noise.py

def set_coherence_time(self, qubit: int, t1: float, t2: float) -> None:
    """Set T1 and T2 coherence times for qubit"""
    if "T1" not in self.coherence_times:
        self.coherence_times["T1"] = {}
    if "T2" not in self.coherence_times:
        self.coherence_times["T2"] = {}

    self.coherence_times["T1"][qubit] = t1
    self.coherence_times["T2"][qubit] = t2

apply_to_circuit ¶

apply_to_circuit(circuit: QuantumCircuit) -> QuantumCircuit

Apply noise model to quantum circuit

Parameters:

Name	Type	Description	Default
`circuit`	`QuantumCircuit`	Original circuit	required

Returns:

Type	Description
`QuantumCircuit`	Noisy circuit with error channels

Source code in src/superquantx/noise.py

def apply_to_circuit(self, circuit: QuantumCircuit) -> QuantumCircuit:
    """Apply noise model to quantum circuit

    Args:
        circuit: Original circuit

    Returns:
        Noisy circuit with error channels

    """
    noisy_circuit = QuantumCircuit(circuit.num_qubits, circuit.num_classical_bits)

    for gate in circuit.gates:
        # Add original gate
        noisy_circuit.gates.append(gate)

        # Add noise after gate
        self._add_gate_noise(noisy_circuit, gate)

    # Add measurements with readout errors
    for qubit, cbit in circuit.measurements:
        self._add_readout_noise(noisy_circuit, qubit, cbit)

    return noisy_circuit

from_device_properties `classmethod` ¶

from_device_properties(device_props: dict[str, Any]) -> NoiseModel

Create noise model from device properties

Parameters:

Name	Type	Description	Default
`device_props`	`dict[str, Any]`	Device property dictionary	required

Returns:

Type	Description
`NoiseModel`	Noise model based on device properties

Source code in src/superquantx/noise.py

@classmethod
def from_device_properties(
    cls,
    device_props: dict[str, Any]
) -> "NoiseModel":
    """Create noise model from device properties

    Args:
        device_props: Device property dictionary

    Returns:
        Noise model based on device properties

    """
    noise_model = cls()

    # Extract gate error rates
    if "gates" in device_props:
        for gate_info in device_props["gates"]:
            gate_name = gate_info.get("gate")
            error_rate = gate_info.get("error_rate", 0.0)
            qubits = gate_info.get("qubits", [])

            if len(qubits) == 1:
                noise_model.add_single_qubit_error(gate_name, error_rate)
            elif len(qubits) == 2:
                noise_model.add_two_qubit_error(gate_name, error_rate)

    # Extract readout errors
    if "readout_errors" in device_props:
        for qubit, error_rate in enumerate(device_props["readout_errors"]):
            noise_model.add_readout_error(qubit, error_rate)

    # Extract coherence times
    if "coherence_times" in device_props:
        t1_times = device_props["coherence_times"].get("T1", [])
        t2_times = device_props["coherence_times"].get("T2", [])

        for qubit, (t1, t2) in enumerate(zip(t1_times, t2_times, strict=False)):
            noise_model.set_coherence_time(qubit, t1, t2)

    return noise_model

ideal `classmethod` ¶

ideal() -> NoiseModel

Create ideal (noiseless) noise model

Source code in src/superquantx/noise.py

@classmethod
def ideal(cls) -> "NoiseModel":
    """Create ideal (noiseless) noise model"""
    return cls()

basic_device_noise `classmethod` ¶

basic_device_noise(single_qubit_error: float = 0.001, two_qubit_error: float = 0.01, readout_error: float = 0.01) -> NoiseModel

Create basic device noise model

Parameters:

Name	Type	Description	Default
`single_qubit_error`	`float`	Single-qubit gate error rate	`0.001`
`two_qubit_error`	`float`	Two-qubit gate error rate	`0.01`
`readout_error`	`float`	Readout error rate	`0.01`

Returns:

Type	Description
`NoiseModel`	Basic noise model

Source code in src/superquantx/noise.py

@classmethod
def basic_device_noise(
    cls,
    single_qubit_error: float = 1e-3,
    two_qubit_error: float = 1e-2,
    readout_error: float = 1e-2
) -> "NoiseModel":
    """Create basic device noise model

    Args:
        single_qubit_error: Single-qubit gate error rate
        two_qubit_error: Two-qubit gate error rate
        readout_error: Readout error rate

    Returns:
        Basic noise model

    """
    noise_model = cls()

    # Common single-qubit gates
    for gate in ["H", "X", "Y", "Z", "RX", "RY", "RZ", "U"]:
        noise_model.add_single_qubit_error(gate, single_qubit_error)

    # Common two-qubit gates
    for gate in ["CNOT", "CZ", "SWAP"]:
        noise_model.add_two_qubit_error(gate, two_qubit_error)

    return noise_model

Usage Examples¶

Basic Circuit Construction¶

import superquantx as sqx
import numpy as np

# Create quantum circuit
circuit = sqx.QuantumCircuit(n_qubits=3, n_classical=3)

# Add quantum gates
circuit.h(0)                    # Hadamard gate
circuit.cx(0, 1)               # CNOT gate
circuit.ry(np.pi/4, 2)         # Y-rotation

# Add measurements
circuit.measure(0, 0)          # Measure qubit 0 to classical bit 0
circuit.measure_all()          # Measure all qubits

print(circuit)

Advanced Gate Operations¶

from superquantx.gates import GateMatrix, PauliString

# Custom rotation gates
theta = np.pi/3
rx_gate = GateMatrix.rx(theta)
ry_gate = GateMatrix.ry(theta) 
rz_gate = GateMatrix.rz(theta)

# Pauli string operations
pauli_str = PauliString('XYZX')  # X⊗Y⊗Z⊗X
print(f"Pauli string: {pauli_str}")
print(f"Matrix shape: {pauli_str.to_matrix().shape}")

# Hamiltonian construction
from superquantx.gates import Hamiltonian, PauliString

# Create Heisenberg model Hamiltonian
hamiltonian = Hamiltonian.heisenberg_model(num_qubits=4, Jx=1.0, Jy=1.0, Jz=1.0)
print(f"Hamiltonian: {hamiltonian}")

# Time evolution
time_evolution_op = hamiltonian.time_evolution(time=0.1)
circuit.unitary(time_evolution_op, range(4))

Measurement Analysis¶

# Execute circuit and analyze results
backend = sqx.get_backend('simulator')
result = backend.execute_circuit(circuit, shots=1000)

# Create measurement result object
measurement = sqx.MeasurementResult(
    counts=result['counts'],
    shots=result['shots'],
    metadata=result.get('metadata', {})
)

# Analyze measurements
print(f"Most frequent outcome: {measurement.most_frequent}")
print(f"Measurement probabilities: {measurement.probabilities}")

# Marginal analysis
marginal = measurement.marginal_counts([0, 1])  # Marginalize over qubits 0,1
print(f"Marginal counts: {marginal}")

# Statistical analysis
entropy = measurement.measurement_entropy()
print(f"Measurement entropy: {entropy:.4f}")

Expectation Value Calculations¶

from superquantx.measurements import QuantumMeasurement
from superquantx.gates import PauliString

# Create measurement system
measurement = QuantumMeasurement(backend="simulator")

# Define observable
observable = 'ZZ'  # Z⊗Z measurement

# Calculate expectation value
exp_value = measurement.measure_observable(
    circuit=circuit,
    observable=observable,
    shots=5000
)

print(f"⟨ZZ⟩ = {exp_value:.4f}")

# Multiple observables
observables = ['XX', 'YY', 'ZZ']

exp_values = []
for obs in observables:
    val = measurement.measure_observable(circuit, obs, shots=5000)
    exp_values.append(val)
    print(f"⟨{obs}⟩ = {val:.4f}")

Quantum State Tomography¶

from superquantx.measurements import QuantumMeasurement

# Create measurement system
measurement = QuantumMeasurement(backend="simulator")

# Perform tomography measurements
tomography_results = measurement.tomography_measurements(
    circuit=circuit,
    qubits=[0, 1],  # Reconstruct 2-qubit state
    shots_per_measurement=1000
)

# Reconstruct density matrix
density_matrix = measurement.reconstruct_state(tomography_results)
print(f"Reconstructed density matrix:\n{density_matrix}")

# Calculate fidelity with target state
bell_state = np.array([1, 0, 0, 1]) / np.sqrt(2)  # |Φ⁺⟩
fidelity = measurement.fidelity(density_matrix, bell_state)

print(f"Fidelity with |Φ⁺⟩: {fidelity:.4f}")
print(f"State purity: {np.trace(density_matrix @ density_matrix).real:.4f}")

Noise Modeling¶

from superquantx.noise import (
    NoiseModel, BitFlipChannel, PhaseFlipChannel, 
    DepolarizingChannel, AmplitudeDampingChannel
)

# Create noise channels
bit_flip = BitFlipChannel(probability=0.01)
phase_flip = PhaseFlipChannel(probability=0.01)
depolarizing = DepolarizingChannel(probability=0.02)
amplitude_damping = AmplitudeDampingChannel(probability=0.05)

# Combine into noise model
noise_model = NoiseModel()

# Add gate-specific noise
noise_model.add_gate_noise('X', bit_flip)
noise_model.add_gate_noise('H', depolarizing)
noise_model.add_gate_noise('CNOT', phase_flip)

# Add readout noise
noise_model.add_readout_noise(
    p0_given_1=0.02,  # Probability of measuring 0 given |1⟩
    p1_given_0=0.03   # Probability of measuring 1 given |0⟩
)

# Apply noise model to backend
noisy_backend = sqx.get_backend('simulator', noise_model=noise_model)

# Execute noisy simulation
noisy_result = noisy_backend.execute_circuit(circuit, shots=1000)
print("Noisy simulation results:", noisy_result['counts'])

Error Mitigation¶

from superquantx.measurements import ResultAnalyzer

# Zero-noise extrapolation
noise_levels = [1, 2, 3]
measurement_results = []

# Collect measurements at different noise levels
for noise_level in noise_levels:
    # Create noisy backend (implementation dependent)
    result = measurement.measure_circuit(circuit, shots=1000)
    measurement_results.append(result)

# Perform extrapolation
zero_noise_value, fit_info = ResultAnalyzer.error_mitigation_zero_noise_extrapolation(
    noise_levels=noise_levels,
    measurement_results=measurement_results,
    observable='Z'
)

print(f"Zero-noise extrapolated value: {zero_noise_value:.4f}")
print(f"Fit R²: {fit_info.get('r_squared', 'N/A'):.4f}")

# Readout error mitigation
calibration_results = {"0": result, "1": result}  # Calibration measurements
corrected_result = ResultAnalyzer.readout_error_mitigation(
    calibration_results=calibration_results,
    measurement_result=result
)
print(f"Corrected counts: {corrected_result.counts}")

Circuit Optimization¶

from superquantx.circuits import CircuitOptimizer

# Create optimizer
optimizer = CircuitOptimizer(
    optimization_level=2,
    target_backend=backend
)

# Optimize circuit
optimized_circuit = optimizer.optimize(circuit)

print(f"Original circuit: {circuit.depth()} depth, {circuit.count_ops()} gates")
print(f"Optimized circuit: {optimized_circuit.depth()} depth, {optimized_circuit.count_ops()} gates")

# Specific optimizations
optimized_circuit = optimizer.apply_passes([
    'RemoveRedundantGates',
    'CombineRotations',
    'CancelInverses',
    'CommuteThroughClifford'
])

Parameterized Circuits¶

from superquantx.circuits import Parameter, ParameterVector

# Create parameters
theta = Parameter('theta')
phi_vec = ParameterVector('phi', 3)

# Build parameterized circuit
param_circuit = sqx.QuantumCircuit(3)

param_circuit.ry(theta, 0)
param_circuit.rx(phi_vec[0], 1)
param_circuit.rz(phi_vec[1], 2)
param_circuit.cx(0, 1)
param_circuit.cry(phi_vec[2], 1, 2)

# Bind parameters
bound_circuit = param_circuit.bind_parameters({
    theta: np.pi/4,
    phi_vec: [np.pi/3, np.pi/6, np.pi/2]
})

# Execute bound circuit
result = backend.execute_circuit(bound_circuit)

Quantum Circuit Libraries¶

from superquantx.circuits.library import (
    EfficientSU2,
    RealAmplitudes,
    ZZFeatureMap,
    PauliFeatureMap
)

# Variational ansatz circuits
ansatz1 = EfficientSU2(num_qubits=4, reps=3)
ansatz2 = RealAmplitudes(num_qubits=4, reps=2)

# Feature map circuits for quantum machine learning
feature_map1 = ZZFeatureMap(feature_dimension=4, reps=2)
feature_map2 = PauliFeatureMap(feature_dimension=4, reps=1)

# Combine feature map and ansatz
ml_circuit = feature_map1.compose(ansatz1)

# Bind training data
training_data = [0.1, 0.5, -0.3, 0.8]
bound_ml_circuit = ml_circuit.bind_parameters({
    **feature_map1.parameter_dict(training_data),
    **ansatz1.random_parameters()
})

Circuit Simulation and Debugging¶

from superquantx.circuits import CircuitSimulator

# Create detailed simulator
sim = CircuitSimulator(backend='statevector')

# Step-by-step execution
sim.initialize_circuit(circuit)

for step, gate in enumerate(circuit.data):
    print(f"Step {step}: Applying {gate}")

    # Apply gate
    sim.apply_gate(gate)

    # Get current state
    current_state = sim.get_statevector()
    print(f"  Statevector norm: {np.linalg.norm(current_state):.6f}")

    # Check entanglement
    entanglement = sim.calculate_entanglement()
    print(f"  Entanglement entropy: {entanglement:.4f}")

# Final state analysis
final_state = sim.get_statevector()
final_density_matrix = sim.get_density_matrix()

print("Final state analysis:")
print(f"  Purity: {np.trace(final_density_matrix @ final_density_matrix).real:.4f}")
print(f"  Von Neumann entropy: {sim.von_neumann_entropy():.4f}")

Performance Optimization¶

Circuit Compilation¶

from superquantx.circuits import QuantumCompiler

# Create compiler for specific backend
compiler = QuantumCompiler(target_backend=backend)

# Compile circuit
compiled_circuit = compiler.compile(
    circuit=circuit,
    optimization_level=3,
    scheduling='as_late_as_possible',
    layout='dense'
)

# Analysis compilation results
print(f"Compilation report:")
print(f"  Original gates: {circuit.count_ops()}")
print(f"  Compiled gates: {compiled_circuit.count_ops()}")
print(f"  Gate reduction: {(1 - compiled_circuit.count_ops()/circuit.count_ops())*100:.1f}%")

Batch Circuit Execution¶

# Execute multiple circuits efficiently
circuits = [create_random_circuit(n_qubits=4) for _ in range(10)]

# Parallel execution
results = backend.execute_circuits_parallel(
    circuits=circuits,
    shots=1000,
    max_workers=4
)

# Batch analysis
success_rate = sum(1 for r in results if r['success']) / len(results)
avg_execution_time = np.mean([r.get('execution_time', 0) for r in results])

print(f"Batch execution: {success_rate*100:.1f}% success rate")
print(f"Average execution time: {avg_execution_time:.3f}s")

Best Practices¶

Circuit Construction¶

Use Native Gates: Prefer gates supported by target backend
Minimize Depth: Reduce circuit depth for better fidelity
Optimize Layout: Consider qubit connectivity constraints
Parameter Management: Use symbolic parameters for flexibility

Measurement Strategy¶

Statistical Significance: Use sufficient shots for reliable statistics
Marginal Analysis: Focus on relevant qubit subsets
Error Bars: Always include measurement uncertainties
Baseline Comparison: Compare with theoretical expectations

Noise Handling¶

Realistic Models: Use device-specific noise parameters
Error Mitigation: Apply appropriate mitigation techniques
Validation: Compare noisy vs. noiseless simulations
Calibration: Regularly update noise models from hardware data

For more detailed examples and tutorials, see: - Circuit Construction Tutorial - Backend Integration

Circuits API Reference¶

Quantum Circuits¶

Quantum Circuit¶

superquantx.circuits.QuantumCircuit ¶

Functions¶

copy ¶

add_register ¶

h ¶

x ¶

y ¶

z ¶

s ¶

sdg ¶

t ¶

tdg ¶

rx ¶

ry ¶

rz ¶

u ¶

cx ¶

cnot ¶

cy ¶

cz ¶

swap ¶

crx ¶

cry ¶

crz ¶

ccx ¶

toffoli ¶

cswap ¶

fredkin ¶

measure ¶

measure_all ¶

barrier ¶

compose ¶

inverse ¶

to_dict ¶

to_json ¶

from_dict classmethod ¶

from_json classmethod ¶

draw ¶

Quantum Gate¶

superquantx.circuits.QuantumGate ¶

Functions¶

to_dict ¶

from_dict classmethod ¶

Classical Register¶

superquantx.circuits.ClassicalRegister ¶

Quantum Gates¶

Gate Matrix Library¶

superquantx.gates.GateMatrix ¶

Functions¶

rx staticmethod ¶

ry staticmethod ¶

rz staticmethod ¶

u staticmethod ¶

phase staticmethod ¶

cnot staticmethod ¶

cz staticmethod ¶

swap staticmethod ¶

iswap staticmethod ¶

crx staticmethod ¶

cry staticmethod ¶

crz staticmethod ¶

xx staticmethod ¶

yy staticmethod ¶

zz staticmethod ¶

toffoli staticmethod ¶

fredkin staticmethod ¶

Pauli String Operations¶

superquantx.gates.PauliString ¶

Functions¶

matrix ¶

commutes_with ¶

Hamiltonian Operations¶

superquantx.gates.Hamiltonian ¶

Functions¶

matrix ¶

expectation_value ¶

ground_state_energy ¶

from_dict `classmethod` ¶

from_json `classmethod` ¶

from_dict `classmethod` ¶

rx `staticmethod` ¶

ry `staticmethod` ¶

rz `staticmethod` ¶

u `staticmethod` ¶

phase `staticmethod` ¶

cnot `staticmethod` ¶

cz `staticmethod` ¶

swap `staticmethod` ¶

iswap `staticmethod` ¶

crx `staticmethod` ¶

cry `staticmethod` ¶

crz `staticmethod` ¶

xx `staticmethod` ¶

yy `staticmethod` ¶

zz `staticmethod` ¶

toffoli `staticmethod` ¶

fredkin `staticmethod` ¶

from_dict `classmethod` ¶

heisenberg_model `staticmethod` ¶

ising_model `staticmethod` ¶

probabilities `property` ¶

most_frequent `property` ¶

from_dict `classmethod` ¶

from_json `classmethod` ¶

compare_results `staticmethod` ¶

error_mitigation_zero_noise_extrapolation `staticmethod` ¶

readout_error_mitigation `staticmethod` ¶

kraus_operators `abstractmethod` ¶

apply_to_density_matrix `abstractmethod` ¶

from_device_properties `classmethod` ¶

ideal `classmethod` ¶