Update surface code demo (#1834)

drdren · web-flow · commit 2a447e47193f · 2026-07-14T15:53:47.000-04:00
### Before submitting Please complete the following checklist when submitting a PR: - [ ] Ensure that your tutorial executes correctly, and conforms to the guidelines specified in the [README](https://github.com/PennyLaneAI/demos/blob/master/README.md). - [ ] Remember to do a grammar check of the content you include. - [ ] All tutorials conform to [PEP8 standards](https://www.python.org/dev/peps/pep-0008/). To auto format files, simply `pip install black`, and then run `black -l 100 path/to/file.py`. When all the above are checked, delete everything above the dashed line and fill in the pull request template. ------------------------------------------------------------------------------------------------------------ **Title:** **Summary:** **Relevant references:** **Possible Drawbacks:** **Related GitHub Issues:** ---- If you are writing a demonstration, please answer these questions to facilitate the marketing process. * GOALS — Why are we working on this now? *Eg. Promote a new PL feature or show a PL implementation of a recent paper.* * AUDIENCE — Who is this for? *Eg. Chemistry researchers, PL educators, beginners in quantum computing.* * KEYWORDS — What words should be included in the marketing post? * Which of the following types of documentation is most similar to your file? (more details [here](https://www.notion.so/xanaduai/Different-kinds-of-documentation-69200645fe59442991c71f9e7d8a77f8)) - [ ] Tutorial - [ ] Demo - [ ] How-to
diff --git a/demonstrations_v2/intro_to_surface_code/demo.py b/demonstrations_v2/intro_to_surface_code/demo.py
@@ -4,7 +4,7 @@
 ============================
 
 The surface code is the gold standard for deploying `quantum error correction (QEC) <https://pennylane.ai/codebook/quantum-error-correction>`__ on hardware today. 
-Not only does it provide a high circuit-level :doc:`error threshold <demos/tutorial_ft_threshold>` (around 1%), but it only requires local connectivity, making it amenable to hardware with 2D nearest-neighbor connectivity, such as :doc:`superconducting qubits <demos/tutorial_sc_qubits>`.
+Not only does it provide a high circuit-level :doc:`error threshold <demos/tutorial_fault_tolerant_threshold>` (around 1%), but it only requires local connectivity, making it amenable to hardware with 2D nearest-neighbor connectivity, such as :doc:`superconducting qubits <demos/tutorial_sc_qubits>`.
 
 Beyond it being a fully-functioning QEC code, it serves as a great introduction to the world of `fault-tolerant quantum computing (FTQC) <https://pennylane.ai/topics/fault-tolerant-quantum-computing>`__,
 because its working principles are ubiquitous in most modern QEC codes such as :doc:`qLDPC codes <demos/tutorial_qldpc_codes>` that break the locality requirement and are more qubit efficient. 
diff --git a/demonstrations_v2/intro_to_surface_code/metadata.json b/demonstrations_v2/intro_to_surface_code/metadata.json
@@ -7,11 +7,13 @@
     ],
     "executable_stable": true,
     "executable_latest": true,
