sinter 1.15.0__py3-none-any.whl

sinter/_data/_anon_task_stats_test.py

@@ -0,0 +1,35 @@
+import collections
+
+import sinter
+
+
+def test_repr():
+    v = sinter.AnonTaskStats(shots=22, errors=3, discards=4, seconds=5)
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.AnonTaskStats()
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.AnonTaskStats(shots=22)
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.AnonTaskStats(shots=21, errors=4)
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.AnonTaskStats(shots=21, discards=4)
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.AnonTaskStats(seconds=4)
+    assert eval(repr(v), {"sinter": sinter}) == v
+
+
+def test_add():
+    a0 = sinter.AnonTaskStats(shots=220, errors=30, discards=40, seconds=50)
+    b0 = sinter.AnonTaskStats(shots=50, errors=4, discards=3, seconds=2)
+    assert a0 + b0 == sinter.AnonTaskStats(shots=270, errors=34, discards=43, seconds=52)
+    assert a0 + sinter.AnonTaskStats() == a0
+
+    a = sinter.AnonTaskStats(shots=220, errors=30, discards=40, seconds=50, custom_counts=collections.Counter({'a': 10, 'b': 20}))
+    b = sinter.AnonTaskStats(shots=50, errors=4, discards=3, seconds=2, custom_counts=collections.Counter({'a': 1, 'c': 3}))
+    assert a + b == sinter.AnonTaskStats(shots=270, errors=34, discards=43, seconds=52, custom_counts=collections.Counter({'a': 11, 'b': 20, 'c': 3}))
+
+    assert a + sinter.AnonTaskStats() == a
+    assert sinter.AnonTaskStats() + b == b
+
+    assert a + b0 == sinter.AnonTaskStats(shots=270, errors=34, discards=43, seconds=52, custom_counts=collections.Counter({'a': 10, 'b': 20}))
+    assert a0 + b == sinter.AnonTaskStats(shots=270, errors=34, discards=43, seconds=52, custom_counts=collections.Counter({'a': 1, 'c': 3}))

sinter/_data/_collection_options.py

