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

qec/utils/load_code_util.py

@@ -0,0 +1,142 @@
+import json
+from typing import Union
+import inspect
+from pathlib import Path
+from qec.utils.sparse_binary_utils import dict_to_binary_csr_matrix
+import qec.code_constructions
+
+
+def load_code(filepath: Union[str, Path]):
+    """
+    Loads a quantum error correction code from a JSON file.
+
+    Parameters
+    ----------
+    filepath : Union[str, Path]
+        Path to JSON file containing code data
+
+    Returns
+    -------
+    object
+        An instance of the quantum error correction code class.
+
+    Raises
+    ------
+        FileNotFoundError
+            If the specified file does not exist.
+        ValueError
+            If the input file is missing the 'class_name' key.
+        AttributeError
+            If the specified class does not exist in qec.code_constructions.
+    """
+
+    file_path = Path(filepath)
+    if not file_path.exists():
+        raise FileNotFoundError(
+            f"Error: No file found at the specified path: {file_path}"
+        )
+
+    with open(file_path, "r") as file:
+        code_data = json.load(file)
+
+    if "class_name" not in code_data:
+        raise ValueError(
+            "Error: The input JSON file must contain a 'class_name' key specifying the class to instantiate."
+        )
+
+    try:
+        class_reference = eval(
+            f"qec.code_constructions.{code_data['class_name']}", {"qec": qec}
+        )
+    except AttributeError:
+        raise AttributeError(
+            f"Error: The specified class '{code_data['class_name']}' does not exist in qec.code_constructions."
+        )
+
+    constructor_parameters = inspect.signature(
+        class_reference.__init__
+    ).parameters.keys()
+    filtered_input_parameters = {}
+
+    for key, value in code_data.items():
+        if key in constructor_parameters:
+            if isinstance(value, dict) and all(
+                k in value for k in ["indices", "indptr", "shape"]
+            ):
+                filtered_input_parameters[key] = dict_to_binary_csr_matrix(
+                    value
+                )  # Convert sparse matrix
+            else:
+                filtered_input_parameters[key] = value  # Keep as-is if not a matrix
+
+    # Instantiate the class
+    code_instance = class_reference(**filtered_input_parameters)
+
+    # Add extra attributes from JSON that are valid class attributes but not constructor parameters
+    class_attributes = dir(code_instance)
+    for key, value in code_data.items():
+        if key not in constructor_parameters and key in class_attributes:
+            if isinstance(value, dict) and all(
+                k in value for k in ["indices", "indptr", "shape"]
+            ):
+                value = dict_to_binary_csr_matrix(value)  # Convert sparse matrix
+            else:
+                pass
+
+            if (not isinstance(value, str) or value != "?") and value is not None:
+                setattr(code_instance, key, value)
+
+    return code_instance
+
+
+def load_code_from_id(code_id: int):
+    """
+    Load a quantum error correction code from a JSON file based on its ID from the package data.
+
+    The code files are packaged as data in the directory:
+        qec/code_instances/saved_codes
+    and are named as f"{code_id}.json".
+
+    Parameters
+    ----------
+    code_id : int
+        The identifier of the saved code.
+
+    Returns
+    -------
+    object
+        An instance of the quantum error correction code class loaded from the JSON data.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the JSON file corresponding to code_id is not found.
+    """
+    from importlib.resources import files, as_file
+    from importlib import import_module
+    from pathlib import Path
+
+    filename = f"{code_id}.json"
+    package = "qec.code_instances.saved_codes"
+    try:
+        pkg = import_module(package)
+        # If the package spec lacks an origin, fall back.
+        if pkg.__spec__ is None or pkg.__spec__.origin is None:
+            raise ImportError("Package spec origin not found; fallback to filesystem.")
+        resource = files(pkg).joinpath(filename)
+    except Exception:
+        # Fallback: construct the path relative to this file.
+        resource = (
+            Path(__file__).parent.parent / "code_instances" / "saved_codes" / filename
+        )
+
+    if not resource.is_file():
+        raise FileNotFoundError(
+            f"File '{filename}' does not exist in package data at '{package}' "
+            f"or via fallback path '{resource}'."
+        )
+
+    with as_file(resource) as resource_path:
+        if not resource_path.exists():
+            raise FileNotFoundError(f"File '{resource_path}' does not exist on disk.")
+        return load_code(resource_path)

