demsym 0.1.0__tar.gz

demsym-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Olliver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

demsym-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: demsym
+Version: 0.1.0
+Summary: Exact twisted symmetries of stim detector error models, with PyTorch equivariant decoder wrappers
+Project-URL: Homepage, https://github.com/dwatces/equivariant-quantum-ml
+Author-email: Daniel Olliver <dwatces@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: detector-error-model,equivariance,floquet-code,neural-decoder,quantum-error-correction,stim,symmetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: stim>=1.12
+Provides-Extra: dev
+Requires-Dist: pymatching; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: torch>=2.0; extra == 'dev'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# demsym
+
+**Exact twisted symmetries of stim detector error models — solved, verified,
+and wrapped into PyTorch equivariant decoders.**
+
+A symmetry of a quantum error-correcting experiment is not just a permutation
+of detectors. It acts on the *labels* too: logical observables pick up
+syndrome-dependent corrections (the logical representative moves), and on some
+codes the symmetry *mixes the logical qubits*. `demsym` works with the full
+twisted action
+
+```
+syndrome:  x  ->  x_g            (x_g[perm[d]] = x[d])
+label:     c  ->  A c  ⊕  X·x_g
+```
+
+with `A` invertible over GF(2) and `X` a per-observable syndrome-linear
+correction. Given any stim circuit and a candidate detector permutation, it
+**solves (A, X) directly from the detector error model** and verifies the
+result exactly (multiset equality of all error mechanisms — no sampling, no
+tolerance). A `None` is a real answer: the permutation is *not* a symmetry of
+that DEM.
+
+## Install
+
+```
+pip install demsym            # solver only (numpy + stim)
+pip install 'demsym[torch]'   # + the PyTorch equivariant wrapper
+```
+
+## Sixty seconds: the whole story on 20 detectors
+
+```python
+import stim, demsym
+
+c = stim.Circuit.generated(
+    "repetition_code:memory", distance=5, rounds=4,
+    before_round_data_depolarization=0.04,
+    before_measure_flip_probability=0.01)
+
+dem  = demsym.Dem.from_circuit(c)
+perm = demsym.perm_from_coords(c, lambda co: (8.0 - co[0],) + co[1:])
+
+elem = demsym.solve_action(dem, perm, name="mirror")
+print(elem)   # Element('mirror', nd=20, A=I, |chi|=20)
+```
+
+Three things just happened:
+
+1. **The mirror verifies** — it is an exact symmetry of the circuit-level DEM.
+2. **The twist is real**: `|chi| != 0`. The logical observable is the last
+   data qubit; its mirror image is the first; the difference is a chain of
+   checks — a syndrome-linear label correction. Drop it
+   (`X = 0`) and verification fails. Naive "invariant" models mis-tie exactly
+   here.
+3. Change the noise to `after_clifford_depolarization=0.01` and
+   `solve_action` returns `None` — **circuit-level extraction noise breaks
+   the spatial symmetry**. That is not a bug; it is a structural fact about
+   schedules, and finding it is the point of the tool.
+
+Build the group and an exactly equivariant model:
+
+```python
+group = demsym.close([elem], dem)          # verified closure, identity included
+model = demsym.nn.TwistedEquivariant(
+    demsym.nn.mlp_backbone(dem.num_detectors, dem.num_observables), group)
+# model(x): (batch, nd) -> (batch, 2^k) logits over joint observable classes
+demsym.nn.equivariance_probe(model, group, sampled_shots)   # ~1e-6
+```
+
+## What this machinery found (the reason it exists)
+
+Applied to memory experiments at circuit level (all numbers from logged runs;
+preprint in preparation):
+
+- **Surface code: obstruction.** No detector permutation implementing the
+  code's spatial symmetries verifies on circuit-level DEMs across 999
+  coordinate-map candidates and 1,728 extraction schedules (including
+  co-designed ones). Mechanism: hook errors de-symmetrize the schedule; a
+  mirror-axis ancilla cannot equal its own east-west swap.
+- **Honeycomb Floquet code: exactness.** With completely naive uniform
+  extraction, the circuit-level DEM of a terminated Hastings–Haah honeycomb
+  memory carries an **exact p3 space group** (translations + C3, verified on
+  all 4,584 mechanism groups at L=6). Trivalence does the work: weight-2
+  checks make 1-bit schedules automatically covariant.
+- **C3 mixes the logical qubits**: `A = [[1,1],[1,0]]`, order 3 in GL(2,F2) —
+  solved blind from the DEM. The correct decoder is therefore a 4-class
+  twisted-equivariant model; scalar per-observable equivariance cannot
+  express this.
+- **Equivariance as a learnability switch.** Matched 63k-parameter MLPs on
+  the honeycomb task (p=0.002, MWPM joint accuracy 0.947, majority 0.291):
+
+  | train samples | plain | 9-element twisted tying |
+  |---|---|---|
+  | 250 | 0.258 | **0.363** |
+  | 1,000 | 0.267 | **0.404** |
+  | 16,000 | 0.274 | **0.600** |
+  | 64,000 | 0.290 | **0.744** |
+  | 256,000 | 0.391 | **0.806** |
+
+  The plain network at 64k samples — and at 22.5× the parameters (1.4M) — sits
+  at the majority baseline; the tied model at n=1,000 beats plain at
+  n=256,000 (≥256× sample efficiency). We claim **no** superiority over
+  matched-graph MWPM anywhere; the tied model remains ~14 pp below it on this
+  task.
+
+## Validation
+
+The solver is validated against the analytic symmetry action of
+**Egorov, Bondesan & Welling, "The END: An Equivariant Neural Decoder"
+(arXiv:2304.07362)** on their setting (toric code, code capacity): the blind
+DEM solve recovers their action — including the 90°-rotation logical swap —
+**uniquely among all 24 observable permutations**, for every element. That
+bridge ships as a test (`tests/test_toric_end.py`).
+
+## Scope and honest limits
+
+- You supply candidate permutations (from detector coordinates via
+  `perm_from_coords`, or any construction you trust); demsym decides, exactly.
+  Automorphism *discovery* is out of scope for v0.1 — see AutDEC
+  (arXiv:2503.01738) for DEM-automorphism search via graph tools.
+- `X` is gauge-fixed only modulo directions invisible to every mechanism:
+  equivariance is exact on **realizable** syndromes. Probe with sampled
+  shots, not random bit-vectors.
+- Auto-enumeration of `A` candidates covers k ≤ 3 observables (GL(k,F2) =
+  1, 6, 168); beyond that, pass `A_candidates` (e.g. the observable
+  permutation matrices, as the toric validation does for k=4).
+- The wrapper costs |G| backbone passes per forward: matched parameters, not
+  matched FLOPs.
+- Twisted equivariant decoding itself is prior art (The END, above). What
+  demsym adds is the solve-from-DEM route — the one that still exists at
+  circuit level, where analytic lattice-path constructions don't apply —
+  plus the verified wrapper.
+
+## License
+
+MIT. Author: Daniel Olliver (dwatces@gmail.com).

