openqasm / openqasm

Quantum assembly language for extended quantum circuits

OpenQASM

OpenQASM is an imperative programming language for describing quantum circuits. It is capable of describing universal quantum computing using the circuit model, measurement-based model, and near-term quantum computing experiments.

This repo contains the OpenQASM specification, examples, and tools for the OpenQASM intermediate representation.

OpenQASM is a Qiskit project.

Current version: 3.0

• Live language specification version 3.0

• The branch of this repository for the previous version: OpenQASM 2.0

About this project

In this repository, you'll find all the documentation related to OpenQASM, some useful OpenQASM examples, and plugins for some text editors.

Language specs

The live language documentation specification.

Examples

An example of OpenQASM 3.0 source code is given below. Several more examples may be found in the examples folder.

/*
 * Repeat-until-success circuit for Rz(theta),
 * cos(theta-pi)=3/5, from Nielsen and Chuang, Chapter 4.
 */
OPENQASM 3;
include "stdgates.inc";

/*
 * Applies identity if out is 01, 10, or 11 and a Z-rotation by
 * theta + pi where cos(theta)=3/5 if out is 00.
 * The 00 outcome occurs with probability 5/8.
 */
def segment qubit[2] anc, qubit psi -> bit[2] {
  bit[2] b;
  reset anc;
  h anc;
  ccx anc[0], anc[1], psi;
  s psi;
  ccx anc[0], anc[1], psi;
  z psi;
  h anc;
  measure anc -> b;
  return b;
}

qubit input;
qubit[2] ancilla;
bit[2] flags = "11";
bit output;

reset input;
h input;

// braces are optional in this case
while(int(flags) != 0) {
  flags = segment ancilla, input;
}
rz(pi - arccos(3 / 5)) input;
h input;
output = measure input;  // should get zero

Citation format

For research papers, we encourage authors to reference.

• [Version 3.0] Andrew W. Cross, Ali Javadi-Abhari, Thomas Alexander, Niel de Beaudrap, Lev S. Bishop, Steven Heidel, Colm A. Ryan, John Smolin, Jay M. Gambetta, Blake R. Johnson "OpenQASM 3: A broader and deeper quantum assembly language" [arxiv:2104.14722].
• [Previous Version: 2.0] Andrew W. Cross, Lev S. Bishop, John A. Smolin, Jay M. Gambetta "Open Quantum Assembly Language" [arXiv:1707.03429].

Governance

The OpenQASM project has a process for accepting changes to the language and making decisions codified in its governance model.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Contributing

If you'd like to help please take a look to our contribution guidelines. This project adheres to a Code of Conduct. By participating, you are expected to uphold this code.

Release Notes

See the section on Release Notes contribution guidelines.

openqasm's Issues

benchmark for shor algorithm

Hello, I wonder that do you have any open source qasm code for shor algorithm, grover algorithm or deutsch algorithm? I'm doing some projects related to qubit allocation so I need more benchmarks to evaluate my ideas. Thank you very much.

Variable identifiers can overlap with hardware qubit identifiers

Per https://github.com/Qiskit/openqasm/blob/master/source/language/types.rst, variable identifiers can begin with a percent sign.

But this means that %0, %1, ... are valid variable identifiers, which seems like it should be disallowed since those are intended to be used for hardware qubits.

cc @ajavadia

`include` statement is missing in `A Open QASM Grammar` of language spec.

include statement is missing in spec/qasm2.rst line 675-683 and spec-human/qasm2.pdf page 21.

Special syntax for lengths?

This page: https://qiskit.github.io/openqasm/language/delays.html#delays-and-other-lengthened-instructions contains a special syntax for lengths that doesn't seem to be fully spec-ed out anywhere (search for "rotary" on that page).

Should all lengths use square brackets? In particular the pulse shapes in the pulse proposal could look like:

gaussian(...)[100dt]

instead of now:

gaussian(100dt, ...)

Dead links in README.md for benchmarking

There are a number of links in the README for benchmarks that no longer go to the respective tutorials, such as the section on the Fourier Transform, Bernstein-Vazirani algorithm and Counterfeit-Coin finding algorithm.

Typo in rotation operator definition

