215 lines
9.1 KiB
Plaintext
215 lines
9.1 KiB
Plaintext
---
|
||
title: qasm3
|
||
description: API reference for qiskit.qasm3
|
||
in_page_toc_min_heading_level: 2
|
||
python_api_type: module
|
||
python_api_name: qiskit.qasm3
|
||
---
|
||
|
||
<span id="module-qiskit.qasm3" />
|
||
|
||
<span id="qiskit-qasm3" />
|
||
|
||
# OpenQASM 3
|
||
|
||
<span id="module-qiskit.qasm3" />
|
||
|
||
`qiskit.qasm3`
|
||
|
||
Qiskit provides some tools for converting between [OpenQASM 3](https://openqasm.com) representations of quantum programs, and the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") class. These will continue to evolve as Qiskit’s support for the dynamic-circuit capabilities expressed by OpenQASM 3 increases.
|
||
|
||
## Exporting to OpenQASM 3
|
||
|
||
The high-level functions are simply [`dump()`](#qiskit.qasm3.dump "qiskit.qasm3.dump") and [`dumps()`](#qiskit.qasm3.dumps "qiskit.qasm3.dumps"), which respectively export to a file (given as a filename) and to a Python string.
|
||
|
||
### dump
|
||
|
||
<Function id="qiskit.qasm3.dump" github="https://github.com/qiskit/qiskit/tree/stable/0.23/qiskit/qasm3/__init__.py" signature="dump(circuit, stream, **kwargs)">
|
||
Serialize a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object as a OpenQASM3 stream to file-like object.
|
||
|
||
**Parameters**
|
||
|
||
* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Circuit to serialize.
|
||
* **stream** (*TextIOBase*) – stream-like object to dump the OpenQASM3 serialization
|
||
* **\*\*kwargs** – Arguments for the [`Exporter`](#qiskit.qasm3.Exporter "qiskit.qasm3.Exporter") constructor.
|
||
|
||
**Return type**
|
||
|
||
`None`
|
||
</Function>
|
||
|
||
### dumps
|
||
|
||
<Function id="qiskit.qasm3.dumps" github="https://github.com/qiskit/qiskit/tree/stable/0.23/qiskit/qasm3/__init__.py" signature="dumps(circuit, **kwargs)">
|
||
Serialize a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object in an OpenQASM3 string.
|
||
|
||
**Parameters**
|
||
|
||
* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Circuit to serialize.
|
||
* **\*\*kwargs** – Arguments for the [`Exporter`](#qiskit.qasm3.Exporter "qiskit.qasm3.Exporter") constructor.
|
||
|
||
**Returns**
|
||
|
||
The OpenQASM3 serialization
|
||
|
||
**Return type**
|
||
|
||
str
|
||
</Function>
|
||
|
||
Both of these exporter functions are single-use wrappers around the main [`Exporter`](#qiskit.qasm3.Exporter "qiskit.qasm3.Exporter") class. For more complex exporting needs, including dumping multiple circuits in a single session, it may be more convenient or faster to use the complete interface.
|
||
|
||
### Exporter
|
||
|
||
<Class id="qiskit.qasm3.Exporter" github="https://github.com/qiskit/qiskit/tree/stable/0.23/qiskit/qasm3/exporter.py" signature="Exporter(includes=('stdgates.inc',), basis_gates=('U',), disable_constants=False, alias_classical_registers=False, indent=' ')" modifiers="class">
|
||
QASM3 exporter main class.
|
||
|
||
**Parameters**
|
||
|
||
* **includes** (`Sequence`\[`str`]) – the filenames that should be emitted as includes. These files will be parsed for gates, and any objects dumped from this exporter will use those definitions where possible.
|
||
* **basis\_gates** (`Sequence`\[`str`]) – the basic defined gate set of the backend.
|
||
* **disable\_constants** (`bool`) – if `True`, always emit floating-point constants for numeric parameter values. If `False` (the default), then values close to multiples of QASM 3 constants (`pi`, `euler`, and `tau`) will be emitted in terms of those constants instead, potentially improving accuracy in the output.
|
||
* **alias\_classical\_registers** (`bool`) – If `True`, then classical bit and classical register declarations will look similar to quantum declarations, where the whole set of bits will be declared in a flat array, and the registers will just be aliases to collections of these bits. This is inefficient for running OpenQASM 3 programs, however, and may not be well supported on backends. Instead, the default behaviour of `False` means that individual classical registers will gain their own `bit[size] register;` declarations, and loose [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit")s will go onto their own declaration. In this form, each [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") must be in either zero or one [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")s.
|
||
* **indent** (`str`) – the indentation string to use for each level within an indented block. Can be set to the empty string to disable indentation.
|
||
|
||
#### dump
|
||
|
||
<Function id="qiskit.qasm3.Exporter.dump" signature="dump(circuit, stream)">
|
||
Convert the circuit to QASM 3, dumping the result to a file or text stream.
|
||
</Function>
|
||
|
||
#### dumps
|
||
|
||
<Function id="qiskit.qasm3.Exporter.dumps" signature="dumps(circuit)">
|
||
Convert the circuit to QASM 3, returning the result as a string.
|
||
</Function>
|
||
</Class>
|
||
|
||
All of these interfaces will raise [`QASM3ExporterError`](#qiskit.qasm3.QASM3ExporterError "qiskit.qasm3.QASM3ExporterError") on failure.
|
||
|
||
### QASM3ExporterError
|
||
|
||
<Class id="qiskit.qasm3.QASM3ExporterError" github="https://github.com/qiskit/qiskit/tree/stable/0.23/qiskit/qasm3/exceptions.py" signature="QASM3ExporterError(*message)" modifiers="exception">
|
||
An error raised during running the OpenQASM 3 exporter.
|
||
|
||
Set the error message.
|
||
</Class>
|
||
|
||
## Importing from OpenQASM 3
|
||
|
||
Currently only two high-level functions are offered, as Qiskit support for importing from OpenQASM 3 is in its infancy, and the implementation is expected to change significantly. The two functions are [`load()`](#qiskit.qasm3.load "qiskit.qasm3.load") and [`loads()`](#qiskit.qasm3.loads "qiskit.qasm3.loads"), which are direct counterparts of [`dump()`](#qiskit.qasm3.dump "qiskit.qasm3.dump") and [`dumps()`](#qiskit.qasm3.dumps "qiskit.qasm3.dumps"), respectively loading a program indirectly from a named file and directly from a given string.
|
||
|
||
<Admonition title="Note" type="note">
|
||
While we are still in the exploratory release period, to use either function, the package `qiskit_qasm3_import` must be installed. This can be done by installing Qiskit Terra with the `qasm3-import` extra, such as by:
|
||
|
||
```python
|
||
pip install qiskit-terra[qasm3-import]
|
||
```
|
||
|
||
We expect that this functionality will eventually be merged into core Terra, and no longer require an optional import, but we do not yet have a timeline for this.
|
||
</Admonition>
|
||
|
||
### load
|
||
|
||
<Function id="qiskit.qasm3.load" github="https://github.com/qiskit/qiskit/tree/stable/0.23/qiskit/qasm3/__init__.py" signature="load(filename)">
|
||
Load an OpenQASM 3 program from the file `filename`.
|
||
|
||
**Parameters**
|
||
|
||
**filename** (`str`) – the filename to load the program from.
|
||
|
||
**Returns**
|
||
|
||
a circuit representation of the OpenQASM 3 program.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Raises**
|
||
|
||
[**QASM3ImporterError**](#qiskit.qasm3.QASM3ImporterError "qiskit.qasm3.QASM3ImporterError") – if the OpenQASM 3 file is invalid, or cannot be represented by a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
|
||
</Function>
|
||
|
||
### loads
|
||
|
||
<Function id="qiskit.qasm3.loads" github="https://github.com/qiskit/qiskit/tree/stable/0.23/qiskit/qasm3/__init__.py" signature="loads(program)">
|
||
Load an OpenQASM 3 program from the given string.
|
||
|
||
**Parameters**
|
||
|
||
**program** (`str`) – the OpenQASM 3 program.
|
||
|
||
**Returns**
|
||
|
||
a circuit representation of the OpenQASM 3 program.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Raises**
|
||
|
||
[**QASM3ImporterError**](#qiskit.qasm3.QASM3ImporterError "qiskit.qasm3.QASM3ImporterError") – if the OpenQASM 3 file is invalid, or cannot be represented by a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
|
||
</Function>
|
||
|
||
Both of these two functions raise [`QASM3ImporterError`](#qiskit.qasm3.QASM3ImporterError "qiskit.qasm3.QASM3ImporterError") on failure.
|
||
|
||
### QASM3ImporterError
|
||
|
||
<Class id="qiskit.qasm3.QASM3ImporterError" github="https://github.com/qiskit/qiskit/tree/stable/0.23/qiskit/qasm3/exceptions.py" signature="QASM3ImporterError(*message)" modifiers="exception">
|
||
An error raised during the OpenQASM 3 importer.
|
||
|
||
Set the error message.
|
||
</Class>
|
||
|
||
For example, we can define a quantum program using OpenQASM 3, and use [`loads()`](#qiskit.qasm3.loads "qiskit.qasm3.loads") to directly convert it into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"):
|
||
|
||
```python
|
||
import qiskit.qasm3
|
||
|
||
program = """
|
||
OPENQASM 3.0;
|
||
include "stdgates.inc";
|
||
|
||
input float[64] a;
|
||
qubit[3] q;
|
||
bit[2] mid;
|
||
bit[3] out;
|
||
|
||
let aliased = q[0:1];
|
||
|
||
gate my_gate(a) c, t {
|
||
gphase(a / 2);
|
||
ry(a) c;
|
||
cx c, t;
|
||
}
|
||
gate my_phase(a) c {
|
||
ctrl @ inv @ gphase(a) c;
|
||
}
|
||
|
||
my_gate(a * 2) aliased[0], q[{1, 2}][0];
|
||
measure q[0] -> mid[0];
|
||
measure q[1] -> mid[1];
|
||
|
||
while (mid == "00") {
|
||
reset q[0];
|
||
reset q[1];
|
||
my_gate(a) q[0], q[1];
|
||
my_phase(a - pi/2) q[1];
|
||
mid[0] = measure q[0];
|
||
mid[1] = measure q[1];
|
||
}
|
||
|
||
if (mid[0]) {
|
||
let inner_alias = q[{0, 1}];
|
||
reset inner_alias;
|
||
}
|
||
|
||
out = measure q;
|
||
"""
|
||
circuit = qiskit.qasm3.loads(program)
|
||
circuit.draw("mpl")
|
||
```
|
||
|