qec 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

qec/code_constructions/hgp_code.py

@@ -0,0 +1,264 @@
+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
+
+class HypergraphProductCode(CSSCode):
+    """
+    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)
+    
+
+    def compute_exact_code_distance(self) -> int:
+        """
+        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.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.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}]]"
+
+

qec/{stabilizer_code → code_constructions}/stabilizer_code.py

@@ -45,7 +45,7 @@ class StabilizerCode(object):
         The number of logical qubits in the code.
     code_distance : int
         (Not computed by default) The distance of the code, if known or computed.
-    logicals : scipy.sparse.spmatrix or None
+    logical_operator_basis : scipy.sparse.spmatrix or None
         A basis for the logical operators of the code.
     """
 
@@ -177,7 +177,7 @@ class StabilizerCode(object):
         kernel_h = ldpc.mod2.kernel(self.stabilizer_matrix)
 
         # Sort the rows of the kernel by weight
-        row_weights = np.diff(kernel_h.indptr)
+        row_weights = kernel_h.getnnz(axis=1)
         sorted_rows = np.argsort(row_weights)
         kernel_h = kernel_h[sorted_rows, :]
 
@@ -377,166 +377,64 @@ class StabilizerCode(object):
         """
         return f"< Stabilizer Code, Name: {self.name}, Parameters: [[{self.physical_qubit_count}, {self.logical_qubit_count}, {self.code_distance}]] >"
 
-    def reduce_logical_operator_basis(
-        self,
-        candidate_logicals: Union[Sequence, np.ndarray, scipy.sparse.spmatrix] = [],
-    ):
-        """
-        Reduce the logical operator basis to include lower-weight logicals.
-
-        Parameters
-        ----------
-        candidate_logicals : Union[Sequence, np.ndarray, scipy.sparse.spmatrix], optional
-            A list or array of candidate logical operators to be considered for reducing the basis.
-            Defaults to an empty list.
-        """
-        if len(candidate_logicals) != 0:
-            # Convert candidates to a sparse matrix if they aren't already
-            if not isinstance(candidate_logicals, scipy.sparse.spmatrix):
-                candidate_logicals = scipy.sparse.csr_matrix(
-                    scipy.sparse.csr_matrix(candidate_logicals)
-                )
-
-            # Stack the candidate logicals with the existing logicals
-            temp1 = scipy.sparse.vstack(
-                [candidate_logicals, self.logical_operator_basis]
-            ).tocsr()
-
-            # Compute the Hamming weight over GF4 (number of qubits with non-identity operators)
-            # Split into X and Z parts
-            row_weights = binary_pauli_hamming_weight(temp1).flatten()
-
-            # Sort the rows by Hamming weight (ascending)
-            sorted_rows = np.argsort(row_weights)
-            temp1 = temp1[sorted_rows, :]
-
-            # Add the stabilizer matrix to the top of the stack
-            temp1 = scipy.sparse.vstack([self.stabilizer_matrix, temp1])
-
-            # Calculate the rank of the stabilizer matrix (todo: find way of removing this step)
-            stabilizer_rank = ldpc.mod2.rank(self.stabilizer_matrix)
-
-            # Perform row reduction to find a new logical basis
-            p_rows = ldpc.mod2.pivot_rows(temp1)
-            self.logical_operator_basis = temp1[p_rows[stabilizer_rank:]]
-
     def estimate_min_distance(
         self,
         timeout_seconds: float = 0.25,
         p: float = 0.25,
-        max_iter: int = 10,
-        error_rate: float = 0.1,
-        bp_method: str = "ms",
-        schedule: str = "parallel",
-        ms_scaling_factor: float = 1.0,
-        osd_method: str = "osd_0",
-        osd_order: int = 0,
         reduce_logical_basis: bool = False,
+        decoder: Optional[BpOsdDecoder] = None,
     ) -> int:
         """
         Estimate the minimum distance of the stabilizer code using a BP+OSD decoder-based search.
 
         Parameters
         ----------
-        timeout_seconds : float, optional
-            The time limit (in seconds) for searching random linear combinations.
-        p : float, optional
-            Probability used to randomly include or exclude each logical operator
-            when generating trial logical operators.
-        max_iter : int, optional
-            Maximum number of BP decoder iterations.
-        error_rate : float, optional
-            Crossover probability for the BP+OSD decoder.
-        bp_method : str, optional
-            Belief Propagation method (e.g., "ms" for min-sum).
-        schedule : str, optional
-            Update schedule for BP (e.g., "parallel").
-        ms_scaling_factor : float, optional
-            Scaling factor for min-sum updates.
-        osd_method : str, optional
-            Order-statistic decoding method (e.g., "osd_0").
-        osd_order : int, optional
-            OSD order.
-        reduce_logical_basis : bool, optional
-            If True, attempts to reduce the logical operator basis to include lower-weight operators.
+        timeout_seconds : float
+            Time limit in seconds for the search. Default: 0.25
+        p : float
+            Probability for including each logical operator in trial combinations. Default: 0.25
+        reduce_logical_basis : bool
+            Whether to attempt reducing logical operator basis. Default: False
+        decoder : Optional[BpOsdDecoder]
+            Pre-configured BP+OSD decoder. If None, initialises with default settings.
 
         Returns
         -------
         int
-            The best-known estimate of the code distance found within the time limit.
+            Best estimate of code distance found within time limit
         """
         if self.logical_operator_basis is None:
             self.logical_operator_basis = self.compute_logical_basis()
 