demsym-0.1.0/README.md

@@ -0,0 +1,137 @@
+# demsym
+
+**Exact twisted symmetries of stim detector error models — solved, verified,
+and wrapped into PyTorch equivariant decoders.**
+
+A symmetry of a quantum error-correcting experiment is not just a permutation
+of detectors. It acts on the *labels* too: logical observables pick up
+syndrome-dependent corrections (the logical representative moves), and on some
+codes the symmetry *mixes the logical qubits*. `demsym` works with the full
+twisted action
+
+```
+syndrome:  x  ->  x_g            (x_g[perm[d]] = x[d])
+label:     c  ->  A c  ⊕  X·x_g
+```
+
+with `A` invertible over GF(2) and `X` a per-observable syndrome-linear
+correction. Given any stim circuit and a candidate detector permutation, it
+**solves (A, X) directly from the detector error model** and verifies the
+result exactly (multiset equality of all error mechanisms — no sampling, no
+tolerance). A `None` is a real answer: the permutation is *not* a symmetry of
+that DEM.
+
+## Install
+
+```
+pip install demsym            # solver only (numpy + stim)
+pip install 'demsym[torch]'   # + the PyTorch equivariant wrapper
+```
+
+## Sixty seconds: the whole story on 20 detectors
+
+```python
+import stim, demsym
+
+c = stim.Circuit.generated(
+    "repetition_code:memory", distance=5, rounds=4,
+    before_round_data_depolarization=0.04,
+    before_measure_flip_probability=0.01)
+
+dem  = demsym.Dem.from_circuit(c)
+perm = demsym.perm_from_coords(c, lambda co: (8.0 - co[0],) + co[1:])
+
+elem = demsym.solve_action(dem, perm, name="mirror")
+print(elem)   # Element('mirror', nd=20, A=I, |chi|=20)
+```
+
+Three things just happened:
+
+1. **The mirror verifies** — it is an exact symmetry of the circuit-level DEM.
+2. **The twist is real**: `|chi| != 0`. The logical observable is the last
+   data qubit; its mirror image is the first; the difference is a chain of
+   checks — a syndrome-linear label correction. Drop it
+   (`X = 0`) and verification fails. Naive "invariant" models mis-tie exactly
+   here.
+3. Change the noise to `after_clifford_depolarization=0.01` and
+   `solve_action` returns `None` — **circuit-level extraction noise breaks
+   the spatial symmetry**. That is not a bug; it is a structural fact about
+   schedules, and finding it is the point of the tool.
+
+Build the group and an exactly equivariant model:
+
+```python
+group = demsym.close([elem], dem)          # verified closure, identity included
+model = demsym.nn.TwistedEquivariant(
+    demsym.nn.mlp_backbone(dem.num_detectors, dem.num_observables), group)
+# model(x): (batch, nd) -> (batch, 2^k) logits over joint observable classes
+demsym.nn.equivariance_probe(model, group, sampled_shots)   # ~1e-6
+```
+
+## What this machinery found (the reason it exists)
+
+Applied to memory experiments at circuit level (all numbers from logged runs;
+preprint in preparation):
+
+- **Surface code: obstruction.** No detector permutation implementing the
+  code's spatial symmetries verifies on circuit-level DEMs across 999
+  coordinate-map candidates and 1,728 extraction schedules (including
+  co-designed ones). Mechanism: hook errors de-symmetrize the schedule; a
+  mirror-axis ancilla cannot equal its own east-west swap.
+- **Honeycomb Floquet code: exactness.** With completely naive uniform
+  extraction, the circuit-level DEM of a terminated Hastings–Haah honeycomb
+  memory carries an **exact p3 space group** (translations + C3, verified on
+  all 4,584 mechanism groups at L=6). Trivalence does the work: weight-2
+  checks make 1-bit schedules automatically covariant.
+- **C3 mixes the logical qubits**: `A = [[1,1],[1,0]]`, order 3 in GL(2,F2) —
+  solved blind from the DEM. The correct decoder is therefore a 4-class
+  twisted-equivariant model; scalar per-observable equivariance cannot
+  express this.
+- **Equivariance as a learnability switch.** Matched 63k-parameter MLPs on
+  the honeycomb task (p=0.002, MWPM joint accuracy 0.947, majority 0.291):
+
+  | train samples | plain | 9-element twisted tying |
+  |---|---|---|
+  | 250 | 0.258 | **0.363** |
+  | 1,000 | 0.267 | **0.404** |
+  | 16,000 | 0.274 | **0.600** |
+  | 64,000 | 0.290 | **0.744** |
+  | 256,000 | 0.391 | **0.806** |
+
+  The plain network at 64k samples — and at 22.5× the parameters (1.4M) — sits
+  at the majority baseline; the tied model at n=1,000 beats plain at
+  n=256,000 (≥256× sample efficiency). We claim **no** superiority over
+  matched-graph MWPM anywhere; the tied model remains ~14 pp below it on this
+  task.
+
+## Validation
+
+The solver is validated against the analytic symmetry action of
+**Egorov, Bondesan & Welling, "The END: An Equivariant Neural Decoder"
+(arXiv:2304.07362)** on their setting (toric code, code capacity): the blind
+DEM solve recovers their action — including the 90°-rotation logical swap —
+**uniquely among all 24 observable permutations**, for every element. That
+bridge ships as a test (`tests/test_toric_end.py`).
+
+## Scope and honest limits
+
+- You supply candidate permutations (from detector coordinates via
+  `perm_from_coords`, or any construction you trust); demsym decides, exactly.
+  Automorphism *discovery* is out of scope for v0.1 — see AutDEC
+  (arXiv:2503.01738) for DEM-automorphism search via graph tools.
+- `X` is gauge-fixed only modulo directions invisible to every mechanism:
+  equivariance is exact on **realizable** syndromes. Probe with sampled
+  shots, not random bit-vectors.
+- Auto-enumeration of `A` candidates covers k ≤ 3 observables (GL(k,F2) =
+  1, 6, 168); beyond that, pass `A_candidates` (e.g. the observable
+  permutation matrices, as the toric validation does for k=4).
+- The wrapper costs |G| backbone passes per forward: matched parameters, not
+  matched FLOPs.
+- Twisted equivariant decoding itself is prior art (The END, above). What
+  demsym adds is the solve-from-DEM route — the one that still exists at
+  circuit level, where analytic lattice-path constructions don't apply —
+  plus the verified wrapper.
+
+## License
+
+MIT. Author: Daniel Olliver (dwatces@gmail.com).

