From ede93be2f3fa4b063552f2836af58a22ac293bc2 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sun, 29 Dec 2024 06:30:37 +0000 Subject: [PATCH] build based on 3297023 --- dev/.documenter-siteinfo.json | 2 +- dev/API/index.html | 142 ++++++++++---------- dev/ECC_API/index.html | 18 +-- dev/ECC_evaluating/2ed4ea99.png | Bin 0 -> 42752 bytes dev/ECC_evaluating/438ab177.png | Bin 42533 -> 0 bytes dev/ECC_evaluating/8541d19e.png | Bin 0 -> 55472 bytes dev/ECC_evaluating/9c5c1fd2.png | Bin 55151 -> 0 bytes dev/ECC_evaluating/index.html | 4 +- dev/allops/index.html | 2 +- dev/canonicalization/13e138a3.png | Bin 9895 -> 0 bytes dev/canonicalization/3a263328.png | Bin 9442 -> 0 bytes dev/canonicalization/5cef4748.png | Bin 0 -> 9770 bytes dev/canonicalization/7d7b216e.png | Bin 0 -> 9476 bytes dev/canonicalization/af461151.png | Bin 9717 -> 0 bytes dev/canonicalization/b9097138.png | Bin 0 -> 9805 bytes dev/canonicalization/c8c9a5da.png | Bin 9806 -> 0 bytes dev/canonicalization/dea66803.png | Bin 0 -> 9906 bytes dev/canonicalization/index.html | 8 +- dev/commonstates/index.html | 2 +- dev/datastructures/index.html | 2 +- dev/ecc_example_sim/index.html | 6 +- dev/graphs/index.html | 2 +- dev/index.html | 2 +- dev/mixed/index.html | 2 +- dev/noise/index.html | 2 +- dev/noisycircuits/index.html | 2 +- dev/noisycircuits_API/index.html | 2 +- dev/noisycircuits_mc/index.html | 4 +- dev/noisycircuits_ops/index.html | 2 +- dev/noisycircuits_perturb/index.html | 4 +- dev/objects.inv | Bin 6558 -> 6558 bytes dev/plotting/{a44cea28.svg => 25819685.svg} | 12 +- dev/plotting/{3be57790.svg => 512c1ac5.svg} | 12 +- dev/plotting/{7b673675.svg => 69471e53.svg} | 12 +- dev/plotting/{1fed49ed.svg => c4d07dc6.svg} | 12 +- dev/plotting/{76b9fb44.svg => db4a1c9e.svg} | 12 +- dev/plotting/index.html | 12 +- dev/references/index.html | 2 +- dev/stab-algebra-manual/index.html | 2 +- dev/tutandpub/index.html | 2 +- 40 files changed, 143 insertions(+), 143 deletions(-) create mode 100644 dev/ECC_evaluating/2ed4ea99.png delete mode 100644 dev/ECC_evaluating/438ab177.png create mode 100644 dev/ECC_evaluating/8541d19e.png delete mode 100644 dev/ECC_evaluating/9c5c1fd2.png delete mode 100644 dev/canonicalization/13e138a3.png delete mode 100644 dev/canonicalization/3a263328.png create mode 100644 dev/canonicalization/5cef4748.png create mode 100644 dev/canonicalization/7d7b216e.png delete mode 100644 dev/canonicalization/af461151.png create mode 100644 dev/canonicalization/b9097138.png delete mode 100644 dev/canonicalization/c8c9a5da.png create mode 100644 dev/canonicalization/dea66803.png rename dev/plotting/{a44cea28.svg => 25819685.svg} (98%) rename dev/plotting/{3be57790.svg => 512c1ac5.svg} (99%) rename dev/plotting/{7b673675.svg => 69471e53.svg} (99%) rename dev/plotting/{1fed49ed.svg => c4d07dc6.svg} (98%) rename dev/plotting/{76b9fb44.svg => db4a1c9e.svg} (98%) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index dd75437bc..13e261f50 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-21T22:35:13","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-29T06:30:29","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/API/index.html b/dev/API/index.html index 14b6d401a..b74beff33 100644 --- a/dev/API/index.html +++ b/dev/API/index.html @@ -4,7 +4,7 @@ padding-top: 0 !important; padding-bottom: 0 !important; } -

States

Stabilizer states can be represented with the Stabilizer, Destabilizer, MixedStabilizer, and MixedDestabilizer tableau data structures. You probably want to use MixedDestabilizer which supports the widest set of operations.

Moreover, a MixedDestabilizer can be stored inside a Register together with a set of classical bits in which measurement results can be written.

Lastly, for Pauli frame simulations there is the PauliFrame type, a tableau in which each row represents a different Pauli frame.

There are convenience constructors for common types of states and operators.

Operations

Acting on quantum states can be performed either:

See the full list of operations for a list of implemented operations.

Autogenerated API list

QuantumClifford.QuantumClifford — Module

A module for using the Stabilizer formalism and simulating Clifford circuits.

source
QuantumClifford.continue_stat — Constant

Returned by applywstatus! if the circuit simulation should continue.

source
QuantumClifford.failure_stat — Constant

Returned by applywstatus! if the circuit reports a failure.

See also: VerifyOp, BellMeasurement.

source
QuantumClifford.false_success_stat — Constant

Returned by applywstatus! if the circuit reports a success, but it is a false positive (i.e., there was an undetected error).

See also: VerifyOp, BellMeasurement.

source
QuantumClifford.true_success_stat — Constant

Returned by applywstatus! if the circuit reports a success and there is no undetected error.

See also: VerifyOp, BellMeasurement.

source
QuantumClifford.AbstractSingleQubitOperator — Type

Supertype of all single-qubit symbolic operators.

source
QuantumClifford.AbstractSymbolicOperator — Type

Supertype of all symbolic operators. Subtype of AbstractCliffordOperator

source
QuantumClifford.AbstractTwoQubitOperator — Type

Supertype of all two-qubit symbolic operators.

source
QuantumClifford.BellMeasurement — Type

A Bell measurement performing the correlation measurement corresponding to the given pauli projections on the qubits at the selected indices.

source
QuantumClifford.CircuitStatus — Type

A convenience struct to represent the status of a circuit simulated by mctrajectories

source
QuantumClifford.ClassicalXOR — Type

Applies an XOR gate to classical bits. Currently only implemented for functionality with pauli frames.

source
QuantumClifford.CliffordOperator — Type

Clifford Operator specified by the mapping of the basis generators.

julia> tCNOT
+
States
Stabilizer states can be represented with the Stabilizer, Destabilizer, MixedStabilizer, and MixedDestabilizer tableau data structures. You probably want to use MixedDestabilizer which supports the widest set of operations.
Moreover, a MixedDestabilizer can be stored inside a Register together with a set of classical bits in which measurement results can be written.
Lastly, for Pauli frame simulations there is the PauliFrame type, a tableau in which each row represents a different Pauli frame.
There are convenience constructors for common types of states and operators.
Operations
Acting on quantum states can be performed either:
  • In a "linear algebra" language where unitaries, measurements, and other operations have separate interfaces. This is an explicitly deterministic lower-level interface, which provides a great deal of control over how tableaux are manipulated. See the Stabilizer Tableau Algebra Manual as a primer on these approaches.
  • Or in a "circuit" language, where the operators (and measurements and noise) are represented as circuit gates. This is a higher-level interface in which the outcome of an operation can be stochastic. The API for it is centered around the apply! function. Particularly useful for Monte Carlo simulations and Perturbative Expansion Symbolic Results.
See the full list of operations for a list of implemented operations.
Autogenerated API list
QuantumClifford.BellMeasurement — Type
A Bell measurement performing the correlation measurement corresponding to the given pauli projections on the qubits at the selected indices.
source
QuantumClifford.CliffordOperator — Type
Clifford Operator specified by the mapping of the basis generators.
julia> tCNOT
 X₁ ⟼ + XX
 X₂ ⟼ + _X
 Z₁ ⟼ + Z_
@@ -33,12 +33,12 @@
 
 julia> CliffordOperator(d)
 X₁ ⟼ + Z
-Z₁ ⟼ + Y
source
QuantumClifford.Destabilizer — Type
A tableau representation of a pure stabilizer state. The tableau tracks the destabilizers as well, for efficient projections. On initialization there are no checks that the provided state is indeed pure. This enables the use of this data structure for mixed stabilizer state, but a better choice would be to use MixedDestabilizer.
source
QuantumClifford.MixedDestabilizer — Type
A tableau representation for mixed stabilizer states that keeps track of the destabilizers in order to provide efficient projection operations.
The rank r of the n-qubit tableau is tracked, either so that it can be used to represent a mixed stabilizer state, or so that it can be used to represent an n-r logical-qubit code over n physical qubits. The "logical" operators are tracked as well.
When the constructor is called on an incomplete Stabilizer it automatically calculates the destabilizers and logical operators, following chapter 4 of (Gottesman, 1997). Under the hood the conversion uses the canonicalize_gott! canonicalization. That canonicalization permutes the columns of the tableau, but we automatically undo the column permutation in the preparation of a MixedDestabilizer so that qubits are not reindexed. The boolean keyword arguments undoperm and reportperm can be used to control this behavior and to report the permutations explicitly.
See also: stabilizerview, destabilizerview, logicalxview, logicalzview
source
QuantumClifford.PauliFrame — Type
struct PauliFrame{T, S} <: QuantumClifford.AbstractQCState
This is a wrapper around a tableau. This "frame" tableau is not to be viewed as a normal stabilizer tableau, although it does conjugate the same under Clifford operations. Each row in the tableau refers to a single frame. The row represents the Pauli operation by which the frame and the reference differ.
source
QuantumClifford.Destabilizer — Type
A tableau representation of a pure stabilizer state. The tableau tracks the destabilizers as well, for efficient projections. On initialization there are no checks that the provided state is indeed pure. This enables the use of this data structure for mixed stabilizer state, but a better choice would be to use MixedDestabilizer.
source
QuantumClifford.MixedDestabilizer — Type
A tableau representation for mixed stabilizer states that keeps track of the destabilizers in order to provide efficient projection operations.
The rank r of the n-qubit tableau is tracked, either so that it can be used to represent a mixed stabilizer state, or so that it can be used to represent an n-r logical-qubit code over n physical qubits. The "logical" operators are tracked as well.
When the constructor is called on an incomplete Stabilizer it automatically calculates the destabilizers and logical operators, following chapter 4 of (Gottesman, 1997). Under the hood the conversion uses the canonicalize_gott! canonicalization. That canonicalization permutes the columns of the tableau, but we automatically undo the column permutation in the preparation of a MixedDestabilizer so that qubits are not reindexed. The boolean keyword arguments undoperm and reportperm can be used to control this behavior and to report the permutations explicitly.
See also: stabilizerview, destabilizerview, logicalxview, logicalzview
source
QuantumClifford.PauliFrame — Type
struct PauliFrame{T, S} <: QuantumClifford.AbstractQCState
This is a wrapper around a tableau. This "frame" tableau is not to be viewed as a normal stabilizer tableau, although it does conjugate the same under Clifford operations. Each row in the tableau refers to a single frame. The row represents the Pauli operation by which the frame and the reference differ.
source
QuantumClifford.PauliFrame — Method
PauliFrame(
     frames,
     qubits,
     measurements
 ) -> PauliFrame{Stabilizer{QuantumClifford.Tableau{Vector{UInt8}, LinearAlgebra.Adjoint{UInt64, Matrix{UInt64}}}}}
-
Prepare an empty set of Pauli frames with the given number of frames and qubits. Preallocates spaces for measurement number of measurements.
source
QuantumClifford.PauliOperator — Type
A multi-qubit Pauli operator ($±\{1,i\}\{I,Z,X,Y\}^{\otimes n}$).
A Pauli can be constructed with the P custom string macro or by building up one through products and tensor products of smaller operators.
julia> pauli3 = P"-iXYZ"
+
Prepare an empty set of Pauli frames with the given number of frames and qubits. Preallocates spaces for measurement number of measurements.
source
QuantumClifford.PauliOperator — Type
A multi-qubit Pauli operator ($±\{1,i\}\{I,Z,X,Y\}^{\otimes n}$).
A Pauli can be constructed with the P custom string macro or by building up one through products and tensor products of smaller operators.
julia> pauli3 = P"-iXYZ"
 -iXYZ
 
 julia> pauli4 = 1im * pauli3 ⊗ X
@@ -55,7 +55,7 @@
 (true, false)
 
 julia> p[1] = (true, true); p
-+ YYZ
source
QuantumClifford.Register — Type
A register, representing the state of a computer including both a tableaux and an array of classical bits (e.g. for storing measurement results)
source
QuantumClifford.Reset — Type
Reset the specified qubits to the given state.
Be careful, this operation implies first tracing out the qubits, which can lead to mixed states if these qubits were entangled with the rest of the system.
See also: sMRZ
source
QuantumClifford.SingleQubitOperator — Type
A "symbolic" general single-qubit operator which permits faster multiplication than an operator expressed as an explicit tableau.
julia> op = SingleQubitOperator(2, true, true, true, false, true, true) # Tableau components and phases
++ YYZ
source
QuantumClifford.Register — Type
A register, representing the state of a computer including both a tableaux and an array of classical bits (e.g. for storing measurement results)
source
QuantumClifford.Reset — Type
Reset the specified qubits to the given state.
Be careful, this operation implies first tracing out the qubits, which can lead to mixed states if these qubits were entangled with the rest of the system.
See also: sMRZ
source
QuantumClifford.SingleQubitOperator — Type
A "symbolic" general single-qubit operator which permits faster multiplication than an operator expressed as an explicit tableau.
julia> op = SingleQubitOperator(2, true, true, true, false, true, true) # Tableau components and phases
 SingleQubitOperator on qubit 2
 X₁ ⟼ - Y
 Z₁ ⟼ - X
@@ -76,7 +76,7 @@
 
 julia> CliffordOperator(op, 1, compact=true) # You can also extract just the non-trivial part of the tableau
 X₁ ⟼ - Y
-Z₁ ⟼ - X
See also: sHadamard, sPhase, sId1, sX, sY, sZ, CliffordOperator
Or simply consult subtypes(QuantumClifford.AbstractSingleQubitOperator) and subtypes(QuantumClifford.AbstractTwoQubitOperator) for a full list. You can think of the s prefix as "symbolic" or "sparse".
source
QuantumClifford.SparseGate — Type
A Clifford gate, applying the given cliff operator to the qubits at the selected indices.
apply!(state, cliff, indices) and apply!(state, SparseGate(cliff, indices)) give the same result.
source
QuantumClifford.StabMixture — Type
mutable struct StabMixture{T, F}
Represents mixture ∑ ϕᵢⱼ Pᵢ ρ Pⱼ† where ρ is a pure stabilizer state.
julia> StabMixture(S"-X")
+Z₁ ⟼ - X
See also: sHadamard, sPhase, sId1, sX, sY, sZ, CliffordOperator
Or simply consult subtypes(QuantumClifford.AbstractSingleQubitOperator) and subtypes(QuantumClifford.AbstractTwoQubitOperator) for a full list. You can think of the s prefix as "symbolic" or "sparse".
source
QuantumClifford.SparseGate — Type
A Clifford gate, applying the given cliff operator to the qubits at the selected indices.
apply!(state, cliff, indices) and apply!(state, SparseGate(cliff, indices)) give the same result.
source
QuantumClifford.StabMixture — Type
mutable struct StabMixture{T, F}
Represents mixture ∑ ϕᵢⱼ Pᵢ ρ Pⱼ† where ρ is a pure stabilizer state.
julia> StabMixture(S"-X")
 A mixture ∑ ϕᵢⱼ Pᵢ ρ Pⱼ† where ρ is
 𝒟ℯ𝓈𝓉𝒶𝒷
 + Z
@@ -101,7 +101,7 @@
  0.0+0.353553im | + _ | + Z
  0.0-0.353553im | + Z | + _
  0.853553+0.0im | + _ | + _
- 0.146447+0.0im | + Z | + Z
See also: PauliChannel
source
QuantumClifford.Stabilizer — Type
Stabilizer, i.e. a list of commuting multi-qubit Hermitian Pauli operators.
Instances can be created with the S custom string macro or as direct sum of other stabilizers.
Stabilizers and Destabilizers
In many cases you probably would prefer to use the MixedDestabilizer data structure, as it caries a lot of useful additional information, like tracking rank and destabilizer operators. Stabilizer has mostly a pedagogical value, and it is also used for slightly faster simulation of a particular subset of Clifford operations.
julia> s = S"XXX
+ 0.146447+0.0im | + Z | + Z
See also: PauliChannel
source
QuantumClifford.Stabilizer — Type
Stabilizer, i.e. a list of commuting multi-qubit Hermitian Pauli operators.
Instances can be created with the S custom string macro or as direct sum of other stabilizers.
Stabilizers and Destabilizers
In many cases you probably would prefer to use the MixedDestabilizer data structure, as it caries a lot of useful additional information, like tracking rank and destabilizer operators. Stabilizer has mostly a pedagogical value, and it is also used for slightly faster simulation of a particular subset of Clifford operations.
julia> s = S"XXX
              ZZI
              IZZ"
 + XXX
@@ -134,7 +134,7 @@
 
 julia> s[1,1] = (true, false); s
 + X_