-        def decoder_setup():
-            # # Remove redundnant rows from stabilizer matrix
-            p_rows = ldpc.mod2.pivot_rows(self.stabilizer_matrix)
-            full_rank_stabilizer_matrix = self.stabilizer_matrix[p_rows]
-            # full_rank_stabilizer_matrix = self.stabilizer_matrix
-
-            # Build a stacked matrix of stabilizers and logicals
-            stack = scipy.sparse.vstack(
-                [full_rank_stabilizer_matrix, self.logical_operator_basis]
-            ).tocsr()
-
-            # Initial distance estimate from the current logicals
-
-            min_distance = np.min(
-                binary_pauli_hamming_weight(self.logical_operator_basis)
-            )
-
-            max_distance = np.max(self.logical_basis_weights())
-
-            # Set up BP+OSD decoder
-            bp_osd = BpOsdDecoder(
-                stack,
-                error_rate=error_rate,
-                max_iter=max_iter,
-                bp_method=bp_method,
-                schedule=schedule,
-                ms_scaling_factor=ms_scaling_factor,
-                osd_method=osd_method,
-                osd_order=osd_order,
-            )
-
-            return (
-                bp_osd,
-                stack,
-                full_rank_stabilizer_matrix,
-                min_distance,
-                max_distance,
-            )
-
-        # setup the decoder
+        # Initial setup of decoder and parameters
         bp_osd, stack, full_rank_stabilizer_matrix, min_distance, max_distance = (
-            decoder_setup()
+            self._setup_distance_estimation_decoder(decoder)
         )
 
-        # List to store candidate logical operators for basis reduction
+        # Initialize storage for candidate logicals and tracking
         candidate_logicals = []
+        weight_one_syndromes_searched = 0
 
-        # 2) Randomly search for better representatives of logical operators
+        # Main search loop
         start_time = time.time()
         with tqdm(total=timeout_seconds, desc="Estimating distance") as pbar:
-            weight_one_syndromes_searched = 0
             while time.time() - start_time < timeout_seconds:
+                # Update progress bar
                 elapsed = time.time() - start_time
-                # Update progress bar based on elapsed time
                 pbar.update(elapsed - pbar.n)
 
                 # Initialize an empty dummy syndrome
                 dummy_syndrome = np.zeros(stack.shape[0], dtype=np.uint8)
 
                 if weight_one_syndromes_searched < self.logical_operator_basis.shape[0]:
+                    # Try each logical operator individually first
                     dummy_syndrome[
                         full_rank_stabilizer_matrix.shape[0]
                         + weight_one_syndromes_searched
-                    ] = 1  # pick exactly one logical operator
+                    ] = 1
                     weight_one_syndromes_searched += 1
-
                 else:
                     # Randomly pick a combination of logical rows
