Full ECC API (autogenerated)

QuantumClifford.ECC.CircuitCode — Type

CircuitCode is defined by a given encoding circuit circ.

n: qubit number
circ: the encoding circuit
encode_qubits: the qubits to be encoded

QuantumClifford.ECC.CommutationCheckECCSetup — Type

Configuration for ECC evaluator that does not simulate any ECC circuits, rather it simply checks the commutation of the parity check and the Pauli error.

This is much faster than any other simulation method, but it is incapable of noisy-circuit simulations and thus useless for fault-tolerance studies.

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.DistanceMIPAlgorithm — Type

struct DistanceMIPAlgorithm <: QECCore.AbstractDistanceAlg

A Mixed Integer Programming (MIP) method for computing the code distance of CSS stabilizer codes by finding the minimum-weight non-trivial logical PauliOperator (either X-type or Z-type). Used with distance to select MIP as the method of finding the distance of a code.

Note

Requires a JuMP-compatible MIP solver (e.g., HiGHS, SCIP).
For some stabilizer CSS codes, the X-distance and Z-distance are equal.

logical_qubit: index of the logical qubit to compute code distance for (nothing means compute for all logical qubits)
logical_operator_type: type of logical operator to consider (:X or :Z, defaults to :minXZ).
solver: JuMP-compatible MIP solver (e.g., HiGHS, SCIP)
opt_summary: when true (default=false), prints the MIP solver's solution summary
time_limit: time limit (in seconds) for the MIP solver's execution (default=60.0)

source

QuantumClifford.ECC.NaiveSyndromeECCSetup — Type

Configuration for ECC evaluator that runs the simplest syndrome measurement circuit.

The circuit is being simulated (as opposed to doing only a quick commutation check). This circuit would give poor performance if there is non-zero gate noise.

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)

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

QECCore.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

QECCore.parity_matrix_x — Method

Parity check boolean matrix of a code (only the X entries in the tableau, i.e. the checks for Z errors).

Only CSS codes have this method.

Implemented in an extension requiring `Hecke.jl`

QuantumCliffordHeckeExt.ExtendedGeneralizedBicycleCode — Type

struct ExtendedGeneralizedBicycleCode <: QECCore.AbstractCSSCode

The extended generalized bicycle code is a family of quantum LDPC codes generated through algebraic extension of a base GeneralizedBicycleCode. Starting with initial generating polynomials $a(x), b(x) \in \mathbb{F}_2^{\langle\ell\rangle}$, the extended GB codes are constructed by polynomial multiplication, where for each extension step $m$, an extension polynomial

\[\begin{aligned} p^{(m)}(x) \in \mathbb{F}_2^{\langle\kappa_m\ell\rangle} \end{aligned}\]

is selected to produce extended polynomials:

\[\begin{aligned} a^{(m)}(x) &= p^{(m)}(x)a(x), \\ b^{(m)}(x) &= p^{(m)}(x)b(x) \end{aligned}\]

These extended polynomials are then used to form $\kappa_m\ell \times \kappa_m\ell$ circulant matrices $A_m$ and $B_m$, which are combined into a parity-check matrix $H_m$ with block structure:

\[\begin{aligned} H_m = \begin{pmatrix} A_m \mid B_m & 0 \\ 0 & B_m^\top \mid A_m^\top \end{pmatrix} \end{aligned}\]

while maintaining logical dimension:

\[\begin{aligned} k_m = 2\deg\left(\gcd\left(a^{(m)}, b^{(m)}, x^{\kappa_m\ell}-1\right)\right) \end{aligned}\]

that are always bounded below by the base code dimension k.

Example

julia> import Hecke: polynomial_ring, GF, one, gen; using QuantumClifford.ECC;

julia> R, x = polynomial_ring(GF(2), "x");

julia> l = 5;

julia> a = 1 + x^4;

julia> b = 1 + x + x^2 + x^4;

julia> c = GeneralizedBicycleCode(a, b, l);

julia> import HiGHS;

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(10, 2, 3)

julia> m, p = 4, one(R);

julia> new_code = ExtendedGeneralizedBicycleCode(c, m, p);

julia> code_n(new_code), code_k(new_code), distance(new_code, DistanceMIPAlgorithm(solver=HiGHS))
(40, 2, 5)

julia> m, p = 4, 1 + x;

julia> new_code = ExtendedGeneralizedBicycleCode(c, m, p);

julia> code_n(new_code), code_k(new_code), distance(new_code, DistanceMIPAlgorithm(solver=HiGHS))
(40, 4, 5)

Note

(Koukoulekidis et al., 2024) establishes that ℓ = 5 is the minimal lift size required to achieve quantum error-correcting codes with a minimum distance of d ≥ 3.

Fields

base_code::QECCore.AbstractCSSCode: The base generalized bicycle code to extend.
m::Int64: The extension index (m ≥ 1)
p::Nemo.FqPolyRingElem: The extension polynomial ∈ 𝔽₂[((m-1)ℓ +1)].

source

QuantumCliffordHeckeExt.GeneralizedBicycleCode — Type

struct GeneralizedBicycleCode <: QECCore.AbstractCSSCode

Generalized bicycle codes ((Koukoulekidis et al., 2024))

A generalized bicycle quantum LDPC code constructed from two polynomials in $\mathbb{F}_2[x]/(x^l - 1)$.

Here is an example of a [[10, 2, 3]] GB code from the Appendix B of (Koukoulekidis et al., 2024) with lift size of 5 build out of two polymonials in $\mathbb{F}_2[x]/(x^l - 1)$.

julia> import Hecke: polynomial_ring, GF; using QuantumClifford.ECC;

julia> R, x = polynomial_ring(GF(2), "x");

julia> l = 5;

julia> a = 1 + x^4;

julia> b = 1 + x + x^2 + x^4;

julia> c = GeneralizedBicycleCode(a, b, l);

julia> import HiGHS;

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(10, 2, 3)

