Add coordinate filtering to detector slice diagrams (#386)

* Add coordinate filtering to detector slice diagrams
- Add `--filter_coords` argument to `stim diagram`
- Add `filter_coords` argument to `stim.Circuit.diagram`
- Add anchors to getting started notebook
- Broke down and wrote a split method
- Broke down and wrote a parse_exact_double_from_string method
- Added a stim diagram documentation example of making an animated gif

Author: Strilanc

doc/getting_started.ipynb

@@ -1251,6 +1251,7 @@ def diagram(
     *,
     type: 'Literal["detector-slice-text"]',
     tick: int,
+    filter_coords: Optional[Iterable[Iterable[float]]] = None,
 ) -> 'stim._DiagramHelper':
     pass
 @overload
@@ -1259,13 +1260,15 @@ def diagram(
     *,
     type: 'Literal["detector-slice-svg"]',
     tick: int,
+    filter_coords: Optional[Iterable[Iterable[float]]] = None,
 ) -> 'stim._DiagramHelper':
     pass
 def diagram(
     self,
     *,
     type: str,
     tick: Optional[int] = None,
+    filter_coords: Optional[Iterable[Iterable[float]]] = None,
 ) -> 'stim._DiagramHelper':
     """Returns a diagram of the circuit, from a variety of options.
 
@@ -1309,6 +1312,9 @@ def diagram(
             instruction to slice at. Note that the first TICK in the
             circuit is tick=1. The value tick=0 refers to the very start
             of the circuit.
+        filter_coords: A set of acceptable coordinate prefixes. For
+            detector slice diagrams, only detectors whose coordinates
+            begin with one of these filters will be included.
 
     Returns:
         An object whose `__str__` method returns the diagram, so that

doc/python_api_reference_vDev.md

@@ -769,6 +769,7 @@ class Circuit:
         *,
         type: 'Literal["detector-slice-text"]',
         tick: int,
+        filter_coords: Optional[Iterable[Iterable[float]]] = None,
     ) -> 'stim._DiagramHelper':
         pass
     @overload
@@ -777,13 +778,15 @@ class Circuit:
         *,
         type: 'Literal["detector-slice-svg"]',
         tick: int,
+        filter_coords: Optional[Iterable[Iterable[float]]] = None,
     ) -> 'stim._DiagramHelper':
         pass
     def diagram(
         self,
         *,
         type: str,
         tick: Optional[int] = None,
+        filter_coords: Optional[Iterable[Iterable[float]]] = None,
     ) -> 'stim._DiagramHelper':
         """Returns a diagram of the circuit, from a variety of options.
 
@@ -827,6 +830,9 @@ class Circuit:
                 instruction to slice at. Note that the first TICK in the
                 circuit is tick=1. The value tick=0 refers to the very start
                 of the circuit.
+            filter_coords: A set of acceptable coordinate prefixes. For
+                detector slice diagrams, only detectors whose coordinates
+                begin with one of these filters will be included.
 
         Returns:
             An object whose `__str__` method returns the diagram, so that

doc/stim.pyi

@@ -557,6 +557,7 @@ NAME
 
 SYNOPSIS
     stim diagram \
+        [--filter_coords float.seperatedby(',').seperatedby(':')] \
         [--in filepath] \
         [--out filepath] \
         [--remove_noise] \
@@ -566,7 +567,25 @@ SYNOPSIS
 DESCRIPTION
     Produces various kinds of diagrams.
 
+
 OPTIONS
+    --filter_coords
+        Specifies coordinate filters that determine what appears in the diagram.
+
+        A coordinate is a double precision floating point number.
+        A point is a tuple of coordinates.
+        The coordinates of a point are separate by commas (',').
+        A filter is a set of points.
+        Points are separated by colons (':').
+
+        For example, in a detector slice diagram, specifying
+        "--filter-coords 2,3:4,5,6" means that only detectors whose
+        first two coordinates are (2,3), or whose first three coordinate
+        are (4,5,6), should be included in the diagram. Note that the
+        filters are always prefix matches, so a detector with coordinates
+        (2,3,4) matches the filter 2,3.
+
+
     --in
         Where to read the object to diagram from.
 
@@ -690,6 +709,44 @@ EXAMPLES
         q0: -H-@-
                |
         q1: ---X-
+
+
+    Example #2
+        >>> # Making a video of detector slices moving around
+
+        >>> # First, make a circuit to animate.
+        >>> stim gen \
+                --code surface_code \
+                --task rotated_memory_x \
+                --distance 5 \
+                --rounds 100 \
+                > surface_code.stim
+
+        >>> # Second, use gnu-parallel and stim diagram to make video frames.
+        >>> parallel stim diagram \
+            --filter_coords 2,2:4,2 \
+            --type detector-slice-svg \
+            --tick {} \
+            --in surface_code.stim \
+            --out video_frame_{}.svg \
+            ::: {50..150}
+
+        >>> # Third, use ffmpeg to turn the frames into a GIF.
+        >>> # (note: the complex filter argument is optional; it turns the background white)
+        >>> ffmpeg output_animation.gif \
+            -framerate 5 \
+            -pattern_type glob -i 'video_frame_*.svg' \
+            -pix_fmt rgb8 \
+            -filter_complex "[0]split=2[bg][fg];[bg]drawbox=c=white@1:t=fill[bg];[bg][fg]overlay=format=auto"
+
+        >>> # Alternatively, make an MP4 video instead of a GIF.
+        >>> ffmpeg output_video.mp4 \
+            -framerate 5 \
+            -pattern_type glob -i 'video_frame_*.svg' \
+            -vf scale=1024:-1 \
+            -c:v libx264 \
+            -vf format=yuv420p \
+            -vf "pad=ceil(iw/2)*2:ceil(ih/2)*2"
 ```
 
 <a name="explain_errors"></a>

doc/usage_command_line.md

@@ -769,6 +769,7 @@ class Circuit:
         *,
         type: 'Literal["detector-slice-text"]',
         tick: int,
+        filter_coords: Optional[Iterable[Iterable[float]]] = None,
     ) -> 'stim._DiagramHelper':
         pass
     @overload
@@ -777,13 +778,15 @@ class Circuit:
         *,
         type: 'Literal["detector-slice-svg"]',
         tick: int,
+        filter_coords: Optional[Iterable[Iterable[float]]] = None,
     ) -> 'stim._DiagramHelper':
         pass
     def diagram(
         self,
         *,
         type: str,
         tick: Optional[int] = None,
+        filter_coords: Optional[Iterable[Iterable[float]]] = None,
     ) -> 'stim._DiagramHelper':
         """Returns a diagram of the circuit, from a variety of options.
 
@@ -827,6 +830,9 @@ class Circuit:
                 instruction to slice at. Note that the first TICK in the
                 circuit is tick=1. The value tick=0 refers to the very start
                 of the circuit.
+            filter_coords: A set of acceptable coordinate prefixes. For
+                detector slice diagrams, only detectors whose coordinates
+                begin with one of these filters will be included.
 
         Returns:
             An object whose `__str__` method returns the diagram, so that

glue/python/src/stim/__init__.pyi

@@ -1,14 +1,12 @@
-import os
 
 import contextlib
 import functools
 import pathlib
-import subprocess
 import tempfile
 
 import math
 import time
-from typing import Optional, Dict, Callable, Tuple, Iterable
+from typing import Optional, Dict, Callable, Tuple
 from typing import Union
 
 import numpy as np

glue/sample/src/sinter/_decoding.py

@@ -16,6 +16,7 @@
 
 #include <algorithm>
 #include <array>
+#include <cmath>
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
@@ -389,3 +390,26 @@ ostream_else_cout stim::find_output_stream_argument(
     }
     return {std::move(f)};
 }
+
+std::vector<std::string> stim::split(char splitter, const std::string &text) {
+    std::vector<std::string> result;
+    size_t start = 0;
+    for (size_t k = 0; k < text.size(); k++) {
+        if (text[k] == splitter) {
+            result.push_back(text.substr(start, k - start));
+            start = k + 1;
+        }
+    }
+    result.push_back(text.substr(start, text.size() - start));
+    return result;
+}
+
+double stim::parse_exact_double_from_string(const std::string &text) {
+    char *end = nullptr;
+    const char *c = text.c_str();
+    double d = strtod(c, &end);
+    if (isspace(*c) || end == c || end != c + text.size() || std::isinf(d) || std::isnan(d)) {
+        throw std::invalid_argument("Not an exact double: '" + text + "'");
+    }
+    return d;
+}

src/stim/arg_parse.cc

@@ -260,6 +260,10 @@ struct ostream_else_cout {
 ///         Command line argument isn't present and default_std_out is false.
 ostream_else_cout find_output_stream_argument(const char *name, bool default_std_out, int argc, const char **argv);
 
+std::vector<std::string> split(char splitter, const std::string &text);
+
+double parse_exact_double_from_string(const std::string &text);
+
 }  // namespace stim
 
 #endif

src/stim/arg_parse.h

@@ -260,7 +260,9 @@ TEST(arg_parse, find_open_file_argument) {
 
     args = {""};
     ASSERT_THROW_MSG(
-        { find_open_file_argument("-arg", nullptr, "rb", args.size(), args.data()); }, std::invalid_argument, "Missing");
+        { find_open_file_argument("-arg", nullptr, "rb", args.size(), args.data()); },
+        std::invalid_argument,
+        "Missing");
     args = {""};
     ASSERT_EQ(find_open_file_argument("-arg", tmp, "rb", args.size(), args.data()), tmp);
 
@@ -292,3 +294,33 @@ TEST(arg_parse, find_open_file_argument) {
 
     fclose(tmp);
 }
+
+TEST(arg_parse, split) {
+    ASSERT_EQ(split(',', ""), (std::vector<std::string>{""}));
+    ASSERT_EQ(split(',', "abc"), (std::vector<std::string>{"abc"}));
+    ASSERT_EQ(split(',', ","), (std::vector<std::string>{"", ""}));
+    ASSERT_EQ(split(',', "abc,"), (std::vector<std::string>{"abc", ""}));
+    ASSERT_EQ(split(',', ",abc"), (std::vector<std::string>{"", "abc"}));
+    ASSERT_EQ(split(',', "abc,def,ghi"), (std::vector<std::string>{"abc", "def", "ghi"}));
+    ASSERT_EQ(split(',', "abc,def,ghi,"), (std::vector<std::string>{"abc", "def", "ghi", ""}));
+}
+
+TEST(arg_parse, parse_exact_double_from_string) {
+    ASSERT_THROW({ parse_exact_double_from_string(""); }, std::invalid_argument);
+    ASSERT_THROW({ parse_exact_double_from_string("a"); }, std::invalid_argument);
+    ASSERT_THROW({ parse_exact_double_from_string(" 1"); }, std::invalid_argument);
+    ASSERT_THROW({ parse_exact_double_from_string("\t1"); }, std::invalid_argument);
+    ASSERT_THROW({ parse_exact_double_from_string("1 "); }, std::invalid_argument);
+    ASSERT_THROW({ parse_exact_double_from_string("banana"); }, std::invalid_argument);
+    ASSERT_THROW({ parse_exact_double_from_string("1.2.3"); }, std::invalid_argument);
+    ASSERT_THROW({ parse_exact_double_from_string("INFINITY"); }, std::invalid_argument);
+    ASSERT_THROW({ parse_exact_double_from_string("inf"); }, std::invalid_argument);
+    ASSERT_THROW({ parse_exact_double_from_string("nan"); }, std::invalid_argument);
+
+    ASSERT_EQ(parse_exact_double_from_string("0"), 0);
+    ASSERT_EQ(parse_exact_double_from_string("1"), 1);
+    ASSERT_EQ(parse_exact_double_from_string("+1"), 1);
+    ASSERT_EQ(parse_exact_double_from_string("1e3"), 1000);
+    ASSERT_EQ(parse_exact_double_from_string("1.5"), 1.5);
+    ASSERT_EQ(parse_exact_double_from_string("-1.5"), -1.5);
+}

src/stim/arg_parse.test.cc

@@ -1808,6 +1808,7 @@ void stim_pybind::pybind_circuit_methods(pybind11::module &, pybind11::class_<Ci
         pybind11::kw_only(),
         pybind11::arg("type") = "timeline-text",
         pybind11::arg("tick") = pybind11::none(),
+        pybind11::arg("filter_coords") = pybind11::none(),
         clean_doc_string(u8R"DOC(
             @overload def diagram(self, *, type: 'Literal["timeline-text"]') -> 'stim._DiagramHelper':
             @overload def diagram(self, *, type: 'Literal["timeline-svg"]') -> 'stim._DiagramHelper':
@@ -1816,9 +1817,9 @@ void stim_pybind::pybind_circuit_methods(pybind11::module &, pybind11::class_<Ci
             @overload def diagram(self, *, type: 'Literal["match-graph-svg"]') -> 'stim._DiagramHelper':
             @overload def diagram(self, *, type: 'Literal["match-graph-3d"]') -> 'stim._DiagramHelper':
             @overload def diagram(self, *, type: 'Literal["match-graph-3d-html"]') -> 'stim._DiagramHelper':
-            @overload def diagram(self, *, type: 'Literal["detector-slice-text"]', tick: int) -> 'stim._DiagramHelper':
-            @overload def diagram(self, *, type: 'Literal["detector-slice-svg"]', tick: int) -> 'stim._DiagramHelper':
-            @signature def diagram(self, *, type: str, tick: Optional[int] = None) -> 'stim._DiagramHelper':
+            @overload def diagram(self, *, type: 'Literal["detector-slice-text"]', tick: int, filter_coords: Optional[Iterable[Iterable[float]]] = None) -> 'stim._DiagramHelper':
+            @overload def diagram(self, *, type: 'Literal["detector-slice-svg"]', tick: int, filter_coords: Optional[Iterable[Iterable[float]]] = None) -> 'stim._DiagramHelper':
+            @signature def diagram(self, *, type: str, tick: Optional[int] = None, filter_coords: Optional[Iterable[Iterable[float]]] = None) -> 'stim._DiagramHelper':
             Returns a diagram of the circuit, from a variety of options.
 
             Args:
@@ -1861,6 +1862,9 @@ void stim_pybind::pybind_circuit_methods(pybind11::module &, pybind11::class_<Ci
                     instruction to slice at. Note that the first TICK in the
                     circuit is tick=1. The value tick=0 refers to the very start
                     of the circuit.
+                filter_coords: A set of acceptable coordinate prefixes. For
+                    detector slice diagrams, only detectors whose coordinates
+                    begin with one of these filters will be included.
 
             Returns:
                 An object whose `__str__` method returns the diagram, so that