OpenQASM

The QDK provides interoperability with OpenQASM programs built upon the core QDK compiler infrastructure.

Editing OpenQASM in VS Code

This extension provides both a rich OpenQASM development environment and Azure Quantum integration. Features of the extension include:

• Syntax highlighting and basic syntax features (e.g. brace matching)
• Error checking in OpenQASM source files
• Breakpoint debugging and script execution for OpenQASM source files and debugging with live circuit generation
• Integration with Azure Quantum for quantum job submission
• Completions
• Code lens (run, run shots with histogram, resource estimate, debug, generate circuit diagram)

Samples

Several common quantum algorithms are provided as samples in the completion list. After creating a new .qasm document, type sample to filter the completion list to them, and tab-complete to insert the sample.

Running and Debugging OpenQASM Code

After developing a OpenQASM quantum algorithm, you have the option to run your code. This can be done either locally on a quantum simulator, for free; or via submission to Azure Quantum, for a price.

Running Locally on a Quantum Simulator

In VS Code, access the Command Palette (ctrl/cmd+shift+P). Run the command "Debug: Run File". This will run the file on your computer, using a quantum simulator. (You can also use the Play icon and drop-down in the top-right of the editor. See the screenshot in Debugging Locally section following. Or simply press Ctrl-F5). Note that this command only appears if you currently have a ".qasm" file selected and open. You can see the output from the program in the VS Code Debug Console output pane.

Debugging Locally

The extension includes a debugger. The debugger can handle typical breakpoint-style debugging (step into, over, out of, etc) as well as render program state.

To start the debugger, click the debug icon in the top right of VS Code. Select "Debug File".

Alternatively, you can click on the Debug code lens at the top of the OpenQASM program.

From here, the state of the program should be visible in the debugger pane on the left, and breakpoints will work. You can see the qubit state as well as local variable state in the "Variables" section:

Running via Azure Quantum

See this wiki article for instructions on submitting to Azure.

Python

Prequisites: Follow Steps 1-3 from the Tutorial: Q# in Jupyter Notebooks and VS Code

4. Run OpenQASM in a Python notebook cell

import qsharp
from qsharp import BitFlipNoise, TargetProfile
from qsharp.openqasm import run

qsharp.init(target_profile=TargetProfile.Base)

result = run(
    """
    include "stdgates.inc";
    qubit[2] q;
    reset q;
    h q[0];
    cx q[0], q[1];
    bit c = measure q;
    """,
    shots=10,
    noise=BitFlipNoise(0.1),
)
print(results)

5. Use OpenQASM program from Python

First we'll import the OpenQASM program into the Python environment leveraging the import_qasm call and giving the program a name which we can reference (the default is program):

from qsharp import init, TargetProfile
from qsharp.openqasm import import_openqasm

qsharp.init(target_profile=TargetProfile.Base)

import_qasm(
    """
    include "stdgates.inc";
    qubit[2] q;
    reset q;
    h q[0];
    cx q[0], q[1];
    bit c = measure q;
    """,
    name="bell",
)

With the OpenQASM program loaded into a callable name bell, we can now import it via the QDK's Python bindings:

from qsharp.code import bell
bell()

Additionally, since it is defined in the session, we can run it directly from a Q# cell:

%%qsharp
bell()

This also unlocks all of the other QDK package functionality. Like noisy simulation:

from qsharp.code import bell
from qsharp_widgets import Histogram

# run it as called from Q#
Histogram(qsharp.run("bell()", shots=1000, noise=qsharp.DepolarizingNoise(0.01)))
# or invoke the Python callable directly
Histogram(qsharp.run(bell, shots=1000, noise=qsharp.DepolarizingNoise(0.01)))

Circuit rendering:

from qsharp.code import bell
qsharp.circuit(bell)

Circuit widget rendering:

from qsharp.code import bell
from qsharp_widgets import Circuit

Circuit(qsharp.circuit(bell))

Code generation:

from qsharp.code import bell

print(qsharp.compile(bell))

We can also define input for the compiled OpenQASM code so that we can parameterize input:

import_qasm(
    """
    include "stdgates.inc";
    input float theta;
    qubit[2] q;
    rx(theta) q[0];
    rx(-theta) q[1];
    bit[2] c;
    c = measure q;
    """,
    name="parameterized_circuit",
)

from qsharp.code import parameterized_circuit

bound_compilation = qsharp.compile(parameterized_circuit, 1.57)
print(bound_compilation)

We can also compile the OpenQASM directly without the QDK's Python bindings:

from qsharp import TargetProfile
from qsharp.openqasm import compile

compilation = compile(
    """
    include "stdgates.inc";
    input float theta;
    qubit[2] q;
    rx(theta) q[0];
    rx(-theta) q[1];
    bit[2] c;
    c = measure q;
    """,
    1.57,
    target_profile=TargetProfile.Base,
) 

print(compilation)

Known limitations and issues

This is an early release of OpenQASM support in the QDK and its capabilities will evolve over time.

Known limitations or constraints

• Compiling programs with input variables requires the Python API

Unsupported or unimplemented OpenQASM language features

• importing files other than "stdgates.inc"
• angle input variables must be defined as float
• Ranges with open start or end: [:1:5], [0:1:]
• Array references (passing arrays as parameters)
  • Qubit[n] and bit[n] are supported as parameters
• Extern functions
• Built-in functions (sin, cos, etc.)
• sizeof and durationof calls
• Hardware qubit ids
• Duration type value, this includes supplying durations on gate and box instructions.
• Stretch type values
• break keyword
• continue keyword
• Alias declarations
• Calibration statements
• Calibration grammar statements
• Defcal statements
• Delay statements

Issues

Tracked in OpenQASM Active Issues #2451