Here is an example of a [[12, 2, 3]] GB code from the Appendix B of (Koukoulekidis et al., 2024) with lift size of 6 build out of two polymonials in $\mathbb{F}_2[x]/(x^l - 1)$.

julia> import Hecke: polynomial_ring, GF; using QuantumClifford.ECC;

julia> R, x = polynomial_ring(GF(2), "x");

julia> l = 6;

julia> a = 1 + x + x^2 + x^5;

julia> b = 1 + x + x^3 + x^5;

julia> c = GeneralizedBicycleCode(a, b, l);

julia> import HiGHS;

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(12, 2, 3)

Implemented in an extension requiring `Oscar.jl`

QuantumCliffordOscarExt.DDimensionalSurfaceCode — Type

struct DDimensionalSurfaceCode <: QuantumCliffordOscarExt.DDimensionalCode

Constructs the D-dimensional surface code using chain complexes and $\mathbb{F}_2$-homology.

Homological Algebra Foundations of Quantum Error Correction

The theory of chain complexes over $\mathbb{F}_2$ provides a unified framework for understanding error-correcting codes, where classical $[n, k, d]$ codes correspond to 2-term complexes and quantum CSS codes arise naturally as 3-term complexes satisfying the commutativity condition $H_Z^T H_X = 0$. The homological framework reveals that:

Quantum CSS codes arise from chain complexes where boundary operators correspond to parity checks.
Logical operators correspond to homology classes.
Higher-dimensional codes can be constructed through products of complexes.

Chain Complex Structure

A chain complex $C$ of length $n$ is a sequence of finite-dimensional vector spaces $C_j$ over $\mathbb{F}_2$ connected by boundary operators that are linear transformations $\partial_j \colon C_j \to C_{j-1}$:

\[\begin{aligned} C : \{0\} \longrightarrow C_n \xrightarrow{\partial_n} C_{n-1} \xrightarrow{\partial_{n-1}} \cdots \xrightarrow{\partial_2} C_1 \xrightarrow{\partial_1} C_0 \longrightarrow \{0\} \end{aligned}\]

with boundary operators satisfying $\partial_i \circ \partial_{i+1} = 0$ (equivalently, $\text{im}\, \partial_{j+1} \subseteq \ker \partial_j)$.We define:

i-chains: Elements of $C_i$
i-cycles: $Z_i(C) := \ker \partial_i$
i-boundaries: $B_i(C) := \mathrm{im} \partial_{i+1}$
i-th homology: $H_i(C) := Z_i(C)/B_i(C)$

Cohomology of the Dual Complex

Given a chain complex $C$ with boundary operators $\partial_j$, its cochain complex $\widetilde{C}$ is the dual sequence with coboundary maps $\delta^i = \partial_{i+1}^T$:

\[\begin{aligned} \widetilde{C} : \{0\} \longleftarrow C_0^* \xleftarrow{\partial_1^T} C_1^* \xleftarrow{\partial_2^T} \cdots \xleftarrow{\partial_n^T} C_n^* \longleftarrow \{0\} \end{aligned}\]

where

i-cocycles: $Z^i(\widetilde{C}) := \ker \partial_{i+1}^T$
i-coboundaries: $B^i(\widetilde{C}) := \mathrm{im} \partial_i^T$
i-th cohomology: $H^i(\widetilde{C}) := Z^i(\widetilde{C})/B^i(\widetilde{C})$

Note

The cohomology group $H^i(\widetilde{C}) = H(\partial_{i+1}^T, \partial_i^T)$ has the same rank as the homology group $H_i(C)$ and corresponds to $X$-type logical operators in the CSS code $CSS(\partial_i, \partial_{i+1}^T)$, while $H_i(C)$ corresponds to $Z$-type operators.

Classical Codes via Chain Complexes and $\mathbb{F_2}$ Homology

An $[n,k,d]$ classical code corresponds to a 2-term complex:

\[\begin{aligned} \{0\} \longrightarrow C_1 \xrightarrow{\partial_1 = H} C_0 \longrightarrow \{0\} \end{aligned}\]

where

$C_1 = \mathbb{F}_2^n$ (codeword space)
$C_0 = \mathbb{F}_2^{n-k}$ (syndrome space)
$H$ is the parity check matrix

Quantum CSS Codes via Chain Complexes and $\mathbb{F_2}$ Homology

Quantum CSS codes extend this to 3-term complexes:

\[\begin{aligned} \{0\} \longrightarrow C_2 \xrightarrow{\partial_2 = H_Z^T} C_1 \xrightarrow{\partial_1 = H_X} C_0 \longrightarrow \{0\} \end{aligned}\]

where

$C_1 = \mathbb{F}_2^n$ (physical qubits)
$C_2 = \mathbb{F}_2^{m_Z}$ (Z-stabilizers)
$C_0 = \mathbb{F}_2^{m_X}$ (X-stabilizers)

with the condition $\partial_1 \partial_2 = H_Z^TH_X = 0$ ensuring that CSS orthogonality is satisfied.

For any chain complex, selecting two consecutive boundary operators defines a valid CSS code. When qubits are identified with the space $C_i$, the code parameters are:

number of physical qubits: $n = \dim C_i$
number of logical qubits: $k = \dim H_i(C) = \dim H^i(C)$
code distance: $d = \min\{\text{wt}(v) | v \in (H_i(C) \cup H^i(C))\backslash\{0\}\}$

Note

Quantum error-correcting codes, which are represented as 3-term chain complexes, can be constructed by applying the homological or hypergraph product to two 2-term chain complexes.

For a detailed explanation, see the ECC Zoo's writeup on the CSS-to-homology correspondence.

D-dimensional Surface Code ((Berthusen et al., 2024), (Zeng and Pryadko, 2019))

We provide an explicit construction of the D-dimensional surface code within the framework of chain complexes and homology over $\mathbb{F_2}$.

The quantum code is obtained by applying the homological product (or hypergraph product) to two 2-term chain complexes. Our construction relies on taking the hypergraph product of these complexes.