qec/utils/sparse_binary_utils.py

@@ -0,0 +1,80 @@
+import numpy.typing
+import numpy as np
+import scipy.sparse
+
+
+def convert_to_binary_scipy_sparse(
+    matrix: numpy.typing.ArrayLike,
+) -> scipy.sparse.csr_matrix:
+    """
+    Convert and validate a matrix as a sparse binary matrix in CSR format.
+
+    This function checks whether all elements of the input matrix are binary (0 or 1).
+    If the input is not already a sparse matrix, it converts it to a CSR (Compressed Sparse Row) matrix.
+
+    Parameters
+    ----------
+    matrix : array-like
+        Input matrix of shape (M, N). Can be a dense array-like or any SciPy sparse matrix format.
+
+    Returns
+    -------
+    scipy.sparse.csr_matrix
+        Binary sparse matrix in CSR format, of shape (M, N).
+
+    Raises
+    ------
+    ValueError
+        If the input matrix has elements outside {0, 1}.
+    TypeError
+        If the input is not array-like.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scipy.sparse import csr_matrix
+    >>> from qec.utils.sparse_binary_utils import convert_to_binary_scipy_sparse
+    >>> mat = np.array([[0, 1], [1, 0]])
+    >>> convert_to_binary_scipy_sparse(mat).toarray()
+    array([[0, 1],
+           [1, 0]])
+
+    >>> mat = csr_matrix([[0, 1], [1, 0]])
+    >>> convert_to_binary_scipy_sparse(mat).toarray()
+    array([[0, 1],
+           [1, 0]])
+
+    >>> mat = np.array([[0, 2], [1, 0]])
+    >>> convert_to_binary_scipy_sparse(mat)
+    Traceback (most recent call last):
+        ...
+    ValueError: All elements of the input matrix must be binary.
+    """
+    if not isinstance(matrix, (np.ndarray, list, scipy.sparse.spmatrix)):
+        raise TypeError("Input must be array-like.")
+
+    if not isinstance(matrix, scipy.sparse.csr_matrix):
+        matrix = scipy.sparse.csr_matrix(matrix, dtype=np.uint8)
+
+    if not matrix.dtype == np.uint8:
+        matrix = matrix.astype(np.uint8)
+
+    if not np.all(np.isin(matrix.data, [0, 1])):
+        raise ValueError("All elements of the input matrix must be binary.")
+
+    return matrix
+
+
+def binary_csr_matrix_to_dict(matrix: scipy.sparse.spmatrix):
+    return {
+        "indices": matrix.indices.tolist(),
+        "indptr": matrix.indptr.tolist(),
+        "shape": matrix.shape,
+    }
+
+
+def dict_to_binary_csr_matrix(csr_dict: dict):
+    return scipy.sparse.csr_matrix(
+        ([1] * len(csr_dict["indices"]), csr_dict["indices"], csr_dict["indptr"]),
+        shape=csr_dict["shape"],
+    )

