Skip to main content

Importer for parsing OpenQASM 3 strings into Qiskit circuits

Project description

Importer from OpenQASM 3 to Qiskit

LicenseReleaseDownloads

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

qiskit_qasm3_import-0.5.1.tar.gz (34.1 kB view details)

Uploaded Source

Built Distribution

qiskit_qasm3_import-0.5.1-py3-none-any.whl (27.6 kB view details)

Uploaded Python 3

File details

Details for the file qiskit_qasm3_import-0.5.1.tar.gz.

File metadata

  • Download URL: qiskit_qasm3_import-0.5.1.tar.gz
  • Upload date:
  • Size: 34.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.15

File hashes

Hashes for qiskit_qasm3_import-0.5.1.tar.gz
Algorithm Hash digest
SHA256 334fff0080667fe9cb39e807b0875a2658b01d33b4c964a8816411b30938c107
MD5 7f4f9f7f5ff0427de67123e9843aa9a3
BLAKE2b-256 f4a70c5241d05e999b0f13e89241b4c2c2c488add7f3240642612591fdd4f2d8

See more details on using hashes here.

File details

Details for the file qiskit_qasm3_import-0.5.1-py3-none-any.whl.

File metadata

File hashes

Hashes for qiskit_qasm3_import-0.5.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ba6cc1ce3b142c069be07e945816a4bc1458fafe950df4f0eb15ae97d5275102
MD5 1d57b0acc1b6b36b570bc3d6ac531cda
BLAKE2b-256 c2f2d061b1eb3edd70b4503c06ebe94e087d089de01187b7b5d8d99a43df010a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page