deltakit-core 0.5.0__py3-none-any.whl

deltakit_core/__init__.py

@@ -0,0 +1,16 @@
+# (c) Copyright Riverlane 2020-2025.
+"""Description of ``deltakit.core`` namespace here."""
+
+import importlib.metadata
+
+# It looks like these were intended to be separate, public modules.
+# For now, import them as such. This can be reconsidered during API review.
+from . import decoding_graphs
+
+__version__ = importlib.metadata.version(__package__)
+
+# Prevent import of `importlib` (and any other non-public objects) from this module.
+del importlib
+
+# List only public members in `__all__`.
+__all__ = ["decoding_graphs"]

deltakit_core/data_formats/__init__.py

@@ -0,0 +1,33 @@
+# (c) Copyright Riverlane 2020-2025.
+"""
+Sub-package for data formats and converting them to other data types
+"""
+
+from deltakit_core.data_formats._b801_parsers import (
+    to_bytearray,
+    b8_to_syndromes,
+    b8_to_measurements,
+    b8_to_logical_flip,
+    syndromes_to_b8_file,
+    logical_flips_to_b8_file,
+    parse_01_to_logical_flips,
+    parse_01_to_syndromes,
+)
+from deltakit_core.data_formats._measurements import (
+    split_input_data_to_c64,
+    c64_to_addressed_input_words,
+)
+
+# List only public members in `__all__`.
+__all__ = [
+    "to_bytearray",
+    "b8_to_syndromes",
+    "b8_to_measurements",
+    "b8_to_logical_flip",
+    "syndromes_to_b8_file",
+    "logical_flips_to_b8_file",
+    "parse_01_to_logical_flips",
+    "parse_01_to_syndromes",
+    "split_input_data_to_c64",
+    "c64_to_addressed_input_words",
+]

deltakit_core/data_formats/_b801_parsers.py

