qec 0.3.0__py3-none-any.whl → 0.3.3__py3-none-any.whl

qec/code_constructions/hgp_code.py

@@ -0,0 +1,344 @@
+import numpy as np
+import scipy
+from typing import Union, Tuple
+import ldpc.mod2
+import time
+
+from qec.code_constructions import CSSCode
+from qec.utils.sparse_binary_utils import (
+    convert_to_binary_scipy_sparse,
+    binary_csr_matrix_to_dict,
+)
+
+
+class HypergraphProductCode(CSSCode):
+    r"""
+    Implements a Hypergraph Product (HGP) code - derived from two classical linear binary codes.
+    
+    Parameters
+    ----------
+    seed_matrix_1 : 
+        A classical linear binary code used as a "seed" in the HGP construction method.
+    seed_matrix_2 :
+        A classical linear binary code used as a "seed" in the HGP construction method.
+    name : str, default = None
+        The name of the code. If None, the name is set to: "Hypergraph product code" 
+    
+    Attributes
+    ----------
+    seed_matrix_1 : scipy.sparse.spmatrix
+        The input seed_matrix_1 stored as a scipy sparse matrix.
+    seed_matrix_2 : scipy.sparse.spmatrix
+        The input seed_matrix_2 stored as a scipy sparse matrix.
+    _n1 : int
+        Number of columns in seed_matrix_1
+    _n2 : int
+        Number of columns in seed_matrix_2
+    _m1 : int
+        Number of rows in seed_matrix_1 (the number of columns of it's transpose)
+    _m2 : int
+        Number of rows in seed_matrix_2 (the number of columns of it's transpose)
+    
+    Notes
+    -----
+
+    The X and Z stabilizer matrices are given by [1]_: 
+    
+    .. math::
+
+        \begin{align}
+            H_{X} &= \begin{pmatrix}
+                        H_{1}\otimes I_{n_{2}} & \,\,I_{r_{1}}\otimes H_{2}^{T}
+                     \end{pmatrix}\tag*{(1)}\\
+            H_{Z} &= \begin{pmatrix}
+                        I_{n_{1}}\otimes H_{2} & \,\,H_{1}^{T}\otimes I_{r_{2}}
+                     \end{pmatrix}~, \tag*{(2)}
+        \end{align}
+
+    where  :math:`H_1` and  :math:`H_2` correspond to the parity check matrix of the first and second "seed" codes.
+    
+
+    .. [1] J.-P. Tillich and G. Zemor, “Quantum LDPC Codes With Positive Rate and Minimum Distance Proportional to the Square Root of the Blocklength”, IEEE Transactions on Information Theory 60, 1193 (2014)
+    """
+
+    def __init__(
+        self,
+        seed_matrix_1: Union[np.ndarray, scipy.sparse.spmatrix],
+        seed_matrix_2: Union[np.ndarray, scipy.sparse.spmatrix],
+        name: str = None,
+    ):
+        self.name = name if name else "Hypergraph product code"
+
+        if not all(
+            isinstance(seed_m, (np.ndarray, scipy.sparse.spmatrix))
+            for seed_m in (seed_matrix_1, seed_matrix_2)
+        ):
+            raise TypeError(
+                "The seed matrices must be either numpy arrays or scipy sparse matrices."
+            )
+
+        self.seed_matrix_1 = convert_to_binary_scipy_sparse(seed_matrix_1)
+        self.seed_matrix_2 = convert_to_binary_scipy_sparse(seed_matrix_2)
+
+        # maybe move the below to a private _construct_stabilizer_matrices function?
+        # --------------------------------------------------------------------------
+        self._n1 = seed_matrix_1.shape[1]
+        self._n2 = seed_matrix_2.shape[1]
+
+        self._m1 = seed_matrix_1.shape[0]
+        self._m2 = seed_matrix_2.shape[0]
+
+        x_left = scipy.sparse.kron(seed_matrix_1, scipy.sparse.eye(self._n2))
+        x_right = scipy.sparse.kron(scipy.sparse.eye(self._m1), seed_matrix_2.T)
+        self.x_stabilizer_matrix = scipy.sparse.hstack([x_left, x_right])
+
+        z_left = scipy.sparse.kron(scipy.sparse.eye(self._n1), seed_matrix_2)
+        z_right = scipy.sparse.kron(seed_matrix_1.T, scipy.sparse.eye(self._m2))
+        self.z_stabilizer_matrix = scipy.sparse.hstack([z_left, z_right])
+        # --------------------------------------------------------------------------
+
+        super().__init__(self.x_stabilizer_matrix, self.z_stabilizer_matrix, self.name)
+
+        self.code_distance = None
+
+    def compute_exact_code_distance(self) -> int:
+        r"""
+        Computes the exact code distance of the HGP code.
+
+        Returns
+        -------
+        int
+            The distance of the code.
+
+        Notes
+        -----
+        The distance of a HGP code is given as:
+
+        .. math::
+
+            \min(d_1, d_2, d_1^T, d_2^T)
+
+        corresponding to the distance of the seed codes and the distance of their transposes.
+        """
+
+        rank_seed_m1 = ldpc.mod2.rank(self.seed_matrix_1)
+        rank_seed_m2 = ldpc.mod2.rank(self.seed_matrix_2)
+
+        if self.seed_matrix_1.shape[1] != rank_seed_m1:
+            self.d1 = ldpc.mod2.compute_exact_code_distance(self.seed_matrix_1)
+        else:
+            self.d1 = np.inf
+
+        if self.seed_matrix_2.shape[1] != rank_seed_m2:
+            self.d2 = ldpc.mod2.compute_exact_code_distance(self.seed_matrix_2)
+        else:
+            self.d2 = np.inf
+
+        # note: rank(A) = rank(A^T):
+        if self.seed_matrix_1.shape[0] != rank_seed_m1:
+            self.d1T = ldpc.mod2.compute_exact_code_distance(self.seed_matrix_1.T)
+        else:
+            self.d1T = np.inf
+
+        if self.seed_matrix_2.shape[0] != rank_seed_m2:
+            self.d2T = ldpc.mod2.compute_exact_code_distance(self.seed_matrix_2.T)
+        else:
+            self.d2T = np.inf
+
+        self.x_code_distance = min(self.d1T, self.d2)
+        self.z_code_distance = min(self.d1, self.d2T)
+        self.code_distance = min(self.x_code_distance, self.z_code_distance)
+
+        return self.code_distance
+
+    def estimate_min_distance(self, timeout_seconds: float = 0.025) -> int:
+        """
+        Estimate the minimum X and Z distance of the HGP code.        Parameters
+        ----------
+        timeout_seconds : float, optional
+            Time limit in seconds for the full search. Default: 0.25
+
+        Returns
+        -------
+        int
+            Best estimate of the (overall) code distance found within time limit.
+
+        """
+
+        rank_seed_m1 = ldpc.mod2.rank(self.seed_matrix_1)
+        rank_seed_m2 = ldpc.mod2.rank(self.seed_matrix_2)
+
+        d1_timeout_seconds = timeout_seconds / 4
+        if self.seed_matrix_1.shape[1] != rank_seed_m1:
+            d1_start_time = time.time()
+            d1_min_estimate, _, _ = ldpc.mod2.estimate_code_distance(
+                self.seed_matrix_1, d1_timeout_seconds, 0
+            )
+            d1_run_time = time.time() - d1_start_time
+        else:
+            d1_min_estimate = np.inf
+            d1_run_time = 0
+
+        d1T_timeout_seconds = (
+            (d1_timeout_seconds * 4 - d1_run_time) / 3
+            if d1_run_time <= d1_timeout_seconds
+            else timeout_seconds / 4
+        )
+        if self.seed_matrix_1.shape[0] != rank_seed_m1:
+            d1T_start_time = time.time()
+            d1T_min_estimate, _, _ = ldpc.mod2.estimate_code_distance(
+                self.seed_matrix_1.T, d1T_timeout_seconds, 0
+            )
+            d1T_run_time = time.time() - d1T_start_time
+        else:
+            d1T_min_estimate = np.inf
+            d1T_run_time = 0
+
+        d2_timeout_seconds = (
+            (d1T_timeout_seconds * 3 - d1T_run_time) / 2
+            if d1T_run_time <= d1T_timeout_seconds
+            else timeout_seconds / 4
+        )
+        if self.seed_matrix_2.shape[1] != rank_seed_m2:
+            d2_start_time = time.time()
+            d2_min_estimate, _, _ = ldpc.mod2.estimate_code_distance(
+                self.seed_matrix_2, d2_timeout_seconds, 0
+            )
+            d2_run_time = time.time() - d2_start_time
+        else:
+            d2_min_estimate = np.inf
+            d2_run_time = 0
+
+        d2T_timeout_seconds = (
+            (d2_timeout_seconds * 2 - d2_run_time)
+            if d2_run_time <= d2_timeout_seconds
+            else timeout_seconds / 4
+        )
+        if self.seed_matrix_2.shape[0] != rank_seed_m2:
+            d2T_min_estimate, _, _ = ldpc.mod2.estimate_code_distance(
+                self.seed_matrix_2.T, d2T_timeout_seconds, 0
+            )
+        else:
+            d2T_min_estimate = np.inf
+
+        self.x_code_distance = min(d1T_min_estimate, d2_min_estimate)
+        self.z_code_distance = min(d1_min_estimate, d2T_min_estimate)
+        self.code_distance = min(self.x_code_distance, self.z_code_distance)
+
+        return self.code_distance
+
+    def compute_logical_basis(
+        self,
+    ) -> Tuple[scipy.sparse.spmatrix, scipy.sparse.spmatrix]:
+        """
+        Compute the logical operator basis for the given HGP code.
+
+        Returns
+        -------
+        Tuple[scipy.sparse.spmatrix, scipy.sparse.spmatrix]
+            Logical X and Z operator bases (lx, lz).
+        """
+
+        ker_h1 = ldpc.mod2.kernel(self.seed_matrix_1)
+        ker_h2 = ldpc.mod2.kernel(self.seed_matrix_2)
+        ker_h1T = ldpc.mod2.kernel(self.seed_matrix_1.T)
+        ker_h2T = ldpc.mod2.kernel(self.seed_matrix_2.T)
+
+        row_comp_h1 = ldpc.mod2.row_complement_basis(self.seed_matrix_1)
+        row_comp_h2 = ldpc.mod2.row_complement_basis(self.seed_matrix_2)
+        row_comp_h1T = ldpc.mod2.row_complement_basis(self.seed_matrix_1.T)
+        row_comp_h2T = ldpc.mod2.row_complement_basis(self.seed_matrix_2.T)
+
+        temp = scipy.sparse.kron(ker_h1, row_comp_h2)
+        lz1 = scipy.sparse.hstack(
+            [
+                temp,
+                scipy.sparse.csr_matrix(
+                    (temp.shape[0], self._m1 * self._m2), dtype=np.uint8
+                ),
+            ]
+        )
+
+        temp = scipy.sparse.kron(row_comp_h1T, ker_h2T)
+        lz2 = scipy.sparse.hstack(
+            [
+                scipy.sparse.csr_matrix(
+                    (temp.shape[0], self._n1 * self._n2), dtype=np.uint8
+                ),
+                temp,
+            ]
+        )
+
+        self.z_logical_operator_basis = scipy.sparse.csr_matrix(
+            scipy.sparse.vstack([lz1, lz2], dtype=np.uint8)
+        )
+
+        temp = scipy.sparse.kron(row_comp_h1, ker_h2)
+        lx1 = scipy.sparse.hstack(
+            [
+                temp,
+                scipy.sparse.csr_matrix(
+                    (temp.shape[0], self._m1 * self._m2), dtype=np.uint8
+                ),
+            ]
+        )
+
+        temp = scipy.sparse.kron(ker_h1T, row_comp_h2T)
+        lx2 = scipy.sparse.hstack(
+            [
+                scipy.sparse.csr_matrix(
+                    (temp.shape[0], self._n1 * self._n2), dtype=np.uint8
+                ),
+                temp,
+            ]
+        )
+
+        self.x_logical_operator_basis = scipy.sparse.csr_matrix(
+            scipy.sparse.vstack([lx1, lx2], dtype=np.uint8)
+        )
+
+        # Follows the way it is done in CSSCode -> move it into __init__?
+        # ----------------------------------------------------------------
+        self.logical_qubit_count = self.x_logical_operator_basis.shape[0]
+        # ----------------------------------------------------------------
+
+        return (self.x_logical_operator_basis, self.z_logical_operator_basis)
+
+    def __str__(self):
+        """
+        String representation of the HGP code. Includes the name and [[n, k, d]] properties of the code.
+
+        Returns
+        -------
+        str
+            String representation of the HGP code.
+        """
+
+        return f"{self.name} Hypergraphproduct Code: [[N={self.physical_qubit_count}, K={self.logical_qubit_count}, dx={self.x_code_distance}, dz={self.z_code_distance}]]"
+
+    def _class_specific_save(self):
+        class_specific_data = {
+            "code_distance": self.code_distance
+            if self.code_distance is not None
+            else "?",
+            "x_code_distance": self.x_code_distance
+            if self.x_code_distance is not None
+            else "?",
+            "z_code_distance": self.z_code_distance
+            if self.z_code_distance is not None
+            else "?",
+            "seed_matrix_1": binary_csr_matrix_to_dict(self.seed_matrix_1),
+            "seed_matrix_2": binary_csr_matrix_to_dict(self.seed_matrix_2),
+            "x_logical_operator_basis": binary_csr_matrix_to_dict(
+                self.x_logical_operator_basis
+            )
+            if self._x_logical_operator_basis is not None
+            else "?",
+            "z_logical_operator_basis": binary_csr_matrix_to_dict(
+                self.z_logical_operator_basis
+            )
+            if self._z_logical_operator_basis is not None
+            else "?",
+        }
+
+        return class_specific_data

