sinter 1.15.0__py3-none-any.whl

sinter/_decoding/_decoding_decoder_class.py

@@ -0,0 +1,161 @@
+import abc
+import pathlib
+
+import numpy as np
+import stim
+
+
+class CompiledDecoder(metaclass=abc.ABCMeta):
+    """Abstract class for decoders preconfigured to a specific decoding task.
+
+    This is the type returned by `sinter.Decoder.compile_decoder_for_dem`. The
+    idea is that, when many shots of the same decoding task are going to be
+    performed, it is valuable to pay the cost of configuring the decoder only
+    once instead of once per batch of shots. Custom decoders can optionally
+    implement that method, and return this type, to increase sampling
+    efficiency.
+    """
+
+    @abc.abstractmethod
+    def decode_shots_bit_packed(
+            self,
+            *,
+            bit_packed_detection_event_data: np.ndarray,
+    ) -> np.ndarray:
+        """Predicts observable flips from the given detection events.
+
+        All data taken and returned must be bit packed with bitorder='little'.
+
+        Args:
+            bit_packed_detection_event_data: Detection event data stored as a
+                bit packed numpy array. The numpy array will have the following
+                dtype/shape:
+
+                    dtype: uint8
+                    shape: (num_shots, ceil(dem.num_detectors / 8))
+
+                where `num_shots` is the number of shots to decoder and `dem` is
+                the detector error model this instance was compiled to decode.
+
+                It's guaranteed that the data will be laid out in memory so that
+                detection events within a shot are contiguous in memory (i.e.
+                that bit_packed_detection_event_data.strides[1] == 1).
+
+        Returns:
+            Bit packed observable flip data stored as a bit packed numpy array.
+            The numpy array must have the following dtype/shape:
+
+                dtype: uint8
+                shape: (num_shots, ceil(dem.num_observables / 8))
+
+            where `num_shots` is bit_packed_detection_event_data.shape[0] and
+            `dem` is the detector error model this instance was compiled to
+            decode.
+        """
+        pass
+
+
+class Decoder:
+    """Abstract base class for custom decoders.
+
+    Custom decoders can be explained to sinter by inheriting from this class and
+    implementing its methods.
+
+    Decoder classes MUST be serializable (e.g. via pickling), so that they can
+    be given to worker processes when using python multiprocessing.
+
+    Child classes should implement `compile_decoder_for_dem`, but (for legacy
+    reasons) can alternatively implement `decode_via_files`. At least one of
+    the two methods must be implemented.
+    """
+
+    def compile_decoder_for_dem(
+        self,
+        *,
+        dem: stim.DetectorErrorModel,
+    ) -> CompiledDecoder:
+        """Creates a decoder preconfigured for the given detector error model.
+
+        This method is optional to implement. By default, it will raise a
+        NotImplementedError. When sampling, sinter will attempt to use this
+        method first and otherwise fallback to using `decode_via_files`.
+
+        The idea is that the preconfigured decoder amortizes the cost of
+        configuration over more calls. This makes smaller batch sizes efficient,
+        reducing the amount of memory used for storing each batch, improving
+        overall efficiency.
+
+        Args:
+            dem: A detector error model for the samples that will need to be
+                decoded. What to configure the decoder to decode.
+
+        Returns:
+            An instance of `sinter.CompiledDecoder` that can be used to invoke
+            the preconfigured decoder.
+
+        Raises:
+            NotImplementedError: This `sinter.Decoder` doesn't support compiling
+                for a dem.
+        """
+        raise NotImplementedError('compile_decoder_for_dem')
+
+    def decode_via_files(self,
+                         *,
+                         num_shots: int,
+                         num_dets: int,
+                         num_obs: int,
+                         dem_path: pathlib.Path,
+                         dets_b8_in_path: pathlib.Path,
+                         obs_predictions_b8_out_path: pathlib.Path,
+                         tmp_dir: pathlib.Path,
+                       ) -> None:
+        """Performs decoding by reading/writing problems and answers from disk.
+
+        Args:
+            num_shots: The number of times the circuit was sampled. The number
+                of problems to be solved.
+            num_dets: The number of detectors in the circuit. The number of
+                detection event bits in each shot.
+            num_obs: The number of observables in the circuit. The number of
+                predicted bits in each shot.
+            dem_path: The file path where the detector error model should be
+                read from, e.g. using `stim.DetectorErrorModel.from_file`. The
+                error mechanisms specified by the detector error model should be
+                used to configure the decoder.
+            dets_b8_in_path: The file path that detection event data should be
+                read from. Note that the file may be a named pipe instead of a
+                fixed size object. The detection events will be in b8 format
+                (see
+                https://github.com/quantumlib/Stim/blob/main/doc/result_formats.md
+                ). The number of detection events per shot is available via the
+                `num_dets` argument or via the detector error model at
+                `dem_path`.
+            obs_predictions_b8_out_path: The file path that decoder predictions
+                must be written to. The predictions must be written in b8 format
+                (see
+                https://github.com/quantumlib/Stim/blob/main/doc/result_formats.md
+                ). The number of observables per shot is available via the
+                `num_obs` argument or via the detector error model at
+                `dem_path`.
+            tmp_dir: Any temporary files generated by the decoder during its
+                operation MUST be put into this directory. The reason for this
+                requirement is because sinter is allowed to kill the decoding
+                process without warning, without giving it time to clean up any
+                temporary objects. All cleanup should be done via sinter
+                deleting this directory after killing the decoder.
+        """
+        dem = stim.DetectorErrorModel.from_file(dem_path)
+
+        try:
+            compiled = self.compile_decoder_for_dem(dem=dem)
+        except NotImplementedError as ex:
+            raise NotImplementedError(f"{type(self).__qualname__} didn't implement `compile_decoder_for_dem` or `decode_via_files`.") from ex
+
+        num_det_bytes = -(-num_dets // 8)
+        num_obs_bytes = -(-num_obs // 8)
+        dets = np.fromfile(dets_b8_in_path, dtype=np.uint8, count=num_shots * num_det_bytes)
+        dets = dets.reshape(num_shots, num_det_bytes)
+        obs = compiled.decode_shots_bit_packed(bit_packed_detection_event_data=dets)
+        if obs.dtype != np.uint8 or obs.shape != (num_shots, num_obs_bytes):
+            raise ValueError(f"Got a numpy array with dtype={obs.dtype},shape={obs.shape} instead of dtype={np.uint8},shape={(num_shots, num_obs_bytes)} from {type(self).__qualname__}(...).compile_decoder_for_dem(...).decode_shots_bit_packed(...).")
+        obs.tofile(obs_predictions_b8_out_path)

sinter/_decoding/_decoding_fusion_blossom.py

@@ -0,0 +1,193 @@
+import math
+import pathlib
+from typing import Callable, List, TYPE_CHECKING, Tuple
+
+import numpy as np
+import stim
+
+from sinter._decoding._decoding_decoder_class import Decoder, CompiledDecoder
+
+if TYPE_CHECKING:
+    import fusion_blossom
+
+
+class FusionBlossomCompiledDecoder(CompiledDecoder):
+    def __init__(self, solver: 'fusion_blossom.SolverSerial', fault_masks: 'np.ndarray', num_dets: int, num_obs: int):
+        self.solver = solver
+        self.fault_masks = fault_masks
+        self.num_dets = num_dets
+        self.num_obs = num_obs
+
+    def decode_shots_bit_packed(
+            self,
+            *,
+            bit_packed_detection_event_data: 'np.ndarray',
+    ) -> 'np.ndarray':
+        num_shots = bit_packed_detection_event_data.shape[0]
+        predictions = np.zeros(shape=(num_shots, (self.num_obs + 7) // 8), dtype=np.uint8)
+        import fusion_blossom
+        for shot in range(num_shots):
+            dets_sparse = np.flatnonzero(np.unpackbits(bit_packed_detection_event_data[shot], count=self.num_dets, bitorder='little'))
+            syndrome = fusion_blossom.SyndromePattern(syndrome_vertices=dets_sparse)
+            self.solver.solve(syndrome)
+            prediction = int(np.bitwise_xor.reduce(self.fault_masks[self.solver.subgraph()]))
+            predictions[shot] = np.packbits(
+                np.array(list(np.binary_repr(prediction, width=self.num_obs))[::-1],dtype=np.uint8),
+                bitorder="little",
+            )
+            self.solver.clear()
+        return predictions
+
+
+class FusionBlossomDecoder(Decoder):
+    """Use fusion blossom to predict observables from detection events."""
+
+    def compile_decoder_for_dem(self, *, dem: 'stim.DetectorErrorModel') -> CompiledDecoder:
+        try:
+            import fusion_blossom
+        except ImportError as ex:
+            raise ImportError(
+                "The decoder 'fusion_blossom' isn't installed\n"
+                "To fix this, install the python package 'fusion_blossom' into your environment.\n"
+                "For example, if you are using pip, run `pip install fusion_blossom`.\n"
+            ) from ex
+
+        solver, fault_masks = detector_error_model_to_fusion_blossom_solver_and_fault_masks(dem)
+        return FusionBlossomCompiledDecoder(solver, fault_masks, dem.num_detectors, dem.num_observables)
+
+
+    def decode_via_files(self,
+                         *,
+                         num_shots: int,
+                         num_dets: int,
+                         num_obs: int,
+                         dem_path: pathlib.Path,
+                         dets_b8_in_path: pathlib.Path,
+                         obs_predictions_b8_out_path: pathlib.Path,
+                         tmp_dir: pathlib.Path,
+                       ) -> None:
+        try:
+            import fusion_blossom
+        except ImportError as ex:
+            raise ImportError(
+                "The decoder 'fusion_blossom' isn't installed\n"
+                "To fix this, install the python package 'fusion-blossom' into your environment.\n"
+                "For example, if you are using pip, run `pip install fusion-blossom~=0.1.4`.\n"
+            ) from ex
+
+        error_model = stim.DetectorErrorModel.from_file(dem_path)
+        solver, fault_masks = detector_error_model_to_fusion_blossom_solver_and_fault_masks(error_model)
+        num_det_bytes = math.ceil(num_dets / 8)
+        with open(dets_b8_in_path, 'rb') as dets_in_f:
+            with open(obs_predictions_b8_out_path, 'wb') as obs_out_f:
+                for _ in range(num_shots):
+                    dets_bit_packed = np.fromfile(dets_in_f, dtype=np.uint8, count=num_det_bytes)
+                    if dets_bit_packed.shape != (num_det_bytes,):
+                        raise IOError('Missing dets data.')
+                    dets_sparse = np.flatnonzero(np.unpackbits(dets_bit_packed, count=num_dets, bitorder='little'))
+                    syndrome = fusion_blossom.SyndromePattern(syndrome_vertices=dets_sparse)
+                    solver.solve(syndrome)
+                    prediction = int(np.bitwise_xor.reduce(fault_masks[solver.subgraph()]))
+                    obs_out_f.write(prediction.to_bytes((num_obs + 7) // 8, byteorder='little'))
+                    solver.clear()
+
+
+def iter_flatten_model(model: stim.DetectorErrorModel,
+                       handle_error: Callable[[float, List[int], List[int]], None],
+                       handle_detector_coords: Callable[[int, np.ndarray], None]):
+    det_offset = 0
+    coords_offset = np.zeros(100, dtype=np.float64)
+
+    def _helper(m: stim.DetectorErrorModel, reps: int):
+        nonlocal det_offset
+        nonlocal coords_offset
+        for _ in range(reps):
+            for instruction in m:
+                if isinstance(instruction, stim.DemRepeatBlock):
+                    _helper(instruction.body_copy(), instruction.repeat_count)
+                elif isinstance(instruction, stim.DemInstruction):
+                    if instruction.type == "error":
+                        dets: List[int] = []
+                        frames: List[int] = []
+                        t: stim.DemTarget
+                        p = instruction.args_copy()[0]
+                        for t in instruction.targets_copy():
+                            if t.is_relative_detector_id():
+                                dets.append(t.val + det_offset)
+                            elif t.is_logical_observable_id():
+                                frames.append(t.val)
+                            elif t.is_separator():
+                                # Treat each component of a decomposed error as an independent error.
+                                # (Ideally we could configure some sort of correlated analysis; oh well.)
+                                handle_error(p, dets, frames)
+                                frames = []
+                                dets = []
+                        # Handle last component.
+                        handle_error(p, dets, frames)
+                    elif instruction.type == "shift_detectors":
+                        det_offset += instruction.targets_copy()[0]
+                        a = np.array(instruction.args_copy())
+                        coords_offset[:len(a)] += a
+                    elif instruction.type == "detector":
+                        a = np.array(instruction.args_copy())
+                        for t in instruction.targets_copy():
+                            handle_detector_coords(t.val + det_offset, a + coords_offset[:len(a)])
+                    elif instruction.type == "logical_observable":
+                        pass
+                    else:
+                        raise NotImplementedError()
+                else:
+                    raise NotImplementedError()
+    _helper(model, 1)
+
+
+def detector_error_model_to_fusion_blossom_solver_and_fault_masks(model: stim.DetectorErrorModel) -> Tuple['fusion_blossom.SolverSerial', np.ndarray]:
+    """Convert a stim error model into a NetworkX graph."""
+
+    import fusion_blossom
+
+    def handle_error(p: float, dets: List[int], frame_changes: List[int]):
+        if p == 0:
+            return
+        if len(dets) == 0:
+            # No symptoms for this error.
+            # Code probably has distance 1.
+            # Accept it and keep going, though of course decoding will probably perform terribly.
+            return
+        if len(dets) == 1:
+            dets = [dets[0], num_detectors]
+        if len(dets) > 2:
+            raise NotImplementedError(
+                f"Error with more than 2 symptoms can't become an edge or boundary edge: {dets!r}.")
+        if p > 0.5:
+            # fusion_blossom doesn't support negative edge weights.
+            # approximate them as weight 0.
+            p = 0.5
+        weight = math.log((1 - p) / p)
+        mask = sum(1 << k for k in frame_changes)
+        edges.append((dets[0], dets[1], weight, mask))
+
+    def handle_detector_coords(detector: int, coords: np.ndarray):
+        pass
+
+    num_detectors = model.num_detectors
+    edges: List[Tuple[int, int, float, int]] = []
+    iter_flatten_model(
+        model,
+        handle_error=handle_error,
+        handle_detector_coords=handle_detector_coords,
+    )
+    max_weight = max(1e-4, max((w for _, _, w, _ in edges), default=1))
+    rescaled_edges = [
+        (a, b, round(w * 2**10 / max_weight) * 2)
+        for a, b, w, _ in edges
+    ]
+    fault_masks = np.array([e[3] for e in edges], dtype=np.uint64)
+
+    initializer = fusion_blossom.SolverInitializer(
+        num_detectors + 1,  # Total number of nodes.
+        rescaled_edges,  # Weighted edges.
+        [num_detectors],  # Boundary node.
+    )
+
+    return fusion_blossom.SolverSerial(initializer), fault_masks

sinter/_decoding/_decoding_mwpf.py

@@ -0,0 +1,302 @@
+import math
+import pathlib
+from typing import Callable, List, TYPE_CHECKING, Tuple, Any, Optional
+
+import numpy as np
+import stim
+
+from sinter._decoding._decoding_decoder_class import Decoder, CompiledDecoder
+
+if TYPE_CHECKING:
+    import mwpf
+
+
+def mwpf_import_error() -> ImportError:
+    return ImportError(
+        "The decoder 'MWPF' isn't installed\n"
+        "To fix this, install the python package 'MWPF' into your environment.\n"
+        "For example, if you are using pip, run `pip install MWPF~=0.1.5`.\n"
+    )
+
+
+class MwpfCompiledDecoder(CompiledDecoder):
+    def __init__(
+        self,
+        solver: "mwpf.SolverSerialJointSingleHair",
+        fault_masks: "np.ndarray",
+        num_dets: int,
+        num_obs: int,
+    ):
+        self.solver = solver
+        self.fault_masks = fault_masks
+        self.num_dets = num_dets
+        self.num_obs = num_obs
+
+    def decode_shots_bit_packed(
+        self,
+        *,
+        bit_packed_detection_event_data: "np.ndarray",
+    ) -> "np.ndarray":
+        num_shots = bit_packed_detection_event_data.shape[0]
+        predictions = np.zeros(
+            shape=(num_shots, (self.num_obs + 7) // 8), dtype=np.uint8
+        )
+        import mwpf
+
+        for shot in range(num_shots):
+            dets_sparse = np.flatnonzero(
+                np.unpackbits(
+                    bit_packed_detection_event_data[shot],
+                    count=self.num_dets,
+                    bitorder="little",
+                )
+            )
+            syndrome = mwpf.SyndromePattern(defect_vertices=dets_sparse)
+            if self.solver is None:
+                prediction = 0
+            else:
+                self.solver.solve(syndrome)
+                prediction = int(
+                    np.bitwise_xor.reduce(self.fault_masks[self.solver.subgraph()])
+                )
+                self.solver.clear()
+            predictions[shot] = np.packbits(
+                np.array(
+                    list(np.binary_repr(prediction, width=self.num_obs))[::-1],
+                    dtype=np.uint8,
+                ),
+                bitorder="little",
+            )
+        return predictions
+
+
+class MwpfDecoder(Decoder):
+    """Use MWPF to predict observables from detection events."""
+
+    def __init__(
+        self,
+        decoder_cls: Any = None,  # decoder class used to construct the MWPF decoder.
+        # in the Rust implementation, all of them inherits from the class of `SolverSerialPlugins`
+        # but just provide different plugins for optimizing the primal and/or dual solutions.
+        # For example, `SolverSerialUnionFind` is the most basic solver without any plugin: it only
+        # grows the clusters until the first valid solution appears; some more optimized solvers uses
+        # one or more plugins to further optimize the solution, which requires longer decoding time.
+        cluster_node_limit: int = 50,  # The maximum number of nodes in a cluster,
+    ):
+        self.decoder_cls = decoder_cls
+        self.cluster_node_limit = cluster_node_limit
+        super().__init__()
+
+    def compile_decoder_for_dem(
+        self,
+        *,
+        dem: "stim.DetectorErrorModel",
+    ) -> CompiledDecoder:
+        solver, fault_masks = detector_error_model_to_mwpf_solver_and_fault_masks(
+            dem,
+            decoder_cls=self.decoder_cls,
+            cluster_node_limit=self.cluster_node_limit,
+        )
+        return MwpfCompiledDecoder(
+            solver,
+            fault_masks,
+            dem.num_detectors,
+            dem.num_observables,
+        )
+
+    def decode_via_files(
+        self,
+        *,
+        num_shots: int,
+        num_dets: int,
+        num_obs: int,
+        dem_path: pathlib.Path,
+        dets_b8_in_path: pathlib.Path,
+        obs_predictions_b8_out_path: pathlib.Path,
+        tmp_dir: pathlib.Path,
+    ) -> None:
+        import mwpf
+
+        error_model = stim.DetectorErrorModel.from_file(dem_path)
+        solver, fault_masks = detector_error_model_to_mwpf_solver_and_fault_masks(
+            error_model,
+            decoder_cls=self.decoder_cls,
+            cluster_node_limit=self.cluster_node_limit,
+        )
+        num_det_bytes = math.ceil(num_dets / 8)
+        with open(dets_b8_in_path, "rb") as dets_in_f:
+            with open(obs_predictions_b8_out_path, "wb") as obs_out_f:
+                for _ in range(num_shots):
+                    dets_bit_packed = np.fromfile(
+                        dets_in_f, dtype=np.uint8, count=num_det_bytes
+                    )
+                    if dets_bit_packed.shape != (num_det_bytes,):
+                        raise IOError("Missing dets data.")
+                    dets_sparse = np.flatnonzero(
+                        np.unpackbits(
+                            dets_bit_packed, count=num_dets, bitorder="little"
+                        )
+                    )
+                    syndrome = mwpf.SyndromePattern(defect_vertices=dets_sparse)
+                    if solver is None:
+                        prediction = 0
+                    else:
+                        solver.solve(syndrome)
+                        prediction = int(
+                            np.bitwise_xor.reduce(fault_masks[solver.subgraph()])
+                        )
+                        solver.clear()
+                    obs_out_f.write(
+                        prediction.to_bytes((num_obs + 7) // 8, byteorder="little")
+                    )
+
+
+class HyperUFDecoder(MwpfDecoder):
+    def __init__(self):
+        super().__init__(decoder_cls="SolverSerialUnionFind", cluster_node_limit=0)
+
+
+def iter_flatten_model(
+    model: stim.DetectorErrorModel,
+    handle_error: Callable[[float, List[int], List[int]], None],
+    handle_detector_coords: Callable[[int, np.ndarray], None],
+):
+    det_offset = 0
+    coords_offset = np.zeros(100, dtype=np.float64)
+
+    def _helper(m: stim.DetectorErrorModel, reps: int):
+        nonlocal det_offset
+        nonlocal coords_offset
+        for _ in range(reps):
+            for instruction in m:
+                if isinstance(instruction, stim.DemRepeatBlock):
+                    _helper(instruction.body_copy(), instruction.repeat_count)
+                elif isinstance(instruction, stim.DemInstruction):
+                    if instruction.type == "error":
+                        dets: set[int] = set()
+                        frames: set[int] = set()
+                        t: stim.DemTarget
+                        p = instruction.args_copy()[0]
+                        for t in instruction.targets_copy():
+                            if t.is_relative_detector_id():
+                                dets ^= {t.val + det_offset}
+                            elif t.is_logical_observable_id():
+                                frames ^= {t.val}
+                        handle_error(p, list(dets), list(frames))
+                    elif instruction.type == "shift_detectors":
+                        det_offset += instruction.targets_copy()[0]
+                        a = np.array(instruction.args_copy())
+                        coords_offset[: len(a)] += a
+                    elif instruction.type == "detector":
+                        a = np.array(instruction.args_copy())
+                        for t in instruction.targets_copy():
+                            handle_detector_coords(
+                                t.val + det_offset, a + coords_offset[: len(a)]
+                            )
+                    elif instruction.type == "logical_observable":
+                        pass
+                    else:
+                        raise NotImplementedError()
+                else:
+                    raise NotImplementedError()
+
+    _helper(model, 1)
+
+
+def deduplicate_hyperedges(
+    hyperedges: List[Tuple[List[int], float, int]]
+) -> List[Tuple[List[int], float, int]]:
+    indices: dict[frozenset[int], Tuple[int, float]] = dict()
+    result: List[Tuple[List[int], float, int]] = []
+    for dets, weight, mask in hyperedges:
+        dets_set = frozenset(dets)
+        if dets_set in indices:
+            idx, min_weight = indices[dets_set]
+            p1 = 1 / (1 + math.exp(weight))
+            p2 = 1 / (1 + math.exp(result[idx][1]))
+            p = p1 * (1 - p2) + p2 * (1 - p1)
+            # choosing the mask from the most likely error
+            new_mask = result[idx][2]
+            if weight < min_weight:
+                indices[dets_set] = (idx, weight)
+                new_mask = mask
+            result[idx] = (dets, math.log((1 - p) / p), new_mask)
+        else:
+            indices[dets_set] = (len(result), weight)
+            result.append((dets, weight, mask))
+    return result
+
+
+def detector_error_model_to_mwpf_solver_and_fault_masks(
+    model: stim.DetectorErrorModel,
+    decoder_cls: Any = None,
+    cluster_node_limit: int = 50,
+) -> Tuple[Optional["mwpf.SolverSerialJointSingleHair"], np.ndarray]:
+    """Convert a stim error model into a NetworkX graph."""
+
+    try:
+        import mwpf
+    except ImportError as ex:
+        raise mwpf_import_error() from ex
+
+    num_detectors = model.num_detectors
+    is_detector_connected = np.full(num_detectors, False, dtype=bool)
+    hyperedges: List[Tuple[List[int], float, int]] = []
+
+    def handle_error(p: float, dets: List[int], frame_changes: List[int]):
+        if p == 0:
+            return
+        if len(dets) == 0:
+            # No symptoms for this error.
+            # Code probably has distance 1.
+            # Accept it and keep going, though of course decoding will probably perform terribly.
+            return
+        if p > 0.5:
+            # mwpf doesn't support negative edge weights (yet, will be supported in the next version).
+            # approximate them as weight 0.
+            p = 0.5
+        weight = math.log((1 - p) / p)
+        mask = sum(1 << k for k in frame_changes)
+        is_detector_connected[dets] = True
+        hyperedges.append((dets, weight, mask))
+
+    def handle_detector_coords(detector: int, coords: np.ndarray):
+        pass
+
+    iter_flatten_model(
+        model,
+        handle_error=handle_error,
+        handle_detector_coords=handle_detector_coords,
+    )
+    # mwpf package panic on duplicate edges, thus we need to handle them here
+    hyperedges = deduplicate_hyperedges(hyperedges)
+
+    # fix the input by connecting an edge to all isolated vertices; will be supported in the next version
+    for idx in range(num_detectors):
+        if not is_detector_connected[idx]:
+            hyperedges.append(([idx], 0, 0))
+
+    max_weight = max(1e-4, max((w for _, w, _ in hyperedges), default=1))
+    rescaled_edges = [
+        mwpf.HyperEdge(v, round(w * 2**10 / max_weight) * 2) for v, w, _ in hyperedges
+    ]
+    fault_masks = np.array([e[2] for e in hyperedges], dtype=np.uint64)
+
+    initializer = mwpf.SolverInitializer(
+        num_detectors,  # Total number of nodes.
+        rescaled_edges,  # Weighted edges.
+    )
+
+    if decoder_cls is None:
+        # default to the solver with highest accuracy
+        decoder_cls = mwpf.SolverSerialJointSingleHair
+    elif isinstance(decoder_cls, str):
+        decoder_cls = getattr(mwpf, decoder_cls)
+    return (
+        (
+            decoder_cls(initializer, config={"cluster_node_limit": cluster_node_limit})
+            if num_detectors > 0 and len(rescaled_edges) > 0
+            else None
+        ),
+        fault_masks,
+    )