Skip to main content

Quantum - API Specification

Version: v1.1.9 | Status: Active | Last Updated: February 2026

Overview​

The Quantum module provides quantum circuit construction, statevector simulation, and common quantum algorithm primitives (Bell state, GHZ state, QFT). All simulation is classical -- no quantum hardware required.

Enums​

GateType​

Supported quantum gate types.

  • GateType.H - Hadamard
  • GateType.X - Pauli-X (NOT)
  • GateType.Y - Pauli-Y
  • GateType.Z - Pauli-Z
  • GateType.CNOT - Controlled-NOT (two-qubit)
  • GateType.SWAP - Swap (two-qubit)
  • GateType.T - T gate (pi/4 phase)
  • GateType.S - S gate (pi/2 phase)
  • GateType.RX - Rotation around X-axis (parameterized)
  • GateType.RY - Rotation around Y-axis (parameterized)
  • GateType.RZ - Rotation around Z-axis (parameterized)
  • GateType.CZ - Controlled-Z (two-qubit)

Data Classes​

Gate​

Represents a gate in a circuit.

FieldTypeDefaultDescription
gate_typeGateTyperequiredThe gate operation
targetintrequiredTarget qubit index
control`intNone`None Control qubit for two-qubit gates
parameter`floatNone`None Rotation angle for RX/RY/RZ

Qubit​

Represents a single qubit state as amplitudes.

FieldTypeDefaultDescription
alphacomplex1+0jAmplitude of 0>
betacomplex0+0jAmplitude of 1>

Class Methods​

  • Qubit.zero() -> Qubit - Returns |0> state.
  • Qubit.one() -> Qubit - Returns |1> state.
  • Qubit.plus() -> Qubit - Returns |+> state (equal superposition).
  • Qubit.minus() -> Qubit - Returns |-> state.

Properties​

  • prob_0 -> float - Probability of measuring 0.
  • prob_1 -> float - Probability of measuring 1.

Qubit.measure() -> int​

  • Description: Measure the qubit, collapsing state to |0> or |1>.
  • Returns: int - 0 or 1 (probabilistic).

Classes​

QuantumCircuit​

Builder for quantum circuits with a fluent API.

QuantumCircuit.__init__(num_qubits, num_classical_bits=0)​

  • Parameters:
    • num_qubits (int): Number of qubits.
    • num_classical_bits (int): Number of classical bits. Defaults to num_qubits.

Gate Methods (all return self for chaining)​

  • h(qubit) -> QuantumCircuit - Add Hadamard gate.
  • x(qubit) -> QuantumCircuit - Add Pauli-X gate.
  • y(qubit) -> QuantumCircuit - Add Pauli-Y gate.
  • z(qubit) -> QuantumCircuit - Add Pauli-Z gate.
  • cnot(control, target) -> QuantumCircuit - Add CNOT gate.
  • swap(qubit1, qubit2) -> QuantumCircuit - Add SWAP gate (two-qubit).
  • cz(control, target) -> QuantumCircuit - Add Controlled-Z gate.
  • rx(qubit, theta) -> QuantumCircuit - Add RX rotation (theta in radians).
  • ry(qubit, theta) -> QuantumCircuit - Add RY rotation.
  • rz(qubit, theta) -> QuantumCircuit - Add RZ rotation.

Measurement Methods​

  • measure(qubit, classical_bit) -> QuantumCircuit - Map qubit measurement to a classical bit.
  • measure_all() -> QuantumCircuit - Measure all qubits to corresponding classical bits.

QuantumSimulator​

Statevector simulator. Executes circuits by applying gate matrices to a full state vector.

QuantumSimulator.__init__()​

No parameters. State is initialized per-run.

QuantumSimulator.run(circuit, shots=1024) -> dict[str, int]​

  • Description: Simulate the circuit for a number of shots and return measurement counts.
  • Parameters:
    • circuit (QuantumCircuit): Circuit to simulate.
    • shots (int): Number of simulation runs. Default: 1024.
  • Returns: dict[str, int] - Mapping of bitstring to count (e.g., {"00": 512, "11": 512}).

Visualization Functions​

circuit_to_ascii(circuit) -> str​

  • Description: Render a quantum circuit as ASCII art. Gate symbols: H, X, Y, Z, Rx, Ry, Rz, CNOT target=X control=*, CZ target=Z control=*, SWAP=x, Measure=M.
  • Parameters:
    • circuit (QuantumCircuit): The circuit to render.
  • Returns: str - Multi-line ASCII art with one line per qubit wire.

circuit_stats(circuit) -> dict​

  • Description: Return circuit statistics.
  • Parameters:
    • circuit (QuantumCircuit): The circuit to analyze.
  • Returns: dict with keys:
    • num_qubits (int): Number of qubits.
    • num_gates (int): Total gate count.
    • gate_counts (dict[str, int]): Count per gate type name.
    • depth (int): Maximum gates on any single qubit wire.
    • has_measurements (bool): Whether the circuit has measurements.

Convenience Functions​

bell_state() -> QuantumCircuit​

Returns a 2-qubit Bell state circuit (H on qubit 0, CNOT 0->1, measure all).

ghz_state(n) -> QuantumCircuit​

Returns an n-qubit GHZ state circuit (H on qubit 0, CNOT 0->i for all other qubits, measure all).

qft(n) -> QuantumCircuit​

Returns an n-qubit Quantum Fourier Transform circuit. Does not include measurement.

Error Handling​

No custom exception classes. Invalid qubit indices may produce IndexError during simulation. The simulator does not validate circuit correctness at construction time.

Configuration​

No external configuration. All parameters are passed at construction or call time.