Random Circuit Generation

API reference for random circuit generation and quantum benchmarking utilities.

random_qcircuit

Generates a random quantum circuit with the specified qubits, depth, and gate types.

Signature

random_qcircuit(qubits: list[int], depth: int, gate_type: list[str]) -> QCircuit
random_qcircuit(qubits: list[int], depth: int, gate_type: list[str], topology: list[list[int]]) -> QCircuit

Parameters

Parameter	Type	Description
qubits	list[int]	List of qubit indices to include in the circuit
depth	int	Depth (number of gate layers) of the circuit
gate_type	list[str]	List of gate type strings to use, e.g. ["H", "CNOT"]
topology	list[list[int]]	Optional chip coupling edge list, in the same format as ChipInfo.get_chip_topology(), e.g. [[0, 1], [1, 2]]. Every two-qubit gate lands on one of these edges; an edge referencing a qubit outside qubits raises ValueError.

Returns

QCircuit — A randomly generated quantum circuit.

Examples

from pyqpanda3.core import random_qcircuit

# Generate a random circuit on qubits [0, 1, 2] with depth 5 using H and CNOT gates
circ = random_qcircuit([0, 1, 2], 5, ["H", "CNOT"])
print(f"Circuit depth: {circ.depth()}")
print(f"Gate count: {circ.count_ops()}")

Sample output (gate counts vary between runs because random_qcircuit does not accept a seed):

Circuit depth: 5
Gate count: {'H': 2, 'CNOT': 4}

random_qprog

Generates a random quantum program with the specified qubits, depth, gate types, and optional topology constraint.

Signature

random_qprog(qubits: list[int], depth: int, gate_type: list[str]) -> QProg
random_qprog(qubits: list[int], depth: int, gate_type: list[str], topology: list[list[int]]) -> QProg

Parameters

Parameter	Type	Description
qubits	list[int]	List of qubit indices to include in the program
depth	int	Depth (number of gate layers) of the program
gate_type	list[str]	List of gate type strings to use, e.g. ["H", "CNOT"]
topology	list[list[int]]	Optional chip coupling edge list, in the same format as ChipInfo.get_chip_topology(), e.g. [[0, 1], [1, 2]]. Every two-qubit gate lands on one of these edges; an edge referencing a qubit outside qubits raises ValueError.

Returns

QProg — A randomly generated quantum program.

Examples

from pyqpanda3.core import random_qcircuit, random_qprog

topology = [[0, 1], [1, 2]]
circ = random_qcircuit([0, 1, 2], 5, ["H", "CNOT"], topology)
prog = random_qprog([0, 1, 2], 5, ["H", "CNOT"], topology)
print(circ.gate_operations())
print(prog.gate_operations())

NOTE

The topology argument is available from 0.5.1; this example was not executed locally (no 0.5.1 wheel in this environment).

QV — Quantum Volume Benchmark

Generates a Quantum Volume (QV) benchmark circuit for the given configuration.

Signature

QV(num_qubit: int, depth: int, seed: int) -> QCircuit

Parameters

Parameter	Type	Description
num_qubit	int	Number of qubits for the QV test
depth	int	Depth (number of layers) of the circuit
seed	int	Random seed for reproducibility

Returns

QCircuit — The quantum volume benchmark circuit.

Examples

from pyqpanda3.core import QV

# Compute quantum volume for a 4-qubit, depth-4 circuit
qv = QV(num_qubit=4, depth=4, seed=42)
print(f"Quantum Volume: {qv}")

运行结果：

Quantum Volume: 
          ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐                                        
q_0:  |0>─┤1         ├ ┤0         ├ ┤0         ├ ┤0         ├ ──────────── ──────────── ──────────── 
          │          │ │  ORACLE  │ │          │ │          │ ┌──────────┐              ┌──────────┐ 
q_1:  |0>─┤          ├ ┤1         ├ ┤  ORACLE  ├ ┤          ├ ┤0         ├ ──────────── ┤1         ├ 
          │  ORACLE  │ ├──────────┤ │          │ │  ORACLE  │ │  ORACLE  │ ┌──────────┐ │          │ 
q_2:  |0>─┤          ├ ┤1         ├ ┤1         ├ ┤          ├ ┤1         ├ ┤1         ├ ┤  ORACLE  ├ 
          │          │ │  ORACLE  │ └──────────┘ │          │ └──────────┘ │  ORACLE  │ │          │ 
q_3:  |0>─┤0         ├ ┤0         ├ ──────────── ┤1         ├ ──────────── ┤0         ├ ┤0         ├ 
          └──────────┘ └──────────┘              └──────────┘              └──────────┘ └──────────┘ 
 c :   / ═══════════════════════════════════════════════════════════════════════

Mathematical Background

Quantum Volume is a single-number metric that captures the overall capability of a quantum processor. It accounts for qubit count, gate fidelity, connectivity, and software performance. The QV protocol runs random circuits of width $n$ and depth $d=n$, checking if the heavy-output probability exceeds $2/3$.

$$QV=2^{min(n,d)}$$

where $n$ is the largest number of qubits for which the heavy-output test passes.

direct_twirl

Performs direct twirling (randomized compiling) on a quantum program, decomposing it into a sequence of random Pauli frames.

Signature

direct_twirl(
    input_circ: QProg,
    twirled_gate: str,
    seed: int
) -> QProg

Parameters

Parameter	Type	Description
input_circ	QProg	Input quantum program to twirl
twirled_gate	str	Gate type to use for twirling. Supported: "CNOT", "CZ"
seed	int	Random seed for reproducibility. Since 0.5.0 all seed values (including those below 8000) yield distinct twirls, and the same seed reproduces the same program

Returns

QProg — The twirled quantum program.

Examples

from pyqpanda3.core import H, CNOT, direct_twirl, QProg

# Build a simple program
prog = QProg()
prog << H(0) << CNOT(0, 1)

# Apply direct twirling
twirled = direct_twirl(prog, "CNOT", 42)
print(f"Original gates: {prog.count_ops()}")
print(f"Twirled gates: {twirled.count_ops()}")

运行结果：

Original gates: {'CNOT': 1, 'H': 1}
Twirled gates: {'CNOT': 1, 'H': 1, 'Z': 1, 'I': 1, 'Y': 2}

Mathematical Background

Twirling converts a general quantum channel into a Pauli channel by conjugating with random Pauli operators. For a channel $\mathcal{E}$:

$${\mathcal{E}}_T(\rho )=\frac{1}{4^n}\sum _{P\in \{I,X,Y,Z{\}}^n}P\mathcal{E}(P\rho P)P$$

This simplifies error characterization and enables error mitigation techniques.

See Also

• Circuit — QCircuit class
• Circuit — QProg class
• Gates — GateType enumeration
• Simulator — Quantum simulators