@@ -0,0 +1,106 @@
+import dataclasses
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import sinter
+
+
+@dataclasses.dataclass(frozen=True)
+class CollectionOptions:
+    """Describes options for how data is collected for a decoding problem.
+
+    Attributes:
+        max_shots: Defaults to None (unused). Stops the sampling process
+            after this many samples have been taken from the circuit.
+        max_errors: Defaults to None (unused). Stops the sampling process
+            after this many errors have been seen in samples taken from the
+            circuit. The actual number sampled errors may be larger due to
+            batching.
+        start_batch_size: Defaults to None (collector's choice). The very
+            first shots taken from the circuit will use a batch of this
+            size, and no other batches will be taken in parallel. Once this
+            initial fact finding batch is done, batches can be taken in
+            parallel and the normal batch size limiting processes take over.
+        max_batch_size: Defaults to None (unused). Limits batches from
+            taking more than this many shots at once. For example, this can
+            be used to ensure memory usage stays below some limit.
+        max_batch_seconds: Defaults to None (unused). When set, the recorded
+            data from previous shots is used to estimate how much time is
+            taken per shot. This information is then used to predict the
+            biggest batch size that can finish in under the given number of
+            seconds. Limits each batch to be no larger than that.
+    """
+
+    max_shots: Optional[int] = None
+    max_errors: Optional[int] = None
+    start_batch_size: Optional[int] = None
+    max_batch_size: Optional[int] = None
+    max_batch_seconds: Optional[float] = None
+
+    def __post_init__(self):
+        if self.max_shots is not None and self.max_shots < 0:
+            raise ValueError(f'max_shots is not None and max_shots={self.max_shots} < 0')
+        if self.max_errors is not None and self.max_errors < 0:
+            raise ValueError(f'max_errors is not None and max_errors={self.max_errors} < 0')
+        if self.start_batch_size is not None and self.start_batch_size <= 0:
+            raise ValueError(f'start_batch_size is not None and start_batch_size={self.start_batch_size} <= 0')
+        if self.max_batch_size is not None and self.max_batch_size <= 0:
+            raise ValueError(
+                f'max_batch_size={self.max_batch_size} is not None and max_batch_size <= 0')
+        if self.max_batch_seconds is not None and self.max_batch_seconds <= 0:
+            raise ValueError(
+                f'max_batch_seconds={self.max_batch_seconds} is not None and max_batch_seconds <= 0')
+
+    def __repr__(self) -> str:
+        terms = []
+        if self.max_shots is not None:
+            terms.append(f'max_shots={self.max_shots!r}')
+        if self.max_errors is not None:
+            terms.append(f'max_errors={self.max_errors!r}')
+        if self.start_batch_size is not None:
+            terms.append(f'start_batch_size={self.start_batch_size!r}')
+        if self.max_batch_size is not None:
+            terms.append(f'max_batch_size={self.max_batch_size!r}')
+        if self.max_batch_seconds is not None:
+            terms.append(f'max_batch_seconds={self.max_batch_seconds!r}')
+        return f'sinter.CollectionOptions({", ".join(terms)})'
+
+    def combine(self, other: 'sinter.CollectionOptions') -> 'sinter.CollectionOptions':
+        """Returns a combination of multiple collection options.
+
+        All fields are combined by taking the minimum from both collection
+        options objects, with None treated as being infinitely large.
+
+        Args:
+            other: The collections options to combine with.
+
+        Returns:
+            The combined collection options.
+
+        Examples:
+            >>> import sinter
+            >>> a = sinter.CollectionOptions(
+            ...    max_shots=1_000_000,
+            ...    start_batch_size=100,
+            ... )
+            >>> b = sinter.CollectionOptions(
+            ...    max_shots=100_000,
+            ...    max_errors=100,
+            ... )
+            >>> a.combine(b)
+            sinter.CollectionOptions(max_shots=100000, max_errors=100, start_batch_size=100)
+        """
+        return CollectionOptions(
+            max_shots=nullable_min(self.max_shots, other.max_shots),
+            max_errors=nullable_min(self.max_errors, other.max_errors),
+            start_batch_size=nullable_min(self.start_batch_size, other.start_batch_size),
+            max_batch_size=nullable_min(self.max_batch_size, other.max_batch_size),
+            max_batch_seconds=nullable_min(self.max_batch_seconds, other.max_batch_seconds))
+
+
+def nullable_min(a: Optional[int], b: Optional[int]) -> Optional[int]:
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return min(a, b)

sinter/_data/_collection_options_test.py

@@ -0,0 +1,24 @@
+import sinter
+
+
+def test_repr():
+    v = sinter.CollectionOptions()
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.CollectionOptions(max_shots=100)
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.CollectionOptions(max_errors=100)
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.CollectionOptions(start_batch_size=10)
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.CollectionOptions(max_batch_size=100)
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.CollectionOptions(max_batch_seconds=30)
+    assert eval(repr(v), {"sinter": sinter}) == v
+    v = sinter.CollectionOptions(max_shots=100, max_errors=90, start_batch_size=80, max_batch_size=200, max_batch_seconds=30)
+    assert eval(repr(v), {"sinter": sinter}) == v
+
+
+def test_combine():
+    a = sinter.CollectionOptions(max_shots=200, max_batch_seconds=300)
+    b = sinter.CollectionOptions(max_errors=100, max_batch_seconds=400)
+    assert a.combine(b) == sinter.CollectionOptions(max_errors=100, max_shots=200, max_batch_seconds=300)

sinter/_data/_csv_out.py