{qec-0.3.0.dist-info → qec-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: qec
-Version: 0.3.0
+Version: 0.3.3
 Summary: Python Tools for Quantum Error Correction
 Author-email: Joschka Roffe <joschka@roffe.eu>, Tamas Noszko <T.K.Noszko@sms.ed.ac.uk>, Liam Veeder-Sweeney <L.D.Veeder-Sweeney@sms.ed.ac.uk>
 License: MIT License
@@ -34,13 +34,12 @@ Requires-Dist: numpy>=1.24.0
 Requires-Dist: scipy>=1.9.3
 Requires-Dist: requests
 Requires-Dist: beautifulsoup4
+Dynamic: license-file
+
+![qec_banner](https://github.com/user-attachments/assets/9f54ed76-f606-44ed-aa15-275695e45ea0)
 
-<h1>
-<p align="center">
-  <br>QEC
-</h1>
   <p align="center">
-    Python Tools for Quantum Error Correction
+    QEC: Python Tools for Quantum Error Correction
     <br />
     <a href="https://qec.codes/">Website</a>
     ·
@@ -54,8 +53,8 @@ Requires-Dist: beautifulsoup4
 
 # Features
 
-## Code constructions and fundamental analysis
-We currently provide the construction methods for the stabilizer generators of the QEC code families below, along with optimized methods to obtain their fundamental properties. All the classes allow to:
+## Base functionality: code constructions and "fundamental" analysis
+We currently provide the construction methods for the stabilizer generators of the QEC code families below, along with optimized methods to obtain their fundamental properties. All the classes allow you to:
 
 - obtain the physical qubit count
 - obtain the logical qubit count
@@ -63,11 +62,18 @@ We currently provide the construction methods for the stabilizer generators of t
 - estimate the minimum code distance
 - obtain a logical basis
 
-The classes (along with their extre methods) are:
+The classes (along with their extra methods) are:
 
 - Hyperprgarph Product (HGP) codes, with methods:
   - construct the x and z stabiliser matrices from the seed codes
   - obtain the canonical basis (work in progress)
+ 
+- Surface codes
+  - Unrotated Surface code
+  - Periodic Surface XZZX code
+  - Rotated Surface XZZX code
+ 
+- Toric code
     
 - Calderbank-Shor-Steane (CSS) codes
   - check that the seed codes satisfy the CSS criteria
@@ -75,8 +81,24 @@ The classes (along with their extre methods) are:
 - Stabiliser codes
   - check that the input stabiliser matrix is valid
 
-## Circuit compilation
-Work in progress.
+## Circuit compilation 
+
+>
+> _Note:_ this functionality is still work in progress. The corresponding code is not part of the `main` branch - you can find it on the `circuit_compilation` branch to play around.  
+>
+
+Currently we only support circuit compilation for memory experiments of:
+
+- HGP codes with:
+  - "coloration circuit" stabilizer schedule (twice the depth of the most optimal "cardinal circuit" method)
+  - _under development:_ "cardinal circuit" stabilizer schedule
+
+One can either compile noisy or noisless circuits (for further compilation to one's own needs). To create a nosiy circuit one needs to construct their own noise model, or use one of the available presets:
+- `uniform_depolarizing_noise` 
+- `non_uniform_depolarizing_noise` under development 
+- `phenomenological_noise` 
+
+For a more detailed example please see the `demo.ipynb` [notebook](https://github.com/qec-codes/qec/blob/circuit_compilation/demo/demo.ipynb), inside the `demo/` folder of the `circuit_compilation` branch.
 
 # Installation 
 
@@ -98,18 +120,10 @@ Finally, install the package:
 pip install -e .
 ```
 
-You are all set! To import the package use:
-
-```python
-In  [1]: import qec
-
-In  [2]: qec.__version__
-Out [2]: '0.1.0'
-
-```
-
 # Examples
 
+## Base functionality:
+
 In this example we are going to create the Steane code, and obtain its fundamental code properties. We start by initialising its seed matrices (the [7, 4, 3] Hamming code):
 ```python
 In [1]: import numpy as np
@@ -125,11 +139,13 @@ as the Steane code is part of the CSS code family, we can use the `CSSCode` clas
 In [4]: steane_code = CSSCode(x_stabilizer_matrix = hamming_code,
                               z_stabilizer_matrix = hamming_code,
                               name = "Steane")
-In [5]: print(steane_code)
-Out [6]: Steane Code: [[N=7, K=1, dx<=3, dz<=3]]
+In [5]: steane_code.compute_exact_code_distance()
+In [6]: print(steane_code)
+
+Out [7]: Steane Code: [[N=7, K=1, dx<=3, dz<=3]]
 ```
 
-we can see that all the fundamental properties (N - physical qubit number, K - logical qubit number, dx - X distance, dz - Z distance) are pre-calculated for us. We can continue our analysis by taking a look at the x and z logical basis of the code: 
+we can see that all the fundamental properties (N - physical qubit number, K - logical qubit number, dx - X distance, dz - Z distance). We can continue our analysis by taking a look at the x and z logical basis of the code: 
 
 ```python
 In [7]: print(steane_code.x_logical_operator_basis.toarray())
@@ -138,6 +154,21 @@ In [9]: print(steane_code.z_logical_operator_basis.toarray())
 Out [10]: [[1 1 0 1 0 0 0]]
 ```
 
+## Circuit compilation:
+
+```python
+In [10]: from qec.code_constructions import HypergraphProductCode
+In [11]: from qec.circuit_compilation import MemoryExperiment
+
+In [12]: hgp_example_code = HypergraphProductCode(hamming_code, hamming_code)
+
+In [12]: hgp_memory_example = MemoryExperiment(hgp_example_code)
+
+In [13]: hgp_X_mem_circuit = hgp_memory_example.circuit(basis = 'X', rounds = 1, noise = False)
+```
+
+To see the output circuit and a more detailed example (including a simulation) see the `demo.ipynb` [notebook](https://github.com/qec-codes/qec/blob/circuit_compilation/demo/demo.ipynb), inside the `demo/` folder of the `circuit_compilation` branch.
+
                               
 
 

qec-0.3.3.dist-info/RECORD

@@ -0,0 +1,27 @@
+qec/__init__.py,sha256=daEdpEyAJIa8b2VkCqSKcw8PaExcB6Qro80XNes_sHA,2
+qec/code_constructions/__init__.py,sha256=Jg7aUTYaTuFnLGcpqPmc7iSQeM6Kwi_p9eUQBLNvePQ,600
+qec/code_constructions/css_code.py,sha256=e4X6QMnZ_xHdZENsaqrfFe-tl0XgEHvm7Fw2yBM3low,38614
+qec/code_constructions/hgp_code.py,sha256=FqghbZ6mQIBlQIJwhaPU_Zb1LjnmHBS_PGtQVNPl_mA,12310
+qec/code_constructions/periodic_surface_xzzx.py,sha256=iF95s-py85ivELlCiL5oEWe87OUVaKI3r4mJjaKy_-o,3551
+qec/code_constructions/rotated_xzzx.py,sha256=wSWH9H1AaNn_Yyhnr_NSvZdlo_sV9HW5JHFcBrjAnQY,4400
+qec/code_constructions/stabilizer_code.py,sha256=InPbSrqzMxueMQaFbUt-ytDHCWIzgIddnlAwYegpRFg,24258
+qec/code_constructions/surface_code.py,sha256=s49uyMZPRjOwBqpfLeB5Dl38O8w7BP8Y1tBemFhyDr0,2561
+qec/code_constructions/toric_code.py,sha256=Q8f3jU80gwsjqRVtp2tBuO6yRltQI5KeD49xQm8vuAw,1952
+qec/code_instances/__init__.py,sha256=5T_Qw26-cQc5BC6RM23_oDAYRdB3UPU5MeCGPxsoSRs,79
+qec/code_instances/five_qubit_code.py,sha256=ZHyusTEnnnmUv4QxPLXQSKbEQv2QOoBqn2V9N4SgrQE,2177
+qec/code_instances/saved_codes/1.json,sha256=PEErxvbeDupmZ4woHxC6EGAaRxfZ34fb4cOpBkfHvrs,850
+qec/code_instances/saved_codes/2.json,sha256=Dwp5XT65s9Wu51WFJjzNzkP5WYLcVPkVoIpfLb92PMM,2920
+qec/code_instances/saved_codes/3.json,sha256=3FeCj54tl708TeEsaChb_qqr92kw4_9S1wf4VASN-5U,4687
+qec/code_instances/saved_codes/4.json,sha256=H4ktJy02VGPxqSAZkjam1HMlPex2KjmbcG9CBdP4NhI,5452
+qec/codetables_de/__init__.py,sha256=_BQq4cIgZHbGPsA6qsJnMJ-B5eHqiYvUKbSubmJP8jA,68
+qec/codetables_de/codetables_de.py,sha256=4tkoHtr4VXHm0qY9r397EUhxFXR1Mp6DqqtfblGyzbw,3725
+qec/utils/__init__.py,sha256=lSkUeUQhk2KU8EgH63jSehwAMHQAJ3XBDmmRIKXRuN8,123
+qec/utils/binary_pauli_utils.py,sha256=Vtqw-wWlOmrj2CDDhjjNmgUZHe5TJ2bU5-c_pV_Q4ks,13280
+qec/utils/codetables_de_utils.py,sha256=Qbk2y-4sMufSrgQyuC6pDBOteeC3By_BiykVz4mIL7o,9467
+qec/utils/load_code_util.py,sha256=w4icqtSKvEiA9JuFAc1AdkCt31dDC-SYK4-d4G4YfAY,4642
+qec/utils/sparse_binary_utils.py,sha256=02qxK1iC_8jFIeuH1vjSd_3OwuKT5wWsVBshklc2IIA,2397
+qec-0.3.3.dist-info/licenses/LICENSE,sha256=1b_xwNz1znYBfEaCL6pN2gNBAn8pQIjDRs_UhDp1EJI,1066
+qec-0.3.3.dist-info/METADATA,sha256=r6ZBxOp3OYOhSOvjah90naZqy93BQcnHUpqIgfJpLoU,6392
+qec-0.3.3.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+qec-0.3.3.dist-info/top_level.txt,sha256=d8l_7pJ5u9uWdviNp0FUK-j8VPZqywkDek7qa4NDank,4
+qec-0.3.3.dist-info/RECORD,,

{qec-0.3.0.dist-info → qec-0.3.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (80.3.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

qec/code_instances/saved_codes/steane.json

@@ -1,34 +0,0 @@
-{
-    "class_name": "CSSCode",
-    "name": "Steane",
-    "physical_qubit_count": 7,
-    "logical_qubit_count": 1,
-    "code_distance": 3,
-    "x_code_distance": 3,
-    "z_code_distance": 3,
-    "x_stabilizer_matrix": {
-        "data": [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
-        "indices": [0, 3, 5, 6, 1, 3, 4, 6, 2, 4, 5, 6],
-        "indptr": [0, 4, 8, 12],
-        "shape": [3, 7]
-    },
-    "z_stabilizer_matrix": {
-        "data": [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
-        "indices": [0, 3, 5, 6, 1, 3, 4, 6, 2, 4, 5, 6],
-        "indptr": [0, 4, 8, 12],
-        "shape": [3, 7]
-    },
-    "x_logical_operator_basis": {
-        "data": [1, 1, 1],
-        "indices": [0, 1, 3],
-        "indptr": [0, 3],
-        "shape": [1, 7]
-    },
-    "z_logical_operator_basis": {
-        "data": [1, 1, 1],
-        "indices": [0, 1, 3],
-        "indptr": [0, 3],
-        "shape": [1, 7]
-    },
-    "notes": "this is a test note"
-}

qec/code_instances/saved_codes/test.json

@@ -1 +0,0 @@
-{"hello": "world"}

qec-0.3.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-qec/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-qec/code_instances/saved_codes/1.json,sha256=whH698pYdPARAVomZOxoYerwW0IzaCOavL5KMIFuB9Y,1616
-qec/code_instances/saved_codes/steane.json,sha256=Hx6TqeE8KHOL189fJG4eIekiuQvVLcltjbOCsN1mEPQ,930
-qec/code_instances/saved_codes/test.json,sha256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE,18
-qec-0.3.0.dist-info/LICENSE,sha256=1b_xwNz1znYBfEaCL6pN2gNBAn8pQIjDRs_UhDp1EJI,1066
-qec-0.3.0.dist-info/METADATA,sha256=FTk3YvEROBX7QuNFBAwjVkUVBs6mhED0j71y0W2jQMQ,4611
-qec-0.3.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-qec-0.3.0.dist-info/top_level.txt,sha256=d8l_7pJ5u9uWdviNp0FUK-j8VPZqywkDek7qa4NDank,4
-qec-0.3.0.dist-info/RECORD,,