Source code for mimiqcircuits.decomposition.basis.flattened

#
# 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.
#
"""Flattened decomposition basis."""

from __future__ import annotations

from typing import TYPE_CHECKING, Sequence

from mimiqcircuits.decomposition.abstract import DecompositionBasis, DecompositionError

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] = {}


[docs] class FlattenedBasis(DecompositionBasis): """Decomposition basis that expands containers and keeps every other operation. ``GateCall``, ``Block`` and ``BlockCall``, and the ``Inverse`` of a ``GateCall``, are expanded with :class:`FlattenContainers` until none is left, at any depth. An ``IfStatement`` whose body is a container becomes one conditional instruction per instruction of the body. Gates are not decomposed, and that includes a ``GateCall`` wrapped in ``Control``, ``Power``, ``Parallel`` or ``Repeat``, which is kept. Examples: >>> from mimiqcircuits import * >>> # a declared gate that holds a Bell-pair preparation >>> bell = GateDecl("bell", (), Circuit().push(GateH(), 0).push(GateCX(), 0, 1)) >>> c = Circuit() >>> c.push(bell(), 0, 1) 2-qubit circuit with 1 instruction: └── bell() @ q[0:1] <BLANKLINE> >>> c.push(GateSWAP(), 0, 1) 2-qubit circuit with 2 instructions: ├── bell() @ q[0:1] └── SWAP @ q[0:1] <BLANKLINE> >>> # the call is expanded; SWAP is a gate and is kept >>> decompose(c, FlattenedBasis()) 2-qubit circuit with 3 instructions: ├── H @ q[0] ├── CX @ q[0], q[1] └── SWAP @ q[0:1] <BLANKLINE> """
[docs] def isterminal(self, op: Operation) -> bool: """Check whether an operation is kept, that is not a container. Args: op: The operation to check. Returns: ``False`` for the containers listed in the class description and for an ``IfStatement`` whose body is one, ``True`` otherwise. """ t = type(op) known = _TERMINAL_BY_TYPE.get(t) if known is not None: return known from mimiqcircuits.blockdecl import BlockCall from mimiqcircuits.gatedecl import GateCall from mimiqcircuits.operations.block import Block from mimiqcircuits.operations.ifstatement import IfStatement from mimiqcircuits.operations.inverse import Inverse # An inverse is decided by what it wraps, so it is never cached. if isinstance(op, Inverse): return not isinstance(op.op, (GateCall, Block, BlockCall)) # A conditional container is flattened into conditional instructions; # it is decided by its body, so it is never cached either. if isinstance(op, IfStatement): return self.isterminal(op.get_operation()) known = not isinstance(op, (GateCall, Block, BlockCall)) _TERMINAL_BY_TYPE[t] = known return known
[docs] def decompose( self, op: Operation, qubits: Sequence[int], bits: Sequence[int], zvars: Sequence[int], ) -> Circuit: """Expand one level of a container. Args: op: The container, or the ``IfStatement`` of one, to expand. 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 contents of ``op``, each made conditional if ``op`` is an ``IfStatement``. Raises: DecompositionError: If ``op`` is not a container. """ from mimiqcircuits.operations.ifstatement import IfStatement from mimiqcircuits.decomposition.rules import FlattenContainers from mimiqcircuits.operations.ifstatement import _decompose_ifstatement if isinstance(op, IfStatement): return _decompose_ifstatement(self, op, qubits, bits, zvars) rule = FlattenContainers() if rule.matches(op): return rule.decompose_step(op, qubits, bits, zvars) raise DecompositionError( f"Operation {op.name} matches FlattenedBasis but cannot be decomposed." )
__all__ = ["FlattenedBasis"]