Source code for mimiqcircuits.decomposition.basis.canonical

#
# 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.
#
"""Canonical decomposition basis targeting GateU and GateCX."""

from __future__ import annotations

from dataclasses import dataclass
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, filled on first use. Shared by all
# instances: the canonical gate set does not depend on the basis's state.
_TERMINAL_BY_TYPE: dict[type, bool] = {}


[docs] @dataclass(frozen=True, init=False) class CanonicalBasis(DecompositionBasis): """Decomposition basis targeting ``GateU`` and ``GateCX``. Every gate is rewritten into ``GateU`` (an arbitrary single-qubit gate) and ``GateCX``, with the built-in decomposition of each operation (:class:`CanonicalRewrite`). The non-unitary primitives are kept as they are; :meth:`isterminal` lists them. This is the default basis of :func:`decompose`. 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(GateH(), 0) 1-qubit circuit with 1 instruction: └── H @ q[0] <BLANKLINE> >>> c.push(GateSWAP(), 0, 1) 2-qubit circuit with 2 instructions: ├── H @ q[0] └── SWAP @ q[0:1] <BLANKLINE> >>> c.push(Measure(), 0, 0) 2-qubit, 1-bit circuit with 3 instructions: ├── H @ q[0] ├── SWAP @ q[0:1] └── M @ q[0], c[0] <BLANKLINE> >>> # gates become GateU and GateCX; the measurement is kept >>> decompose(c, CanonicalBasis()) 2-qubit, 1-bit circuit with 5 instructions: ├── U((1/2)*pi, 0, pi, 0.0) @ q[0] ├── CX @ q[0], q[1] ├── CX @ q[1], q[0] ├── CX @ q[0], q[1] └── M @ q[0], c[0] <BLANKLINE> """ 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 canonical basis. The terminal operations are ``GateU`` and ``GateCX``; ``Measure``; ``Reset``, ``ResetX`` and ``ResetY``; ``Loss``, ``Reload``, ``Check`` and ``MeasureCheck``; ``Barrier`` and ``Delay``; classical operations and annotations; noise channels and ``ReadoutErr``; ``ExpectationValue``, ``Amplitude``, ``SchmidtRank``, ``VonNeumannEntropy`` and ``BondDim``; and the z-register operations ``Add``, ``Multiply`` and ``Pow``. An ``IfStatement`` or ``WhileStatement`` is terminal when its body is. Args: op: The operation to check. Returns: ``True`` if ``op`` is terminal. """ # Terminality depends only on the operation's type, except for the # conditionals, which defer to their body. Caching by type 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.classical.abstract_classical import AbstractClassical from mimiqcircuits.complex import Add, Multiply, Pow from mimiqcircuits.operations.amplitude import Amplitude from mimiqcircuits.operations.annotations import AbstractAnnotation from mimiqcircuits.operations.barrier import Barrier from mimiqcircuits.operations.entanglement import ( BondDim, SchmidtRank, VonNeumannEntropy, ) from mimiqcircuits.operations.expectationvalue import ExpectationValue from mimiqcircuits.operations.gates.delay import Delay from mimiqcircuits.operations.gates.standard.cpauli import GateCX from mimiqcircuits.operations.gates.standard.u import GateU from mimiqcircuits.operations.ifstatement import IfStatement from mimiqcircuits.operations.krauschannel import krauschannel from mimiqcircuits.operations.losschannel import ( Check, Loss, MeasureCheck, Reload, ) from mimiqcircuits.operations.measure import Measure from mimiqcircuits.operations.readouterr import ReadoutErr from mimiqcircuits.operations.reset import Reset from mimiqcircuits.operations.whilestatement import WhileStatement # IfStatement, WhileStatement: terminal if the inner operation is if isinstance(op, (IfStatement, WhileStatement)): return self.isterminal(op.get_operation()) known = isinstance( op, ( # Core gates GateU, GateCX, # Measurement, reset and Loss operations Measure, Reset, Loss, Reload, Check, MeasureCheck, # Control flow Barrier, # Classical operations AbstractClassical, # Annotations AbstractAnnotation, # Noise channels krauschannel, ReadoutErr, # Expectation values and entanglement measures ExpectationValue, Amplitude, SchmidtRank, VonNeumannEntropy, BondDim, # Z-register operations Add, Multiply, Pow, # Delay (timing information) Delay, ), ) _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 with its built-in decomposition. 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 one decomposition step. Raises: DecompositionError: If ``op`` has no built-in decomposition. """ from mimiqcircuits.decomposition.rules import CanonicalRewrite rule = CanonicalRewrite() if rule.matches(op): return rule.decompose_step(op, qubits, bits, zvars) raise DecompositionError( f"Operation {op.name} is not supported by CanonicalBasis " "and cannot be decomposed." )
[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__ = ["CanonicalBasis"]