Double Complex

Given chain complexes C and D, we construct a double complex derived from the tensor product of two 2-term chain complexes:

\[\begin{aligned} C \boxtimes D \quad \text{with} \quad \partial_i^v = \partial_i^C \otimes I_{D_i} \quad \text{and} \quad \partial_i^h = I_{C_i} \otimes \partial_i^D \end{aligned}\]

Total Complex

The total complex is derived from a double complex by taking the direct sum of vector spaces and boundary maps that share the same dimension:

\[\begin{aligned} \text{Tot}(C \boxtimes D)_i = \bigoplus_{i=j+k} C_j \otimes D_k = E_i \end{aligned}\]

with boundary maps:

\[\begin{aligned} \partial_i^E = \bigoplus_{i=j+k} \partial_j^v \oplus \partial_k^h \end{aligned}\]

The resulting chain complex, called the tensor product of $C$ and $D$, $C ⊗ D$, enables the construction of a CSS code when selecting any three consecutive terms in its sequence.

Subfamilies

[[L² + (L − 1)², 1, L]] 2D Surface Code

The 2D surface code is constructed using the hypergraph product of two repetition codes.Thus, we obtain a new 3-term chain complex:

\[\begin{aligned} E_2 \xrightarrow{\partial_2^E} E_1 \xrightarrow{\partial_1^E} E_0 \end{aligned}\]

Examples

julia> using Oscar; using QuantumClifford; using QuantumClifford.ECC;

julia> D = 2; L = 2;

julia> c = DDimensionalSurfaceCode(D, L);

julia> code = parity_checks(c)
+ X_X_X
+ _X_XX
+ ZZ__Z
+ __ZZZ

julia> import HiGHS; import JuMP;

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(5, 1, 2)

When L = 4, we get [[25,1, 4]] 2D surface code from (Berthusen et al., 2024).

julia> using Oscar; using QuantumClifford; using QuantumClifford.ECC;

julia> D = 2; L = 4;

julia> c = DDimensionalSurfaceCode(D, L);

julia> code = parity_checks(c)
+ X___X___________X________
+ _X___X__________XX_______
+ __X___X__________XX______
+ ___X___X__________X______
+ ____X___X__________X_____
+ _____X___X_________XX____
+ ______X___X_________XX___
+ _______X___X_________X___
+ ________X___X_________X__
+ _________X___X________XX_
+ __________X___X________XX
+ ___________X___X________X
+ ZZ______________Z________
+ _ZZ______________Z_______
+ __ZZ______________Z______
+ ____ZZ__________Z__Z_____
+ _____ZZ__________Z__Z____
+ ______ZZ__________Z__Z___
+ ________ZZ_________Z__Z__
+ _________ZZ_________Z__Z_
+ __________ZZ_________Z__Z
+ ____________ZZ________Z__
+ _____________ZZ________Z_
+ ______________ZZ________Z

julia> import HiGHS; import JuMP;

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(25, 1, 4)

Chain Complex

The construction is as follows:

\[\begin{aligned} C = \left( C_1 \xrightarrow{\partial} C_0 \right) \quad \text{and} \quad D = \left( D_1 \xrightarrow{\partial^T} D_0 \right) \end{aligned}\]

where $\partial$ is the $(L-1) \times L$ parity check matrix:

\[\begin{aligned} H = \begin{pmatrix} 1 & 1 & & \\ & 1 & \ddots & \\ & & \ddots & 1 \\ & & & 1 \end{pmatrix} \end{aligned}\]

[[L³ + 2L(L − 1)², 1, min(L, L²)]] 3D Surface Code

The 3D surface code is obtained by taking the hypergraph product of a 2D surface code with a repetition code. Thus, we obtain a new 4-term chain complex:

\[\begin{aligned} F_3 \xrightarrow{\partial_3^F} F_2 \xrightarrow{\partial_2^F} F_1 \xrightarrow{\partial_1^F} F_0 \end{aligned}\]

Metachecks

Z-type metachecks: $M_Z^T = \partial_3^F$

Example

Here is an example of [[12, 1, 2]] 3D Surface code with L = 2 from (Berthusen et al., 2024).

julia> using Oscar; using QuantumClifford; using QuantumClifford.ECC;

julia> D = 3; L = 2;

julia> c = DDimensionalSurfaceCode(D, L);

julia> code = parity_checks(c)
+ XX__X_____X_
+ __XXX______X
+ _____XX__XX_
+ _______XXX_X
+ Z_Z_Z_______
+ _Z_ZZ_______
+ _____Z_Z_Z__
+ ______Z_ZZ__
+ Z____Z____Z_
+ _Z____Z___Z_
+ __Z____Z___Z
+ ___Z____Z__Z
+ ____Z____ZZZ

julia> code_n(c), code_k(c)
(12, 1)

Note

For the 3D surface code, there is an asymmetry between the Z- and X-bases (Berthusen et al., 2024). Specifically, the Z-distance ($d_Z$) is 4, whereas the X-distance ($d_X$) is 2. As a result, the code has the parameters [[12, 1, 2]].

julia> import HiGHS; import JuMP;

julia> dz = distance(c, DistanceMIPAlgorithm(solver=HiGHS, logical_operator_type=:Z))
4

julia> dx = distance(c, DistanceMIPAlgorithm(solver=HiGHS, logical_operator_type=:X))
2

[[6L⁴ − 12L³ + 10L² − 4L + 1, 1, L²]] 4D Surface Code

The 4D surface code is constructed by taking the hypergraph product of a 3D surface code with a repetition code. Thus, we obtain a new 5-term chain complex:

\[\begin{aligned} G_4 \xrightarrow{\partial_4^G} G_3 \xrightarrow{\partial_3^G} G_2 \xrightarrow{\partial_2^G} G_1 \xrightarrow{\partial_1^G} G_0 \end{aligned}\]

[[33, 1, 4]]

