Merge remote-tracking branch 'upstream/main'

.github/workflows/ci.yml

@@ -153,56 +153,93 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v3
       - run: python dev/overwrite_dev_versions_with_date.py
-      - run: mkdir -p output/stim
-      - run: mkdir -p output/stimcirq
-      - run: mkdir -p output/sinter
       - run: python -m pip install pybind11~=2.11.1 cibuildwheel~=2.16.2 setuptools wheel
       - run: python -m cibuildwheel --print-build-identifiers
-      - run: python -m cibuildwheel --output-dir output/stim
-      - run: python setup.py sdist
-      - run: cd glue/cirq && python setup.py sdist
-      - run: cd glue/sample && python setup.py sdist
-      - run: mv dist/* output/stim
-      - run: mv glue/cirq/dist/* output/stimcirq
-      - run: mv glue/sample/dist/* output/sinter
-      - uses: actions/upload-artifact@v3
+      - run: python -m cibuildwheel --output-dir dist
+      - uses: actions/[email protected]
         with:
-          name: dist
-          path: |
-            ./output/stimcirq/*.tar.gz
-            ./output/sinter/*.tar.gz
-            ./output/stim/*
-  check_sdist_installs:
+          name: "dist-stim-${{ matrix.os_dist.os }}-${{ matrix.os_dist.dist }}-${{ matrix.os_dist.macosarch }}"
+          path: dist/*
+  build_sdist:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v3
-      - run: python -m pip install pybind11~=2.11.1 cibuildwheel~=2.16.2 setuptools wheel
+      - run: python -m pip install setuptools pybind11~=2.11.1
+      - run: python dev/overwrite_dev_versions_with_date.py
+      - run: mkdir output
       - run: python setup.py sdist
-      - run: pip install dist/*.tar.gz
+      - run: cd glue/cirq && python setup.py sdist
+      - run: cd glue/sample && python setup.py sdist
+      - uses: actions/[email protected]
+        with:
+          name: "dist-sinter"
+          path: glue/sample/dist/*.tar.gz
+      - uses: actions/[email protected]
+        with:
+          name: "dist-stimcirq"
+          path: glue/cirq/dist/*.tar.gz
+      - uses: actions/[email protected]
+        with:
+          name: "dist-stim-sdist"
+          path: dist/*.tar.gz
+  check_sdist_installs_stim:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v3
+    - run: python -m pip install pybind11~=2.11.1 cibuildwheel~=2.16.2 setuptools wheel
+    - run: python setup.py sdist
+    - run: pip install dist/*.tar.gz
+  check_sdist_installs_sinter:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v3
+    - run: python -m pip install setuptools
+    - run: cd glue/sample && python setup.py sdist
+    - run: pip install glue/sample/dist/*
+    - run: python -c "import sinter"
+  merge_upload_artifacts:
+    needs: ["build_dist", "build_sdist"]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Merge Artifacts
+        uses: actions/upload-artifact/merge@v4
+        with:
+          name: dist-stim
+          pattern: dist-stim-*
   upload_dev_release_to_pypi:
-    needs: ["build_dist"]
+    needs: ["merge_upload_artifacts"]
     if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/download-artifact@v2
+      - uses: actions/[email protected]
+        with:
+          name: dist-stim
+          path: dist-stim
+      - uses: actions/[email protected]
+        with:
+          name: dist-stimcirq
+          path: dist-stimcirq
+      - uses: actions/[email protected]
         with:
-          name: dist
-          path: dist
+          name: dist-sinter
+          path: dist-sinter
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           user: __token__
-          packages_dir: dist/stim/
+          packages_dir: dist-stim
           password: ${{ secrets.pypi_token_stim }}
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           user: __token__
-          packages_dir: dist/stimcirq/
+          packages_dir: dist-stimcirq
           password: ${{ secrets.pypi_token_stimcirq }}
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           user: __token__
-          packages_dir: dist/sinter/
+          packages_dir: dist-sinter
           password: ${{ secrets.pypi_token_sinter }}
   run_main:
     runs-on: ubuntu-latest

dev/gen_sinter_api_reference.py

@@ -48,6 +48,25 @@ def main():
 ```
 '''.strip())
 
+    replace_rules = []
+    for package in ['stim', 'sinter']:
+        p = __import__(package)
+        for name in dir(p):
+            x = getattr(p, name)
+            if isinstance(x, type) and 'class' in str(x):
+                desired_name = f'{package}.{name}'
+                if '._' in str(x):
+                    bad_name = str(x).split("'")[1]
+                    replace_rules.append((bad_name, desired_name))
+                lonely_name = desired_name.split(".")[-1]
+                for q in ['"', "'"]:
+                    replace_rules.append(('ForwardRef(' + q + lonely_name + q + ')', desired_name))
+                    replace_rules.append(('ForwardRef(' + q + desired_name + q + ')', desired_name))
+                    replace_rules.append((q + desired_name + q, desired_name))
+                    replace_rules.append((q + lonely_name + q, desired_name))
+                replace_rules.append(('ForwardRef(' + desired_name + ')', desired_name))
+                replace_rules.append(('ForwardRef(' + lonely_name + ')', desired_name))
+
     for obj in objects:
         print()
         print(f'<a name="{obj.full_name}"></a>')
@@ -58,7 +77,10 @@ def main():
             print(f'# (in class {".".join(obj.full_name.split(".")[:-1])})')
         else:
             print(f'# (at top-level in the sinter module)')
-        print('\n'.join(obj.lines))
+        for line in obj.lines:
+            for a, b in replace_rules:
+                line = line.replace(a, b)
+            print(line)
         print("```")
 
 

dev/util_gen_stub_file.py

@@ -1,5 +1,4 @@
 import dataclasses
-import sys
 import types
 from typing import Any
 from typing import Optional, Iterator, List
@@ -9,6 +8,7 @@
 
 keep = {
     "__add__",
+    "__radd__",
     "__eq__",
     "__call__",
     "__ge__",
@@ -224,17 +224,6 @@ def print_doc(*, full_name: str, parent: object, obj: object, level: int) -> Opt
             text += '@abc.abstractmethod\n'
         sig_name = f'{term_name}{inspect.signature(obj)}'
         text += "\n".join(splay_signature(f"def {sig_name}:"))
-        text = text.replace('''ForwardRef('sinter.TaskStats')''', 'sinter.TaskStats')
-        text = text.replace('''ForwardRef('sinter.Task')''', 'sinter.Task')
-        text = text.replace('''ForwardRef('sinter.Progress')''', 'sinter.Progress')
-        text = text.replace('''ForwardRef('sinter.Decoder')''', 'sinter.Decoder')
-        text = text.replace("'AnonTaskStats'", "sinter.AnonTaskStats")
-        text = text.replace('sinter._decoding_decoder_class.CompiledDecoder', 'sinter.CompiledDecoder')
-        text = text.replace("'AnonTaskStats'", "sinter.AnonTaskStats")
-        text = text.replace("'stim.Circuit'", "stim.Circuit")
-        text = text.replace("'stim.DetectorErrorModel'", "stim.DetectorErrorModel")
-        text = text.replace("'sinter.CollectionOptions'", "sinter.CollectionOptions")
-        text = text.replace("'sinter.Fit'", 'sinter.Fit')
 
         # Replace default value lambdas with their source.
         if 'lambda' in str(text):

doc/circuit_data_references.md

@@ -29,3 +29,5 @@
 - [arXiv:2407.13826 ](https://arxiv.org/abs/2407.13826) → [Stim circuits for 'Designing fault-tolerant circuits using detector error models'](https://github.com/peter-janderks/short_measurement_schedules_simulations/tree/main/stim_circuits)
 - [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.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)

doc/developer_documentation.md

@@ -68,22 +68,18 @@ A *spandrel* is an implementation detail that has observable effects, but which
 
 - Create an off-main-branch release commit
     - [ ] `git checkout main -b SOMEBRANCHNAME`
-    - [ ] Update version to `version = 'X.Y.0'` in `setup.py` (at repo root)
-    - [ ] Update version to `version = 'X.Y.0'` in `glue/cirq/setup.py`
-    - [ ] Update version to `version = 'X.Y.0'` in `glue/sinter/setup.py`
-    - [ ] Update version to `version = 'X.Y.0'` in `glue/stimzx/setup.py`
+    - [ ] Global search replace `__version__ = 'X.Y.dev0'` with `__version__ = 'X.Y.0'`
     - [ ] `git commit -a -m "Bump to vX.Y.0"`
     - [ ] `git tag vX.Y.0`
     - [ ] Push tag to github
     - [ ] Check github `Actions` tab and confirm ci is running on the tag
     - [ ] Wait for ci to finish validating and producing artifacts for the tag
     - [ ] Get `stim`, `stimcirq`, and `sinter` wheels/sdists [from cibuildwheels](#pypackage.stim.cibuildwheels) of this tag
 - Bump to next dev version on main branch
-    - [ ] Update version to `version = 'X.(Y+1).dev0'` in `setup.py` (at repo root)
-    - [ ] Update version to `version = 'X.(Y+1).dev0'` in `glue/cirq/setup.py`
-    - [ ] Update version to `version = 'X.(Y+1).dev0'` in `glue/sinter/setup.py`
-    - [ ] Update version to `version = 'X.(Y+1).dev0'` in `glue/stimzx/setup.py`
-    - [ ] Update `INTENTIONAL_VERSION_SEED_INCOMPATIBILITY` in `src/stim/circuit/circuit.h`
+    - [ ] `git checkout main -b SOMEBRANCHNAME`
+    - [ ] Global search replace `__version__ = 'X.Y.dev0'` with `__version__ = 'X.(Y+1).dev0'`
+    - [ ] Increment `INTENTIONAL_VERSION_SEED_INCOMPATIBILITY` in `src/stim/circuit/circuit.h`
+    - [ ] `git commit -a -m "Start vX.(Y+1).dev"`
     - [ ] Push to github as a branch and merge into main using a pull request
 - Write release notes on github
     - [ ] In title, use two-word theming of most important changes

doc/file_format_stim_circuit.md

@@ -34,6 +34,17 @@ Each line is either blank, an instruction, a block initiator, or a block termina
 Also, each line may be indented with spacing characters and may end with a comment indicated by a hash (`#`).
 Comments and indentation are purely decorative; they carry no semantic significance.
 
+Here is a formal definition of the above paragraph.
+Entries like `/this/` are regular expressions.
+Entries like `<this>` are named expressions.
+Entries like `'this'` are literal string expressions.
+The `::=` operator means "defined as".
+The `|` binary operator means "or".
+The `?` suffix operator means "zero-or-one".
+The `*` suffix operator means "zero-or-many".
+Parens are used to group expressions.
+Adjacent expressions are combined by concatenation.
+
 ```
 <CIRCUIT> ::= <LINE>*
 <LINE> ::= <INDENT> (<INSTRUCTION> | <BLOCK_START> | <BLOCK_END>)? <COMMENT>? '\n'
@@ -42,13 +53,15 @@ Comments and indentation are purely decorative; they carry no semantic significa
 ```
 
 An *instruction* is composed of a name,
+then (introduced in stim v1.15) an optional tag inside square brackets,
 then an optional comma-separated list of arguments inside of parentheses,
 then a list of space-separated targets.
 For example, the line `X_ERROR(0.1) 5 6` is an instruction with a name (`X_ERROR`),
 one argument (`0.1`), and two targets (`5` and `6`).
 
 ```
-<INSTRUCTION> ::= <NAME> <PARENS_ARGUMENTS>? <TARGETS>
+<INSTRUCTION> ::= <NAME> <TAG>? <PARENS_ARGUMENTS>? <TARGETS>
+<TAG> ::= '[' /[^\r\]\n]/* ']'
 <PARENS_ARGUMENTS> ::= '(' <ARGUMENTS> ')' 
 <ARGUMENTS> ::= /[ \t]*/ <ARG> /[ \t]*/ (',' <ARGUMENTS>)?
 <TARGETS> ::= /[ \t]+/ <TARG> <TARGETS>?