qec/code_constructions/periodic_surface_xzzx.py

@@ -0,0 +1,100 @@
+import numpy as np
+import scipy.sparse
+from qec.code_constructions import StabilizerCode
+
+
+class PeriodicSurfaceXZZX(StabilizerCode):
+    """
+    Represents a Periodic Surface XZZX Code, a type of quantum error correction code.
+
+    This code is defined on a standard surface code lattice with periodic boundary conditions.
+    The stabilizers measure XZZX, and the qubits are labeled sequentially from 1 to N, row by row from left to right.
+
+    The code's parity check matrix is defined as follows:
+
+    H = [Hx | Hz]
+
+    where Hz is a repetition code over N qubits, with N = lx * lz + (lx - 1) * (lz - 1).
+    Hz is constructed such that the vertically measured stabilizers have periodic boundary conditions.
+    Hx and Hz are swapped if noise_bias is set to "X".
+
+    Parameters
+    ----------
+    lx : int
+        The size of the lattice in the horizontal direction.
+    lz : int
+        The size of the lattice in the vertical direction.
+    noise_bias : str, optional
+        The type of noise bias, default is "Z". This determines which stabilizer Pauli type is defined by the repetition code that spans all qubits.
+
+    Attributes
+    ----------
+    hx : scipy.sparse.csr_matrix
+        The parity check matrix for X stabilizers.
+    hz : scipy.sparse.csr_matrix
+        The parity check matrix for Z stabilizers.
+    stabilizer_matrix : scipy.sparse.csr_matrix
+        The combined parity check matrix [Hx | Hz].
+    name : str
+        The name of the code.
+    """
+
+    def __init__(self, lx: int, lz: int, noise_bias: str = "Z"):
+        # Calculate the total number of qubits
+        N = lx * lz + (lx - 1) * (lz - 1)
+
+        # Generate the parity check matrices for Z and X stabilizers based on noise bias
+        if noise_bias == "X":
+            hz = self._full_row_rank_shift_matrix(
+                N, 0
+            ) + self._full_row_rank_shift_matrix(N, 1)
+            hx = self._full_row_rank_shift_matrix(
+                N, lz
+            ) + self._full_row_rank_shift_matrix(N, (1 - lz))
+        else:  # Default to "Z" noise bias
+            hz = self._full_row_rank_shift_matrix(
+                N, lx
+            ) + self._full_row_rank_shift_matrix(N, (1 - lx))
+            hx = self._full_row_rank_shift_matrix(
+                N, 0
+            ) + self._full_row_rank_shift_matrix(N, 1)
+
+        # Combine the parity check matrices into a single stabilizer matrix
+        stabilizer_matrix = scipy.sparse.hstack([hx, hz])
+
+        # Initialize the StabilizerCode with the combined parity check matrix
+        super().__init__(
+            stabilizer_matrix, name=f"Periodic Surface XZZX ({lx}x{lz}) Code"
+        )
+
+    def _full_row_rank_shift_matrix(
+        self, n: int, shift: int
+    ) -> scipy.sparse.csr_matrix:
+        """
+        Generate a full-rank shift matrix.
+
+        Parameters
+        ----------
+        n : int
+            The size of the matrix.
+        shift : int
+            The shift to apply to the permutation.
+
+        Returns
+        -------
+        scipy.sparse.csr_matrix
+            The full-rank shift matrix.
+        """
+        # Create the base matrix with an identity matrix and a zero column
+        base = (
+            scipy.sparse.hstack(
+                [scipy.sparse.identity(n - 1), scipy.sparse.csc_matrix((n - 1, 1))]
+            )
+            .astype(np.uint8)
+            .tocsc()
+        )
+        # Create the permutation array
+        perm = np.arange(n)
+        perm = (perm - shift) % n
+        # Apply the permutation to the base matrix
+        return base[:, perm]