-                    # (with probability p, set the corresponding row in the syndrome to 1)
                     while True:
                         random_mask = np.random.choice(
                             [0, 1],
@@ -550,7 +448,6 @@ class StabilizerCode(object):
                             dummy_syndrome[self.stabilizer_matrix.shape[0] + idx] = 1
 
                 candidate = bp_osd.decode(dummy_syndrome)
-
                 w = np.count_nonzero(
                     candidate[: self.physical_qubit_count]
                     | candidate[self.physical_qubit_count :]
@@ -558,44 +455,129 @@ class StabilizerCode(object):
 
                 if w < min_distance:
                     min_distance = w
-                if w < max_distance:
-                    if reduce_logical_basis:
-                        lc = np.hstack(
-                            [
-                                candidate[self.physical_qubit_count :],
-                                candidate[: self.physical_qubit_count],
-                            ]
-                        )
-                        candidate_logicals.append(lc)
-
-                # 3) If requested, reduce the logical operator basis to include lower-weight operators
+                if w < max_distance and reduce_logical_basis:
+                    lc = np.hstack(
+                        [
+                            candidate[self.physical_qubit_count :],
+                            candidate[: self.physical_qubit_count],
+                        ]
+                    )
+                    candidate_logicals.append(lc)
+
+                # Reduce logical operator basis if we have enough candidates
                 if (
                     len(candidate_logicals) >= self.logical_qubit_count
                     and reduce_logical_basis
                 ):
-                    self.reduce_logical_operator_basis(candidate_logicals)
+                    self._reduce_logical_operator_basis(candidate_logicals)
                     (
                         bp_osd,
                         stack,
                         full_rank_stabilizer_matrix,
                         min_distance,
                         max_distance,
-                    ) = decoder_setup()
+                    ) = self._setup_distance_estimation_decoder(decoder)
                     candidate_logicals = []
                     weight_one_syndromes_searched = 0
 
                 pbar.set_description(
-                    f"Estimating distance: min-weight found <= {min_distance}, basis weights: {self.logical_basis_weights()}"
+                    f"Estimating distance: min-weight found <= {min_distance}, "
+                    f"basis weights: {self.logical_basis_weights()}"
                 )
 
-        if reduce_logical_basis and len(candidate_logicals) > 0:
-            self.reduce_logical_operator_basis(candidate_logicals)
-            candidate_logicals = []
-            weight_one_syndromes_searched = 0
-            max_distance = np.max(self.logical_basis_weights())
+        # Final basis reduction if needed
+        if reduce_logical_basis and candidate_logicals:
+            self._reduce_logical_operator_basis(candidate_logicals)
 
-        # Update and return the estimated distance
         self.code_distance = min_distance
+        return min_distance
+
+    def _setup_distance_estimation_decoder(
+        self, decoder: Optional[BpOsdDecoder] = None
+    ) -> Tuple[BpOsdDecoder, scipy.sparse.spmatrix, scipy.sparse.spmatrix, int, int]:
+        """
+        Set up decoder and initial parameters.
+
+        Parameters
+        ----------
+        decoder : Optional[BpOsdDecoder]
+            Pre-configured decoder. If None, initialises with default settings.
+
+        Returns
+        -------
+        Tuple[BpOsdDecoder, scipy.sparse.spmatrix, scipy.sparse.spmatrix, int, int]
+            Returns (decoder, stack matrix, full rank stabilizer matrix, min distance, max distance)
+        """
+        # Remove redundant rows from stabilizer matrix
+        p_rows = ldpc.mod2.pivot_rows(self.stabilizer_matrix)
+        full_rank_stabilizer_matrix = self.stabilizer_matrix[p_rows]
+
+        # Build a stacked matrix of stabilizers and logicals
+        stack = scipy.sparse.vstack(
+            [full_rank_stabilizer_matrix, self.logical_operator_basis]
+        ).tocsr()
+
+        # Initial distance estimate from current logicals
+        min_distance = np.min(binary_pauli_hamming_weight(self.logical_operator_basis))
+        max_distance = np.max(self.logical_basis_weights())
+
+        # Set up BP+OSD decoder if not provided
+        if decoder is None:
+            decoder = BpOsdDecoder(
+                stack,
+                error_rate=0.1,
+                max_iter=10,
+                bp_method="ms",
+                schedule="parallel",
+                ms_scaling_factor=1.0,
+                osd_method="osd_0",
+                osd_order=0,
+            )
+
+        return decoder, stack, full_rank_stabilizer_matrix, min_distance, max_distance
+
+    def _reduce_logical_operator_basis(
+        self,
+        candidate_logicals: Union[Sequence, np.ndarray, scipy.sparse.spmatrix] = [],
+    ):
+        """
+        Reduce the logical operator basis to include lower-weight logicals.
+
+        Parameters
+        ----------
+        candidate_logicals : Union[Sequence, np.ndarray, scipy.sparse.spmatrix], optional
+            A list or array of candidate logical operators to be considered for reducing the basis.
+            Defaults to an empty list.
+        """
+        if len(candidate_logicals) != 0:
+            # Convert candidates to a sparse matrix if they aren't already
+            if not isinstance(candidate_logicals, scipy.sparse.spmatrix):
+                candidate_logicals = scipy.sparse.csr_matrix(
+                    scipy.sparse.csr_matrix(candidate_logicals)
+                )
+
+            # Stack the candidate logicals with the existing logicals
+            temp1 = scipy.sparse.vstack(
+                [candidate_logicals, self.logical_operator_basis]
+            ).tocsr()
+
+            # Compute the Hamming weight over GF4 (number of qubits with non-identity operators)
+            # Split into X and Z parts
+            row_weights = binary_pauli_hamming_weight(temp1).flatten()
+
+            # Sort the rows by Hamming weight (ascending)
+            sorted_rows = np.argsort(row_weights)
+            temp1 = temp1[sorted_rows, :]
+
+            # Add the stabilizer matrix to the top of the stack
+            temp1 = scipy.sparse.vstack([self.stabilizer_matrix, temp1])
+
+            # Calculate the rank of the stabilizer matrix (todo: find way of removing this step)
+            stabilizer_rank = ldpc.mod2.rank(self.stabilizer_matrix)
+
+            # Perform row reduction to find a new logical basis
+            p_rows = ldpc.mod2.pivot_rows(temp1)
+            self.logical_operator_basis = temp1[p_rows[stabilizer_rank:]]
 
     def logical_basis_weights(self):
         """

qec/code_instances/__init__.py

@@ -0,0 +1 @@
+from .five_qubit_code import FiveQubitCode

qec/{quantum_codes → code_instances}/five_qubit_code.py

@@ -1,4 +1,4 @@
-from qec.stabilizer_code.stabilizer_code import StabilizerCode
+from qec.code_constructions import StabilizerCode
 
 
 class FiveQubitCode(StabilizerCode):

qec/codetables_de/__init__.py

@@ -0,0 +1 @@
+from .codetables_de import CodeTablesDE

qec/{quantum_codes → codetables_de}/codetables_de.py

@@ -1,4 +1,4 @@
-from qec.stabilizer_code import StabilizerCode
+from qec.code_constructions import StabilizerCode
 from qec.utils.codetables_de_utils import get_codetables_de_matrix, pcm_to_csr_matrix
 
 

qec/utils/binary_pauli_utils.py

@@ -299,7 +299,9 @@ def symplectic_product(
     a = convert_to_binary_scipy_sparse(a)
     b = convert_to_binary_scipy_sparse(b)
 
-    assert (a.shape[1] == b.shape[1]), "Input matrices must have the same number of columns."
+    assert (
+        a.shape[1] == b.shape[1]
+    ), "Input matrices must have the same number of columns."
     assert a.shape[1] % 2 == 0, "Input matrices must have an even number of columns."
 
     n = a.shape[1] // 2

qec/utils/codetables_de_utils.py

@@ -1,4 +1,5 @@
 import logging
+
 # Suppress debug and info messages from urllib3 and requests libraries
 logging.getLogger("urllib3").setLevel(logging.WARNING)
 logging.getLogger("requests").setLevel(logging.WARNING)
@@ -9,6 +10,7 @@ import requests
 from bs4 import BeautifulSoup
 import json
 
+
 def get_codetables_de_matrix(q, n, k, output_json_path=None, write_to_file=False):
     """
     Retrieve quantum code data from Markus Grassl's codetables.de website.