@@ -0,0 +1,74 @@
+import collections
+import csv
+import io
+import json
+from typing import Any, Optional
+
+
+def escape_csv(text: Any, width: Optional[int]) -> str:
+    output = io.StringIO()
+    csv.writer(output).writerow([text])
+    text = output.getvalue().strip()
+    if width is not None:
+        text = text.rjust(width)
+    return text
+
+
+def csv_line(*,
+             shots: Any,
+             errors: Any,
+             discards: Any,
+             seconds: Any,
+             decoder: Any,
+             strong_id: Any,
+             json_metadata: Any,
+             custom_counts: Any,
+             is_header: bool = False) -> str:
+    if isinstance(seconds, float):
+        if seconds < 1:
+            seconds = f'{seconds:0.3f}'
+        elif seconds < 10:
+            seconds = f'{seconds:0.2f}'
+        else:
+            seconds = f'{seconds:0.1f}'
+    if not is_header:
+        json_metadata = json.dumps(json_metadata,
+                                   separators=(',', ':'),
+                                   sort_keys=True)
+        if custom_counts:
+            custom_counts = escape_csv(
+                json.dumps(custom_counts,
+                           separators=(',', ':'),
+                           sort_keys=True), None)
+        else:
+            custom_counts = ''
+
+
+    shots = escape_csv(shots, 10)
+    if isinstance(errors, (dict, collections.Counter)):
+        errors = json.dumps(errors, separators=(',', ':'), sort_keys=True)
+    errors = escape_csv(errors, 10)
+    discards = escape_csv(discards, 10)
+    seconds = escape_csv(seconds, 8)
+    decoder = escape_csv(decoder, None)
+    strong_id = escape_csv(strong_id, None)
+    json_metadata = escape_csv(json_metadata, None)
+    return (f'{shots},'
+            f'{errors},'
+            f'{discards},'
+            f'{seconds},'
+            f'{decoder},'
+            f'{strong_id},'
+            f'{json_metadata},'
+            f'{custom_counts}')
+
+
+CSV_HEADER = csv_line(shots='shots',
+                      errors='errors',
+                      discards='discards',
+                      seconds='seconds',
+                      strong_id='strong_id',
+                      decoder='decoder',
+                      json_metadata='json_metadata',
+                      custom_counts='custom_counts',
+                      is_header=True)

sinter/_data/_existing_data.py