In line 130 of spec/qasm2.tex there should be a \phi instead of \theta, i.e.$R_z(\phi)=\mathrm{exp}(-i\phi Z/2)$ instead of $R_z(\phi)=\mathrm{exp}(-i\theta Z/2)$.

dead link

https://github.com/Qiskit/openqasm/tree/master/benchmarks#fourier-transform
the notebook link

Implicit Timing

Within the circuit timing section https://qiskit.github.io/openqasm/language/delays.html#delays-and-other-lengthened-instructions, there are instructions such as

length start_stretch = s - .5 * lengthof({x %0;})

Within lengthof, it appears {x %0} is meant to be a box. Should it include the type boxas or should it be assumed that if {} are found as an argument for lengthof it is a box type.

Wrong sign on teleportation.qasm when X,Z == [1, 1]

X and Z corrections should be interchanged, otherwise we get a MINUS (-) global phase when the final measurement result is [1, 1]. Proposed fix in #48.

Complex numbers

To support non-discriminated values we probably need a complex type. I started to write this, but then realized how much bikeshedding there would be:

Complex numbers
~~~~~~~~~~~~~~~

Complex numbers may be declared with ``complex[size] name;``, where ``size``
indicates the size of the two floating point numbers used to store the real
and imaginary parts of the complex number. For instance, a ``complex[32]``
represents two single-precision 32-bit floats. Note that some hardware vendors
may not support manipulating these values at run-time.

.. code-block:: none

   // Declare a single-precision complex number (two 32-bit floats)
   complex[32] my_complex = 1/sqrt(2) + 1/sqrt(2)*i;

(Incomplete) list of bikeshedding:

• Is the imaginary number i or j?
• Which functions do we need to add? (re, im, conj, norm)

Classical bits and registers initialization using 0b representation.

in the section "Classical bits and registers initialization" we could add support to use the prefix 0b for binary format, instead of only the String format. Example 0b1001, instead of "1001".

It would allow to be more flexible to introduce the numbers in other bases and transform them in a simple way.

Also this format is common used in other languages like C, Python, Rust, Java ...

Timing types and `s` gate