demsym-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "demsym"
+version = "0.1.0"
+description = "Exact twisted symmetries of stim detector error models, with PyTorch equivariant decoder wrappers"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Daniel Olliver", email = "dwatces@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.24", "stim>=1.12"]
+keywords = [
+    "quantum-error-correction", "stim", "detector-error-model",
+    "equivariance", "neural-decoder", "symmetry", "floquet-code",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+[project.optional-dependencies]
+torch = ["torch>=2.0"]
+dev = ["pytest", "torch>=2.0", "pymatching"]
+
+[project.urls]
+Homepage = "https://github.com/dwatces/equivariant-quantum-ml"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/demsym"]

demsym-0.1.0/src/demsym/__init__.py

@@ -0,0 +1,32 @@
+"""demsym — exact twisted symmetries of stim detector error models.
+
+Given a stim circuit (or hand-built noise model): test candidate detector
+permutations for exact twisted symmetry of the DEM, solving the label
+action (A, X) over GF(2) — including actions that MIX logical observables
+(A != I) and syndrome-dependent corrections (X != 0) — and wrap any
+PyTorch backbone into an exactly equivariant decoder.
+
+    import demsym
+    dem  = demsym.Dem.from_circuit(circuit)
+    perm = demsym.perm_from_coords(circuit, my_coord_map)
+    elem = demsym.solve_action(dem, perm, name="C3")   # Element or None
+    group = demsym.close([elem], dem)
+    model = demsym.nn.TwistedEquivariant(backbone, group)
+
+`None` from solve_action is a real answer: the permutation is not a
+twisted symmetry of that DEM. See the README for what this machinery found
+on the surface code (obstruction) vs the honeycomb Floquet code (exact
+symmetry, with A mixing the logical qubits).
+"""
+from .dem import Dem
+from .element import Element, apply_A, identity
+from .gf2 import gl2_matrices, solve_gf2
+from .perms import perm_from_coords
+from .solve import close, solve_action
+
+from . import nn  # noqa: E402  (torch imported lazily inside)
+
+__version__ = "0.1.0"
+__all__ = ["Dem", "Element", "apply_A", "identity", "gl2_matrices",
+           "solve_gf2", "perm_from_coords", "solve_action", "close", "nn",
+           "__version__"]

demsym-0.1.0/src/demsym/dem.py

@@ -0,0 +1,78 @@
+"""Detector-error-model extraction and grouping.
+
+The unit demsym works on is the multiset view of a DEM: error mechanisms
+grouped by their detector set, each group holding the multiset of
+(observable-mask, probability) pairs. Symmetry is then a statement about
+this object — see `solve.solve_action`.
+
+Grouping by detector set (rather than pairing individual mechanisms) is
+load-bearing: stim merges error mechanisms that hit identical (detectors,
+observables), so per-mechanism pairing across a candidate symmetry breaks on
+merge collisions while the per-group multiset comparison does not.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Iterable
+
+
+@dataclass
+class Dem:
+    """Grouped detector error model.
+
+    groups: detector-set -> sorted tuple of (obs_mask, prob) pairs, where
+    obs_mask packs observable indices as bits (bit i = observable i flipped).
+    """
+    num_detectors: int
+    num_observables: int
+    groups: dict[frozenset[int], tuple[tuple[int, float], ...]] = \
+        field(default_factory=dict)
+
+    @property
+    def num_mechanisms(self) -> int:
+        return sum(len(g) for g in self.groups.values())
+
+    @classmethod
+    def from_circuit(cls, circuit, prob_decimals: int = 9) -> "Dem":
+        """Extract from a stim.Circuit (via its detector error model)."""
+        dem = circuit.detector_error_model(flatten_loops=True)
+        return cls.from_stim_dem(dem, prob_decimals=prob_decimals)
+
+    @classmethod
+    def from_stim_dem(cls, dem, prob_decimals: int = 9) -> "Dem":
+        """Extract from a stim.DetectorErrorModel."""
+        mechs = []
+        off = 0
+        for inst in dem.flattened():
+            if inst.type == "shift_detectors":
+                t0 = inst.targets_copy()[0]
+                off += t0.val if hasattr(t0, "val") else int(t0)
+            elif inst.type == "error":
+                p = inst.args_copy()[0]
+                dets, ob = [], 0
+                for t in inst.targets_copy():
+                    if t.is_relative_detector_id():
+                        dets.append(t.val + off)
+                    elif t.is_logical_observable_id():
+                        ob ^= 1 << t.val
+                mechs.append((dets, ob, p))
+        return cls.from_mechanisms(mechs, dem.num_detectors,
+                                   dem.num_observables,
+                                   prob_decimals=prob_decimals)
+
+    @classmethod
+    def from_mechanisms(cls, mechanisms: Iterable[tuple], num_detectors: int,
+                        num_observables: int,
+                        prob_decimals: int = 9) -> "Dem":
+        """Build from explicit (detector_ids, obs_mask, probability) triples.
+
+        Use this for code-capacity / hand-built noise models that never pass
+        through stim.
+        """
+        by_v = defaultdict(list)
+        for dets, ob, p in mechanisms:
+            by_v[frozenset(int(d) for d in dets)].append(
+                (int(ob), round(float(p), prob_decimals)))
+        groups = {v: tuple(sorted(g)) for v, g in by_v.items()}
+        return cls(int(num_detectors), int(num_observables), groups)

demsym-0.1.0/src/demsym/element.py

@@ -0,0 +1,107 @@
+"""Twisted symmetry elements of a detector error model.
+
+An element acts on (syndrome, label) as
+
+    x  ->  x_g            with  x_g[perm[d]] = x[d]
+    c  ->  A c  XOR  X x_g
+
+where c is the vector of logical-observable bits, A is invertible over
+GF(2), and X (one row per observable) is a syndrome-linear correction.
+The element is a symmetry when this map sends the DEM's mechanism multiset
+to itself exactly (see `Element.verify`).
+
+Gauge note: X is determined only modulo directions invisible to every
+mechanism detector set, so two correct X's may differ as vectors while
+acting identically on realizable syndromes. All checks here are therefore
+multiset checks against the DEM, never X-equality.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .dem import Dem
+
+
+def apply_A(Amat: np.ndarray, ob: int) -> int:
+    """Apply a GF(2) matrix to a bit-packed observable mask."""
+    k = Amat.shape[0]
+    o = np.array([(ob >> i) & 1 for i in range(k)], dtype=np.int64)
+    o2 = Amat.dot(o) % 2
+    return int(sum((int(o2[i]) & 1) << i for i in range(k)))
+
+
+@dataclass
+class Element:
+    """A verified-or-candidate twisted symmetry element."""
+    name: str
+    perm: np.ndarray   # (nd,) int64, detector d -> perm[d]
+    A: np.ndarray      # (k, k) int64 over GF(2)
+    X: np.ndarray      # (k, nd) int64 over GF(2)
+
+    def __post_init__(self):
+        self.perm = np.asarray(self.perm, dtype=np.int64)
+        self.A = np.asarray(self.A, dtype=np.int64) % 2
+        self.X = np.asarray(self.X, dtype=np.int64) % 2
+
+    @property
+    def num_detectors(self) -> int:
+        return len(self.perm)
+
+    @property
+    def num_observables(self) -> int:
+        return self.A.shape[0]
+
+    @property
+    def is_identity_perm(self) -> bool:
+        return bool((self.perm == np.arange(len(self.perm))).all())
+
+    def chi_weights(self) -> list[int]:
+        return [int(r.sum()) for r in self.X]
+
+    def __matmul__(self, first: "Element") -> "Element":
+        """self @ first = apply `first`, then `self` (function composition)."""
+        if len(first.perm) != len(self.perm):
+            raise ValueError("element sizes differ")
+        perm = self.perm[first.perm]
+        A = (self.A @ first.A) % 2
+        # X of `first` acts on the intermediate syndrome x_1; rewrite it on
+        # the final syndrome x_12 (x_1[e] = x_12[self.perm[e]]), then mix
+        # its rows through self.A and add self's own correction.
+        Y = np.zeros_like(first.X)
+        Y[:, self.perm] = first.X
+        X = ((self.A @ Y) + self.X) % 2
+        return Element(f"{self.name}.{first.name}", perm, A, X)
+
+    def verify(self, dem: Dem) -> bool:
+        """Exact multiset check: does this element map the DEM to itself?"""
+        perm = self.perm
+        for v, group in dem.groups.items():
+            v2 = frozenset(int(perm[d]) for d in v)
+            tgt = dem.groups.get(v2)
+            if tgt is None:
+                return False
+            idx = [int(perm[d]) for d in v]
+            b = 0
+            for i in range(self.num_observables):
+                b |= int(self.X[i][idx].sum() % 2) << i
+            img = sorted((apply_A(self.A, o) ^ b, p) for o, p in group)
+            if tuple(img) != tgt:
+                return False
+        return True
+
+    def __repr__(self):
+        a = "I" if (self.A == np.eye(self.num_observables,
+                                     dtype=np.int64)).all() \
+            else self.A.tolist()
+        return (f"Element({self.name!r}, nd={self.num_detectors}, "
+                f"A={a}, |chi|={self.chi_weights()})")
+
+
+def identity(dem: Dem, name: str = "I") -> Element:
+    """The identity element for a given DEM."""
+    k = dem.num_observables
+    return Element(name, np.arange(dem.num_detectors),
+                   np.eye(k, dtype=np.int64),
+                   np.zeros((k, dem.num_detectors), dtype=np.int64))

demsym-0.1.0/src/demsym/gf2.py

@@ -0,0 +1,75 @@
+"""Dense GF(2) linear algebra, sized for detector-error-model problems."""
+from __future__ import annotations
+
+import numpy as np
+
+
+def solve_gf2(A: np.ndarray, b: np.ndarray) -> np.ndarray | None:
+    """Solve A x = b over GF(2). Returns one solution, or None if inconsistent.
+
+    A: (m, n) 0/1 matrix, b: (m,) 0/1 vector. Free variables are set to 0.
+    """
+    A = (np.asarray(A).copy() % 2).astype(np.int8)
+    b = (np.asarray(b).copy() % 2).astype(np.int8)
+    m, n = A.shape
+    piv, r = [], 0
+    for col in range(n):
+        if r >= m:
+            break
+        rows = np.nonzero(A[r:, col])[0]
+        if len(rows) == 0:
+            continue
+        A[[r, r + rows[0]]] = A[[r + rows[0], r]]
+        b[[r, r + rows[0]]] = b[[r + rows[0], r]]
+        mask = A[:, col].astype(bool)
+        mask[r] = False
+        A[mask] ^= A[r]
+        b[mask] ^= b[r]
+        piv.append(col)
+        r += 1
+    if np.any(b[r:]):
+        return None
+    x = np.zeros(n, dtype=np.int64)
+    for k, col in enumerate(piv):
+        x[col] = b[k]
+    return x
+
+
+def gl2_matrices(k: int) -> list[np.ndarray]:
+    """All invertible k x k matrices over GF(2). Sizes: 1, 6, 168 for k=1,2,3."""
+    if k > 3:
+        raise ValueError(
+            f"enumerating GL({k},F2) ({_gl_order(k)} matrices) is not done "
+            "automatically; pass A_candidates explicitly (e.g. permutation "
+            "matrices, or the subgroup your lattice action can produce)")
+    out = []
+    for bits in range(1 << (k * k)):
+        M = np.array([[(bits >> (i * k + j)) & 1 for j in range(k)]
+                      for i in range(k)], dtype=np.int64)
+        if _gf2_det(M):
+            out.append(M)
+    # identity first: it is the most common answer and exits the search early
+    out.sort(key=lambda M: 0 if (M == np.eye(k, dtype=np.int64)).all() else 1)
+    return out
+
+
+def _gf2_det(M: np.ndarray) -> int:
+    M = M.copy() % 2
+    n = M.shape[0]
+    for col in range(n):
+        rows = np.nonzero(M[col:, col])[0]
+        if len(rows) == 0:
+            return 0
+        r = col + rows[0]
+        M[[col, r]] = M[[r, col]]
+        mask = M[:, col].astype(bool)
+        mask[col] = False
+        M[mask] ^= M[col]
+    return 1
+
+
+def _gl_order(k: int) -> int:
+    n = 1
+    for i in range(k):
+        n *= (1 << k) - (1 << i)
+    return n

demsym-0.1.0/src/demsym/nn.py

@@ -0,0 +1,125 @@
+"""PyTorch twisted-equivariant wrapper (requires the `torch` extra).
+
+The model averages a backbone over the group with the label twist applied:
+
+    f(x)[c] = (1/|G|) sum_g backbone(x_g)[ A_g c  XOR  X_g x_g ]
+
+where x_g[perm_g[d]] = x[d]. With elements verified against the DEM, f is
+exactly equivariant on realizable syndromes (X is gauge-fixed only on
+those — probe with sampled shots, not random bit vectors).
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .element import Element, apply_A
+
+
+def _torch():
+    try:
+        import torch
+        return torch
+    except ImportError as e:  # pragma: no cover
+        raise ImportError("demsym.nn requires torch: pip install "
+                          "'demsym[torch]'") from e
+
+
+def TwistedEquivariant(backbone, elements: list[Element]):
+    """Wrap a logits backbone into a twisted-equivariant model.
+
+    backbone: torch.nn.Module mapping (batch, num_detectors) floats to
+    (batch, 2**k) logits, where k = num_observables. Class c is the
+    bit-packed joint observable value (bit i = observable i).
+    elements: the FULL group including the identity — pass the output of
+    demsym.close(...).
+    """
+    torch = _torch()
+    nn = torch.nn
+
+    if not elements:
+        raise ValueError("need at least the identity element")
+    k = elements[0].num_observables
+    nclass = 1 << k
+    if not any(e.is_identity_perm for e in elements):
+        raise ValueError("element list must include the identity "
+                         "(use demsym.close, which always adds it)")
+
+    class _TwistedEquivariant(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.backbone = backbone
+            self.num_observables = k
+            invps, chis, cmaps = [], [], []
+            for e in elements:
+                invp = np.zeros(len(e.perm), dtype=np.int64)
+                invp[e.perm] = np.arange(len(e.perm))
+                invps.append(torch.tensor(invp, dtype=torch.long))
+                chis.append(torch.tensor(e.X.astype(np.float32)))
+                cmaps.append(torch.tensor(
+                    [apply_A(e.A, c) for c in range(nclass)],
+                    dtype=torch.long))
+            self.register_buffer("IP", torch.stack(invps))   # (|G|, nd)
+            self.register_buffer("CH", torch.stack(chis))    # (|G|, k, nd)
+            self.register_buffer("CM", torch.stack(cmaps))   # (|G|, 2^k)
+
+        def forward(self, x):
+            outs = []
+            for g in range(self.IP.shape[0]):
+                xg = x[:, self.IP[g]]
+                logit = self.backbone(xg)
+                b = torch.remainder(xg @ self.CH[g].T, 2.0).long()
+                bidx = torch.zeros_like(b[:, 0])
+                for i in range(self.num_observables):
+                    bidx = bidx | (b[:, i] << i)
+                idx = self.CM[g][None, :].expand(x.shape[0], nclass) \
+                    ^ bidx[:, None]
+                outs.append(torch.gather(logit, 1, idx))
+            return torch.stack(outs).mean(dim=0)
+
+    return _TwistedEquivariant()
+
+
+def mlp_backbone(num_detectors: int, num_observables: int, hidden: int = 128):
+    """The matched-parameter 2-layer MLP used in the demsym experiments."""
+    torch = _torch()
+    nn = torch.nn
+    return nn.Sequential(nn.Linear(num_detectors, hidden), nn.ReLU(),
+                         nn.Linear(hidden, hidden), nn.ReLU(),
+                         nn.Linear(hidden, 1 << num_observables))
+
+
+def equivariance_probe(model, elements: list[Element], x) -> float:
+    """Worst-case |f(x) - twisted f(x_g)| over the group, on given syndromes.
+
+    x must be REALIZABLE syndromes (sampled shots): X carries a gauge
+    freedom invisible to mechanisms, so random bit-vectors would report
+    false violations. Expect ~1e-6 (float32 averaging noise) when the
+    construction is correct.
+    """
+    torch = _torch()
+    nclass = 1 << elements[0].num_observables
+    x = torch.as_tensor(x, dtype=torch.float32,
+                        device=next(model.parameters()).device)
+    worst = 0.0
+    model.eval()
+    with torch.no_grad():
+        fx = model(x)
+        for e in elements:
+            if e.is_identity_perm:
+                continue
+            invp = np.zeros(len(e.perm), dtype=np.int64)
+            invp[e.perm] = np.arange(len(e.perm))
+            xg = x[:, torch.tensor(invp, dtype=torch.long, device=x.device)]
+            fg = model(xg)
+            b = torch.remainder(
+                xg @ torch.tensor(e.X.astype(np.float32),
+                                  device=x.device).T, 2.0).long()
+            bidx = torch.zeros_like(b[:, 0])
+            for i in range(e.num_observables):
+                bidx = bidx | (b[:, i] << i)
+            cm = torch.tensor([apply_A(e.A, c) for c in range(nclass)],
+                              device=x.device)
+            idx = cm[None, :].expand(x.shape[0], nclass) ^ bidx[:, None]
+            worst = max(worst,
+                        float((fx - torch.gather(fg, 1, idx)).abs().max()))
+    return worst

demsym-0.1.0/src/demsym/perms.py

@@ -0,0 +1,45 @@
+"""Candidate detector permutations from stim detector coordinates."""
+from __future__ import annotations
+
+import numpy as np
+
+
+def perm_from_coords(circuit, fn, decimals: int = 6) -> np.ndarray:
+    """Detector permutation induced by a map on detector coordinates.
+
+    fn receives each detector's coordinate tuple (as floats, from
+    DETECTOR(...) annotations) and returns the image coordinate tuple.
+    Every detector must carry coordinates, and fn must permute the
+    coordinate set exactly; raises ValueError otherwise (which is itself
+    informative: the map is not a symmetry of the detector layout).
+
+    Tip for periodic layouts: fold coordinates modulo the lattice size
+    inside fn.
+    """
+    coords = circuit.get_detector_coordinates()
+    nd = circuit.num_detectors
+    if len(coords) != nd or any(len(c) == 0 for c in coords.values()):
+        raise ValueError("every detector needs a DETECTOR(...) coordinate "
+                         "annotation to use perm_from_coords")
+
+    def key(c):
+        return tuple(round(float(x), decimals) for x in c)
+
+    index = {}
+    for d, c in coords.items():
+        kk = key(c)
+        if kk in index:
+            raise ValueError(f"two detectors share coordinates {kk}; "
+                             "disambiguate (e.g. add a layer coordinate)")
+        index[kk] = d
+    perm = np.zeros(nd, dtype=np.int64)
+    for d, c in coords.items():
+        kk = key(fn(tuple(float(x) for x in c)))
+        if kk not in index:
+            raise ValueError(
+                f"image of detector {d} at {key(c)} -> {kk} is not a "
+                "detector coordinate; the map does not permute the layout")
+        perm[d] = index[kk]
+    if len(set(perm.tolist())) != nd:
+        raise ValueError("coordinate map is not a bijection on detectors")
+    return perm

demsym-0.1.0/src/demsym/solve.py

@@ -0,0 +1,130 @@
+"""Solve the twisted label action (A, X) for a candidate detector permutation.
+
+Method (per candidate A): for every detector-set group v, the image group
+perm(v) must carry the same multiset of (observable, probability) pairs
+after o -> A o XOR b, where b = X·indicator(perm(v)) is a single unknown
+GF(2) bit-vector per group. Each group constrains b to a consistent set;
+bits forced to a single value become linear equations on the rows of X,
+solved by GF(2) elimination; the candidate is accepted only after a final
+gauge-free multiset verification of the full DEM.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .dem import Dem
+from .element import Element, apply_A
+from .gf2 import gl2_matrices, solve_gf2
+
+
+def solve_action(dem: Dem, perm, name: str = "g",
+                 A_candidates: list[np.ndarray] | None = None
+                 ) -> Element | None:
+    """Find (A, X) making `perm` a twisted symmetry of `dem`.
+
+    perm: array of length num_detectors, detector d -> perm[d]. Must be a
+    bijection (raises otherwise).
+    A_candidates: optional list of k x k GF(2) matrices to try, in order.
+    Defaults to all of GL(k, F2) for k <= 3; for larger k pass candidates
+    explicitly (e.g. the 2^k observable permutation matrices).
+
+    Returns a verified Element, or None if no candidate A admits a
+    consistent X. None is a real answer: the permutation is not a twisted
+    symmetry of this DEM under any tried A.
+    """
+    perm = np.asarray(perm, dtype=np.int64)
+    nd = dem.num_detectors
+    if perm.shape != (nd,) or len(set(perm.tolist())) != nd:
+        raise ValueError(f"perm must be a bijection on {nd} detectors")
+    k = dem.num_observables
+    if A_candidates is None:
+        A_candidates = gl2_matrices(k)
+
+    groups = dem.groups
+    nb = 1 << k
+    for Amat in A_candidates:
+        Amat = np.asarray(Amat, dtype=np.int64) % 2
+        eq_rows = [[] for _ in range(k)]
+        eq_t = [[] for _ in range(k)]
+        ok = True
+        for v, group in groups.items():
+            v2 = frozenset(int(perm[d]) for d in v)
+            tgt = groups.get(v2)
+            if tgt is None:
+                ok = False
+                break
+            src = sorted((apply_A(Amat, o), p) for o, p in group)
+            cons = [b for b in range(nb)
+                    if tuple(sorted((o ^ b, p) for o, p in src)) == tgt]
+            if not cons:
+                ok = False
+                break
+            row = None
+            for bit in range(k):
+                vals = {(b >> bit) & 1 for b in cons}
+                if len(vals) == 1:
+                    if row is None:
+                        row = np.zeros(nd, dtype=np.int8)
+                        for d in v2:
+                            row[d] = 1
+                    eq_rows[bit].append(row)
+                    eq_t[bit].append(vals.pop())
+        if not ok:
+            continue
+        X, good = [], True
+        for bit in range(k):
+            if eq_rows[bit]:
+                sol = solve_gf2(np.array(eq_rows[bit]),
+                                np.array(eq_t[bit], dtype=np.int8))
+                if sol is None:
+                    good = False
+                    break
+                X.append(sol)
+            else:
+                X.append(np.zeros(nd, dtype=np.int64))
+        if not good:
+            continue
+        cand = Element(name, perm, Amat, np.stack(X))
+        if cand.verify(dem):
+            return cand
+    return None
+
+
+def close(generators: list[Element], dem: Dem,
+          max_size: int = 1024) -> list[Element]:
+    """Group closure of verified elements, with the identity included.
+
+    Every product is re-verified against the DEM (cheap, and a convention
+    self-check). Elements are deduplicated by their detector permutation.
+    Raises if the closure exceeds max_size or a product fails to verify.
+    """
+    from .element import identity
+    if not generators:
+        return [identity(dem)]
+    els = {identity(dem).perm.tobytes(): identity(dem)}
+    frontier = []
+    for g in generators:
+        key = g.perm.tobytes()
+        if key not in els:
+            if not g.verify(dem):
+                raise ValueError(f"generator {g.name} does not verify")
+            els[key] = g
+            frontier.append(g)
+    while frontier:
+        new = []
+        for g in frontier:
+            for h in list(els.values()):
+                for prod in (g @ h, h @ g):
+                    key = prod.perm.tobytes()
+                    if key in els:
+                        continue
+                    if not prod.verify(dem):
+                        raise AssertionError(
+                            f"product {prod.name} of verified elements fails "
+                            "verification — composition convention bug")
+                    els[key] = prod
+                    new.append(prod)
+                    if len(els) > max_size:
+                        raise ValueError(f"closure exceeds {max_size}")
+        frontier = new
+    return list(els.values())

