mimiqcircuits.decomposition.abstract

Abstract base classes for the decomposition framework.

This module defines the core abstractions for quantum circuit decomposition:

Classes

DecompositionBasis()

Abstract base class for decomposition targets.

DecompositionContext([nqubits, borrow, ...])

State that decompose() hands to a basis and its rules.

RewriteRule()

Abstract base class for single-step rewrite rules.

Exceptions

DecompositionError

Raised when an operation cannot be decomposed.

class RewriteRule[source]

Bases: ABC

Abstract base class for single-step rewrite rules.

A rewrite rule says how to rewrite an operation into a circuit of other operations, but not when to stop. Apply it once with decompose_step(), or repeatedly with decompose(), which wraps it in a RuleBasis and rewrites until nothing matches. For a target gate set, see DecompositionBasis.

A subclass implements matches() and decompose_step().

Examples

>>> from mimiqcircuits import *
>>> # a rule that rewrites a SWAP into three CX gates
>>> class SwapToCX(RewriteRule):
...     def matches(self, op):
...         return isinstance(op, GateSWAP)
...
...     def decompose_step(self, op, qubits, bits, zvars):
...         # qubits are the targets of the SWAP in the circuit
...         a, b = qubits
...         circ = Circuit()
...         circ.push(GateCX(), a, b)
...         circ.push(GateCX(), b, a)
...         circ.push(GateCX(), a, b)
...         return circ
>>> c = Circuit()
>>> c.push(GateH(), 0)
1-qubit circuit with 1 instruction:
└── H @ q[0]

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

>>> # the SWAP matches and is rewritten; the H does not and is kept
>>> decompose_step(c, SwapToCX())
2-qubit circuit with 4 instructions:
├── H @ q[0]
├── CX @ q[0], q[1]
├── CX @ q[1], q[0]
└── CX @ q[0], q[1]
abstract matches(op)[source]

Check whether this rule can rewrite an operation.

Parameters:

op (Operation) – The operation to check.

Returns:

True if decompose_step() accepts op.

Return type:

bool

abstract decompose_step(op, qubits, bits, zvars)[source]

Rewrite an operation one step.

Call it only on an operation that matches() accepts. The result acts on the given indices, so it can be appended in place of the original instruction. Its operations may themselves match the rule again.

Parameters:
  • op (Operation) – The operation to rewrite.

  • qubits (Sequence[int]) – Qubit indices the operation acts on.

  • bits (Sequence[int]) – Classical bit indices the operation acts on.

  • zvars (Sequence[int]) – Z-variable indices the operation acts on.

Returns:

A new Circuit that implements op on those indices.

Raises:

DecompositionError – If the rule cannot rewrite op.

Return type:

Circuit

decompose_step_ctx(op, qubits, bits, zvars, ctx)[source]

Apply this rule with a DecompositionContext.

Rules that use the context, for example to borrow qubits, override this method. The default drops the context and calls decompose_step().

class DecompositionBasis[source]

Bases: ABC

Abstract base class for decomposition targets.

A basis decides which operations are terminal, that is kept as they are, and how to rewrite every other operation. decompose() rewrites each non-terminal operation with decompose() and repeats on the result until only terminal operations are left.

A subclass implements isterminal() and decompose().

Examples

>>> from mimiqcircuits import *
>>> # a basis of GateU and GateCZ: CX becomes H, CZ, H and the rest
>>> # follows the built-in decomposition
>>> class CZBasis(DecompositionBasis):
...     def isterminal(self, op):
...         return isinstance(op, (GateU, GateCZ))
...
...     def decompose(self, op, qubits, bits, zvars):
...         if isinstance(op, GateCX):
...             control, target = qubits
...             circ = Circuit()
...             circ.push(GateH(), target)
...             circ.push(GateCZ(), control, target)
...             circ.push(GateH(), target)
...             return circ
...         return CanonicalRewrite().decompose_step(op, qubits, bits, zvars)
>>> c = Circuit()
>>> c.push(GateCX(), 0, 1)
2-qubit circuit with 1 instruction:
└── CX @ q[0], q[1]

>>> # the H gates are not terminal, so they are decomposed in turn
>>> decompose(c, CZBasis())
2-qubit circuit with 3 instructions:
├── U((1/2)*pi, 0, pi, 0.0) @ q[1]
├── CZ @ q[0], q[1]
└── U((1/2)*pi, 0, pi, 0.0) @ q[1]
abstract isterminal(op)[source]

Check whether an operation is terminal in this basis.

Terminal operations are the target set: decompose() keeps them as they are.

Parameters:

op (Operation) – The operation to check.

Returns:

True if op is kept, False if it is rewritten.

Return type:

bool

abstract decompose(op, qubits, bits, zvars)[source]

Rewrite a non-terminal operation one step.

Called by decompose() only for operations that isterminal() rejects. The result does not need to be terminal: decompose() keeps rewriting it.

Parameters:
  • op (Operation) – The operation to rewrite.

  • qubits (Sequence[int]) – Qubit indices the operation acts on.

  • bits (Sequence[int]) – Classical bit indices the operation acts on.

  • zvars (Sequence[int]) – Z-variable indices the operation acts on.

Returns:

A new Circuit that implements op on those indices.

Raises:

DecompositionError – If the basis has no rewrite for op.

Return type:

Circuit

decompose_ctx(op, qubits, bits, zvars, ctx)[source]

Decompose a non-terminal operation with a DecompositionContext.

decompose() always calls this method. Bases that pass the context on to their rules override it. The default drops the context and calls decompose().

class DecompositionContext(nqubits=0, borrow=False, unitary_only=False, allocator=None, bit=None)[source]

Bases: object

State that decompose() hands to a basis and its rules.

The context goes next to the operation and its targets, through DecompositionBasis.decompose_ctx() and RewriteRule.decompose_step_ctx().

Parameters:
  • nqubits (int) – Width of the circuit being decomposed. Qubits 0, ..., nqubits - 1 that are not targets of the operation may be borrowed. 0 means the width is unknown, and nothing is borrowed.

  • borrow (bool) – Whether rules may borrow qubits outside the operation’s targets. A borrowed qubit can be in any state; the decomposition acts as the identity on it.

  • unitary_only (bool) – Set when the result must be unitary, as for the body of a wrapped GateDecl or of an IfStatement.

decompose() also hands out clean ancillas through the context when the basis has max_ancillas > 0. A rule that takes them brackets their use with AncillaAlloc and AncillaFree and returns them in |0>. With allow_measurement=True on the basis, the context also holds a classical bit, numbered after those of the circuit, that rules may measure an ancilla into.

Bases and rules that do not use the context inherit the default *_ctx methods, which drop it and call the method without it.

classmethod from_basis(basis, nqubits, nbits=0)[source]

The context for a circuit nqubits wide with nbits bits.

Clean ancillas and the measured bit are numbered after them, so a circuit of unknown width gets none.

unitary()[source]

The same context for a result that must be unitary.

can_measure()[source]

Whether a rule may measure an ancilla.

available()[source]

Number of clean ancillas that can be taken now.

take_clean(k)[source]

Up to k clean ancillas for the rule that receives this context.

exception DecompositionError[source]

Bases: Exception

Raised when an operation cannot be decomposed.

A basis raises it from DecompositionBasis.decompose() for an operation it is not terminal for and has no rewrite for, and most rules raise it from RewriteRule.decompose_step() for an operation they do not match.