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

qec/code_constructions/surface_code.py

@@ -0,0 +1,66 @@
+import ldpc.codes.rep_code
+
+import ldpc.codes
+from qec.code_constructions import HypergraphProductCode
+
+
+class SurfaceCode(HypergraphProductCode):
+    """
+    Represents a Surface Code, which is a type of quantum error correction code.
+
+    The Surface Code is constructed using two repetition codes, one for the X stabilizers
+    and one for the Z stabilizers. The distances dx and dz specify the code distances
+    for the X and Z stabilizers, respectively, corresponding to the height and width of the lattice.
+
+    The Surface Code is a specific instance of a Hypergraph Product Code. The hypergraph product
+    construction allows for the creation of quantum error correction codes with desirable properties
+    such as high distance and low-weight stabilizers. In this construction, two classical codes are
+    used to generate the quantum code. For the Surface Code, these classical codes are simple repetition
+    codes.
+
+    Parameters
+    ----------
+    dx : int, optional
+        The code distance for the X stabilizers (width of the lattice). If not specified, it will be set to the value of dz.
+    dz : int, optional
+        The code distance for the Z stabilizers (height of the lattice). If not specified, it will be set to the value of dx.
+
+    Raises
+    ------
+    ValueError
+        If both dx and dz are not specified.
+
+    Attributes
+    ----------
+    x_code_distance : int
+        The code distance for X errors.
+    z_code_distance : int
+        The code distance for Z errors.
+    code_distance : int
+        The minimum of x_code_distance and z_code_distance.
+
+    Notes
+    -----
+    The Surface Code is constructed using the hypergraph product of two repetition codes. The repetition
+    code is a simple classical code where each bit is repeated multiple times to provide redundancy. By
+    taking the hypergraph product of two such codes, we obtain a quantum code with stabilizers that are
+    low-weight and a code distance that is determined by the distances of the original repetition codes.
+    """
+
+    def __init__(self, dx: int = None, dz: int = None):
+        if dx is None and dz is None:
+            raise ValueError("Please specify dx or dz")
+        if dx is None:
+            dx = dz
+        if dz is None:
+            dz = dx
+
+        h1 = ldpc.codes.rep_code(dz)
+        h2 = ldpc.codes.rep_code(dx)
+
+        super().__init__(h1, h2, name=f"({dx}x{dz})-Surface Code")
+
+        self.x_code_distance = dx
+        self.z_code_distance = dz
+
+        self.code_distance = min(self.x_code_distance, self.z_code_distance)

qec/code_constructions/toric_code.py

@@ -0,0 +1,56 @@
+import ldpc.codes
+from qec.code_constructions import HypergraphProductCode
+
+
+class ToricCode(HypergraphProductCode):
+    """
+    Represents a Toric Code, which is a type of quantum error correction code.
+
+    The Toric Code is constructed using two ring codes, one for the X stabilizers
+    and one for the Z stabilizers. The distances dx and dz specify the code distances
+    for the X and Z stabilizers, respectively, corresponding to the height and width of the lattice.
+
+    The Toric Code is defined on a torus and is the generalization of the Surface Code with periodic
+    boundary conditions. The Toric Code has a logical qubit count of 2.
+
+    Parameters
+    ----------
+    dx : int, optional
+        The code distance for the X stabilizers (width of the lattice). If not specified, it will be set to the value of dz.
+    dz : int, optional
+        The code distance for the Z stabilizers (height of the lattice). If not specified, it will be set to the value of dx.
+
+    Raises
+    ------
+    ValueError
+        If both dx and dz are not specified.
+
+    Attributes
+    ----------
+    x_code_distance : int
+        The code distance the X errors.
+    z_code_distance : int
+        The code distance for Z errors.
+    code_distance : int
+        The minimum of x_code_distance and z_code_distance.
+    logical_qubit_count : int
+        The number of logical qubits in the code, which is 2 for the Toric Code.
+    """
+
+    def __init__(self, dx: int = None, dz: int = None):
+        if dx is None and dz is None:
+            raise ValueError("Please specify dx or dz")
+        if dx is None:
+            dx = dz
+        if dz is None:
+            dz = dx
+
+        h1 = ldpc.codes.ring_code(dz)
+        h2 = ldpc.codes.ring_code(dx)
+
+        super().__init__(h1, h2, name=f"({dx}x{dz})-Toric Code")
+
+        self.x_code_distance = dx
+        self.z_code_distance = dz
+
+        self.code_distance = min(self.x_code_distance, self.z_code_distance)

qec/code_instances/__init__.py

@@ -0,0 +1,5 @@
+from .five_qubit_code import FiveQubitCode
+
+__all__ = [
+    "FiveQubitCode",
+]

qec/code_instances/five_qubit_code.py