demsym-0.1.0/tests/test_compose_close.py

@@ -0,0 +1,68 @@
+"""Composition law and verified group closure on the toric setting."""
+import numpy as np
+import pytest
+
+from demsym import close, identity, solve_action
+
+from toric_cc import build
+
+
+@pytest.fixture(scope="module")
+def toric4():
+    return build(L=4, p=0.1)
+
+
+def solved(dem, perms, name, cands):
+    e = solve_action(dem, perms[name], name=name, A_candidates=cands)
+    assert e is not None
+    return e
+
+
+def test_translation_closure_is_the_full_torus_group(toric4):
+    dem, perms = toric4
+    I4 = [np.eye(4, dtype=np.int64)]
+    t10 = solved(dem, perms, "T10", I4)
+    t01 = solved(dem, perms, "T01", I4)
+    grp = close([t10, t01], dem)
+    assert len(grp) == 16  # Z_4 x Z_4, identity included
+    assert all((e.A == np.eye(4, dtype=np.int64)).all() for e in grp)
+
+
+def test_rotation_powers_close_to_order_4(toric4):
+    dem, perms = toric4
+    rot = solved(dem, perms, "ROT90",
+                 [np.eye(4, dtype=np.int64)[[1, 0, 3, 2]]])
+    grp = close([rot], dem)
+    assert len(grp) == 4
+    r2 = rot @ rot
+    assert r2.verify(dem)
+    # C2 inverts both axes: A back to identity
+    assert (r2.A == np.eye(4, dtype=np.int64)).all()
+    r4 = r2 @ r2
+    assert r4.is_identity_perm
+    assert (r4.A == np.eye(4, dtype=np.int64)).all()
+    # X of the full cycle may be pure gauge; it must still verify as identity
+    assert r4.verify(dem)
+
+
+def test_composition_is_associative_on_perms_and_A(toric4):
+    dem, perms = toric4
+    I4 = [np.eye(4, dtype=np.int64)]
+    t10 = solved(dem, perms, "T10", I4)
+    t01 = solved(dem, perms, "T01", I4)
+    rot = solved(dem, perms, "ROT90",
+                 [np.eye(4, dtype=np.int64)[[1, 0, 3, 2]]])
+    a = (rot @ t10) @ t01
+    b = rot @ (t10 @ t01)
+    assert (a.perm == b.perm).all() and (a.A == b.A).all()
+    assert a.verify(dem) and b.verify(dem)
+
+
+def test_identity_neutral(toric4):
+    dem, perms = toric4
+    I4 = [np.eye(4, dtype=np.int64)]
+    t10 = solved(dem, perms, "T10", I4)
+    e = identity(dem)
+    assert ((e @ t10).perm == t10.perm).all()
+    assert ((t10 @ e).perm == t10.perm).all()
+    assert (t10 @ e).verify(dem)