@@ -0,0 +1,173 @@
+import collections
+import json
+import pathlib
+from typing import Any, Dict, List, TYPE_CHECKING
+
+from sinter._data._task_stats import TaskStats
+from sinter._data._task import Task
+from sinter._data._anon_task_stats import AnonTaskStats
+
+if TYPE_CHECKING:
+    import sinter
+
+
+class ExistingData:
+    def __init__(self):
+        self.data: Dict[str, TaskStats] = {}
+
+    def stats_for(self, case: Task) -> AnonTaskStats:
+        if isinstance(case, Task):
+            key = case.strong_id()
+        else:
+            raise NotImplementedError(f'{type(case)}')
+        if key not in self.data:
+            return AnonTaskStats()
+        return self.data[key].to_anon_stats()
+
+    def add_sample(self, sample: TaskStats) -> None:
+        k = sample.strong_id
+        current = self.data.get(k)
+        if current is not None:
+            self.data[k] = current + sample
+        else:
+            self.data[k] = sample
+
+    def __iadd__(self, other: 'ExistingData') -> 'ExistingData':
+        for sample in other.data.values():
+            self.add_sample(sample)
+        return self
+
+    @staticmethod
+    def from_file(path_or_file: Any) -> 'ExistingData':
+        expected_fields = {
+            "shots",
+            "discards",
+            "errors",
+            "seconds",
+            "strong_id",
+            "decoder",
+            "json_metadata",
+        }
+        # Import is done locally to reduce cost of importing sinter.
+        import csv
+        if isinstance(path_or_file, (str, pathlib.Path)):
+            with open(path_or_file) as csvfile:
+                return ExistingData.from_file(csvfile)
+        reader = csv.DictReader(path_or_file)
+        reader.fieldnames = [e.strip() for e in reader.fieldnames]
+        actual_fields = set(reader.fieldnames)
+        if not (expected_fields <= actual_fields):
+            raise ValueError(
+                f"Bad CSV data. "
+                f"Got columns {sorted(actual_fields)!r} "
+                f"but expected columns {sorted(expected_fields)!r}")
+        has_custom_counts = 'custom_counts' in actual_fields
+        result = ExistingData()
+        for row in reader:
+            if has_custom_counts:
+                custom_counts = row['custom_counts']
+                if custom_counts is None or custom_counts == '':
+                    custom_counts = collections.Counter()
+                else:
+                    custom_counts = json.loads(custom_counts)
+                    if not isinstance(custom_counts, dict) or not all(isinstance(k, str) or not isinstance(v, int) for k, v in custom_counts.items()):
+                        raise ValueError(f"{row['custom_counts']=} isn't empty or a dictionary from string keys to integer values.")
+                    custom_counts = collections.Counter(custom_counts)
+            else:
+                custom_counts = collections.Counter()
+            result.add_sample(TaskStats(
+                shots=int(row['shots']),
+                discards=int(row['discards']),
+                errors=int(row['errors']),
+                custom_counts=custom_counts,
+                seconds=float(row['seconds']),
+                strong_id=row['strong_id'],
+                decoder=row['decoder'],
+                json_metadata=json.loads(row['json_metadata']),
+            ))
+        return result
+
+
+def stats_from_csv_files(*paths_or_files: Any) -> List['sinter.TaskStats']:
+    """Reads and aggregates shot statistics from CSV files.
+
+    (An old alias of `read_stats_from_csv_files`, kept around for backwards
+    compatibility.)
+
+    Assumes the CSV file was written by printing `sinter.CSV_HEADER` and then
+    a list of `sinter.TaskStats`. When statistics from the same task appear
+    in multiple files (identified by the strong id being the same), the
+    statistics for that task are folded together (so only the total shots,
+    total errors, etc for each task are included in the results).
+
+    Args:
+        *paths_or_files: Each argument should be either a path (in the form of
+            a string or a pathlib.Path) or a TextIO object (e.g. as returned by
+            `open`). File data is read from each argument.
+
+    Returns:
+        A list of task stats, where each task appears only once in the list and
+        the stats associated with it are the totals aggregated from all files.
+
+    Examples:
+        >>> import sinter
+        >>> import io
+        >>> in_memory_file = io.StringIO()
+        >>> _ = in_memory_file.write('''
+        ...     shots,errors,discards,seconds,decoder,strong_id,json_metadata
+        ...     1000,42,0,0.125,pymatching,9c31908e2b,"{""d"":9}"
+        ...     3000,24,0,0.125,pymatching,9c31908e2b,"{""d"":9}"
+        ...     1000,250,0,0.125,pymatching,deadbeef08,"{""d"":7}"
+        ... '''.strip())
+        >>> _ = in_memory_file.seek(0)
+        >>> stats = sinter.stats_from_csv_files(in_memory_file)
+        >>> for stat in stats:
+        ...     print(repr(stat))
+        sinter.TaskStats(strong_id='9c31908e2b', decoder='pymatching', json_metadata={'d': 9}, shots=4000, errors=66, seconds=0.25)
+        sinter.TaskStats(strong_id='deadbeef08', decoder='pymatching', json_metadata={'d': 7}, shots=1000, errors=250, seconds=0.125)
+    """
+    result = ExistingData()
+    for p in paths_or_files:
+        result += ExistingData.from_file(p)
+    return list(result.data.values())
+
+
+def read_stats_from_csv_files(*paths_or_files: Any) -> List['sinter.TaskStats']:
+    """Reads and aggregates shot statistics from CSV files.
+
+    Assumes the CSV file was written by printing `sinter.CSV_HEADER` and then
+    a list of `sinter.TaskStats`. When statistics from the same task appear
+    in multiple files (identified by the strong id being the same), the
+    statistics for that task are folded together (so only the total shots,
+    total errors, etc for each task are included in the results).
+
+    Args:
+        *paths_or_files: Each argument should be either a path (in the form of
+            a string or a pathlib.Path) or a TextIO object (e.g. as returned by
+            `open`). File data is read from each argument.
+
+    Returns:
+        A list of task stats, where each task appears only once in the list and
+        the stats associated with it are the totals aggregated from all files.
+
+    Examples:
+        >>> import sinter
+        >>> import io
+        >>> in_memory_file = io.StringIO()
+        >>> _ = in_memory_file.write('''
+        ...     shots,errors,discards,seconds,decoder,strong_id,json_metadata
+        ...     1000,42,0,0.125,pymatching,9c31908e2b,"{""d"":9}"
+        ...     3000,24,0,0.125,pymatching,9c31908e2b,"{""d"":9}"
+        ...     1000,250,0,0.125,pymatching,deadbeef08,"{""d"":7}"
+        ... '''.strip())
+        >>> _ = in_memory_file.seek(0)
+        >>> stats = sinter.read_stats_from_csv_files(in_memory_file)
+        >>> for stat in stats:
+        ...     print(repr(stat))
+        sinter.TaskStats(strong_id='9c31908e2b', decoder='pymatching', json_metadata={'d': 9}, shots=4000, errors=66, seconds=0.25)
+        sinter.TaskStats(strong_id='deadbeef08', decoder='pymatching', json_metadata={'d': 7}, shots=1000, errors=250, seconds=0.125)
+    """
+    result = ExistingData()
+    for p in paths_or_files:
+        result += ExistingData.from_file(p)
+    return list(result.data.values())

