https://github.com/qiskit/qiskit-qasm3-import
Importer from OpenQASM 3 to Qiskit's QuantumCircuit
https://github.com/qiskit/qiskit-qasm3-import
openqasm qiskit quantum-computing
Last synced: 3 months ago
JSON representation
Importer from OpenQASM 3 to Qiskit's QuantumCircuit
- Host: GitHub
- URL: https://github.com/qiskit/qiskit-qasm3-import
- Owner: Qiskit
- License: apache-2.0
- Created: 2022-11-09T20:33:03.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-06-03T21:35:16.000Z (4 months ago)
- Last Synced: 2025-06-04T06:03:53.061Z (4 months ago)
- Topics: openqasm, qiskit, quantum-computing
- Language: Python
- Homepage: https://qiskit.github.io/qiskit-qasm3-import
- Size: 106 KB
- Stars: 24
- Watchers: 13
- Forks: 9
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Importer from OpenQASM 3 to Qiskit
[](https://opensource.org/licenses/Apache-2.0)[](https://github.com/Qiskit/qiskit-qasm3-import/releases)[](https://pypi.org/project/qiskit-qasm3-import/)
This repository provides the Python package `qiskit_qasm3_import`, which is a
basic and temporary importer from OpenQASM 3 into Qiskit's `QuantumCircuit`.
Qiskit itself accepts this package as an optional dependency if it is installed.
In that case, Qiskit exposes the functions `qiskit.qasm3.load` and
`qiskit.qasm3.loads`, which are wrappers around `qiskit_qasm3_import.parse`.
This project is a stop-gap measure until various technical decisions can be
resolved the correct way; Terra makes strong guarantees of stability and support
in its interfaces, and we are not yet ready to make that commitment for this
project, hence the minimal wrappers.
## Example
The principal entry point to the package is the top-level `parse` function,
which accepts a string containing a complete OpenQASM 3 programme. This complex
example shows a lot of the capabilities of the importer.
```qasm
OPENQASM 3.0;
// The 'stdgates.inc' include is supported, and the gates are only available
// if it has correctly been included.
include "stdgates.inc";
// Parametrised inputs are supported.
input float[64] a;
qubit[3] q;
bit[2] mid;
bit[3] out;
// Aliasing and re-aliasing are supported.
let aliased = q[0:1];
// Parametrised gates that make use of the stdlib.
gate my_gate(a) c, t {
gphase(a / 2);
ry(a) c;
cx c, t;
}
// Gate modifiers work as well; this gate is equivalent to `p(-a) c;`.
gate my_phase(a) c {
ctrl @ inv @ gphase(a) c;
}
// We handle mathematical expressions on gate creation and complex indexing
// of temporary collections.
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];
// We support the builtin mathematical symbols.
my_phase(a - pi/2) q[1];
mid[0] = measure q[0];
mid[1] = measure q[1];
}
// The condition resolver can also handle simple cases that don't look
// _exactly_ like equality conditions.
if (mid[0]) {
// There is limited support for aliasing within nested scopes.
let inner_alias = q[{0, 1}];
reset inner_alias;
}
out = measure q;
```
Assuming this program is stored as a string in a variable `program`, we then
import it into a `QuantumCircuit` by doing:
```python
from qiskit_qasm3_import import parse
circuit = parse(program)
```
`circuit` is now a complete `QuantumCircuit`, so we can see exactly what it
turned into:
```python
circuit.draw()
```
```text
┌───────────────┐┌─┐ ┌─────────────┐┌──────────┐┌─┐
q_0: ┤0 ├┤M├───┤0 ├┤0 ├┤M├───
│ my_gate(2*a) │└╥┘┌─┐│ ││ │└╥┘┌─┐
q_1: ┤1 ├─╫─┤M├┤1 ├┤1 ├─╫─┤M├
└──────┬─┬──────┘ ║ └╥┘│ ││ If_else │ ║ └╥┘
q_2: ───────┤M├────────╫──╫─┤ While_loop ├┤ ├─╫──╫─
└╥┘ ║ ║ │ ││ │ ║ ║
mid_0: ════════╬═════════╩══╬═╡1 ╞╡0 ╞═╬══╬═
║ ║ │ │└──────────┘ ║ ║
mid_1: ════════╬════════════╩═╡0 ╞═════════════╬══╬═
║ └─────────────┘ ║ ║
out_0: ════════╬══════════════════════════════════════════╩══╬═
║ ║
out_1: ════════╬═════════════════════════════════════════════╩═
║
out_2: ════════╩═══════════════════════════════════════════════
```
## Installation
Install the latest release of the `qiskit_qasm3_import` package from pip:
```text
pip install qiskit_qasm3_import
```
This will automatically install all the dependencies as well (an OpenQASM 3
parser, for example) if they are not already installed. Alternatively, you can
install Qiskit Terra directly with this package as an optional dependency by
doing
```text
pip install qiskit-terra[qasm3-import]
```
## Developing
If you're looking to contribute to this project, please first read
[our contributing guidelines](CONTRIBUTING.md).
Set up your development environment by installing the development requirements
with pip:
```bash
pip install -r requirements-dev.txt tox
```
This installs a few more packages than the dependencies of the package at
runtime, because there are some tools we use for testing also included, such as
`tox` and `pytest`.
After the development requirements are installed, you can install an editable
version of the package with
```bash
pip install -e .
```
After this, any changes you make to the library code will immediately be present
when you open a new Python interpreter session.
### Building documentation
After the development requirements have been installed, the command
```bash
tox -e docs
```
will build the HTML documentation, and place it in `docs/_build/html`. The
documentation state of the `main` branch of this repository is published to
https://qiskit.github.io/qiskit-qasm3-import.
### Code style and linting
The Python components of this repository are formatted using `black`. You can
run this on the required files by running
```bash
tox -e black
```
The full lint suite can be run with
```bash
tox -e lint
```
## License
This project is licensed under [version 2.0 of the Apache License](LICENSE).