Merge branch 'main' into u/ab/fix_qubit_id_pauli_keys

Author: Strilanc

.clang-format

@@ -11,6 +11,7 @@ AllowShortLoopsOnASingleLine: false
 AllowShortLambdasOnASingleLine: None
 BinPackArguments: false
 BinPackParameters: false
+PointerAlignment: Right
 
 IncludeCategories:
   - Regex:           '^<.*>$'

.github/workflows/ci.yml

@@ -29,17 +29,14 @@ jobs:
       fail-fast: false
       matrix:
         os_dist: [
-          {os: ubuntu-24.04, dist: cp36-manylinux_x86_64},
-          {os: ubuntu-24.04, dist: cp37-manylinux_x86_64},
           {os: ubuntu-24.04, dist: cp38-manylinux_x86_64},
           {os: ubuntu-24.04, dist: cp39-manylinux_x86_64},
           {os: ubuntu-24.04, dist: cp310-manylinux_x86_64},
           {os: ubuntu-24.04, dist: cp311-manylinux_x86_64},
           {os: ubuntu-24.04, dist: cp312-manylinux_x86_64},
           {os: ubuntu-24.04, dist: cp313-manylinux_x86_64},
+          {os: ubuntu-24.04, dist: cp314-manylinux_x86_64},
 
-          {os: ubuntu-24.04, dist: cp36-manylinux_i686},
-          {os: ubuntu-24.04, dist: cp37-manylinux_i686},
           # cp38-manylinux_i686 disabled because pandas isn't prebuilt and takes 20 minutes to build.
           # {os: ubuntu-latest, dist: cp38-manylinux_i686},
           # cp39-manylinux_i686 disabled because pandas isn't prebuilt and takes 20 minutes to build.
@@ -88,21 +85,21 @@ jobs:
           # {os: ubuntu-latest, dist: cp39-musllinux_i686},
           # {os: ubuntu-latest, dist: cp310-musllinux_i686},
 
-          {os: macos-14, dist: cp36-macosx_x86_64, macosarch: x86_64},
-          {os: macos-14, dist: cp37-macosx_x86_64, macosarch: x86_64},
           {os: macos-14, dist: cp38-macosx_x86_64, macosarch: x86_64},
           {os: macos-14, dist: cp39-macosx_x86_64, macosarch: x86_64},
           {os: macos-14, dist: cp310-macosx_x86_64, macosarch: x86_64},
           {os: macos-14, dist: cp311-macosx_x86_64, macosarch: x86_64},
           {os: macos-14, dist: cp312-macosx_x86_64, macosarch: x86_64},
           {os: macos-14, dist: cp313-macosx_x86_64, macosarch: x86_64},
+          {os: macos-14, dist: cp314-macosx_x86_64, macosarch: x86_64},
 
           {os: macos-14, dist: cp38-macosx_arm64, macosarch: arm64},
           {os: macos-14, dist: cp39-macosx_arm64, macosarch: arm64},
           {os: macos-14, dist: cp310-macosx_arm64, macosarch: arm64},
           {os: macos-14, dist: cp311-macosx_arm64, macosarch: arm64},
           {os: macos-14, dist: cp312-macosx_arm64, macosarch: arm64},
           {os: macos-14, dist: cp313-macosx_arm64, macosarch: arm64},
+          {os: macos-14, dist: cp314-macosx_arm64, macosarch: arm64},
 
           # pypy OSX builds disabled because numpy isn't prebuilt and fails to build.
           #
@@ -119,19 +116,14 @@ jobs:
           # {os: macOS-10.15, dist: pp38-macosx_x86_64},
           # {os: macOS-10.15, dist: pp39-macosx_x86_64},
 
-          {os: windows-2025, dist: cp36-win_amd64},
-          {os: windows-2025, dist: cp37-win_amd64},
           {os: windows-2025, dist: cp38-win_amd64},
           {os: windows-2025, dist: cp39-win_amd64},
           {os: windows-2025, dist: cp310-win_amd64},
           {os: windows-2025, dist: cp311-win_amd64},
           {os: windows-2025, dist: cp312-win_amd64},
+          {os: windows-2025, dist: cp313-win_amd64},
+          {os: windows-2025, dist: cp314-win_amd64},
 
-          # (April 2024) disabled because numpy fails to build. Unsure why it's not using a prebuilt wheel.
-          # {os: windows-2025, dist: cp313-win_amd64},
-
-          {os: windows-2025, dist: cp36-win32},
-          {os: windows-2025, dist: cp37-win32},
           # cp38-win32 and cp39-win32 disabled because scipy fails to build.
           #
           # The actual error seen in github actions:
@@ -159,7 +151,7 @@ jobs:
       - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3
       - uses: actions/setup-python@3542bca2639a428e1796aaa6a2ffef0c0f575566 # v3
       - run: python dev/overwrite_dev_versions_with_date.py
-      - run: python -m pip install pybind11~=2.11.1 cibuildwheel~=2.23.2 setuptools wheel
+      - run: python -m pip install pybind11~=2.11.1 cibuildwheel~=3.3.1 setuptools wheel
       - run: python -m cibuildwheel --print-build-identifiers
       - run: python -m cibuildwheel --output-dir dist
       - uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
@@ -204,7 +196,7 @@ jobs:
     steps:
     - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3
     - uses: actions/setup-python@3542bca2639a428e1796aaa6a2ffef0c0f575566 # v3
-    - run: python -m pip install pybind11~=2.11.1 cibuildwheel~=2.23.2 setuptools wheel
+    - run: python -m pip install pybind11~=2.11.1 cibuildwheel~=3.3.1 setuptools wheel
     - run: python setup.py sdist
     - run: pip install dist/*.tar.gz
   check_sdist_installs_sinter:
@@ -411,6 +403,9 @@ jobs:
       - uses: actions/setup-node@f1f314fca9dfce2769ece7d933488f076716723e # v1
         with:
           node-version: 16.x
+      - uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6
+        with:
+          python-version: '3.13'
       - run: bazel build :stim_dev_wheel
       - run: pip install bazel-bin/stim-0.0.dev0-py3-none-any.whl
       - run: diff <(python dev/gen_stim_api_reference.py -dev) doc/python_api_reference_vDev.md

dev/gen_stim_stub_file.py

@@ -20,7 +20,7 @@ def main():
 """Stim {version}: a fast quantum stabilizer circuit library."""
 # (This is a stubs file describing the classes and methods in stim.)
 from __future__ import annotations
-from typing import overload, TYPE_CHECKING, List, Dict, Tuple, Any, Union, Iterable, Optional
+from typing import overload, TYPE_CHECKING, List, Dict, Tuple, Any, Union, Iterable, Optional, Sequence, Literal
 if TYPE_CHECKING:
     import io
     import pathlib

dev/util_gen_stub_file.py

@@ -8,6 +8,7 @@
 
 keep = {
     "__add__",
+    "__ipow__",
     "__radd__",
     "__eq__",
     "__call__",
@@ -36,6 +37,8 @@
     "__next__",
 }
 skip = {
+    "__annotate_func__",
+    "__annotations_cache__",
     "__firstlineno__",
     "__static_attributes__",
     "__replace__",
@@ -72,6 +75,8 @@
     "__post_init__",
     "__weakref__",
     "__abstractmethods__",
+    "__annotate_func__",
+    "__annotations_cache__",
 }
 
 

doc/circuit_data_references.md

@@ -33,14 +33,18 @@
 - [arXiv:2408.00758](https://arxiv.org/abs/2408.00758) → [Stim circuits for ``To reset, or not to reset -- that is the question" manuscript](https://zenodo.org/records/13152440)
 - [arXiv:2408.11894](https://arxiv.org/abs/2408.11894) → [Stim circuits for 'Automated Synthesis of Fault-Tolerant State Preparation Circuits for Quantum Error Correction Codes'](https://github.com/cda-tum/mqt-qecc/tree/main/src/mqt/qecc/ft_stateprep/eval/circuits)
 - [arXiv:2408.13687](https://arxiv.org/abs/2408.13687) → [Data for "Quantum error correction below the surface code threshold"](https://zenodo.org/records/13273331)
+- [arXiv:2409.04628](https://arxiv.org/abs/2409.04628) → [Stim implementation of the [[16,4,4]] Tesseract Code](https://github.com/DeDuckProject/tesseract-code-stim) (circuits are in the stim_circuits/ directory)
 - [arXiv:2409.17595](https://arxiv.org/abs/2409.17595) → [Data for "Magic state cultivation: growing T states as cheap as CNOT gates"](https://zenodo.org/records/13777072)
 - [arXiv:2412.01391](https://arxiv.org/abs/2412.01391) → [GitHub repo for "Transversal Logical Clifford gates on rotated surface codes with reconfigurable neutral atom arrays"](https://github.com/Zihan-Chen-PhMA/Dynamical-S-gate-decoding/) (circuits are in the circuit_garage/ directory)
 - [arXiv:2412.14256](https://arxiv.org/abs/2412.14256) → [Data for "Scaling and logic in the color code on a superconducting quantum processor"](https://zenodo.org/records/14238944)
 - [arXiv:2412.14360](https://arxiv.org/abs/2412.14360) → [Data for "Demonstrating dynamic surface codes"](https://zenodo.org/records/14238907)
+- [arXiv:2412.15187](https://arxiv.org/abs/2412.15187) → [Stim circuits and results for "Universal quantum computation via scalable measurement-free error correction"](https://zenodo.org/records/15707012)
 
 ## 2025
 
 - [arXiv:2503.04968](https://arxiv.org/abs/2503.04968) → [GitHub repo for "Optimized Noise-Resilient Surface Code Teleportation Interfaces"](https://github.com/QEC-pages/Modular-Surface-code-simulations/) (circuits are in the out/ directory)
 - [arXiv:2503.18657](https://arxiv.org/abs/2503.18657) → [GitHub repo for "Efficient Magic State Cultivation on RP^2"](https://github.com/Zihan-Chen-PhMA/Cultiv_T_RP2/) (circuits are in the circuit_garage/ directory)
+- [arXiv:2504.02935](https://arxiv.org/abs/2504.02935) → [Scripts, Stim circuits and simulation results for "Magic State Injection with Erasure Qubits"](https://zenodo.org/records/15874462)
 - [arXiv:2507.08069](https://arxiv.org/abs/2507.08069) → [Stim circuits and simulation results for "A dynamic circuit for the honeycomb Floquet code"](https://zenodo.org/records/15854678)
 - [arXiv:2507.19430](https://arxiv.org/abs/2507.19430) → [Stim circuits and parity check matrices for "Directional Codes: a new family of quantum LDPC codes on hexagonal- and square-grid connectivity hardware" manuscript](https://zenodo.org/records/16422162)
+- [arXiv:2512.17999](https://arxiv.org/abs/2512.17999) → [Stim circuits for "Logical gates on Floquet codes via folds and twists"](https://zenodo.org/records/17966122)

doc/developer_documentation.md

@@ -202,11 +202,7 @@ include(FetchContent)
 FetchContent_Declare(stim
         GIT_REPOSITORY https://github.com/quantumlib/stim.git
         GIT_TAG v1.4.0)  # [[[<<<<<<< customize the version you want!!]]]
-FetchContent_GetProperties(stim)
-if(NOT stim_POPULATED)
-  FetchContent_Populate(stim)
-  add_subdirectory(${stim_SOURCE_DIR})
-endif()
+FetchContent_MakeAvailable(stim)
 ```
 
 (Replace `v1.4.0` with another version tag as appropriate.)

doc/file_format_stim_circuit.md

@@ -25,7 +25,8 @@ and annotations for tasks such as detection event sampling and drawing the circu
 ## Encoding
 
 Stim circuit files are always encoded using UTF-8.
-Furthermore, the only place in the file where non-ASCII characters are permitted is inside of comments.
+
+(Also, the only place in the file where non-ASCII characters can validly appear is inside of comments and tags.)
 
 ## Syntax
 

doc/gates.md

@@ -1784,7 +1784,7 @@ Example:
     # Apply Y to qubit 5 controlled by qubit 2.
     CY 2 5
 
-    # Perform CY 2 5 then CX 4 2.
+    # Perform CY 2 5 then CY 4 2.
     CY 2 5 4 2
 
     # Apply Y to qubit 6 if the most recent measurement result was TRUE.
@@ -3579,7 +3579,7 @@ Example:
 
     # Sample errors from the distribution 10% XX, 20% YZ, 70% II.
     # Apply independently to qubit pairs (1,2), (5,6), and (8,3)
-    PAULI_CHANNEL_2(0,0,0, 0.1,0,0,0, 0,0,0,0.2, 0,0,0,0) 1 2 5 6 8 3
+    PAULI_CHANNEL_2(0,0,0, 0,0.1,0,0, 0,0,0,0.2, 0,0,0,0) 1 2 5 6 8 3
 
 Pauli Mixture:
 
@@ -4879,13 +4879,19 @@ detection event simulations and affect whether the observable is included in err
 makes it easier to benchmark all observables of a code, without having to introduce noiseless qubits entangled with the
 logical qubit to avoid the testing of the X observable anticommuting with the testing of the Z observable.
 
+Unlike a `DETECTOR` instruction which provides a complete description of a detector by listing all its constituent
+measurement records, an individual `OBSERVABLE_INCLUDE` instruction is not required to (and generally does not) fully
+describe a logical observable. Instead, measurement records or Pauli targets are added to it incrementally. A logical
+observable can be given both types of description: as a collection of Pauli targets and as a collection of measurement
+record targets.
+
 Parens Arguments:
 
     A non-negative integer specifying the index of the logical observable to add the measurement records to.
 
 Targets:
 
-    The measurement records to add to the specified observable.
+    The measurement records or Pauli terms to add to the specified observable.
 
 Example:
 
@@ -4921,6 +4927,12 @@ Example:
     OBSERVABLE_INCLUDE(0) X0 X1
     OBSERVABLE_INCLUDE(1) Z0 Z2
 
+    # Stim circuit may include a description of an observable in terms of Pauli targets
+    # alongside a description in terms of measurement records.
+    OBSERVABLE_INCLUDE(0) Z0 Z1
+    M 0 1
+    OBSERVABLE_INCLUDE(0) rec[-2] rec[-1]
+
 <a name="QUBIT_COORDS"></a>
 ### The 'QUBIT_COORDS' Instruction