sinter/_data/_existing_data_test.py

@@ -0,0 +1,41 @@
+import collections
+import pathlib
+import tempfile
+
+import sinter
+
+
+def test_read_stats_from_csv_files():
+    with tempfile.TemporaryDirectory() as d:
+        d = pathlib.Path(d)
+
+        with open(d / 'tmp.csv', 'w') as f:
+            print("""
+shots,errors,discards,seconds,decoder,strong_id,json_metadata
+  300,     1,      20,    1.0,pymatching,abc123,"{""d"":3}"
+ 1000,     3,      40,    3.0,pymatching,abc123,"{""d"":3}"
+ 2000,     0,      10,    2.0,pymatching,def456,"{""d"":5}"
+    """.strip(), file=f)
+
+        assert sinter.read_stats_from_csv_files(d / 'tmp.csv') == [
+            sinter.TaskStats(strong_id='abc123', decoder='pymatching', json_metadata={'d': 3}, shots=1300, errors=4, discards=60, seconds=4.0),
+            sinter.TaskStats(strong_id='def456', decoder='pymatching', json_metadata={'d': 5}, shots=2000, errors=0, discards=10, seconds=2.0),
+        ]
+
+        with open(d / 'tmp2.csv', 'w') as f:
+            print("""
+shots,errors,discards,seconds,decoder,strong_id,json_metadata,custom_counts
+  300,     1,      20,    1.0,pymatching,abc123,"{""d"":3}","{""dets"":1234}"
+ 1000,     3,      40,    3.0,pymatching,abc123,"{""d"":3}",
+ 2000,     0,      10,    2.0,pymatching,def456,"{""d"":5}"
+    """.strip(), file=f)
+
+        assert sinter.read_stats_from_csv_files(d / 'tmp2.csv') == [
+            sinter.TaskStats(strong_id='abc123', decoder='pymatching', json_metadata={'d': 3}, shots=1300, errors=4, discards=60, seconds=4.0, custom_counts=collections.Counter({'dets': 1234})),
+            sinter.TaskStats(strong_id='def456', decoder='pymatching', json_metadata={'d': 5}, shots=2000, errors=0, discards=10, seconds=2.0),
+        ]
+
+        assert sinter.read_stats_from_csv_files(d / 'tmp.csv', d / 'tmp2.csv') == [
+            sinter.TaskStats(strong_id='abc123', decoder='pymatching', json_metadata={'d': 3}, shots=2600, errors=8, discards=120, seconds=8.0, custom_counts=collections.Counter({'dets': 1234})),
+            sinter.TaskStats(strong_id='def456', decoder='pymatching', json_metadata={'d': 5}, shots=4000, errors=0, discards=20, seconds=4.0),
+        ]