Here is an example of [[33, 1, 4]] 4D Surface code with L = 2 from (Berthusen et al., 2024).

julia> using Oscar; using QuantumClifford; using QuantumClifford.ECC;

julia> D = 4; L = 2;

julia> c = DDimensionalSurfaceCode(D, L);

julia> import HiGHS; import JuMP;

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(33, 1, 4)

Metachecks

Both X and Z-type metachecks available:

$M_Z^T = \partial_4^G$
$M_X = \partial_1^G$

To obtain surface codes of greater dimensionality, we alternate between C and D and then form a product with the chain complex representing the DDimensionalSurfaceCode (Berthusen et al., 2024).

Note

The procedure described above for the DDimensionalSurfaceCode can alternatively be performed using an L × L repetition code and only the chain complex C. In this case, the result would be the DDimensionalToricCode.

See also: DDimensionalSurfaceCode

Fields

D::Int64: Dimension of the Toric code (must be ≥ 2).
L::Int64: Size parameter determining the D-dimensional Toric code family, constructed via hypergraph product of L × L repetition code chain complexes.

source

QuantumCliffordOscarExt.DoubleHomologicalProductCode — Type

Constructs the Double Homological Product code from (Campbell, 2019).

4-term Chain Complex

To construct a quantum error-correcting code with metachecks, we require a length-4 chain complex. This can be built by taking the homological product of two length-2 chain complexes.

The length-4 chain complex, structured as:

\[\begin{aligned} \breve{C}_{-2} \xrightarrow{\breve{\delta}_{-2}} \breve{C}_{-1} \xrightarrow{\breve{\delta}_{-1}} \breve{C}_0 \xrightarrow{\breve{\delta}_0} \breve{C}_1 \xrightarrow{\breve{\delta}_1} \breve{C}_2 \end{aligned}\]

The homological product of two 2D chain complexes produces this length-4 complex, following the general rule:

\[\begin{aligned} \breve{C}_m = \bigoplus_{i - j = m} \tilde{C}_i \otimes \tilde{C}_j \end{aligned}\]

The boundary maps are represented as block matrices and are defined as:

\[\begin{align} \breve{\delta}_{-2} &= \begin{pmatrix} I \otimes \tilde{\delta}_0^T \\ \tilde{\delta}_{-1} \otimes I \end{pmatrix}, \\ \breve{\delta}_{-1} &= \begin{pmatrix} I \otimes \tilde{\delta}_{-1}^T & 0 \\ \tilde{\delta}_{-1} \otimes I & I \otimes \tilde{\delta}_0^T \\ 0 & \tilde{\delta}_0 \otimes I \end{pmatrix}, \\ \breve{\delta}_0 &= \begin{pmatrix} \tilde{\delta}_{-1} \otimes I & I \otimes \tilde{\delta}_{-1}^T & 0 \\ 0 & \tilde{\delta}_0 \otimes I & I \otimes \tilde{\delta}_0^T \end{pmatrix}, \\ \breve{\delta}_1 &= \begin{pmatrix} \tilde{\delta}_0 \otimes I & I \otimes \tilde{\delta}_{-1}^T \end{pmatrix} \end{align}\]

The condition $\breve{\delta}_{j+1} \breve{\delta}_j = 0$ holds for all j, which follows from the corresponding property of the $\tilde{\delta}$ matrices.

Example

Here is [[241, 1, 9]] double homological product code from Table I of (Campbell, 2019).

julia> using Oscar; using QuantumClifford; using QuantumClifford.ECC; using QECCore;

julia> δ = [1 1 0;
            0 1 1];

julia> c = DoubleHomologicalProductCode(δ);

julia> import HiGHS; import JuMP;

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(241, 1, 9)

Fields

H::AbstractMatrix: The parity-check matrix of a classical error-correcting code.

source

QuantumCliffordOscarExt.HomologicalProductCode — Type

struct HomologicalProductCode{T<:AbstractAlgebra.MatElem} <: QECCore.AbstractCSSCode

Constructs a D-dimensional CSS quantum code (D ≥ 2) from D classical parity-check matrices via iterated homological products.

Several interpretations of the homological product exist. For example, (Bravyi and Hastings, 2013) employ a simplified version known as the single-sector homological product. In contrast, the HomologicalProductCode adopts a more conventional definition, which (Bravyi and Hastings, 2013) would refer to as the multi-sector homological product.

The term "homological product codes" can broadly encompass various constructions involving the product of quantum codes ((Bravyi and Hastings, 2013), (Campbell, 2019)). However, HomologicalProductCode focuses specifically on a particular subset—namely, the product of classical codes, which can also be described as length-1 chain complexes (sometimes called high-dimensional hypergraph product codes (Zeng and Pryadko, 2019)).

Product Complex

Given $D$ chain complexes $\{\mathcal{B}^i\}_{i\in[D]}$, where $\mathcal{B}^i = \{\{B^i_{x_i}\}_{x_i}, \{\partial^i_{x_i}\}_{x_i}\}$, the $D$-dimensional product complex is defined as:

\[\begin{aligned} \mathcal{D} = \{\{D_{\vec{x}}\}_{\vec{x}=(x_1,\dots,x_D)^T \in \mathbb{Z}^D}, \{\partial^i_{\vec{x}}: D_{\vec{x}} \to D_{\vec{x}-\vec{e}_i}\}_{i\in[D],\vec{x}\in\mathbb{Z}^D}\} := \text{Prod}(\{\mathcal{B}^i\}_{i\in[D]}) \end{aligned}\]

the tensor product of these chain complexes, where:

\[\begin{aligned} D_{\vec{x}} := \bigotimes_{i=1}^D B^i_{x_i}, \\ \partial^i_{\vec{x}} := \bigotimes_{j=1}^D (\partial^j_{x_j})^{\delta_{i,j}} \end{aligned}\]

where $\delta_{i,j}$ is the Kronecker delta function and $(\partial^j_{x_j})^0$ is defined as the identity map (Xu et al., 2024).

Note

