mimiqcircuits.decomposition.basis¶
Decomposition bases for quantum circuits.
The available bases are:
CanonicalBasis: Decomposes to GateU + GateCX (default)CliffordTBasis: Decomposes to Clifford+T gate setFlattenedBasis: Flattens container operationsQASMBasis: Decomposes to OpenQASM 2.0 gate setStimBasis: Decomposes to Stim Clifford gate setRuleBasis: Wraps a RewriteRule as a DecompositionBasis
- class CanonicalBasis(borrow=False, max_ancillas=0, allow_measurement=False)[source]¶
Bases:
DecompositionBasisDecomposition basis targeting
GateUandGateCX.Every gate is rewritten into
GateU(an arbitrary single-qubit gate) andGateCX, with the built-in decomposition of each operation (CanonicalRewrite). The non-unitary primitives are kept as they are;isterminal()lists them. This is the default basis ofdecompose().- Parameters:
borrow (bool) – 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 (int) – Let decompositions add up to this many clean ancillas, numbered after the qubits of the circuit and marked with
AncillaAllocandAncillaFree. Ancillas freed by one operation are reused by the next.allow_measurement (bool) – 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 aValueError.
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] >>> c.push(GateSWAP(), 0, 1) 2-qubit circuit with 2 instructions: ├── H @ q[0] └── SWAP @ q[0:1] >>> 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] >>> # 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]
- isterminal(op)[source]¶
Check whether an operation is terminal in the canonical basis.
The terminal operations are
GateUandGateCX;Measure;Reset,ResetXandResetY;Loss,Reload,CheckandMeasureCheck;BarrierandDelay; classical operations and annotations; noise channels andReadoutErr;ExpectationValue,Amplitude,SchmidtRank,VonNeumannEntropyandBondDim; and the z-register operationsAdd,MultiplyandPow. AnIfStatementorWhileStatementis terminal when its body is.
- decompose(op, qubits, bits, zvars)[source]¶
Rewrite a non-terminal operation with its built-in decomposition.
- Parameters:
- Returns:
A new
Circuitwith one decomposition step.- Raises:
DecompositionError – If
ophas no built-in decomposition.- Return type:
- decompose_ctx(op, qubits, bits, zvars, ctx)[source]¶
Decompose with a context, which only some operations use.
Operations without a rule that uses the context go to
decompose(), so an override of it keeps being called.
- class CliffordTBasis(sk_depth=None, rotations=None, borrow=False, max_ancillas=0, allow_measurement=False)[source]¶
Bases:
DecompositionBasisDecomposition basis targeting the Clifford+T gate set.
Clifford+T is the standard universal gate set of error-corrected quantum computing. The terminal operations of this basis are those of
StimBasisplusGateTandGateTDG, so the two bases always keep the same Clifford and stabilizer operations:single-qubit Cliffords:
GateID,GateX,GateY,GateZ,GateH,GateHXY,GateHYZ,GateS,GateSDG,GateSX,GateSXDG,GateSY,GateSYDG;two-qubit Cliffords:
GateCX,GateCY,GateCZ,GateSWAP,GateISWAP,GateISWAPDG,GateDCX,GateECR;Pauli rotations by
+-pi/2:GateRXX,GateRYY,GateRZZ, andRPauliwith a non-identity Pauli string;the non-Clifford
GateTandGateTDG;measurements, resets and measure-and-resets in the X, Y and Z bases,
MeasureXX,MeasureYY,MeasureZZandMeasurePauli;Pauli noise:
PauliX,PauliY,PauliZ,Depolarizing1,Depolarizing2andPauliNoise;barriers and annotations;
classical operations, which
StimBasisdoes not keep;an
IfStatementwhose body is terminal in this basis, with any condition.StimBasisonly keeps a conditionalGateX,GateYorGateZon a single bit.
Non-terminal operations are rewritten by the first rule that matches, in this order:
SpecialAngleRewrite: rotations by multiples ofpi/4to exact Clifford+T.GateECRtoS,SX,CXandX, as inStimBasis, with no T gate.ToffoliToCliffordTRewrite:GateCCXto Clifford+T with 7 T gates.A
GateUwhose angles are all zero (a pure global phase) is dropped.ZYZRewrite:GateUtoRZ*RY*RZ, andGateRXtoGateRYbetweenSandS†.ToZRotationRewrite:GateRYtoGateRZand Cliffords.The
rotationsrule (defaultGridSynthRewrite): remainingGateRZto an approximate Clifford+T sequence.CanonicalRewrite: any other operation, towardGateUandGateCX. AGateRX,GateRYorGateRZthat reaches this point has a symbolic angle and raisesDecompositionError.
The
rotationsrule only sees angles that step 1 could not decompose exactly. The body of anIfStatementgoes through the same pipeline and stays conditional. No T-count optimization is performed on the result.- Parameters:
sk_depth (int | None) – Use
SolovayKitaevRewritewith this recursion depth as therotationsrule.rotations (RewriteRule) – Rule that synthesizes the remaining Z-rotations. The default
GridSynthRewrite()approximates each rotation to operator-norm error1e-10. The rule must matchGateRZwith a numeric angle and emit only gates of this basis.borrow (bool) – 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 (int) – Let decompositions add up to this many clean ancillas, numbered after the qubits of the circuit and marked with
AncillaAllocandAncillaFree. Ancillas freed by one operation are reused by the next.allow_measurement (bool) – 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 aValueError. With a clean ancilla, aGateCCXthen costs 4 T instead of 7.
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.
- Raises:
ValueError – If both
sk_depthandrotationsare given, or ifrotationsdoes not matchGateRZ.
Decomposing an operation that no rule handles, such as a noise channel other than the Pauli ones above, raises a
DecompositionError.Examples
>>> from mimiqcircuits import * >>> from symengine import pi >>> c = Circuit() >>> c.push(GateRZ(pi/4), 0) 1-qubit circuit with 1 instruction: └── RZ((1/4)*pi) @ q[0] >>> # a special angle is decomposed exactly >>> decompose(c, CliffordTBasis()) 1-qubit circuit with 1 instruction: └── T @ q[0]
>>> # An arbitrary angle is approximated to 1e-10 by gridsynth >>> c2 = Circuit() >>> c2.push(GateRZ(0.123), 0) 1-qubit circuit with 1 instruction: └── RZ(0.123) @ q[0] >>> decomposed2 = decompose(c2, CliffordTBasis())
>>> # A looser error bound per rotation gives fewer T gates >>> basis = CliffordTBasis(rotations=GridSynthRewrite(epsilon=1e-6)) >>> decomposed3 = decompose(c2, basis) >>> def tcount(c): ... return sum(isinstance(inst.operation, (GateT, GateTDG)) for inst in c) >>> tcount(decomposed3) < tcount(decomposed2) True
>>> # Solovay-Kitaev instead of gridsynth >>> decomposed4 = decompose(c2, CliffordTBasis(sk_depth=0))
- decompose(op, qubits, bits, zvars)[source]¶
Rewrite a non-terminal operation one step toward Clifford+T.
Applies the first matching rule of the list in the class description.
- Parameters:
- Returns:
A new
Circuitwith the rewrite.- Raises:
DecompositionError – If no rule applies to
op.- Return type:
- decompose_ctx(op, qubits, bits, zvars, ctx)[source]¶
Decompose with a context, which only some operations use.
Operations without a rule that uses the context go to
decompose(), so an override of it keeps being called.
- class FlattenedBasis[source]¶
Bases:
DecompositionBasisDecomposition basis that expands containers and keeps every other operation.
GateCall,BlockandBlockCall, and theInverseof aGateCall, are expanded withFlattenContainersuntil none is left, at any depth. AnIfStatementwhose body is a container becomes one conditional instruction per instruction of the body. Gates are not decomposed, and that includes aGateCallwrapped inControl,Power,ParallelorRepeat, 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] >>> c.push(GateSWAP(), 0, 1) 2-qubit circuit with 2 instructions: ├── bell() @ q[0:1] └── SWAP @ q[0:1] >>> # 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]
- decompose(op, qubits, bits, zvars)[source]¶
Expand one level of a container.
- Parameters:
- Returns:
A new
Circuitwith the contents ofop, each made conditional ifopis anIfStatement.- Raises:
DecompositionError – If
opis not a container.- Return type:
- class QASMBasis(borrow=False, max_ancillas=0, allow_measurement=False)[source]¶
Bases:
DecompositionBasisDecomposition basis targeting the OpenQASM 2.0 gate library.
The terminal gates are the OpenQASM 2.0 built-ins and the gates of the
qelib1.incinclude file that have a direct MIMIQ counterpart, so a decomposed circuit can be written as OpenQASM 2.0 and read back by any parser that ships the standardqelib1.inc.The terminal operations are:
the OpenQASM 2.0 built-ins
GateUandGateCX;the single-qubit gates of
qelib1.inc:GateU3,GateU2,GateU1,GateID,GateX,GateY,GateZ,GateH,GateS,GateSDG,GateT,GateTDG,GateRX,GateRYandGateRZ;the two-qubit gates of
qelib1.inc:GateCY,GateCZ,GateCH,GateCRX,GateCRY,GateCRZ,GateSWAP,GateRXXandGateRZZ;the three- and four-qubit gates of
qelib1.inc:GateCCX,GateCSWAPandGateC3X;Measure,ResetandBarrier, but not the X and Y variants ofMeasureandReset;annotations, such as
AncillaAlloc, which the OpenQASM writer drops;an
IfStatementwhose body is terminal;a
GateCallwhose declaration holds only terminal operations.
Every other operation is decomposed through
CanonicalRewrite. Operations that OpenQASM 2.0 cannot express and that have no decomposition into the gates above (noise channels, classical operations, Z-register operations, …) raiseDecompositionError.MeasureResetdecomposes intoMeasurefollowed byReset. This leaves the same state and bit as its canonical decomposition, a measurement and anXconditioned on its outcome, and unlike that conditional it can be written for a circuit of any number of bits. OpenQASM 2.0 has no loops, soWhileStatementraisesDecompositionError.- Parameters:
borrow (bool) – 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 (int) – Let decompositions add up to this many clean ancillas, numbered after the qubits of the circuit and marked with
AncillaAllocandAncillaFree. Ancillas freed by one operation are reused by the next.allow_measurement (bool) – 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 aValueError.
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(GateCCX(), 0, 1, 2) 3-qubit circuit with 1 instruction: └── C₂X @ q[0:1], q[2] >>> c.push(GateSX(), 0) 3-qubit circuit with 2 instructions: ├── C₂X @ q[0:1], q[2] └── SX @ q[0] >>> c.push(MeasureReset(), 0, 0) 3-qubit, 1-bit circuit with 3 instructions: ├── C₂X @ q[0:1], q[2] ├── SX @ q[0] └── MR @ q[0], c[0] >>> # CCX is in qelib1.inc and is kept; SX is not and is rewritten; >>> # MeasureReset becomes a measurement and a reset >>> decompose(c, QASMBasis()) 3-qubit, 1-bit circuit with 7 instructions: ├── C₂X @ q[0:1], q[2] ├── S† @ q[0] ├── H @ q[0] ├── S† @ q[0] ├── U(0, 0, 0, (1/4)*pi) @ q[0] ├── M @ q[0], c[0] └── Reset @ q[0]
See also
- decompose(op, qubits, bits, zvars)[source]¶
Rewrite a non-terminal operation one step toward OpenQASM 2.0.
MeasureResetbecomesMeasureandReset; every other operation goes throughCanonicalRewrite.- Parameters:
- Returns:
A new
Circuitwith the rewrite.- Raises:
DecompositionError – If
opis aWhileStatementor has no built-in decomposition.- Return type:
- decompose_ctx(op, qubits, bits, zvars, ctx)[source]¶
Decompose with a context, which only some operations use.
Operations without a rule that uses the context go to
decompose(), so an override of it keeps being called.
- class RuleBasis(rule)[source]¶
Bases:
DecompositionBasisDecomposition basis that applies one rewrite rule until it no longer matches.
An operation is terminal when the rule does not match it. When the rule does not match an
IfStatement, it is applied to the body, which stays conditional.decompose()andeachdecomposed()wrap a rule passed in place of a basis in aRuleBasis.- Parameters:
rule (RewriteRule) – The rewrite rule to apply.
Examples
>>> from mimiqcircuits import * >>> from symengine import pi >>> c = Circuit() >>> c.push(GateH(), 0) 1-qubit circuit with 1 instruction: └── H @ q[0] >>> c.push(GateRX(pi/2), 0) 1-qubit circuit with 2 instructions: ├── H @ q[0] └── RX((1/2)*pi) @ q[0] >>> # rewrite every X and Y rotation into Z rotations; H is kept >>> decompose(c, RuleBasis(ToZRotationRewrite())) 1-qubit circuit with 4 instructions: ├── H @ q[0] ├── H @ q[0] ├── RZ((1/2)*pi) @ q[0] └── H @ q[0]
- decompose(op, qubits, bits, zvars)[source]¶
Apply the rule once to an operation.
- Parameters:
- Returns:
A new
Circuitwith the rewrite. For anIfStatementthe rule does not match, the rewrite of its body, with each instruction made conditional.- Raises:
DecompositionError – If the rule cannot rewrite
op.- Return type:
- decompose_ctx(op, qubits, bits, zvars, ctx)[source]¶
Apply the rule once, with a context, as
decompose()does.
- class StimBasis[source]¶
Bases:
DecompositionBasisDecomposition basis targeting the gate set of the Stim stabilizer simulator.
Stim simulates stabilizer circuits: Clifford gates, Pauli measurements and resets, Pauli noise and quantum error correction annotations. Gates are rewritten toward that set by the first rule that matches, in this order:
A
GateUwhose angles are all zero (a pure global phase) is dropped.ZYZRewrite:GateUtoRZ*RY*RZ, andGateRXtoGateRYbetweenSandS†.SpecialAngleRewritewithonly_cliffords=True: rotations by multiples ofpi/2to Clifford gates.GateECRtoS,SX,CXandX, equal up to a global phase. Stim has no ECR instruction, and the canonical decomposition goes through non-CliffordRZX(+-pi/4).CanonicalRewrite: any other operation.
A
GateRX,GateRYorGateRZby any other angle is not a Clifford gate and raisesDecompositionError; so does any non-Clifford gate that reduces to one, such asGateT. UseCliffordTBasisfor such circuits.The terminal operations are:
single-qubit Cliffords:
GateID,GateX,GateY,GateZ,GateH,GateHXY,GateHYZ,GateS,GateSDG,GateSX,GateSXDG,GateSYandGateSYDG;two-qubit Cliffords:
GateCX,GateCY,GateCZ,GateSWAP,GateISWAP,GateISWAPDGandGateDCX;Pauli rotations by
+-pi/2:GateRXX,GateRYY,GateRZZ, andRPauliwith a non-identity Pauli string. Angles are compared modulo2*pi, since a rotation by3*pi/2equals one by-pi/2up to a global phase. Other angles are decomposed;measurements in any Pauli basis:
Measure,MeasureX,MeasureY,MeasureXX,MeasureYY,MeasureZZandMeasurePauli;resets and measure-and-resets in the Z, X and Y bases:
Reset,ResetX,ResetY,MeasureReset,MeasureResetXandMeasureResetY;Pauli noise:
PauliX,PauliY,PauliZ,Depolarizing1,Depolarizing2andPauliNoise;Barrierand annotations, includingDetector,ObservableIncludeandQubitCoordinates;feedback: an
IfStatementofGateX,GateYorGateZconditioned on a single bit being1.
The same Pauli conditioned on a bit being
0becomes the Pauli followed by the Pauli conditioned on1. Any other conditional operation has its body decomposed while staying conditional, and raisesDecompositionErrorif that does not lead to conditional Paulis.The terminal operations correspond to Stim instructions as follows.
MIMIQ Operation
Stim Operation
GateIDIGateXXGateYYGateZZGateHHGateHXYH_XYGateHYZH_YZGateSSGateSDGS_DAGGateSXSQRT_XGateSXDGSQRT_X_DAGGateSYSQRT_YGateSYDGSQRT_Y_DAGGateCXCNOT/CXGateCYCYGateCZCZGateSWAPSWAPGateISWAPISWAPGateISWAPDGISWAP_DAGGateDCXSWAPCXGateRXX(+-pi/2)SQRT_XX/SQRT_XX_DAGGateRYY(+-pi/2)SQRT_YY/SQRT_YY_DAGGateRZZ(+-pi/2)SQRT_ZZ/SQRT_ZZ_DAGRPauli(P, +-pi/2)SPP/SPP_DAGIfStatement(GateX(), 1)CX rec[-k] qIfStatement(GateY(), 1)CY rec[-k] qIfStatement(GateZ(), 1)CZ rec[-k] qMeasureMMeasureXMXMeasureYMYMeasureXXMXXMeasureYYMYYMeasureZZMZZMeasurePauliMPPResetRResetXRXResetYRYMeasureResetMRMeasureResetXMRXMeasureResetYMRYPauliXX_ERRORPauliYY_ERRORPauliZZ_ERRORDepolarizing1DEPOLARIZE1Depolarizing2DEPOLARIZE2PauliNoisePAULI_CHANNEL_1,PAULI_CHANNEL_2orE/ELSE_CORRELATED_ERRORDetectorDETECTORObservableIncludeOBSERVABLE_INCLUDEQubitCoordinatesQUBIT_COORDSGateECRis terminal as a Clifford gate but has no Stim instruction of its own.Examples
>>> from mimiqcircuits import * >>> from symengine import pi >>> c = Circuit() >>> c.push(GateRY(pi/2), 0) 1-qubit circuit with 1 instruction: └── RY((1/2)*pi) @ q[0] >>> c.push(GateCX(), 0, 1) 2-qubit circuit with 2 instructions: ├── RY((1/2)*pi) @ q[0] └── CX @ q[0], q[1] >>> # RY(pi/2) is the Clifford SY; CX is already a Stim gate >>> decompose(c, StimBasis()) 2-qubit circuit with 2 instructions: ├── SY @ q[0] └── CX @ q[0], q[1]
>>> # a T gate is not a Clifford gate and is refused >>> c = Circuit() >>> c.push(GateT(), 0) 1-qubit circuit with 1 instruction: └── T @ q[0] >>> decompose(c, StimBasis()) Traceback (most recent call last): ... mimiqcircuits.decomposition.abstract.DecompositionError: Rotation RZ cannot be decomposed into the Stim basis. Only rotations with angles that are multiples of pi/2 are Clifford gates.
See also
- decompose(op, qubits, bits, zvars)[source]¶
Rewrite a non-terminal operation one step toward the Stim gate set.
Applies the first matching rule of the list in the class description. A conditional operation is handled as described there.
- Parameters:
- Returns:
A new
Circuitwith the rewrite.- Raises:
DecompositionError – If
opis a rotation by an angle that is not a multiple ofpi/2, a conditional operation Stim cannot express, or has no built-in decomposition.- Return type:
Modules
Canonical decomposition basis targeting GateU and GateCX. |
|
Clifford+T decomposition basis. |
|
Flattened decomposition basis. |
|
OpenQASM 2.0 decomposition basis. |
|
RuleBasis: Wrapper to use a RewriteRule as a DecompositionBasis. |
|
Stim stabilizer simulator decomposition basis. |