From e171a29db7c22e49533f9a515b93d86004bd7fd7 Mon Sep 17 00:00:00 2001 From: Rafael Haenel Date: Wed, 18 Nov 2026 11:57:51 -0700 Subject: [PATCH 1/3] feat(experimental): add shortest_errors, an exact fault-distance search shortest_errors(circuit, max_weight=k) returns every smallest set of faults that can flip an observable without flipping a detector, with the exact probabilities that the set goes undetected and flips an observable. Circuit errors with equal error-basis bits act identically, so they form one fault. Direct detectors are single f-bits, so sets whose direct detectors cancel are found by joining two tables of smaller sets on a linear hash; the statevector components then decide each candidate exactly by walking every measurement branch of their tape (statevector/branches.py). The builder now records each noise channel's instruction and target range, so faults are explained with stim.CircuitErrorLocation. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 11 + src/tsim/core/builder.py | 62 +++- src/tsim/core/parse.py | 31 +- src/tsim/experimental.py | 17 +- src/tsim/noise/faults.py | 418 +++++++++++++++++++++++++ src/tsim/statevector/branches.py | 263 ++++++++++++++++ test/unit/noise/test_faults.py | 299 ++++++++++++++++++ test/unit/statevector/test_branches.py | 115 +++++++ test/unit/test_public_api.py | 7 + 9 files changed, 1216 insertions(+), 7 deletions(-) create mode 100644 src/tsim/noise/faults.py create mode 100644 src/tsim/statevector/branches.py create mode 100644 test/unit/noise/test_faults.py create mode 100644 test/unit/statevector/test_branches.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e4e9b4d4..93df7c00 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added +- **Fault distance of non-Clifford circuits (experimental).** + `tsim.experimental.shortest_errors(circuit, max_weight=k)` returns every + smallest set of faults that can flip an observable without flipping a + detector, like Stim's `shortest_graphlike_error` but exact and for circuits + with T gates. Each result gives the probability that the faults go undetected + and that they flip an observable, and explains each fault with + `stim.CircuitErrorLocation`s. An empty result proves the distance exceeds `k`. + The fault distance of d=5 T-state cultivation (3, as found by + [Chan et al.](https://arxiv.org/abs/2609.17706)) takes 7 s. + ### Changed - The stabilizer-rank strategies compile components of the same shape once, and no longer run components with a single output without compiling them. A diff --git a/src/tsim/core/builder.py b/src/tsim/core/builder.py index fcfec89b..d3b10276 100644 --- a/src/tsim/core/builder.py +++ b/src/tsim/core/builder.py @@ -18,7 +18,7 @@ from dataclasses import dataclass from fractions import Fraction -from typing import Literal, get_args +from typing import Literal, NamedTuple, get_args import numpy as np from zxparam import Domain, EdgeType, Graph, Phase, Vertex, VertexType @@ -46,6 +46,23 @@ """The classical outputs of a built graph (see ``GraphBuilder.build``).""" +class Site(NamedTuple): + """Where a noise channel sits in the flattened circuit. + + Attributes: + instruction: Index of its instruction in the flattened circuit. + start: Index of its first target in the instruction. + end: One past the index of its last target. + record: Index of the measurement record it flips, if it flips one. + + """ + + instruction: int + start: int + end: int + record: int + + def error_phase(error_bit: int) -> Phase: """Return the phase of a noise spider for error bit ``error_bit`` (ID = bit).""" return Phase(Fraction(0), frozenset({error_bit})) @@ -90,7 +107,12 @@ def __init__(self) -> None: self._first_vertex: dict[int, Vertex] = {} self._last_vertex: dict[int, Vertex] = {} self._channel_probs: list[np.ndarray] = [] + self._channel_sites: list[Site] = [] + self._chain_links: dict[int, list[tuple[int, Site]]] = {} + self._chain_sites: list[Site] = [] self._num_error_bits = 0 + self.position: tuple[int, int, int] = (-1, 0, 0) + """Instruction index and target range that the parser is at.""" self._correlated_error_probs: list[float] = [] self._chain_spiders: list[Vertex] = [] self._chain_toggles: list[set[int]] = [] @@ -126,6 +148,29 @@ def channel_probs(self) -> list[np.ndarray]: self._check_finalized() return list(self._channel_probs) + @property + def channel_sites(self) -> list[Site]: + """Each noise channel's place in the flattened circuit. + + A correlated-error chain is at its first link; ``chain_links`` has the + others. + """ + self._check_finalized() + return list(self._channel_sites) + + @property + def chain_links(self) -> dict[int, list[tuple[int, Site]]]: + """The links of each correlated-error chain, by channel. + + A link is the channel outcome in which it alone fires, and its site. + """ + self._check_finalized() + return dict(self._chain_links) + + def _site(self) -> Site: + """Return the site of a channel added at the parser's position.""" + return Site(*self.position, len(self._records)) + @property def num_error_bits(self) -> int: """The number of error bits, which are the error parameter IDs.""" @@ -358,6 +403,7 @@ def add_channel(self, probs: np.ndarray) -> int: num_bits = channel_num_bits(probs) first = self._num_error_bits self._channel_probs.append(probs) + self._channel_sites.append(self._site()) self._num_error_bits += num_bits return first @@ -385,6 +431,7 @@ def correlated_error( if type_ == "Z" or type_ == "Y": self._chain_toggles[self._chain_spider(qubit, VertexType.Z)] ^= {term} self._correlated_error_probs.append(p) + self._chain_sites.append(self._site()) def _chain_spider(self, qubit: int, vertex_type: VertexType) -> int: """Return the index of the pending chain's noise spider for a component. @@ -431,6 +478,8 @@ def finalize_correlated_error(self) -> None: if not probabilities: return spiders, toggles = self._chain_spiders, self._chain_toggles + sites = self._chain_sites + self._chain_sites = [] self._chain_spiders = [] self._chain_toggles = [] self._chain_runs = {} @@ -445,7 +494,9 @@ def finalize_correlated_error(self) -> None: "instructions approximate it to first order in p" ) # NOTE: a chain that flips no spider, such as E(p) X0 X0, has no channel. - if 0 < c < k: + if c == 0: + return + if c < k: masks = [0] * k for bit, i in enumerate(live): for term in toggles[i]: @@ -453,11 +504,16 @@ def finalize_correlated_error(self) -> None: first = self.add_channel(chain_error_probs(masks, probabilities, c)) for bit, i in enumerate(live): self._graph.set_phase(spiders[i], error_phase(first + bit)) - elif c > 0: + else: + masks = [1 << term for term in range(k)] first = self.add_channel(correlated_error_probs(probabilities)) for i in live: bits = frozenset(first + term for term in toggles[i]) self._graph.set_phase(spiders[i], Phase(Fraction(0), bits)) + # NOTE: add_channel recorded the parser's position, which is past the chain. + channel = len(self._channel_sites) - 1 + self._channel_sites[channel] = sites[0] + self._chain_links[channel] = list(zip(masks, sites, strict=True)) # ------------------------------------------------------------------------- # Detectors and observables diff --git a/src/tsim/core/parse.py b/src/tsim/core/parse.py index 2e5c540a..9c40b235 100644 --- a/src/tsim/core/parse.py +++ b/src/tsim/core/parse.py @@ -97,6 +97,21 @@ def _validate_r_pauli_targets(instruction: stim.CircuitInstruction) -> None: seen = set() +def _product_ranges(instruction: stim.CircuitInstruction) -> list[tuple[int, int]]: + """Return the target range ``(start, end)`` of each Pauli product.""" + targets = instruction.targets_copy() + ranges = [] + start = 0 + for i in range(len(targets)): + if targets[i].is_combiner or ( + i + 1 < len(targets) and targets[i + 1].is_combiner + ): + continue + ranges.append((start, i + 1)) + start = i + 1 + return ranges + + def _iter_pauli_products( instruction: stim.CircuitInstruction, ) -> Iterator[tuple[list[tuple[Literal["X", "Y", "Z"], int]], bool]]: @@ -166,8 +181,13 @@ def parse_stim_circuit(stim_circuit: stim.Circuit) -> GraphBuilder: """ builder = GraphBuilder() - for instruction in stim_circuit.flattened(): + flattened = stim_circuit.flattened() + for index in range(len(flattened)): + instruction = flattened[index] assert not isinstance(instruction, stim.CircuitRepeatBlock) + # NOTE: the builder records this position with each noise channel that + # the instruction adds; the loops below narrow it to the targets. + builder.position = (index, 0, len(instruction.targets_copy())) name = instruction.name if name == "SHIFT_COORDS": @@ -217,7 +237,10 @@ def parse_stim_circuit(stim_circuit: stim.Circuit) -> GraphBuilder: if name == "MPP": args = instruction.gate_args_copy() p = args[0] if args else 0 - for paulis, invert in _iter_pauli_products(instruction): + products = _iter_pauli_products(instruction) + ranges = _product_ranges(instruction) + for (paulis, invert), (start, end) in zip(products, ranges, strict=True): + builder.position = (index, start, end) mpp(builder, paulis, invert, p=p) continue if name in ("SPP", "SPP_DAG") and is_t_tag(instruction.tag): @@ -247,7 +270,8 @@ def parse_stim_circuit(stim_circuit: stim.Circuit) -> GraphBuilder: if name == "MPAD": args = instruction.gate_args_copy() p = args[0] if args else 0 - for target in instruction.targets_copy(): + for i_target, target in enumerate(instruction.targets_copy()): + builder.position = (index, i_target, i_target + 1) mpad(builder, target.value, p=p) continue if name == "E" or name == "ELSE_CORRELATED_ERROR": @@ -300,6 +324,7 @@ def parse_stim_circuit(stim_circuit: stim.Circuit) -> GraphBuilder: for i_target in range(0, len(targets), num_qubits): chunk = targets[i_target : i_target + num_qubits] cc_chunk = is_classically_controlled[i_target : i_target + num_qubits] + builder.position = (index, i_target, i_target + num_qubits) chunk_inverted = False for j in range(num_qubits): chunk_inverted ^= invert[i_target + j] diff --git a/src/tsim/experimental.py b/src/tsim/experimental.py index e1941e3e..1da6fef2 100644 --- a/src/tsim/experimental.py +++ b/src/tsim/experimental.py @@ -7,12 +7,27 @@ detector outcomes with a stabilizer rank decomposition. - `SteaneEncoder` and `ColorEncoder5` encode a circuit transversally into the [[7,1,3]] Steane code and the [[17,1,5]] color code. +- `shortest_errors` finds a circuit's fault distance: every smallest set of + faults that flips an observable without flipping a detector, as `LogicalError`s + of `Fault`s. """ +from tsim.noise.faults import ( + Fault as Fault, + LogicalError as LogicalError, + shortest_errors as shortest_errors, +) from tsim.sampler import CompiledStateProbs as CompiledStateProbs from tsim.utils.encoder import ( ColorEncoder5 as ColorEncoder5, SteaneEncoder as SteaneEncoder, ) -__all__ = ["ColorEncoder5", "CompiledStateProbs", "SteaneEncoder"] +__all__ = [ + "ColorEncoder5", + "CompiledStateProbs", + "Fault", + "LogicalError", + "SteaneEncoder", + "shortest_errors", +] diff --git a/src/tsim/noise/faults.py b/src/tsim/noise/faults.py new file mode 100644 index 00000000..88c6ab36 --- /dev/null +++ b/src/tsim/noise/faults.py @@ -0,0 +1,418 @@ +"""Exact search for the smallest sets of circuit errors that cause a logical error. + +Tsim compiles a noisy circuit to error-basis bits ``f = T e`` and a program over +them. Nothing else about the noise reaches the outputs, so circuit errors with +the same f-bits are one fault, as error mechanisms with the same symptoms are +in a detector error model. Each direct detector is one f-bit, which a set of +faults flips or does not; the other detectors and the observables come out of +the statevector components, where ``Branches`` gives a set's exact chance to +flip no detector and to flip an observable. + +``shortest_errors`` tries every set of ``w`` faults for ``w = 1, 2, …``. It +finds the sets whose direct detectors cancel by joining two tables of smaller +sets on a hash of those detectors, and walks the tapes for these alone. +""" + +from __future__ import annotations + +from collections.abc import Iterator, Sequence +from dataclasses import dataclass +from math import comb +from typing import TYPE_CHECKING + +import numpy as np +import stim + +from tsim.compile.pipeline import compile_program +from tsim.core.graph import prepare_graph +from tsim.core.parse import parse_stim_circuit +from tsim.noise.channels import channel_num_bits +from tsim.statevector.branches import Branches, unique_rows +from tsim.statevector.program import StatevectorComponent + +if TYPE_CHECKING: + from tsim.circuit import Circuit + +MIN_PROBABILITY = 1e-9 +"""Smallest chance to flip an observable undetected that counts as a logical error.""" + +MAX_COMBINATIONS = 30_000_000 +"""Most sets of faults that one side of the join may hold.""" + +_BATCH = 1 << 20 +_HASH_BITS = 40 +_INDEX_BITS = 24 +_PAULI = {1: stim.target_z, 2: stim.target_x, 3: stim.target_y} +_MEASURED = {"M": "Z", "MX": "X", "MY": "Y", "MR": "Z", "MRX": "X", "MRY": "Y"} +_MEASURED_PAIR = {"MXX": "X", "MYY": "Y", "MZZ": "Z"} + + +@dataclass(frozen=True) +class Fault: + """One way for a circuit to go wrong: circuit errors with the same effect. + + Attributes: + circuit_error_locations: The circuit errors that are this fault, as in + ``stim.ExplainedError``. Their instruction offsets index + ``circuit.flattened()``. + probability: The sum of their probabilities. + + """ + + circuit_error_locations: tuple[stim.CircuitErrorLocation, ...] + probability: float + + +@dataclass(frozen=True) +class LogicalError: + """Faults that together can flip an observable without flipping a detector. + + ``len(error)`` is the number of faults and iterating yields them, as for the + list that ``stim.Circuit.shortest_graphlike_error`` returns. + + Attributes: + faults: The faults. + undetected_probability: The probability that no detector flips when + exactly these faults happen. + logical_flip_probability: The probability that no detector flips and an + observable does. + + """ + + faults: tuple[Fault, ...] + undetected_probability: float + logical_flip_probability: float + + def __len__(self) -> int: + """Return the number of faults.""" + return len(self.faults) + + def __iter__(self) -> Iterator[Fault]: + """Iterate over the faults.""" + return iter(self.faults) + + +def shortest_errors(circuit: Circuit, *, max_weight: int) -> list[LogicalError]: + """Return every smallest set of faults that causes a logical error. + + A fault is a circuit error, such as one Pauli of a ``DEPOLARIZE2``, together + with the circuit errors that act the same. A set of faults is a logical + error if it can flip an observable while every detector keeps its noiseless + value. With non-Clifford gates that happens with a probability, which the + result reports; in a Clifford circuit it is 0 or 1. + + The search is exhaustive, so the number of faults in the result is the + circuit's fault distance, and an empty result proves that the distance is + above ``max_weight``. Its cost grows as (number of faults)^(max_weight / 2) + and with the number of measurement branches of the circuit's statevector + components. + + Args: + circuit: The circuit, with its noise, detectors and observables. + max_weight: The largest number of faults to try. + + Returns: + The logical errors with the fewest faults, most likely first, or an + empty list if up to ``max_weight`` faults cause none. + + Raises: + ValueError: If a detector or an observable is random without noise, or + the search would need more than ``MAX_COMBINATIONS`` sets of faults + at once. + + """ + if max_weight < 1: + raise ValueError(f"max_weight must be at least 1, not {max_weight}") + if circuit.num_observables == 0: + return [] + search = _Search(circuit) + for weight in range(1, max_weight + 1): + found = search.logical_errors(weight) + if found: + return found + return [] + + +class _Search: + """A circuit's faults and the program that decides what they do.""" + + def __init__(self, circuit: Circuit) -> None: + prepared = prepare_graph(circuit, sample_detectors=True) + program = compile_program( + prepared, mode="sequential", strategy="active_statevector" + ) + num_f = prepared.error_transform.shape[0] + self._stim_circuit = circuit._stim_circ + self._locations: _Locations | None = None + + # NOTE: f-vectors are Python ints here: bit j is f-bit j. + bit_f = [ + sum(1 << row for row in column) + for column in prepared.error_transform.columns() + ] + groups: dict[int, list[tuple[int, int, float]]] = {} + first = 0 + for channel, probs in enumerate(prepared.channel_probs): + num_bits = channel_num_bits(probs) + for outcome in (np.flatnonzero(probs[1:]) + 1).tolist(): + f = 0 + for bit in range(num_bits): + if outcome >> bit & 1: + f ^= bit_f[first + bit] + if f: + event = (channel, outcome, float(probs[outcome])) + groups.setdefault(f, []).append(event) + first += num_bits + self._events = list(groups.values()) + num_bytes = max(1, -(-num_f // 8)) + self._f = np.frombuffer( + b"".join(f.to_bytes(num_bytes, "little") for f in groups), dtype=np.uint8 + ).reshape(len(groups), num_bytes) + if len(groups) >= 1 << _INDEX_BITS: + raise ValueError( + f"the circuit has {len(groups)} faults, too many to search" + ) + + num_direct = len(program.direct_f_indices) + direct = program.direct_f_indices + is_detector = program.output_order[:num_direct] < prepared.num_detectors + detector_bits = np.unique(direct[is_detector & (direct >= 0)]) + self._observable_bits = np.unique(direct[~is_detector & (direct >= 0)]) + mask = np.zeros(8 * num_bytes, dtype=np.uint8) + mask[detector_bits] = 1 + self._detector_mask = np.packbits(mask, bitorder="little") + self._branches = [] + for component in program.components: + assert isinstance(component, StatevectorComponent) + self._branches.append(Branches(component, prepared.num_detectors)) + # NOTE: this raises if a detector or an observable is random without noise. + self._probabilities(np.zeros((1, num_bytes), dtype=np.uint8)) + + # NOTE: a GF(2)-linear hash of the direct detectors that a fault flips, + # so that a set's hash is the XOR of its faults' hashes. + bits = np.unpackbits(self._f, axis=1, bitorder="little")[:, detector_bits] + rng = np.random.default_rng(0) + mixer = rng.integers(0, 2, size=(len(detector_bits), _HASH_BITS)) + mixed = (bits.astype(np.float32) @ mixer.astype(np.float32)).astype(np.int64) + self._hash = ( + ((mixed & 1) << np.arange(_HASH_BITS)).sum(axis=1).astype(np.uint64) + ) + + def logical_errors(self, weight: int) -> list[LogicalError]: + """Return the logical errors of exactly ``weight`` faults.""" + found = [] + for sets, f in self._undetected_by_direct(weight): + one, group = unique_rows(f) + undetected, flip = self._probabilities(f[one]) + for i in np.flatnonzero(flip[group] > MIN_PROBABILITY).tolist(): + faults = [int(j) for j in sets[i]] + row = group[i] + # NOTE: two circuit errors of one channel exclude each other. + if _distinct([{e[0] for e in self._events[j]} for j in faults]): + error = LogicalError( + tuple(self._fault(j) for j in faults), + float(undetected[row]), + float(flip[row]), + ) + found.append(error) + + def likelihood(error: LogicalError) -> float: + product = error.logical_flip_probability + for fault in error.faults: + product *= fault.probability + return product + + return sorted(found, key=likelihood, reverse=True) + + def _probabilities(self, f: np.ndarray) -> tuple[np.ndarray, np.ndarray]: + """Return the chance that no detector flips, and that an observable does. + + Args: + f: Packed f-vectors that flip no direct detector, one per row. + + """ + bits = np.unpackbits(f, axis=1, bitorder="little") + undetected = np.ones(len(f)) + unflipped = np.ones(len(f)) + for branches in self._branches: + passed, same = branches.probabilities(bits[:, branches.f_selection]) + undetected *= passed + unflipped *= same + unflipped[bits[:, self._observable_bits].any(axis=1)] = 0.0 + return undetected, undetected - unflipped + + def _undetected_by_direct( + self, weight: int + ) -> Iterator[tuple[np.ndarray, np.ndarray]]: + """Yield the sets of ``weight`` faults that flip no direct detector. + + Each batch is the sets, shape ``(sets, weight)`` with the faults of a + set ascending, and their packed f-vectors. A set is the first ``weight // 2`` of its faults joined to + the others, so both sides have equal hashes. + """ + n = len(self._events) + small = weight // 2 + for size in (small, weight - small): + if comb(n, size) > MAX_COMBINATIONS: + raise ValueError( + f"sets of {weight} out of {n} faults need {comb(n, size)} " + f"combinations at once, more than {MAX_COMBINATIONS}; lower " + "max_weight or remove noise from the circuit" + ) + left, right = _combinations(n, small), _combinations(n, weight - small) + shift = np.uint64(_INDEX_BITS) + last = left[:, -1].astype(np.uint64) + np.uint64(1) if small else np.uint64(0) + left_key = self._set_hash(left) << shift + # NOTE: a key is the hash, then the first fault, so the right sides of a + # left side are a run of the sorted keys: those of its hash whose first + # fault comes after its last. + keys = self._set_hash(right) << shift | right[:, 0].astype(np.uint64) + order = np.argsort(keys) + keys = keys[order] + lo = np.searchsorted(keys, left_key | last) + hi = np.searchsorted( + keys, left_key | np.uint64((1 << _INDEX_BITS) - 1), "right" + ) + counts = hi - lo + ends = np.cumsum(counts) + start = 0 + while start < len(left): + done = ends[start - 1] if start else 0 + stop = max(start + 1, int(np.searchsorted(ends, done + _BATCH, "right"))) + count = counts[start:stop] + parent = np.repeat(np.arange(start, stop), count) + offset = np.arange(len(parent)) - np.repeat(np.cumsum(count) - count, count) + match = order[np.repeat(lo[start:stop], count) + offset] + sets = np.column_stack([left[parent], right[match]]) + # NOTE: equal hashes do not prove that the direct detectors cancel. + f = np.bitwise_xor.reduce(self._f[sets], axis=1) + quiet = ~(f & self._detector_mask).any(axis=1) + yield sets[quiet], f[quiet] + start = stop + + def _set_hash(self, sets: np.ndarray) -> np.ndarray: + """Return the hash of each set of faults.""" + if sets.shape[1] == 0: + return np.zeros(len(sets), dtype=np.uint64) + return np.bitwise_xor.reduce(self._hash[sets], axis=1) + + def _fault(self, index: int) -> Fault: + """Return fault ``index`` with its circuit errors explained.""" + if self._locations is None: + self._locations = _Locations(self._stim_circuit) + events = self._events[index] + return Fault( + tuple( + self._locations.of(channel, outcome) for channel, outcome, _ in events + ), + sum(p for _, _, p in events), + ) + + +def _combinations(n: int, size: int) -> np.ndarray: + """Return the ascending tuples of ``size`` out of ``n`` indices, one per row.""" + sets = np.zeros((1, 0), dtype=np.int32) + for _ in range(size): + last = sets[:, -1] if sets.shape[1] else np.full(len(sets), -1, dtype=np.int32) + count = n - 1 - last + parent = np.repeat(np.arange(len(sets)), count) + offset = np.arange(len(parent)) - np.repeat(np.cumsum(count) - count, count) + nxt = (last[parent] + 1 + offset).astype(np.int32) + sets = np.column_stack([sets[parent], nxt]) + return sets + + +def _distinct(choices: Sequence[set[int]]) -> bool: + """Return whether one item can be taken from each set, all different.""" + if not choices: + return True + return any( + _distinct([other - {item} for other in choices[1:]]) for item in choices[0] + ) + + +class _Locations: + """Where each noise channel outcome happens in the flattened circuit.""" + + def __init__(self, stim_circuit: stim.Circuit) -> None: + builder = parse_stim_circuit(stim_circuit) + self._sites = builder.channel_sites + self._links = builder.chain_links + self._flat = stim_circuit.flattened() + self._coords = self._flat.get_final_qubit_coordinates() + self._ticks = np.cumsum([op.name == "TICK" for op in self._flat]) + + def _target(self, target: stim.GateTarget) -> stim.GateTargetWithCoords: + coords = [] if target.is_combiner else self._coords.get(target.value, []) + return stim.GateTargetWithCoords(target, coords) + + def of(self, channel: int, outcome: int) -> stim.CircuitErrorLocation: + """Return the circuit error of ``outcome`` of noise channel ``channel``.""" + site = self._sites[channel] + for mask, link in self._links.get(channel, ()): + if mask == outcome: + site = link + op = self._flat[site.instruction] + assert isinstance(op, stim.CircuitInstruction) + name = op.name + targets = op.targets_copy()[site.start : site.end] + qubits = [t.value for t in targets if not t.is_combiner] + + def paulis(codes: Sequence[int]) -> list[stim.GateTarget]: + pairs = zip(codes, qubits, strict=True) + return [_PAULI[code](qubit) for code, qubit in pairs if code] + + product: list[stim.GateTarget] = [] + measured: list[stim.GateTarget] | None = None + if name in ("X_ERROR", "Y_ERROR", "Z_ERROR"): + product = [stim.target_pauli(qubits[0], name[0])] + elif name in ("DEPOLARIZE1", "PAULI_CHANNEL_1"): + product = paulis([outcome]) + elif name in ("DEPOLARIZE2", "PAULI_CHANNEL_2"): + product = paulis([outcome & 3, outcome >> 2]) + elif name in ("HERALDED_ERASE", "HERALDED_PAULI_CHANNEL_1"): + product, measured = paulis([outcome >> 1]), [] + elif name in ("E", "ELSE_CORRELATED_ERROR"): + product = targets + elif name in _MEASURED: + measured = [stim.target_pauli(qubits[0], _MEASURED[name])] + elif name in _MEASURED_PAIR: + measured = [stim.target_pauli(q, _MEASURED_PAIR[name]) for q in qubits] + elif name == "MPP": + measured = [ + stim.target_pauli(t.value, t.pauli_type) + for t in targets + if not t.is_combiner + ] + elif name == "MPAD": + measured = [] + else: + raise NotImplementedError(f"no explanation for noise of {name}") + # NOTE: Stim reads a FlippedMeasurement without a record as no flip. Its + # type stub names the keywords differently from the module. + flip: dict = { + "record_index": None if measured is None else site.record, + "observable": [self._target(t) for t in measured or ()], + } + flipped = stim.FlippedMeasurement(**flip) + return stim.CircuitErrorLocation( + tick_offset=int(self._ticks[site.instruction]), + flipped_pauli_product=[self._target(t) for t in product], + flipped_measurement=flipped, + instruction_targets=stim.CircuitTargetsInsideInstruction( + gate=name, + tag=op.tag, + args=op.gate_args_copy(), + target_range_start=site.start, + target_range_end=site.end, + targets_in_range=[self._target(t) for t in targets], + ), + stack_frames=[ + stim.CircuitErrorLocationStackFrame( + instruction_offset=site.instruction, + iteration_index=0, + instruction_repetitions_arg=0, + ) + ], + noise_tag=op.tag, + ) diff --git a/src/tsim/statevector/branches.py b/src/tsim/statevector/branches.py new file mode 100644 index 00000000..8a5e8277 --- /dev/null +++ b/src/tsim/statevector/branches.py @@ -0,0 +1,263 @@ +"""Exact outcome probabilities of a statevector component, for given f-bits. + +The sampler draws each measurement of a component's tape. ``Branches`` follows +both outcomes instead, for many rows of f-bits at once, and drops a branch as +soon as one of its detectors differs from the noiseless value. What reaches the +end of the tape gives, for each row, the exact probability that no detector of +the component flips, and that no detector and no observable flips. +""" + +from __future__ import annotations + +from collections.abc import Iterator +from functools import cached_property + +import numpy as np + +from tsim.statevector.program import MEASURE_DORMANT, ROTATE, StatevectorComponent + +MAX_BYTES = 1 << 27 +"""Bytes of amplitudes that a walk aims to hold at once.""" + +MAX_NOISELESS_BRANCHES = 1 << 12 +"""Most measurement branches of the noiseless circuit that a component may have.""" + +IMPOSSIBLE = 1e-12 +"""Weight below which a measurement outcome cannot happen.""" + +_I_POWERS = (1, 1j, -1, -1j) + + +def _parity(values: np.ndarray) -> np.ndarray: + """Return the parity of the bits of each integer below 2^32.""" + values = values ^ (values >> 16) + values = values ^ (values >> 8) + values = values ^ (values >> 4) + values = values ^ (values >> 2) + return (values ^ (values >> 1)) & 1 + + +def _weights(amps: np.ndarray) -> np.ndarray: + """Return the squared norm of each row of amplitudes.""" + return (np.abs(amps) ** 2).sum(axis=1) + + +def _bit_parity(bits: np.ndarray, rows: np.ndarray) -> np.ndarray: + """Return the parity of ``bits & row`` for each row of ``bits`` and of ``rows``.""" + # NOTE: uint8 sums wrap modulo 256, which keeps their parity. + return (bits @ rows.T) & 1 + + +def unique_rows(rows: np.ndarray) -> tuple[np.ndarray, np.ndarray]: + """Group the equal rows of a uint8 matrix. + + Returns: + The index of one row of each group, and the group of each row. + + """ + # NOTE: sorting 64-bit words is much faster than ``np.unique(rows, axis=0)``. + words = np.zeros((len(rows), max(8, -(-rows.shape[1] // 8) * 8)), dtype=np.uint8) + words[:, : rows.shape[1]] = rows + words = words.view(np.uint64) + order = np.lexsort(words.T) + first = np.ones(len(rows), dtype=bool) + first[1:] = (words[order[1:]] != words[order[:-1]]).any(axis=1) + group = np.empty(len(rows), dtype=np.int64) + group[order] = np.cumsum(first) - 1 + return order[first], group + + +class Branches: + """The measurement branches of one component's tape. + + Attributes: + f_selection: Global f-bit index of each component f-bit. + + """ + + def __init__(self, component: StatevectorComponent, num_detectors: int) -> None: + """Read the tape of ``component``, whose outputs from ``num_detectors`` on are observables.""" + tape = component.tape + num_f = len(tape.f_selection) + self.f_selection = tape.f_selection + self._tape = tape + self._size = 1 << component.width + self._index = np.arange(self._size) + self._lanes = max(2, MAX_BYTES // (16 * self._size)) + self._sign_f = tape.sign_row[:, :num_f].astype(np.float32) + self._sign_b = tape.sign_row[:, num_f:].astype(np.uint8) + self._out_f = tape.output_row[:, :num_f].astype(np.float32) + self._out_b = tape.output_row[:, num_f:].astype(np.uint8) + self._branch = tape.branch - num_f + # NOTE: an output is known once the last measurement that it reads ran. + measured = np.flatnonzero(tape.branch >= 0) + setter = np.full(self._out_b.shape[1], -1) + setter[self._branch[measured]] = measured + ready = np.max(np.where(self._out_b, setter[None, :], -1), axis=1, initial=-1) + self._outputs = np.asarray(component.output_indices, dtype=np.int64) + self._num_detectors = num_detectors + self._observable = self._outputs >= num_detectors + self._early = np.flatnonzero((ready < 0) & ~self._observable) + self._ready = [ + np.flatnonzero((ready == a) & ~self._observable) + for a in range(len(tape.kind)) + ] + self._cache: dict[bytes, tuple[float, float]] = {} + + @cached_property + def reference(self) -> np.ndarray: + """The noiseless value of each output slot. + + Raises: + ValueError: If a detector or an observable of the component is + random without noise, or the noiseless tape has more than + ``MAX_NOISELESS_BRANCHES`` measurement branches. + + """ + noiseless = np.zeros((1, len(self.f_selection)), dtype=np.uint8) + leaves = list(self._leaves(noiseless, prune=False)) + values = np.concatenate([outputs for _, _, outputs in leaves]) + random = np.flatnonzero((values != values[0]).any(axis=0)) + if len(random): + slot = int(random[0]) + index = int(self._outputs[slot]) + name = ( + f"observable {index - self._num_detectors}" + if self._observable[slot] + else f"detector {index}" + ) + raise ValueError( + f"{name} is random without noise, so no error can flip it; " + "every detector and observable must be deterministic" + ) + return values[0] + + def probabilities(self, f: np.ndarray) -> tuple[np.ndarray, np.ndarray]: + """Return each row's chance to pass the detectors, and to pass unflipped. + + Args: + f: The component's f-bits, shape ``(rows, len(f_selection))``. + + Returns: + The probability that no detector of the component flips, and the + probability that no detector and no observable flips, per row. + + """ + f = np.asarray(f, dtype=np.uint8) + packed = np.packbits(f, axis=1) + one, group = unique_rows(packed) + keys = [row.tobytes() for row in packed[one]] + missing = [i for i, key in enumerate(keys) if key not in self._cache] + if missing: + passed = np.zeros(len(missing)) + unflipped = np.zeros(len(missing)) + for row, weight, outputs in self._leaves(f[one[missing]], prune=True): + same = (outputs == self.reference)[:, self._observable].all(axis=1) + np.add.at(passed, row, weight) + np.add.at(unflipped, row[same], weight[same]) + for i, p, u in zip(missing, passed, unflipped, strict=True): + self._cache[keys[i]] = (float(p), float(u)) + result = np.array([self._cache[key] for key in keys]).reshape(-1, 2)[group] + return result[:, 0], result[:, 1] + + def _leaves( + self, f: np.ndarray, *, prune: bool + ) -> Iterator[tuple[np.ndarray, np.ndarray, np.ndarray]]: + """Yield the branches that reach the end of the tape, in batches. + + A batch is the row of ``f`` of each branch, its probability and its + output values. With ``prune``, only branches whose detectors have their + reference values are followed. + """ + tape = self._tape + sign = (f @ self._sign_f.T).astype(np.int64) & 1 + sign ^= tape.sign_const.astype(np.int64) + out = ((f @ self._out_f.T).astype(np.int64) & 1).astype(np.uint8) + out ^= tape.output_const.astype(np.uint8) + rows = np.arange(len(f)) + if prune: + early = self._early + rows = rows[(out[:, early] == self.reference[early]).all(axis=1)] + step = max(1, self._lanes // 4) + for start in range(0, len(rows), step): + row = rows[start : start + step] + amps = np.zeros((len(row), self._size), dtype=np.complex128) + amps[:, 0] = 1.0 + bits = np.zeros((len(row), self._out_b.shape[1]), dtype=np.uint8) + yield from self._walk(0, amps, row, bits, sign, out, prune) + + def _walk( + self, + start: int, + amps: np.ndarray, + row: np.ndarray, + bits: np.ndarray, + sign: np.ndarray, + out: np.ndarray, + prune: bool, + ) -> Iterator[tuple[np.ndarray, np.ndarray, np.ndarray]]: + """Run the actions from ``start`` on lanes and yield those that finish. + + Lane ``i`` has amplitudes ``amps[i]``, whose squared norm is its + probability, belongs to row ``row[i]`` and has branch bits ``bits[i]``. + ``sign`` and ``out`` hold the rows' f-bit parts of the rotation signs + and of the outputs. + """ + tape = self._tape + for a in range(start, len(tape.kind)): + if len(row) == 0: + return + x, z = int(tape.x_mask[a]), int(tape.z_mask[a]) + # NOTE: the Pauli P = i^|x&z| X^x Z^z takes amplitudes ``amps`` to + # ``amps[:, source] * phase``. + source = self._index ^ x + phase = _I_POWERS[(x & z).bit_count() & 3] * (1 - 2 * _parity(source & z)) + if tape.kind[a] <= ROTATE: + flip = sign[row, a] ^ _bit_parity(bits, self._sign_b[a]) + coupling = (2.0 * flip - 1.0) * (1j * tape.sin[a]) + amps = tape.cos[a] * amps + coupling[:, None] * ( + amps[:, source] * phase + ) + continue + children = [] + for outcome in (0, 1): + if tape.kind[a] == MEASURE_DORMANT: + kept, child = np.arange(len(row)), amps * np.sqrt(0.5) + else: + moved = amps[:, source] * phase + projected = (amps - moved if outcome else amps + moved) / 2 + kept = np.flatnonzero(_weights(projected) > IMPOSSIBLE) + projected = projected[kept] + # NOTE: the planner moved the measured Pauli onto the pivot, + # which ends in |0>, as in ``shared._project_range``. + pivot = 1 << int(tape.pivot[a]) + low = self._index[self._index & pivot == 0] + child = np.zeros_like(projected) + if x == 0: + child[:, low] = projected[:, low] + projected[:, low | pivot] + else: + child[:, low] = np.sqrt(2.0) * projected[:, low] + child_bits = bits[kept] + child_bits[:, self._branch[a]] = outcome + children.append((child, row[kept], child_bits)) + amps = np.concatenate([child[0] for child in children]) + row = np.concatenate([child[1] for child in children]) + bits = np.concatenate([child[2] for child in children]) + slots = self._ready[a] + if prune and len(slots): + values = out[row][:, slots] ^ _bit_parity(bits, self._out_b[slots]) + keep = (values == self.reference[slots]).all(axis=1) + amps, row, bits = amps[keep], row[keep], bits[keep] + if not prune and len(row) > MAX_NOISELESS_BRANCHES: + raise ValueError( + "the noiseless circuit has more than " + f"{MAX_NOISELESS_BRANCHES} measurement branches in one component" + ) + if len(row) > self._lanes: + half = len(row) // 2 + for part in (slice(0, half), slice(half, None)): + yield from self._walk( + a + 1, amps[part], row[part], bits[part], sign, out, prune + ) + return + yield row, _weights(amps), out[row] ^ _bit_parity(bits, self._out_b) diff --git a/test/unit/noise/test_faults.py b/test/unit/noise/test_faults.py new file mode 100644 index 00000000..8eef9a93 --- /dev/null +++ b/test/unit/noise/test_faults.py @@ -0,0 +1,299 @@ +"""Tests for ``tsim.noise.faults``: the exact search for shortest logical errors.""" + +import itertools + +import numpy as np +import pytest +import stim + +from tsim import Circuit +from tsim.experimental import shortest_errors +from tsim.noise.faults import _combinations, _distinct, _Search + +# A Bell pair is stabilized by XX and ZZ, also under T on one qubit and T_DAG on +# the other. An X error between the T layers turns into (X ± Y)/√2, which the XX +# detector catches half of the time; between S layers it turns into Y. +BELL = """ + R 0 1 + H 0 + CX 0 1 + {gate} 0 + {gate}_DAG 1 + X_ERROR(0.01) 0 1 + {gate}_DAG 0 + {gate} 1 + MPP X0*X1 + DETECTOR rec[-1] + MPP Z0*Z1 + OBSERVABLE_INCLUDE(0) rec[-1] +""" + +GHZ = """ + R 0 1 2 + H 0 + CX 0 1 0 2 + T 0 1 2 + DEPOLARIZE1(0.01) 0 1 2 + T_DAG 0 1 2 + TICK + DEPOLARIZE2(0.01) 0 1 + MPP X0*X1*X2 Z0*Z1 + DETECTOR rec[-2] + DETECTOR rec[-1] + MPP Z1*Z2 + OBSERVABLE_INCLUDE(0) rec[-1] +""" + +# One round of a three-qubit repetition code, with every kind of noise. +NOISES = """ + QUBIT_COORDS(0, 1) 0 + R 0 1 2 + E(0.01) X0 X1 + ELSE_CORRELATED_ERROR(0.02) X2 Z1 + DEPOLARIZE2(0.01) 0 1 + TICK + HERALDED_PAULI_CHANNEL_1(0.01, 0.02, 0.03, 0.04) 1 + DETECTOR rec[-1] + MPP(0.01) Z0*Z1 Z1*Z2 + DETECTOR rec[-2] + DETECTOR rec[-1] + TICK + PAULI_CHANNEL_1(0.01, 0.02, 0) 2 + PAULI_CHANNEL_2(0, 0, 0, 0.01, 0, 0, 0, 0, 0, 0, 0.02, 0, 0, 0, 0) 0 2 + Y_ERROR(0.01) 0 + MZZ(0.01) 0 1 1 2 + DETECTOR rec[-2] rec[-4] + DETECTOR rec[-1] rec[-3] + MR(0.01) 0 + M(0.01) 1 2 + DETECTOR rec[-3] rec[-2] rec[-5] + DETECTOR rec[-2] rec[-1] rec[-4] + OBSERVABLE_INCLUDE(0) rec[-1] +""" + + +def _generated(task: str, distance: int) -> stim.Circuit: + return stim.Circuit.generated( + task, + distance=distance, + rounds=3, + after_clifford_depolarization=0.01, + before_measure_flip_probability=0.01, + after_reset_flip_probability=0.01, + ) + + +def _with_errors(circuit: Circuit, error) -> Circuit: + """Return the noiseless circuit with one circuit error of each fault.""" + flat = circuit.stim_circuit.flattened() + inserted: dict[int, stim.Circuit] = {} + for fault in error: + location = fault.circuit_error_locations[0] + (frame,) = location.stack_frames + paulis = inserted.setdefault(frame.instruction_offset, stim.Circuit()) + for target in location.flipped_pauli_product: + pauli = target.gate_target.pauli_type + paulis.append(f"{pauli}_ERROR", [target.gate_target.value], 1) + out = stim.Circuit() + for index in range(len(flat)): + out += flat[index : index + 1].without_noise() + out += inserted.get(index, stim.Circuit()) + return Circuit(out) + + +@pytest.mark.parametrize( + ("task", "distance"), + [ + ("repetition_code:memory", 3), + ("repetition_code:memory", 5), + ("surface_code:rotated_memory_z", 3), + # NOTE: hook errors halve the distance of Stim's color code circuit. + ("color_code:memory_xyz", 3), + ], +) +def test_the_distance_of_a_clifford_circuit_is_stims(task, distance): + circuit = _generated(task, distance) + # NOTE: Stim's search gives an upper bound, which is tight for these circuits. + expected = len( + circuit.search_for_undetectable_logical_errors( + dont_explore_detection_event_sets_with_size_above=6, + dont_explore_edges_with_degree_above=6, + dont_explore_edges_increasing_symptom_degree=False, + ) + ) + errors = shortest_errors(Circuit(circuit), max_weight=distance) + assert errors + assert {len(error) for error in errors} == {expected} + for error in errors: + assert error.undetected_probability == pytest.approx(1.0) + assert error.logical_flip_probability == pytest.approx(1.0) + assert shortest_errors(Circuit(circuit), max_weight=expected - 1) == [] + + +@pytest.mark.parametrize( + "task", ["repetition_code:memory", "surface_code:rotated_memory_z"] +) +def test_the_errors_are_undetectable_logical_errors_for_stim(task): + circuit = _generated(task, 3) + reference = circuit.reference_sample() + converter = circuit.compile_m2d_converter() + quiet = converter.convert( + measurements=reference[None, :], separate_observables=True + ) + for error in shortest_errors(Circuit(circuit), max_weight=3)[:20]: + noisy = _with_errors(Circuit(circuit), error).stim_circuit + sample = noisy.compile_sampler().sample(1) + detectors, observables = converter.convert( + measurements=sample, separate_observables=True + ) + assert np.array_equal(detectors, quiet[0]) + assert not np.array_equal(observables, quiet[1]) + + +@pytest.mark.parametrize( + "text", [NOISES, str(_generated("surface_code:rotated_memory_z", 3))] +) +def test_the_circuit_error_locations_are_stims(text): + circuit = stim.Circuit(text) + explained = circuit.flattened().explain_detector_error_model_errors() + expected = {str(loc) for e in explained for loc in e.circuit_error_locations} + search = _Search(Circuit(circuit)) + got = { + str(location) + for index in range(len(search._events)) + for location in search._fault(index).circuit_error_locations + } + assert got == expected + + +def test_t_gates_make_an_error_undetected_half_of_the_time(): + (error,) = shortest_errors(Circuit(BELL.format(gate="T")), max_weight=2) + assert len(error) == 1 + assert error.undetected_probability == pytest.approx(0.5) + assert error.logical_flip_probability == pytest.approx(0.5) + (fault,) = error + products = [ + [str(t.gate_target) for t in location.flipped_pauli_product] + for location in fault.circuit_error_locations + ] + # NOTE: on a Bell pair, an X on either qubit is the same error. + assert products == [["stim.target_x(0)"], ["stim.target_x(1)"]] + assert fault.probability == pytest.approx(0.02) + location = fault.circuit_error_locations[0] + assert location.instruction_targets.gate == "X_ERROR" + assert location.stack_frames[0].instruction_offset == 5 + assert location.flipped_measurement is None + + assert shortest_errors(Circuit(BELL.format(gate="S")), max_weight=2) == [] + + +def test_the_probabilities_are_those_of_sampling_the_errors(): + circuit = Circuit(GHZ) + errors = shortest_errors(circuit, max_weight=2) + assert {len(error) for error in errors} == {1} + assert {round(error.undetected_probability, 6) for error in errors} == {0.5, 1.0} + shots = 20_000 + for error in errors: + sampler = _with_errors(circuit, error).compile_detector_sampler(seed=0) + detectors, observables = sampler.sample( + shots, + separate_observables=True, + use_detector_reference_sample=True, + use_observable_reference_sample=True, + ) + quiet = ~detectors.any(axis=1) + flipped = quiet & observables.any(axis=1) + for got, expected in ( + (quiet.mean(), error.undetected_probability), + (flipped.mean(), error.logical_flip_probability), + ): + assert abs(got - expected) < 5 * np.sqrt(0.25 / shots) + + +def test_the_most_likely_error_comes_first(): + errors = shortest_errors(Circuit(GHZ), max_weight=1) + + def likelihood(error): + return error.logical_flip_probability * np.prod( + [fault.probability for fault in error] + ) + + assert [likelihood(e) for e in errors] == sorted(map(likelihood, errors))[::-1] + + +def test_errors_of_one_channel_do_not_combine(): + # NOTE: X and Y each flip the ZZ detector and together are a Z, which flips + # only the observable. One PAULI_CHANNEL_1 applies one of them. + one_channel = """ + R 0 1 + H 0 + CX 0 1 + PAULI_CHANNEL_1(0.01, 0.01, 0) 0 + MPP Z0*Z1 + DETECTOR rec[-1] + MPP X0*X1 + OBSERVABLE_INCLUDE(0) rec[-1] + """ + assert shortest_errors(Circuit(one_channel), max_weight=2) == [] + two_channels = one_channel.replace( + "PAULI_CHANNEL_1(0.01, 0.01, 0) 0", "X_ERROR(0.01) 0\nY_ERROR(0.01) 0" + ) + (error,) = shortest_errors(Circuit(two_channels), max_weight=2) + assert len(error) == 2 + + +def test_no_observable_or_no_noise_has_no_errors(): + assert ( + shortest_errors(Circuit("X_ERROR(0.1) 0\nM 0\nDETECTOR rec[-1]"), max_weight=3) + == [] + ) + assert ( + shortest_errors(Circuit("M 0\nOBSERVABLE_INCLUDE(0) rec[-1]"), max_weight=3) + == [] + ) + + +def test_an_undetected_single_error_has_weight_one(): + (error,) = shortest_errors( + Circuit("X_ERROR(0.1) 0\nM 0\nOBSERVABLE_INCLUDE(0) rec[-1]"), max_weight=3 + ) + assert len(error) == 1 + + +def test_random_detectors_and_observables_are_rejected(): + with pytest.raises(ValueError, match="detector 0 is random without noise"): + shortest_errors( + Circuit( + "RX 0\nT 0\nX_ERROR(0.1) 0\nM 0\nDETECTOR rec[-1]\nM 0\nOBSERVABLE_INCLUDE(0) rec[-1]" + ), + max_weight=1, + ) + with pytest.raises(ValueError, match="observable 0 is random without noise"): + shortest_errors( + Circuit("RX 0\nT 0\nX_ERROR(0.1) 0\nM 0\nOBSERVABLE_INCLUDE(0) rec[-1]"), + max_weight=1, + ) + + +def test_max_weight_is_checked(): + with pytest.raises(ValueError, match="max_weight must be at least 1"): + shortest_errors(Circuit(GHZ), max_weight=0) + + +def test_a_search_that_is_too_large_is_refused(monkeypatch): + monkeypatch.setattr("tsim.noise.faults.MAX_COMBINATIONS", 10) + with pytest.raises(ValueError, match="lower max_weight"): + shortest_errors(Circuit(_generated("repetition_code:memory", 3)), max_weight=3) + + +@pytest.mark.parametrize(("n", "size"), [(5, 0), (5, 1), (6, 2), (7, 3), (3, 4)]) +def test_combinations(n, size): + expected = list(itertools.combinations(range(n), size)) + assert [tuple(row) for row in _combinations(n, size).tolist()] == expected + + +def test_distinct(): + assert _distinct([{1}, {2}]) + assert _distinct([{1, 2}, {1}]) + assert not _distinct([{1}, {1}]) + assert not _distinct([{1, 2}, {1, 2}, {1, 2}]) diff --git a/test/unit/statevector/test_branches.py b/test/unit/statevector/test_branches.py new file mode 100644 index 00000000..e799b3ce --- /dev/null +++ b/test/unit/statevector/test_branches.py @@ -0,0 +1,115 @@ +"""Tests for ``tsim.statevector.branches``: exact outcome probabilities of a tape.""" + +from test.helpers.statevector import ( + CIRCUITS, + assert_distributions_close, + f_patterns, + ops_distribution, + output_indices, + quantum_components, +) + +import numpy as np +import pytest + +from tsim.statevector.branches import Branches, unique_rows +from tsim.statevector.pbc import ComponentLayout, read_pauli_ops +from tsim.statevector.program import compile_statevector_component + +DETERMINISTIC = """ + R 0 1 2 + H 0 + CX 0 1 0 2 + T 0 1 2 + DEPOLARIZE1(0.01) 0 1 2 + T_DAG 0 1 2 + DEPOLARIZE1(0.01) 0 1 2 + MPP X0*X1*X2 Z0*Z1 + DETECTOR rec[-2] + DETECTOR rec[-1] + MPP Z1*Z2 + OBSERVABLE_INCLUDE(0) rec[-1] +""" + + +def _components(text: str, *, sample_detectors: bool): + """Yield each non-direct component's compiled form and its Pauli ops.""" + components, layout = quantum_components(text, sample_detectors=sample_detectors) + for component in components: + indices = output_indices(component) + ops = read_pauli_ops(component, ComponentLayout.of(component, indices, layout)) + yield compile_statevector_component(component, indices, layout), ops + + +@pytest.mark.parametrize("name", sorted(CIRCUITS)) +@pytest.mark.parametrize("sample_detectors", [True, False]) +def test_the_branches_have_the_exact_output_distribution(name, sample_detectors): + for compiled, ops in _components(CIRCUITS[name], sample_detectors=sample_detectors): + patterns = f_patterns(ops.num_f, limit=8) + branches = Branches(compiled, num_detectors=len(compiled.output_indices)) + got: list[dict] = [{} for _ in patterns] + f = np.array(patterns, dtype=np.uint8).reshape(len(patterns), ops.num_f) + for row, weight, outputs in branches._leaves(f, prune=False): + for r, w, out in zip( + row.tolist(), weight.tolist(), outputs.tolist(), strict=True + ): + got[r][tuple(out)] = got[r].get(tuple(out), 0.0) + w + for pattern, distribution in zip(patterns, got, strict=True): + assert_distributions_close(distribution, ops_distribution(ops, pattern)) + + +def test_probabilities_are_those_of_the_reference_outputs(): + ((compiled, ops),) = _components(DETERMINISTIC, sample_detectors=True) + # NOTE: outputs 0 and 1 are the detectors, output 2 is the observable. + is_detector = np.array(compiled.output_indices) < 2 + branches = Branches(compiled, num_detectors=2) + reference = branches.reference + patterns = f_patterns(ops.num_f, limit=64) + passed, unflipped = branches.probabilities(np.array(patterns, dtype=np.uint8)) + assert passed[0] == pytest.approx(1.0) + assert unflipped[0] == pytest.approx(1.0) + assert any(0.4 < p < 0.6 for p in passed) + for i, pattern in enumerate(patterns): + distribution = ops_distribution(ops, pattern) + quiet = { + outcome: p + for outcome, p in distribution.items() + if np.array_equal(np.array(outcome)[is_detector], reference[is_detector]) + } + assert passed[i] == pytest.approx(sum(quiet.values()), abs=1e-9) + same = quiet.get(tuple(reference.tolist()), 0.0) + assert unflipped[i] == pytest.approx(same, abs=1e-9) + + +def test_many_rows_split_into_lanes(monkeypatch): + ((compiled, ops),) = _components(DETERMINISTIC, sample_detectors=True) + f = np.array(f_patterns(ops.num_f, limit=64), dtype=np.uint8) + expected = Branches(compiled, num_detectors=2).probabilities(f) + monkeypatch.setattr("tsim.statevector.branches.MAX_BYTES", 64) + got = Branches(compiled, num_detectors=2).probabilities(f) + np.testing.assert_allclose(got, expected, atol=1e-12) + + +def test_a_random_noiseless_output_has_no_reference(): + text = """ + R 0 + H 0 + T 0 + H 0 + X_ERROR(0.1) 0 + M 0 + DETECTOR rec[-1] + """ + ((compiled, _),) = _components(text, sample_detectors=True) + with pytest.raises(ValueError, match="detector 0 is random without noise"): + Branches(compiled, num_detectors=1).probabilities(np.zeros((1, 1))) + + +def test_unique_rows_groups_equal_rows(): + rng = np.random.default_rng(0) + rows = rng.integers(0, 3, size=(500, 11), dtype=np.uint8) + one, group = unique_rows(rows) + assert len(one) == len(np.unique(rows, axis=0)) + assert np.array_equal(rows[one][group], rows) + one, group = unique_rows(np.zeros((3, 0), dtype=np.uint8)) + assert one.tolist() == [0] and group.tolist() == [0, 0, 0] diff --git a/test/unit/test_public_api.py b/test/unit/test_public_api.py index 8c4eb956..372842ac 100644 --- a/test/unit/test_public_api.py +++ b/test/unit/test_public_api.py @@ -1,5 +1,6 @@ import tsim import tsim.experimental +from tsim.noise.faults import Fault, LogicalError, shortest_errors from tsim.sampler import CompiledStateProbs from tsim.utils.encoder import ColorEncoder5, SteaneEncoder @@ -17,8 +18,14 @@ def test_experimental_api(): assert tsim.experimental.CompiledStateProbs is CompiledStateProbs assert tsim.experimental.ColorEncoder5 is ColorEncoder5 assert tsim.experimental.SteaneEncoder is SteaneEncoder + assert tsim.experimental.shortest_errors is shortest_errors + assert tsim.experimental.LogicalError is LogicalError + assert tsim.experimental.Fault is Fault assert sorted(tsim.experimental.__all__) == [ "ColorEncoder5", "CompiledStateProbs", + "Fault", + "LogicalError", "SteaneEncoder", + "shortest_errors", ] From 7f43fb3bea2810c92433cbfd65cbcb20d1328a65 Mon Sep 17 00:00:00 2001 From: Rafael Haenel Date: Wed, 18 Nov 2026 13:04:07 -0700 Subject: [PATCH 2/3] perf(experimental): walk each tape once per rotation signs, join in numba The tape reads a set's f-bits only through its rotation signs and a linear flip of its outputs, and few distinct signs occur: 3,864 among the 18M weight-4 candidates of Z-flagged d=5 cultivation. Branches.outcomes now gives the exact output distribution per distinct signs, and a numba join (noise/fault_join.py) streams the larger half of each set instead of storing it, in two passes: one collects the distinct signs, the other keeps the sets whose signs and output flips can flip an observable undetected. d=5 cultivation to weight 3 goes from 10 s to 0.7 s, Z-flagged d=5 to weight 4 from 160 s to 5 s, and weight 5 is now within reach. max_errors keeps only the most likely errors. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 +- src/tsim/noise/fault_join.py | 300 +++++++++++++++++ src/tsim/noise/faults.py | 445 +++++++++++++++++-------- src/tsim/statevector/branches.py | 169 +++++----- test/unit/noise/test_faults.py | 40 +++ test/unit/statevector/test_branches.py | 77 +++-- 6 files changed, 772 insertions(+), 262 deletions(-) create mode 100644 src/tsim/noise/fault_join.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 93df7c00..37cf0ce3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 and that they flip an observable, and explains each fault with `stim.CircuitErrorLocation`s. An empty result proves the distance exceeds `k`. The fault distance of d=5 T-state cultivation (3, as found by - [Chan et al.](https://arxiv.org/abs/2609.17706)) takes 7 s. + [Chan et al.](https://arxiv.org/abs/2609.17706)) takes under a second, and + that of its Z-flagged version (4) takes 5 s. ### Changed - The stabilizer-rank strategies compile components of the same shape once, and diff --git a/src/tsim/noise/fault_join.py b/src/tsim/noise/fault_join.py new file mode 100644 index 00000000..3ffe8ab8 --- /dev/null +++ b/src/tsim/noise/fault_join.py @@ -0,0 +1,300 @@ +"""Numba kernels that join sets of faults whose direct detectors cancel. + +A set of ``w`` faults, ascending, is a stored ``left`` set of the first +``w // 2`` and a streamed ``right`` set of the others. The left sets are +sorted by a GF(2)-linear hash of their direct detectors and then by their last +fault, so the left sets that complete a right set are a prefix of one run. +Each fault is a row of words: direct detectors ``D``, rotation signs ``S`` and +output flips ``O``; a set's words are the XOR of its faults' words. + +``scan`` streams every right set. In ``COLLECT`` mode it gathers the distinct +``S`` of the sets whose direct detectors cancel, with one set of each; in +``EMIT`` mode it keeps the sets whose ``(S, O)`` the caller's table marks as a +possible logical error. +""" + +from __future__ import annotations + +import numba +import numpy as np + +from tsim.utils.kernels import jit, kernel + +COLLECT = 0 +EMIT = 1 + +_M1 = np.uint64(0xBF58476D1CE4E5B9) +_M2 = np.uint64(0x94D049BB133111EB) +_GOLDEN = np.uint64(0x9E3779B97F4A7C15) + + +@jit +def _mix(x): + """Return the splitmix64 finalizer of ``x``.""" + x = (x ^ (x >> np.uint64(30))) * _M1 + x = (x ^ (x >> np.uint64(27))) * _M2 + return x ^ (x >> np.uint64(31)) + + +@jit +def _words_hash(a, b, mask): + """Return a hash of the words ``a`` followed by ``b & mask``.""" + h = _GOLDEN + for k in range(len(a)): + h = _mix(h ^ a[k]) + for k in range(len(b)): + h = _mix(h ^ (b[k] & mask[k])) + return h + + +@jit +def build_index(keys, capacity): + """Return an open-addressing table of ``keys``, which must be distinct. + + Slot ``s`` holds the index of a key, or -1. ``capacity`` is a power of 2 + above ``len(keys)``. + """ + table = np.full(capacity, -1, dtype=np.int64) + mask = np.uint64(capacity - 1) + for i in range(len(keys)): + s = _mix(keys[i]) & mask + while table[s] >= 0: + s = (s + np.uint64(1)) & mask + table[s] = i + return table + + +@jit +def build_word_index(keys, masked, mask, capacity): + """Return an open-addressing table of the rows ``(keys, masked & mask)``.""" + table = np.full(capacity, -1, dtype=np.int64) + slots = np.uint64(capacity - 1) + for i in range(len(keys)): + s = _words_hash(keys[i], masked[i], mask) & slots + while table[s] >= 0: + s = (s + np.uint64(1)) & slots + table[s] = i + return table + + +@jit +def _find(table, keys, key): + """Return the index of ``key`` in an index of ``build_index``, or -1.""" + mask = np.uint64(len(table) - 1) + s = _mix(key) & mask + while table[s] >= 0: + if keys[table[s]] == key: + return table[s] + s = (s + np.uint64(1)) & mask + return -1 + + +@jit +def _find_words(table, keys, masked, a, b, mask): + """Return the row of ``(a, b & mask)`` in a ``build_word_index``, or -1.""" + slots = np.uint64(len(table) - 1) + s = _words_hash(a, b, mask) & slots + while table[s] >= 0: + i = table[s] + same = True + for k in range(len(a)): + if keys[i, k] != a[k]: + same = False + break + if same: + for k in range(len(b)): + if masked[i, k] != (b[k] & mask[k]): + same = False + break + if same: + return i + s = (s + np.uint64(1)) & slots + return -1 + + +@jit +def _visit(mode, lane, h, c, r, faults, left, runs, signs, outputs, store, found): + """Handle the right set ``c[:r]``, whose detector hash is ``h``. + + Returns False once the lane's buffer is full. + """ + d_words, s_words, o_words, _ = faults + left_sets, left_last, left_d, left_s, left_o = left + run_keys, run_start, run_end, run_table = runs + i = _find(run_table, run_keys, h) + if i < 0: + return True + for e in range(run_start[i], run_end[i]): + if left_last[e] >= c[0]: + break + cancels = True + for k in range(d_words.shape[1]): + word = left_d[e, k] + for j in range(r): + word ^= d_words[c[j], k] + if word != 0: + cancels = False + break + if not cancels: + continue + for k in range(s_words.shape[1]): + word = left_s[e, k] + for j in range(r): + word ^= s_words[c[j], k] + signs[k] = word + for k in range(o_words.shape[1]): + word = left_o[e, k] + for j in range(r): + word ^= o_words[c[j], k] + outputs[k] = word + if mode == COLLECT: + if not _collect(lane, e, c, r, signs, left_sets, store): + return False + elif not _emit(lane, e, c, r, signs, outputs, left_sets, found): + return False + return True + + +@jit +def _collect(lane, e, c, r, signs, left_sets, store): + """Add the signs of a set to the lane's set of distinct signs.""" + keys, table, sets, count = store + capacity = keys.shape[1] + slots = np.uint64(table.shape[1] - 1) + s = _words_hash(signs, signs[:0], signs[:0]) & slots + while table[lane, s] >= 0: + i = table[lane, s] + same = True + for k in range(len(signs)): + if keys[lane, i, k] != signs[k]: + same = False + break + if same: + return True + s = (s + np.uint64(1)) & slots + n = count[lane] + if n == capacity: + return False + table[lane, s] = n + keys[lane, n] = signs + _write_set(sets[lane, n], e, c, r, left_sets) + count[lane] = n + 1 + return True + + +@jit +def _emit(lane, e, c, r, signs, outputs, left_sets, found): + """Keep a set whose signs and output flips can flip an observable.""" + keys, masked, det_mask, obs_mask, multi, obs, table, sets, count = found + i = _find_words(table, keys, masked, signs, outputs, det_mask) + if i < 0: + return True + if not multi[i]: + same = True + for k in range(len(outputs)): + if (outputs[k] & obs_mask[k]) != obs[i, k]: + same = False + break + if same: + return True + n = count[lane] + if n == sets.shape[1]: + return False + _write_set(sets[lane, n], e, c, r, left_sets) + count[lane] = n + 1 + return True + + +@jit +def _write_set(out, e, c, r, left_sets): + """Write the left set ``e`` followed by ``c[:r]``.""" + size = left_sets.shape[1] + for j in range(size): + out[j] = left_sets[e, j] + for j in range(r): + out[size + j] = c[j] + + +def _scan(mode, r, faults, left, runs, store, found): + """Stream every right set of ``r`` faults through ``_visit``. + + Lane ``lane`` takes the right sets whose first fault is ``lane`` modulo the + number of lanes. Returns whether a lane's buffer filled up. + """ + _, s_words, o_words, hashes = faults + n = len(hashes) + lanes = store[3].shape[0] + full = np.zeros(lanes, dtype=np.bool_) + for lane in numba.prange(lanes): + c = np.zeros(3, dtype=np.int64) + signs = np.zeros(s_words.shape[1], dtype=np.uint64) + outputs = np.zeros(o_words.shape[1], dtype=np.uint64) + for c0 in range(lane, n, lanes): + if full[lane]: + break + c[0] = c0 + h0 = hashes[c0] + if r == 1: + if not _visit( + mode, + lane, + h0, + c, + r, + faults, + left, + runs, + signs, + outputs, + store, + found, + ): + full[lane] = True + continue + for c1 in range(c0 + 1, n): + c[1] = c1 + h1 = h0 ^ hashes[c1] + if r == 2: + if not _visit( + mode, + lane, + h1, + c, + r, + faults, + left, + runs, + signs, + outputs, + store, + found, + ): + full[lane] = True + break + continue + for c2 in range(c1 + 1, n): + c[2] = c2 + if not _visit( + mode, + lane, + h1 ^ hashes[c2], + c, + r, + faults, + left, + runs, + signs, + outputs, + store, + found, + ): + full[lane] = True + break + if full[lane]: + break + return full.any() + + +scan = kernel(_scan) +"""``scan(work, mode, r, faults, left, runs, store, found)``, in parallel when +``work`` (the number of right sets) is large.""" diff --git a/src/tsim/noise/faults.py b/src/tsim/noise/faults.py index 88c6ab36..c3ed3dab 100644 --- a/src/tsim/noise/faults.py +++ b/src/tsim/noise/faults.py @@ -3,14 +3,20 @@ Tsim compiles a noisy circuit to error-basis bits ``f = T e`` and a program over them. Nothing else about the noise reaches the outputs, so circuit errors with the same f-bits are one fault, as error mechanisms with the same symptoms are -in a detector error model. Each direct detector is one f-bit, which a set of -faults flips or does not; the other detectors and the observables come out of -the statevector components, where ``Branches`` gives a set's exact chance to -flip no detector and to flip an observable. - -``shortest_errors`` tries every set of ``w`` faults for ``w = 1, 2, …``. It -finds the sets whose direct detectors cancel by joining two tables of smaller -sets on a hash of those detectors, and walks the tapes for these alone. +in a detector error model. + +A set of faults acts through three GF(2)-linear images of its f-bits: the +direct detectors it flips, the rotation signs of the statevector components it +flips, and the flips of their outputs and of the direct observables. Only the +rotation signs act nonlinearly, and few distinct ones occur, so ``Branches`` +walks each component once per distinct signs for the exact distribution of its +outputs; the output flips then just shift that distribution. + +``shortest_errors`` tries every set of ``w`` faults for ``w = 1, 2, …``. A +numba join (``fault_join``) streams the sets whose direct detectors cancel, a +stored half against a streamed half on a hash of those detectors: a first pass +collects their distinct rotation signs, a second keeps the sets whose signs and +output flips can flip an observable undetected. """ from __future__ import annotations @@ -20,14 +26,16 @@ from math import comb from typing import TYPE_CHECKING +import numba import numpy as np import stim from tsim.compile.pipeline import compile_program from tsim.core.graph import prepare_graph from tsim.core.parse import parse_stim_circuit +from tsim.noise import fault_join from tsim.noise.channels import channel_num_bits -from tsim.statevector.branches import Branches, unique_rows +from tsim.statevector.branches import Branches, gf2_product from tsim.statevector.program import StatevectorComponent if TYPE_CHECKING: @@ -37,11 +45,14 @@ """Smallest chance to flip an observable undetected that counts as a logical error.""" MAX_COMBINATIONS = 30_000_000 -"""Most sets of faults that one side of the join may hold.""" +"""Most sets of faults that the stored side of the join may hold.""" + +MAX_SCANNED = 100_000_000_000 +"""Most sets of faults that the streamed side of the join may go through.""" + +FIRST_CAPACITY = 1 << 10 +"""Sets that each lane of the join can hold before its buffers grow.""" -_BATCH = 1 << 20 -_HASH_BITS = 40 -_INDEX_BITS = 24 _PAULI = {1: stim.target_z, 2: stim.target_x, 3: stim.target_y} _MEASURED = {"M": "Z", "MX": "X", "MY": "Y", "MR": "Z", "MRX": "X", "MRY": "Y"} _MEASURED_PAIR = {"MXX": "X", "MYY": "Y", "MZZ": "Z"} @@ -92,7 +103,9 @@ def __iter__(self) -> Iterator[Fault]: return iter(self.faults) -def shortest_errors(circuit: Circuit, *, max_weight: int) -> list[LogicalError]: +def shortest_errors( + circuit: Circuit, *, max_weight: int, max_errors: int | None = None +) -> list[LogicalError]: """Return every smallest set of faults that causes a logical error. A fault is a circuit error, such as one Pauli of a ``DEPOLARIZE2``, together @@ -103,22 +116,27 @@ def shortest_errors(circuit: Circuit, *, max_weight: int) -> list[LogicalError]: The search is exhaustive, so the number of faults in the result is the circuit's fault distance, and an empty result proves that the distance is - above ``max_weight``. Its cost grows as (number of faults)^(max_weight / 2) - and with the number of measurement branches of the circuit's statevector - components. + above ``max_weight``. It stores the sets of ``max_weight // 2`` faults and + streams those of the other faults, so its time grows as (number of + faults)^(max_weight - max_weight // 2). It supports up to 6 faults. Args: circuit: The circuit, with its noise, detectors and observables. max_weight: The largest number of faults to try. + max_errors: If given, return only this many of the logical errors, the + most likely ones. Returns: The logical errors with the fewest faults, most likely first, or an - empty list if up to ``max_weight`` faults cause none. + empty list if up to ``max_weight`` faults cause none. A logical error's + likelihood is its ``logical_flip_probability`` times the probabilities + of its faults. Raises: - ValueError: If a detector or an observable is random without noise, or - the search would need more than ``MAX_COMBINATIONS`` sets of faults - at once. + ValueError: If a detector or an observable is random without noise, + ``max_weight`` is above 6, or the search would need more than + ``MAX_COMBINATIONS`` stored or ``MAX_SCANNED`` streamed sets of + faults. """ if max_weight < 1: @@ -127,7 +145,7 @@ def shortest_errors(circuit: Circuit, *, max_weight: int) -> list[LogicalError]: return [] search = _Search(circuit) for weight in range(1, max_weight + 1): - found = search.logical_errors(weight) + found = search.logical_errors(weight, max_errors=max_errors) if found: return found return [] @@ -144,6 +162,7 @@ def __init__(self, circuit: Circuit) -> None: num_f = prepared.error_transform.shape[0] self._stim_circuit = circuit._stim_circ self._locations: _Locations | None = None + self._explained: dict[int, Fault] = {} # NOTE: f-vectors are Python ints here: bit j is f-bit j. bit_f = [ @@ -164,149 +183,307 @@ def __init__(self, circuit: Circuit) -> None: groups.setdefault(f, []).append(event) first += num_bits self._events = list(groups.values()) + self._fault_probability = np.array( + [sum(p for _, _, p in events) for events in self._events] + ) + # NOTE: the channel of each fault whose circuit errors share one, else -1. + self._single_channel = np.array( + [ + events[0][0] if len({e[0] for e in events}) == 1 else -1 + for events in self._events + ], + dtype=np.int64, + ) num_bytes = max(1, -(-num_f // 8)) - self._f = np.frombuffer( + packed = np.frombuffer( b"".join(f.to_bytes(num_bytes, "little") for f in groups), dtype=np.uint8 ).reshape(len(groups), num_bytes) - if len(groups) >= 1 << _INDEX_BITS: - raise ValueError( - f"the circuit has {len(groups)} faults, too many to search" - ) + self._bits = np.unpackbits(packed, axis=1, bitorder="little")[:, :num_f] num_direct = len(program.direct_f_indices) direct = program.direct_f_indices is_detector = program.output_order[:num_direct] < prepared.num_detectors detector_bits = np.unique(direct[is_detector & (direct >= 0)]) - self._observable_bits = np.unique(direct[~is_detector & (direct >= 0)]) - mask = np.zeros(8 * num_bytes, dtype=np.uint8) - mask[detector_bits] = 1 - self._detector_mask = np.packbits(mask, bitorder="little") - self._branches = [] + observable_bits = np.unique(direct[~is_detector & (direct >= 0)]) + self._branches: list[Branches] = [] for component in program.components: assert isinstance(component, StatevectorComponent) - self._branches.append(Branches(component, prepared.num_detectors)) - # NOTE: this raises if a detector or an observable is random without noise. - self._probabilities(np.zeros((1, num_bytes), dtype=np.uint8)) - - # NOTE: a GF(2)-linear hash of the direct detectors that a fault flips, - # so that a set's hash is the XOR of its faults' hashes. - bits = np.unpackbits(self._f, axis=1, bitorder="little")[:, detector_bits] + branches = Branches(component, prepared.num_detectors) + # NOTE: this raises if an output is random without noise. + assert branches.reference is not None + self._branches.append(branches) + + # NOTE: each fault is three rows of bits: the direct detectors that it + # flips, the rotation signs that it flips, and the output flips of the + # components followed by the direct observables. A set's rows are the + # XOR of its faults' rows. + signs = [np.zeros((len(groups), 0), dtype=np.uint8)] + flips = [] + self._slots: list[np.ndarray] = [] + observable: list[np.ndarray] = [] + for branches in self._branches: + local = self._bits[:, branches.f_selection] + signs.append(gf2_product(local, branches.sign_rows)) + flips.append(gf2_product(local, branches.output_rows)) + start = sum(len(slots) for slots in self._slots) + self._slots.append(np.arange(start, start + len(branches.observable))) + observable.append(branches.observable) + flips.append(self._bits[:, observable_bits]) + observable.append(np.ones(len(observable_bits), dtype=bool)) + is_observable = np.concatenate(observable) + self._direct = np.arange( + len(is_observable) - len(observable_bits), len(is_observable) + ) + self._d = _words(self._bits[:, detector_bits]) + self._s = _words(np.concatenate(signs, axis=1)) + self._o = _words(np.concatenate(flips, axis=1)) + self._det_mask = _words(~is_observable[None, :])[0] + self._obs_mask = _words(is_observable[None, :])[0] + # NOTE: a GF(2)-linear hash of the direct detectors, so that a set's hash + # is the XOR of its faults' hashes. rng = np.random.default_rng(0) - mixer = rng.integers(0, 2, size=(len(detector_bits), _HASH_BITS)) - mixed = (bits.astype(np.float32) @ mixer.astype(np.float32)).astype(np.int64) - self._hash = ( - ((mixed & 1) << np.arange(_HASH_BITS)).sum(axis=1).astype(np.uint64) + mixer = rng.integers(0, 2**63, size=len(detector_bits), dtype=np.uint64) + chosen = self._bits[:, detector_bits].astype(bool) + self._hash = np.bitwise_xor.reduce( + np.where(chosen, mixer, np.uint64(0)), axis=1, initial=np.uint64(0) ) - def logical_errors(self, weight: int) -> list[LogicalError]: + def logical_errors( + self, weight: int, *, max_errors: int | None = None + ) -> list[LogicalError]: """Return the logical errors of exactly ``weight`` faults.""" - found = [] - for sets, f in self._undetected_by_direct(weight): - one, group = unique_rows(f) - undetected, flip = self._probabilities(f[one]) - for i in np.flatnonzero(flip[group] > MIN_PROBABILITY).tolist(): - faults = [int(j) for j in sets[i]] - row = group[i] - # NOTE: two circuit errors of one channel exclude each other. - if _distinct([{e[0] for e in self._events[j]} for j in faults]): - error = LogicalError( - tuple(self._fault(j) for j in faults), - float(undetected[row]), - float(flip[row]), - ) - found.append(error) - - def likelihood(error: LogicalError) -> float: - product = error.logical_flip_probability - for fault in error.faults: - product *= fault.probability - return product - - return sorted(found, key=likelihood, reverse=True) - - def _probabilities(self, f: np.ndarray) -> tuple[np.ndarray, np.ndarray]: - """Return the chance that no detector flips, and that an observable does. - - Args: - f: Packed f-vectors that flip no direct detector, one per row. + n = len(self._events) + small, large = weight // 2, weight - weight // 2 + if large > 3: + raise ValueError(f"the search supports up to 6 faults, not {weight}") + if comb(n, small) > MAX_COMBINATIONS or comb(n, large) > MAX_SCANNED: + raise ValueError( + f"sets of {weight} out of {n} faults are too many to search; lower " + "max_weight or remove noise from the circuit" + ) + join = _Join(self, weight) + + # NOTE: one walk per distinct rotation signs serves every set with them. + signs, sets = join.collect() + if len(signs) == 0: + return [] + reps = np.bitwise_xor.reduce(self._bits[sets], axis=1) + distributions = [ + branches.outcomes(reps[:, branches.f_selection]) + for branches in self._branches + ] + sets = join.emit(self._table(signs, distributions)) + undetected, flip = self._probabilities(signs, distributions, sets) + keep = (flip > MIN_PROBABILITY) & self._distinct_channels(sets) + sets, undetected, flip = sets[keep], undetected[keep], flip[keep] + likelihood = flip * np.prod(self._fault_probability[sets], axis=1) + order = np.argsort(-likelihood, kind="stable")[:max_errors] + return [ + LogicalError( + tuple(self._fault(j) for j in sets[i].tolist()), + float(undetected[i]), + float(flip[i]), + ) + for i in order.tolist() + ] + def _distinct_channels(self, sets: np.ndarray) -> np.ndarray: + """Return whether each set can take its circuit errors from distinct channels. + + Two circuit errors of one channel exclude each other. """ - bits = np.unpackbits(f, axis=1, bitorder="little") - undetected = np.ones(len(f)) - unflipped = np.ones(len(f)) - for branches in self._branches: - passed, same = branches.probabilities(bits[:, branches.f_selection]) - undetected *= passed - unflipped *= same - unflipped[bits[:, self._observable_bits].any(axis=1)] = 0.0 - return undetected, undetected - unflipped + channel = self._single_channel[sets] + simple = (channel >= 0).all(axis=1) + ordered = np.sort(channel, axis=1) + ok = ~(ordered[:, 1:] == ordered[:, :-1]).any(axis=1) + for i in np.flatnonzero(~simple).tolist(): + ok[i] = _distinct([{e[0] for e in self._events[j]} for j in sets[i]]) + return ok + + def _table(self, signs: np.ndarray, distributions: list[list]) -> tuple: + """Return ``fault_join.scan``'s table of the logical errors of ``signs``. + + Its rows are the signs and detector deviations that can happen together. + A set with signs ``s`` and output flips ``o`` flips no detector exactly + when ``(s, o)`` is a row, and can then flip an observable unless the row + has one observable deviation only, equal to ``o``'s. + """ + width = sum(len(slots) for slots in self._slots) + len(self._direct) + keys, masked, multi, observables = [], [], [], [] + for i, key in enumerate(signs): + # NOTE: the components are independent, so any deviations of theirs + # can happen together. + rows = [np.zeros(width, dtype=bool)] + for slots, component in zip(self._slots, distributions, strict=True): + deviations, _ = component[i] + grown = [] + for row in rows: + for deviation in deviations: + new = row.copy() + new[slots] = deviation.astype(bool) + grown.append(new) + rows = grown + options: dict[bytes, set[bytes]] = {} + for row in rows: + words = _words(row[None, :])[0] + det = (words & self._det_mask).tobytes() + options.setdefault(det, set()).add((words & self._obs_mask).tobytes()) + for det, obs in options.items(): + keys.append(key) + masked.append(np.frombuffer(det, dtype=np.uint64)) + multi.append(len(obs) > 1) + observables.append(np.frombuffer(next(iter(obs)), dtype=np.uint64)) + keys_array = np.array(keys, dtype=np.uint64).reshape(len(keys), -1) + masked_array = np.array(masked, dtype=np.uint64).reshape(len(keys), -1) + index = fault_join.build_word_index( + keys_array, masked_array, self._det_mask, _capacity(len(keys)) + ) + return ( + keys_array, + masked_array, + self._det_mask, + self._obs_mask, + np.array(multi, dtype=np.bool_), + np.array(observables, dtype=np.uint64).reshape(len(keys), -1), + index, + ) - def _undetected_by_direct( - self, weight: int - ) -> Iterator[tuple[np.ndarray, np.ndarray]]: - """Yield the sets of ``weight`` faults that flip no direct detector. + def _probabilities( + self, signs: np.ndarray, distributions: list[list], sets: np.ndarray + ) -> tuple[np.ndarray, np.ndarray]: + """Return each set's chance that no detector flips, and that an observable does. - Each batch is the sets, shape ``(sets, weight)`` with the faults of a - set ascending, and their packed f-vectors. A set is the first ``weight // 2`` of its faults joined to - the others, so both sides have equal hashes. + ``distributions[j][i]`` is component ``j``'s distribution for ``signs[i]``, + which must hold the signs of every set. """ - n = len(self._events) - small = weight // 2 - for size in (small, weight - small): - if comb(n, size) > MAX_COMBINATIONS: - raise ValueError( - f"sets of {weight} out of {n} faults need {comb(n, size)} " - f"combinations at once, more than {MAX_COMBINATIONS}; lower " - "max_weight or remove noise from the circuit" + row_s = np.bitwise_xor.reduce(self._s[sets], axis=1) + index = {key.tobytes(): i for i, key in enumerate(signs)} + group = np.array([index[row.tobytes()] for row in row_s], dtype=np.int64) + flips = np.unpackbits( + np.bitwise_xor.reduce(self._o[sets], axis=1).view(np.uint8), + axis=1, + bitorder="little", + ).astype(bool) + undetected = np.ones(len(sets)) + unflipped = np.ones(len(sets)) + order = np.argsort(group, kind="stable") + bounds = np.searchsorted(group[order], np.arange(len(signs) + 1)) + for i in np.flatnonzero(np.diff(bounds)).tolist(): + rows = order[bounds[i] : bounds[i + 1]] + for branches, slots, component in zip( + self._branches, self._slots, distributions, strict=True + ): + deviations, probability = component[i] + same = ( + deviations.astype(bool)[None, :, :] == flips[rows][:, None, slots] ) - left, right = _combinations(n, small), _combinations(n, weight - small) - shift = np.uint64(_INDEX_BITS) - last = left[:, -1].astype(np.uint64) + np.uint64(1) if small else np.uint64(0) - left_key = self._set_hash(left) << shift - # NOTE: a key is the hash, then the first fault, so the right sides of a - # left side are a run of the sorted keys: those of its hash whose first - # fault comes after its last. - keys = self._set_hash(right) << shift | right[:, 0].astype(np.uint64) - order = np.argsort(keys) - keys = keys[order] - lo = np.searchsorted(keys, left_key | last) - hi = np.searchsorted( - keys, left_key | np.uint64((1 << _INDEX_BITS) - 1), "right" - ) - counts = hi - lo - ends = np.cumsum(counts) - start = 0 - while start < len(left): - done = ends[start - 1] if start else 0 - stop = max(start + 1, int(np.searchsorted(ends, done + _BATCH, "right"))) - count = counts[start:stop] - parent = np.repeat(np.arange(start, stop), count) - offset = np.arange(len(parent)) - np.repeat(np.cumsum(count) - count, count) - match = order[np.repeat(lo[start:stop], count) + offset] - sets = np.column_stack([left[parent], right[match]]) - # NOTE: equal hashes do not prove that the direct detectors cancel. - f = np.bitwise_xor.reduce(self._f[sets], axis=1) - quiet = ~(f & self._detector_mask).any(axis=1) - yield sets[quiet], f[quiet] - start = stop - - def _set_hash(self, sets: np.ndarray) -> np.ndarray: - """Return the hash of each set of faults.""" - if sets.shape[1] == 0: - return np.zeros(len(sets), dtype=np.uint64) - return np.bitwise_xor.reduce(self._hash[sets], axis=1) + passed = same[:, :, ~branches.observable].all(axis=2) + undetected[rows] *= passed @ probability + unflipped[rows] *= same.all(axis=2) @ probability + unflipped[flips[:, self._direct].any(axis=1)] = 0.0 + return undetected, undetected - unflipped def _fault(self, index: int) -> Fault: """Return fault ``index`` with its circuit errors explained.""" + if index in self._explained: + return self._explained[index] if self._locations is None: self._locations = _Locations(self._stim_circuit) events = self._events[index] - return Fault( + self._explained[index] = Fault( tuple( self._locations.of(channel, outcome) for channel, outcome, _ in events ), sum(p for _, _, p in events), ) + return self._explained[index] + + +class _Join: + """The sets of ``weight`` faults whose direct detectors cancel. + + A set is a stored left set of its first ``weight // 2`` faults and a right + set of the others, which ``fault_join.scan`` streams. + """ + + def __init__(self, search: _Search, weight: int) -> None: + self._weight = weight + self._large = weight - weight // 2 + self._search = search + self._faults = (search._d, search._s, search._o, search._hash) + small = weight // 2 + sets = _combinations(len(search._events), small) + last = sets[:, -1].astype(np.int64) if small else np.full(len(sets), -1) + hashes = np.bitwise_xor.reduce(search._hash[sets], axis=1, initial=np.uint64(0)) + order = np.lexsort((last, hashes)) + sets, last, hashes = sets[order], last[order], hashes[order] + words = ( + np.bitwise_xor.reduce(rows[sets], axis=1, initial=np.uint64(0)) + for rows in self._faults[:3] + ) + self._left = (sets, last, *words) + keys, start = np.unique(hashes, return_index=True) + end = np.append(start[1:], len(hashes)) + table = fault_join.build_index(keys, _capacity(len(keys))) + self._runs = (keys, start.astype(np.int64), end.astype(np.int64), table) + + def collect(self) -> tuple[np.ndarray, np.ndarray]: + """Return the distinct signs of the sets, and one set of each.""" + signs, sets = self._scan(fault_join.COLLECT, None) + _, first = np.unique(signs, axis=0, return_index=True) + return signs[first], sets[first] + + def emit(self, table: tuple) -> np.ndarray: + """Return the sets whose signs and output flips ``table`` marks.""" + return self._scan(fault_join.EMIT, table)[1] + + def _scan(self, mode: int, table: tuple | None) -> tuple[np.ndarray, np.ndarray]: + """Run ``fault_join.scan``, growing its buffers until they fit.""" + lanes = numba.get_num_threads() + width_s, width_o = self._search._s.shape[1], self._search._o.shape[1] + if table is None: + table = ( + np.zeros((0, width_s), np.uint64), + np.zeros((0, width_o), np.uint64), + np.zeros(width_o, np.uint64), + np.zeros(width_o, np.uint64), + np.zeros(0, np.bool_), + np.zeros((0, width_o), np.uint64), + np.full(1, -1, np.int64), + ) + collect = mode == fault_join.COLLECT + capacity = FIRST_CAPACITY + work = comb(len(self._search._events), self._large) + while True: + sets = np.zeros((lanes, capacity, self._weight), np.int32) + count = np.zeros(lanes, np.int64) + store = ( + np.zeros((lanes, capacity if collect else 0, width_s), np.uint64), + np.full((lanes, _capacity(capacity) if collect else 1), -1, np.int64), + sets, + count, + ) + found = (*table, sets, count) + args = (mode, self._large, self._faults, self._left, self._runs) + if not fault_join.scan(work, *args, store, found): + break + capacity *= 8 + sets = np.concatenate([sets[i, : count[i]] for i in range(lanes)]) + signs = np.concatenate([store[0][i, : count[i]] for i in range(lanes)]) + return signs, sets + + +def _words(bits: np.ndarray) -> np.ndarray: + """Return rows of bits as rows of uint64 words, at least one word per row.""" + width = max(1, -(-bits.shape[1] // 64)) + padded = np.zeros((len(bits), 64 * width), dtype=np.uint8) + padded[:, : bits.shape[1]] = bits + return np.packbits(padded, axis=1, bitorder="little").view(np.uint64) + + +def _capacity(count: int) -> int: + """Return the power of 2 at least twice ``count``, for an open-addressing table.""" + return 1 << max(1, (2 * count).bit_length()) def _combinations(n: int, size: int) -> np.ndarray: diff --git a/src/tsim/statevector/branches.py b/src/tsim/statevector/branches.py index 8a5e8277..621e9b28 100644 --- a/src/tsim/statevector/branches.py +++ b/src/tsim/statevector/branches.py @@ -1,10 +1,14 @@ -"""Exact outcome probabilities of a statevector component, for given f-bits. +"""Exact outcome distributions of a statevector component, for given f-bits. The sampler draws each measurement of a component's tape. ``Branches`` follows -both outcomes instead, for many rows of f-bits at once, and drops a branch as -soon as one of its detectors differs from the noiseless value. What reaches the -end of the tape gives, for each row, the exact probability that no detector of -the component flips, and that no detector and no observable flips. +both outcomes instead, for many rows of f-bits at once, and returns the exact +distribution of the component's outputs. + +The f-bits enter the tape in two ways: they set the signs of its rotations, and +they flip its outputs by a parity of their own. Only the first needs the walk. +``outcomes`` therefore reports how the outputs deviate from their noiseless +values apart from the second, so one walk serves every row with the same +rotation signs. """ from __future__ import annotations @@ -19,8 +23,8 @@ MAX_BYTES = 1 << 27 """Bytes of amplitudes that a walk aims to hold at once.""" -MAX_NOISELESS_BRANCHES = 1 << 12 -"""Most measurement branches of the noiseless circuit that a component may have.""" +MAX_BRANCHES = 1 << 20 +"""Most measurement branches that one row of f-bits may have.""" IMPOSSIBLE = 1e-12 """Weight below which a measurement outcome cannot happen.""" @@ -48,23 +52,10 @@ def _bit_parity(bits: np.ndarray, rows: np.ndarray) -> np.ndarray: return (bits @ rows.T) & 1 -def unique_rows(rows: np.ndarray) -> tuple[np.ndarray, np.ndarray]: - """Group the equal rows of a uint8 matrix. - - Returns: - The index of one row of each group, and the group of each row. - - """ - # NOTE: sorting 64-bit words is much faster than ``np.unique(rows, axis=0)``. - words = np.zeros((len(rows), max(8, -(-rows.shape[1] // 8) * 8)), dtype=np.uint8) - words[:, : rows.shape[1]] = rows - words = words.view(np.uint64) - order = np.lexsort(words.T) - first = np.ones(len(rows), dtype=bool) - first[1:] = (words[order[1:]] != words[order[:-1]]).any(axis=1) - group = np.empty(len(rows), dtype=np.int64) - group[order] = np.cumsum(first) - 1 - return order[first], group +def gf2_product(bits: np.ndarray, rows: np.ndarray) -> np.ndarray: + """Return ``bits @ rows.T`` modulo 2, as uint8.""" + product = bits.astype(np.float32) @ rows.T.astype(np.float32) + return (product.astype(np.int64) & 1).astype(np.uint8) class Branches: @@ -72,11 +63,14 @@ class Branches: Attributes: f_selection: Global f-bit index of each component f-bit. + sign_rows: The component f-bits that each rotation's sign reads. + output_rows: The component f-bits that each output slot reads. + observable: Whether each output slot is an observable. """ def __init__(self, component: StatevectorComponent, num_detectors: int) -> None: - """Read the tape of ``component``, whose outputs from ``num_detectors`` on are observables.""" + """Read the tape of ``component``; outputs from ``num_detectors`` on are observables.""" tape = component.tape num_f = len(tape.f_selection) self.f_selection = tape.f_selection @@ -84,25 +78,16 @@ def __init__(self, component: StatevectorComponent, num_detectors: int) -> None: self._size = 1 << component.width self._index = np.arange(self._size) self._lanes = max(2, MAX_BYTES // (16 * self._size)) - self._sign_f = tape.sign_row[:, :num_f].astype(np.float32) + rotation = tape.kind <= ROTATE + self._rotations = np.flatnonzero(rotation) + self.sign_rows = tape.sign_row[rotation, :num_f].astype(np.uint8) + self.output_rows = tape.output_row[:, :num_f].astype(np.uint8) self._sign_b = tape.sign_row[:, num_f:].astype(np.uint8) - self._out_f = tape.output_row[:, :num_f].astype(np.float32) self._out_b = tape.output_row[:, num_f:].astype(np.uint8) self._branch = tape.branch - num_f - # NOTE: an output is known once the last measurement that it reads ran. - measured = np.flatnonzero(tape.branch >= 0) - setter = np.full(self._out_b.shape[1], -1) - setter[self._branch[measured]] = measured - ready = np.max(np.where(self._out_b, setter[None, :], -1), axis=1, initial=-1) self._outputs = np.asarray(component.output_indices, dtype=np.int64) self._num_detectors = num_detectors - self._observable = self._outputs >= num_detectors - self._early = np.flatnonzero((ready < 0) & ~self._observable) - self._ready = [ - np.flatnonzero((ready == a) & ~self._observable) - for a in range(len(tape.kind)) - ] - self._cache: dict[bytes, tuple[float, float]] = {} + self.observable = self._outputs >= num_detectors @cached_property def reference(self) -> np.ndarray: @@ -110,20 +95,18 @@ def reference(self) -> np.ndarray: Raises: ValueError: If a detector or an observable of the component is - random without noise, or the noiseless tape has more than - ``MAX_NOISELESS_BRANCHES`` measurement branches. + random without noise. """ noiseless = np.zeros((1, len(self.f_selection)), dtype=np.uint8) - leaves = list(self._leaves(noiseless, prune=False)) - values = np.concatenate([outputs for _, _, outputs in leaves]) + values = np.concatenate([out for _, _, out in self._leaves(noiseless)]) random = np.flatnonzero((values != values[0]).any(axis=0)) if len(random): slot = int(random[0]) index = int(self._outputs[slot]) name = ( f"observable {index - self._num_detectors}" - if self._observable[slot] + if self.observable[slot] else f"detector {index}" ) raise ValueError( @@ -132,59 +115,72 @@ def reference(self) -> np.ndarray: ) return values[0] - def probabilities(self, f: np.ndarray) -> tuple[np.ndarray, np.ndarray]: - """Return each row's chance to pass the detectors, and to pass unflipped. + def outcomes(self, f: np.ndarray) -> list[tuple[np.ndarray, np.ndarray]]: + """Return each row's distribution of output deviations. + + A deviation is the outputs XOR their noiseless values XOR + ``gf2_product(f, output_rows)``, so it depends on ``f`` only through + ``gf2_product(f, sign_rows)``. Args: f: The component's f-bits, shape ``(rows, len(f_selection))``. Returns: - The probability that no detector of the component flips, and the - probability that no detector and no observable flips, per row. + For each row, the deviations that can happen, shape + ``(deviations, output slots)``, and their probabilities. + + Raises: + ValueError: If the walk has more than ``MAX_BRANCHES`` branches + per row. """ f = np.asarray(f, dtype=np.uint8) - packed = np.packbits(f, axis=1) - one, group = unique_rows(packed) - keys = [row.tobytes() for row in packed[one]] - missing = [i for i, key in enumerate(keys) if key not in self._cache] - if missing: - passed = np.zeros(len(missing)) - unflipped = np.zeros(len(missing)) - for row, weight, outputs in self._leaves(f[one[missing]], prune=True): - same = (outputs == self.reference)[:, self._observable].all(axis=1) - np.add.at(passed, row, weight) - np.add.at(unflipped, row[same], weight[same]) - for i, p, u in zip(missing, passed, unflipped, strict=True): - self._cache[keys[i]] = (float(p), float(u)) - result = np.array([self._cache[key] for key in keys]).reshape(-1, 2)[group] - return result[:, 0], result[:, 1] + flips = gf2_product(f, self.output_rows) ^ self.reference + rows, weights, deviations = [], [], [] + leaves = 0 + for row, weight, outputs in self._leaves(f): + leaves += len(row) + if leaves > MAX_BRANCHES * len(f): + raise ValueError( + f"the tape has more than {MAX_BRANCHES} measurement branches" + ) + rows.append(row) + weights.append(weight) + deviations.append(outputs ^ flips[row]) + row = np.concatenate(rows) + weight = np.concatenate(weights) + deviation = np.concatenate(deviations) + order = np.argsort(row, kind="stable") + bounds = np.searchsorted(row[order], np.arange(len(f) + 1)) + result = [] + for r in range(len(f)): + mine = order[bounds[r] : bounds[r + 1]] + values, group = np.unique(deviation[mine], axis=0, return_inverse=True) + probability = np.zeros(len(values)) + np.add.at(probability, group.ravel(), weight[mine]) + result.append((values, probability)) + return result def _leaves( - self, f: np.ndarray, *, prune: bool + self, f: np.ndarray ) -> Iterator[tuple[np.ndarray, np.ndarray, np.ndarray]]: """Yield the branches that reach the end of the tape, in batches. A batch is the row of ``f`` of each branch, its probability and its - output values. With ``prune``, only branches whose detectors have their - reference values are followed. + output values. """ tape = self._tape - sign = (f @ self._sign_f.T).astype(np.int64) & 1 - sign ^= tape.sign_const.astype(np.int64) - out = ((f @ self._out_f.T).astype(np.int64) & 1).astype(np.uint8) - out ^= tape.output_const.astype(np.uint8) - rows = np.arange(len(f)) - if prune: - early = self._early - rows = rows[(out[:, early] == self.reference[early]).all(axis=1)] + sign = np.zeros((len(f), len(tape.kind)), dtype=np.uint8) + sign[:, self._rotations] = gf2_product(f, self.sign_rows) + sign ^= tape.sign_const.astype(np.uint8) + out = gf2_product(f, self.output_rows) ^ tape.output_const.astype(np.uint8) step = max(1, self._lanes // 4) - for start in range(0, len(rows), step): - row = rows[start : start + step] + for start in range(0, len(f), step): + row = np.arange(start, min(start + step, len(f))) amps = np.zeros((len(row), self._size), dtype=np.complex128) amps[:, 0] = 1.0 bits = np.zeros((len(row), self._out_b.shape[1]), dtype=np.uint8) - yield from self._walk(0, amps, row, bits, sign, out, prune) + yield from self._walk(0, amps, row, bits, sign, out) def _walk( self, @@ -194,19 +190,16 @@ def _walk( bits: np.ndarray, sign: np.ndarray, out: np.ndarray, - prune: bool, ) -> Iterator[tuple[np.ndarray, np.ndarray, np.ndarray]]: """Run the actions from ``start`` on lanes and yield those that finish. Lane ``i`` has amplitudes ``amps[i]``, whose squared norm is its probability, belongs to row ``row[i]`` and has branch bits ``bits[i]``. - ``sign`` and ``out`` hold the rows' f-bit parts of the rotation signs - and of the outputs. + ``sign`` and ``out`` hold the rows' f-bit parts of the action signs and + of the outputs. """ tape = self._tape for a in range(start, len(tape.kind)): - if len(row) == 0: - return x, z = int(tape.x_mask[a]), int(tape.z_mask[a]) # NOTE: the Pauli P = i^|x&z| X^x Z^z takes amplitudes ``amps`` to # ``amps[:, source] * phase``. @@ -243,21 +236,11 @@ def _walk( amps = np.concatenate([child[0] for child in children]) row = np.concatenate([child[1] for child in children]) bits = np.concatenate([child[2] for child in children]) - slots = self._ready[a] - if prune and len(slots): - values = out[row][:, slots] ^ _bit_parity(bits, self._out_b[slots]) - keep = (values == self.reference[slots]).all(axis=1) - amps, row, bits = amps[keep], row[keep], bits[keep] - if not prune and len(row) > MAX_NOISELESS_BRANCHES: - raise ValueError( - "the noiseless circuit has more than " - f"{MAX_NOISELESS_BRANCHES} measurement branches in one component" - ) if len(row) > self._lanes: half = len(row) // 2 for part in (slice(0, half), slice(half, None)): yield from self._walk( - a + 1, amps[part], row[part], bits[part], sign, out, prune + a + 1, amps[part], row[part], bits[part], sign, out ) return yield row, _weights(amps), out[row] ^ _bit_parity(bits, self._out_b) diff --git a/test/unit/noise/test_faults.py b/test/unit/noise/test_faults.py index 8eef9a93..e4c4b0bf 100644 --- a/test/unit/noise/test_faults.py +++ b/test/unit/noise/test_faults.py @@ -297,3 +297,43 @@ def test_distinct(): assert _distinct([{1, 2}, {1}]) assert not _distinct([{1}, {1}]) assert not _distinct([{1, 2}, {1, 2}, {1, 2}]) + + +def test_full_buffers_grow(monkeypatch): + circuit = Circuit(_generated("surface_code:rotated_memory_z", 3)) + expected = shortest_errors(circuit, max_weight=3) + monkeypatch.setattr("tsim.noise.faults.FIRST_CAPACITY", 1) + got = shortest_errors(circuit, max_weight=3) + assert [str(e) for e in got] == [str(e) for e in expected] + + +def test_two_components_combine(): + # NOTE: two Bell pairs with T gates and an observable each are two + # statevector components. + pair = BELL.format(gate="T") + shifted = pair.replace(" 0", " 2").replace(" 1", " 3").replace("X0*X1", "X2*X3") + shifted = shifted.replace("Z0*Z1", "Z2*Z3").replace( + "OBSERVABLE_INCLUDE(0)", "OBSERVABLE_INCLUDE(1)" + ) + circuit = Circuit(pair + shifted) + assert circuit.num_observables == 2 + errors = shortest_errors(circuit, max_weight=2) + assert len(errors) == 2 + for error in errors: + assert len(error) == 1 + assert error.undetected_probability == pytest.approx(0.5) + assert error.logical_flip_probability == pytest.approx(0.5) + qubits = { + location.flipped_pauli_product[0].gate_target.value + for error in errors + for location in error.faults[0].circuit_error_locations + } + assert qubits == {0, 1, 2, 3} + + +def test_max_errors_keeps_the_most_likely(): + circuit = Circuit(_generated("surface_code:rotated_memory_z", 3)) + every = shortest_errors(circuit, max_weight=3) + best = shortest_errors(circuit, max_weight=3, max_errors=5) + assert len(every) > 5 + assert [str(e) for e in best] == [str(e) for e in every[:5]] diff --git a/test/unit/statevector/test_branches.py b/test/unit/statevector/test_branches.py index e799b3ce..5fa1d15b 100644 --- a/test/unit/statevector/test_branches.py +++ b/test/unit/statevector/test_branches.py @@ -1,4 +1,4 @@ -"""Tests for ``tsim.statevector.branches``: exact outcome probabilities of a tape.""" +"""Tests for ``tsim.statevector.branches``: exact outcome distributions of a tape.""" from test.helpers.statevector import ( CIRCUITS, @@ -12,7 +12,7 @@ import numpy as np import pytest -from tsim.statevector.branches import Branches, unique_rows +from tsim.statevector.branches import Branches, gf2_product from tsim.statevector.pbc import ComponentLayout, read_pauli_ops from tsim.statevector.program import compile_statevector_component @@ -49,7 +49,7 @@ def test_the_branches_have_the_exact_output_distribution(name, sample_detectors) branches = Branches(compiled, num_detectors=len(compiled.output_indices)) got: list[dict] = [{} for _ in patterns] f = np.array(patterns, dtype=np.uint8).reshape(len(patterns), ops.num_f) - for row, weight, outputs in branches._leaves(f, prune=False): + for row, weight, outputs in branches._leaves(f): for r, w, out in zip( row.tolist(), weight.tolist(), outputs.tolist(), strict=True ): @@ -58,36 +58,55 @@ def test_the_branches_have_the_exact_output_distribution(name, sample_detectors) assert_distributions_close(distribution, ops_distribution(ops, pattern)) -def test_probabilities_are_those_of_the_reference_outputs(): +def test_outcomes_are_the_deviations_from_the_reference(): ((compiled, ops),) = _components(DETERMINISTIC, sample_detectors=True) - # NOTE: outputs 0 and 1 are the detectors, output 2 is the observable. - is_detector = np.array(compiled.output_indices) < 2 branches = Branches(compiled, num_detectors=2) - reference = branches.reference patterns = f_patterns(ops.num_f, limit=64) - passed, unflipped = branches.probabilities(np.array(patterns, dtype=np.uint8)) - assert passed[0] == pytest.approx(1.0) - assert unflipped[0] == pytest.approx(1.0) - assert any(0.4 < p < 0.6 for p in passed) - for i, pattern in enumerate(patterns): - distribution = ops_distribution(ops, pattern) - quiet = { - outcome: p - for outcome, p in distribution.items() - if np.array_equal(np.array(outcome)[is_detector], reference[is_detector]) + f = np.array(patterns, dtype=np.uint8) + flips = gf2_product(f, branches.output_rows) ^ branches.reference + for i, (deviations, probability) in enumerate(branches.outcomes(f)): + expected = { + tuple(int(b) for b in np.array(outcome) ^ flips[i]): p + for outcome, p in ops_distribution(ops, patterns[i]).items() + if p > 1e-12 } - assert passed[i] == pytest.approx(sum(quiet.values()), abs=1e-9) - same = quiet.get(tuple(reference.tolist()), 0.0) - assert unflipped[i] == pytest.approx(same, abs=1e-9) + got = dict(zip(map(tuple, deviations.tolist()), probability, strict=True)) + assert_distributions_close(got, expected, atol=1e-9) + noiseless, probability = branches.outcomes(f[:1])[0] + assert noiseless.tolist() == [[0] * len(branches.reference)] + assert probability == pytest.approx([1.0]) + + +def test_outcomes_depend_only_on_the_rotation_signs(): + ((compiled, ops),) = _components(DETERMINISTIC, sample_detectors=True) + branches = Branches(compiled, num_detectors=2) + f = np.array(f_patterns(ops.num_f, limit=64), dtype=np.uint8) + signs = gf2_product(f, branches.sign_rows) + outcomes = branches.outcomes(f) + for i in range(len(f)): + for j in np.flatnonzero((signs == signs[i]).all(axis=1)).tolist(): + assert np.array_equal(outcomes[i][0], outcomes[j][0]) + np.testing.assert_allclose(outcomes[i][1], outcomes[j][1]) def test_many_rows_split_into_lanes(monkeypatch): ((compiled, ops),) = _components(DETERMINISTIC, sample_detectors=True) f = np.array(f_patterns(ops.num_f, limit=64), dtype=np.uint8) - expected = Branches(compiled, num_detectors=2).probabilities(f) + expected = Branches(compiled, num_detectors=2).outcomes(f) monkeypatch.setattr("tsim.statevector.branches.MAX_BYTES", 64) - got = Branches(compiled, num_detectors=2).probabilities(f) - np.testing.assert_allclose(got, expected, atol=1e-12) + got = Branches(compiled, num_detectors=2).outcomes(f) + for (a, p), (b, q) in zip(got, expected, strict=True): + assert np.array_equal(a, b) + np.testing.assert_allclose(p, q, atol=1e-12) + + +def test_too_many_branches_are_refused(monkeypatch): + ((compiled, ops),) = _components(DETERMINISTIC, sample_detectors=True) + branches = Branches(compiled, num_detectors=2) + assert branches.reference is not None + monkeypatch.setattr("tsim.statevector.branches.MAX_BRANCHES", 0) + with pytest.raises(ValueError, match="measurement branches"): + branches.outcomes(np.zeros((1, ops.num_f), dtype=np.uint8)) def test_a_random_noiseless_output_has_no_reference(): @@ -102,14 +121,4 @@ def test_a_random_noiseless_output_has_no_reference(): """ ((compiled, _),) = _components(text, sample_detectors=True) with pytest.raises(ValueError, match="detector 0 is random without noise"): - Branches(compiled, num_detectors=1).probabilities(np.zeros((1, 1))) - - -def test_unique_rows_groups_equal_rows(): - rng = np.random.default_rng(0) - rows = rng.integers(0, 3, size=(500, 11), dtype=np.uint8) - one, group = unique_rows(rows) - assert len(one) == len(np.unique(rows, axis=0)) - assert np.array_equal(rows[one][group], rows) - one, group = unique_rows(np.zeros((3, 0), dtype=np.uint8)) - assert one.tolist() == [0] and group.tolist() == [0, 0, 0] + assert Branches(compiled, num_detectors=1).reference is not None From e3e11e6a8eda72989b5a175238c568adc95c6376 Mon Sep 17 00:00:00 2001 From: Rafael Haenel Date: Wed, 18 Nov 2026 20:15:57 -0700 Subject: [PATCH 3/3] test(experimental): cover the join kernels as Python, MPAD noise and lane splits Codecov does not trace numba, so a test runs the join kernels' py_funcs and checks them against the compiled join. Co-Authored-By: Claude Opus 5.5 --- src/tsim/noise/faults.py | 2 +- test/unit/noise/test_faults.py | 63 +++++++++++++++++++++++++- test/unit/statevector/test_branches.py | 8 +++- 3 files changed, 70 insertions(+), 3 deletions(-) diff --git a/src/tsim/noise/faults.py b/src/tsim/noise/faults.py index c3ed3dab..03012167 100644 --- a/src/tsim/noise/faults.py +++ b/src/tsim/noise/faults.py @@ -563,7 +563,7 @@ def paulis(codes: Sequence[int]) -> list[stim.GateTarget]: ] elif name == "MPAD": measured = [] - else: + else: # pragma: no cover - every noisy gate of Stim is above raise NotImplementedError(f"no explanation for noise of {name}") # NOTE: Stim reads a FlippedMeasurement without a record as no flip. Its # type stub names the keywords differently from the module. diff --git a/test/unit/noise/test_faults.py b/test/unit/noise/test_faults.py index e4c4b0bf..74c2ce86 100644 --- a/test/unit/noise/test_faults.py +++ b/test/unit/noise/test_faults.py @@ -8,7 +8,8 @@ from tsim import Circuit from tsim.experimental import shortest_errors -from tsim.noise.faults import _combinations, _distinct, _Search +from tsim.noise import fault_join +from tsim.noise.faults import FIRST_CAPACITY, _combinations, _distinct, _Search # A Bell pair is stabilized by XX and ZZ, also under T on one qubit and T_DAG on # the other. An X error between the T layers turns into (X ± Y)/√2, which the XX @@ -337,3 +338,63 @@ def test_max_errors_keeps_the_most_likely(): best = shortest_errors(circuit, max_weight=3, max_errors=5) assert len(every) > 5 assert [str(e) for e in best] == [str(e) for e in every[:5]] + + +def _python_join(monkeypatch): + """Run the numba kernels of ``fault_join`` as Python, so coverage sees them.""" + for name in ( + "_mix", + "_words_hash", + "build_index", + "build_word_index", + "_find", + "_find_words", + "_visit", + "_collect", + "_emit", + "_write_set", + ): + monkeypatch.setattr(fault_join, name, getattr(fault_join, name).py_func) + monkeypatch.setattr(fault_join, "scan", lambda _, *args: fault_join._scan(*args)) + + +@pytest.mark.parametrize("capacity", [1, FIRST_CAPACITY]) +@pytest.mark.parametrize("task", ["ghz", "noises", "repetition"]) +def test_the_join_kernels_run_as_python(task, capacity, monkeypatch): + text = { + "ghz": GHZ, + "noises": NOISES, + "repetition": str(_generated("repetition_code:memory", 3)), + }[task] + weights = range(1, 7) + compiled = [_Search(Circuit(text)).logical_errors(w) for w in weights] + _python_join(monkeypatch) + monkeypatch.setattr("tsim.noise.faults.FIRST_CAPACITY", capacity) + # NOTE: the hashes multiply uint64 scalars, which wrap as they do in numba. + with np.errstate(over="ignore"): + python = [_Search(Circuit(text)).logical_errors(w) for w in weights] + assert [[str(e) for e in errors] for errors in python] == [ + [str(e) for e in errors] for errors in compiled + ] + + +def test_more_than_six_faults_are_refused(): + with pytest.raises(ValueError, match="up to 6 faults"): + _Search(Circuit(GHZ)).logical_errors(7) + + +def test_a_noisy_padding_flips_its_record(): + # NOTE: Stim explains this error as a flip of the earlier M, so the test + # cannot compare with Stim. + text = """ + R 0 + M 0 + DETECTOR rec[-1] + MPAD(0.01) 0 + DETECTOR rec[-1] + """ + search = _Search(Circuit(text)) + (location,) = search._fault(0).circuit_error_locations + # NOTE: Stim's getter returns None for a flip without a measured observable. + assert "flipped_measurement.measurement_record_index: 1" in str(location) + assert location.stack_frames[0].instruction_offset == 3 diff --git a/test/unit/statevector/test_branches.py b/test/unit/statevector/test_branches.py index 5fa1d15b..a8707342 100644 --- a/test/unit/statevector/test_branches.py +++ b/test/unit/statevector/test_branches.py @@ -43,7 +43,13 @@ def _components(text: str, *, sample_detectors: bool): @pytest.mark.parametrize("name", sorted(CIRCUITS)) @pytest.mark.parametrize("sample_detectors", [True, False]) -def test_the_branches_have_the_exact_output_distribution(name, sample_detectors): +@pytest.mark.parametrize("max_bytes", [None, 64]) +def test_the_branches_have_the_exact_output_distribution( + name, sample_detectors, max_bytes, monkeypatch +): + if max_bytes is not None: + # NOTE: tiny lanes make the walk split its branches. + monkeypatch.setattr("tsim.statevector.branches.MAX_BYTES", max_bytes) for compiled, ops in _components(CIRCUITS[name], sample_detectors=sample_detectors): patterns = f_patterns(ops.num_f, limit=8) branches = Branches(compiled, num_detectors=len(compiled.output_indices))