mimiqcircuits.qasm

Import and export of OpenQASM 2.0 circuits.

load() and loads() read OpenQASM 2.0 from a file or a string into a Circuit. dump() and dumps() write a circuit as OpenQASM 2.0. Errors raised while reading or writing derive from QASMError, except for an operation with no OpenQASM 2.0 equivalent, which makes the writers raise DecompositionError.

Examples

>>> from mimiqcircuits import *
>>> from mimiqcircuits import qasm
>>> c = qasm.loads('''
... OPENQASM 2.0;
... include "qelib1.inc";
... qreg q[1];
... creg c[1];
... h q[0];
... measure q[0] -> c[0];
... ''')
>>> c
1-qubit, 1-bit circuit with 2 instructions:
├── H @ q[0]
└── M @ q[0], c[0]
exception QASMError[source]

Bases: Exception

Base class for the errors raised when reading or writing OpenQASM.

exception ParseError(message, token=None, parser_state=None)[source]

Bases: QASMError

Raised when the OpenQASM source is not valid syntax, uses an unsupported version, or includes a file that cannot be found.

exception QASMSerializationError[source]

Bases: QASMError

Raised when a circuit cannot be written as OpenQASM 2.0.

exception QASMArgumentError[source]

Bases: QASMError

Raised when the parsed input is not a program or declares an unsupported opaque gate.

exception UndefinedGateError[source]

Bases: QASMError

Raised when the OpenQASM source calls a gate that is not declared.

exception DuplicateRegisterError[source]

Bases: QASMError

Raised when the OpenQASM source declares the same register name twice.

load(filename, includedirs=None)[source]

Read an OpenQASM 2.0 program from a file.

Same as loads() on the file’s content, with the file’s own directory added to the front of includedirs.

Parameters:
  • filename (str) – The path of the file.

  • includedirs (List[str]) – Extra directories to search for included files. Defaults to None.

Returns:

The circuit described by the program.

Return type:

Circuit

Raises:
  • FileNotFoundError – If the file does not exist.

  • ParseError – If the source is not valid OpenQASM 2.0 syntax or an included file is not found.

  • QASMError – If the program cannot be interpreted.

Examples

Write a circuit to a file with dump() and read it back.

>>> from mimiqcircuits import *
>>> from mimiqcircuits import qasm
>>> import os, tempfile
>>> c = Circuit()
>>> c.push(GateH(), 0)
1-qubit circuit with 1 instruction:
└── H @ q[0]

>>> path = os.path.join(tempfile.mkdtemp(), "circuit.qasm")
>>> qasm.dump(c, path)
>>> qasm.load(path)
1-qubit circuit with 1 instruction:
└── H @ q[0]
loads(s, includedirs=None)[source]

Read an OpenQASM 2.0 program from a string.

Quantum registers are laid out one after the other on the circuit’s qubits in order of declaration, and classical registers likewise on its bits. include files are looked up in the current directory, then in the directory of files bundled with the package (which provides qelib1.inc), then in includedirs.

Parameters:
  • s (str) – The OpenQASM 2.0 source.

  • includedirs (List[str]) – Extra directories to search for included files. Defaults to None.

Returns:

The circuit described by the program.

Return type:

Circuit

Raises:
  • ParseError – If the source is not valid OpenQASM 2.0 syntax or an included file is not found.

  • QASMError – If the program cannot be interpreted, for example because it uses an undeclared gate or register (see the subclasses in mimiqcircuits.qasm).

Examples

>>> from mimiqcircuits import *
>>> from mimiqcircuits import qasm

A Bell-state program using gates from qelib1.inc.

>>> src = '''
... OPENQASM 2.0;
... include "qelib1.inc";
... qreg q[2];
... creg c[2];
... h q[0];
... cx q[0],q[1];
... measure q -> c;
... '''
>>> qasm.loads(src)
2-qubit, 2-bit circuit with 4 instructions:
├── H @ q[0]
├── CX @ q[0], q[1]
├── M @ q[0], c[0]
└── M @ q[1], c[1]
dump(c, filename, decompose_wrappers=False, sanitize_names=True)[source]

Write a circuit as an OpenQASM 2.0 program to a file.

The file is overwritten, unless serialization fails. See dumps() for how the circuit is written; load() reads the file back.

Parameters:
  • c (Circuit) – The circuit to write.

  • filename (str) – The path of the file.

  • decompose_wrappers (bool) – Not used.

  • sanitize_names (bool) – If True, rewrite gate declaration names into valid OpenQASM identifiers. Defaults to True.

Raises:
dumps(c, decompose_wrappers=False, sanitize_names=True)[source]

Write a circuit as an OpenQASM 2.0 program.

Operations that OpenQASM 2.0 cannot express directly are decomposed into qelib1.inc gates, and gate declarations (GateDecl) become gate definitions. All qubits go in one register q and all bits in one register c.

Parameters:
  • c (Circuit) – The circuit to write.

  • decompose_wrappers (bool) – Not used.

  • sanitize_names (bool) – If True, rewrite gate declaration names into valid OpenQASM identifiers. If False, an invalid name raises QASMSerializationError. Defaults to True.

Returns:

The OpenQASM 2.0 source.

Return type:

str

Raises:
  • DecompositionError – If an operation cannot be decomposed into the OpenQASM 2.0 basis, such as a noise channel or a classical or z-variable operation.

  • QASMSerializationError – If a name or an IfStatement condition cannot be expressed in OpenQASM 2.0.

Examples

>>> from mimiqcircuits import *
>>> from mimiqcircuits import qasm
>>> c = Circuit()
>>> c.push(GateH(), 0)
1-qubit circuit with 1 instruction:
└── H @ q[0]

>>> c.push(GateCX(), 0, 1)
2-qubit circuit with 2 instructions:
├── H @ q[0]
└── CX @ q[0], q[1]

>>> c.push(Measure(), range(2), range(2))
2-qubit, 2-bit circuit with 4 instructions:
├── H @ q[0]
├── CX @ q[0], q[1]
├── M @ q[0], c[0]
└── M @ q[1], c[1]

>>> print(qasm.dumps(c))
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q[0] -> c[0];
measure q[1] -> c[1];

Modules