-    "dateOfPublication": "2026-07-17T00:00:00+00:00",
-    "dateOfLastModification": "2026-07-09T00:00:00+00:00",
+    "dateOfPublication": "2026-07-14T00:00:00+00:00",
+    "dateOfLastModification": "2026-07-14T00:00:00+00:00",
     "categories": [
         "Quantum Computing",
-        "FTQC"
+        "FTQC",
+        "Quantum Computing",
+        "Quantum Hardware"
     ],
     "tags": [],
     "previewImages": [
diff --git a/demonstrations_v2/tutorial_active_volume/demo.py b/demonstrations_v2/tutorial_active_volume/demo.py
@@ -13,7 +13,7 @@
 
 For readers unfamiliar with ZX-diagrams, it will be useful (but not necessary) to take a look at
 our :doc:`introduction to ZX-calculus <demos/tutorial_zx_calculus>` first.
-Further, it can be instructive to get a primer on :doc:`the surface code <demos/surface_code>`, :doc:`lattice surgery <demos/tutorial_lattice_surgery>`
+Further, it can be instructive to get a primer on :doc:`the surface code <demos/intro_to_surface_code>`, :doc:`lattice surgery <demos/tutorial_lattice_surgery>`
 and dive into the :doc:`Game of Surface Codes <demos/tutorial_game_of_surface_codes>`, but this
 is not a requirement either.
 
diff --git a/demonstrations_v2/tutorial_active_volume/metadata.json b/demonstrations_v2/tutorial_active_volume/metadata.json
@@ -11,7 +11,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2026-01-21T10:00:00+00:00",
-    "dateOfLastModification": "2026-06-19T12:00:00+00:00",
+    "dateOfLastModification": "2026-07-14T12:00:00+00:00",
     "categories": [
         "Quantum Computing",
         "Compilation"
diff --git a/demonstrations_v2/tutorial_bp_catalyst/demo.py b/demonstrations_v2/tutorial_bp_catalyst/demo.py
@@ -267,7 +267,7 @@ def _decode(syndrome: ArrayLike):
 
 ######################################################################
 # While this approach is optimal for small codes, it rapidly becomes infeasible for larger examples.
-# For instance, the distance-:math:`30` :doc:`rotated surface code <demos/surface_code>`, which encodes only :math:`1` logical qubits, has :math:`450`
+# For instance, the distance-:math:`30` :doc:`rotated surface code <demos/intro_to_surface_code>`, which encodes only :math:`1` logical qubits, has :math:`450`
 # stabilizers for both :math:`X` and :math:`Z`. A full lookup table decoder for just one check type
 # would require approximately :math:`2.9\times 10^{35}` entries.
 #
diff --git a/demonstrations_v2/tutorial_bp_catalyst/metadata.json b/demonstrations_v2/tutorial_bp_catalyst/metadata.json
@@ -6,7 +6,7 @@
         }
     ],
     "dateOfPublication": "2025-08-25T14:30:00+00:00",
-    "dateOfLastModification": "2026-04-17T15:48:14+00:00",
+    "dateOfLastModification": "2026-07-14T15:48:14+00:00",
     "categories": [
         "Quantum Computing"
     ],
diff --git a/demonstrations_v2/tutorial_fault_tolerant_threshold/demo.py b/demonstrations_v2/tutorial_fault_tolerant_threshold/demo.py
@@ -23,7 +23,7 @@
 
 In this demo, we will learn the theoretical framework of the fault-tolerant threshold
 theorem and observe this phenomenon in action. We will construct a QEC scheme called the
-:doc:`rotated surface code <demos/surface_code>`, and subject it to simulated quantum noise across a range of physical
+:doc:`rotated surface code <demos/intro_to_surface_code>`, and subject it to simulated quantum noise across a range of physical
 error rates, computing two key metrics: (i) the pseudo-threshold (:math:`p_{pseudo}`), which
 is the break-even point where a specific error-correcting code becomes better than doing
 nothing at all, and (ii) the fault-tolerant threshold (:math:`p_{th}`), the fundamental