@@ -0,0 +1,141 @@
+# (c) Copyright Riverlane 2020-2025.
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterator, Tuple
+
+import numpy as np
+from deltakit_core.decoding_graphs import Bitstring, OrderedSyndrome
+
+
+def to_bytearray(data: Path | bytes) -> bytearray:
+    """Converts either the content of a file or a bytes object to
+    a bytearray object. A key motivation for this is that np.unpackbits
+    accepts bytearray but not bytes."""
+    if isinstance(data, Path):
+        with open(data, "rb") as b8_data:
+            return bytearray(b8_data.read())
+    return bytearray(data)
+
+
+def b8_to_syndromes(
+    b8_input: Path | bytes, detector_num: int
+) -> Iterator[OrderedSyndrome]:
+    """Given a b8 input (either a file path containing b8 data or bytes),
+    and the number of detectors that should be in each syndrome, return a
+    generator of syndromes.
+
+    Informed by https://github.com/quantumlib/Stim/blob/main/doc/result_formats.md#b8
+    """
+    bytes_per_shot = (detector_num + 7) // 8
+    b8_byte_arr: bytearray = to_bytearray(b8_input)
+    for offset in range(0, len(b8_byte_arr), bytes_per_shot):
+        yield OrderedSyndrome.from_bitstring(
+            np.unpackbits(
+                np.frombuffer(b8_byte_arr[offset : offset + bytes_per_shot],
+                              dtype=np.uint8),
+                bitorder="little",
+            ).tolist()
+        )
+
+
+def b8_to_measurements(b8_input: Path, measurement_num: int) -> Iterator[Bitstring]:
+    """Given a b8 input (a file path containing b8 data),
+    and the number of measurements in each shot,
+    return a generator of measurement bitstrings.
+
+    Informed by https://github.com/quantumlib/Stim/blob/main/doc/result_formats.md#b8
+    """
+    bytes_per_shot = (measurement_num + 7) // 8
+    b8_byte_arr: bytearray = to_bytearray(b8_input)
+    for offset in range(0, len(b8_byte_arr), bytes_per_shot):
+        yield Bitstring.from_bits(
+            np.unpackbits(
+                np.frombuffer(b8_byte_arr[offset : offset + bytes_per_shot],
+                              dtype=np.uint8),
+                bitorder="little",
+            ).tolist()
+        )
+
+
+def b8_to_logical_flip(
+    b8_input: Path | bytes, num_logicals: int = 1
+) -> Iterator[Tuple[bool, ...]]:
+    """Given a b8 input (either a file path containing b8 data or bytes),
+    and the number of detectors that should be in each syndrome, return a
+    generator of logical flips.
+
+    Informed by https://github.com/quantumlib/Stim/blob/main/doc/result_formats.md#b8
+    """
+    bytes_per_shot = (num_logicals + 7) // 8
+    b8_byte_arr: bytearray = to_bytearray(b8_input)
+    for offset in range(0, len(b8_byte_arr), bytes_per_shot):
+        yield tuple(
+            np.unpackbits(
+                np.frombuffer(b8_byte_arr[offset : offset + bytes_per_shot],
+                              dtype=np.uint8),
+                bitorder="little",
+            )[:num_logicals].tolist(),
+        )
+
+
+def syndromes_to_b8_file(
+    syndrome_b8_out: Path, detector_num: int, syndromes: Iterator[OrderedSyndrome]
+):
+    """Given a syndrome generator, this will output them to file in the b8 format.
+    Informed by https://github.com/quantumlib/Stim/blob/main/doc/result_formats.md#b8
+    """
+    with open(syndrome_b8_out, "wb") as b8_out_handle:
+        for syndrome in syndromes:
+            b8_out_handle.write(
+                bytes(
+                    np.packbits(syndrome.as_bitstring(detector_num), bitorder="little")
+                )
+            )
+
+
+def logical_flips_to_b8_file(
+    logical_flips_b8_out: Path, logical_flips: Iterator[Tuple[bool, ...]]
+):
+    """Given a logical flip generator, this will output them to file in the b8 format.
+    b8 is a byte-padded bitstring representation for logical flips. This is more
+    efficient than the string-based 01 representation.
+    Informed by https://github.com/quantumlib/Stim/blob/main/doc/result_formats.md#b8
+    """
+    with open(logical_flips_b8_out, "wb") as data_b8:
+        for logical_flip in logical_flips:
+            data_b8.write(bytes(np.packbits(logical_flip, bitorder="little")))
+
+
+def parse_01_to_logical_flips(
+    logical_flips_01_file: Path,
+) -> Iterator[Tuple[bool, ...]]:
+    """Given a filepath for a 01 file containing target logical flips, return a
+    generator of logical flips as booleans.
+
+    01 files are string based, where each line is a different shot. Where 1
+    indicates the reference logical is flipped.
+
+    Use logical_flips_to_b8_file on the result of this function to translate 01
+    data to b8 data that can be decoded via the B8DecoderManager.
+    """
+    with open(logical_flips_01_file, "r", encoding="utf-8") as logical_flips_handle:
+        for bit_string in logical_flips_handle.read().splitlines():
+            yield tuple(char != "0" for char in bit_string)
+
+
+def parse_01_to_syndromes(
+    logical_flips_01_file: Path,
+) -> Iterator[OrderedSyndrome]:
+    """Given a filepath for a 01 file containing syndromes, return a
+    generator of OrderedSyndromes.
+
+    01 files are string based, where each line is a different target logical as a
+    string of 0s and 1s. Where 1 indicates the reference logical is flipped.
+
+    Use logical_flips_to_b8_file on the result of this function to translate 01
+    data to b8 data that can be decoded via the B8DecoderManager.
+    """
+    with open(logical_flips_01_file, "r", encoding="utf-8") as logical_flips_handle:
+        for bit_string in logical_flips_handle.read().splitlines():
+            yield OrderedSyndrome([i for i, v in enumerate(bit_string) if v == "1"])

deltakit_core/data_formats/_measurements.py

