updating docs

quantumgizmos · Jun 25, 2024 · 6d08223 · 6d08223
1 parent b31072f
commit 6d08223
Show file tree

Hide file tree

Showing 8 changed files with 136 additions and 606 deletions.
diff --git a/README.ipynb b/README.ipynb
diff --git a/README.md b/README.md
@@ -27,6 +27,7 @@ The documentation for `LDPCv2` can be found [here](https://roffe.eu/software/ldp
 - Stabiliser inactivation BP (https://arxiv.org/abs/2205.06125)
 - Generalised BP (https://arxiv.org/abs/2212.03214)
 - Functions need to be properly documented (in progress)
+- STIM integration
 - More functionality for studying classical codes. Eg. support for received vector decoding and the AWGN noise channel.
 - Proper test coverage is required (C++ has 100%, Python tests still need to expanded).
 
@@ -47,10 +48,10 @@ pip install -Ue .
 
 ## Installation from Test PyPi
 
-This package is currenlty hosted on TestPyPi. Installation requires Python>=3.8. To install, run the following `pip` commands.
+This package is currently hosted on TestPyPi. Installation requires Python>=3.8. To install, run the following `pip` commands.
 
 ```
-pip install -U numpy scipy tqdm pytest
+pip install -U numpy scipy tqdm pytest stim sinter BeliefMatching
 pip install -i https://test.pypi.org/simple/ ldpc
 ```
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,12 +1,9 @@
 import os
 import sys
 import ldpc
-import udlr
 ldpc_path = os.path.dirname(ldpc.__file__)
-udlr_path = os.path.dirname(udlr.__file__)
 
 sys.path.insert(0, ldpc_path )
-sys.path.insert(0, udlr_path )
 
 # Configuration file for the Sphinx documentation builder.
 #

diff --git a/docs/source/installation.md b/docs/source/installation.md
@@ -1,23 +1,25 @@
 # Setup
 
-## Installation from PyPi (recommended method)
+## Python - Installation from source
 
-Installtion from [PyPi](https://pypi.org/project/ldpc/) requires Python>=3.6.
-To install via pip, run:
+The C++ source code can be found in src_cpp. Python bindings are implemented using Cython and can be found in src/ldpc. To install the Python version of the repository follows the instructions below: 
+
+- Download the repo.
+- Navigate to the root.
+- Pip install with `python>=3.8`.
+Note: installation requires a `C` compiler. Eg. `gcc` on Linux or `clang` on Windows.
 
 ```
-pip install -U ldpc
+git clone git@github.com:quantumgizmos/ldpc_v2.git
+cd ldpc
+pip install -Ue .
 ```
 
-## Installation (from source)
+## Installation from Test PyPi
 
-Installation from source requires Python>=3.6 and a local C compiler (eg. 'gcc' in Linux or 'clang' in Windows). The LDPC package can then be installed by running:
+This package is currently hosted on TestPyPi. Installation requires Python>=3.8. To install, run the following `pip` commands.
 
 ```
-git clone https://github.com/quantumgizmos/ldpc.git
-cd ldpc
-pip install -e ldpc
-```
-
-## Dependencies
-This package makes use of the `mod2sparse` data structure from Radford Neal's [Software for Low Density Parity Check Codes](https://www.cs.toronto.edu/~radford/ftp/LDPC-2012-02-11/index.html) C package.
+pip install -U numpy scipy tqdm pytest stim sinter BeliefMatching
+pip install -i https://test.pypi.org/simple/ ldpc
+```
diff --git a/docs/source/quantum_decoder.ipynb b/docs/source/quantum_decoder.ipynb
@@ -15,14 +15,26 @@
     "\n",
     "The belief propagation + ordered statistics decoder (BP+OSD) is a modified version of BP that works well for quantum LDPC codes. An advantage of the BP+OSD decoder is that it always returns a decoding that satisfies the syndrome equation.\n",
     "\n",
-    "The `LDPC` implementation of BP+OSD inherits from the `ldpc.BpDecoder` class. The setup is therefore very similar, with only two extra parameters to specify the `osd_method` and the `osd_order`. An example is below:"
+    "The `LDPC` implementation of BP+OSD inherits from the `ldpc.BpDecoder` class. The setup is therefore very similar, with only two extra parameters to specify the `osd_method` and the `osd_order`. The `LDPCv2` package now includes an implementation of the fast-solve algorithm for `OSD_0`, which terminates the Gaussian elimination as soon as the syndrome becomes linearly dependent on the columns elimianted up to that point.\n",
+    "\n",
+    "An example is below:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 6,
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Syndrome: [1 0 1 1 1]\n",
+      "Decoding: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0]\n",
+      "Decoding syndrome: [1 0 1 1 1]\n"
+     ]
+    }
+   ],
    "source": [
     "import numpy as np\n",
     "import ldpc.codes\n",
@@ -37,7 +49,7 @@
     "            bp_method = 'product_sum',\n",
     "            max_iter = 7,\n",
     "            schedule = 'serial',\n",
-    "            osd_method = 'osd_cs',\n",
+    "            osd_method = 'osd_cs', #set to OSD_0 for fast solve\n",
     "            osd_order = 2\n",
     "        )\n",
     "\n",
@@ -50,17 +62,74 @@
     "print(f\"Decoding syndrome: {decoding_syndrome}\")\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Belief propagation + localized statistics decoding (BP+LSD)\n",
+    "\n",
+    "The belief propagation + localized statistics decoder (BP+LSD) is a parallel inversion-based decoder for quantum LDPC codes (see our paper https://arxiv.org/abs/2406.???). Similar to OSD, the LSD algorithm solves the decoding problem through matrix inversion. However, matrix inversion is performed on local error clusters rather than over the entire parity check matrix. This considerably speeds up decoding relative to BP+OSD for large parity check matrices. Higher-order reprocessing, using either the 'combination sweep' or 'exhaustive' strategy can also be performed locally for each cluster.\n",
+    "\n",
+    "An advantage of LSD (over OSD) is that the number of bp iterations (`BpDecoder.max_iter`) can be set to a small number (experiment with this, but we find ~30 usually suffices) without reducing runtime. The decoder then relies more on the post-processor, but this does not matter as the runtime of the LSD algorithm scales (roughly) with the error rate rather than the size of the parity check matrix (as is the case for BP+OSD).\n",
+    "\n",
+    "The `LDPC` implementation of BP+LSD inherits from the `ldpc.BpDecoder` class. The setup is therefore very similar, with only two extra parameters to specify the `lsd_method` and the `lsd_order`. Note that for higher-order reprocessing, `lsd_cs-w` and `osd_cs-w` are not entirely equivalent, so expect some differences. \n",
+    "\n",
+    "An example is below:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Syndrome: [0 1 0 1 1]\n",
+      "Decoding: [0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]\n",
+      "Decoding syndrome: [0 1 0 1 1]\n"
+     ]
+    }
+   ],
+   "source": [
+    "import numpy as np\n",
+    "import ldpc.codes\n",
+    "from ldpc.bplsd_decoder import BpLsdDecoder \n",
+    "\n",
+    "H = ldpc.codes.hamming_code(5)\n",
+    "\n",
+    "## The \n",
+    "bp_osd = BpLsdDecoder(\n",
+    "            H,\n",
+    "            error_rate = 0.1,\n",
+    "            bp_method = 'product_sum',\n",
+    "            max_iter = 2,\n",
+    "            schedule = 'serial',\n",
+    "            osd_method = 'lsd_cs', \n",
+    "            osd_order = 2\n",
+    "        )\n",
+    "\n",
+    "syndrome = np.random.randint(size=H.shape[0], low=0, high=2).astype(np.uint8)\n",
+    "\n",
+    "print(f\"Syndrome: {syndrome}\")\n",
+    "decoding = bp_osd.decode(syndrome)\n",
+    "print(f\"Decoding: {decoding}\")\n",
+    "decoding_syndrome = H@decoding % 2\n",
+    "print(f\"Decoding syndrome: {decoding_syndrome}\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "# Belief-find\n",
     "\n",
-    "The belief propagation + union-find decoder (belief-find) is an alternative to BP+OSD for decoding quantum LDPC codes. Belief-find first attempts to solve the decoding using belief propagation. If this fails, a union-find decoder is run as a post-processor using the output of BP to guide cluster growth. The `LDPC` package implements two versions of belief-find:\n",
+    "The belief propagation + union-find decoder (belief-find) is an alternative to BP+OSD/LSD for decoding quantum LDPC codes. Belief-find first attempts to solve the decoding using belief propagation. If this fails, a union-find decoder is run as a post-processor using the output of BP to guide cluster growth. The `LDPC` package implements two versions of belief-find:\n",
     "\n",
     "1) **Peeling belief-find**. This approach uses a peeling decoder to solve the local decoding problem in each cluster. Peeling uinon-find is limited to decoding codes that have point like syndromes. e.g, the surface and toric codes. The peeling version of union-find decoder was first proposed by Delfosse & Nickerson in (https://arxiv.org/abs/1709.06218). Peeling belief-find was first proposed and implemented by Oscar Higgott (https://arxiv.org/abs/2203.04948).\n",
     "\n",
-    "2) **Cluster-inversion belief-find**. This approach solves the local decoding problem on each cluster using matrix inverison. Cluster-inversion union find can be applied to any quantum LDPC code. Matrix inversion find was first proposed by Delfosse et al. (https://arxiv.org/abs/2103.08049), and later improved by Berent et al. (https://arxiv.org/abs/2209.01180). As far as I am aware, the `LDPCv2` has the first implementation of cluster-inversion belief-find.\n",
+    "2) **Cluster-inversion belief-find**. This approach solves the local decoding problem on each cluster using matrix inverison. Cluster-inversion union find can be applied to any quantum LDPC code. Matrix inversion find was first proposed by Delfosse et al. (https://arxiv.org/abs/2103.08049), and later improved by Berent et al. (https://arxiv.org/abs/2209.01180). \n",
     "\n",
     "The `LDPC` implementation of belief-find inherits from the `ldpc.BpDecoder` class.\n",
     "\n",
@@ -69,16 +138,16 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Syndrome: [1 0 0 1 0]\n",
-      "Decoding: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0]\n",
-      "Decoding syndrome: [1 0 0 1 0]\n"
+      "Syndrome: [0 0 1 0 1]\n",
+      "Decoding: [0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]\n",
+      "Decoding syndrome: [0 0 1 0 1]\n"
      ]
     }
    ],
@@ -118,7 +187,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -143,15 +212,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Decoding: [0 0 0 1 0 1 0 1 0 1 0 0 0 0 1]\n",
-      "Decoding syndrome: [0 0 1 1 1 1 1 1 1 1 0 0 0 1 1]\n"
+      "Decoding: [1 0 1 0 0 0 1 0 0 1 1 0 0 1 0]\n",
+      "Decoding syndrome: [1 1 1 0 0 1 1 0 1 0 1 0 1 1 1]\n"
      ]
     }
    ],
@@ -164,13 +233,6 @@
     "decoding_syndrome = H@decoding % 2\n",
     "print(f\"Decoding syndrome: {decoding_syndrome}\")"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
@@ -189,7 +251,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.10.13"
   }
  },
  "nbformat": 4,

diff --git a/python_test/test_qcodes.py b/python_test/test_qcodes.py
@@ -104,12 +104,12 @@ def test_400_16_6_hgp():
     ler, min_logical, speed, _ = quantum_mc_sim(hx, lx, error_rate, run_count, seed, decoder,
                                                 f"Min-sum LSD-0 parallel schedule")
 
-    decoder = BpLsdDecoder(hx, error_rate=error_rate, max_iter=5, bp_method="ms", ms_scaling_factor=0.625,
-                           schedule="parallel", lsd_order=osd_order, lsd_method="osd_cs")
-    decoder.set_do_stats(True)
+    decoder = BpLsdDecoder(hx, error_rate=error_rate, max_iter=max_iter, bp_method="ms", ms_scaling_factor=0.625,
+                           schedule="parallel", lsd_order=osd_order, lsd_method="lsd_cs")
+    # decoder.set_do_stats(True)
     ler, min_logical, speed, _ = quantum_mc_sim(hx, lx, error_rate, run_count, seed, decoder,
                                                 f"Min-sum LSD-{osd_order} parallel schedule")
-    print(json.dumps(decoder.statistics))
+    # print(json.dumps(decoder.statistics))
 
 def test_toric_20():
     hx = scipy.sparse.load_npz("python_test/pcms/hx_toric_20.npz")

diff --git a/src_python/ldpc/bplsd_decoder/__init__.pyi b/src_python/ldpc/bplsd_decoder/__init__.pyi
@@ -34,13 +34,13 @@ class BpLsdDecoder(BpDecoderBase):
     serial_schedule_order : Optional[List[int]], optional
         A list of integers specifying the serial schedule order. Must be of length equal to the block length of the code,
         by default None.
-    bits_per_step : int, optional, NotImplemented
+    bits_per_step : int, optional
         Specifies the number of bits added to the cluster in each step of the LSD algorithm. If no value is provided, this is set the block length of the code.
     lsd_order: int, optional
-        The order of the OSD algorithm applied to each cluster. Must be greater than or equal to 0, by default 0.
-    lsd_method: OsdMethod
-        The OSD method of the OSD algorithm applied to each cluster. Must be one of {'OSD_0', 'OSD_E', 'OSD_CS'}.
-        By default 'OSD_0'.
+        The order of the LSD algorithm applied to each cluster. Must be greater than or equal to 0, by default 0.
+    lsd_method: str, optional
+        The LSD method of the LSD algorithm applied to each cluster. Must be one of {'LSD_0', 'LSD_E', 'LSD_CS'}.
+        By default 'LSD_0'.
     Notes
     -----
     The `BpLsdDecoder` class leverages soft information outputted by the BP decoder to guide the cluster growth
@@ -109,12 +109,12 @@ class BpLsdDecoder(BpDecoderBase):
     @property
     def lsd_method(self) -> Optional[str]:
         """
-        The Ordered Statistic Decoding (OSD) method used.
+        The Localized Statistic Decoding (LSD) method used.
 
         Returns
         -------
         Optional[str]
-            A string representing the OSD method used. Must be one of {'OSD_0', 'OSD_E', 'OSD_CS'}. If no OSD method
+            A string representing the LSD method used. Must be one of {'LSD_0', 'LSD_E', 'LSD_CS'}. If no LSD method
             has been set, returns `None`.
         """
 
@@ -127,8 +127,8 @@ class BpLsdDecoder(BpDecoderBase):
         Parameters
         ----------
         method : Union[str, int, float]
-            A string, integer or float representing the OSD method to use. Must be one of {'OSD_0', 'OSD_E', 'OSD_CS'}, corresponding to
-            OSD order-0, OSD Exhaustive or OSD-Cominbation-Sweep.
+            A string, integer or float representing the OSD method to use. Must be one of {'LSD_0', 'LSD_E', 'LSD_CS'}, corresponding to
+            LSD order-0, LSD Exhaustive or LSD-Cominbation-Sweep.
         """