Importer from OpenQASM 3 to Qiskit

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.

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:

from qiskit_qasm3_import import parse
circuit = parse(program)

circuit is now a complete QuantumCircuit, so we can see exactly what it
turned into:

circuit.draw()

       ┌───────────────┐┌─┐   ┌─────────────┐┌──────────┐┌─┐
  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:

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

pip install qiskit-terra[qasm3-import]

Developing

If you're looking to contribute to this project, please first read
our contributing guidelines.

Set up your development environment by installing the development requirements
with pip:

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

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

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

tox -e black

The full lint suite can be run with

tox -e lint

License

This project is licensed under version 2.0 of the Apache License.

Dependencies of qiskit-qasm3-import (2).
Dependency	Optional
openqasm3	false
qiskit	false

Package profile

qiskit-qasm3-import

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description