demsym-0.1.0/tests/test_gf2.py

@@ -0,0 +1,48 @@
+import numpy as np
+import pytest
+
+from demsym import Dem, gl2_matrices, solve_gf2
+
+
+def test_gl_sizes():
+    assert len(gl2_matrices(1)) == 1
+    assert len(gl2_matrices(2)) == 6
+    assert len(gl2_matrices(3)) == 168
+
+
+def test_gl_identity_first_and_invertible():
+    for k in (1, 2, 3):
+        mats = gl2_matrices(k)
+        assert (mats[0] == np.eye(k, dtype=np.int64)).all()
+
+
+def test_gl_k4_requires_explicit_candidates():
+    with pytest.raises(ValueError):
+        gl2_matrices(4)
+
+
+def test_solve_gf2_roundtrip():
+    rng = np.random.default_rng(0)
+    for _ in range(20):
+        m, n = rng.integers(3, 12, size=2)
+        A = rng.integers(0, 2, size=(m, n))
+        x = rng.integers(0, 2, size=n)
+        b = A.dot(x) % 2
+        sol = solve_gf2(A, b)
+        assert sol is not None
+        assert (A.dot(sol) % 2 == b).all()
+
+
+def test_solve_gf2_inconsistent():
+    A = np.array([[1, 0], [1, 0]])
+    b = np.array([0, 1])
+    assert solve_gf2(A, b) is None
+
+
+def test_dem_groups_merge_by_detector_set():
+    dem = Dem.from_mechanisms(
+        [({0, 1}, 0b01, 0.1), ({1, 0}, 0b10, 0.2), ({2}, 0, 0.3)],
+        num_detectors=3, num_observables=2)
+    assert dem.num_mechanisms == 3
+    assert len(dem.groups) == 2
+    assert dem.groups[frozenset({0, 1})] == ((1, 0.1), (2, 0.2))