@@ -0,0 +1,58 @@
+# (c) Copyright Riverlane 2020-2025.
+import csv
+from itertools import cycle
+from pathlib import Path
+from typing import Iterable, Iterator, List, Tuple
+
+from deltakit_core.decoding_graphs import Bitstring
+
+
+def split_input_data_to_c64(
+    input_data: Iterable[Iterable[Bitstring]], output_path: Path
+):
+    """
+    Given a list of round-split decoder input data, this will output them to a file
+    as comma separated 64-bit integers. Each line is a new shot.
+
+    The decoder input data could be measurements or syndromes.
+    """
+    with open(output_path, "w", encoding="ascii") as output_handle:
+        cw = csv.writer(output_handle)
+        for input_datum in input_data:
+            words = [
+                int(item)
+                for line in [
+                    input_datum_round.to_words(64) for input_datum_round in input_datum
+                ]
+                for item in line
+            ]
+            cw.writerow(words)
+
+
+def c64_to_addressed_input_words(
+    input_path: Path, round_width: int
+) -> Iterator[List[Tuple[int, int]]]:
+    """Given a path to a c64 file, return, for each line, the words within the line
+    and the index of each word in each round. These are appropriate for input to a
+    hardware decoder, they could be syndromes or measurement data.
+
+    Parameters
+    ----------
+    input_path : Path
+        Path to the c64 file to read.
+    round_width : int
+        The number of detectors or measurements per round.
+
+    Yields
+    ------
+    List[Tuple[int, int]]
+        List of addressed 64bit words
+    """
+    with open(input_path, "r", encoding="ascii") as input_handle:
+        syndrome_reader = csv.reader(input_handle)
+        for row in syndrome_reader:
+            round_indices = cycle(range(round_width // 64 + 1))
+            yield [
+                (word_index, int(word_64))
+                for word_index, word_64 in zip(round_indices, row, strict=False)
+            ]

deltakit_core/decoding_graphs/__init__.py

@@ -0,0 +1,122 @@
+# (c) Copyright Riverlane 2020-2025.
+"""
+Sub-package for defining decoding graphs and related data types; these structures are
+used by many decoders to define their understanding of the code and noise model being
+decoded.
+"""
+
+from deltakit_core.decoding_graphs._data_qubits import (
+    DecodingEdge,
+    DecodingHyperEdge,
+    EdgeRecord,
+    EdgeT,
+    OrderedDecodingEdges,
+    errors_to_syndrome,
+)
+
+from deltakit_core.decoding_graphs._decoding_graph import (
+    AnyEdgeT,
+    DecodingCode,
+    DecodingHyperGraph,
+    DecodingHyperMultiGraph,
+    HyperLogicals,
+    HyperMultiGraph,
+    NXCode,
+    NXDecodingGraph,
+    NXDecodingMultiGraph,
+    NXLogicals,
+)
+
+from deltakit_core.decoding_graphs._dem_parsing import (
+    DemParser,
+    DetectorCounter,
+    DetectorRecorder,
+    LogicalsInEdges,
+    dem_to_decoding_graph_and_logicals,
+    dem_to_hypergraph_and_logicals,
+    observable_warning,
+)
+
+from deltakit_core.decoding_graphs._syndromes import (
+    Bitstring,
+    DetectorRecord,
+    FixedWidthBitstring,
+    OrderedSyndrome,
+    get_round_words,
+)
+
+from deltakit_core.decoding_graphs._weighted_graphs import (
+    change_graph_error_probabilities,
+    vector_weights,
+)
+
+from deltakit_core.decoding_graphs._decoding_graph_tools import (
+    compute_graph_distance,
+    compute_graph_distance_for_logical,
+    filter_to_data_edges,
+    filter_to_measure_edges,
+    graph_to_json,
+    has_contiguous_nodes,
+    hypergraph_to_weighted_edge_list,
+    inverse_logical_at_boundary,
+    is_single_connected_component,
+    single_boundary_is_last_node,
+    unweight_graph,
+    worst_case_num_detectors,
+)
+
+from deltakit_core.decoding_graphs._explained_dem_parsing import (
+    extract_logicals,
+    parse_explained_dem,
+)
+
+from deltakit_core.decoding_graphs._hypergraph_decomposition import decompositions
+
+# List only public members in `__all__`.
+__all__ = [
+    "DecodingEdge",
+    "DecodingHyperEdge",
+    "EdgeRecord",
+    "EdgeT",
+    "OrderedDecodingEdges",
+    "errors_to_syndrome",
+    "AnyEdgeT",
+    "DecodingCode",
+    "DecodingHyperGraph",
+    "DecodingHyperMultiGraph",
+    "HyperLogicals",
+    "HyperMultiGraph",
+    "NXCode",
+    "NXDecodingGraph",
+    "NXDecodingMultiGraph",
+    "NXLogicals",
+    "DemParser",
+    "DetectorCounter",
+    "DetectorRecorder",
+    "LogicalsInEdges",
+    "dem_to_decoding_graph_and_logicals",
+    "dem_to_hypergraph_and_logicals",
+    "observable_warning",
+    "Bitstring",
+    "DetectorRecord",
+    "FixedWidthBitstring",
+    "OrderedSyndrome",
+    "get_round_words",
+    "change_graph_error_probabilities",
+    "vector_weights",
+    "compute_graph_distance",
+    "compute_graph_distance_for_logical",
+    "filter_to_data_edges",
+    "filter_to_measure_edges",
+    "graph_to_json",
+    "has_contiguous_nodes",
+    "hypergraph_to_weighted_edge_list",
+    "inverse_logical_at_boundary",
+    "is_single_connected_component",
+    "single_boundary_is_last_node",
+    "unweight_graph",
+    "worst_case_num_detectors",
+    "extract_logicals",
+    "parse_explained_dem",
+    "decompositions",
+]