A product complex is a high-dimensional generalization of the chain complex.

Total Complex

The $\mathcal{D}$-product complex is constructed from $D$ base chain complexes with vector spaces $\{D_{\vec{x}}\}_{\vec{x}}$ and boundary maps $\{\partial^i_{\vec{x}}\}_{i\in[D],\vec{x}}$. It's total chain complex $\mathcal{T} = \{\{T_k\}_k, \{\delta_k\}_k\} := \text{Tot}(\mathcal{D})$ as follows:

\[\begin{aligned} T_k := \bigoplus_{|\vec{x}|=k} D_{\vec{x}} \end{aligned}\]

and the boundary maps:

\[\begin{aligned} \delta_k\left(\bigoplus_{|\vec{x}|=k} a_{\vec{x}}\right) = \sum_{|\vec{x}|=k} \left(\bigoplus_{|\vec{y}|=k-1} \partial_{\vec{y},\vec{x}} a_{\vec{x}}\right) \end{aligned}\]

for any $a_{\vec{x}} \in D_{\vec{x}}$, and

\[\begin{aligned} \partial_{\vec{y},\vec{x}} := \begin{cases} \partial^i_{\vec{x}} & \text{if } \vec{x} - \vec{y} = \vec{e}_i \text{ for some } i \in [D], \\ 0 & \text{otherwise.} \end{cases} \end{aligned}\]

Note

The total complex is obtained by projecting the $D$-dimensional complex along the "diagonal" direction. Once a total chain complex is derived from a product complex (with length greater than 2), a quantum code can be defined from a length-2 subcomplex (Xu et al., 2024).

(Xu et al., 2024) focuses on product complexes with length-1 base complexes $\{\mathcal{C}^i\}_{i\in[D]}}$ (classical codes). In this case, the total complex $\mathcal{T} = \text{Tot}(\text{Prod}(\{\mathcal{C}^i\}_{i\in[D]}))$ has length $D$:

\[\begin{aligned} T_D \xrightarrow{\delta_D} T_{D-1} \xrightarrow{\delta_{D-1}} \cdots \xrightarrow{\delta_1} T_0 \end{aligned}\]

(Xu et al., 2024) considers dimensions $D = 2, 3, 4$.

For $D = 2$, the standard hypergraph product code is obtained, with planar surface codes as a special case (Xu et al., 2024).
For $D = 3$ and $D = 4$, the construction yields 3D and 4D homological product codes, with 3D surface/toric codes serving as specific instances (Xu et al., 2024).

Examples

Here is a 3D Homological product code from (Quintavalle et al., 2021).

julia> using Oscar; using QuantumClifford; using QuantumClifford.ECC; using QECCore;

julia> δ = matrix(GF(2), parity_matrix(RepCode(3)));

julia> c = HomologicalProductCode([δ,δ,δ]);

julia> import HiGHS; import JuMP;

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(81, 3, 3)

Here is the [[117, 9, 4]] Homological product code construct from classical quasi-cyclic code from Table III of (Xu et al., 2024).

julia> using Oscar; using QuantumClifford; using QuantumClifford.ECC; using QECCore;

julia> R, x = polynomial_ring(GF(2), "x");

julia> l = 3;

julia> H = matrix(R, 2, 3, [x^2 x^2 x^2;
                            x   x^2  0]);

julia> c = HomologicalProductCode([H,transpose(H)], l);

julia> import HiGHS; import JuMP;

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(117, 9, 4)

Here is a Homological product of (3,4)-classical LDPC codes.

julia> using Oscar; using QuantumClifford; using QuantumClifford.ECC; using QECCore;

julia> μ = 2; wc = 3; wr = 4;

julia> c = GallagerLDPC(μ, wc, wr);

julia> H = matrix(GF(2), parity_matrix(c));

julia> c = HomologicalProductCode([H,transpose(H)]);

julia> import HiGHS; import JuMP;