@@ -57,6 +70,14 @@ one argument (`0.1`), and two targets (`5` and `6`).
 An instruction *name* starts with a letter and then contains a series of letters, digits, and underscores.
 Names are case-insensitive.
 
+An instruction *tag* is an arbitrary string enclosed by square brackets.
+Certain characters cannot appear directly in the tag, and must instead be included using escape sequences.
+The closing square bracket character `]` cannot appear directly, and is instead encoded using the escape sequence `\C`.
+The carriage return character cannot appear directly, and is instead encoded using the escape sequence `\r`.
+The line feed character cannot appear directly, and is instead encoded using the escape sequence `\n`.
+The backslash character `\` cannot appear directly, and is instead encoded using the escape sequence `\B`.
+(This backslash escape sequence differs from the common escape sequence `\\` because that sequence causes exponential explosions when escaping multiple times.)
+
 An *argument* is a double precision floating point number.
 
 A *target* can either be a qubit target (a non-negative integer),
@@ -124,6 +145,17 @@ Currently, control flow is limited to *repetition*.
 A circuit can contain `REPEAT K { ... }` blocks,
 which indicate that the block's instructions should be iterated over `K` times instead of just once.
 
+### Tags
+
+Instruction tags have no effect on the function of a circuit.
+In general, tools should attempt to propagate tags through circuit transformations and otherwise ignore them.
+The intent is that users and tools can use tags to specify custom behavior that stim is not aware of.
+For example, consider the tagged instruction `TICK[100ns]`.
+In most situations, the `100ns` tag does nothing.
+But if you are using a tool that adds noise to circuits, and it's programmed to look at tags to get hints about what
+noise to add, then the `100ns` tag could be a message to that tool (specifying a duration, which the tool could use when
+computing the probability argument of an inserted `DEPOLARIZE1` instruction).
+
 ### Target Types
 
 There are four types of targets that can be given to instructions:

doc/gates.md

@@ -3043,7 +3043,7 @@ Decomposition (into H, S, CX, M, R):
 
 
 <a name="SPP"></a>
-### The 'SPP' Instruction
+### The 'SPP' Gate
 
 The generalized S gate. Phases the -1 eigenspace of Pauli product observables by i.
 
@@ -3109,7 +3109,7 @@ Decomposition (into H, S, CX, M, R):
 
 
 <a name="SPP_DAG"></a>
-### The 'SPP_DAG' Instruction
+### The 'SPP_DAG' Gate
 
 The generalized S_DAG gate. Phases the -1 eigenspace of Pauli product observables by -i.