mimiqcircuits.decomposition.abstract¶
Abstract base classes for the decomposition framework.
This module defines the core abstractions for quantum circuit decomposition:
RewriteRule: Single-step transformation rulesDecompositionBasis: Recursive decomposition to a target gate set
Classes
Abstract base class for decomposition targets. |
|
|
State that |
Abstract base class for single-step rewrite rules. |
Exceptions
Raised when an operation cannot be decomposed. |
- class RewriteRule[source]¶
Bases:
ABCAbstract 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 withdecompose(), which wraps it in aRuleBasisand rewrites until nothing matches. For a target gate set, seeDecompositionBasis.A subclass implements
matches()anddecompose_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:
Trueifdecompose_step()acceptsop.- Return type:
- 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:
- Returns:
A new
Circuitthat implementsopon those indices.- Raises:
DecompositionError – If the rule cannot rewrite
op.- Return type:
- 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:
ABCAbstract 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 withdecompose()and repeats on the result until only terminal operations are left.A subclass implements
isterminal()anddecompose().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.
- abstract decompose(op, qubits, bits, zvars)[source]¶
Rewrite a non-terminal operation one step.
Called by
decompose()only for operations thatisterminal()rejects. The result does not need to be terminal:decompose()keeps rewriting it.- Parameters:
- Returns:
A new
Circuitthat implementsopon those indices.- Raises:
DecompositionError – If the basis has no rewrite for
op.- Return type:
- 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 callsdecompose().
- class DecompositionContext(nqubits=0, borrow=False, unitary_only=False, allocator=None, bit=None)[source]¶
Bases:
objectState that
decompose()hands to a basis and its rules.The context goes next to the operation and its targets, through
DecompositionBasis.decompose_ctx()andRewriteRule.decompose_step_ctx().- Parameters:
nqubits (int) – Width of the circuit being decomposed. Qubits
0, ..., nqubits - 1that are not targets of the operation may be borrowed.0means 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
GateDeclor of anIfStatement.
decompose()also hands out clean ancillas through the context when the basis hasmax_ancillas > 0. A rule that takes them brackets their use withAncillaAllocandAncillaFreeand returns them in|0>. Withallow_measurement=Trueon 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
*_ctxmethods, which drop it and call the method without it.
- exception DecompositionError[source]¶
Bases:
ExceptionRaised 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 fromRewriteRule.decompose_step()for an operation they do not match.