-+ __
There are no automatic checks for correctness (i.e. independence of all rows, commutativity of all rows, hermiticity of all rows). The rank (number of rows) is permitted to be less than the number of qubits (number of columns): canonilization, projection, etc. continue working in that case. To great extent this library uses the Stabilizer data structure simply as a tableau. This might be properly abstracted away in future versions.
See also: PauliOperator, canonicalize!
source
QuantumClifford.UnitaryPauliChannel — Type
A Pauli channel datastructure, mainly for use with StabMixture.
More convenient to use than PauliChannel when you know your Pauli channel is unitary.
julia> Tgate = UnitaryPauliChannel(
++ __
There are no automatic checks for correctness (i.e. independence of all rows, commutativity of all rows, hermiticity of all rows). The rank (number of rows) is permitted to be less than the number of qubits (number of columns): canonilization, projection, etc. continue working in that case. To great extent this library uses the Stabilizer data structure simply as a tableau. This might be properly abstracted away in future versions.
See also: PauliOperator, canonicalize!
source
QuantumClifford.UnitaryPauliChannel — Type
A Pauli channel datastructure, mainly for use with StabMixture.
More convenient to use than PauliChannel when you know your Pauli channel is unitary.
julia> Tgate = UnitaryPauliChannel(
            (I, Z),
            ((1+exp(im*π/4))/2, (1-exp(im*π/4))/2)
        )
@@ -149,7 +149,7 @@
  0.853553+0.0im | + _ | + _
  0.0+0.353553im | + _ | + Z
  0.0-0.353553im | + Z | + _
- 0.146447+0.0im | + Z | + Z
source
QuantumClifford.VerifyOp — Type
A "probe" to verify that the state of the qubits corresponds to a desired good_state, e.g. at the end of the execution of a circuit.
source
QuantumClifford.sMRZ — Type
Measure a qubit in the Z basis and reset to the |0⟩ state.
It does not trace out the qubit!
As described below there is a difference between measuring the qubit (followed by setting it to a given known state) and "tracing out" the qubit. By reset here we mean "measuring and setting to a known state", not "tracing out".
julia> s = MixedDestabilizer(S"XXX ZZI IZZ") # |000⟩+|111⟩
+ 0.146447+0.0im | + Z | + Z
source
QuantumClifford.VerifyOp — Type
A "probe" to verify that the state of the qubits corresponds to a desired good_state, e.g. at the end of the execution of a circuit.
source
QuantumClifford.sMRZ — Type
Measure a qubit in the Z basis and reset to the |0⟩ state.
It does not trace out the qubit!
As described below there is a difference between measuring the qubit (followed by setting it to a given known state) and "tracing out" the qubit. By reset here we mean "measuring and setting to a known state", not "tracing out".
julia> s = MixedDestabilizer(S"XXX ZZI IZZ") # |000⟩+|111⟩
 𝒟ℯ𝓈𝓉𝒶𝒷
 + Z__
 + _X_
@@ -199,7 +199,7 @@
 𝒮𝓉𝒶𝒷━
 + Z__
 - ZZ_
-- Z_Z
See also: Reset, sMZ
source
QuantumClifford.PauliError — Function
A convenient constructor for various types of Pauli errors, that can be used as circuit gates in simulations. Returns more specific types when necessary.
source
QuantumClifford.PauliError — Method
"Construct a gate operation that applies a biased Pauli error on all qubits independently, each with  probabilities px, py, pz. Note that the probability of any error occurring is px+py+pz. Because of this, PauliError(1, p) is equivalent to PauliError(1,p/3,p/3,p/3). Similarly, if one wanted to exclude Z errors from PauliError(1,p/3,p/3,p/3) while mainting the same rate of X errors, one could write PauliError(1, p*2/3, 0, 0) (in the sense that Y errors can be interpreted as an X and a Z happening at the same time).
source
QuantumClifford.PauliError — Method
"Construct a gate operation that applies a biased Pauli error on  qubit q with independent probabilities px, py, pz. Note that the probability of any error occurring is px+py+pz. Because of this, PauliError(1, p) is equivalent to PauliError(1,p/3,p/3,p/3). Similarly, if one wanted to exclude Z errors from PauliError(1,p/3,p/3,p/3) while mainting the same rate of X errors, one could write PauliError(1, p*2/3, 0, 0) (in the sense that Y errors can be interpreted as an X and a Z happening at the same time).
source
QuantumClifford.applybranches — Function
Compute all possible new states after the application of the given operator. Reports the probability of each one of them. Deterministic (as it reports all branches of potentially random processes), part of the Perturbative Expansion interface.
source
QuantumClifford.applynoise! — Function
A method modifying a given state by applying the corresponding noise model. It is non-deterministic, part of the Noise interface.
source
QuantumClifford.PauliError — Function
A convenient constructor for various types of Pauli errors, that can be used as circuit gates in simulations. Returns more specific types when necessary.
source
QuantumClifford.PauliError — Method
"Construct a gate operation that applies a biased Pauli error on all qubits independently, each with  probabilities px, py, pz. Note that the probability of any error occurring is px+py+pz. Because of this, PauliError(1, p) is equivalent to PauliError(1,p/3,p/3,p/3). Similarly, if one wanted to exclude Z errors from PauliError(1,p/3,p/3,p/3) while mainting the same rate of X errors, one could write PauliError(1, p*2/3, 0, 0) (in the sense that Y errors can be interpreted as an X and a Z happening at the same time).
source
QuantumClifford.PauliError — Method
"Construct a gate operation that applies a biased Pauli error on  qubit q with independent probabilities px, py, pz. Note that the probability of any error occurring is px+py+pz. Because of this, PauliError(1, p) is equivalent to PauliError(1,p/3,p/3,p/3). Similarly, if one wanted to exclude Z errors from PauliError(1,p/3,p/3,p/3) while mainting the same rate of X errors, one could write PauliError(1, p*2/3, 0, 0) (in the sense that Y errors can be interpreted as an X and a Z happening at the same time).
source
QuantumClifford.applybranches — Function
Compute all possible new states after the application of the given operator. Reports the probability of each one of them. Deterministic (as it reports all branches of potentially random processes), part of the Perturbative Expansion interface.
source
QuantumClifford.applynoise! — Function
A method modifying a given state by applying the corresponding noise model. It is non-deterministic, part of the Noise interface.
source
QuantumClifford.bell — Function
Prepare one or more Bell pairs (with optional phases).
julia> bell()
 + XX
 + ZZ
 
@@ -217,11 +217,11 @@
 - XX__
 + ZZ__
 - __XX
-- __ZZ
source
QuantumClifford.bigram — Method
bigram(
     state::QuantumClifford.AbstractStabilizer;
     clip
 ) -> Matrix{Int64}
-
Get the bigram of a tableau.
It is the list of endpoints of a tableau in the clipped gauge.
If clip=true (the default) the tableau is converted to the clipped gauge in-place before calculating the bigram. Otherwise, the clip gauge conversion is skipped (for cases where the input is already known to be in the correct gauge).
Introduced in (Nahum et al., 2017), with a more detailed explanation of the algorithm in (Li et al., 2019) and (Gullans et al., 2021).
See also: canonicalize_clip!
source
QuantumClifford.canonicalize! — Method
canonicalize!(
+
Get the bigram of a tableau.
It is the list of endpoints of a tableau in the clipped gauge.
If clip=true (the default) the tableau is converted to the clipped gauge in-place before calculating the bigram. Otherwise, the clip gauge conversion is skipped (for cases where the input is already known to be in the correct gauge).
Introduced in (Nahum et al., 2017), with a more detailed explanation of the algorithm in (Li et al., 2019) and (Gullans et al., 2021).
See also: canonicalize_clip!
source
QuantumClifford.canonicalize_clip! — Method
canonicalize_clip!(
     state::QuantumClifford.AbstractStabilizer;
     phases
 ) -> QuantumClifford.AbstractStabilizer
@@ -294,7 +294,7 @@
 + _XZX__
 - _ZYX_Z
 - __YZ_X
-- ____Z_
If phases=false is set, the canonicalization does not track the phases in the tableau, leading to a significant speedup.
Introduced in (Nahum et al., 2017), with a more detailed explanation of the algorithm in Appendix A of (Li et al., 2019)
See also: canonicalize!, canonicalize_rref!, canonicalize_gott!.
source
QuantumClifford.canonicalize_gott! — Method
Inplace Gottesman canonicalization of a tableau.
This uses different canonical form from canonicalize!. It is used in the computation of the logical X and Z operators of a MixedDestabilizer.
It returns the (in place) modified state, the indices of the last pivot of both Gaussian elimination steps, and the permutations that have been used to put the X and Z tableaux in standard form.
Based on (Gottesman, 1997).
See also: canonicalize!, canonicalize_rref!
source
QuantumClifford.canonicalize_noncomm — Method
For a not-necessarily commutative set of Paulis, return a generating set of the form ⟨A₁, A₂, ... Aₖ, Aₖ₊₁, ... Aₘ, B₁, B₂, ... Bₖ⟩ where pairs Aₖ, Bₖ anticommute and all other pairings commute. Based on (Terhal, 2015)
Returns the generating set as a data structure of type SubsystemCodeTableau. The logicalxview function returns the ⟨A₁, A₂,... Aₖ⟩, and the logicalzview function returns ⟨B₁, B₂, ... Bₖ⟩. stabilizerview returns ⟨Aₖ₊₁, ... Aₘ⟩ as a Stabilizer, and destabilizerview returns the Destabilizer of that Stabilizer.
Phases are zeroed-out in this canonicalization.
julia> canonicalize_noncomm(T"XX XZ XY")
+- ____Z_
If phases=false is set, the canonicalization does not track the phases in the tableau, leading to a significant speedup.
Introduced in (Nahum et al., 2017), with a more detailed explanation of the algorithm in Appendix A of (Li et al., 2019)
See also: canonicalize!, canonicalize_rref!, canonicalize_gott!.
source
QuantumClifford.canonicalize_gott! — Method
Inplace Gottesman canonicalization of a tableau.
This uses different canonical form from canonicalize!. It is used in the computation of the logical X and Z operators of a MixedDestabilizer.
It returns the (in place) modified state, the indices of the last pivot of both Gaussian elimination steps, and the permutations that have been used to put the X and Z tableaux in standard form.
Based on (Gottesman, 1997).
See also: canonicalize!, canonicalize_rref!
source
QuantumClifford.canonicalize_noncomm — Method
For a not-necessarily commutative set of Paulis, return a generating set of the form ⟨A₁, A₂, ... Aₖ, Aₖ₊₁, ... Aₘ, B₁, B₂, ... Bₖ⟩ where pairs Aₖ, Bₖ anticommute and all other pairings commute. Based on (Terhal, 2015)
Returns the generating set as a data structure of type SubsystemCodeTableau. The logicalxview function returns the ⟨A₁, A₂,... Aₖ⟩, and the logicalzview function returns ⟨B₁, B₂, ... Bₖ⟩. stabilizerview returns ⟨Aₖ₊₁, ... Aₘ⟩ as a Stabilizer, and destabilizerview returns the Destabilizer of that Stabilizer.
Phases are zeroed-out in this canonicalization.
julia> canonicalize_noncomm(T"XX XZ XY")
 𝒟ℯ𝓈𝓉𝒶𝒷
 + Z_
 𝒳━━
@@ -302,38 +302,38 @@
 𝒮𝓉𝒶𝒷
 + X_
 𝒵━━
-+ XZ
source
QuantumClifford.canonicalize_rref! — Method
canonicalize_rref!(
     state::QuantumClifford.AbstractStabilizer,
     colindices;
     phases
 ) -> Tuple{QuantumClifford.AbstractStabilizer, Any}
-
Canonicalize a stabilizer (in place) along only some columns.
This uses different canonical form from canonicalize!. It also indexes in reverse in order to make its use in traceout! more efficient. Its use in traceout! is its main application.
It returns the (in place) modified state and the index of the last pivot.
Based on (Audenaert and Plenio, 2005).
See also: canonicalize!, canonicalize_gott!
source
QuantumClifford.centralizer — Method
For a given set of Paulis (in the form of a Tableau), return the subset of Paulis that commute with all Paulis in set.
julia> centralizer(T"XX ZZ _Z")
-+ ZZ
source
QuantumClifford.clifford_cardinality — Method
The size of the Clifford group 𝒞 over a given number of qubits, possibly modulo the phases.
For n qubits, not accounting for phases is 2ⁿⁿΠⱼ₌₁ⁿ(4ʲ-1). There are 4ⁿ different phase configurations.
julia> clifford_cardinality(7)
+
source
QuantumClifford.centralizer — Method
For a given set of Paulis (in the form of a Tableau), return the subset of Paulis that commute with all Paulis in set.
julia> centralizer(T"XX ZZ _Z")
++ ZZ
source
QuantumClifford.clifford_cardinality — Method
The size of the Clifford group 𝒞 over a given number of qubits, possibly modulo the phases.
For n qubits, not accounting for phases is 2ⁿⁿΠⱼ₌₁ⁿ(4ʲ-1). There are 4ⁿ different phase configurations.
julia> clifford_cardinality(7)
 457620995529680351512370381586432000
When not accounting for phases (phases = false) the result is the same as the size of the Symplectic group Sp(2n) ≡ 𝒞ₙ/𝒫ₙ, where 𝒫ₙ is the Pauli group over n qubits.
julia> clifford_cardinality(7, phases=false)
-27930968965434591767112450048000
See also: enumerate_cliffords.
source
QuantumClifford.comm — Function
Check whether two operators commute.
0x0 if they commute, 0x1 if they anticommute.
julia> P"XX"*P"ZZ", P"ZZ"*P"XX"
 (- YY, - YY)
 
 julia> comm(P"ZZ", P"XX")
 0x00
 
 julia> comm(P"IZ", P"XX")
-0x01
See also: comm!
source
QuantumClifford.commutify — Method
For a not-necessarily commutative set of Paulis S, computed S', the non-commutative canonical form of of S. For each pair Aₖ, Bₖ of anticommutative Paulis in S', add a qubit to each Pauli in the set: X to Aₖ, Z to Bₖ, and I to each other operator to produce S'', a fully commutative set. Return S'' as well as a list of the indices of the added qubits.
The returned object is a Stabilizer that is also useful for the matroid_parent function.
julia> commutify(T"XX XZ XY")[1]
+0x01
See also: comm!
source
QuantumClifford.commutify — Method
For a not-necessarily commutative set of Paulis S, computed S', the non-commutative canonical form of of S. For each pair Aₖ, Bₖ of anticommutative Paulis in S', add a qubit to each Pauli in the set: X to Aₖ, Z to Bₖ, and I to each other operator to produce S'', a fully commutative set. Return S'' as well as a list of the indices of the added qubits.
The returned object is a Stabilizer that is also useful for the matroid_parent function.
julia> commutify(T"XX XZ XY")[1]
 + XXX
 + X__
 + XZZ
 
 julia> commutify(T"XX XZ XY")[2]
-3:3
source
QuantumClifford.compactify_circuit — Method
Convert a list of gates to a more optimized "sum type" format which permits faster dispatch.
Generally, this should be called on a circuit before it is used in a simulation.
source
QuantumClifford.contractor — Method
Return the subset of Paulis in a Stabilizer that have identity operators on all qubits corresponding to the given subset, without the entries corresponding to subset. Based on (Goodenough et al., 2024)
julia> contractor(S"_X X_", [1])
-+ X
source
QuantumClifford.delete_columns — Method
Return the given stabilizer without all the qubits in the given iterable.
The resulting tableaux is not guaranteed to be valid (to retain its commutation relationships).
julia> delete_columns(S"XYZ YZX ZXY", [1,3])
+3:3
source
QuantumClifford.compactify_circuit — Method
Convert a list of gates to a more optimized "sum type" format which permits faster dispatch.
Generally, this should be called on a circuit before it is used in a simulation.
source
QuantumClifford.contractor — Method
Return the subset of Paulis in a Stabilizer that have identity operators on all qubits corresponding to the given subset, without the entries corresponding to subset. Based on (Goodenough et al., 2024)
julia> contractor(S"_X X_", [1])
++ X
source
QuantumClifford.delete_columns — Method
Return the given stabilizer without all the qubits in the given iterable.
The resulting tableaux is not guaranteed to be valid (to retain its commutation relationships).
julia> delete_columns(S"XYZ YZX ZXY", [1,3])
 + Y
 + Z
-+ X
See also: traceout!
source
QuantumClifford.enumerate_single_qubit_gates — Method
Generate a symbolic single-qubit gate given its index. Optionally, set non-trivial phases.
julia> enumerate_single_qubit_gates(6)
 sPhase on qubit 1
 X₁ ⟼ + Y
 Z₁ ⟼ + Z
@@ -341,7 +341,7 @@
 julia> enumerate_single_qubit_gates(6, qubit=2, phases=(true, true))
 SingleQubitOperator on qubit 2
 X₁ ⟼ - Y
-Z₁ ⟼ - Z
See also: enumerate_cliffords.
source
QuantumClifford.fastcolumn — Function
Convert a tableau to a memory layout that is fast for column operations.
In this layout a column of the tableau is stored (mostly) contiguously in memory. Due to bitpacking, e.g., packing 64 bits into a single UInt64, the memory layout is not perfectly contiguous, but it is still optimal given that some bitwrangling is required to extract a given bit.
See also: fastrow
source
QuantumClifford.fastrow — Function
Convert a tableau to a memory layout that is fast for row operations.
In this layout a Pauli string (a row of the tableau) is stored contiguously in memory.
See also: fastrow
source
QuantumClifford.generate! — Method
Generate a Pauli operator by using operators from a given the Stabilizer.
It assumes the stabilizer is already canonicalized. It modifies the Pauli operator in place, generating it in reverse, up to a phase. That phase is left in the modified operator, which should be the identity up to a phase. Returns the new operator and the list of indices denoting the elements of stabilizer that were used for the generation.
julia> ghz = S"XXXX
+Z₁ ⟼ - Z
See also: enumerate_cliffords.
source
QuantumClifford.fastcolumn — Function
Convert a tableau to a memory layout that is fast for column operations.
In this layout a column of the tableau is stored (mostly) contiguously in memory. Due to bitpacking, e.g., packing 64 bits into a single UInt64, the memory layout is not perfectly contiguous, but it is still optimal given that some bitwrangling is required to extract a given bit.
See also: fastrow
source
QuantumClifford.fastrow — Function
Convert a tableau to a memory layout that is fast for row operations.
In this layout a Pauli string (a row of the tableau) is stored contiguously in memory.
See also: fastrow
source
QuantumClifford.generate! — Method
Generate a Pauli operator by using operators from a given the Stabilizer.
It assumes the stabilizer is already canonicalized. It modifies the Pauli operator in place, generating it in reverse, up to a phase. That phase is left in the modified operator, which should be the identity up to a phase. Returns the new operator and the list of indices denoting the elements of stabilizer that were used for the generation.
julia> ghz = S"XXXX
                ZZII
                IZZI
                IIZZ";
@@ -358,7 +358,7 @@
 true
 
 julia> generate!(P"XII",canonicalize!(S"XII")) === nothing
-false
source
QuantumClifford.ghz — Function
Prepare a GHZ state of n qubits.
julia> ghz()
 + XXX
 + ZZ_
 + _ZZ
@@ -371,7 +371,7 @@
 + XXXX
 + ZZ__
 + _ZZ_
-+ __ZZ
source
QuantumClifford.graphstate — Method
Convert any stabilizer state to a graph state
Graph states are a special type of entangled stabilizer states that can be represented by a graph. For a graph $G=(V,E)$ the corresponding stabilizers are $S_v = X_v \prod_{u ∈ N(v)} Z_u$. Notice that such tableau rows contain only a single X operator. There is a set of single qubit gates that converts any stabilizer state to a graph state.
This function returns the graph state corresponding to a stabilizer and the gates that might be necessary to convert the stabilizer into a state representable as a graph.
For a tableau stab you can convert it with:
graph, hadamard_idx, iphase_idx, flips_idx = graphstate()
where graph is the graph representation of stab, and the rest specifies the single-qubit gates converting stab to graph: hadamard_idx are the qubits that require a Hadamard gate (mapping X ↔ Z), iphase_idx are (different) qubits that require an inverse Phase gate (Y → X), and flips_idx are the qubits that require a phase flip (Pauli Z gate), after the previous two sets of gates.
julia> using Graphs
+true
See also: graph_gatesequence
source
QuantumClifford.graphstate — Method
Convert any stabilizer state to a graph state
Graph states are a special type of entangled stabilizer states that can be represented by a graph. For a graph $G=(V,E)$ the corresponding stabilizers are $S_v = X_v \prod_{u ∈ N(v)} Z_u$. Notice that such tableau rows contain only a single X operator. There is a set of single qubit gates that converts any stabilizer state to a graph state.
This function returns the graph state corresponding to a stabilizer and the gates that might be necessary to convert the stabilizer into a state representable as a graph.
For a tableau stab you can convert it with:
graph, hadamard_idx, iphase_idx, flips_idx = graphstate()
where graph is the graph representation of stab, and the rest specifies the single-qubit gates converting stab to graph: hadamard_idx are the qubits that require a Hadamard gate (mapping X ↔ Z), iphase_idx are (different) qubits that require an inverse Phase gate (Y → X), and flips_idx are the qubits that require a phase flip (Pauli Z gate), after the previous two sets of gates.
julia> using Graphs
 
 julia> s = S" XXX
               ZZ_
@@ -435,11 +435,11 @@
 1-element Vector{Int64}:
  3
The Graphs.jl library provides many graph-theory tools and the MakieGraphs.jl library provides plotting utilities for graphs.
You can directly call the graph constructor on a stabilizer, if you just want the graph and do not care about the Clifford operation necessary to convert an arbitrary state to a state representable as a graph:
julia> collect(edges( Graph(bell()) ))
 1-element Vector{Graphs.SimpleGraphs.SimpleEdge{Int64}}:
- Edge 1 => 2
For a version that does not copy the stabilizer, but rather performs transformations in-place, use graphstate!. It would perform canonicalize_gott! on its argument as it finds a way to convert it to a graph state.
source
QuantumClifford.groupify — Method
Return the full stabilizer group represented by the input generating set (a Stabilizer).
The returned object is exponentially long.
julia> groupify(S"XZ ZX")
+ Edge 1 => 2
For a version that does not copy the stabilizer, but rather performs transformations in-place, use graphstate!. It would perform canonicalize_gott! on its argument as it finds a way to convert it to a graph state.
source
QuantumClifford.groupify — Method
Return the full stabilizer group represented by the input generating set (a Stabilizer).
The returned object is exponentially long.
julia> groupify(S"XZ ZX")
 + __
 + XZ
 + ZX
-+ YY
source
QuantumClifford.logdot — Method
Logarithm of the inner product between to Stabilizer states.
If the result is nothing, the dot inner product is zero. Otherwise the inner product is 2^(-logdot/2).
The actual inner product can be computed with LinearAlgebra.dot.
Based on (Garcia et al., 2012).
source
QuantumClifford.matroid_parent — Method
For a given set S of Paulis that does not necessarily represent a state, return a set of Paulis S' that represents a state. S' is a superset of commutified S. Additionally returns two arrays representing deletions needed to produce S. Based on (Goodenough et al., 2024)
By deleting the qubits in the first output array from S', taking the normalizer of S', then deleting the qubits in the second returned array from the normalizer of S', S is reproduced.
julia> matroid_parent(T"XX")[1]
++ YY
source
QuantumClifford.logdot — Method
Logarithm of the inner product between to Stabilizer states.
If the result is nothing, the dot inner product is zero. Otherwise the inner product is 2^(-logdot/2).
The actual inner product can be computed with LinearAlgebra.dot.
Based on (Garcia et al., 2012).
source
QuantumClifford.matroid_parent — Method
For a given set S of Paulis that does not necessarily represent a state, return a set of Paulis S' that represents a state. S' is a superset of commutified S. Additionally returns two arrays representing deletions needed to produce S. Based on (Goodenough et al., 2024)
By deleting the qubits in the first output array from S', taking the normalizer of S', then deleting the qubits in the second returned array from the normalizer of S', S is reproduced.
julia> matroid_parent(T"XX")[1]
 + X_X
 + XX_
 + ZZZ
@@ -448,11 +448,11 @@
 3:3
 
 julia> matroid_parent(T"XX")[3]
-3:2
source
QuantumClifford.minimal_generating_set — Method
For a not-necessarily-minimal generating set, return the minimal generating set.
The input has to have only real phases.
julia> minimal_generating_set(S"__ XZ ZX YY")
+3:2
source
QuantumClifford.minimal_generating_set — Method
For a not-necessarily-minimal generating set, return the minimal generating set.
The input has to have only real phases.
julia> minimal_generating_set(S"__ XZ ZX YY")
 + XZ
-+ ZX
source
QuantumClifford.normalizer — Method
Return all Pauli operators with the same number of qubits as the given Tableau t that commute with all operators in t.
julia> normalizer(T"X")
++ ZX
source
QuantumClifford.normalizer — Method
Return all Pauli operators with the same number of qubits as the given Tableau t that commute with all operators in t.
julia> normalizer(T"X")
 + _
-+ X
source
QuantumClifford.pauligroup — Method
Return the full Pauli group of a given length. Phases are ignored by default, but can be included by setting phases=true.
julia> pauligroup(1)
++ X
source
QuantumClifford.pauligroup — Method
Return the full Pauli group of a given length. Phases are ignored by default, but can be included by setting phases=true.
julia> pauligroup(1)
 + _
 + X
 + Z
@@ -474,32 +474,32 @@
 -i_
 -iX
 -iZ
--iY
source
QuantumClifford.pfmeasurements — Method
pfmeasurements(frame::PauliFrame) -> Any
-
Returns the measurement results for each frame in the PauliFrame instance.
Relative measurements
The return measurements are relative to the reference measurements, i.e. they only say whether the reference measurements have been flipped in the given frame.
source
QuantumClifford.pfmeasurements — Method
pfmeasurements(register::Register, frame::PauliFrame) -> Any
-
Takes the references measurements from the given Register and applies the flips as prescribed by the PauliFrame relative measurements. The result is the actual (non-relative) measurement results for each frame.
source
QuantumClifford.pfmeasurements — Method
pfmeasurements(frame::PauliFrame) -> Any
+
Returns the measurement results for each frame in the PauliFrame instance.
Relative measurements
The return measurements are relative to the reference measurements, i.e. they only say whether the reference measurements have been flipped in the given frame.
source
QuantumClifford.pfmeasurements — Method
pfmeasurements(register::Register, frame::PauliFrame) -> Any
+
Takes the references measurements from the given Register and applies the flips as prescribed by the PauliFrame relative measurements. The result is the actual (non-relative) measurement results for each frame.
source
QuantumClifford.pftrajectories — Method
pftrajectories(
     circuit;
     trajectories,
     threads
 ) -> PauliFrame{Stabilizer{QuantumClifford.Tableau{Vector{UInt8}, LinearAlgebra.Adjoint{UInt64, Matrix{UInt64}}}}, Matrix{Bool}}
-
The main method for running Pauli frame simulations of circuits. See the other methods for lower level access.
Multithreading is enabled by default, but can be disabled by setting threads=false. Do not forget to launch Julia with multiple threads enabled, e.g. julia -t4, if you want to use multithreading.
See also: mctrajectories, petrajectories
source
QuantumClifford.pftrajectories — Method
pftrajectories(
+
The main method for running Pauli frame simulations of circuits. See the other methods for lower level access.
Multithreading is enabled by default, but can be disabled by setting threads=false. Do not forget to launch Julia with multiple threads enabled, e.g. julia -t4, if you want to use multithreading.
See also: mctrajectories, petrajectories
source
QuantumClifford.pftrajectories — Method
pftrajectories(
     register::Register,
     circuit;
     trajectories
 ) -> Tuple{Register, PauliFrame{Stabilizer{QuantumClifford.Tableau{Vector{UInt8}, LinearAlgebra.Adjoint{UInt64, Matrix{UInt64}}}}, Matrix{Bool}}}
-
For a given Register and circuit, simulates the reference circuit acting on the register and then also simulate numerous PauliFrame trajectories. Returns the register and the PauliFrame instance.
Use pfmeasurements to get the measurement results.
source
QuantumClifford.phases — Method
The phases of a given tableau. It is a view, i.e. if you modify this array, the original tableau caries these changes.
source
QuantumClifford.prodphase — Method
Get the phase of the product of two Pauli operators.
Phase is encoded as F(4) in the low qubits of an UInt8.
julia> P"ZZZ"*P"XXX"
+
For a given Register and circuit, simulates the reference circuit acting on the register and then also simulate numerous PauliFrame trajectories. Returns the register and the PauliFrame instance.
Use pfmeasurements to get the measurement results.
source
QuantumClifford.phases — Method
The phases of a given tableau. It is a view, i.e. if you modify this array, the original tableau caries these changes.
source
QuantumClifford.prodphase — Method
Get the phase of the product of two Pauli operators.
Phase is encoded as F(4) in the low qubits of an UInt8.
julia> P"ZZZ"*P"XXX"
 -iYYY
 
 julia> prodphase(P"ZZZ", P"XXX")
 0x03
 
 julia> prodphase(P"XXX", P"ZZZ")
-0x01
source
QuantumClifford.random_brickwork_clifford_circuit — Method
Random brickwork Clifford circuit.
The connectivity of the random circuit is brickwork in some dimensions. Each gate in the circuit is a random 2-qubit Clifford gate.
The brickwork is defined as follows: The qubits are arranged as a lattice, and lattice_size contains side length in each dimension. For example, a chain of length five will have lattice_size = (5,), and a 5×5 lattice will have lattice_size = (5, 5).
In multi-dimensional cases, gate layers act alternatively along each direction. The nearest two layers along the same direction are offset by one qubit, forming a so-called brickwork. The boundary condition is chosen as open.
source
QuantumClifford.random_pauli — Function
A random Pauli operator on n qubits.
Use nophase=false to randomize the phase. Use realphase=false to get operators with phases including ±i.
Optionally, a "flip" probability p can be provided specified, in which case each bit is set to I with probability 1-p and to X or Y or Z with probability p. Useful for simulating unbiased Pauli noise.
See also random_pauli!
source
QuantumClifford.stabilizerplot — Function
A Makie.jl recipe for pictorial representation of a tableau.
Requires a Makie.jl backend to be loaded, e.g. using CairoMakie.
Alternatively, you can use the Plots.jl plotting ecosystem, e.g. using Plots; plot(S"XXX ZZZ").
Consult the documentation for more details on visualization options.
source
QuantumClifford.stabilizerplot_axis — Function
A Makie.jl recipe for pictorial representation of a tableau.
Requires a Makie.jl backend to be loaded, e.g. using CairoMakie.
Alternatively, you can use the Plots.jl plotting ecosystem, e.g. using Plots; plot(S"XXX ZZZ").
Consult the documentation for more details on visualization options.
source
QuantumClifford.random_brickwork_clifford_circuit — Method
Random brickwork Clifford circuit.
The connectivity of the random circuit is brickwork in some dimensions. Each gate in the circuit is a random 2-qubit Clifford gate.
The brickwork is defined as follows: The qubits are arranged as a lattice, and lattice_size contains side length in each dimension. For example, a chain of length five will have lattice_size = (5,), and a 5×5 lattice will have lattice_size = (5, 5).
In multi-dimensional cases, gate layers act alternatively along each direction. The nearest two layers along the same direction are offset by one qubit, forming a so-called brickwork. The boundary condition is chosen as open.
source
QuantumClifford.random_pauli — Function
A random Pauli operator on n qubits.
Use nophase=false to randomize the phase. Use realphase=false to get operators with phases including ±i.
Optionally, a "flip" probability p can be provided specified, in which case each bit is set to I with probability 1-p and to X or Y or Z with probability p. Useful for simulating unbiased Pauli noise.
See also random_pauli!
source
QuantumClifford.stabilizerplot — Function
A Makie.jl recipe for pictorial representation of a tableau.
Requires a Makie.jl backend to be loaded, e.g. using CairoMakie.
Alternatively, you can use the Plots.jl plotting ecosystem, e.g. using Plots; plot(S"XXX ZZZ").
Consult the documentation for more details on visualization options.
source
QuantumClifford.stabilizerplot_axis — Function
A Makie.jl recipe for pictorial representation of a tableau.
Requires a Makie.jl backend to be loaded, e.g. using CairoMakie.
Alternatively, you can use the Plots.jl plotting ecosystem, e.g. using Plots; plot(S"XXX ZZZ").
Consult the documentation for more details on visualization options.
source
QuantumClifford.xbit — Method
Extract as a new bit array the X part of the UInt array of packed qubits of a given Pauli operator.
source
QuantumClifford.zbit — Method
Extract as a new bit array the Z part of the UInt array of packed qubits of a given Pauli operator.
source
QuantumInterface.apply! — Function
In QuantumClifford the apply! function is used to apply any quantum operation to a stabilizer state, including unitary Clifford operations, Pauli measurements, and noise. Thus, this function may result in a random/stochastic result (e.g. with measurements or noise).
source
QuantumClifford.xbit — Method
Extract as a new bit array the X part of the UInt array of packed qubits of a given Pauli operator.
source
QuantumClifford.zbit — Method
Extract as a new bit array the Z part of the UInt array of packed qubits of a given Pauli operator.
source
QuantumInterface.apply! — Function
In QuantumClifford the apply! function is used to apply any quantum operation to a stabilizer state, including unitary Clifford operations, Pauli measurements, and noise. Thus, this function may result in a random/stochastic result (e.g. with measurements or noise).
source
QuantumInterface.embed — Method
Embed a Pauli operator in a larger Pauli operator.
julia> embed(5, 3, P"-Y")
 - __Y__
 
 julia> embed(5, (3,5), P"-YX")
-- __Y_X
source
QuantumInterface.entanglement_entropy — Function
Get bipartite entanglement entropy of a subsystem
Defined as entropy of the reduced density matrix.
It can be calculated with multiple different algorithms, the most performant one depending on the particular case.
Currently implemented are the :clip (clipped gauge), :graph (graph state), and :rref (Gaussian elimination) algorithms. Benchmark your particular case to choose the best one.
source
QuantumInterface.entanglement_entropy — Method
Get bipartite entanglement entropy by first converting the state to a graph and computing the rank of the adjacency matrix.
Based on "Entanglement in graph states and its applications".
source
QuantumInterface.expect — Method
expect(p::PauliOperator, st::AbstractStabilizer)
Compute the expectation value of a Pauli operator p on a stabilizer state st. This function will allocate a temporary copy of the stabilizer state st.
source
QuantumInterface.entanglement_entropy — Function
Get bipartite entanglement entropy of a subsystem
Defined as entropy of the reduced density matrix.
It can be calculated with multiple different algorithms, the most performant one depending on the particular case.
Currently implemented are the :clip (clipped gauge), :graph (graph state), and :rref (Gaussian elimination) algorithms. Benchmark your particular case to choose the best one.
source
QuantumInterface.entanglement_entropy — Method
Get bipartite entanglement entropy by first converting the state to a graph and computing the rank of the adjacency matrix.
Based on "Entanglement in graph states and its applications".
source
QuantumInterface.expect — Method
expect(p::PauliOperator, st::AbstractStabilizer)
Compute the expectation value of a Pauli operator p on a stabilizer state st. This function will allocate a temporary copy of the stabilizer state st.
source
QuantumInterface.project! — Method
project!(
     state::MixedStabilizer,
     pauli::PauliOperator;
     phases
@@ -634,25 +634,25 @@
 julia> project!(ms, P"IIY")[1]
 + X__
 + _Z_
-+ __Y
Similarly to project! on Stabilizer, this function has cubic complexity when the Pauli operator commutes with all rows of the tableau. Most of the time it is better to simply use MixedDestabilizer representation.
Unlike other project! methods, this one does not allow for keep_result=false, as the correct rank or anticommutation index can not be calculated without the expensive (cubic) canonicalization operation required by keep_result=true.
See the "Datastructure Choice" section in the documentation for more details.
See also: projectX!, projectY!, projectZ!.
source
QuantumInterface.reset_qubits! — Method
reset_qubits!(
++ __Y
Similarly to project! on Stabilizer, this function has cubic complexity when the Pauli operator commutes with all rows of the tableau. Most of the time it is better to simply use MixedDestabilizer representation.
Unlike other project! methods, this one does not allow for keep_result=false, as the correct rank or anticommutation index can not be calculated without the expensive (cubic) canonicalization operation required by keep_result=true.
See the "Datastructure Choice" section in the documentation for more details.
See also: projectX!, projectY!, projectZ!.
source
QuantumInterface.reset_qubits! — Method
reset_qubits!(
     s::Stabilizer,
     newstate,
     qubits;
     phases
 ) -> Union{PauliOperator, Stabilizer}
-
Reset a given set of qubits to be in the state newstate. These qubits are traced out first, which could lead to "nonlocal" changes in the tableau.
source
QuantumInterface.tensor — Function
Tensor product between operators or tableaux. 
Tensor product between CiffordOperators:
julia> tensor(CliffordOperator(sCNOT), CliffordOperator(sCNOT))
+
Reset a given set of qubits to be in the state newstate. These qubits are traced out first, which could lead to "nonlocal" changes in the tableau.
source
QuantumInterface.tensor — Function
Tensor product between operators or tableaux. 
Tensor product between CiffordOperators:
julia> tensor(CliffordOperator(sCNOT), CliffordOperator(sCNOT))
 X₁ ⟼ + XX__
 X₂ ⟼ + _X__
 X₃ ⟼ + __XX
@@ -679,7 +679,7 @@
 + XZ____
 - _Z____
 + ___XZ_
-- ____Z_
See also tensor_pow.
source
QuantumInterface.tensor_pow — Method
Repeated tensor product of an operators or a tableau.
For CliffordOperator:
julia> tensor_pow(CliffordOperator(sHadamard), 3)
 X₁ ⟼ + Z__
 X₂ ⟼ + _Z_
 X₃ ⟼ + __Z
@@ -701,21 +701,21 @@
 + ___XZ____
 + ____Z____
 + ______XZ_
-+ _______Z_
See also tensor.
source
QuantumInterface.traceout! — Method
traceout!(
     s::Union{MixedDestabilizer, MixedStabilizer},
     qubits;
     phases,
     rank
 ) -> Union{Tuple{Union{MixedDestabilizer, MixedStabilizer}, Int64}, MixedDestabilizer, MixedStabilizer}
-
source
Private API
Private Implementation Details
These functions are used internally by the library and might be drastically modified or deleted without warning or deprecation.
QuantumClifford.Tableau — Type
Internal Tableau type for storing a list of Pauli operators in a compact form. No special semantic meaning is attached to this type, it is just a convenient way to store a list of Pauli operators. E.g. it is not used to represent a stabilizer state, or a stabilizer group, or a Clifford circuit.
source
Base.hcat — Method
Horizontally concatenates tableaux.
julia> hcat(ghz(2), ghz(2))
+
source
Private API
Private Implementation Details
These functions are used internally by the library and might be drastically modified or deleted without warning or deprecation.
QuantumClifford.Tableau — Type
Internal Tableau type for storing a list of Pauli operators in a compact form. No special semantic meaning is attached to this type, it is just a convenient way to store a list of Pauli operators. E.g. it is not used to represent a stabilizer state, or a stabilizer group, or a Clifford circuit.
source
Base.hcat — Method
Horizontally concatenates tableaux.
julia> hcat(ghz(2), ghz(2))
 + XXXX
-+ ZZZZ
See also: vcat
source
Base.inv — Method
inv(
     c::CliffordOperator;
     phases
 ) -> CliffordOperator{QuantumClifford.Tableau{Vector{UInt8}, Matrix{UInt64}}}
@@ -733,32 +733,32 @@
 
 julia> inv(CliffordOperator(tHadamard))
 X₁ ⟼ + Z
-Z₁ ⟼ + X
source
Base.vcat — Method
Vertically concatenates tableaux.
julia> vcat(ghz(2), ghz(2))
+Z₁ ⟼ + X
source
Base.vcat — Method
Vertically concatenates tableaux.
julia> vcat(ghz(2), ghz(2))
 + XX
 + ZZ
 + XX
-+ ZZ
See also: hcat
source
QuantumClifford._remove_rowcol! — Method
Unexported low-level function that removes a row (by shifting all rows up as necessary)
Because MixedDestabilizer is not mutable we return a new MixedDestabilizer with the same (modified) xzs array.
Used on its own, this function will break invariants. Meant to be used with projectremove!.
source
QuantumClifford._rowmove! — Method
Unexported low-level function that moves row i to row j.
Used on its own, this function will break invariants. Meant to be used in _remove_rowcol!.
source
QuantumClifford.applynoise_branches — Function
Compute all possible new states after the application of the given noise model. Reports the probability of each one of them. Deterministic (as it reports all branches of potentially random processes), part of the Noise interface.
source
QuantumClifford._remove_rowcol! — Method
Unexported low-level function that removes a row (by shifting all rows up as necessary)
Because MixedDestabilizer is not mutable we return a new MixedDestabilizer with the same (modified) xzs array.
Used on its own, this function will break invariants. Meant to be used with projectremove!.
source
QuantumClifford._rowmove! — Method
Unexported low-level function that moves row i to row j.
Used on its own, this function will break invariants. Meant to be used in _remove_rowcol!.
source
QuantumClifford.applynoise_branches — Function
Compute all possible new states after the application of the given noise model. Reports the probability of each one of them. Deterministic (as it reports all branches of potentially random processes), part of the Noise interface.
source
QuantumClifford.get_bitmask_idxs — Method
get_bitmask_idxs(
     xzs::AbstractArray{<:Unsigned},
     i::Int64
 ) -> Tuple{Any, Any, Int64, Any}
-
Computes bitmask indices for an unsigned integer at index i within the binary structure of a Tableau or PauliOperator.
For Tableau, the method operates on the .xzs field, while for PauliOperator, it uses the .xz field. It calculates the following values based on the index i:
  • lowbit, the lowest bit.
  • ibig, the index of the word containing the bit.
  • ismall, the position of the bit within the word.
  • ismallm, a bitmask isolating the specified bit.
source
QuantumClifford.gf2_row_echelon_with_pivots! — Method
Performs in-place Gaussian elimination on a binary matrix and returns its row echelon form,rank, the transformation matrix, and the pivot columns. The transformation matrix that converts the original matrix into the row echelon form. The full parameter controls the extent of elimination: if true, only rows below the pivot are affected; if false, both above and below the pivot are eliminated.
source
QuantumClifford.initZ! — Method
initZ!(frame::PauliFrame) -> PauliFrame
-
Inject random Z errors over all frames and qubits for the supplied PauliFrame with probability 0.5.
Calling this after initialization is essential for simulating any non-deterministic circuit. It is done automatically by most PauliFrame constructors.
source
QuantumClifford.make_sumtype — Method
julia> make_sumtype([sCNOT])
+
Computes bitmask indices for an unsigned integer at index i within the binary structure of a Tableau or PauliOperator.
For Tableau, the method operates on the .xzs field, while for PauliOperator, it uses the .xz field. It calculates the following values based on the index i:
  • lowbit, the lowest bit.
  • ibig, the index of the word containing the bit.
  • ismall, the position of the bit within the word.
  • ismallm, a bitmask isolating the specified bit.
source
QuantumClifford.gf2_row_echelon_with_pivots! — Method
Performs in-place Gaussian elimination on a binary matrix and returns its row echelon form,rank, the transformation matrix, and the pivot columns. The transformation matrix that converts the original matrix into the row echelon form. The full parameter controls the extent of elimination: if true, only rows below the pivot are affected; if false, both above and below the pivot are eliminated.
source
QuantumClifford.initZ! — Method
initZ!(frame::PauliFrame) -> PauliFrame
+
Inject random Z errors over all frames and qubits for the supplied PauliFrame with probability 0.5.
Calling this after initialization is essential for simulating any non-deterministic circuit. It is done automatically by most PauliFrame constructors.
source
QuantumClifford.make_sumtype_method — Function
``` julia> makesumtypemethod([sCNOT], :apply!, (:s,)) quote     function QuantumClifford.apply!(s, g::CompactifiedGate)         @cases g begin             sCNOT(q1, q2) => apply!(s, sCNOT(q1, q2))         end     end end
source
QuantumClifford.make_sumtype_method — Function
``` julia> makesumtypemethod([sCNOT], :apply!, (:s,)) quote     function QuantumClifford.apply!(s, g::CompactifiedGate)         @cases g begin             sCNOT(q1, q2) => apply!(s, sCNOT(q1, q2))         end     end end
source
QuantumClifford.projectremoverand! — Method
Unexported low-level function that projects a qubit and returns the result while making the tableau smaller by a qubit.
Because MixedDestabilizer is not mutable we return a new MixedDestabilizer with the same (modified) xzs array.
source
QuantumClifford.remove_column! — Method
Unexported low-level function that removes a column (by shifting all columns to the right of the target by one step to the left)
Because Tableau is not mutable we return a new Tableau with the same (modified) xzs array.
source
QuantumClifford.rowdecompose — Method
Decompose a Pauli $P$ in terms of stabilizer and destabilizer rows from a given tableaux.
For given tableaux of rows destabilizer rows $\{d_i\}$ and stabilizer rows $\{s_i\}$, there are boolean vectors $b$ and $c$ such that $P = i^p \prod_i d_i^{b_i} \prod_i s_i^{c_i}$.
This function returns p, b, c.
julia> s = MixedDestabilizer(ghz(2))
+end)
source
QuantumClifford.projectremoverand! — Method
Unexported low-level function that projects a qubit and returns the result while making the tableau smaller by a qubit.
Because MixedDestabilizer is not mutable we return a new MixedDestabilizer with the same (modified) xzs array.
source
QuantumClifford.remove_column! — Method
Unexported low-level function that removes a column (by shifting all columns to the right of the target by one step to the left)
Because Tableau is not mutable we return a new Tableau with the same (modified) xzs array.
source
QuantumClifford.rowdecompose — Method
Decompose a Pauli $P$ in terms of stabilizer and destabilizer rows from a given tableaux.
For given tableaux of rows destabilizer rows $\{d_i\}$ and stabilizer rows $\{s_i\}$, there are boolean vectors $b$ and $c$ such that $P = i^p \prod_i d_i^{b_i} \prod_i s_i^{c_i}$.
This function returns p, b, c.
julia> s = MixedDestabilizer(ghz(2))
 𝒟ℯ𝓈𝓉𝒶𝒷
 + Z_
 + _X
@@ -770,7 +770,7 @@
 (3, Bool[1, 0], Bool[1, 1])
 
 julia> im^3 * P"Z_" * P"XX" * P"ZZ"
-+ XY
source
QuantumClifford.to_cpu — Function
copies the memory content of the object to CPU
You can only use this function if CUDA.jl is imported
For more advanced users to_cpu(data, element_type) will reinterpret elements of data and converts them to element_type. For example based on your CPU architecture, if working with matrices of UInt32 is faster than UInt64, you can use to_cpu(data, UInt32)
julia> using QuantumClifford: to_cpu, to_gpu
++ XY
source
QuantumClifford.to_cpu — Function
copies the memory content of the object to CPU
You can only use this function if CUDA.jl is imported
For more advanced users to_cpu(data, element_type) will reinterpret elements of data and converts them to element_type. For example based on your CPU architecture, if working with matrices of UInt32 is faster than UInt64, you can use to_cpu(data, UInt32)
julia> using QuantumClifford: to_cpu, to_gpu
 
 julia> using CUDA # without this import, to_cpu, to_gpu are just function
 
@@ -793,7 +793,7 @@
 julia> pf_gpu = to_gpu(PauliFrame(1000, 2, 2));
 julia> circuit = [sMZ(1, 1), sHadamard(2), sMZ(2, 2)];
 julia> pftrajectories(pf_gpu, circuit);
-julia> measurements = to_cpu(pf_gpu.measurements);
See also: to_gpu
source
QuantumClifford.to_gpu — Function
copies the memory content of the object to GPU
You can only use this function if CUDA.jl is imported
For more advanced users to_gpu(data, element_type) will reinterpret elements of data and converts them to element_type. For example based on your GPU architecture, if working with matrices of UInt64 is faster than UInt32, you can use to_gpu(data, UInt64)
julia> using QuantumClifford: to_cpu, to_gpu
+julia> measurements = to_cpu(pf_gpu.measurements);
See also: to_gpu
source
QuantumClifford.to_gpu — Function
copies the memory content of the object to GPU
You can only use this function if CUDA.jl is imported
For more advanced users to_gpu(data, element_type) will reinterpret elements of data and converts them to element_type. For example based on your GPU architecture, if working with matrices of UInt64 is faster than UInt32, you can use to_gpu(data, UInt64)
julia> using QuantumClifford: to_cpu, to_gpu
 
 julia> using CUDA # without this import, to_cpu, to_gpu are just function
 
@@ -816,4 +816,4 @@
 julia> pf_gpu = to_gpu(PauliFrame(1000, 2, 2));
 julia> circuit = [sMZ(1, 1), sHadamard(2), sMZ(2, 2)];
 julia> pftrajectories(pf_gpu, circuit);
-julia> measurements = to_cpu(pf_gpu.measurements);
See also: to_cpu
source
+julia> measurements = to_cpu(pf_gpu.measurements);

See also: to_cpu

source
QuantumClifford.trusted_rank — Function

A "trusted" rank which returns rank(state) for Mixed[De]Stabilizer and length(state) for [De]Stabilizer.

source
QuantumClifford.zero! — Method

Zero-out a given row of a Tableau

source
QuantumClifford.zero! — Method

Zero-out the phases and single-qubit operators in a PauliOperator

source
QuantumClifford.@qubitop1 — Macro

Macro used to define single qubit symbolic gates and their qubit_kernel methods.

source
QuantumClifford.@qubitop2 — Macro

Macro used to define 2-qubit symbolic gates and their qubit_kernel methods.

source
QuantumClifford.@valbooldispatch — Macro

Turns f(Val(x)) into x ? f(Val(true)) : f(Val(false)) in order to avoid dynamic dispatch

See discourse discussion

source
diff --git a/dev/ECC_API/index.html b/dev/ECC_API/index.html index 1bf6df901..a3b65bdb9 100644 --- a/dev/ECC_API/index.html +++ b/dev/ECC_API/index.html @@ -2,7 +2,7 @@ API · QuantumClifford.jl
GitHub

Full ECC API (autogenerated)

QuantumClifford.ECC.CSS — Type

An arbitrary CSS error correcting code defined by its X and Z checks.

julia> CSS([0 1 1 0; 1 1 0 0], [1 1 1 1]) |> parity_checks
 + _XX_
 + XX__
-+ ZZZZ
source
QuantumClifford.ECC.Concat — Type

Concat(c₁, c₂) is a code concatenation of two quantum codes (Knill and Laflamme, 1996).

The inner code c₁ and the outer code c₂. The construction is the following: replace each qubit in code c₂ with logical qubits encoded by code c₁. The resulting code will have n = n₁ × n₂ qubits and k = k₁ × k₂ logical qubits.

source
QuantumClifford.ECC.QuantumReedMuller — Type

The family of [[2ᵐ - 1, 1, 3]] CSS Quantum-Reed-Muller codes, as discovered by Steane in his 1999 paper (Steane, 1999).

Quantum codes are constructed from shortened Reed-Muller codes RM(1, m), by removing the first row and column of the generator matrix Gₘ. Similarly, we can define truncated dual codes RM(m - 2, m) using the generator matrix Hₘ (Anderson et al., 2014). The quantum Reed-Muller codes QRM(m) derived from RM(1, m) are CSS codes.

Given that the stabilizers of the quantum code are defined through the generator matrix of the classical code, the minimum distance of the quantum code corresponds to the minimum distance of the dual classical code, which is d = 3, thus it can correct any single qubit error. Since one stabilizer from the original and one from the dual code are removed in the truncation process, the code parameters are [[2ᵐ - 1, 1, 3]].

You might be interested in consulting (Anderson et al., 2014) and (Campbell et al., 2012) as well.

The ECC Zoo has an entry for this family.

source
QuantumClifford.ECC.ShorSyndromeECCSetup — Type

Configuration for ECC evaluators that simulate the Shor-style syndrome measurement (without a flag qubit).

The simulated circuit includes:

  • perfect noiseless encoding (encoding and its fault tolerance are not being studied here)
  • one round of "memory noise" after the encoding but before the syndrome measurement
  • perfect preparation of entangled ancillary qubits
  • noisy Shor-style syndrome measurement (only two-qubit gate noise)
  • noiseless "logical state measurement" (providing the comparison data when evaluating the decoder)

See also: CommutationCheckECCSetup, NaiveSyndromeECCSetup

source
QuantumClifford.ECC.Surface — Type

The planar surface code refers to the code (Kitaev, 2003) in a 2D lattice with open boundaries.

Illustration of a 3×2 surface code, where qubits are located on the edges:

|---1--(Z)--2---|---3---|
++ ZZZZ
source
QuantumClifford.ECC.Concat — Type

Concat(c₁, c₂) is a code concatenation of two quantum codes (Knill and Laflamme, 1996).

The inner code c₁ and the outer code c₂. The construction is the following: replace each qubit in code c₂ with logical qubits encoded by code c₁. The resulting code will have n = n₁ × n₂ qubits and k = k₁ × k₂ logical qubits.

source
QuantumClifford.ECC.QuantumReedMuller — Type

The family of [[2ᵐ - 1, 1, 3]] CSS Quantum-Reed-Muller codes, as discovered by Steane in his 1999 paper (Steane, 1999).

Quantum codes are constructed from shortened Reed-Muller codes RM(1, m), by removing the first row and column of the generator matrix Gₘ. Similarly, we can define truncated dual codes RM(m - 2, m) using the generator matrix Hₘ (Anderson et al., 2014). The quantum Reed-Muller codes QRM(m) derived from RM(1, m) are CSS codes.

Given that the stabilizers of the quantum code are defined through the generator matrix of the classical code, the minimum distance of the quantum code corresponds to the minimum distance of the dual classical code, which is d = 3, thus it can correct any single qubit error. Since one stabilizer from the original and one from the dual code are removed in the truncation process, the code parameters are [[2ᵐ - 1, 1, 3]].

You might be interested in consulting (Anderson et al., 2014) and (Campbell et al., 2012) as well.

The ECC Zoo has an entry for this family.

source
QuantumClifford.ECC.ShorSyndromeECCSetup — Type

Configuration for ECC evaluators that simulate the Shor-style syndrome measurement (without a flag qubit).

The simulated circuit includes:

  • perfect noiseless encoding (encoding and its fault tolerance are not being studied here)
  • one round of "memory noise" after the encoding but before the syndrome measurement
  • perfect preparation of entangled ancillary qubits
  • noisy Shor-style syndrome measurement (only two-qubit gate noise)
  • noiseless "logical state measurement" (providing the comparison data when evaluating the decoder)

See also: CommutationCheckECCSetup, NaiveSyndromeECCSetup

source
QuantumClifford.ECC.Surface — Type

The planar surface code refers to the code (Kitaev, 2003) in a 2D lattice with open boundaries.

Illustration of a 3×2 surface code, where qubits are located on the edges:

|---1--(Z)--2---|---3---|
 |  (X)  7       8       o
 |---4---|---5---|---6---|
 |       o       o       o
@@ -13,7 +13,7 @@
 + ZZ____Z_
 + _ZZ____Z
 + ___ZZ_Z_
-+ ____ZZ_Z

More information can be seen in (Fowler et al., 2012).

source
QuantumClifford.ECC.TableDecoder — Type

A simple look-up table decoder for error correcting codes.

The lookup table contains only weight=1 errors, thus it is small, but at best it provides only for distance=3 decoding.

The size of the lookup table would grow exponentially quickly for higher distances.

source
QuantumClifford.ECC.TableDecoder — Type

A simple look-up table decoder for error correcting codes.

The lookup table contains only weight=1 errors, thus it is small, but at best it provides only for distance=3 decoding.

The size of the lookup table would grow exponentially quickly for higher distances.

source
QuantumClifford.ECC.Toric — Type

The Toric code (Kitaev, 2003).

Illustration of a 2x2 toric code, where qubits are located on the edges:

|--1-(Z)-2--|
 | (X) 5     6
 |--3--|--4--|
 |     7     8
@@ -23,7 +23,7 @@
 + X_X___XX
 + ZZ__Z_Z_
 + ZZ___Z_Z
-+ __ZZZ_Z_
source
QuantumClifford.ECC.code_k — Method

The number of logical qubits in a code.

Note that when redundant rows exist in the parity check matrix, the number of logical qubits code_k(c) will be greater than code_n(c) - code_s(c), where the difference equals the redundancy.

source
QuantumClifford.ECC.code_s — Function

The number of stabilizer checks in a code. They might not be all linearly independent, thus code_s >= code_n-code_k. For the number of linearly independent checks you can use LinearAlgebra.rank.

source
QuantumClifford.ECC.evaluate_decoder — Method

Evaluate the performance of an error-correcting circuit.

This method requires you give the circuit that performs both syndrome measurements and (probably noiseless) logical state measurements. The faults matrix that translates an error vector into corresponding logical errors is necessary as well.

This is a relatively barebones method that assumes the user prepares necessary circuits, etc. It is a method that is used internally by more user-frienly methods providing automatic conversion of codes and noise models to the necessary noisy circuits.

source
QuantumClifford.ECC.faults_matrix — Method

Error-to-logical-observable map (a.k.a. fault matrix) of a code.

For a code with n physical qubits and k logical qubits this function returns a 2k × 2n binary matrix O such that O[i,j] is true if the logical observable of index i is flipped by the single physical qubit error of index j. Indexing is such that:

  • O[1:k,:] is the error-to-logical-X-observable map (logical X observable, i.e. triggered by logical Z errors)
  • O[k+1:2k,:] is the error-to-logical-Z-observable map
  • O[:,1:n] is the X-physical-error-to-logical-observable map
  • O[n+1:2n,:] is the Z-physical-error-to-logical-observable map

E.g. for k=1, n=10, then if O[2,5] is true, then the logical Z observable is flipped by a X₅ error; and if O[1,12] is true, then the logical X observable is flipped by a Z₂ error.

Of note is that there is a lot of freedom in choosing the logical operations! A logical operator multiplied by a stabilizer operator is still a logical operator. Similarly there is a different fault matrix for each choice of logical operators. But once the logical operators are picked, the fault matrix is fixed.

Below we show an example that uses the Shor code. While it is not the smallest code, it is a convenient choice to showcase the importance of the fault matrix when dealing with degenerate codes where a correction operation and an error do not need to be the same.

First, consider a single-qubit error, potential correction operations, and their effect on the Shor code:

julia> using QuantumClifford.ECC: faults_matrix, Shor9
++ __ZZZ_Z_
source
QuantumClifford.ECC.code_k — Method

The number of logical qubits in a code.

Note that when redundant rows exist in the parity check matrix, the number of logical qubits code_k(c) will be greater than code_n(c) - code_s(c), where the difference equals the redundancy.

source
QuantumClifford.ECC.code_s — Function

The number of stabilizer checks in a code. They might not be all linearly independent, thus code_s >= code_n-code_k. For the number of linearly independent checks you can use LinearAlgebra.rank.

source
QuantumClifford.ECC.evaluate_decoder — Method

Evaluate the performance of an error-correcting circuit.

This method requires you give the circuit that performs both syndrome measurements and (probably noiseless) logical state measurements. The faults matrix that translates an error vector into corresponding logical errors is necessary as well.

This is a relatively barebones method that assumes the user prepares necessary circuits, etc. It is a method that is used internally by more user-frienly methods providing automatic conversion of codes and noise models to the necessary noisy circuits.

source
QuantumClifford.ECC.faults_matrix — Method

Error-to-logical-observable map (a.k.a. fault matrix) of a code.

For a code with n physical qubits and k logical qubits this function returns a 2k × 2n binary matrix O such that O[i,j] is true if the logical observable of index i is flipped by the single physical qubit error of index j. Indexing is such that:

  • O[1:k,:] is the error-to-logical-X-observable map (logical X observable, i.e. triggered by logical Z errors)
  • O[k+1:2k,:] is the error-to-logical-Z-observable map
  • O[:,1:n] is the X-physical-error-to-logical-observable map
  • O[n+1:2n,:] is the Z-physical-error-to-logical-observable map

E.g. for k=1, n=10, then if O[2,5] is true, then the logical Z observable is flipped by a X₅ error; and if O[1,12] is true, then the logical X observable is flipped by a Z₂ error.

Of note is that there is a lot of freedom in choosing the logical operations! A logical operator multiplied by a stabilizer operator is still a logical operator. Similarly there is a different fault matrix for each choice of logical operators. But once the logical operators are picked, the fault matrix is fixed.

Below we show an example that uses the Shor code. While it is not the smallest code, it is a convenient choice to showcase the importance of the fault matrix when dealing with degenerate codes where a correction operation and an error do not need to be the same.

First, consider a single-qubit error, potential correction operations, and their effect on the Shor code:

julia> using QuantumClifford.ECC: faults_matrix, Shor9
 
 julia> state = MixedDestabilizer(Shor9())
 𝒟ℯ𝓈𝓉𝒶𝒷━━━━━
@@ -146,7 +146,7 @@
 julia> O * stab_to_gf2(bad_Z₆Z₉)
 2-element Vector{Int64}:
  1
- 0

While its use in this situation is rather contrived, the fault matrix is incredibly useful when running large scale simulations in which we want a separate fast error sampling process, (e.g. with Pauli frames) and a syndrome decoding process, without coupling between them. We just gather all our syndrome measurement and logical observables from the Pauli frame simulations, and then use them with the fault matrix in the syndrome decoding simulation.

source
QuantumClifford.ECC.isdegenerate — Function

Check if the code is degenerate with respect to a given set of error or with respect to all "up to d physical-qubit" errors (defaulting to d=1).

julia> using QuantumClifford.ECC
+ 0

While its use in this situation is rather contrived, the fault matrix is incredibly useful when running large scale simulations in which we want a separate fast error sampling process, (e.g. with Pauli frames) and a syndrome decoding process, without coupling between them. We just gather all our syndrome measurement and logical observables from the Pauli frame simulations, and then use them with the fault matrix in the syndrome decoding simulation.

source
QuantumClifford.ECC.isdegenerate — Function

Check if the code is degenerate with respect to a given set of error or with respect to all "up to d physical-qubit" errors (defaulting to d=1).

julia> using QuantumClifford.ECC
 
 julia> isdegenerate(Shor9(), [single_z(9,1), single_z(9,2)])
 true
@@ -158,7 +158,7 @@
 false
 
 julia> isdegenerate(Steane7(), 2)
-true
source
QuantumClifford.ECC.naive_encoding_circuit — Method

Encoding physical qubits into a larger logical code.

The initial physical qubits to be encoded have to be at indices n-k+1:n.

Encoding circuits are not fault-tolerant

Encoding circuits are not fault-tolerant, and thus should not be used in practice. Instead, you should measure the stabilizers of the code and the logical observables, thus projecting into the code space (which can be fault-tolerant).

The canonicalization operation performed on the code may permute the qubits (see canonicalize_gott!). That permutation is corrected for with SWAP gates by default (controlled by the undoperm keyword argument).

Based on (Cleve and Gottesman, 1997) and (Gottesman, 1997), however it seems the published algorithm has some errors. Consult the erratum, as well as the more recent (Grassl, 2002) and (Grassl, 2011), and be aware that this implementation also uses H instead of Z gates.

source
QuantumClifford.ECC.naive_syndrome_circuit — Function

Generate the non-fault-tolerant stabilizer measurement cicuit for a given code instance or parity check tableau.

Use the ancillary_index and bit_index arguments to offset where the corresponding part the circuit starts.

Returns the circuit, the number of ancillary qubits that were added, and a list of bit indices that will store the measurement results.

See also: shor_syndrome_circuit

source
QuantumClifford.ECC.shor_syndrome_circuit — Function

Generate the Shor fault-tolerant stabilizer measurement cicuit for a given code instance or parity check tableau.

Use the ancillary_index and bit_index arguments to offset where the corresponding part the circuit starts. Ancillary qubits

Returns:

  • The ancillary cat state preparation circuit.
  • The Shor syndrome measurement circuit.
  • The number of ancillary qubits that were added.
  • The list of bit indices that store the final measurement results.

See also: naive_syndrome_circuit

source

Implemented in an extension requiring Hecke.jl

QuantumCliffordHeckeExt.LPCode — Type
struct LPCode <: QuantumClifford.ECC.AbstractECC

Lifted product codes ((Panteleev and Kalachev, 2021), (Panteleev and Kalachev, Jun 2022))

A lifted product code is defined by the hypergraph product of a base matrices A and the conjugate of another base matrix B'. Here, the hypergraph product is taken over a group algebra, of which the base matrices are consisting.

The binary parity check matrix is obtained by applying repr to each element of the matrix resulted from the hypergraph product, which is mathematically a linear map from each group algebra element to a binary matrix.

Constructors

Multiple constructors are available:

  1. Two base matrices of group algebra elements.

  2. Two lifted codes, whose base matrices are for quantum code construction.

  3. Two base matrices of group elements, where each group element will be considered as a group algebra element by assigning a unit coefficient.

  4. Two base matrices of integers, where each integer represent the shift of a cyclic permutation. The order of the cyclic permutation should be specified.

Examples

A [[882, 24, d ≤ 24]] code from Appendix B of (Roffe et al., 2023). We use the 1st constructor to generate the code and check its length and dimension. During the construction, we do arithmetic operations to get the group algebra elements in base matrices A and B. Here x is the generator of the group algebra, i.e., offset-1 cyclic permutation, and GA(1) is the unit element.

julia> import Hecke: group_algebra, GF, abelian_group, gens; import LinearAlgebra: diagind; using QuantumClifford.ECC;
+true
source
QuantumClifford.ECC.naive_encoding_circuit — Method

Encoding physical qubits into a larger logical code.

The initial physical qubits to be encoded have to be at indices n-k+1:n.

Encoding circuits are not fault-tolerant

Encoding circuits are not fault-tolerant, and thus should not be used in practice. Instead, you should measure the stabilizers of the code and the logical observables, thus projecting into the code space (which can be fault-tolerant).

The canonicalization operation performed on the code may permute the qubits (see canonicalize_gott!). That permutation is corrected for with SWAP gates by default (controlled by the undoperm keyword argument).

Based on (Cleve and Gottesman, 1997) and (Gottesman, 1997), however it seems the published algorithm has some errors. Consult the erratum, as well as the more recent (Grassl, 2002) and (Grassl, 2011), and be aware that this implementation also uses H instead of Z gates.

source
QuantumClifford.ECC.naive_syndrome_circuit — Function

Generate the non-fault-tolerant stabilizer measurement cicuit for a given code instance or parity check tableau.

Use the ancillary_index and bit_index arguments to offset where the corresponding part the circuit starts.

Returns the circuit, the number of ancillary qubits that were added, and a list of bit indices that will store the measurement results.

See also: shor_syndrome_circuit

source
QuantumClifford.ECC.shor_syndrome_circuit — Function

Generate the Shor fault-tolerant stabilizer measurement cicuit for a given code instance or parity check tableau.

Use the ancillary_index and bit_index arguments to offset where the corresponding part the circuit starts. Ancillary qubits

Returns:

  • The ancillary cat state preparation circuit.
  • The Shor syndrome measurement circuit.
  • The number of ancillary qubits that were added.
  • The list of bit indices that store the final measurement results.

See also: naive_syndrome_circuit

source

Implemented in an extension requiring Hecke.jl

QuantumCliffordHeckeExt.LPCode — Type
struct LPCode <: QuantumClifford.ECC.AbstractECC

Lifted product codes ((Panteleev and Kalachev, 2021), (Panteleev and Kalachev, Jun 2022))

A lifted product code is defined by the hypergraph product of a base matrices A and the conjugate of another base matrix B'. Here, the hypergraph product is taken over a group algebra, of which the base matrices are consisting.

The binary parity check matrix is obtained by applying repr to each element of the matrix resulted from the hypergraph product, which is mathematically a linear map from each group algebra element to a binary matrix.

Constructors

Multiple constructors are available:

  1. Two base matrices of group algebra elements.

  2. Two lifted codes, whose base matrices are for quantum code construction.

  3. Two base matrices of group elements, where each group element will be considered as a group algebra element by assigning a unit coefficient.

  4. Two base matrices of integers, where each integer represent the shift of a cyclic permutation. The order of the cyclic permutation should be specified.

Examples

A [[882, 24, d ≤ 24]] code from Appendix B of (Roffe et al., 2023). We use the 1st constructor to generate the code and check its length and dimension. During the construction, we do arithmetic operations to get the group algebra elements in base matrices A and B. Here x is the generator of the group algebra, i.e., offset-1 cyclic permutation, and GA(1) is the unit element.

julia> import Hecke: group_algebra, GF, abelian_group, gens; import LinearAlgebra: diagind; using QuantumClifford.ECC;
 
 julia> l = 63; GA = group_algebra(GF(2), abelian_group(l)); x = gens(GA)[];
 
@@ -186,7 +186,7 @@
 julia> c2 = LPCode(base_matrix, l .- base_matrix', l);
 
 julia> code_n(c2), code_k(c2)
-(175, 19)

Code subfamilies and convenience constructors for them

  • When the base matrices of the LPCode are 1×1, the code is called a two-block group-algebra code two_block_group_algebra_codes.
  • When the base matrices of the LPCode are 1×1 and their elements are sums of cyclic permutations, the code is called a generalized bicycle code generalized_bicycle_codes.
  • When the two matrices are adjoint to each other, the code is called a bicycle code bicycle_codes.

The representation function

We use the default representation function Hecke.representation_matrix to convert a GF(2)-group algebra element to a binary matrix. The default representation, provided by Hecke, is the permutation representation.

We also accept a custom representation function as detailed in LiftedCode.

See also: LiftedCode, two_block_group_algebra_codes, generalized_bicycle_codes, bicycle_codes, haah_cubic_codes.

  • A::Union{LinearAlgebra.Adjoint{<:Hecke.GroupAlgebraElem, <:Matrix{<:Hecke.GroupAlgebraElem}}, Matrix{<:Hecke.GroupAlgebraElem}}: the first base matrix of the code, whose elements are in a group algebra.

  • B::Union{LinearAlgebra.Adjoint{<:Hecke.GroupAlgebraElem, <:Matrix{<:Hecke.GroupAlgebraElem}}, Matrix{<:Hecke.GroupAlgebraElem}}: the second base matrix of the code, whose elements are in the same group algebra as A.

  • GA::Hecke.GroupAlgebra: the group algebra for which elements in A and B are from.

  • repr::Function: a function that converts a group algebra element to a binary matrix; default to be the permutation representation for GF(2)-algebra.

source
QuantumCliffordHeckeExt.LiftedCode — Type
struct LiftedCode <: QuantumClifford.ECC.ClassicalCode

Classical codes lifted over a group algebra, used for lifted product code construction ((Panteleev and Kalachev, 2021), (Panteleev and Kalachev, Jun 2022))

The parity-check matrix is constructed by applying repr to each element of A, which is mathematically a linear map from a group algebra element to a binary matrix. The size of the parity check matrix will enlarged with each element of A being inflated into a matrix. The procedure is called a lift (Panteleev and Kalachev, Jun 2022).

Constructors

A lifted code can be constructed via the following approaches:

  1. A matrix of group algebra elements.

  2. A matrix of group elements, where a group element will be considered as a group algebra element by assigning a unit coefficient.

  3. A matrix of integers, where each integer represent the shift of a cyclic permutation. The order of the cyclic permutation should be specified.

The default GA is the group algebra of A[1, 1], the default representation repr is the permutation representation.

The representation function repr

We use the default representation function Hecke.representation_matrix to convert a GF(2)-group algebra element to a binary matrix. The default representation, provided by Hecke, is the permutation representation.

We also accept a custom representation function (the repr field of the constructor). Whatever the representation, the matrix elements need to be convertible to Integers (e.g. permit lift(ZZ, ...)). Such a customization would be useful to reduce the number of bits required by the code construction.

For example, if we use a D4 group for lifting, our default representation will be 8×8 permutation matrices, where 8 is the group's order. However, we can find a 4×4 matrix representation for the group, e.g. by using the typical 2×2 representation and converting it into binary representation by replacing "1" with the Pauli I, and "-1" with the Pauli X matrix.

See also: LPCode.

  • A::Union{LinearAlgebra.Adjoint{<:Hecke.GroupAlgebraElem, <:Matrix{<:Hecke.GroupAlgebraElem}}, Matrix{<:Hecke.GroupAlgebraElem}}: the base matrix of the code, whose elements are in a group algebra.

  • GA::Hecke.GroupAlgebra: the group algebra for which elements in A are from.

  • repr::Function: a function that converts a group algebra element to a binary matrix; default to be the permutation representation for GF(2)-algebra.

source
QuantumCliffordHeckeExt.LiftedCode — Method

LiftedCode constructor using the default GF(2) representation (coefficients converted to a permutation matrix by representation_matrix provided by Hecke).

source
QuantumClifford.ECC.check_repr_commutation_relation — Method

Checks the commutation relation between the left and right representation matrices for two randomly-sampled elements a and b in the group algebra ℱ[G] with a general group G. It verifies the commutation relation that states, L(a)·R(b) = R(b)·L(a). This property shows that matrices from the left and right representation sets commute with each other, which is an important property related to the CSS orthogonality condition.

source
QuantumClifford.ECC.generalized_bicycle_codes — Method

Generalized bicycle codes, which are a special case of abelian 2GBA codes (and therefore of lifted product codes). Here the group is chosen as the cyclic group of order l, and the base matrices a and b are the sum of the group algebra elements corresponding to the shifts a_shifts and b_shifts.

See also: two_block_group_algebra_codes, bicycle_codes.

A [[254, 28, 14 ≤ d ≤ 20]] code from (A1) in Appendix B of (Panteleev and Kalachev, 2021).

julia> import Hecke; using QuantumClifford.ECC
+(175, 19)

Code subfamilies and convenience constructors for them

  • When the base matrices of the LPCode are 1×1, the code is called a two-block group-algebra code two_block_group_algebra_codes.
  • When the base matrices of the LPCode are 1×1 and their elements are sums of cyclic permutations, the code is called a generalized bicycle code generalized_bicycle_codes.
  • When the two matrices are adjoint to each other, the code is called a bicycle code bicycle_codes.

The representation function

We use the default representation function Hecke.representation_matrix to convert a GF(2)-group algebra element to a binary matrix. The default representation, provided by Hecke, is the permutation representation.

We also accept a custom representation function as detailed in LiftedCode.

See also: LiftedCode, two_block_group_algebra_codes, generalized_bicycle_codes, bicycle_codes, haah_cubic_codes.

  • A::Union{LinearAlgebra.Adjoint{<:Hecke.GroupAlgebraElem, <:Matrix{<:Hecke.GroupAlgebraElem}}, Matrix{<:Hecke.GroupAlgebraElem}}: the first base matrix of the code, whose elements are in a group algebra.

  • B::Union{LinearAlgebra.Adjoint{<:Hecke.GroupAlgebraElem, <:Matrix{<:Hecke.GroupAlgebraElem}}, Matrix{<:Hecke.GroupAlgebraElem}}: the second base matrix of the code, whose elements are in the same group algebra as A.

  • GA::Hecke.GroupAlgebra: the group algebra for which elements in A and B are from.

  • repr::Function: a function that converts a group algebra element to a binary matrix; default to be the permutation representation for GF(2)-algebra.

source
QuantumCliffordHeckeExt.LiftedCode — Type
struct LiftedCode <: QuantumClifford.ECC.ClassicalCode

Classical codes lifted over a group algebra, used for lifted product code construction ((Panteleev and Kalachev, 2021), (Panteleev and Kalachev, Jun 2022))

The parity-check matrix is constructed by applying repr to each element of A, which is mathematically a linear map from a group algebra element to a binary matrix. The size of the parity check matrix will enlarged with each element of A being inflated into a matrix. The procedure is called a lift (Panteleev and Kalachev, Jun 2022).

Constructors

A lifted code can be constructed via the following approaches:

  1. A matrix of group algebra elements.

  2. A matrix of group elements, where a group element will be considered as a group algebra element by assigning a unit coefficient.

  3. A matrix of integers, where each integer represent the shift of a cyclic permutation. The order of the cyclic permutation should be specified.

The default GA is the group algebra of A[1, 1], the default representation repr is the permutation representation.

The representation function repr

We use the default representation function Hecke.representation_matrix to convert a GF(2)-group algebra element to a binary matrix. The default representation, provided by Hecke, is the permutation representation.

We also accept a custom representation function (the repr field of the constructor). Whatever the representation, the matrix elements need to be convertible to Integers (e.g. permit lift(ZZ, ...)). Such a customization would be useful to reduce the number of bits required by the code construction.

For example, if we use a D4 group for lifting, our default representation will be 8×8 permutation matrices, where 8 is the group's order. However, we can find a 4×4 matrix representation for the group, e.g. by using the typical 2×2 representation and converting it into binary representation by replacing "1" with the Pauli I, and "-1" with the Pauli X matrix.

See also: LPCode.

  • A::Union{LinearAlgebra.Adjoint{<:Hecke.GroupAlgebraElem, <:Matrix{<:Hecke.GroupAlgebraElem}}, Matrix{<:Hecke.GroupAlgebraElem}}: the base matrix of the code, whose elements are in a group algebra.

  • GA::Hecke.GroupAlgebra: the group algebra for which elements in A are from.

  • repr::Function: a function that converts a group algebra element to a binary matrix; default to be the permutation representation for GF(2)-algebra.

source
QuantumCliffordHeckeExt.LiftedCode — Method

LiftedCode constructor using the default GF(2) representation (coefficients converted to a permutation matrix by representation_matrix provided by Hecke).

source
QuantumClifford.ECC.check_repr_commutation_relation — Method

Checks the commutation relation between the left and right representation matrices for two randomly-sampled elements a and b in the group algebra ℱ[G] with a general group G. It verifies the commutation relation that states, L(a)·R(b) = R(b)·L(a). This property shows that matrices from the left and right representation sets commute with each other, which is an important property related to the CSS orthogonality condition.

source
QuantumClifford.ECC.generalized_bicycle_codes — Method

Generalized bicycle codes, which are a special case of abelian 2GBA codes (and therefore of lifted product codes). Here the group is chosen as the cyclic group of order l, and the base matrices a and b are the sum of the group algebra elements corresponding to the shifts a_shifts and b_shifts.

See also: two_block_group_algebra_codes, bicycle_codes.

A [[254, 28, 14 ≤ d ≤ 20]] code from (A1) in Appendix B of (Panteleev and Kalachev, 2021).

julia> import Hecke; using QuantumClifford.ECC
 
 julia> c = generalized_bicycle_codes([0, 15, 20, 28, 66], [0, 58, 59, 100, 121], 127);
 
@@ -198,12 +198,12 @@
 julia> c1 = generalized_bicycle_codes([0, 15, 16, 18], [0, 1, 24, 27], l);
 
 julia> code_n(c1), code_k(c1)
-(70, 8)
source
QuantumClifford.ECC.haah_cubic_codes — Method

Haah’s cubic codes (Haah, 2011) can be viewed as generalized bicycle (GB) codes with the group G = Cₗ × Cₗ × Cₗ, where l denotes the lattice size. In particular, a GB code with the group G = ℤ₃ˣ³ corresponds to a cubic code.

The ECC Zoo has an entry for this family.

julia> import Hecke; using QuantumClifford.ECC;
+(70, 8)
source
QuantumClifford.ECC.haah_cubic_codes — Method

Haah’s cubic codes (Haah, 2011) can be viewed as generalized bicycle (GB) codes with the group G = Cₗ × Cₗ × Cₗ, where l denotes the lattice size. In particular, a GB code with the group G = ℤ₃ˣ³ corresponds to a cubic code.

The ECC Zoo has an entry for this family.

julia> import Hecke; using QuantumClifford.ECC;
 
 julia> c = haah_cubic_codes([0, 15, 20, 28, 66], [0, 58, 59, 100, 121], 6);
 
 julia> code_n(c), code_k(c)
-(432, 8)

See also: bicycle_codes, generalized_bicycle_codes, two_block_group_algebra_codes.

source
QuantumClifford.ECC.two_block_group_algebra_codes — Method

Two-block group algebra (2BGA) codes, which are a special case of lifted product codes from two group algebra elements a and b, used as 1x1 base matrices.

Examples of 2BGA code subfamilies

C₄ x C₂

Here is an example of a [[56, 28, 2]] 2BGA code from Table 2 of (Lin and Pryadko, 2024) with direct product of C₄ x C₂.

julia> import Hecke: group_algebra, GF, abelian_group, gens; using QuantumClifford.ECC;
+(432, 8)

See also: bicycle_codes, generalized_bicycle_codes, two_block_group_algebra_codes.

source
QuantumClifford.ECC.two_block_group_algebra_codes — Method

Two-block group algebra (2BGA) codes, which are a special case of lifted product codes from two group algebra elements a and b, used as 1x1 base matrices.

Examples of 2BGA code subfamilies

C₄ x C₂

Here is an example of a [[56, 28, 2]] 2BGA code from Table 2 of (Lin and Pryadko, 2024) with direct product of C₄ x C₂.

julia> import Hecke: group_algebra, GF, abelian_group, gens; using QuantumClifford.ECC;
 
 julia> GA = group_algebra(GF(2), abelian_group([14,2]));
 
@@ -263,4 +263,4 @@
 julia> c = two_block_group_algebra_codes(A, B);
 
 julia> code_n(c), code_k(c)
-(108, 12)

See also: LPCode, generalized_bicycle_codes, bicycle_codes, haah_cubic_codes.

source
+(108, 12)

See also: LPCode, generalized_bicycle_codes, bicycle_codes, haah_cubic_codes.

source
QuantumCliffordHeckeExt.group_algebra_conj — Method

Compute the conjugate of a group algebra element. The conjugate is defined by inversing elements in the associated group.

source
diff --git a/dev/ECC_evaluating/2ed4ea99.png b/dev/ECC_evaluating/2ed4ea99.png new file mode 100644 index 0000000000000000000000000000000000000000..1c2152c4d28691273affa5098c694792bef7ef28 GIT binary patch literal 42752 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 ?8?A(88oylf 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

B_zClH=pO;X>TMq4@)o~(Q~1v3_g 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%0A8PXxO_pZ>Nsc37klb|S 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

4|^vVm<(R&kbjmw$XLQ{Ta?u+p-jh3 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 z z?BN3#@1JED4sh@2!Gi?u8R^|SQBKp)pbw3o1H6G;Z^MQm)M^i&1ENB6`I=Hod~EXq3f z`Rrbt4usi6m5hdMh+9r}_E)Pl3TN(tOON><*z3Q3PAx`0S%mBg`ihAQpU@v-M2qG* z4Z@)xop3z{*_~!EQYHxOch1ppQ{l((O(tnn!nX)}IyQwRK^TXC)AmL_JG^f&%uYc`0m{!cnewE@&m)Ux+Oic<`5z9h#+im?k3e96JrtJ|w9dq1V@D!9aJ3=ZKJ?c&F{hocop4axhan zqJZ727rt`r62K9cKbF4=3b`Q1zZuQY#h#@7?fLC)G~)&wD97^n@|7j#>0===v9t1>Wl|aDEK@Q7Zu%x zk}CGto*22?@H`D!K%5bggF%>%>x*<3?iNG|e(l;R+&rYwxVSJ>Xsw%t)gflE0Z3Q^ z6PDrOE^KNLx}Y{S8XC{T9en=<>9o~j*PMMBcpVx*ef|A$H*bnys`Ah7?fdudN978* z3|$H&siuCx3I*!Xp#f?2s&&z6s6zt8m>&BA_xbQgM9!<&jZ*w`^@k(l7@ z+69Y6P)yK1_zP$OjgB%vw3>+x;HcpB;O75En;E4e&|W@Glz*p@)PcP5cXA*X;^H5} z!^2;{x?{INBoh=6fWihMBy|@i35xc>=6BUNMVTBYRTn$9oWQ{OGc%k>wWj|5I@CFN z%0Upb2WHap_a}E%_}k8H}7eU>)Ly zBDe&zayp&imT(AXwxpRzPH`154`i?*4tW96mXa%_)1yTg2!y6Sf7s2NH^Gd+wp$qW zcyGDs+Q8M=a~_d%n%H=IgNw@mk&E0jXf7DX7NF=dHaD~O5$Y>Uw81k{u%Fk;!h$w% z9A-6B8MiT@=+S{3Gco{aa_uD23iY+ys3fP&^}RVfT$IKNI26gw!b}_oL)F2L(UK@c zs;UH*EZMSUODU)*;Fi=`t7x%DpzcXXICkjJ3ftdJrr0?F#7jI!aWe8ahj?K_PlJpB zoq?I`^^zts&3HODZ`uUuO(P&c1k>^1F2aE?_CRDrVzWLFH`DBnCqP?-?=3L(1jYg& z9hSu)6y@aP_{oA|q;FvGwzk#_j|nieN1=$in8{s=-W`@ZP=|GE*G5|21D9jHxpPK# z_B0ARpcDjX0Zs`N0Q(4@X4Abn7dv8Lv4njh@HAk6TOKLc7;sb`-07P)U4Z3&`=)^6 z38pVIEOD6wYk-e_Ky~*|gheJ8T@fGt^htsnlX!^p0CGdz{pJ=Jt4EF3H8-37I(tY* zrwW@Cgm0SBgE_X!2XcbH1~$RqjiPpI M@6o!aX?Onr0JM97#Q*>R diff --git a/dev/ECC_evaluating/8541d19e.png b/dev/ECC_evaluating/8541d19e.png new file mode 100644 index 0000000000000000000000000000000000000000..6be56fd72bf0ebb016891cf0b62d195c573152e2 GIT binary patch literal 55472 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

aJwq!3`R_yI8j|qjr;Iq7KIXw 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
s}ZxPSU?$#z)v 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 Z8fky>n&JrWRpPk~_8!u|Pd)nA{{dLMk7ED; diff --git a/dev/ECC_evaluating/index.html b/dev/ECC_evaluating/index.html index cd67ab35d..1d771232f 100644 --- a/dev/ECC_evaluating/index.html +++ b/dev/ECC_evaluating/index.html @@ -38,7 +38,7 @@ end end -make_decoder_figure(mem_errors, results, "Shor's code with a lookup table decoder")Example block output

Testing out the toric code with a decoder provided by the python package pymatching (provided in julia by the meta package PyQDecoders.jl).

import PyQDecoders
+make_decoder_figure(mem_errors, results, "Shor's code with a lookup table decoder")
Example block output

Testing out the toric code with a decoder provided by the python package pymatching (provided in julia by the meta package PyQDecoders.jl).

import PyQDecoders
 
 mem_errors = 0.001:0.005:0.1
 codes = [Toric(4,4), Toric(6,6)]
@@ -53,4 +53,4 @@
     end
 end
 
-make_decoder_figure(mem_errors, results, "Toric code with a MWPM decoder")
Example block output +make_decoder_figure(mem_errors, results, "Toric code with a MWPM decoder")Example block output diff --git a/dev/allops/index.html b/dev/allops/index.html index 4b1a7e30d..a17c2b3c4 100644 --- a/dev/allops/index.html +++ b/dev/allops/index.html @@ -10,4 +10,4 @@ noise = UnbiasedUncorrelatedNoise(ε) noisy_gate = NoisyGate(SparseGate(tCNOT, [2,4]), noise)Example block output

In circuit diagrams the noise is not depicted, but after each application of the gate defined in noisy_gate, a noise operator will also be applied. The example above is of Pauli Depolarization implemented by UnbiasedUncorrelatedNoise.

One can also apply only the noise operator by using NoiseOp which acts only on specified qubits. Or alternatively, one can use NoiseOpAll in order to apply noise to all qubits.

[NoiseOp(noise, [4,5]), NoiseOpAll(noise)]
Example block output

The machinery behind noise processes and different types of noise is detailed in the section on noise

Coincidence Measurements

Global parity measurements involving single-qubit projections and classical communication are implemented with BellMeasurement. One needs to specify the axes of measurement and the qubits being measured. If the parity is trivial, the circuit continues, if the parity is non-trivial, the circuit ends and reports a detected failure. This operator is frequently used in the simulation of entanglement purification.

BellMeasurement([sMX(1), sMY(3), sMZ(4)])
Example block output

There is also NoisyBellMeasurement that takes the bit-flip probability of a single-qubit measurement as a third argument.

Stabilizer Measurements

A measurement over one or more qubits can also be performed, e.g., a direct stabilizer measurement on multiple qubits without the use of ancillary qubits. When applied to multiple qubits, this differs from BellMeasurement as it performs a single projection, unlike BellMeasurement which performs a separate projection for every single qubit involved. This measurement is implemented in PauliMeasurement which requires a Pauli operator on which to project and the index of the classical bit in which to store the result. Alternatively, there are sMX, sMZ, sMY if you are measuring a single qubit.

[PauliMeasurement(P"XYZ", 1), sMZ(2, 2)]
Example block output

Reset Operations

The Reset operations lets you trace out the specified qubits and set their state to a specific tableau.

new_state = random_stabilizer(3)
 qubit_indices = [1,2,3]
-Reset(new_state, qubit_indices)
Example block output

It can be done anywhere in a circuit, not just at the beginning.

+Reset(new_state, qubit_indices)Example block output

It can be done anywhere in a circuit, not just at the beginning.

diff --git a/dev/canonicalization/13e138a3.png b/dev/canonicalization/13e138a3.png deleted file mode 100644 index a83af96ff7c1f51518d4c4a02dbaea3a5e2eeaa6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 9895 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 diff --git a/dev/canonicalization/3a263328.png b/dev/canonicalization/3a263328.png deleted file mode 100644 index f5a7a37b1d7fe8d036fbf59ea758f54e5a3d3595..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 9442 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 VM)l53ARxpy2kiFe?>l<-e*m@ZWb6O{ diff --git a/dev/canonicalization/5cef4748.png b/dev/canonicalization/5cef4748.png new file mode 100644 index 0000000000000000000000000000000000000000..1781942d759fcaa054ee931b0a64da700e872518 GIT binary patch literal 9770 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 literal 0 HcmV?d00001 diff --git a/dev/canonicalization/7d7b216e.png b/dev/canonicalization/7d7b216e.png new file mode 100644 index 0000000000000000000000000000000000000000..4add49a3a7dbfbe7bc00d3365f450ca62578e6e8 GIT binary patch literal 9476 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 literal 0 HcmV?d00001 diff --git a/dev/canonicalization/af461151.png b/dev/canonicalization/af461151.png deleted file mode 100644 index 2a07484f78ee48ed83c6847aa291a79e96fbc755..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 9717 zcmds-dsI_*w#PGLeNx2MQB)A@vK5sIc2FWpf>tY4lvtHlfM8`TVjw6IKtd9$R$2uz zN&%Hev|gkV4^cD(0!dI5Dk!K(B7r2l0|_KN^M2gliQc)hR@a@mtF>Oe;g76!RygOk z_isNw`};dT?DF@uowaBd0)epI_T`q{2*i6g5r`?LX8ajkLEA+@;A`4`Ki@3~3;cJP zTbzYJEJ1ABvT1K}{;-&uE+%qiqs=vU{>=TN&bjJx0Au-bQQ(ZM=SAxkVYV3x)(?Vt zek)GTcG$uQ5dCG|-u)+r3qA}__c>nv0=wudM)a&v1sq| z`=vga=h}QORg`XrT6oQaBPrhILl?4ysqy{!s*y+Rg2BA}{1~vXUau>{>EQb^^1Y7` zh>goP%|IaLY@Y*`e(J+h;QE!f?DEfMoHM*!KfPX`*(K`j?fooFF*9k#pAd-8D>sA1 z|1G3SpLsQGfl13>oRu|^zu|4P;;nb{|KkP9Rg)lC5W72$$qGW*gjlG6tZoyACyBe9 zjXVuk_3d=0gAf$TR(2e1hSt%RyoW#xoWFAAiYv1^-eNXEtS`>a=c-vu@=v}LlOiI5 zPa)%DyY7AGPSrJ@ZR%mBgWO4YxS}|J>|%3j{}Xx;gl!#6Fe_`<7c|LR8KHQS$wb#Z ziUI+ArfDf0xE$F%8~3pCm=OFh&!DX8I_+RqMxxE5G%3{rp4Z9*ku>>_!9BQV$}QA#No){m0ls8`bjs_;(0m&dKR^ALlru=wnR71N|!XuOL!?tnBwdX(aE1{j6+_M$FjDE@& zy_dP!#W=z!GWZngBK$OdsMRBloKY%SZzHb@H3g}uCfQMW9fO{~TbimZE;2C518Kyb zq6mT81pzakZr1J-Yi)2^cVZ8uJ+a4B_9+?jIJtiuLwP!tXmI=?kHCqRR3GD8Oe*PQ zX_A~W$RM*|pvJN^BeF0EC}rE9m?H~oFyDcCbtX=ssR55o6Q|Kr>oC6%%- zXpnM!@wn!B2F=!u=@2&=(UxQfK@Lnx{B|x$WxrjMM575Zaw#EI`>_0YG_~E#8J*`U z6J)TvZTu%2%O+4nIkhr)j=IApLVFL-)`3we^nuX3~4raVX4U|^P#G^8XVO$$)uVTQj1x`7W6mMEo{rp zo8QA>c;O6#$bB#C#wwK4_0iRsw^ZkmJ!B4r? z{pER;Gq&PzSG&}##!$wx(kNvEeYp|5!(I2T(ovto8@q3%fEhvEk%-nmrBMd`B2osf zq)nSPEwi=%gE71d2)C4I^-$YUSyL>8QiL=wTCiZCzj*$?FRT1CIBM#fHmItz{MQfa znyHjrAEq^*ZehssJt$qZxncPq+;pt{qI0IL9kfa;Me+WFP^}*+`i2npM6uK{`_|n) zF8bb)663{%&QQA~+)FYwZ`u4w{fs@x_{$@QDx=3sIimus!}1Pihx|~a1nW@hNbR{O zlLS{bCv?sJ=nr1|YcIlZ={t_~K)Nj#t8TOfA<>={)r4x6XBY=}W8&dOLGuoL?2Y); zQOR)jI4hAx%Teay=9JKNa+j#yn)95|XHh(sAUfNSr?JnpXPB2&#q0|bYma%*!;wvE zy5CiQ)NaQ6Y3jEN&#uY~-it)X@7pF$#zPr2K`addPLg0ltCL8eOn_)9G8AF_C#PNs zaN_ANx|1<1fv4?IiG%bjW8q3J)*oNc&FK53ZYr^-*i1hg+8)UM{bBN|U2zV99ROH^ zS|(dJy8;HCH$Z9dvzLe;W!P-j)C-1O#qKC-v36ubziLGo{YAh!99he4x2abI@S*L) zrH;-{*ibKN&dyJPLp*QsL12|%H9lP7C`F;M6%x_NuEA93nM-lYAwFi4{hKo3HA1YO zL`Hmx^uAM`K)sQ`)f!vV+*y(4LY#A#b}dLG_1tt2GI5Ju1Ry2Xbgpp5;GDmfZ>_^? zHsDuAs2yzBq4>sS^IJ2R!Cq|O9l>>8=iZg3WrjMBX6`LQ!C>v;&k=~@yWpC<V&xGDzT^FZXf8@tOIk;%Ikb*e|p`4u3j18 z39)ugsoJjb%Lw2N`7ytNv=^nHQ8D6VSKcL7w+nxd3HsZ(Swt?}IM_J$+y~czo6O;m zui3oh`rmB7b&ViXdO;8B;1CrbptYCqrN`PDae+w-;7R8RN+V8^4zs0{Q+7@Z7k&UY zHOz`c1eEQ}i}-P*khZQQFz0J3>Mn&MV9RJNHKTprUl z)jn)j$^xIg(-4Tx@8rRu0W zD!38SO8*KTxF#e^Y2IZCgU?_n9C-6~vVXD1=OvNCr3zMu7dbr)|@81Hk;u!!ie{wvH$a7h*S< zCR*b7CbikDJa7rN>K|}%Z;7$3nF1^-t9PbW^Z6DSYzB+zlyv{3E$}p0v)56Fs&RQX zn2_TZt{)MGtpS)b zQBxkz#40SF-4WmDCChJNWX*t6M0qhkzk1@CAJy37%oYSf*hvAK$4X1HZmanA*R`j^ zs}flP+~}F0j>EOKTvR&!uV89_@`(n3_F7@s(Shcu!ejj`A&#W2X9nN;X~O--S@4bB zj%mBnEEB~(i}mB`;dV<`kG)&i@)=j^Pp1h48MM}&Ne`}l8&2$Tm0zYKKwNc(Z3yEpbRu|x#fW=ix4ntV1r5blF1j~DuDn>nAFLd1!V>~^Y$1EMQd*TOh~OaqG0TQs9F{s)2(O3lqdjP#GWd}wNN|+Gl-WD)(dBN#1_;Af|(@ZX+M}Y z1nW~byETQ**{>G%jF z_S@VuDTljKTV+QIU?PXBmc|`e(%|{qaCX=NeTBXR0 zm-)E0Kf#hdy#M37ClrHlob#S|9|the^XK#MnG9oc2-NN(v?$_qe2$7lRG$nB~5%HBD-*-!J_&+Nynh zyz=XG_#;^mqy}ij8~;A35K>hnDIVeu$Hs+LCy&lW#mJfpB8=Vkp?K!8$M~&Vx1O2Z zg7oqVSwnVA8M!;%nLP0nNAF(8N>-^s34`aN)l-YyNlabsg~}tFn6%ZzylIKqN)^b+ z1gc(SZD_rVz3xnsxsvu7u+FYstu*E8Kmd$*>hMvCs2 z`B-$I1&+Unq@jkRF$S}SPpw-R<=FQv{d>N(pQFZQ&6X!==;v6&19!@i)_@?BxIXO2 zgLyQRIv78EEss#bxNFr%I5A=l(Z=2_1`-2W18jse%dfJ1s2 zXl2C!m%`+30ThZs>v{zuAflM_q{jYcXMG=#{(uNm#Zu?Xyk)T7G`Yf}Lu4of|Vq3V@Y zDgrbN7!mA-RR*-PvrFoF---d#fqY2dP6_}VVf_6|!z#zXwxrf?kUYhbU=7DKDNK^R z{3)_fQ!OJ8MLOdlF%T4G1xb?4cBnOxb?HDJJnB-AusdmXr+v#51Y*a7E7bS2TLjRC zpQMQu@qG=D+ul4<@z8hgy+wma6y!ry4cxuxNY$zvTP{>oW z1lWiODeRcY!(~ffiBP{}sa87yS&4-gI_bxOW`7_z+!Kwa+?yG$uP4Lyywsp3mVyu8 zJjukY>pI2eO+xTi6rxC5eSK-$4mr)V()DGeXRK(Vl}TZ-)WEVRprFaiOP)F2UJt27c4koQDxj+0QAq$} z{wnN*%t8Tz-=jPvla*L&i*!ucxZ-8pP}b^Q{4I%4aB06>=Y4^pL^Zc+Pw5gpFH;qO|G^t;Z_yto+Sq zM6jNqb$QfLahZ@B^O(muQh2{SRuX~a?eFUVLYt`UhcAdd9`!cTn}BW-D9r>gOmlo- zK}P$kJ5|;DD(V;!o@X@#rUPBzo)?&Eme=OuR;8uM%K<(G@II}dmMaA6Y+RYFz%q2! zt#Hq45Mf@Uitz8x)8Mw=NnZ_!mymjcaLI)Q^ky~CB!g14JM)s@&L!$Mu?#ICQNV?x zaz@|bKCLptW~D5YVMGT&6L~TC*tRWQ+H2p6Y?^-g_LJ{=dWh|lb-sAbS$^3QD-(YI z77Gi%Zi1ju)nqmN_uP=SA{Z!gV(p90F*s_<9~%^PK{vqIg@Yy$94x=tVhb6b&Nqn-8W@C_+ypy_fB#T?ds z<@N~gkoj<1O4IMet5&IEiud*RVTs$>H9Tzv7$C7o$wDxD0>#?vCeXZF)Nt6$SBY^* zbfEE(U2ZA6JZAq_Vy#uIgtVa#Uo>Ogw|ZsH3#9~sm|6(G3-Et< z;0~0{Vm92|$m# z1~x$sapB4F*sd%OFj~N;CQ&=P)_x7Z8Wz*%Q4jcK^NO1`SlaBvy^G)6NO74#(YMfX z2~WSU4^MasBZcHu!)*m(Tf705{tUxDx`&t)l9lrQH#Gnjf`RN39sLhwjgxqOg;n3% zb7ZnL$hrS2%ru?b@Ys)~T~_t-dN4R9X3`GdDLXN8-rn6YMSWJTmU)x?#p@jDZXE3$ z&ZyT>a}l9hG}97^hXI<_d{Gi~`&n+^V1bAkGni%Z!I)L>*e`1~V2C}f_NSsvy~!cy zkZfK|p?YGEyzb&w{W2F95*a9v#|Z-p1;9OUAnIG`5htk@h<=QeS4mCE&dz=K;ha#y z!i5XH8fqPF`H6tz{wKA0uYg$qEFGu>lxb&c%Mt((PnQ(lw_e@t=)zCz)^=GByx-23 zMPB;>+8gD7xA-lbf9cqgxcK-oVH6xVr@?`AWQF?U?^pcO8#;3uerLaXqwwzd)+pxeQ#I`T|x0HUq@5Fxs$;fOK diff --git a/dev/canonicalization/b9097138.png b/dev/canonicalization/b9097138.png new file mode 100644 index 0000000000000000000000000000000000000000..e7048d91d251226fcabb3882d0fd0994bfd365be GIT binary patch literal 9805 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 Fe*i1Yj^h9T diff --git a/dev/canonicalization/dea66803.png b/dev/canonicalization/dea66803.png new file mode 100644 index 0000000000000000000000000000000000000000..b56fc0a073ee483053d47b3a808049e7ad78d415 GIT binary patch literal 9906 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 literal 0 HcmV?d00001 diff --git a/dev/canonicalization/index.html b/dev/canonicalization/index.html index 7a206ba43..7121ae323 100644 --- a/dev/canonicalization/index.html +++ b/dev/canonicalization/index.html @@ -2,13 +2,13 @@ Canonicalization · QuantumClifford.jl
GitHub

Canonicalization operations

Different types of canonicalization operations are implemented. All of them are types of Gaussian elimination.

canonicalize!

First do elimination on all X components and only then perform elimination on the Z components. Based on (Garcia et al., 2012). It is used in logdot for inner products of stabilizer states.

The final tableaux, if square should look like the following

If the tableaux is shorter than a square, the diagonals might not reach all the way to the right.

using QuantumClifford, CairoMakie
 f=Figure()
 stabilizerplot_axis(f[1,1], canonicalize!(random_stabilizer(20,30)))
-f
Example block output

canonicalize_rref!

Cycle between elimination on X and Z for each qubit. Particularly useful for tracing out qubits. Based on (Audenaert and Plenio, 2005). For convenience reasons, the canonicalization starts from the bottom row, and you can specify as a second argument which columns to be canonicalized (useful for tracing out arbitrary qubits, e.g., in traceout!).

The tableau canonicalization is done in recursive steps, each one of which results in something akin to one of these three options 

using QuantumClifford, CairoMakie
+f
Example block output

canonicalize_rref!

Cycle between elimination on X and Z for each qubit. Particularly useful for tracing out qubits. Based on (Audenaert and Plenio, 2005). For convenience reasons, the canonicalization starts from the bottom row, and you can specify as a second argument which columns to be canonicalized (useful for tracing out arbitrary qubits, e.g., in traceout!).

The tableau canonicalization is done in recursive steps, each one of which results in something akin to one of these three options 

using QuantumClifford, CairoMakie
 f=Figure()
 stabilizerplot_axis(f[1,1], canonicalize_rref!(random_stabilizer(20,30),1:30)[1])
-f
Example block output

canonicalize_gott!

First do elimination on all X components and only then perform elimination on the Z components, but without touching the qubits that were eliminated during the X pass. Unlike other canonicalization operations, qubit columns are reordered, providing for a straight diagonal in each block. Particularly useful as certain blocks of the new created matrix are related to logical operations of the corresponding code, e.g. computing the logical X and Z operators of a MixedDestabilizer. Based on (Gottesman, 1997).

A canonicalized tableau would look like the following (the right-most block does not exist for square tableaux). 

using QuantumClifford, CairoMakie
+f
Example block output

canonicalize_gott!

First do elimination on all X components and only then perform elimination on the Z components, but without touching the qubits that were eliminated during the X pass. Unlike other canonicalization operations, qubit columns are reordered, providing for a straight diagonal in each block. Particularly useful as certain blocks of the new created matrix are related to logical operations of the corresponding code, e.g. computing the logical X and Z operators of a MixedDestabilizer. Based on (Gottesman, 1997).

A canonicalized tableau would look like the following (the right-most block does not exist for square tableaux). 

using QuantumClifford, CairoMakie
 f=Figure()
 stabilizerplot_axis(f[1,1], canonicalize_gott!(random_stabilizer(30))[1])
-f
Example block output

canonicalize_clip!

Convert to the "clipped" gauge of a stabilizer state resulting in a "river" of non-identity operators around the diagonal.

using QuantumClifford, CairoMakie
+f
Example block output

canonicalize_clip!

Convert to the "clipped" gauge of a stabilizer state resulting in a "river" of non-identity operators around the diagonal.

using QuantumClifford, CairoMakie
 f=Figure()
 stabilizerplot_axis(f[1,1], canonicalize_clip!(random_stabilizer(30)))
-f
Example block output

The properties of the clipped gauge are:

  1. Each qubit is the left/right "endpoint" of exactly two stabilizer rows.
  2. For the same qubit the two endpoints are always different Pauli operators.

This canonicalization is used to derive the bigram a stabilizer state, which is also related to entanglement entropy in the state.

Introduced in (Nahum et al., 2017), with a more detailed explanation of the algorithm in Appendix A of (Li et al., 2019).

+fExample block output

The properties of the clipped gauge are:

  1. Each qubit is the left/right "endpoint" of exactly two stabilizer rows.
  2. For the same qubit the two endpoints are always different Pauli operators.

This canonicalization is used to derive the bigram a stabilizer state, which is also related to entanglement entropy in the state.

Introduced in (Nahum et al., 2017), with a more detailed explanation of the algorithm in Appendix A of (Li et al., 2019).

diff --git a/dev/commonstates/index.html b/dev/commonstates/index.html index 6a9b5d780..1ea432736 100644 --- a/dev/commonstates/index.html +++ b/dev/commonstates/index.html @@ -72,4 +72,4 @@ + XXXX + ZZ__ + _ZZ_ -+ __ZZ ++ __ZZ diff --git a/dev/datastructures/index.html b/dev/datastructures/index.html index 4206d5296..24c94cbb4 100644 --- a/dev/datastructures/index.html +++ b/dev/datastructures/index.html @@ -1,2 +1,2 @@ -Datastructure Choice · QuantumClifford.jl
GitHub

Data Structures Options

Choosing Appropriate Tableau Data Structure

There are four different data structures used to represent stabilizer states. If you will never need projective measurements you probably would want to use Stabilizer. If you require projective measurements, but only on pure states, Destabilizer should be the appropriate data structure. If mixed stabilizer states are involved, MixedStabilizer would be necessary.

Stabilizer is simply a list of Pauli operators in a tableau form. As a data structure it does not enforce the requirements for a pure stabilizer state (the rows of the tableau do not necessarily commute, nor are they forced to be Hermitian; the tableau might be underdetermined, redundant, or contradictory). It is up to the user to ensure that the initial values in the tableau are meaningful and consistent.

canonicalize!, project!, and generate! can accept an under determined (mixed state) Stabilizer instance and operate correctly. canonicalize! can also accept a redundant Stabilizer (i.e. not all rows are independent), leaving as many identity rows at the bottom of the canonicalized tableau as the number of redundant stabilizers in the initial tableau.

canonicalize! takes $\mathcal{O}(n^3)$ steps. generate! expects a canonicalized input and then takes $\mathcal{O}(n^2)$ steps. project! takes $\mathcal{O}(n^3)$ for projecting on commuting operators due to the need to call canonicalize! and generate!. If the projections is on an anticommuting operator (or if keep_result=false) then it takes $\mathcal{O}(n^2)$ steps.

MixedStabilizer provides explicit tracking of the rank of the mixed state and works properly when the projection is on a commuting operator not in the stabilizer (see table below for details). Otherwise it has the same performance as Stabilizer.

The canonicalization can be made unnecessary if we track the destabilizer generators. There are two data structures capable of that.

Destabilizer stores both the destabilizer and stabilizer states. project! called on it never requires a stabilizer canonicalization, hence it runs in $\mathcal{O}(n^2)$. However, project! will raise an exception if you try to project on a commuting state that is not in the stabilizer as that would be an expensive $\mathcal{O}(n^3)$ operation.

MixedDestabilizer tracks both the destabilizer operators and the logical operators in addition to the stabilizer generators. It does not require canonicalization for measurements and its project! operations always takes $\mathcal{O}(n^2)$.

For the operation _, anticom_index, result = project!(...) we have the following behavior:

projectionStabilizerMixedStabilizerDestabilizerMixedDestabilizer
on anticommuting operator anticom_index>0 result===nothingcorrect result in $\mathcal{O}(n^2)$ stepssame as Stabilizersame as Stabilizersame as Stabilizer
on commuting operator in the stabilizer anticom_index==0 result!==nothing$\mathcal{O}(n^3)$; or $\mathcal{O}(n^2)$ if keep_result=false$\mathcal{O}(n^3)$$\mathcal{O}(n^2)$ if the state is pure, throws exception otherwise$\mathcal{O}(n^2)$
on commuting operator out of the stabilizer[1] anticom_index==rank result===nothing$\mathcal{O}(n^3)$, but the user needs to manually include the new operator to the stabilizer; or $\mathcal{O}(n^2)$ if keep_result=false but then result indistinguishable from cell above and anticom_index==0$\mathcal{O}(n^3)$ and rank goes up by onenot applicable if the state is pure, throws exception otherwise$\mathcal{O}(n^2)$ and rank goes up by one

Notice the results when the projection operator commutes with the state but is not generated by the stabilizers of the state (the last row of the table). In that case we have _, anticom_index, result = project!(...) where both anticom_index==rank and result===nothing, with rank being the new rank after projection, one more than the number of rows in the tableau before the measurement.

Bit Packing in Integers and Array Order

We do not use boolean arrays to store information about the qubits as this would be wasteful (7 out of 8 bits in the boolean would be unused). Instead, we use all 8 qubits in a byte and perform bitwise logical operations as necessary. Implementation details of the object in RAM can matter for performance. The library permits any of the standard UInt types to be used for packing the bits, and larger UInt types (like UInt64) are usually faster as they permit working on 64 qubits at a time (instead of 1 if we used a boolean, or 8 if we used a byte).

Moreover, how a tableau is stored in memory can affect performance, as a row-major storage usually permits more efficient use of the CPU cache (for the particular algorithms we use).

Both of these parameters are benchmarked (testing the application of a Pauli operator, which is an $\mathcal{O}(n^2)$ operation; and testing the canonicalization of a Stabilizer, which is an $\mathcal{O}(n^3)$ operation). Row-major UInt64 is the best performing and it is used by default in this library.

  • 1This can occur only if the state being projected is mixed. Both Stabilizer and Destabilizer can be used for mixed states by simply providing fewer stabilizer generators than qubits at initialization. This can be useful for low-level code that tries to avoid the extra memory cost of using MixedStabilizer and MixedDestabilizer but should be avoided otherwise. project! works correctly or raises an explicit warning on all 4 data structures.
+Datastructure Choice · QuantumClifford.jl
GitHub

Data Structures Options

Choosing Appropriate Tableau Data Structure

There are four different data structures used to represent stabilizer states. If you will never need projective measurements you probably would want to use Stabilizer. If you require projective measurements, but only on pure states, Destabilizer should be the appropriate data structure. If mixed stabilizer states are involved, MixedStabilizer would be necessary.

Stabilizer is simply a list of Pauli operators in a tableau form. As a data structure it does not enforce the requirements for a pure stabilizer state (the rows of the tableau do not necessarily commute, nor are they forced to be Hermitian; the tableau might be underdetermined, redundant, or contradictory). It is up to the user to ensure that the initial values in the tableau are meaningful and consistent.

canonicalize!, project!, and generate! can accept an under determined (mixed state) Stabilizer instance and operate correctly. canonicalize! can also accept a redundant Stabilizer (i.e. not all rows are independent), leaving as many identity rows at the bottom of the canonicalized tableau as the number of redundant stabilizers in the initial tableau.

canonicalize! takes $\mathcal{O}(n^3)$ steps. generate! expects a canonicalized input and then takes $\mathcal{O}(n^2)$ steps. project! takes $\mathcal{O}(n^3)$ for projecting on commuting operators due to the need to call canonicalize! and generate!. If the projections is on an anticommuting operator (or if keep_result=false) then it takes $\mathcal{O}(n^2)$ steps.

MixedStabilizer provides explicit tracking of the rank of the mixed state and works properly when the projection is on a commuting operator not in the stabilizer (see table below for details). Otherwise it has the same performance as Stabilizer.

The canonicalization can be made unnecessary if we track the destabilizer generators. There are two data structures capable of that.

Destabilizer stores both the destabilizer and stabilizer states. project! called on it never requires a stabilizer canonicalization, hence it runs in $\mathcal{O}(n^2)$. However, project! will raise an exception if you try to project on a commuting state that is not in the stabilizer as that would be an expensive $\mathcal{O}(n^3)$ operation.

MixedDestabilizer tracks both the destabilizer operators and the logical operators in addition to the stabilizer generators. It does not require canonicalization for measurements and its project! operations always takes $\mathcal{O}(n^2)$.

For the operation _, anticom_index, result = project!(...) we have the following behavior:

projectionStabilizerMixedStabilizerDestabilizerMixedDestabilizer
on anticommuting operator anticom_index>0 result===nothingcorrect result in $\mathcal{O}(n^2)$ stepssame as Stabilizersame as Stabilizersame as Stabilizer
on commuting operator in the stabilizer anticom_index==0 result!==nothing$\mathcal{O}(n^3)$; or $\mathcal{O}(n^2)$ if keep_result=false$\mathcal{O}(n^3)$$\mathcal{O}(n^2)$ if the state is pure, throws exception otherwise$\mathcal{O}(n^2)$
on commuting operator out of the stabilizer[1] anticom_index==rank result===nothing$\mathcal{O}(n^3)$, but the user needs to manually include the new operator to the stabilizer; or $\mathcal{O}(n^2)$ if keep_result=false but then result indistinguishable from cell above and anticom_index==0$\mathcal{O}(n^3)$ and rank goes up by onenot applicable if the state is pure, throws exception otherwise$\mathcal{O}(n^2)$ and rank goes up by one

Notice the results when the projection operator commutes with the state but is not generated by the stabilizers of the state (the last row of the table). In that case we have _, anticom_index, result = project!(...) where both anticom_index==rank and result===nothing, with rank being the new rank after projection, one more than the number of rows in the tableau before the measurement.

Bit Packing in Integers and Array Order

We do not use boolean arrays to store information about the qubits as this would be wasteful (7 out of 8 bits in the boolean would be unused). Instead, we use all 8 qubits in a byte and perform bitwise logical operations as necessary. Implementation details of the object in RAM can matter for performance. The library permits any of the standard UInt types to be used for packing the bits, and larger UInt types (like UInt64) are usually faster as they permit working on 64 qubits at a time (instead of 1 if we used a boolean, or 8 if we used a byte).

Moreover, how a tableau is stored in memory can affect performance, as a row-major storage usually permits more efficient use of the CPU cache (for the particular algorithms we use).

Both of these parameters are benchmarked (testing the application of a Pauli operator, which is an $\mathcal{O}(n^2)$ operation; and testing the canonicalization of a Stabilizer, which is an $\mathcal{O}(n^3)$ operation). Row-major UInt64 is the best performing and it is used by default in this library.

  • 1This can occur only if the state being projected is mixed. Both Stabilizer and Destabilizer can be used for mixed states by simply providing fewer stabilizer generators than qubits at initialization. This can be useful for low-level code that tries to avoid the extra memory cost of using MixedStabilizer and MixedDestabilizer but should be avoided otherwise. project! works correctly or raises an explicit warning on all 4 data structures.
diff --git a/dev/ecc_example_sim/index.html b/dev/ecc_example_sim/index.html index 87d6baf29..197a389fe 100644 --- a/dev/ecc_example_sim/index.html +++ b/dev/ecc_example_sim/index.html @@ -20,7 +20,7 @@ errors = [PauliError(i,errprob) for i in 1:code_n(code)] fullcircuit = [ecirc..., errors..., scirc...]Example block output

And running this noisy simulation:

frames = pftrajectories(fullcircuit; trajectories=nframes)
 pfmeasurements(frames)
4×6 Matrix{Bool}:
- 1  0  0  1  0  0
- 0  0  0  1  0  1
+ 0  0  0  0  1  1
  0  0  0  0  0  0
- 0  0  0  0  0  0
+ 0 0 0 0 0 0 + 0 0 0 0 0 0 diff --git a/dev/graphs/index.html b/dev/graphs/index.html index cb5a11460..d61d80bb7 100644 --- a/dev/graphs/index.html +++ b/dev/graphs/index.html @@ -43,4 +43,4 @@ + XZZ_ + ZX_Z + Z_XZ -+ _ZZX

Graphs are represented with the Graphs.jl package and plotting can be done both in Plots.jl and Makie.jl (with GraphMakie).

++ _ZZX

Graphs are represented with the Graphs.jl package and plotting can be done both in Plots.jl and Makie.jl (with GraphMakie).

diff --git a/dev/index.html b/dev/index.html index 05cd73581..208b0015e 100644 --- a/dev/index.html +++ b/dev/index.html @@ -15,4 +15,4 @@ julia> tCNOT * S"-XX +ZZ" - X_ -+ _Z

Circuit Simulation

The circuit simulation component of QuantumClifford.jl enables Monte Carlo (or symbolic) simulations of noisy Clifford circuits. It provides three main simulation methods: mctrajectories, pftrajectories, and petrajectories. These methods offer varying levels of efficiency, accuracy, and insight.

Monte Carlo Simulations with Stabilizer Tableaux (mctrajectories)

The mctrajectories method runs Monte Carlo simulations using a Stabilizer tableau representation for the quantum states.

Monte Carlo Simulations with Pauli Frames (pftrajectories)

The pftrajectories method runs Monte Carlo simulations of Pauli frames over a single reference Stabilizer tableau simulation. This approach is much more efficient but supports a smaller class of circuits.

Symbolic Depth-First Traversal of Quantum Trajectories (petrajectories)

The petrajectories method performs a depth-first traversal of the most probable quantum trajectories, providing a fixed-order approximation of the circuit's behavior. This approach gives symbolic expressions for various figures of merit instead of just a numeric value.

++ _Z

Circuit Simulation

The circuit simulation component of QuantumClifford.jl enables Monte Carlo (or symbolic) simulations of noisy Clifford circuits. It provides three main simulation methods: mctrajectories, pftrajectories, and petrajectories. These methods offer varying levels of efficiency, accuracy, and insight.

Monte Carlo Simulations with Stabilizer Tableaux (mctrajectories)

The mctrajectories method runs Monte Carlo simulations using a Stabilizer tableau representation for the quantum states.

Monte Carlo Simulations with Pauli Frames (pftrajectories)

The pftrajectories method runs Monte Carlo simulations of Pauli frames over a single reference Stabilizer tableau simulation. This approach is much more efficient but supports a smaller class of circuits.

Symbolic Depth-First Traversal of Quantum Trajectories (petrajectories)

The petrajectories method performs a depth-first traversal of the most probable quantum trajectories, providing a fixed-order approximation of the circuit's behavior. This approach gives symbolic expressions for various figures of merit instead of just a numeric value.

diff --git a/dev/mixed/index.html b/dev/mixed/index.html index 9e0c50203..aeb462253 100644 --- a/dev/mixed/index.html +++ b/dev/mixed/index.html @@ -57,4 +57,4 @@ + XXX + ZZ_ 𝒵ₗ━━━ -+ Z_Z

Destabilizer and MixedStabilizer do not use any column swaps on instantiation as they do not track the logical operators.

++ Z_Z

Destabilizer and MixedStabilizer do not use any column swaps on instantiation as they do not track the logical operators.

diff --git a/dev/noise/index.html b/dev/noise/index.html index 932ae70ed..5d4122a7a 100644 --- a/dev/noise/index.html +++ b/dev/noise/index.html @@ -1,2 +1,2 @@ -Noise Processes · QuantumClifford.jl
GitHub
+Noise Processes · QuantumClifford.jl
GitHub
diff --git a/dev/noisycircuits/index.html b/dev/noisycircuits/index.html index 0041a20f0..ba5c1929c 100644 --- a/dev/noisycircuits/index.html +++ b/dev/noisycircuits/index.html @@ -1,2 +1,2 @@ -Simulation of Noisy Circuits · QuantumClifford.jl
GitHub

Simulation of Noisy Clifford Circuits

Unstable

This is unfinished experimental functionality that will change significantly.

We have experimental support for simulation of noisy Clifford circuits which can be imported with using QuantumClifford.Experimental.NoisyCircuits.

Both Monte Carlo and Perturbative Expansion approaches are supported. When performing a perturbative expansion in the noise parameter, the expansion can optionally be performed symbolically, to arbitrary high orders.

Multiple notebooks with examples are also available. For instance, see this tutorial on entanglement purification for many examples.

+Simulation of Noisy Circuits · QuantumClifford.jl
GitHub

Simulation of Noisy Clifford Circuits

Unstable

This is unfinished experimental functionality that will change significantly.

We have experimental support for simulation of noisy Clifford circuits which can be imported with using QuantumClifford.Experimental.NoisyCircuits.

Both Monte Carlo and Perturbative Expansion approaches are supported. When performing a perturbative expansion in the noise parameter, the expansion can optionally be performed symbolically, to arbitrary high orders.

Multiple notebooks with examples are also available. For instance, see this tutorial on entanglement purification for many examples.

diff --git a/dev/noisycircuits_API/index.html b/dev/noisycircuits_API/index.html index d6cec2e6a..7f3ed7d86 100644 --- a/dev/noisycircuits_API/index.html +++ b/dev/noisycircuits_API/index.html @@ -1,2 +1,2 @@ -API · QuantumClifford.jl
GitHub

Full API (autogenerated)

Unstable

This is experimental functionality with an unstable API.

+API · QuantumClifford.jl
GitHub

Full API (autogenerated)

Unstable

This is experimental functionality with an unstable API.

diff --git a/dev/noisycircuits_mc/index.html b/dev/noisycircuits_mc/index.html index e90f5b9d2..adc2907bd 100644 --- a/dev/noisycircuits_mc/index.html +++ b/dev/noisycircuits_mc/index.html @@ -15,7 +15,7 @@ # then a Bell measurement # followed by checking whether the final result indeed corresponds to the correct Bell pair. circuit = [n,g1,g2,m,v]Example block output

And we can run a Monte Carlo simulation of that circuit with mctrajectories.

mctrajectories(initial_state, circuit, trajectories=500)
Dict{CircuitStatus, Float64} with 4 entries:
-  true_success:CircuitStatus(1)  => 487.0
   false_success:CircuitStatus(2) => 9.0
+  true_success:CircuitStatus(1)  => 487.0
   continue:CircuitStatus(0)      => 0.0
-  failure:CircuitStatus(3)       => 4.0

For more examples, see the notebook comparing the Monte Carlo and Perturbative method or this tutorial on entanglement purification for many examples.

Interface for custom operations

If you want to create a custom gate type (e.g. calling it Operation), you need to definite the following methods.

applywstatus!(s::T, g::Operation)::Tuple{T,Symbol} where T is a tableaux type like Stabilizer or a Register. The Symbol is the status of the operation. Predefined statuses are kept in the registered_statuses list, but you can add more. Be sure to expand this list if you want the trajectory simulators using your custom statuses to output all trajectories.

There is also applynoise! which is a convenient way to create a noise model that can then be plugged into the NoisyGate struct, letting you reuse the predefined perfect gates and measurements. However, you can also just make up your own noise operator simply by implementing applywstatus! for it.

You can also consult the list of implemented operators.

+ failure:CircuitStatus(3) => 4.0

For more examples, see the notebook comparing the Monte Carlo and Perturbative method or this tutorial on entanglement purification for many examples.

Interface for custom operations

If you want to create a custom gate type (e.g. calling it Operation), you need to definite the following methods.

applywstatus!(s::T, g::Operation)::Tuple{T,Symbol} where T is a tableaux type like Stabilizer or a Register. The Symbol is the status of the operation. Predefined statuses are kept in the registered_statuses list, but you can add more. Be sure to expand this list if you want the trajectory simulators using your custom statuses to output all trajectories.

There is also applynoise! which is a convenient way to create a noise model that can then be plugged into the NoisyGate struct, letting you reuse the predefined perfect gates and measurements. However, you can also just make up your own noise operator simply by implementing applywstatus! for it.

You can also consult the list of implemented operators.

diff --git a/dev/noisycircuits_ops/index.html b/dev/noisycircuits_ops/index.html index 43cd8a2bf..3fd3e3ee0 100644 --- a/dev/noisycircuits_ops/index.html +++ b/dev/noisycircuits_ops/index.html @@ -10,4 +10,4 @@ gate3 = SparseGate(tSWAP, [1,3]) cg = ConditionalGate(gate1, gate2, 2) dg = DecisionGate([gate1,gate2,gate3], bit_register->1) # it will always perform gate1 -[sMX(4,1), sMZ(5,2), cg, dg]Example block output

TODO: Split ConditionalGate into quantum conditional and classical conditional

+[sMX(4,1), sMZ(5,2), cg, dg]Example block output

TODO: Split ConditionalGate into quantum conditional and classical conditional

diff --git a/dev/noisycircuits_perturb/index.html b/dev/noisycircuits_perturb/index.html index fd30d5d40..226411e7a 100644 --- a/dev/noisycircuits_perturb/index.html +++ b/dev/noisycircuits_perturb/index.html @@ -18,6 +18,6 @@ circuit = [n,g1,g2,m,v] petrajectories(initial_state, circuit)
Dict{CircuitStatus, Float64} with 3 entries:
-  true_success:CircuitStatus(1)  => 0.967065
   false_success:CircuitStatus(2) => 0.019406
-  failure:CircuitStatus(3)       => 0.0129373

For more examples, see the notebook comparing the Monte Carlo and Perturbative method or this tutorial on entanglement purification.

Symbolic expansions

The perturbative expansion method works with symbolic variables as well. One can use any of the symbolic libraries available in Julia and simply plug symbolic parameters in lieu of numeric parameters. A detailed example is available as a Jupyter notebook.

Interface for custom operations

If you want to create a custom gate type (e.g. calling it Operation), you need to definite the following methods.

applyop_branches!(s::T, g::Operation; max_order=1)::Vector{Tuple{T,Symbol,Real,Int}} where T is a tableaux type like Stabilizer or a Register. The Symbol is the status of the operation, the Real is the probability for that branch, and the Int is the order of that branch.

There is also applynoise_branches! which is convenient for use in NoisyGate, but you can also just make up your own noise operator simply by implementing applyop_branches! for it.

You can also consult the list of implemented operators.

+ true_success:CircuitStatus(1) => 0.967065 + failure:CircuitStatus(3) => 0.0129373

For more examples, see the notebook comparing the Monte Carlo and Perturbative method or this tutorial on entanglement purification.

Symbolic expansions

The perturbative expansion method works with symbolic variables as well. One can use any of the symbolic libraries available in Julia and simply plug symbolic parameters in lieu of numeric parameters. A detailed example is available as a Jupyter notebook.

Interface for custom operations

If you want to create a custom gate type (e.g. calling it Operation), you need to definite the following methods.

applyop_branches!(s::T, g::Operation; max_order=1)::Vector{Tuple{T,Symbol,Real,Int}} where T is a tableaux type like Stabilizer or a Register. The Symbol is the status of the operation, the Real is the probability for that branch, and the Int is the order of that branch.

There is also applynoise_branches! which is convenient for use in NoisyGate, but you can also just make up your own noise operator simply by implementing applyop_branches! for it.

You can also consult the list of implemented operators.

diff --git a/dev/objects.inv b/dev/objects.inv index 8bc91f2dc3af98d6be0954f4486c1b820edfe576..0255ce1e97b7342e3d11060b877e70e14456157f 100644 GIT binary patch delta 12 TcmbPdJkNN7H>24`pCCy99ijvs delta 12 TcmbPdJkNN7H>2rBpCCy99i0Rm diff --git a/dev/plotting/a44cea28.svg b/dev/plotting/25819685.svg similarity index 98% rename from dev/plotting/a44cea28.svg rename to dev/plotting/25819685.svg index 91085c78b..20409825f 100644 --- a/dev/plotting/a44cea28.svg +++ b/dev/plotting/25819685.svg @@ -1,23 +1,23 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + Visualizations · QuantumClifford.jl
GitHub

Visualizations

Stabilizers have a plot recipe that can be used with Plots.jl or Makie.jl. It simply displays the corresponding parity check matrix (extracted with stab_to_gf2) as a bitmap image. Circuits can be visualized with Quantikz.jl.

Importing the aforementioned packages together with QuantumClifford is necessary to enable the plotting functionality (implemented as package extensions).

Plots.jl

In Plots.jl we have a simple recipe plot(s::Stabilizer; xzcomponents=...) where xzcomponents=:split plots the tableau heatmap in a wide form, X bits on the left, Z bits on the right; or xzcomponents=:together plots them overlapping, with different colors for I, X, Z, and Y.

using QuantumClifford, Plots
-plot(random_stabilizer(20,30), xzcomponents=:split)
Example block output
using QuantumClifford, Plots
-plot(canonicalize!(random_stabilizer(20,30)))
Example block output
using QuantumClifford, Plots
-plot(canonicalize_gott!(random_stabilizer(30))[1], xzcomponents=:split)
Example block output
using QuantumClifford, Plots
-plot(canonicalize_gott!(random_stabilizer(30))[1]; xzcomponents=:together)
Example block output
using QuantumClifford, Plots
-plot(canonicalize_rref!(random_stabilizer(20,30),1:30)[1]; xzcomponents=:together)
Example block output

Makie.jl

Makie's heatmap can be directly called on Stabilizer.

using QuantumClifford, CairoMakie
+plot(random_stabilizer(20,30), xzcomponents=:split)
Example block output
using QuantumClifford, Plots
+plot(canonicalize!(random_stabilizer(20,30)))
Example block output
using QuantumClifford, Plots
+plot(canonicalize_gott!(random_stabilizer(30))[1], xzcomponents=:split)
Example block output
using QuantumClifford, Plots
+plot(canonicalize_gott!(random_stabilizer(30))[1]; xzcomponents=:together)
Example block output
using QuantumClifford, Plots
+plot(canonicalize_rref!(random_stabilizer(20,30),1:30)[1]; xzcomponents=:together)
Example block output

Makie.jl

Makie's heatmap can be directly called on Stabilizer.

using QuantumClifford, CairoMakie
 s = S"IIXZ
       ZZIZ
       YYIZ
@@ -47,4 +47,4 @@
 f=Figure()
 stabilizerplot_axis(f[1,1],random_stabilizer(100))
 f
Example block output

Quantikz.jl

With the Quantikz library you can visualize gates or sequences of gates.

using QuantumClifford, Quantikz
-circuit = [sCNOT(1,2), SparseGate(random_clifford(4), [1,4,5,6]), sMZ(4)]
Example block output
+circuit = [sCNOT(1,2), SparseGate(random_clifford(4), [1,4,5,6]), sMZ(4)]Example block output diff --git a/dev/references/index.html b/dev/references/index.html index a715e7039..fe1b277bf 100644 --- a/dev/references/index.html +++ b/dev/references/index.html @@ -1,2 +1,2 @@ -Suggested Readings & References · QuantumClifford.jl
GitHub

Suggested reading

For the basis of the tableaux methods first read (Gottesman, 1998) followed by the more efficient approach described in (Aaronson and Gottesman, 2004).

The tableaux can be canonicalized (i.e. Gaussian elimination can be performed on them) in a number of different ways, and considering the different approaches provides useful insight. The following methods are implemented in this library:

For the use of these methods in error correction and the subtle overlap between the two fields consider these resources. They are also useful in defining some of the specific constraints in commutation between rows in the tableaux:

These publications describe the uniform sampling of random stabilizer states:

For circuit construction routines (for stabilizer measurements for a given code):

For quantum code construction routines:

For classical code construction routines:

References

  • Aaronson, S. and Gottesman, D. (2004). Improved simulation of stabilizer circuits. Physical Review A 70, 052328.
  • Abbe, E.; Shpilka, A. and Ye, M. (2020). Reed–Muller codes: Theory and algorithms. IEEE Transactions on Information Theory 67, 3251–3277.
  • Anderson, J. T.; Duclos-Cianci, G. and Poulin, D. (2014). Fault-tolerant conversion between the steane and reed-muller quantum codes. Physical review letters 113, 080501.
  • Audenaert, K. M. and Plenio, M. B. (2005). Entanglement on mixed stabilizer states: normal forms and reduction procedures. New Journal of Physics 7, 170.
  • Bhatia, A. S. and Kumar, A. (2018). McEliece cryptosystem based on extended Golay code, arXiv preprint arXiv:1811.06246.
  • Bose, R. C. and Ray-Chaudhuri, D. K. (1960). Further results on error correcting binary group codes. Information and Control 3, 279–290.
  • Bose, R. C. and Ray-Chaudhuri, D. K. (1960). On a class of error correcting binary group codes. Information and control 3, 68–79.
  • Bravyi, S.; Cross, A. W.; Gambetta, J. M.; Maslov, D.; Rall, P. and Yoder, T. J. (2024). High-threshold and low-overhead fault-tolerant quantum memory. Nature 627, 778–782.
  • Bravyi, S. and Maslov, D. (2021). Hadamard-free circuits expose the structure of the Clifford group. IEEE Transactions on Information Theory 67, 4546–4563.
  • Brown, W. and Fawzi, O. (Jul 2013). Short Random Circuits Define Good Quantum Error Correcting Codes. In: 2013 IEEE International Symposium on Information Theory; pp. 346–350.
  • Calderbank, A. R.; Rains, E. M.; Shor, P. and Sloane, N. J. (1998). Quantum error correction via codes over GF (4). IEEE Transactions on Information Theory 44, 1369–1387.
  • Campbell, E. T.; Anwar, H. and Browne, D. E. (2012). Magic-state distillation in all prime dimensions using quantum reed-muller codes. Physical Review X 2, 041021.
  • Chao, R. and Reichardt, B. W. (2017). Quantum Error Correction with Only Two Extra Qubits. Physical review letters 121 5, 050502.
  • Cleve, R. and Gottesman, D. (1997). Efficient computations of encodings for quantum error correction. Physical Review A 56, 76.
  • Djordjevic, I. B. (2021). Quantum information processing, quantum computing, and quantum error correction: an engineering approach (Academic Press).
  • Fowler, A. G.; Mariantoni, M.; Martinis, J. M. and Cleland, A. N. (2012). Surface codes: Towards practical large-scale quantum computation. Physical Review A 86, 032324.
  • Garcia, H. J.; Markov, I. L. and Cross, A. W. (2012). Efficient inner-product algorithm for stabilizer states, arXiv preprint arXiv:1210.6646.
  • Golay, M. J. (1949). Notes on digital coding. Proc. IEEE 37, 657.
  • Goodenough, K.; Sajjad, A.; Kaur, E.; Guha, S. and Towsley, D. (2024). Bipartite entanglement of noisy stabilizer states through the lens of stabilizer codes, arXiv:2406.02427 [quant-ph].
  • Gottesman, D. (1996). Class of quantum error-correcting codes saturating the quantum Hamming bound. Physical Review A 54, 1862.
  • Gottesman, D. (1997). Stabilizer codes and quantum error correction. Ph.D. Thesis, California Institute of Technology.
  • Gottesman, D. (1998). The Heisenberg representation of quantum computers. In: International Conference on Group Theoretic Methods in Physics (Citeseer).
  • Grassl, M. (2002). Algorithmic aspects of quantum error-correcting codes. Mathematics of Quantum Computation, 223–252.
  • Grassl, M. (2011). Variations on encoding circuits for stabilizer quantum codes. In: International Conference on Coding and Cryptology (Springer); pp. 142–158.
  • Gullans, M. J.; Krastanov, S.; Huse, D. A.; Jiang, L. and Flammia, S. T. (2021). Quantum Coding with Low-Depth Random Circuits. Physical Review X 11, 031066.
  • Haah, J. (2011). Local stabilizer codes in three dimensions without string logical operators. Physical Review A?Atomic, Molecular, and Optical Physics 83, 042330.
  • Hocquenghem, A. (1959). Codes correcteurs d'erreurs. Chiffers 2, 147–156.
  • Huffman, W. C. and Pless, V. (2010). Fundamentals of error-correcting codes (Cambridge university press).
  • Knill, E. and Laflamme, R. (1996). Concatenated quantum codes, arXiv preprint quant-ph/9608012.
  • Koenig, R. and Smolin, J. A. (2014). How to efficiently select an arbitrary Clifford group element. Journal of Mathematical Physics 55, 122202.
  • Krastanov, S.; de la Cerda, A. S. and Narang, P. (2020). Heterogeneous Multipartite Entanglement Purification for Size-Constrained Quantum Devices, arXiv preprint arXiv:2011.11640.
  • Li, Y.; Chen, X. and Fisher, M. P. (2019). Measurement-driven entanglement transition in hybrid quantum circuits. Physical Review B 100, 134306.
  • Lin, H.-K. and Pryadko, L. P. (2024). Quantum two-block group algebra codes. Physical Review A 109, 022407.
  • Lin, S. and Costello, D. (2024). Error Control Coding (Pearson).
  • MacKay, D. J.; Mitchison, G. and McFadden, P. L. (2004). Sparse-graph codes for quantum error correction. IEEE Transactions on Information Theory 50, 2315–2330.
  • Muller, D. E. (1954). Application of Boolean algebra to switching circuit design and to error detection. Transactions of the IRE professional group on electronic computers, 6–12.
  • Nahum, A.; Ruhman, J.; Vijay, S. and Haah, J. (2017). Quantum Entanglement Growth under Random Unitary Dynamics. Physical Review X 7, 031016.
  • Panteleev, P. and Kalachev, G. (2021). Degenerate Quantum LDPC Codes With Good Finite Length Performance. Quantum 5, 585, arXiv:1904.02703 [quant-ph].
  • Panteleev, P. and Kalachev, G. (Jun 2022). Asymptotically Good Quantum and Locally Testable Classical LDPC Codes. In: Proceedings of the 54th Annual ACM SIGACT Symposium on Theory of Computing (ACM, Rome Italy); pp. 375–388.
  • Raaphorst, S. (2003). Reed-muller codes. Carleton University, May 9.
  • Raveendran, N.; Rengaswamy, N.; Rozpędek, F.; Raina, A.; Jiang, L. and Vasić, B. (2022). Finite Rate QLDPC-GKP Coding Scheme That Surpasses the CSS Hamming Bound. Quantum 6, 767.
  • Reed, I. S. (1954). A class of multiple-error-correcting codes and the decoding scheme. IEEE Transactions on Information Theory 4, 38–49.
  • Roffe, J.; Cohen, L. Z.; Quintavalle, A. O.; Chandra, D. and Campbell, E. T. (2023). Bias-Tailored Quantum LDPC Codes. Quantum 7, 1005.
  • Steane, A. M. (1999). Quantum reed-muller codes. IEEE Transactions on Information Theory 45, 1701–1703.
  • Steane, A. M. (2007). A tutorial on quantum error correction. In: PROCEEDINGS-INTERNATIONAL SCHOOL OF PHYSICS ENRICO FERMI, Vol. 162 (IOS Press; Ohmsha; 1999); p. 1.
  • Van Den Berg, E. (2021). A simple method for sampling random Clifford operators. In: 2021 IEEE International Conference on Quantum Computing and Engineering (QCE) (IEEE); pp. 54–59.
  • Voss, L.; Xian, S. J.; Haug, T. and Bharti, K. (2024). Multivariate Bicycle Codes, arXiv:2406.19151 [quant-ph].
  • Wang, M. and Mueller, F. (2024). Coprime Bivariate Bicycle Codes and their Properties, arXiv preprint arXiv:2408.10001.
  • Wilde, M. M. (2009). Logical operators of quantum codes. Physical Review A 79, 062322.
  • Yu, S.; Bierbrauer, J.; Dong, Y.; Chen, Q. and Oh, C. H. (2013). All the Stabilizer Codes of Distance 3. IEEE Transactions on Information Theory 59, 5179–5185.
+Suggested Readings & References · QuantumClifford.jl
GitHub

Suggested reading

For the basis of the tableaux methods first read (Gottesman, 1998) followed by the more efficient approach described in (Aaronson and Gottesman, 2004).

The tableaux can be canonicalized (i.e. Gaussian elimination can be performed on them) in a number of different ways, and considering the different approaches provides useful insight. The following methods are implemented in this library:

For the use of these methods in error correction and the subtle overlap between the two fields consider these resources. They are also useful in defining some of the specific constraints in commutation between rows in the tableaux:

These publications describe the uniform sampling of random stabilizer states:

For circuit construction routines (for stabilizer measurements for a given code):

For quantum code construction routines:

For classical code construction routines:

References

  • Aaronson, S. and Gottesman, D. (2004). Improved simulation of stabilizer circuits. Physical Review A 70, 052328.
  • Abbe, E.; Shpilka, A. and Ye, M. (2020). Reed–Muller codes: Theory and algorithms. IEEE Transactions on Information Theory 67, 3251–3277.
  • Anderson, J. T.; Duclos-Cianci, G. and Poulin, D. (2014). Fault-tolerant conversion between the steane and reed-muller quantum codes. Physical review letters 113, 080501.
  • Audenaert, K. M. and Plenio, M. B. (2005). Entanglement on mixed stabilizer states: normal forms and reduction procedures. New Journal of Physics 7, 170.
  • Bhatia, A. S. and Kumar, A. (2018). McEliece cryptosystem based on extended Golay code, arXiv preprint arXiv:1811.06246.
  • Bose, R. C. and Ray-Chaudhuri, D. K. (1960). Further results on error correcting binary group codes. Information and Control 3, 279–290.
  • Bose, R. C. and Ray-Chaudhuri, D. K. (1960). On a class of error correcting binary group codes. Information and control 3, 68–79.
  • Bravyi, S.; Cross, A. W.; Gambetta, J. M.; Maslov, D.; Rall, P. and Yoder, T. J. (2024). High-threshold and low-overhead fault-tolerant quantum memory. Nature 627, 778–782.
  • Bravyi, S. and Maslov, D. (2021). Hadamard-free circuits expose the structure of the Clifford group. IEEE Transactions on Information Theory 67, 4546–4563.
  • Brown, W. and Fawzi, O. (Jul 2013). Short Random Circuits Define Good Quantum Error Correcting Codes. In: 2013 IEEE International Symposium on Information Theory; pp. 346–350.
  • Calderbank, A. R.; Rains, E. M.; Shor, P. and Sloane, N. J. (1998). Quantum error correction via codes over GF (4). IEEE Transactions on Information Theory 44, 1369–1387.
  • Campbell, E. T.; Anwar, H. and Browne, D. E. (2012). Magic-state distillation in all prime dimensions using quantum reed-muller codes. Physical Review X 2, 041021.
  • Chao, R. and Reichardt, B. W. (2017). Quantum Error Correction with Only Two Extra Qubits. Physical review letters 121 5, 050502.
  • Cleve, R. and Gottesman, D. (1997). Efficient computations of encodings for quantum error correction. Physical Review A 56, 76.
  • Djordjevic, I. B. (2021). Quantum information processing, quantum computing, and quantum error correction: an engineering approach (Academic Press).
  • Fowler, A. G.; Mariantoni, M.; Martinis, J. M. and Cleland, A. N. (2012). Surface codes: Towards practical large-scale quantum computation. Physical Review A 86, 032324.
  • Garcia, H. J.; Markov, I. L. and Cross, A. W. (2012). Efficient inner-product algorithm for stabilizer states, arXiv preprint arXiv:1210.6646.
  • Golay, M. J. (1949). Notes on digital coding. Proc. IEEE 37, 657.
  • Goodenough, K.; Sajjad, A.; Kaur, E.; Guha, S. and Towsley, D. (2024). Bipartite entanglement of noisy stabilizer states through the lens of stabilizer codes, arXiv:2406.02427 [quant-ph].
  • Gottesman, D. (1996). Class of quantum error-correcting codes saturating the quantum Hamming bound. Physical Review A 54, 1862.
  • Gottesman, D. (1997). Stabilizer codes and quantum error correction. Ph.D. Thesis, California Institute of Technology.
  • Gottesman, D. (1998). The Heisenberg representation of quantum computers. In: International Conference on Group Theoretic Methods in Physics (Citeseer).
  • Grassl, M. (2002). Algorithmic aspects of quantum error-correcting codes. Mathematics of Quantum Computation, 223–252.
  • Grassl, M. (2011). Variations on encoding circuits for stabilizer quantum codes. In: International Conference on Coding and Cryptology (Springer); pp. 142–158.
  • Gullans, M. J.; Krastanov, S.; Huse, D. A.; Jiang, L. and Flammia, S. T. (2021). Quantum Coding with Low-Depth Random Circuits. Physical Review X 11, 031066.
  • Haah, J. (2011). Local stabilizer codes in three dimensions without string logical operators. Physical Review A?Atomic, Molecular, and Optical Physics 83, 042330.
  • Hocquenghem, A. (1959). Codes correcteurs d'erreurs. Chiffers 2, 147–156.
  • Huffman, W. C. and Pless, V. (2010). Fundamentals of error-correcting codes (Cambridge university press).
  • Knill, E. and Laflamme, R. (1996). Concatenated quantum codes, arXiv preprint quant-ph/9608012.
  • Koenig, R. and Smolin, J. A. (2014). How to efficiently select an arbitrary Clifford group element. Journal of Mathematical Physics 55, 122202.
  • Krastanov, S.; de la Cerda, A. S. and Narang, P. (2020). Heterogeneous Multipartite Entanglement Purification for Size-Constrained Quantum Devices, arXiv preprint arXiv:2011.11640.
  • Li, Y.; Chen, X. and Fisher, M. P. (2019). Measurement-driven entanglement transition in hybrid quantum circuits. Physical Review B 100, 134306.
  • Lin, H.-K. and Pryadko, L. P. (2024). Quantum two-block group algebra codes. Physical Review A 109, 022407.
  • Lin, S. and Costello, D. (2024). Error Control Coding (Pearson).
  • MacKay, D. J.; Mitchison, G. and McFadden, P. L. (2004). Sparse-graph codes for quantum error correction. IEEE Transactions on Information Theory 50, 2315–2330.
  • Muller, D. E. (1954). Application of Boolean algebra to switching circuit design and to error detection. Transactions of the IRE professional group on electronic computers, 6–12.
  • Nahum, A.; Ruhman, J.; Vijay, S. and Haah, J. (2017). Quantum Entanglement Growth under Random Unitary Dynamics. Physical Review X 7, 031016.
  • Panteleev, P. and Kalachev, G. (2021). Degenerate Quantum LDPC Codes With Good Finite Length Performance. Quantum 5, 585, arXiv:1904.02703 [quant-ph].
  • Panteleev, P. and Kalachev, G. (Jun 2022). Asymptotically Good Quantum and Locally Testable Classical LDPC Codes. In: Proceedings of the 54th Annual ACM SIGACT Symposium on Theory of Computing (ACM, Rome Italy); pp. 375–388.
  • Raaphorst, S. (2003). Reed-muller codes. Carleton University, May 9.
  • Raveendran, N.; Rengaswamy, N.; Rozpędek, F.; Raina, A.; Jiang, L. and Vasić, B. (2022). Finite Rate QLDPC-GKP Coding Scheme That Surpasses the CSS Hamming Bound. Quantum 6, 767.
  • Reed, I. S. (1954). A class of multiple-error-correcting codes and the decoding scheme. IEEE Transactions on Information Theory 4, 38–49.
  • Roffe, J.; Cohen, L. Z.; Quintavalle, A. O.; Chandra, D. and Campbell, E. T. (2023). Bias-Tailored Quantum LDPC Codes. Quantum 7, 1005.
  • Steane, A. M. (1999). Quantum reed-muller codes. IEEE Transactions on Information Theory 45, 1701–1703.
  • Steane, A. M. (2007). A tutorial on quantum error correction. In: PROCEEDINGS-INTERNATIONAL SCHOOL OF PHYSICS ENRICO FERMI, Vol. 162 (IOS Press; Ohmsha; 1999); p. 1.
  • Van Den Berg, E. (2021). A simple method for sampling random Clifford operators. In: 2021 IEEE International Conference on Quantum Computing and Engineering (QCE) (IEEE); pp. 54–59.
  • Voss, L.; Xian, S. J.; Haug, T. and Bharti, K. (2024). Multivariate Bicycle Codes, arXiv:2406.19151 [quant-ph].
  • Wang, M. and Mueller, F. (2024). Coprime Bivariate Bicycle Codes and their Properties, arXiv preprint arXiv:2408.10001.
  • Wilde, M. M. (2009). Logical operators of quantum codes. Physical Review A 79, 062322.
  • Yu, S.; Bierbrauer, J.; Dong, Y.; Chen, Q. and Oh, C. H. (2013). All the Stabilizer Codes of Distance 3. IEEE Transactions on Information Theory 59, 5179–5185.
diff --git a/dev/stab-algebra-manual/index.html b/dev/stab-algebra-manual/index.html index 41ccd5a39..3fe0ea6c8 100644 --- a/dev/stab-algebra-manual/index.html +++ b/dev/stab-algebra-manual/index.html @@ -314,4 +314,4 @@ 𝒮𝓉𝒶𝒷━ + _ZX - _Z_ -- Z_X

Mixed States

Both the Stabilizer and Destabilizer structures have more general forms that enable work with mixed stabilizer states. They are the MixedStabilizer and MixedDestabilizer structures, described in Mixed States. More information that can be seen in the data structures page, which expands upon the algorithms available for each structure.

Random States and Circuits

random_clifford, random_stabilizer, and enumerate_cliffords can be used for the generation of random states.

+- Z_X

Mixed States

Both the Stabilizer and Destabilizer structures have more general forms that enable work with mixed stabilizer states. They are the MixedStabilizer and MixedDestabilizer structures, described in Mixed States. More information that can be seen in the data structures page, which expands upon the algorithms available for each structure.

Random States and Circuits

random_clifford, random_stabilizer, and enumerate_cliffords can be used for the generation of random states.

diff --git a/dev/tutandpub/index.html b/dev/tutandpub/index.html index 887978906..26c1a7042 100644 --- a/dev/tutandpub/index.html +++ b/dev/tutandpub/index.html @@ -1,2 +1,2 @@ -Tutorials and Publications · QuantumClifford.jl
GitHub

Tutorials and Publications

This list has a number of notebooks with tutorials, examples, and reproduction of published results (some of these results originally obtained with this very library).

On the topic of explicit use of the Tableaux formalism for Stabilizer states

On the Monte Carlo and Perturbative Expansions for Noisy Clifford circuits

+Tutorials and Publications · QuantumClifford.jl
GitHub

Tutorials and Publications

This list has a number of notebooks with tutorials, examples, and reproduction of published results (some of these results originally obtained with this very library).

On the topic of explicit use of the Tableaux formalism for Stabilizer states

On the Monte Carlo and Perturbative Expansions for Noisy Clifford circuits