demsym-0.1.0/tests/test_repetition.py

@@ -0,0 +1,63 @@
+"""The 20-detector miniature of the whole story, on stim generated circuits:
+
+- phenomenological noise: the mirror is an exact twisted symmetry, and the
+  twist is REAL (A = I with X = 0 does not verify — the moved logical needs
+  the syndrome-linear correction);
+- circuit-level noise on the same code: the same mirror has NO solution —
+  extraction-schedule errors de-symmetrize the DEM (the obstruction).
+"""
+import numpy as np
+import pytest
+import stim
+
+from demsym import Dem, Element, identity, perm_from_coords, solve_action
+
+D = 5
+
+
+def gen(**noise):
+    return stim.Circuit.generated("repetition_code:memory", distance=D,
+                                  rounds=4, **noise)
+
+
+def mirror(c):
+    return (2.0 * (D - 1) - c[0],) + tuple(c[1:])
+
+
+@pytest.fixture(scope="module")
+def phenom():
+    c = gen(before_round_data_depolarization=0.04,
+            before_measure_flip_probability=0.01)
+    return c, Dem.from_circuit(c), perm_from_coords(c, mirror)
+
+
+def test_mirror_verifies_with_twist(phenom):
+    c, dem, perm = phenom
+    e = solve_action(dem, perm, name="mirror")
+    assert e is not None and e.verify(dem)
+    assert (e.A == np.eye(1, dtype=np.int64)).all()
+    assert sum(e.chi_weights()) > 0
+    # the twist is forced: the untwisted candidate is NOT a symmetry
+    bare = Element("mirror_untwisted", perm, e.A, np.zeros_like(e.X))
+    assert not bare.verify(dem)
+
+
+def test_identity_always_solves(phenom):
+    _, dem, _ = phenom
+    e = solve_action(dem, np.arange(dem.num_detectors))
+    assert e is not None and (e.A == np.eye(1, dtype=np.int64)).all()
+    assert identity(dem).verify(dem)
+
+
+def test_circuit_level_noise_obstructs_the_mirror():
+    c = gen(after_clifford_depolarization=0.01,
+            before_measure_flip_probability=0.01)
+    dem = Dem.from_circuit(c)
+    perm = perm_from_coords(c, mirror)
+    assert solve_action(dem, perm, name="mirror") is None
+
+
+def test_perm_from_coords_rejects_non_layout_maps(phenom):
+    c, _, _ = phenom
+    with pytest.raises(ValueError):
+        perm_from_coords(c, lambda co: (co[0] + 2.0,) + tuple(co[1:]))