diff --git a/demonstrations_v2/tutorial_fault_tolerant_threshold/metadata.json b/demonstrations_v2/tutorial_fault_tolerant_threshold/metadata.json
@@ -6,7 +6,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2026-04-24T15:00:00+00:00",
-    "dateOfLastModification": "2026-04-29T15:00:00+00:00",
+    "dateOfLastModification": "2026-07-14T15:00:00+00:00",
     "categories": [
         "Quantum Computing",
         "FTQC",
diff --git a/demonstrations_v2/tutorial_game_of_surface_codes/demo.py b/demonstrations_v2/tutorial_game_of_surface_codes/demo.py
@@ -16,7 +16,7 @@
 Introduction
 ------------
 
-The game of surface codes is a high-level framework for designing :doc:` surface code <demos/surface_code>` quantum computing architectures.
+The game of surface codes is a high-level framework for designing :doc:` surface code <demos/intro_to_surface_code>` quantum computing architectures.
 The game helps us understand space-time trade-offs, where designs with a higher qubit overhead allow for faster computations and vice versa.
 For example, a space-efficient design might allow a computation with :math:`10^8` T gates to run in :math:`4` hours using :math:`55k` physical qubits, 
 whereas an intermediate design may run the same computation in :math:`22` minutes using :math:`120k` physical qubits, 
diff --git a/demonstrations_v2/tutorial_game_of_surface_codes/metadata.json b/demonstrations_v2/tutorial_game_of_surface_codes/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2025-06-02T00:00:00+00:00",
-    "dateOfLastModification": "2026-06-16T00:00:00+00:00",
+    "dateOfLastModification": "2026-07-14T00:00:00+00:00",
     "categories": [
         "Quantum Computing",
         "Compilation",
diff --git a/demonstrations_v2/tutorial_lattice_surgery/demo.py b/demonstrations_v2/tutorial_lattice_surgery/demo.py
@@ -15,7 +15,7 @@
     :width: 50%
     :target: javascript:void(0)
 
-For self-consistency, we are going to briefly recap the basic concepts of the :doc:`rotated surface code <demos/surface_code>` and explain why `Pauli product measurements <https://pennylane.ai/compilation/pauli-based-computation>`__ are sufficient 
+For self-consistency, we are going to briefly recap the basic concepts of the :doc:`rotated surface code <demos/intro_to_surface_code>` and explain why `Pauli product measurements <https://pennylane.ai/compilation/pauli-based-computation>`__ are sufficient 
 for universal computing. We are then going to explain how to perform such 
 `homological measurements <https://arxiv.org/abs/2410.02753>`__ using lattice splitting and merging.
 
diff --git a/demonstrations_v2/tutorial_lattice_surgery/metadata.json b/demonstrations_v2/tutorial_lattice_surgery/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2025-12-17T00:00:00+00:00",
-    "dateOfLastModification": "2026-07-02T00:00:00+00:00",
+    "dateOfLastModification": "2026-07-14T00:00:00+00:00",
     "categories": [
         "Quantum Computing",
         "FTQC"
diff --git a/demonstrations_v2/tutorial_magic_states/demo.py b/demonstrations_v2/tutorial_magic_states/demo.py
@@ -130,7 +130,7 @@ def magic_state_injection_circuit(target_state_params):
 # several smaller inner codes. As such, the main operations in a distillation protocol are 
 # logical, executed across multiple error-correcting blocks, resulting in a significant resource overhead. 
 # For instance, in a 15-to-1 distillation protocol [#Fowler]_, fifteen logical qubits---each already
-# protected by an inner :doc:`surface code <demos/surface_code>`---are further encoded into a single block of a Reed-Muller 
+# protected by an inner :doc:`surface code <demos/intro_to_surface_code>`---are further encoded into a single block of a Reed-Muller 
 # code (outer code) to distill just one improved magic state.
 #
 # See this :doc:`demo <demos/tutorial_magic_state_distillation>` 
diff --git a/demonstrations_v2/tutorial_magic_states/metadata.json b/demonstrations_v2/tutorial_magic_states/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2026-01-23T10:00:00+00:00",
-    "dateOfLastModification": "2026-05-28T00:00:00+00:00",
+    "dateOfLastModification": "2026-07-14T00:00:00+00:00",
     "categories": [
         "Quantum Computing"
     ],
diff --git a/demonstrations_v2/tutorial_mbqc/demo.py b/demonstrations_v2/tutorial_mbqc/demo.py
@@ -580,7 +580,7 @@ def CNOT_MBQC(input_state):
 # `Daniel Gottesman's thesis <https://arxiv.org/abs/quant-ph/9705052>`_ or `this blog post by
 # Arthur Pesah <https://arthurpesah.me/blog/2022-01-25-intro-qec-1/>`_ for a more compact
 # introduction. Instead, we will give you the gist of quantum error correction in the
-# MBQC framework. We will do so by using the :doc:`surface code <demos/surface_code>` [#FowlerSurfaceCode]_ [#FowlerPolyestimate]_ [#GoogleQEC2022]_ as an example. This code makes use of stabilizers of the form :math:`\bigotimes_i X_i` or 
+# MBQC framework. We will do so by using the :doc:`surface code <demos/intro_to_surface_code>` [#FowlerSurfaceCode]_ [#FowlerPolyestimate]_ [#GoogleQEC2022]_ as an example. This code makes use of stabilizers of the form :math:`\bigotimes_i X_i` or 
 # :math:`\bigotimes_j Z_j,` as depicted below.
 #
 # .. _fig-surfacecode:
diff --git a/demonstrations_v2/tutorial_mbqc/metadata.json b/demonstrations_v2/tutorial_mbqc/metadata.json
@@ -11,7 +11,7 @@
     "executable_stable": false,
     "executable_latest": false,
     "dateOfPublication": "2022-12-05T00:00:00+00:00",
-    "dateOfLastModification": "2026-04-21T15:48:14+00:00",
+    "dateOfLastModification": "2026-07-14T15:48:14+00:00",
     "categories": [
         "Quantum Hardware",
         "Quantum Computing",
diff --git a/demonstrations_v2/tutorial_qldpc_codes/demo.py b/demonstrations_v2/tutorial_qldpc_codes/demo.py
@@ -20,7 +20,7 @@
 4. Linear time classical decoding and corresponding error correction.
 
 Unfortunately, these requirements are not all mutually compatible. For example, widely used
-topological codes, such as :doc:`surface codes <demos/surface_code>`, use local, nearest-neighbour connections, but usually
+topological codes, such as :doc:`surface codes <demos/intro_to_surface_code>`, use local, nearest-neighbour connections, but usually
 have poor encoding rates. It remains unclear which combination of these trade-offs will offer
 the best long-term solution. However, because solving real-world problems requires scaling up to
 thousands of logical qubits, moving beyond strict nearest-neighbour constraints has become crucial.
diff --git a/demonstrations_v2/tutorial_qldpc_codes/metadata.json b/demonstrations_v2/tutorial_qldpc_codes/metadata.json
@@ -6,7 +6,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2026-04-13T00:00:00+00:00",
-    "dateOfLastModification": "2026-05-28T00:00:00+00:00",
+    "dateOfLastModification": "2026-07-14T00:00:00+00:00",
 "categories": [
 "Algorithms",
 "FTQC",
diff --git a/demonstrations_v2/tutorial_stabilizer_codes/demo.py b/demonstrations_v2/tutorial_stabilizer_codes/demo.py
@@ -11,7 +11,7 @@
 Quantum error correction is implemented through **error correction codes,** which come in many varieties that address different error types.
 Is there a unified way to understand all these codes? The **stabilizer formalism** provides such a framework for
 a large class of quantum error correction codes [#Gottesman1997]_. The so-called
-**stabilizer codes**, such as the repetition, Shor, Steane, and :doc:`surface codes <demos/surface_code>`,
+**stabilizer codes**, such as the repetition, Shor, Steane, and :doc:`surface codes <demos/intro_to_surface_code>`,
 all fall under this formalism.
 
 In this demo, we will introduce the stabilizer formalism using a bottom-up approach. We build
diff --git a/demonstrations_v2/tutorial_stabilizer_codes/metadata.json b/demonstrations_v2/tutorial_stabilizer_codes/metadata.json
@@ -11,7 +11,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2025-08-19T09:00:00+00:00",
-    "dateOfLastModification": "2026-05-06T15:00:00+00:00",
+    "dateOfLastModification": "2026-07-14T15:00:00+00:00",
     "categories": [
         "Algorithms",
         "Quantum Computing",
diff --git a/demonstrations_v2/tutorial_toric_code/demo.py b/demonstrations_v2/tutorial_toric_code/demo.py
@@ -7,7 +7,7 @@
     :property="og:description": Investigation of the toric code degenerate ground state and anyon excitations
     :property="og:image": https://pennylane.ai/qml/_static/demonstration_assets/types_of_loops.png
 
-.. note:: If you are looking for a demo on the :doc:`rotated surface code <demos/surface_code>`, please follow the link.
+.. note:: If you are looking for a demo on the :doc:`rotated surface code <demos/intro_to_surface_code>`, please follow the link.
 
 Introduction
 ------------
diff --git a/demonstrations_v2/tutorial_toric_code/metadata.json b/demonstrations_v2/tutorial_toric_code/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2022-08-08T00:00:00+00:00",
-    "dateOfLastModification": "2026-04-17T15:48:14+00:00",
+    "dateOfLastModification": "2026-07-14T15:48:14+00:00",
     "categories": [
         "Algorithms",
         "Quantum Computing"

Original file line number	Diff line number	Diff line change
`@@ -267,7 +267,7 @@ def _decode(syndrome: ArrayLike):`
`267`	`267`
`268`	`268`	`######################################################################`
`269`	`269`	`# While this approach is optimal for small codes, it rapidly becomes infeasible for larger examples.`
`270`		-# For instance, the distance-:math:`30` :doc:`rotated surface code <demos/surface_code>`, which encodes only :math:`1` logical qubits, has :math:`450`
	`270`	+# For instance, the distance-:math:`30` :doc:`rotated surface code <demos/intro_to_surface_code>`, which encodes only :math:`1` logical qubits, has :math:`450`
`271`	`271`	# stabilizers for both :math:`X` and :math:`Z`. A full lookup table decoder for just one check type
`272`	`272`	# would require approximately :math:`2.9\times 10^{35}` entries.
`273`	`273`	`#`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`}`
`7`	`7`	`],`
`8`	`8`	`"dateOfPublication": "2025-08-25T14:30:00+00:00",`
`9`		`- "dateOfLastModification": "2026-04-17T15:48:14+00:00",`
	`9`	`+ "dateOfLastModification": "2026-07-14T15:48:14+00:00",`
`10`	`10`	`"categories": [`
`11`	`11`	`"Quantum Computing"`
`12`	`12`	`],`