#
# Copyright © 2022-2024 University of Strasbourg. All Rights Reserved.
# Copyright © 2023-2025 QPerfect. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""OpenQASM 2.0 decomposition basis."""
from __future__ import annotations
from dataclasses import dataclass
from functools import lru_cache
from typing import TYPE_CHECKING, Sequence
from mimiqcircuits.decomposition.abstract import (
DecompositionBasis,
DecompositionError,
_AncillaOptions,
)
if TYPE_CHECKING:
from mimiqcircuits.circuit import Circuit
from mimiqcircuits.operations.operation import Operation
# Terminality per operation type, for the types where the type alone decides
# it. Filled on first use and shared by all instances.
_TERMINAL_BY_TYPE: dict[type, bool] = {}
@lru_cache(maxsize=None)
def _qasm_terminal_types():
from mimiqcircuits.operations.barrier import Barrier
from mimiqcircuits.operations.gates.standard.chadamard import GateCH
from mimiqcircuits.operations.gates.standard.cnx import GateC3X, GateCCX
from mimiqcircuits.operations.gates.standard.cpauli import GateCX, GateCY, GateCZ
from mimiqcircuits.operations.gates.standard.crotations import (
GateCRX,
GateCRY,
GateCRZ,
)
from mimiqcircuits.operations.gates.standard.cswap import GateCSWAP
from mimiqcircuits.operations.gates.standard.deprecated import (
GateU1,
GateU2,
GateU3,
)
from mimiqcircuits.operations.gates.standard.hadamard import GateH
from mimiqcircuits.operations.gates.standard.id import GateID
from mimiqcircuits.operations.gates.standard.interactions import GateRXX, GateRZZ
from mimiqcircuits.operations.gates.standard.pauli import GateX, GateY, GateZ
from mimiqcircuits.operations.gates.standard.rotations import GateRX, GateRY, GateRZ
from mimiqcircuits.operations.gates.standard.s import GateS, GateSDG
from mimiqcircuits.operations.gates.standard.swap import GateSWAP
from mimiqcircuits.operations.gates.standard.t import GateT, GateTDG
from mimiqcircuits.operations.gates.standard.u import GateU
return (
# OpenQASM 2.0 built-ins
GateU,
GateCX,
# qelib1.inc, single qubit
GateU3,
GateU2,
GateU1,
GateID,
GateX,
GateY,
GateZ,
GateH,
GateS,
GateSDG,
GateT,
GateTDG,
GateRX,
GateRY,
GateRZ,
# qelib1.inc, two qubits
GateCY,
GateCZ,
GateCH,
GateCRX,
GateCRY,
GateCRZ,
GateSWAP,
GateRXX,
GateRZZ,
# qelib1.inc, three and four qubits
GateCCX,
GateCSWAP,
GateC3X,
Barrier,
)
[docs]
@dataclass(frozen=True, init=False)
class QASMBasis(DecompositionBasis):
"""Decomposition basis targeting the OpenQASM 2.0 gate library.
The terminal gates are the OpenQASM 2.0 built-ins and the gates of the
``qelib1.inc`` include file that have a direct MIMIQ counterpart, so a
decomposed circuit can be written as OpenQASM 2.0 and read back by any
parser that ships the standard ``qelib1.inc``.
The terminal operations are:
- the OpenQASM 2.0 built-ins ``GateU`` and ``GateCX``;
- the single-qubit gates of ``qelib1.inc``: ``GateU3``, ``GateU2``,
``GateU1``, ``GateID``, ``GateX``, ``GateY``, ``GateZ``, ``GateH``,
``GateS``, ``GateSDG``, ``GateT``, ``GateTDG``, ``GateRX``, ``GateRY``
and ``GateRZ``;
- the two-qubit gates of ``qelib1.inc``: ``GateCY``, ``GateCZ``,
``GateCH``, ``GateCRX``, ``GateCRY``, ``GateCRZ``, ``GateSWAP``,
``GateRXX`` and ``GateRZZ``;
- the three- and four-qubit gates of ``qelib1.inc``: ``GateCCX``,
``GateCSWAP`` and ``GateC3X``;
- ``Measure``, ``Reset`` and ``Barrier``, but not the X and Y variants of
``Measure`` and ``Reset``;
- annotations, such as :class:`AncillaAlloc`, which the OpenQASM writer
drops;
- an ``IfStatement`` whose body is terminal;
- a ``GateCall`` whose declaration holds only terminal operations.
Every other operation is decomposed through :class:`CanonicalRewrite`.
Operations that OpenQASM 2.0 cannot express and that have no decomposition
into the gates above (noise channels, classical operations, Z-register
operations, ...) raise :class:`DecompositionError`.
``MeasureReset`` decomposes into ``Measure`` followed by ``Reset``. This
leaves the same state and bit as its canonical decomposition, a
measurement and an ``X`` conditioned on its outcome, and unlike that
conditional it can be written for a circuit of any number of bits.
OpenQASM 2.0 has no loops, so ``WhileStatement`` raises
:class:`DecompositionError`.
Args:
borrow: Let decompositions borrow qubits of the circuit that the
operation does not act on. A borrowed qubit can be in any state;
the decomposition leaves it as it found it.
max_ancillas: Let decompositions add up to this many clean ancillas,
numbered after the qubits of the circuit and marked with
:class:`AncillaAlloc` and :class:`AncillaFree`. Ancillas freed by
one operation are reused by the next.
allow_measurement: With ``max_ancillas``, let decompositions undo
steps by measuring an ancilla into one extra bit, numbered after
the bits of the circuit. A circuit without bits is refused with a
``ValueError``.
The three ancilla options are off by default, and only change how
multi-controlled X gates are decomposed. Circuits whose width is unknown,
such as a lone operation, get no ancillas.
Examples:
>>> from mimiqcircuits import *
>>> c = Circuit()
>>> c.push(GateCCX(), 0, 1, 2)
3-qubit circuit with 1 instruction:
└── C₂X @ q[0:1], q[2]
<BLANKLINE>
>>> c.push(GateSX(), 0)
3-qubit circuit with 2 instructions:
├── C₂X @ q[0:1], q[2]
└── SX @ q[0]
<BLANKLINE>
>>> c.push(MeasureReset(), 0, 0)
3-qubit, 1-bit circuit with 3 instructions:
├── C₂X @ q[0:1], q[2]
├── SX @ q[0]
└── MR @ q[0], c[0]
<BLANKLINE>
>>> # CCX is in qelib1.inc and is kept; SX is not and is rewritten;
>>> # MeasureReset becomes a measurement and a reset
>>> decompose(c, QASMBasis())
3-qubit, 1-bit circuit with 7 instructions:
├── C₂X @ q[0:1], q[2]
├── S† @ q[0]
├── H @ q[0]
├── S† @ q[0]
├── U(0, 0, 0, (1/4)*pi) @ q[0]
├── M @ q[0], c[0]
└── Reset @ q[0]
<BLANKLINE>
See Also:
:class:`CanonicalBasis`, :class:`CliffordTBasis`, :class:`StimBasis`
"""
ancillas: _AncillaOptions
def __init__(
self,
borrow: bool = False,
max_ancillas: int = 0,
allow_measurement: bool = False,
):
object.__setattr__(
self,
"ancillas",
_AncillaOptions(
borrow=borrow,
max_ancillas=max_ancillas,
allow_measurement=allow_measurement,
),
)
def _ancillaoptions(self):
return self.ancillas
[docs]
def isterminal(self, op: Operation) -> bool:
"""Check whether an operation is terminal in the OpenQASM 2.0 basis.
Args:
op: The operation to check.
Returns:
``True`` if ``op`` is one of the terminal operations listed in the
class description.
"""
# Terminality depends only on the operation's type, except for gate
# calls and conditionals, which are decided by what they wrap. Caching
# the type-only answers skips the chain of isinstance checks, each of
# which goes through ABCMeta.
t = type(op)
known = _TERMINAL_BY_TYPE.get(t)
if known is not None:
return known
from mimiqcircuits.gatedecl import GateCall
from mimiqcircuits.operations.annotations import AbstractAnnotation
from mimiqcircuits.operations.ifstatement import IfStatement
from mimiqcircuits.operations.measure import Measure
from mimiqcircuits.operations.reset import Reset
# Measure and Reset are matched exactly: their X/Y-basis variants are
# not part of OpenQASM 2.0 and must be decomposed.
if type(op) in (Measure, Reset):
return True
# Annotations carry no gate. The OpenQASM writer drops them.
if isinstance(op, AbstractAnnotation):
return True
if isinstance(op, GateCall):
return all(
self.isterminal(inst.get_operation()) for inst in op.decl.circuit
)
if isinstance(op, IfStatement):
inner_op = op.get_operation()
return inner_op is not None and self.isterminal(inner_op)
known = isinstance(op, _qasm_terminal_types())
_TERMINAL_BY_TYPE[t] = known
return known
[docs]
def decompose(
self,
op: Operation,
qubits: Sequence[int],
bits: Sequence[int],
zvars: Sequence[int],
) -> Circuit:
"""Rewrite a non-terminal operation one step toward OpenQASM 2.0.
``MeasureReset`` becomes ``Measure`` and ``Reset``; every other
operation goes through :class:`CanonicalRewrite`.
Args:
op: The operation to rewrite.
qubits: Qubit indices the operation acts on.
bits: Classical bit indices the operation acts on.
zvars: Z-variable indices the operation acts on.
Returns:
A new :class:`~mimiqcircuits.Circuit` with the rewrite.
Raises:
DecompositionError: If ``op`` is a ``WhileStatement`` or has no
built-in decomposition.
"""
from mimiqcircuits.circuit import Circuit
from mimiqcircuits.operations.measure import Measure
from mimiqcircuits.operations.measurereset import MeasureReset
from mimiqcircuits.operations.reset import Reset
from mimiqcircuits.operations.whilestatement import WhileStatement
from mimiqcircuits.decomposition.rules import CanonicalRewrite
if type(op) is MeasureReset:
c = Circuit()
c.push(Measure(), qubits[0], bits[0])
c.push(Reset(), qubits[0])
return c
if isinstance(op, WhileStatement):
raise DecompositionError(
"WhileStatement cannot be decomposed into the OpenQASM 2.0 basis, "
"which has no loops."
)
rule = CanonicalRewrite()
if rule.matches(op):
return rule.decompose_step(op, qubits, bits, zvars)
raise DecompositionError(
f"Operation {op.name} cannot be decomposed into the OpenQASM 2.0 basis."
)
[docs]
def decompose_ctx(
self,
op: Operation,
qubits: Sequence[int],
bits: Sequence[int],
zvars: Sequence[int],
ctx,
) -> Circuit:
"""Decompose with a context, which only some operations use.
Operations without a rule that uses the context go to
:meth:`decompose`, so an override of it keeps being called.
"""
from mimiqcircuits.decomposition.abstract import _uses_context
from mimiqcircuits.decomposition.rules import CanonicalRewrite
rule = CanonicalRewrite()
if _uses_context(op) and rule.matches(op):
return rule.decompose_step_ctx(op, qubits, bits, zvars, ctx)
return self.decompose(op, qubits, bits, zvars)
__all__ = ["QASMBasis"]