demsym-0.1.0/tests/test_torch_wrapper.py

@@ -0,0 +1,59 @@
+"""Exact equivariance of the torch wrapper on realizable syndromes."""
+import numpy as np
+import pytest
+import stim
+
+from demsym import Dem, close, perm_from_coords, solve_action
+
+torch = pytest.importorskip("torch")
+
+from demsym.nn import TwistedEquivariant, equivariance_probe, mlp_backbone  # noqa: E402
+
+D = 5
+
+
+@pytest.fixture(scope="module")
+def setting():
+    c = stim.Circuit.generated("repetition_code:memory", distance=D, rounds=4,
+                               before_round_data_depolarization=0.04,
+                               before_measure_flip_probability=0.01)
+    dem = Dem.from_circuit(c)
+    perm = perm_from_coords(c, lambda co: (2.0 * (D - 1) - co[0],)
+                            + tuple(co[1:]))
+    e = solve_action(dem, perm, name="mirror")
+    grp = close([e], dem)
+    assert len(grp) == 2
+    shots = c.compile_detector_sampler(seed=7).sample(128).astype(np.float32)
+    return dem, grp, shots
+
+
+def test_probe_is_exact_on_realizable_syndromes(setting):
+    dem, grp, shots = setting
+    torch.manual_seed(0)
+    model = TwistedEquivariant(mlp_backbone(dem.num_detectors, 1, hidden=16),
+                               grp)
+    assert equivariance_probe(model, grp, shots) < 1e-5
+
+
+def test_forward_shape_and_gradients(setting):
+    dem, grp, shots = setting
+    torch.manual_seed(0)
+    model = TwistedEquivariant(mlp_backbone(dem.num_detectors, 1, hidden=16),
+                               grp)
+    x = torch.tensor(shots[:32])
+    out = model(x)
+    assert out.shape == (32, 2)
+    loss = torch.nn.functional.cross_entropy(
+        out, torch.zeros(32, dtype=torch.long))
+    loss.backward()
+    grads = [p.grad for p in model.parameters()]
+    assert all(g is not None for g in grads)
+    assert any(float(g.abs().sum()) > 0 for g in grads)
+
+
+def test_requires_identity_element(setting):
+    dem, grp, _ = setting
+    non_id = [e for e in grp if not e.is_identity_perm]
+    with pytest.raises(ValueError):
+        TwistedEquivariant(mlp_backbone(dem.num_detectors, 1, hidden=16),
+                           non_id)