qec/code_constructions/rotated_xzzx.py

@@ -0,0 +1,122 @@
+import scipy.sparse
+from qec.code_constructions import StabilizerCode
+
+
+class RotatedSurfaceXZZX(StabilizerCode):
+    """
+    Represents a Rotated Surface XZZX Code, a type of quantum error correction code.
+
+    This code is defined on a rotated surface code lattice of size lx x lz where all stabilizers measure XZZX.
+    The boundary conditions are periodic.
+
+    Parameters
+    ----------
+    lx : int
+        The size of the lattice in the horizontal direction.
+    lz : int
+        The size of the lattice in the vertical direction.
+
+    Attributes
+    ----------
+    hx : scipy.sparse.csr_matrix
+        The parity check matrix for X stabilizers.
+    hz : scipy.sparse.csr_matrix
+        The parity check matrix for Z stabilizers.
+    stabilizer_matrix : scipy.sparse.csr_matrix
+        The combined parity check matrix [Hx | Hz].
+    name : str
+        The name of the code.
+
+    Notes
+    -----
+    If lx and lz are both even, then the code encodes 2 logical qubits. Otherwise, it encodes 1 logical qubit.
+    The code's parity check matrix can be derived as a composition of two full-rank shift matrices.
+    This code is described in https://arxiv.org/abs/2009.07851.
+    """
+
+    def __init__(self, lx: int, lz: int):
+        # Calculate the total number of qubits
+        n = lx * lz
+        # Calculate the number of stabilizers
+        m = (lx - 1) * (lz - 1) + lz // 2 + (lz - 1) // 2 + lx // 2 + (lx - 1) // 2
+
+        # Initialize sparse matrices for hx and hz using lil_matrix for efficient construction
+        hx = scipy.sparse.lil_matrix((m, n), dtype=int)
+        hz = scipy.sparse.lil_matrix((m, n), dtype=int)
+
+        # Fill the hx and hz matrices for the main grid
+        for j in range(lx - 1):
+            for k in range(lz - 1):
+                temp = j * (lz - 1)
+                # Set the X and Z stabilizers for the main grid
+                hx[temp + k, j * lz + k] = 1
+                hx[temp + k, j * lz + k + lz + 1] = 1
+
+                hz[temp + k, j * lz + k + 1] = 1
+                hz[temp + k, j * lz + k + lz] = 1
+
+        # Add the extra stabilizers to the top of the lattice
+        temp = (lx - 1) * (lz - 1)
+        count = 0
+        for j in range(0, lz - 1, 2):
+            # Set the Z Pauli components
+            hz[temp + count, j] = 1
+            hz[temp + count, (n - 1) - (lz - 1) + 1 + j] = 1
+
+            # Set the X Pauli components
+            hx[temp + count, j + 1] = 1
+            hx[temp + count, (n - 1) - (lz - 1) + j] = 1
+
+            count += 1
+
+        # Add the extra stabilizers to the bottom of the lattice
+        temp = (lx - 1) * (lz - 1) + lz // 2
+        count = 0
+        for j in range(1, lz - 1, 2):
+            # Set the X Pauli components
+            hx[temp + count, j + 1] = 1
+            hx[temp + count, (n - 1) - (lz - 1) + j] = 1
+
+            # Set the Z Pauli components
+            hz[temp + count, j] = 1
+            hz[temp + count, (n - 1) - (lz - 1) + 1 + j] = 1
+
+            count += 1
+
+        # Add the extra stabilizers to the right of the lattice
+        temp = (lx - 1) * (lz - 1) + lz // 2 + (lz - 1) // 2
+        count = 0
+        for j in range(0, lx - 1, 2):
+            # Set the Z Pauli components
+            hz[temp + count, (j + 1) * lz + lz - 1] = 1
+            hz[temp + count, j * lz] = 1
+
+            # Set the X Pauli components
+            hx[temp + count, (j + 1) * lz] = 1
+            hx[temp + count, j * lz + lz - 1] = 1
+
+            count += 1
+
+        # Add the extra stabilizers to the left of the lattice
+        temp = (lx - 1) * (lz - 1) + lz // 2 + (lz - 1) // 2 + lx // 2
+        count = 0
+        for j in range(1, lx - 1, 2):
+            # Set the Z Pauli components
+            hz[temp + count, (j + 1) * lz + lz - 1] = 1
+            hz[temp + count, j * lz] = 1
+
+            # Set the X Pauli components
+            hx[temp + count, (j + 1) * lz] = 1
+            hx[temp + count, j * lz + lz - 1] = 1
+
+            count += 1
+
+        # Convert hx and hz to CSR format for efficient arithmetic operations and storage
+        hx = hx.tocsc()
+        hz = hz.tocsc()
+
+        # Combine the parity check matrices into a single stabilizer matrix
+        stabilizer_matrix = scipy.sparse.hstack([hx, hz]).tocsr()
+
+        # Initialize the StabilizerCode with the combined parity check matrix
+        super().__init__(stabilizer_matrix, name=f"Rotated XZZX ({lx}x{lz}) Code")