162 lines
12 KiB
Plaintext
162 lines
12 KiB
Plaintext
---
|
||
title: random (dev version)
|
||
description: API reference for qiskit.circuit.random in the dev version of qiskit
|
||
in_page_toc_min_heading_level: 2
|
||
python_api_type: module
|
||
python_api_name: qiskit.circuit.random
|
||
---
|
||
|
||
<span id="module-qiskit.circuit.random" />
|
||
|
||
<span id="random-circuits-qiskit-circuit-random" />
|
||
|
||
# Random Circuits
|
||
|
||
`qiskit.circuit.random`
|
||
|
||
## Overview
|
||
|
||
The [`qiskit.circuit.random`](#module-qiskit.circuit.random "qiskit.circuit.random") module offers functions that can be used for generating arbitrary circuits with gates randomly selected from a given set of gates.
|
||
|
||
These circuits can be used for benchmarking existing quantum hardware and estimating the performance of quantum circuit transpilers and software infrastructure. The functions below can generate bespoke quantum circuits respecting various properties such as number of qubits, depth of the circuit, coupling map, gate set, etc.
|
||
|
||
### Generating arbitrary circuits
|
||
|
||
#### random\_circuit
|
||
|
||
<Function id="qiskit.circuit.random.random_circuit" github="https://github.com/Qiskit/qiskit/tree/main/qiskit/circuit/random/utils.py#L460-L684" signature="qiskit.circuit.random.random_circuit(num_qubits, depth, max_operands=4, measure=False, conditional=False, reset=False, seed=None, num_operand_distribution=None)">
|
||
Generate random circuit of arbitrary size and form.
|
||
|
||
This function will generate a random circuit by randomly selecting gates from the set of standard gates in `qiskit.circuit.library.standard_gates`. For example:
|
||
|
||
```python
|
||
from qiskit.circuit.random import random_circuit
|
||
|
||
circ = random_circuit(2, 2, measure=True)
|
||
circ.draw(output='mpl')
|
||
```
|
||
|
||
|
||
|
||
**Parameters**
|
||
|
||
* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – number of quantum wires
|
||
* **depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – layers of operations (i.e. critical path length)
|
||
* **max\_operands** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – maximum qubit operands of each gate (between 1 and 4)
|
||
* **measure** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – if True, measure all qubits at the end
|
||
* **conditional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – if True, insert middle measurements and conditionals
|
||
* **reset** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – if True, insert middle resets
|
||
* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – sets random seed (optional)
|
||
* **num\_operand\_distribution** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")) – a distribution of gates that specifies the ratio of 1-qubit, 2-qubit, 3-qubit, …, n-qubit gates in the random circuit. Expect a deviation from the specified ratios that depends on the size of the requested random circuit. (optional)
|
||
|
||
**Returns**
|
||
|
||
constructed circuit
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when invalid options given
|
||
</Function>
|
||
|
||
### Generating arbitrary circuits respecting qubit-coupling
|
||
|
||
#### random\_circuit\_from\_graph
|
||
|
||
<Function id="qiskit.circuit.random.random_circuit_from_graph" github="https://github.com/Qiskit/qiskit/tree/main/qiskit/circuit/random/utils.py#L79-L457" signature="qiskit.circuit.random.random_circuit_from_graph(interaction_graph, min_2q_gate_per_edge=1, max_operands=2, measure=False, conditional=False, reset=False, seed=None, insert_1q_oper=True, prob_conditional=0.1, prob_reset=0.1)">
|
||
Generate random circuit of arbitrary size and form which strictly respects the interaction graph passed as argument. Interaction Graph is a graph G=(V, E) where V are the qubits in the circuit, and, E is the set of two-qubit gate interactions between two particular qubits in the circuit.
|
||
|
||
This function will generate a random circuit by randomly selecting 1Q and 2Q gates from the set of standard gates in `qiskit.circuit.library.standard_gates`. The user can attach a numerical value as a metadata to the edge of the graph indicating the edge weight for that particular edge, These edge weights would be normalized to the probabilities of the edges getting selected. If all the edge weights are passed as None, then the probability of each qubit-pair of getting selected is set to 1/N, where N is the number of edges in the interaction\_graph passed in, i.e each edge is drawn uniformly. If any weight of an edge is set as zero, that particular edge will not be included in the output circuit.
|
||
|
||
Passing a list of tuples of control qubit, target qubit and associated probability is also acceptable as a way to specify an interaction graph.
|
||
|
||
If numerical values are present as probabilities but some/any are None, or negative, when max\_operands=2 this will raise a ValueError.
|
||
|
||
If max\_operands is set to 1, then there are no 2Q operations, so no need to take care of the edges, in such case the function will return a circuit from the random\_circuit function, which would be passed with the max\_operands as 1.
|
||
|
||
If max\_operands is set to 2, then in every while-iteration 2Q gates are chosen randomly, and qubit-pairs which exist in the input interaction graph are also chosen randomly based on the probability attached to the qubit-pair. Then in a for-iteration 2Q gates are applied to the randomly chosen qubit-pairs with the aim to reach the count of 2Q on any qubit-pair to min\_2q\_gate\_per\_edge criteria as soon as possible within a particular iteration. Now, if some qubits are still idle after applying 2Q gates for that particular iteration, then randomly chosen 1Q gates are applied to those idle qubits if insert\_1q\_oper is set to True.
|
||
|
||
Example:
|
||
|
||
```python
|
||
from qiskit.circuit.random.utils import random_circuit_from_graph
|
||
import rustworkx as rx
|
||
pydi_graph = rx.PyDiGraph()
|
||
pydi_graph.add_nodes_from(range(7))
|
||
cp_map = [(0, 1, 0.18), (1, 2, 0.15), (2, 3, 0.15), (3, 4, 0.22), (4, 5, 0.13), (5, 6, 0.17)]
|
||
pydi_graph.add_edges_from(cp_map)
|
||
# cp_map can be passed in directly as interaction_graph
|
||
qc = random_circuit_from_graph(pydi_graph, min_2q_gate_per_edge=2, seed=12345)
|
||
qc.draw(output='mpl')
|
||
```
|
||
|
||
|
||
|
||
**Parameters**
|
||
|
||
* **interaction\_graph** (*PyGraph | PyDiGraph | List\[Tuple\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*]]*) – Interaction Graph
|
||
* **min\_2q\_gate\_per\_edge** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – Minimum number of times every qubit-pair must be used in the random circuit. (optional, default:1)
|
||
* **max\_operands** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – maximum qubit operands of each gate(should be 1 or 2) (optional, default:2)
|
||
* **measure** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – if True, measure all qubits at the end. (optional, default: False)
|
||
* **conditional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – if True, insert middle measurements and conditionals. (optional, default: False)
|
||
* **reset** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – if True, insert middle resets. (optional, default: False)
|
||
* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – sets random seed. (If None, a random seed is chosen) (optional)
|
||
* **insert\_1q\_oper** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Insert 1Q operations to the circuit. (optional, default: True)
|
||
* **prob\_conditional** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – Probability less than 1.0, this is used to control the occurrence of conditionals in the circuit. (optional, default: 0.1)
|
||
* **prob\_reset** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – Probability less than 1.0, this is used to control the occurrence of reset in the circuit. (optional, default: 0.1)
|
||
|
||
**Returns**
|
||
|
||
constructed circuit
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Raises**
|
||
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – When max\_operands is not 1 or 2.
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – When max\_operands is set to 1, but no 1Q operations are allowed by setting insert\_1q\_oper to false.
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – When the interaction graph has no edges, so only 1Q gates are possible in the circuit, but insert\_1q\_oper is set to False.
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – When an invalid interaction graph object is passed.
|
||
* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Given max\_operands=2, when any edge have probability None but not all, or any of the probabilities are negative.
|
||
</Function>
|
||
|
||
### Generating arbitrary circuits with clifford gates
|
||
|
||
#### random\_clifford\_circuit
|
||
|
||
<Function id="qiskit.circuit.random.random_clifford_circuit" github="https://github.com/Qiskit/qiskit/tree/main/qiskit/circuit/random/utils.py#L687-L755" signature="qiskit.circuit.random.random_clifford_circuit(num_qubits, num_gates, gates='all', seed=None)">
|
||
Generate a pseudo-random Clifford circuit.
|
||
|
||
This function will generate a Clifford circuit by randomly selecting the chosen amount of Clifford gates from the set of standard gates in `qiskit.circuit.library.standard_gates`. For example:
|
||
|
||
```python
|
||
from qiskit.circuit.random import random_clifford_circuit
|
||
|
||
circ = random_clifford_circuit(num_qubits=2, num_gates=6)
|
||
circ.draw(output='mpl')
|
||
```
|
||
|
||
|
||
|
||
**Parameters**
|
||
|
||
* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – number of quantum wires.
|
||
* **num\_gates** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – number of gates in the circuit.
|
||
* **gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*]*) – optional list of Clifford gate names to randomly sample from. If `"all"` (default), use all Clifford gates in the standard library.
|
||
* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| np.random.Generator*) – sets random seed/generator (optional).
|
||
|
||
**Returns**
|
||
|
||
constructed circuit
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|