demsym-0.1.0/tests/test_toric_end.py

@@ -0,0 +1,46 @@
+"""Validation against The END's analytic symmetry action (arXiv:2304.07362).
+
+On their setting — toric code, code capacity, i.i.d. depolarizing — the
+blind DEM solve must recover their Fig. 3 action UNIQUELY among all 24
+observable permutation matrices, for all four lattice elements. This is the
+ground-truth bridge: no analytic input, the action comes out of the DEM.
+"""
+import itertools
+
+import numpy as np
+import pytest
+
+from demsym import solve_action
+
+from toric_cc import build
+
+PERMS24 = [np.eye(4, dtype=np.int64)[list(p)]
+           for p in itertools.permutations(range(4))]
+EXPECTED_A = {
+    "T10": np.eye(4, dtype=np.int64),
+    "T01": np.eye(4, dtype=np.int64),
+    "ROT90": np.eye(4, dtype=np.int64)[[1, 0, 3, 2]],  # X1<->X2, Z1<->Z2
+    "MIR": np.eye(4, dtype=np.int64),
+}
+
+
+@pytest.fixture(scope="module")
+def toric():
+    return build(L=6, p=0.1)
+
+
+@pytest.mark.parametrize("name", ["T10", "T01", "ROT90", "MIR"])
+def test_blind_solve_unique_and_matches_end(toric, name):
+    dem, perms = toric
+    sols = [s for A in PERMS24
+            if (s := solve_action(dem, perms[name], name=name,
+                                  A_candidates=[A])) is not None]
+    assert len(sols) == 1, f"{name}: A not unique among 24 label perms"
+    assert (sols[0].A == EXPECTED_A[name]).all()
+    assert sols[0].verify(dem)
+
+
+def test_translations_carry_nonzero_twist(toric):
+    dem, perms = toric
+    e = solve_action(dem, perms["T10"], A_candidates=[np.eye(4, dtype=np.int64)])
+    assert e is not None and sum(e.chi_weights()) > 0

demsym-0.1.0/tests/toric_cc.py

@@ -0,0 +1,104 @@
+"""Shared toric-code code-capacity construction (The END's setting).
+
+L x L torus, qubits on edges; A(i,j) X-stabilizers are detectors 0..L^2-1,
+B(i,j) Z-stabilizers are detectors L^2..2L^2-1. Four logical observables
+gamma = (X1, X2, Z1, Z2) as bits 0..3. Mechanisms: X, Z, Y on each edge at
+p/3 (i.i.d. depolarizing, perfect syndromes).
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from demsym import Dem
+
+
+def build(L: int = 6, p: float = 0.1):
+    def vdet(i, j):
+        return (i % L) * L + (j % L)
+
+    def pdet(i, j):
+        return L * L + (i % L) * L + (j % L)
+
+    def edge_dets_X(e):
+        t, i, j = e
+        if t == "h":
+            return {pdet(i, j), pdet(i - 1, j)}
+        return {pdet(i, j), pdet(i, j - 1)}
+
+    def edge_dets_Z(e):
+        t, i, j = e
+        if t == "h":
+            return {vdet(i, j), vdet(i, j + 1)}
+        return {vdet(i, j), vdet(i + 1, j)}
+
+    edges = [(t, i, j) for i in range(L) for j in range(L) for t in ("h", "v")]
+    XBAR1 = {("h", i, 0) for i in range(L)}
+    XBAR2 = {("v", 0, j) for j in range(L)}
+    ZBAR1 = {("h", 0, j) for j in range(L)}
+    ZBAR2 = {("v", i, 0) for i in range(L)}
+
+    def obs_of(e, pauli):
+        o = 0
+        if pauli in ("Z", "Y"):
+            o |= (e in XBAR1) << 0
+            o |= (e in XBAR2) << 1
+        if pauli in ("X", "Y"):
+            o |= (e in ZBAR1) << 2
+            o |= (e in ZBAR2) << 3
+        return o
+
+    mechs = []
+    for e in edges:
+        for pauli in "XZY":
+            dets = set()
+            if pauli in ("X", "Y"):
+                dets ^= edge_dets_X(e)
+            if pauli in ("Z", "Y"):
+                dets ^= edge_dets_Z(e)
+            mechs.append((dets, obs_of(e, pauli), p / 3))
+    dem = Dem.from_mechanisms(mechs, 2 * L * L, 4)
+
+    def perm_from_edgemap(emap):
+        vsets, psets = {}, {}
+        for i in range(L):
+            for j in range(L):
+                vs = frozenset({("h", i, j), ("h", i, (j - 1) % L),
+                                ("v", i, j), ("v", (i - 1) % L, j)})
+                ps = frozenset({("h", i, j), ("h", (i + 1) % L, j),
+                                ("v", i, j), ("v", i, (j + 1) % L)})
+                vsets[vs] = vdet(i, j)
+                psets[ps] = pdet(i, j)
+        perm = np.zeros(2 * L * L, dtype=np.int64)
+        for sets in (vsets, psets):
+            for s, d in sets.items():
+                img = frozenset(emap(e) for e in s)
+                tgt = vsets.get(img, psets.get(img))
+                assert tgt is not None, "edge map is not a lattice automorphism"
+                perm[d] = tgt
+        assert len(set(perm.tolist())) == 2 * L * L
+        return perm
+
+    def T10(e):
+        t, i, j = e
+        return (t, (i + 1) % L, j)
+
+    def T01(e):
+        t, i, j = e
+        return (t, i, (j + 1) % L)
+
+    def ROT(e):
+        t, i, j = e
+        if t == "h":
+            return ("v", j % L, (-i) % L)
+        return ("h", j % L, (-i - 1) % L)
+
+    def MIR(e):
+        t, i, j = e
+        if t == "h":
+            return ("h", i, (-j - 1) % L)
+        return ("v", i, (-j) % L)
+
+    perms = {name: perm_from_edgemap(f)
+             for name, f in (("T10", T10), ("T01", T01),
+                             ("ROT90", ROT), ("MIR", MIR))}
+    return dem, perms