julia> coden(c), codek(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS)) (100, 20, 2) ```

Fields

boundary_maps::Vector{T} where T<:AbstractAlgebra.MatElem: A length-D vector of parity-check matrices of classical error-correcting codes.

source

QuantumClifford.ECC.boundary_maps — Method

Returns all boundary maps of the chain complex, including both parity check and metacheck matrices.

Here are the boundary maps of [[12, 1, 2]] 3D Surface code with L = 2 from (Berthusen et al., 2024).

julia> using Oscar; using QuantumClifford; using QECCore;

julia> using QuantumClifford.ECC: DDimensionalSurfaceCode, boundary_maps, metacheck_matrix_z;

julia> D = 3; L = 2;

julia> c = DDimensionalSurfaceCode(D, L);

julia> Mz, Hz, Hx = boundary_maps(c);

The parity check matrices of [[12, 1, 2]] 3D Surface code are

julia> Hx
4×12 Matrix{Int64}:
 1  1  0  0  1  0  0  0  0  0  1  0
 0  0  1  1  1  0  0  0  0  0  0  1
 0  0  0  0  0  1  1  0  0  1  1  0
 0  0  0  0  0  0  0  1  1  1  0  1

Note

For 3D and higher-dimensional codes, Oscar returns Z-type parity check matrix as transpose ($H_Z^T$). We transpose it to convert it back to $H_Z$. See B3, page 11 of (Berthusen et al., 2024).

julia> Hz'
9×12 adjoint(::Matrix{Int64}) with eltype Int64:
 1  0  1  0  1  0  0  0  0  0  0  0
 0  1  0  1  1  0  0  0  0  0  0  0
 0  0  0  0  0  1  0  1  0  1  0  0
 0  0  0  0  0  0  1  0  1  1  0  0
 1  0  0  0  0  1  0  0  0  0  1  0
 0  1  0  0  0  0  1  0  0  0  1  0
 0  0  1  0  0  0  0  1  0  0  0  1
 0  0  0  1  0  0  0  0  1  0  0  1
 0  0  0  0  1  0  0  0  0  1  1  1

Along with the Z- and X-type parity check matrices, we have a metacheck matrix specifically for the Z-type checks. The classical code derived from this metacheck matrix has a distance of d = 2 meaning it can identify (but not correct) a single error in the Z-type syndrome measurements. See page 12 of (Berthusen et al., 2024) for details.

julia> Mz'
2×9 adjoint(::Matrix{Int64}) with eltype Int64:
 1  0  1  0  1  0  1  0  1
 0  1  0  1  0  1  0  1  1

We can use metacheck_matrix_z directly instead of using boundary_maps.

julia> metacheck_matrix_z(c)
2×9 Matrix{Int64}:
 1  0  1  0  1  0  1  0  1
 0  1  0  1  0  1  0  1  1

Metachecks in CSS Codes

The parity-check matrices $M_Z$ and $M_X$ are called metachecks in CSS codes. These matrices emerge from the constraints imposed by boundary maps, which satisfy the condition $\partial_{i+1} \partial_i = 0$. This guarantees that:

\[\begin{aligned} M_Z H_Z = 0 \quad \text{and} \quad M_X H_X = 0, \end{aligned}\]

meaning that:

Valid $Z$-type syndromes must be in $\ker M_Z$
Valid $X$-type syndromes must be in $\ker M_X$

When measurement errors occur, they distort the syndrome vector $\mathbf{s}$, generating a detectable metasyndrome. By examining $\mathbf{m}$, we can identify and correct errors in $\mathbf{s}$ before proceeding with standard decoding. This technique is called syndrome repair decoding (Higgott and Breuckmann, 2023).

source

QuantumClifford.ECC.twobga_from_direct_product — Method

twobga_from_direct_product(
    a_elts::Vector{Hecke.GroupAlgebraElem{Nemo.FqFieldElem, Hecke.GroupAlgebra{Nemo.FqFieldElem, Oscar.DirectProductGroup, Oscar.BasicGAPGroupElem{Oscar.DirectProductGroup}}}},
    b_elts::Vector{Hecke.GroupAlgebraElem{Nemo.FqFieldElem, Hecke.GroupAlgebra{Nemo.FqFieldElem, Oscar.DirectProductGroup, Oscar.BasicGAPGroupElem{Oscar.DirectProductGroup}}}},
    F2G::Hecke.GroupAlgebra{Nemo.FqFieldElem, Oscar.DirectProductGroup, Oscar.BasicGAPGroupElem{Oscar.DirectProductGroup}}
) -> Any

Constructing two block group algebra codes by specifying the direct product to be used. See also the more general two_block_group_algebra_codes.

Two block group algebra codes are constructed by choosing a group (and specific generators), then choosing two polynomials made out of these generators, then piping these two polynomials as the elements of 1×1 matrices to the lifted product code constructors.

The Hecke library, for which we already have an extension, provides for a fairly easy way to construct such polynomials for many abelian and small groups. See two_block_group_algebra_codes for those capabilities.

However, more esoteric groups can be specified as the direct product of other groups. To support arbitrary direct products we use Oscar, which builds upon Hecke. Oscar supports the direct product operation between two or more arbitrary general groups, including non-abelian groups such as alternating_group, dihedral_group, symmetric_group, and even arbitrary finitely presented groups (e.g., free_group). This capability is not available in Hecke.jl. The 2BGA codes discovered in (Lin and Pryadko, 2024) rely on direct products of two or more general groups, which necessitate the use of Oscar.direct_product.

This particular function is nothing more than a simple wrapper that takes care of argument conversions. Of note, the polynomials here are given as lists of monomials.

Of course, if you are comfortable with Oscar, you can use two_block_group_algebra_codes directly.

Examples

The [[56, 28, 2]] abelian 2BGA code from Appendix C, Table II in (Lin and Pryadko, 2024) can be constructed using the direct product of two cyclic groups. Specifically, the group C₂₈ of order l = 28 can be represented as C₁₄ × C₂, where the first group has order m = 14 and the second group has order n = 2.

julia> import Oscar: cyclic_group, small_group_identification, describe, order

julia> import Hecke: gens, quo, group_algebra, GF, one, direct_product, sub

julia> using QuantumClifford, QuantumClifford.ECC

julia> m = 14; n = 2;

julia> C₁₄ = cyclic_group(m);

julia> C₂ = cyclic_group(n);

julia> G = direct_product(C₁₄, C₂);

julia> GA = group_algebra(GF(2), G);

julia> x, s = gens(GA)[1], gens(GA)[3];

julia> a = [one(GA), x^7];

julia> b = [one(GA), x^7, s, x^8, s * x^7, x];

julia> c = twobga_from_direct_product(a, b, GA);

julia> order(G)
28

julia> code_n(c), code_k(c)
(56, 28)

julia> describe(G), small_group_identification(G)
("C14 x C2", (28, 4))

Danger

When using the direct product, there isn't necessarily a unique set of generators. It is essential to verify that Oscar is providing you with the generators you expect, e.g. for a cycling group that you have the presentation Cₘ = ⟨x, s | xᵐ = s² = xsx⁻¹s⁻¹ = 1⟩. For situations where the generators provided by Oscar are not the ones you want, you can also use twobga_from_fp_group where you specify the group presentation directly.

As a verification that you have the correct generators, Oscar.sub can be used to determine if H is a subgroup of G and to confirm that both C₁₄ and C₂ are subgroups of C₂₈.

julia> order(gens(G)[1])
14

julia> order(gens(G)[3])
2

julia> x^14 == s^2 == x * s * x^-1 * s^-1
true

julia> H, _  = sub(G, [gens(G)[1], gens(G)[3]]);

julia> H == G
true

source

QuantumClifford.ECC.twobga_from_fp_group — Method

twobga_from_fp_group(
    a_elts::Vector{Oscar.FPGroupElem},
    b_elts::Vector{Oscar.FPGroupElem},
    F2G::Hecke.GroupAlgebra{Nemo.FqFieldElem, Oscar.FPGroup, Oscar.FPGroupElem}
) -> Any

Constructing two block group algebra codes by specifying the group presentation.

However, more esoteric groups are usually specified by a group presentation ⟨S | R⟩, where S is a set of generators and R is the relations those generators obey. To support arbitrary group presentations we use Oscar, which builds upon Hecke. We use Oscar.free_group and quo in order to first prepare the free group generated by S, and then the group obeying also the relations R, i.e. the ⟨S | R⟩ presentation.

After that point we proceed as usual, creating two polynomials of generators and piping them to two_block_group_algebra_codes.

This particular function is nothing more than a simple wrapper that takes care of argument conversions. Of note, the polynomials here are given as lists of monomials.

Of course, if you are comfortable with Oscar, you can use two_block_group_algebra_codes directly.

Examples

The [[96, 12, 10]] 2BGA code from Table I in (Lin and Pryadko, 2024) has the group presentation ⟨r, s | s⁶ = r⁸ = r⁻¹srs = 1⟩ (the group C₂ × (C₃ ⋉ C₈)).

julia> import Oscar: free_group, small_group_identification, describe, order

julia> import Hecke: gens, quo, group_algebra, GF, one

julia> using QuantumClifford, QuantumClifford.ECC

julia> F = free_group(["r", "s"]);

julia> r, s = gens(F); # generators

julia> G, = quo(F, [s^6, r^8, r^(-1) * s * r * s]);  # relations

julia> GA = group_algebra(GF(2), G);

julia> r, s = gens(G);

julia> a = [one(G), r, s^3 * r^2, s^2 * r^3];

julia> b = [one(G), r, s^4 * r^6, s^5 * r^3];

julia> c = twobga_from_fp_group(a, b, GA);

julia> order(G)
48

julia> code_n(c), code_k(c)
(96, 12)

julia> describe(G), small_group_identification(G)
("C2 x (C3 : C8)", (48, 9))

Cyclic Groups

Cyclic groups with specific group presentations, given by Cₘ = ⟨x, s | xᵐ = s² = xsx⁻¹s⁻¹ = 1⟩, where the order is 2m as seen in Table II of (Lin and Pryadko, 2024).

The [[56, 28, 2]] abelian 2BGA code from Appendix C, Table II in (Lin and Pryadko, 2024) is constructed using the group presentation ⟨x, s | xs = sx, xᵐ = s² = 1⟩ (the cyclic group C₂₈ = C₁₄ × C₂).

julia> m = 14;

julia> F = free_group(["x", "s"]);

julia> x, s = gens(F); # generators

julia> G, = quo(F, [x^m, s^2, x * s * x^-1 * s^-1]); # relations

julia> GA = group_algebra(GF(2), G);

julia> x, s = gens(G);

julia> a = [one(G), x^7];

julia> b = [one(G), x^7, s, x^8, s * x^7, x];

julia> c = twobga_from_fp_group(a, b, GA);

julia> order(G)
28

julia> code_n(c), code_k(c)
(56, 28)

julia> describe(G), small_group_identification(G)
("C14 x C2", (28, 4))

Dihedral Groups

Dihedral (non-abelian) groups with group presentations given by Dₘ = ⟨r, s | rᵐ = s² = (rs)² = 1⟩, where the order is 2m.

The [[24, 8, 3]] 2BGA code from Appendix C, Table III in (Lin and Pryadko, 2024) is constructed by specifying a group presentation below (giving the group D₆ = C₆ ⋉ C₂).

julia> m = 6;

julia> F = free_group(["r", "s"]);

julia> r, s = gens(F); # generators

julia> G, = quo(F, [r^m, s^2, (r*s)^2]); # relations

julia> GA = group_algebra(GF(2), G);

julia> r, s = gens(G);

julia> a = [one(G), r^4];

julia> b = [one(G), s*r^4, r^3, r^4, s*r^2, r];

julia> c = twobga_from_fp_group(a, b, GA);

julia> order(G)
12

julia> code_n(c), code_k(c)
(24, 8)

julia> describe(G), small_group_identification(G)
("D12", (12, 4))

Note

Notice how in all of these construction we are specifying a group presentation. We are explicitly not picking a group by name and getting its "canonical" generators, as we do not a priori know whether Oscar would give us the generating set we need (generating sets are not unique).

source

Implemented in an extension requiring `JuMP.jl`

QECCore.distance — Method

distance(
    code::QECCore.AbstractECC,
    alg::QuantumClifford.ECC.DistanceMIPAlgorithm
) -> Any

Compute the distance of a code using mixed integer programming. See QuantumClifford.ECC.DistanceMIPAlgorithm for configuration options.

Specifically, it computes the minimum distance of a Calderbank-Shor-Steane code by solving two independent Mixed Integer Programs for X-type ($d_X$) and Z-type ($d_Z$) distances. The code distance is $d = \min(d_X, d_Z)$.

Background on Minimum Distance

For classical codes, the minimum distance, which measures a code's error-correcting capability, is equivalent to its minimum weight. This can be computed by generating all possible codewords from combinations of the generator matrix rows, calculating their weights, and finding the smallest. While accurate, this method takes exponential time. Vardy (Vardy, 1997) demonstrated that computing the minimum distance is NP-hard, and the corresponding decision problem is NP-complete, making polynomial-time algorithms unlikely.

For quantum codes, classical intuition does not always apply. The minimum distance is given by the minimum weight of a non-trivial logical operator. This is generally unrelated to the minimum distance of the corresponding stabilizer code when viewed as a classical, additive code. White and Grassl (White and Grassl, 2006) proposed mapping quantum codes to higher-dimensional classical linear codes. This mapping allows the minimum distance of the quantum additive code to be inferred from that of the classical linear code but increases parameters from n to 3n and d to 2d, adding complexity. Furthermore, once a minimal weight vector is identified, it is essential to verify whether it belongs to the Pauli group 𝒫ₙ over n qubits (Sabo, 2022).

Note

The minimum distance problem for quantum codes is NP-hard, and this hardness extends to multiplicative and additive approximations, even when restricted to stabilizer or CSS codes, with the result established through a reduction from classical problems in the CWS framework using a 4-cycle free graph (Kapshikar and Kundu, 2023). Despite this, methods that improve on brute-force approaches are actively explored.

For a more in-depth background on minimum distance, see Chapter 3 of (Sabo, 2022).

Quantum Error Correction and Code Distance

The foundation of quantum error correction lies in protecting logical quantum information from physical errors by encoding it across multiple qubits. A quantum code's performance is fundamentally characterized by its distance (d), which quantifies the code's ability to detect and correct errors. Practically, the distance represents the minimum number of physical qubit errors required to cause an undetectable logical error - one that corrupts encoded information while evading the code's error detection mechanisms.

Fundamentals of Quantum Code Distance

The distance d of a quantum error-correcting code represents its robustness against physical errors and is defined as (Ekert et al., undated):

\[\begin{aligned} d = \min_{P \in N(S)\setminus S} \mathrm{wt}(P) \end{aligned}\]

where:

$N(S)$ denotes the normalizer of the stabilizer group S.
$\mathrm{wt}(P)$ represents the weight of Pauli operator P.
The minimization is taken over all logical operators that are not stabilizers.

The distance reveals the essential property that it equals the smallest number of qubits that must be affected to produce a logical error undetectable by stabilizer measurements. The normalizer condition $P \in N(S)$ ensures the operator commutes with all stabilizers, while $P \notin S$ guarantees it performs a non-trivial logical operation (Ekert et al., undated).

Mixed Integer Programming

We compute the minimum code distance for CSS (Calderbank-Shor-Steane) codes by solving MIPs.

The distance is computed separately for X-type ($d_X$) and Z-type ($d_Z$) logical operators, then combined to give the true code distance: $d = \min(d_X, d_Z)$.

X-type and Z-type Distances

The X-type distance ($d_X$) and Z-type distance ($d_Z$) are defined as the minimum number of errors required to implement a non-trivial logical operator of the opposite type, subject to the following constraints:

For $d_X$ (where $U = X$), the errors are Z-type (phase flips), and the constraints involve the X-stabilizer matrix $\mathbf{H_X}$ and X-logical operators $\mathbf{L_X}$. The error vector is denoted as $\mathbf{e}_Z$.
For $d_Z$ (where $U = Z$), the errors are X-type (bit flips), with constraints given by the Z-stabilizer matrix $\mathbf{H_Z}$ and Z-logical operators $\mathbf{L_Z}$, and the error vector is $\mathbf{e}_X$.

\[\begin{aligned} \text{Minimize} \quad & \sum_{i=1}^n e_{V,i} \quad \text{(Hamming weight of errors)} \\ \text{Subject to} \quad & \mathbf{H_U} \cdot \mathbf{e}_V \equiv \mathbf{0} \pmod{2} \quad \text{(Commutes with U-stabilizers)} \\ & \mathbf{L_U} \cdot \mathbf{e}_V \equiv 1 \pmod{2} \quad \text{(Anti-commutes with U-logical)} \\ & e_{V,i} \in \{0,1\} \quad \text{(Binary error variables)} \end{aligned}\]

Example

A [[40, 8, 5]] 2BGA code with the minimum distance of 5 from Table 2 of (Lin and Pryadko, 2024).

julia> import Hecke: group_algebra, GF, abelian_group, gens; import HiGHS; import JuMP;

julia> using QuantumClifford, QuantumClifford.ECC

julia> l = 10; m = 2;

julia> GA = group_algebra(GF(2), abelian_group([l,m]));

julia> x, s = gens(GA);

julia> A = 1 + x^6;

julia> B = 1 + x^5 + s + x^6 + x + s*x^2;

julia> c = two_block_group_algebra_codes(A,B);

julia> code_n(c), code_k(c), distance(c, DistanceMIPAlgorithm(solver=HiGHS))
(40, 8, 5)

A [[48, 6, 8]] GB code with the minimum distance of 8 from (A3) in Appendix B of (Panteleev and Kalachev, 2021).

julia> l = 24;

julia> c1 = generalized_bicycle_codes([0, 2, 8, 15], [0, 2, 12, 17], l);

julia> code_n(c1), code_k(c1), distance(c1, DistanceMIPAlgorithm(solver=HiGHS))
(48, 6, 8)

Applications

Mixed-integer programming (MIP) is applied in quantum error correction, notably for decoding and minimum distance computation. Some applications are as follows:

The first usecase of the MIP approach was the code capacity Most Likely Error (MLE) decoder for color codes introduced in (Landahl et al., 2011).
For all quantum LDPC codes presented in (Panteleev and Kalachev, 2021), the lower and upper bounds on the minimum distance was obtained by reduction to a mixed integer linear program and using the GNU Linear Programming Kit ((Makhorin, 2008)).
For all the Bivariate Bicycle (BB) codes presented in (Bravyi et al., 2024), the code distance was calculated using the mixed integer programming approach.
(Lacroix et al., 2024) developed a MLE decoder that finds the most likely chain of Pauli errors given the observed error syndrome by solving a mixed-integer program using HiGHS package ((Huangfu and Hall, 2018)).
(Cain et al., 2025) formulate maximum-likelihood decoding as a mixed-integer program maximizing $\prod_{j=1}^M p_j^{E_j}(1-p_j)^{1-E_j}$ (where binary variables $E_j \in {0,1}$ indicate error occurrence) subject to syndrome constraints, solved optimally via MIP solvers despite its NP-hard complexity.

source

Full ECC API (autogenerated)

Implemented in an extension requiring Hecke.jl

Implemented in an extension requiring Oscar.jl

Implemented in an extension requiring JuMP.jl

Implemented in an extension requiring `Hecke.jl`

Implemented in an extension requiring `Oscar.jl`

Implemented in an extension requiring `JuMP.jl`