@@ -0,0 +1,67 @@
+from qec.code_constructions import StabilizerCode
+
+
+class FiveQubitCode(StabilizerCode):
+    """
+    Five-Qubit Quantum Error-Correcting Code.
+
+    The `FiveQubitCode` class implements the [[5, 1, 3]] quantum stabilizer code,
+    which is the smallest possible quantum error-correcting code capable of
+    correcting an arbitrary single-qubit error. This code encodes one logical
+    qubit into five physical qubits and has a distance of three, allowing it
+    to detect up to two errors and correct one.
+
+    Parameters
+    ----------
+    None
+
+    Attributes
+    ----------
+    code_distance : int
+        The distance of the quantum code. For the five-qubit code, this is set to 3.
+
+    Inherits
+    --------
+    StabilizerCode
+        The base class providing functionalities for stabilizer-based quantum
+        error-correcting codes, including initialization, distance computation,
+        and parameter retrieval.
+
+    Examples
+    --------
+    >>> five_qubit = FiveQubitCode()
+    >>> five_qubit.phyiscal_qubit_count
+    5
+    >>> five_qubit.logical_qubit_count
+    1
+    >>> five_qubit.code_distance
+    3
+    """
+
+    def __init__(self):
+        """
+        Initialize the Five-Qubit Code with predefined Pauli stabilizers.
+
+        The constructor sets up the stabilizer generators for the [[5, 1, 3]]
+        quantum code using their corresponding Pauli strings. It then calls the
+        superclass initializer to establish the stabilizer matrix and other
+        essential parameters.
+
+        Parameters
+        ----------
+        None
+
+        Raises
+        ------
+        ValueError
+            If the provided stabilizer generators do not satisfy the necessary
+            commutation relations required for a valid stabilizer code.
+        """
+        # Define the Pauli stabilizer generators for the five-qubit code
+        pauli_stabilizers = [["XZZXI"], ["IXZZX"], ["XIXZZ"], ["ZXIXZ"]]
+
+        # Initialize the StabilizerCode with the defined stabilizers and a custom name
+        super().__init__(stabilizers=pauli_stabilizers, name="5-Qubit Code")
+
+        # Set the distance attribute specific to the five-qubit code
+        self.code_distance = 3

qec/codetables_de/__init__.py

@@ -0,0 +1,3 @@
+from .codetables_de import CodeTablesDE
+
+__all__ = ["CodeTablesDE"]

qec/codetables_de/codetables_de.py

@@ -0,0 +1,97 @@
+import numpy as np
+from qec.code_constructions import StabilizerCode
+from qec.utils.codetables_de_utils import get_codetables_de_matrix, pcm_to_csr_matrix
+
+
+class CodeTablesDE(StabilizerCode):
+    """
+    A code object built from data obtained from Markus Grassl's codetables.de website (with `q=4`).
+
+    This class inherits from `StabilizerCode` and initialises the code
+    by querying the codetables.de website for the specified parameters `(n, k)`,
+    constructing the stabilizer (PCM) matrix, and passing it up to the
+    `StabilizerCode` parent class.
+
+    Parameters
+    ----------
+    physical_qubit_count : int
+        Length of the code (number of physical qubits).
+    logical_qubit_count : int
+        Dimension of the code (number of logical qubits).
+
+    Attributes
+    ----------
+    name : str
+        Name assigned to this code instance. Defaults to "CodeTablesDE".
+    url : str
+        The URL from which this code's data was retrieved.
+    code_distance : int
+        The code's minimum distance. This is updated if the reported upper bound
+        from the codetables.de website is smaller than the base class default.
+
+    See Also
+    --------
+    StabilizerCode : Parent class providing stabilizer code functionality.
+    get_codetables_de_matrix : Function that queries codetables.de to retrieve code data.
+    pcm_to_csr_matrix : Function that converts a PCM-like list of column indices into a CSR matrix.
+
+    Notes
+    -----
+    - The data is retrieved from:
+      https://codetables.de
+      maintained by Markus Grassl.
+    """
+
+    def __init__(self, physical_qubit_count: int, logical_qubit_count: int):
+        """
+        Initialise a code from Markus Grassl's codetables.de website with `q=4`, `n`, and `k`.
+
+        This method queries the codetables.de database for a stabilizer matrix
+        describing a code with parameters (q=4, n, k). The matrix is then
+        converted to a CSR (Compressed Sparse Row) format and passed to
+        the parent `StabilizerCode` class.
+
+        Parameters
+        ----------
+        n : int
+            Length of the code (number of physical qubits).
+        k : int
+            Dimension of the code (number of logical qubits).
+
+        Notes
+        -----
+        - `d_upper` from the query result is used to potentially update `self.code_distance`
+          if it is smaller than the default distance assigned by `StabilizerCode`.
+        - Since this code is defined over GF(4), `q` is hardcoded as 4.
+        - Data is retrieved from Markus Grassl's website (https://codetables.de).
+
+        Raises
+        ------
+        ValueError
+            If no valid matrix data can be retrieved from codetables.de, or
+            if the site indicates that such a code does not exist.
+        """
+        # Retrieve code data from codetables.de
+        ct_dict = get_codetables_de_matrix(
+            q=4, n=physical_qubit_count, k=logical_qubit_count
+        )
+
+        # Construct the stabilizer matrix in CSR format
+        # The matrix is 2*n columns wide, as is typical for GF(4) stabilizers.
+        stabilizer_matrix = pcm_to_csr_matrix(
+            ct_dict["pcm"], num_cols=2 * int(ct_dict["n"])
+        )
+
+        # Initialise the parent class with this stabilizer matrix
+        super().__init__(stabilizers=stabilizer_matrix)
+
+        # Name of this code and the URL from which we retrieved it
+        self.name = "CodeTablesDE"
+        self.url = ct_dict["url"]
+
+        # Update distance if the reported upper bound is smaller than the default
+        if self.code_distance is None:
+            self.code_distance = np.inf
+
+        if int(ct_dict["d_upper"]) < self.code_distance:
+            self.code_distance = int(ct_dict["d_upper"])

qec/utils/__init__.py

@@ -0,0 +1,6 @@
+from qec.utils.load_code_util import load_code, load_code_from_id
+
+__all__ = [
+    "load_code",
+    "load_code_from_id",
+]