Timing units dt, ns, µs, ms, s are meant to be reserved types. However, the pi/2 gate is typically denoted s (https://quantum-computing.ibm.com/docs/iqx/operations-glossary#s-gate).

Perhaps the timing types should be capitalized or use sec to avoid this confusion?

Add inverse trigonometric functions to the grammar

QISKit uses inverse trigonometric functions internally and the resulting QASM includes them. See:
https://github.com/lbello/qiskit-sdk-py/commit/8b6ce2b979dd6cb5ab714e6aae70397323d285ee#diff-d975dd8e31d73eac04b5c6d76ebd89fc

They are not explicitly forbidden in the specification, but they are not part of the grammar. Probably just make sense to add them.

Small typo in a example file

It seems that there is a small typo on the first line of the Deutsch Algorithm.
In the first line we have:
\\Implementation of Deutsch algorithm with two qubits for f(x)=x
shouldn't it be:
//Implementation of Deutsch algorithm with two qubits for f(x)=x
i.e. instead of the backslash, a normal slash!?

Arguments cannot be indexed within the body of the gate definition. Why?

Playing with the parser, I noticed that the specification does not allow registers to be indexed in the gate definition. What's the rationale behind that?

Implicit size of types

The specification states that there are no implicit sizes for OpenQASM types: https://qiskit.github.io/openqasm/language/types.html#integers.

However, in some of the examples, an implicit width is assumed:

• https://github.com/Qiskit/openqasm/blob/master/examples/vqe.qasm#L77
• https://github.com/Qiskit/openqasm/blob/master/examples/scqec.qasm#L99
• https://github.com/Qiskit/openqasm/blob/master/examples/qec.qasm#L25

I think a default width would be nice, but either way the specification and examples should match.

Boxing Questions

Suggestions on boxing: https://qiskit.github.io/openqasm/language/delays.html#boxed-expressions.

Rather than boxas/boxto types, use a single box type. A duration would be optional and a name required (as is the case for any type.

box[optional_duration] name {...}.

For instance, a 1 ms box w/ centered CNOT would be:

box[1ms] cx_centered {
     stretch a;
     delay[a] q;
     cx q[0], q[1];
     delay[a] q;
}

Furthermore, I assume a box may only be used within a gate or a subroutine (or implicitly as {} in a lengthof)?

Grammar: add link to ANTLR4

in the section Grammar, add link to ANTLR4 to get more info and tools to generate the parser.

ANTLR: https://www.antlr.org/

Gate-wise conditionals without control flow

The new “conditionals via control flow” of OpenQASM 3.0 are a strict generalisation of “conditionals per gate” of OpenQASM 2.0 in terms of expressivity and reducing code size in many cases. However, there could be merit in supporting both via different language primitives.

I am not an expert in hardware design, but the incorporation of arbitrary control flow across the controller systems seems like it is much more complicated to support than conditionally killing a pulse from an otherwise fixed pulse schedule generated at compile-time. This kind of conditional could still see usefulness once arbitrary control flow is supported.

Suppose we have an error-correcting code where we have parallelised all measurements and then need to apply corrections across many qubits. Assuming the control flow is a global property (i.e. we have a global instruction pointer, making any jump in control flow act as a global barrier), we can only consider the branches for a single conditional correction at a time when using control flow, meaning correcting different qubits must be done in sequence. Whereas with gate-level conditionals, the conditional is handled locally at the pulse generator, so each conditional correction can be suitably handled in parallel.

If it turns out that the intention of any abstract machine for OpenQASM 3.0 is to determine control flow jumps as soon as possible and allow reordering of gates around the actual jump (e.g. gates that appear in code as before the jump but don't affect the branch condition could be executed in parallel with the first few gates from after the jump), then the distinction between the two types of conditional is irrelevant. In that case, just a clarification in the live specification is sufficient.

Add issues and GitHub link to the live doc

I would like to have at the top links to making pull requests, issues, and a link to the GitHub. This is important as when you are the live documentation it is not clear how to edit it or make comments. I will make a short term change to the introduction for this but long term i think a header would be good.

Wrong matrix size in "Built-in gates" section

https://github.com/Qiskit/openqasm/blob/master/source/language/gates.rst refers to the unitary matrix for an n-qubit gate as n \times n. Should be 2^n \times 2^n

Ordering policy of evaluation in classical instructions

There is no description about evaluation order in classical instructions. I believe it is as most of programming languages (such as python)

Parenthesized forms (with ( and )) are necessary for users to control evaluation order.

If assignment is allowed in variable declaration (as shown in many examples), ordering of qubit specifications and variable specifications need to be defined.

Example: int a = sub(a, b, c) q0, q1;

If sub takes two qubits, q0 and q1 may be its arguments. However, q1 can be recognized a declared variable as int.

I guess that qubit specifications should be weakest. A parenthesized form will be necessary if two qubit arguments are taken as int a = (sub(a, b, c) q0, q1);.

Add sections and sub-section to live document nav bar

Again following the webassembly example, the side bar should list all the sub-section heading in the current section, e.g. https://webassembly.github.io/spec/core/valid/types.html

defcal for reset

Currently, we do not support a defcal for reset.

options
add three gates, reset measurement

or
can we get it all under one defcal

Review content and figures

Make sure our content and figures are up to date so we can start evolving the specification.

rewrite readme

We need to clean up readme, dead links, and a bit of motivation etc.

Drop the colon in subroutine and defcals

Instead of:

def xcheck qubit[4]:d, qubit:a -> bit {
def parity(bit[n]:cin) -> bit {
defcal rz(angle[20]:theta) %q {

just drop the colon:

def xcheck qubit[4] d, qubit a -> bit {
def parity(bit[n] cin) -> bit {
defcal rz(angle[20] theta) %q {

Two reasons I strongly suggest this change:

• Parameter definition in a function should match variable declaration statements. Variables are declared with the line qubit a; not qubit:a;.
• Rust, Python, Scala, and other languages use the colon syntax for parameters but in reverse, where the type comes second. This is going to be really confusing for people familiar with any of those languages. For new readers, it would be really hard in a line like def sample(int:uint) to tell which is the type (int) and which is the parameter name (uint)

Declaring multiple types at once

I noticed in the adder.qasm example that multiple qubits can be declared at once (https://github.com/Qiskit/openqasm/blob/master/examples/adder.qasm#L20). I assume this is more generally true that one can do type identifier1[size1], identifier2[size2], ..., identifierN[sizeN]. I think this should be made explicit.

cast from uint to bool

I think cast operation from uint to bool is not clearly defined in the specification. I'm not sure following two cast operations in adder.qasm are valid or not:

uint[4] a_in = 1;  // a = 0001
uint[4] b_in = 15; // b = 1111
...
  if(bool(ain[i])) x a[i];
  if(bool(bin[i])) x b[i]; 

(BTW, variable names (ain and bin should be a_in and b_in).)

I guess that they are

  if((bit[4](a_in))[i]) x a[i];
  if((bit[4](b_in))[i]) x b[i];

or does uint[4] a_in allow bit access with a_in[i] (as creg)?

Method for multiple gates of same type

Imagine I want to be able to calibrate two definitions of CX (fast or slow). Currently, it is not clear how this should be done as cx in the defcal needs to match cx in gate.

defcal cx %q0 %q1 { ... }

We need to make this clearer that a user should do the following: define two calibrations but update the library of gates with the second defined in terms of the first it is here that they provide some extra information for the compiler to know when and how to use the second.

gate cx_2 qargs { cx qargs }

defcal cx %q0 %q1 { ... } defcal cx_2 %q0 %q1 { ... }

This needs some changes to get that a user can build gates up from the matrix definitions and also associate them with the same matrix but provide a different definition for the gate.

definition of ^ operator

A subsection Classical bits and registers describes as

Classical registers and bits support bitwise operators and the corresponding assignment operators between registers of the same size: and &, or |, xor ^.

and a subsection Integers describes as

Integer types support addition +, subtraction -, multiplication *, and integer division /; the corresponding assignments +=, -=, *=, and /=; as well as increment ++ and decrement --.

In a surface code in examples, ^ is used as "power" operation for integers, I guess.

const d = 3;         // code distance
const m = 10;        // number of syndrome measurement cycles
const shots = 1000;  // number of samples
const n = d^2;       // number of code qubits

If operator is like Python, ^ is XOR and ** is POWER.

Remove text -> rst building files

Since going forward all files should be rst i think we should remove all latex files.

These include

.bib
.txt

Enhance the pipeline for creating new tikz images and export them to SVG

PR #98 introduces utilities for easing the conversion from tikz images to SVG. Enhance those tools to allow batch processing and end-to-end transformation of tikz files.

Declaring multiple types at once

I noticed in the adder.qasm example that multiple qubits can be declared at once (https://github.com/Qiskit/openqasm/blob/master/examples/adder.qasm#L20). I assume this is more generally true that one can do type identifier1[size1], identifier2[size2], ..., identifierN[sizeN]. I think this should be made explicit.

Benchmark Generators using Depreciated Code

The benchmark generation files are using outdated code. Notable examples include QuantumProgram and two_qubit_kak.

Benchmarks are not working on version 0.6.1

Due to the changes in 0.6.1, the benchmarks don't work any more,

Happy to take a look at it btw.

create a tag for QASM 2.0

Hi I'm wondering if there could be a tag for QASM 2.0, which makes it easier to find specifications and examples for QASM 2.0?

Bests

Update links in README

The paths in the Readme lead to dead links. Please update.

https://github.com/IBMQuantum/QASM/tree/master/spec ->
https://github.com/IBM/qiskit-openqasm/tree/master/spec

https://github.com/IBMQuantum/QASM/tree/master/examples ->
https://github.com/IBM/qiskit-openqasm/tree/master/examples

Is the CU1 gate in openqasm correct?

Hi,

in page 11 of openqasm specification:

a is used for control the rotation of b, so a should not be changed.

However, in the implementation, a is updated in the first statement.

gate cu1(lambda) a,b
{

u1(lambda/2) a;
cx a,b;
u1(-lambda/2) b;

        Thanks

Peng

Missing '#' in the include statement

In the language specification the include statement is prefixed with #:

// First non-comment is a version string
OPENQASM 3.0;

#include "stdgates.qasm";

// Rest of QASM program

In all examples and in the grammar this # is missing.

Algorithms by the community

Dear IBM quantum team,

A zip file with quantum circuits from the IBM quantum experience community is attached. It would be great if some circuits can be merged with examples.

Thanks, Bram (user sensor1)
qasm_circuits.zip

builtin math functions

OpenQASM paper defines builtin math functions: sin, cos, tan, exp, ln, and sqrt.
But an example (rus.qasm) and README uses arccos.

I guess that OpenQASM3.0 extends builtin math functions and provide trigonometric-functions (and others). https://numpy.org/doc/stable/reference/routines.math.html#trigonometric-functions

cRz and cU1 gates not completely equivalent?

Hello! I am new to the Qiskit Github page but I have been working on an undergraduate research project utilizing openQASM for the past year. During this time I have come across a couple of bugs/inconsistencies that I hope to revisit and share on this page. Disclaimer: I am still new to quantum computing and mostly self-taught, so I apologize in advance for any errors/misunderstandings. I have developed a real passion for the subject and I'm looking forward to getting involved more in the community!

Problem:

The cRz and cU1 gates are listed as equivalent in the gates glossary but seem to provide different results when applied to an initial superposition of H gates. There seems to be an extra overall phase factor involved that is not referenced in the definitions of the gates.

Steps to Reproduce the Problem:

Examples of each gate:

OPENQASM 2.0;
include "qelib1.inc";

qreg q[3];
creg c[3];

h q[0];
h q[1];
h q[2];
crz(pi/2) q[0],q[2];

OPENQASM 2.0;
include "qelib1.inc";

qreg q[3];
creg c[3];

h q[0];
h q[1];
h q[2];
cu1(pi/2) q[0],q[2];

Comments:

Are these differences in phase normal? If so, I would suggest noting this in the glossary because as a beginner I found it a little confusing. Alternatively, if I did something out of the ordinary or do not have a complete understanding of these gates let me know. I'm excited to contribute and continue learning!

"inc" files allowed in "include"

Based on the examples, files with either the qasm or inc specifier are allowed in include, however only .qasm is included in the live specification.

Add section on pulse-level control instructions

The section on pulses states that a "future document will define a textualized representation of one such grammar, OpenPulse". This issue tracks the definition of that representation.

I have had some brief offline discussions about this with Blake and Lauren. It would be good to open up the discussion here to help explore what this textualized representation could look like.

Add table of contents to live document

Landing page for live document should be something like: https://webassembly.github.io/spec/core/

to support data section in qasm to run the same circuits multiple times with different input data

I expect that with the same circuits, I can run it multiple times with different input data. In this case, I don't need to recompile the circuits multiple times. Every time when I want to run on new data, I just need to update the data section without updating other parts.
For example, in this qasm below, I had one operation "u3(data:input_magic1,0,pi) q1[0]" and a data section with foreach. So if it will execute all circuits for every different input_magic1, it will be very great.

OPENQASM 2.0;\ninclude "qelib1.inc";\nqreg q0[2];\nqreg q1[2];\ncreg c0[2];\ncreg c1[2];\nmeasure q1[1] -> c1[1];\nu3(data:input_magic1,0,pi) q1[0];\nmeasure q1[0] -> c1[0];\nu3(pi,0,pi) q0[1];\nmeasure q0[1] -> c0[1];\nu2(localinputvar1,0) q0[0];\nmeasure q0[0] -> c0[0];
section data: foreach (input_magic1: pi; input_magic1: 0.1; input_magic1: 0.2, input_magic1: 0.3)

Images are missing from live doc

Circuits and stretch diagrams are missing from the live doc.

Fix the contribution in the live documentation

can we make this ^1 or * so it's simpler to read.

extend Aliasing registers examples

In the Types and Casting > Register concatenation and slicing, could be interesting add extra examples showing the possibility to concatenate two alias, and how we can work the a negative range to get the last elements too.

qubit[10] two;
// new code to add
let begin_three = two[0:2];
// example using negative ranges to take the last 3 elements
let last_three = two[-4:-1];
// example how concatenate two alias in another one
let both = begin_three || last_three;