#
# 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.
#
"""Main decomposition functions for quantum circuits.
This module provides the primary API for decomposing quantum circuits:
- :func:`decompose`: recursively decompose to a target basis.
- :func:`eachdecomposed`: the same, as a lazy iterator.
- :func:`decompose_step`: apply a rewrite rule once.
- :class:`DecomposeIterator`: the iterator behind both.
"""
from __future__ import annotations
from collections.abc import Iterator
from typing import TYPE_CHECKING
from mimiqcircuits.decomposition.abstract import (
DecompositionBasis,
DecompositionContext,
RewriteRule,
_AncillaAllocator,
_borrowable,
)
from mimiqcircuits.decomposition.basis import CanonicalBasis, RuleBasis
from mimiqcircuits.decomposition.rules import CanonicalRewrite
from mimiqcircuits.operations.gates.gate import Gate
if TYPE_CHECKING:
from mimiqcircuits.circuit import Circuit
from mimiqcircuits.instruction import Instruction
from mimiqcircuits.operations.operation import Operation
def _to_basis(basis: DecompositionBasis | RewriteRule) -> DecompositionBasis:
"""Convert a RewriteRule to a DecompositionBasis if needed."""
if isinstance(basis, RewriteRule):
return RuleBasis(basis)
return basis
def _op_basename(op):
"""Build a descriptive base name from the wrapper chain.
Examples:
GateRX(0.5) -> "RX"
Inverse(GateRX(0.5)) -> "RX_inv"
Control(2, GateRX(0.5)) -> "C2RX"
Control(1, GateH()) -> "CH"
Power(GateRX(0.5), 3) -> "RX_pow"
Inverse(Control(2, GateH())) -> "C2H_inv"
GateCall(decl, ...) -> decl.name
Inverse(GateCall(decl, ...)) -> decl.name + "_dagger"
"""
from mimiqcircuits.operations.control import Control
from mimiqcircuits.operations.inverse import Inverse
from mimiqcircuits.operations.power import Power
from mimiqcircuits.gatedecl import GateCall
if isinstance(op, GateCall):
return op.decl.name
if isinstance(op, Control):
n = op.num_controls
inner = _op_basename(op.op)
return f"C{n}{inner}" if n > 1 else f"C{inner}"
if isinstance(op, Inverse):
inner = _op_basename(op.op)
suffix = "_dagger" if isinstance(op.op, GateCall) else "_inv"
return f"{inner}{suffix}"
if isinstance(op, Power):
inner = _op_basename(op.op)
return f"{inner}_pow"
return getattr(op, "name", type(op).__name__)
def _haslosses(op):
from mimiqcircuits.blockdecl import BlockCall
from mimiqcircuits.operations.block import Block
from mimiqcircuits.operations.ifstatement import IfStatement
from mimiqcircuits.operations.losschannel import Loss, Reload
from mimiqcircuits.operations.repeat import Repeat
from mimiqcircuits.operations.whilestatement import WhileStatement
if isinstance(op, (Loss, Reload)):
return True
if isinstance(op, (IfStatement, WhileStatement, Repeat)):
return _haslosses(op.op)
if isinstance(op, Block):
return any(_haslosses(i.operation) for i in op.instructions)
if isinstance(op, BlockCall):
return any(_haslosses(i.operation) for i in op.decl.instructions)
return False
def _wrapped_decl_name(op):
"""Generate a GateDecl name for a wrapped (non-terminal) operation."""
return f"mimiq_{_op_basename(op)}"
def _rebuild_with_symbols(op, symbols):
"""Rebuild a (possibly wrapped) operation with symbolic parameters.
Traverses the wrapper chain (Control, Inverse, Power) and reconstructs
with symbolic params at the leaf gate.
"""
from mimiqcircuits.operations.control import Control
from mimiqcircuits.operations.inverse import Inverse
from mimiqcircuits.operations.power import Power
from mimiqcircuits.gatedecl import GateCall
if isinstance(op, Control):
inner = _rebuild_with_symbols(op.op, symbols)
return Control(op.num_controls, inner)
if isinstance(op, Inverse):
inner = _rebuild_with_symbols(op.op, symbols)
return Inverse(inner)
if isinstance(op, Power):
inner = _rebuild_with_symbols(op.op, symbols)
return Power(inner, op.exponent)
if isinstance(op, GateCall):
return GateCall(op.decl, symbols)
# Leaf gate — reconstruct with symbolic params
return type(op)(*symbols)
def _get_leaf_parnames(op):
"""Get parnames from the leaf gate in a wrapper chain.
Wrappers (Control, Inverse, Power) delegate getparams() to their inner op
but may not set _parnames. This traverses to the leaf to find the actual
parameter names.
"""
from mimiqcircuits.operations.control import Control
from mimiqcircuits.operations.inverse import Inverse
from mimiqcircuits.operations.power import Power
from mimiqcircuits.gatedecl import GateCall
if isinstance(op, (Control, Inverse, Power)):
return _get_leaf_parnames(op.op)
if isinstance(op, GateCall):
# GateCall params come from decl.arguments, not _parnames
return tuple(str(a) for a in op.decl.arguments)
return op._parnames
def _compact_extra(circ, nq, nqb):
"""Renumber the extra qubits a body used, keeping their order.
The borrowed slots (from ``nq`` to ``nqb - 1``) come first, then the clean
ones (from ``nqb`` on). The declaration is then only as wide as what it
touches, with its clean ancillas last. Returns the body and the number of
clean ancillas.
"""
from mimiqcircuits.circuit import Circuit
used = sorted({q for inst in circ for q in inst.qubits if q >= nq})
remap = {u: nq + i for i, u in enumerate(used)}
out = Circuit()
for inst in circ:
qubits = [remap.get(q, q) for q in inst.qubits]
out.push(inst.operation, *qubits, *inst.bits, *inst.zvars)
return out, sum(1 for u in used if u >= nqb)
def _wrap_decomposition(inst, basis, cache, ctx):
"""Wrap a non-terminal gate instruction into a GateDecl/GateCall.
Decomposes the operation one step, recursively wraps the result and
creates a GateDecl from the wrapped body. Returns the instructions to
emit: the GateCall, with markers around it for the clean ancillas it
uses. A body that measures becomes a BlockDecl instead, and the call a
BlockCall that writes the measured bit.
"""
from mimiqcircuits.circuit import Circuit
from mimiqcircuits.instruction import Instruction
from mimiqcircuits.operations.inverse import Inverse
from mimiqcircuits.gatedecl import GateCall, GateDecl
from mimiqcircuits.operations.annotations import AncillaAlloc, AncillaFree
from mimiqcircuits.blockdecl import BlockCall, BlockDecl
op = inst.operation
qs = inst.qubits
bs = inst.bits
zs = inst.zvars
nq = op.num_qubits
# Step 1: Canonicalize for parametric reuse.
# For GateCall/Inverse(GateCall), use the decl's own symbolic arguments.
# For all other parametric ops (including wrappers like Control(2, GateRX(0.5))),
# rebuild the op with fresh symbols from the leaf gate's parnames.
# Note: Control._parnames is () even when inner gate has params,
# so we use _get_leaf_parnames + getparams() to detect parametric ops.
if isinstance(op, GateCall):
# GateCall(decl, args) -> canonical = GateCall(decl, decl.arguments)
symbols = op.decl.arguments
concrete_args = op.arguments
canonical_op = GateCall(op.decl, symbols) if symbols else op
elif isinstance(op, Inverse) and isinstance(op.op, GateCall):
# Inverse(GateCall(decl, args)) -> canonical = Inverse(GateCall(decl, decl.arguments))
symbols = op.op.decl.arguments
concrete_args = op.op.arguments
if symbols:
canonical_gc = GateCall(op.op.decl, symbols)
canonical_op = Inverse(canonical_gc)
else:
canonical_op = op
else:
leaf_parnames = _get_leaf_parnames(op)
if leaf_parnames:
# Parametric op: plain gates (GateRYY(0.5)) AND wrappers
# (Control(2, GateRX(0.5)), Inverse(GateRX(0.5)), Power(GateRX(0.5), 3))
from symengine import Symbol
symbols = tuple(Symbol(pn) for pn in leaf_parnames)
concrete_args = tuple(op.getparams())
try:
canonical_op = _rebuild_with_symbols(op, symbols)
except Exception:
# Fallback: no canonicalization
canonical_op = op
concrete_args = ()
symbols = ()
else:
# Non-parametric ops (Inverse(GateH), Power(GateX, 3), etc.)
canonical_op = op
concrete_args = ()
symbols = ()
# Step 2: Check cache
# The body is built on targets 0..nq-1, followed by nb slots for the
# qubits it may borrow and nc slots for clean ancillas. The borrowable
# qubits are nearest-first in both frames, so slot nq + j stands for
# borrowable[j] at this call site. Clean ancillas are taken at the call
# site once the body has said how many it uses.
borrowable = _borrowable(ctx, qs, ctx.nqubits)
nborrow = len(borrowable)
nclean = ctx.allocator.available() if ctx.allocator is not None else 0
def call(op, nextra, num_ancillas, bits=bs):
"""Call ``op`` on the data qubits, borrowed ones and clean ancillas.
The clean ancillas are taken now, and the call-site markers bracket
them.
"""
clean = ctx.take_clean(num_ancillas)
borrowed = borrowable[: nextra - num_ancillas]
qubits = tuple(qs) + tuple(borrowed) + tuple(clean)
return (
[Instruction(AncillaAlloc(), (q,)) for q in clean]
+ [Instruction(op, qubits, bits, zs)]
+ [Instruction(AncillaFree(), (q,)) for q in clean]
)
def call_decl(decl):
if isinstance(decl, BlockDecl):
return call(
BlockCall(decl, concrete_args),
decl.num_qubits - nq,
decl.num_ancillas,
(ctx.bit,),
)
return call(
GateCall(decl, concrete_args), decl.num_qubits - nq, decl.num_ancillas
)
# Only the rule that decomposes the operation itself gets clean ancillas;
# the operations it produces are wrapped with none. With measurements
# allowed, its body may measure into bit 0, the bit of the call site.
# A measuring body must not be reused where only unitaries are allowed,
# hence `measure` in the key.
measure = nclean > 0 and ctx.can_measure()
key = (canonical_op, nborrow, nclean, measure)
if key in cache:
return call_decl(cache[key])
bodyalloc = _AncillaAllocator(nq + nborrow, nclean) if nclean > 0 else None
bodyctx = DecompositionContext(
nqubits=nq + nborrow,
borrow=ctx.borrow,
unitary_only=not measure,
allocator=bodyalloc,
bit=0 if measure else None,
)
innerctx = DecompositionContext(
nqubits=nq + nborrow, borrow=ctx.borrow, unitary_only=True
)
one_step = basis.decompose_ctx(canonical_op, tuple(range(nq)), (), (), bodyctx)
# Declaration bodies carry no ancilla markers: the call site has them.
wrapped = Circuit()
for sub_inst in DecomposeIterator(
one_step, basis, wrap=True, cache=cache, ctx=innerctx
):
if not isinstance(sub_inst.operation, (AncillaAlloc, AncillaFree)):
wrapped.push(sub_inst)
body, L = _compact_extra(wrapped, nq, nq + nborrow)
# A body that measures cannot be a GateDecl; it becomes a BlockDecl whose
# bit is the measured bit of the call site.
name = _wrapped_decl_name(op)
if all(isinstance(i.operation, Gate) for i in body):
decl = GateDecl(name, symbols, body, num_ancillas=L)
else:
decl = BlockDecl(name, symbols, body, num_ancillas=L)
cache[key] = decl
return call_decl(decl)
def _wrap_block(inst, basis, cache, ctx):
"""Wrap a non-terminal, non-gate instruction into a Block.
The Block holds the wrapped decomposition of the operation, so the gates
in it become GateCalls as usual. Returns the Block instruction in a list,
as :func:`_wrap_decomposition` does.
"""
from mimiqcircuits.instruction import Instruction
from mimiqcircuits.operations.block import Block
op = inst.operation
nq, nb, nz = op.num_qubits, op.num_bits, op.num_zvars
bodyctx = DecompositionContext(nqubits=nq, borrow=ctx.borrow)
one_step = basis.decompose_ctx(
op, tuple(range(nq)), tuple(range(nb)), tuple(range(nz)), bodyctx
)
# Push one by one: the Block constructor deep-copies its instructions,
# which would duplicate the cached GateDecls.
block = Block(nq, nb, nz)
for sub_inst in DecomposeIterator(
one_step, basis, wrap=True, cache=cache, ctx=bodyctx
):
block.push(sub_inst)
return [Instruction(block, inst.qubits, inst.bits, inst.zvars)]
[docs]
class DecomposeIterator(Iterator["Instruction"]):
"""Iterator over the instructions of a recursive decomposition.
Decomposes depth-first and yields each terminal instruction as soon as it
is reached, in circuit order, so the decomposed circuit is never held in
memory at once. Each non-terminal operation is decomposed only when the
iteration reaches it. :func:`eachdecomposed` builds one with the default
basis, and :func:`decompose` collects one into a circuit.
Args:
source: The circuit, instruction or operation to decompose. A bare
operation is placed on qubits, bits and z-variables ``0, 1, ...``.
basis: The target basis. Unlike :func:`decompose`, a rewrite rule is
not accepted here; wrap it in a :class:`RuleBasis`.
wrap: If ``False`` (default), yield only terminal operations. If
``True``, yield each non-terminal gate as a ``GateCall`` to a
``GateDecl`` holding its decomposition, and each other
non-terminal operation (such as ``MeasureReset``) as a ``Block``
holding its decomposition, in both cases wrapped again at every
level. A gate whose decomposition measures an ancilla becomes a
``BlockCall`` to a ``BlockDecl``.
cache: Dictionary that maps operations to the declaration built for
them when ``wrap=True``, keyed by the (symbolic) operation, the
numbers of borrowed and clean qubits its body was offered, and
whether it may measure. Pass the same dictionary to several
iterators to share declarations between them. A new one is used
by default.
nqubits: Width of the circuit, which bounds the qubits a basis with
``borrow=True`` may borrow. Defaults to ``source.num_qubits()``
for a Circuit and to 0 (borrow nothing) for anything else, so the
result never depends on the values of the target indices alone.
ctx: The :class:`DecompositionContext` to use instead of the one
built from ``basis`` and ``nqubits``.
Raises:
ValueError: If the basis borrows qubits and ``source`` contains
``Loss`` or ``Reload``: losses act on qubits a borrowing
decomposition relies on. Resolve them first, for example with
``lower_losses``.
TypeError: If ``source`` is not a circuit, instruction or operation.
DecompositionError: While iterating, if the basis cannot decompose an
operation.
Examples:
>>> from mimiqcircuits import *
>>> c = Circuit()
>>> c.push(GateH(), 0)
1-qubit circuit with 1 instruction:
└── H @ q[0]
<BLANKLINE>
>>> # instructions are produced one at a time
>>> for inst in DecomposeIterator(c, CanonicalBasis()):
... print(inst)
U((1/2)*pi, 0, pi, 0.0) @ q[0]
"""
def __init__(
self,
source: Circuit | Instruction | Operation,
basis: DecompositionBasis,
wrap: bool = False,
cache: dict | None = None,
nqubits: int = 0,
ctx: DecompositionContext | None = None,
):
from mimiqcircuits.circuit import Circuit
from mimiqcircuits.instruction import Instruction
from mimiqcircuits.operations.operation import Operation
basis = _to_basis(basis)
self._basis = basis
self._wrap = wrap
self._cache = cache if cache is not None else {}
self._stack: list[Instruction] = []
# Wrapped calls come with their ancilla markers, queued here.
self._ready: list[Instruction] = []
# Initialize stack based on source type
if isinstance(source, Circuit):
# Reverse so we process in order (stack is LIFO)
self._stack = list(reversed(source.instructions))
elif isinstance(source, Instruction):
self._stack = [source]
elif isinstance(source, Operation):
# Create instruction with canonical targets
inst = Instruction(
source,
tuple(range(source.num_qubits)),
tuple(range(source.num_bits)),
tuple(range(source.num_zvars)),
)
self._stack = [inst]
else:
raise TypeError(
f"Cannot decompose {type(source).__name__}. "
"Expected Circuit, Instruction, or Operation."
)
if ctx is None:
nbits = 0
if isinstance(source, Circuit):
nqubits = max(nqubits, source.num_qubits())
nbits = source.num_bits()
if basis._ancillaoptions().allow_measurement and nbits == 0:
# Such a circuit is sampled on all its qubits; a measured
# ancilla bit would make it sampled on that bit alone.
raise ValueError(
"allow_measurement needs a circuit with classical bits"
)
ctx = DecompositionContext.from_basis(basis, nqubits, nbits)
if ctx.borrow and any(_haslosses(i.operation) for i in self._stack):
raise ValueError(
"cannot borrow qubits in a circuit with Loss or Reload; "
"resolve the losses first, for example with lower_losses"
)
self._ctx = ctx
def __iter__(self) -> DecomposeIterator:
return self
def _emit(self, inst):
if self._ctx.allocator is not None:
self._ctx.allocator.track(inst)
return inst
def __next__(self) -> Instruction:
while self._ready or self._stack:
if self._ready:
return self._emit(self._ready.pop())
inst = self._stack.pop()
op = inst.operation
if self._basis.isterminal(op):
return self._emit(inst)
if self._wrap:
if isinstance(op, Gate):
out = _wrap_decomposition(inst, self._basis, self._cache, self._ctx)
else:
out = _wrap_block(inst, self._basis, self._cache, self._ctx)
self._ready.extend(reversed(out))
continue
decomposed = self._basis.decompose_ctx(
op, inst.qubits, inst.bits, inst.zvars, self._ctx
)
self._stack.extend(reversed(decomposed.instructions))
raise StopIteration
[docs]
def decompose(
source: Circuit | Instruction | Operation,
basis: DecompositionBasis | RewriteRule | None = None,
wrap: bool = False,
) -> Circuit:
"""Recursively decompose a circuit to a target basis.
Rewrites every operation of ``source`` that is not terminal in ``basis``,
and repeats on the result, until only terminal operations are left. The
source is not modified.
Args:
source: The circuit, instruction or operation to decompose. A bare
operation is placed on qubits, bits and z-variables ``0, 1, ...``.
basis: The target basis. A :class:`RewriteRule` is wrapped in a
:class:`RuleBasis`, so it is applied until it no longer matches.
Defaults to :class:`CanonicalBasis`.
wrap: If ``False`` (default), the result holds only terminal
operations. If ``True``, each non-terminal gate becomes a
``GateCall`` to a ``GateDecl`` holding its decomposition, and
each other non-terminal operation (such as ``MeasureReset``) a
``Block`` holding its decomposition, both wrapped again at every
level. Gates that differ only in their parameters share one
``GateDecl``. A gate whose decomposition measures an ancilla
(``allow_measurement=True``) becomes a ``BlockCall`` to a shared
``BlockDecl``. This keeps the structure of the original circuit
visible.
Returns:
A new :class:`~mimiqcircuits.Circuit` of terminal operations, plus
``GateCall`` and ``Block`` operations when ``wrap=True``.
Raises:
TypeError: If ``source`` is not a circuit, instruction or operation.
DecompositionError: If ``basis`` cannot decompose an operation, for
example a ``GateT`` in :class:`StimBasis`.
Examples:
>>> from mimiqcircuits import *
>>> c = Circuit()
>>> c.push(GateH(), 0)
1-qubit circuit with 1 instruction:
└── H @ q[0]
<BLANKLINE>
>>> c.push(GateCCX(), 0, 1, 2)
3-qubit circuit with 2 instructions:
├── H @ q[0]
└── C₂X @ q[0:1], q[2]
<BLANKLINE>
>>> # the default basis leaves only GateU and GateCX
>>> sorted({type(inst.operation).__name__ for inst in decompose(c)})
['GateCX', 'GateU']
>>> # any other basis can be given
>>> sorted({type(inst.operation).__name__ for inst in decompose(c, CliffordTBasis())})
['GateCX', 'GateH', 'GateT', 'GateTDG']
>>> # with wrap=True each gate becomes a call to a declared gate,
>>> # so the two CH gates share one declaration
>>> c = Circuit()
>>> c.push(GateCH(), 0, 1)
2-qubit circuit with 1 instruction:
└── CH @ q[0], q[1]
<BLANKLINE>
>>> c.push(GateCH(), 1, 2)
3-qubit circuit with 2 instructions:
├── CH @ q[0], q[1]
└── CH @ q[1], q[2]
<BLANKLINE>
>>> decompose(c, wrap=True)
3-qubit circuit with 2 instructions:
├── mimiq_CH() @ q[0:1]
└── mimiq_CH() @ q[1:2]
<BLANKLINE>
"""
from mimiqcircuits.circuit import Circuit
if basis is None:
basis = CanonicalBasis()
else:
basis = _to_basis(basis)
cache = {} if wrap else None
result = Circuit()
for inst in DecomposeIterator(source, basis, wrap=wrap, cache=cache):
result.push(inst)
return result
[docs]
def decompose_step(
source: Circuit | Instruction | Operation,
rule: RewriteRule | None = None,
) -> Circuit:
"""Apply a rewrite rule once to every instruction of a circuit.
Each instruction whose operation matches ``rule`` is replaced by the
result of :meth:`RewriteRule.decompose_step`; the others are copied
unchanged. Unlike :func:`decompose`, the result is not rewritten again,
so it can still hold operations that match ``rule``.
Args:
source: The circuit, instruction or operation to rewrite. A bare
operation is placed on qubits, bits and z-variables ``0, 1, ...``.
rule: The rewrite rule to apply. Defaults to
:class:`CanonicalRewrite`. A :class:`DecompositionBasis` is not
accepted.
Returns:
A new :class:`~mimiqcircuits.Circuit` with the rule applied once.
Raises:
TypeError: If ``source`` is not a circuit, instruction or operation.
Examples:
>>> from mimiqcircuits import *
>>> from symengine import pi
>>> c = Circuit()
>>> c.push(GateH(), 0)
1-qubit circuit with 1 instruction:
└── H @ q[0]
<BLANKLINE>
>>> c.push(GateRX(pi/3), 0)
1-qubit circuit with 2 instructions:
├── H @ q[0]
└── RX((1/3)*pi) @ q[0]
<BLANKLINE>
>>> # ZYZRewrite matches RX but not H, so only RX is rewritten
>>> decompose_step(c, ZYZRewrite())
1-qubit circuit with 4 instructions:
├── H @ q[0]
├── S @ q[0]
├── RY((1/3)*pi) @ q[0]
└── S† @ q[0]
<BLANKLINE>
>>> # the default rule expands one level of the built-in decomposition
>>> decompose_step(GateSWAP())
2-qubit circuit with 3 instructions:
├── CX @ q[0], q[1]
├── CX @ q[1], q[0]
└── CX @ q[0], q[1]
<BLANKLINE>
"""
from mimiqcircuits.circuit import Circuit
from mimiqcircuits.instruction import Instruction
from mimiqcircuits.operations.operation import Operation
if rule is None:
rule = CanonicalRewrite()
result = Circuit()
# Handle different source types
if isinstance(source, Operation):
qubits = tuple(range(source.num_qubits))
bits = tuple(range(source.num_bits))
zvars = tuple(range(source.num_zvars))
if rule.matches(source):
decomposed = rule.decompose_step(source, qubits, bits, zvars)
result.append(decomposed)
else:
result.push(source, *qubits, *bits, *zvars)
elif isinstance(source, Instruction):
op = source.operation
if rule.matches(op):
decomposed = rule.decompose_step(
op, source.qubits, source.bits, source.zvars
)
result.append(decomposed)
else:
result.push(source)
elif isinstance(source, Circuit):
for inst in source:
op = inst.operation
if rule.matches(op):
decomposed = rule.decompose_step(
op, inst.qubits, inst.bits, inst.zvars
)
result.append(decomposed)
else:
result.push(inst)
else:
raise TypeError(
f"Cannot decompose {type(source).__name__}. "
"Expected Circuit, Instruction, or Operation."
)
return result
[docs]
def eachdecomposed(
source: Circuit | Instruction | Operation,
basis: DecompositionBasis | RewriteRule | None = None,
wrap: bool = False,
) -> DecomposeIterator:
"""Iterate over the instructions of a recursive decomposition.
Yields the same instructions as :func:`decompose`, one at a time, without
building the decomposed circuit. Use it to stream a large decomposition
or to stop early.
Args:
source: The circuit, instruction or operation to decompose. A bare
operation is placed on qubits, bits and z-variables ``0, 1, ...``.
basis: The target basis. A :class:`RewriteRule` is wrapped in a
:class:`RuleBasis`. Defaults to :class:`CanonicalBasis`.
wrap: Wrap non-terminal operations instead of expanding them, as in
:func:`decompose`. Defaults to ``False``.
Returns:
A :class:`DecomposeIterator` over the decomposed instructions.
Raises:
TypeError: If ``source`` is not a circuit, instruction or operation.
DecompositionError: While iterating, if ``basis`` cannot decompose an
operation.
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>
>>> # instructions are computed as they are requested
>>> it = eachdecomposed(c)
>>> next(it)
U((1/2)*pi, 0, pi, 0.0) @ q[2]
"""
if basis is None:
basis = CanonicalBasis()
else:
basis = _to_basis(basis)
cache = {} if wrap else None
return DecomposeIterator(source, basis, wrap=wrap, cache=cache)
__all__ = [
"decompose",
"decompose_step",
"eachdecomposed",
"DecomposeIterator",
]