dist_m4ri.py

Go to the documentation of this file.

"""
dist_m4ri.py: Python wrapper for the multithreaded dist_m4ri distance calculator.
 
Provides high-level APIs for computing:
- Classical code distance: compute_classical_distance(...)
- Single-sided quantum code distance: compute_quantum_distance(...)
- CSS quantum code distance: compute_css_distance(...)
- Detector Error Model (DEM) distance: compute_dem_distance(...)
- Certified lower bound on the distance of a Stim memory circuit from its code-sized model:
  compute_model_lower_bound(...)
 
Supports distance caching, codeword export, and fallback/option for the codedistance library.
Since dist_m4ri natively handles multithreading (via POSIX threads and dynamic bracketing),
no Python-level threading or subprocess-per-core logic is necessary.
"""
 
import os
import sys
import json
import time
import random
import shutil
import hashlib
import numbers
import tempfile
import itertools
import threading
import subprocess
from pathlib import Path
from typing import List, Tuple, Union, Optional, Dict, Any, Set, Sequence, Callable
 
_codedistance_mod = None
_stim_mod = None
_qec_cert_mod = None
 
__version__ = "0.16.1"
 
# Debug bitmap (debug=N): bits 1..32768 are passed to the dist_m4ri binary (1: summary, 2: progress, 4: periodic
# status, 8: thread allocation and timing, 16: code parameters, 32: codeword supports, 64: arguments, 128: matrices,
# 256: codeword dump, 2048: no size cutoff; see its --morehelp), the higher bits are used by the Python wrapper only.
PY_DBG_COMMANDS = 1 << 16    # echo the dist_m4ri command lines and their run times
PY_DBG_CACHE = 1 << 17       # cache messages
PY_DBG_CIRCUITS = 1 << 18    # Stim circuit to DEM conversion details
PY_DBG_KEEP_FILES = 1 << 19  # keep (and list) the temporary matrix, codeword, and DEM files
BIN_DBG_MASK = 0xFFFF        # the debug bits passed to the dist_m4ri binary
VERBOSE_DEBUG = 3 | PY_DBG_COMMANDS | PY_DBG_CACHE  # debug bits implied by verbose=True (--verbose)
 
 
def parse_debug_value(val: Union[str, int]) -> int:
    """
    Parses a debug bitmap value: a non-negative decimal or hexadecimal (0x...) integer, as in the dist_m4ri binary
    (no octal: leading zeros are ignored).
 
    Args:
        val: The value, e.g., "3" or "0x10004", or an int.
 
    Returns:
        The debug bitmap.
 
    Raises:
        ValueError: If the value is not a non-negative integer.
    """
    msg = f"invalid debug={val!r}: expected a non-negative decimal or hexadecimal (0x...) integer"
    if isinstance(val, bool):
        raise ValueError(msg)
    if isinstance(val, int):
        value = val
    else:
        s = str(val).strip()
        try:
            value = int(s[2:], 16) if s.lower().startswith("0x") else int(s, 10)
        except ValueError:
            raise ValueError(msg) from None
    if value < 0:
        raise ValueError(msg)
    return value
 
 
def _get_codedistance():
    """Lazily imports the codedistance library only when requested."""
    global _codedistance_mod
    if _codedistance_mod is None:
        try:
            import codedistance
            _codedistance_mod = codedistance
        except ImportError:
            raise ImportError("codedistance library is requested but not installed.")
    return _codedistance_mod
 
 
def _get_stim():
    """Lazily imports stim only when requested."""
    global _stim_mod
    if _stim_mod is None:
        try:
            import stim
            _stim_mod = stim
        except ImportError:
            raise ImportError("stim library is requested but not installed.")
    return _stim_mod
 
 
def _get_qec_cert():
    """Lazily imports qec_cert (io, pipeline) only when requested."""
    global _qec_cert_mod
    if _qec_cert_mod is None:
        try:
            import qec_cert
            from qec_cert import io as _qec_io, pipeline as _qec_pipeline
            _qec_cert_mod = (qec_cert, _qec_io, _qec_pipeline)
        except ImportError:
            raise ImportError("qec_cert library is requested (engine='cert') but not installed.")
    return _qec_cert_mod
 
 
def _has_qec_cert() -> bool:
    """Checks whether qec_cert is importable without raising ImportError."""
    try:
        _get_qec_cert()
        return True
    except ImportError:
        return False
 
 
def __getattr__(name: str) -> Any:
    """Lazily resolves module attributes without loading heavy dependencies at startup."""
    if name == "_HAS_STIM":
        try:
            import stim
            return True
        except ImportError:
            return False
    if name == "_HAS_CODEDISTANCE":
        try:
            import codedistance
            return True
        except ImportError:
            return False
    if name == "_HAS_QEC_CERT":
        return _has_qec_cert()
    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 
# Global cache for distance results
_distance_cache: Dict[str, Any] = {}
_use_distance_cache: bool = True
_distance_cache_file: Optional[str] = None
_newer_cache_files: Set[str] = set()  # cache files written by a newer version: ignored and never overwritten
_last_run_stats: Dict[str, Any] = {}
_last_css_stats: Dict[str, Dict[str, Any]] = {"X": {}, "Z": {}}
 
# Aliases for backward compatibility with vecdec.py
_css_distance_cache = _distance_cache
_use_css_distance_cache = _use_distance_cache
 
 
def set_distance_cache_file(filepath: Optional[Union[str, Path]] = None) -> None:
    """
    Sets the default JSON file for persistent distance caching.
    If the file exists, its contents are loaded into memory.
    """
    global _distance_cache_file
    if filepath is not None:
        _distance_cache_file = str(Path(filepath).resolve())
        load_distance_cache(_distance_cache_file)
    else:
        _distance_cache_file = None
 
 
def load_distance_cache(filepath: Optional[Union[str, Path]] = None) -> Dict[str, Any]:
    """
    Loads distance cache from a JSON file into memory.
    Inspects cache version silently; a cache file written by a newer version is ignored with a warning, and it is
    never overwritten by save_distance_cache().
    """
    global _distance_cache, _distance_cache_file
    target_file = str(Path(filepath).resolve()) if filepath is not None else _distance_cache_file
    if target_file and os.path.isfile(target_file):
        try:
            with open(target_file, "r") as f:
                data = json.load(f)
            if isinstance(data, dict):
                cache_ver = data.pop("__version__", None)
                # If cache is from a future incompatible version, skip loading (and do not overwrite it)
                if cache_ver is not None and _parse_version(cache_ver) > _parse_version(__version__):
                    _newer_cache_files.add(target_file)
                    sys.stderr.write(
                        f"# Warning: Cache file '{target_file}' has newer version {cache_ver} "
                        f"(current {__version__}); ignoring incompatible cache (the file is not overwritten).\n"
                    )
                    return _distance_cache
                # Sanitize any legacy CSS cache entries where dmax was set from dmin when dmax_X == dmax_Z == 0
                for k, v in data.items():
                    if isinstance(v, dict) and k.startswith("css:"):
                        if v.get("dmax_X", 0) == 0 and v.get("dmax_Z", 0) == 0 and "dmax_X" in v:
                            v["dmax"] = 0
                _distance_cache.update(data)
        except Exception as e:
            sys.stderr.write(f"# Warning: Failed to load distance cache from {target_file}: {e}\n")
    return _distance_cache
 
 
def save_distance_cache(filepath: Optional[Union[str, Path]] = None) -> None:
    """
    Saves the in-memory distance cache to a JSON file.
    Silently writes "__version__": __version__ into the file.
    Uses atomic write via a temporary file to prevent corruption.
    A cache file written by a newer version (see load_distance_cache()) is not overwritten.
    """
    global _distance_cache, _distance_cache_file
    target_file = str(Path(filepath).resolve()) if filepath is not None else _distance_cache_file
    if not target_file or target_file in _newer_cache_files:
        return
 
    parent_dir = os.path.dirname(os.path.abspath(target_file)) or "."
    os.makedirs(parent_dir, exist_ok=True)
    fd, temp_path = tempfile.mkstemp(suffix=".tmp", prefix="dist_cache_", dir=parent_dir)
    try:
        cache_data = dict(_distance_cache)
        cache_data["__version__"] = __version__
        with open(fd, "w") as f:
            json.dump(cache_data, f, indent=2)
        os.replace(temp_path, target_file)
    except Exception as e:
        if os.path.exists(temp_path):
            try: os.remove(temp_path)
            except OSError: pass
        sys.stderr.write(f"# Warning: Failed to save distance cache to {target_file}: {e}\n")
 
 
def clear_distance_cache(cache_file: Optional[Union[str, Path]] = None, clear_file: bool = False) -> None:
    """
    Clears all cached distance calculations from memory, and optionally deletes the persistent JSON file.
    """
    global _distance_cache, _distance_cache_file
    _distance_cache.clear()
    target_file = str(Path(cache_file).resolve()) if cache_file is not None else _distance_cache_file
    if clear_file and target_file and os.path.isfile(target_file):
        try:
            os.remove(target_file)
            _newer_cache_files.discard(target_file)
        except OSError:
            pass
 
 
def enable_distance_cache() -> None:
    """Enables distance caching."""
    global _use_distance_cache
    _use_distance_cache = True
 
 
def disable_distance_cache() -> None:
    """Disables distance caching."""
    global _use_distance_cache
    _use_distance_cache = False
 
 
def get_distance_cache() -> Dict[str, Any]:
    """Returns the global distance cache dictionary."""
    global _distance_cache
    return _distance_cache
 
 
def format_bounds_list(dmin: int, dmax: int, num_rw: int) -> List[int]:
    """
    Returns [dmin, dmax, num_rw] according to:
    - [d, d, 0] if known exactly
    - [dmin, 0, 0] if there is no upper bound (dmax == 0)
    - [0, dmax, num_rw] if there is no lower bound (dmin <= 1)
    - [dmin, dmax, num_rw] otherwise
    """
    eff_dmin = dmin if dmin > 1 else 0
    eff_dmax = dmax if dmax > 0 else 0
    eff_rw = num_rw if num_rw > 0 else 0
    if eff_dmin > 0 and eff_dmin == eff_dmax:
        return [eff_dmin, eff_dmax, 0]
    elif eff_dmax == 0:
        return [eff_dmin, 0, 0]
    elif eff_dmin == 0:
        return [0, eff_dmax, eff_rw]
    else:
        return [eff_dmin, eff_dmax, eff_rw]
 
 
def format_bounds_str(bounds: List[int]) -> str:
    """Formats a bounds list [dmin, dmax, num_rw] as a string, stating '(exact)' if bounds coincide."""
    dmin, dmax, num_rw = bounds[0], bounds[1], bounds[2]
    if dmin > 0 and dmin == dmax:
        return f"{dmin} {dmax} {num_rw} (exact)"
    return f"{dmin} {dmax} {num_rw}"
 
 
def rw_infoset_find_prob(n: int, rank: int, w: int, pairs_l: int = 0) -> float:
    """
    Information-set estimate of the probability that a RW step finds a given codeword of weight w.
 
    Model: uniform random information sets (as in the dist_m4ri binary, rw_infoset_find_prob()).  A RW step
    reduces H (rank r) with a random column order; a codeword is found if exactly one of its w positions is among
    the k = n - r non-pivot columns: P1(w) = w C(n-w, k-1) / C(n, k).  Codewords of weight w > r + 1 are never
    found (P1 = 0).  With the RW pairs (pairs_l > 0, the binary's option pairs), also if exactly two of its positions
    are non-pivot columns and its other w - 2 positions avoid the l pivot rows of the buckets:
    P2(w) = C(w, 2) C(n-w, k-2) / C(n, k) * C(r - w + 2, l) / C(r, l), and the probability is P1 + P2.
 
    Args:
        n: Block length (number of columns of H).
        rank: Rank r of H.
        w: Codeword weight.
        pairs_l: The number l of pivot rows of the buckets of the RW pairs (0: no pairs).
 
    Returns:
        P1(w) + P2(w).
    """
    import math
    k = n - rank
    if n <= 0 or rank < 0 or k <= 0 or w < 1 or w > n or w - 1 > rank:
        return 0.0
 
    def log_binom(a: int, b: int) -> float:
        return math.lgamma(a + 1) - math.lgamma(b + 1) - math.lgamma(a - b + 1)
 
    p = math.exp(math.log(w) + log_binom(n - w, k - 1) - log_binom(n, k))
    if pairs_l > 0 and w >= 2 and k >= 2 and w - 2 + pairs_l <= rank:
        p += math.exp(log_binom(w, 2) + log_binom(n - w, k - 2) - log_binom(n, k) + log_binom(rank - w + 2, pairs_l)
                      - log_binom(rank, pairs_l))
    return min(1.0, p)
 
 
def rw_infoset_estimate(
    n: int, rank: int, steps: int, d: int, dmin: int = 1, step_time: float = 0.0, target: float = 0.01,
    steps_total: int = 0, pairs_l: int = 0
) -> Optional[Dict[str, Any]]:
    """
    Information-set estimate of the probability that RW missed a codeword lighter than the upper bound d found.
 
    Among the weights max(dmin, 1) <= w < d (not excluded by CC), the weight hardest to find (the smallest P(w),
    see rw_infoset_find_prob()) is used: a single codeword of this weight is missed in `steps` RW steps with uniform
    random permutations with probability (1 - P)^steps.  The number of RW steps for the target miss probability is
    given in total, with the fraction steps / steps_total of uniform steps as in the run (localized windows, used in
    about half of the steps for n >= 500, are not counted).  Same as print_rw_infoset_estimate() in the binary.
 
    Args:
        n: Block length (number of columns of H).
        rank: Rank of H.
        steps: Number of completed RW steps with uniform random permutations.
        d: Smallest weight found (the upper bound dmax).
        dmin: Certified lower bound (smaller weights are excluded).
        step_time: Wall time per RW step in seconds (0: unknown).
        target: Target miss probability (default: 0.01).
        steps_total: Number of all completed RW steps (0: the same as `steps`).
        pairs_l: The number l of pivot rows of the buckets of the RW pairs (0: no pairs), see rw_infoset_find_prob().
 
    Returns:
        Dictionary with the weight `w`, the probability `p_find` = P(w) per step, the miss probability `p_miss`,
        the total number of RW steps `steps_target` for the target miss probability (None if the codeword cannot be
        found), and the corresponding wall time `time_target` (None if unknown); or None if there are no weights to
        check.
    """
    import math
    w_lo, w_hi = max(dmin, 1), d - 1
    if w_hi < w_lo or n <= 0:
        return None
    w_hard, p1 = w_hi, rw_infoset_find_prob(n, rank, w_hi, pairs_l)  # the weight hardest to find (smallest P)
    for w in range(w_lo, w_hi):
        pw = rw_infoset_find_prob(n, rank, w, pairs_l)
        if pw < p1:
            w_hard, p1 = w, pw
    steps_target: Optional[int]
    if p1 <= 0.0:
        p_miss, steps_target = 1.0, None
    elif p1 >= 1.0:
        p_miss, steps_target = (0.0 if steps > 0 else 1.0), 1
    else:
        lq = math.log1p(-p1)
        p_miss = math.exp(steps * lq) if steps > 0 else 1.0
        steps_target = math.ceil(math.log(target) / lq)
    if steps_target is not None and steps > 0 and steps_total > steps:
        steps_target = math.ceil(steps_target * steps_total / steps)
    time_target = steps_target * step_time if (steps_target is not None and step_time > 0.0) else None
    return {"w": w_hard, "p_find": p1, "p_miss": p_miss, "steps_target": steps_target, "time_target": time_target}
 
 
def _format_duration(t: float) -> str:
    """Formats a duration in seconds (s, min, h, or days), as in the dist_m4ri binary."""
    if t < 120.0:
        return f"{t:.3g} s"
    if t < 7200.0:
        return f"{t / 60.0:.3g} min"
    if t < 172800.0:
        return f"{t / 3600.0:.3g} h"
    return f"{t / 86400.0:.3g} days"
 
 
def _parse_stderr_stats(stderr: str) -> Dict[str, Any]:
    """
    Parses codeword and hit statistics from dist_m4ri stderr output (debug & 1), and with debug & 8 the CC rounds:
    "cc_rounds", a list with an entry for each completed CC round, {"w": weight, "work": the CC thread time in s,
    "predicted": the predicted work (None if not known), "time": the wall time of the round in s, "threads": the CC
    threads (at the end of the round in method=3), "nodes": the calls of the CC recursion (None from binaries before
    0.15.0)}, and "cc_nodes", the total of the nodes of these rounds.
    """
    import re
    stats: Dict[str, Any] = {"extra_weights": [], "rw_converged": False, "hit_warnings": []}
    if not stderr:
        return stats
    hit_warning: Optional[List[str]] = None
    skip_estimate = False
    for line in stderr.splitlines():
        line_s = line.strip()
        if line_s.startswith("#   information-set estimate"):  # printed by the binary after a hit warning
            skip_estimate = True
        elif skip_estimate and line_s.startswith("#   "):
            continue
        else:
            skip_estimate = False
        if skip_estimate:
            if hit_warning is not None:
                stats["hit_warnings"].append(" ".join(hit_warning))
                hit_warning = None
            continue
        if hit_warning is not None:
            if line_s.startswith("#   "):  # continuation of a hit uniformity warning
                hit_warning.append(line_s[1:].strip())
                continue
            stats["hit_warnings"].append(" ".join(hit_warning))
            hit_warning = None
        if line_s.startswith("# Warning: non-uniform RW hit counts"):
            hit_warning = [line_s[len("# Warning: "):]]
            continue
        if line_s.startswith("# Note: drop=") and " not used: " in line_s:  # the reduction (drop=FILE) is not exact
            stats["drop_note"] = line_s.split(" not used: ", 1)[1].replace("; using the full DEM", "")
            continue
        if line_s.startswith("# Note: drop=") and "none of the listed detectors is in the DEM" in line_s:
            stats["drop_none_listed"] = True
            continue
        if line_s.startswith("# RW information sets:"):
            m_rw = re.search(
                r"n=(\d+), rank\‍(H\‍)=(\d+), steps=(\d+) \‍(uniform permutations: (\d+)\‍), ksub=(\d+), "
                r"(?:pairs=(\d+), )?([0-9.eE+-]+) s/step per thread, (\d+) RW threads", line_s
            )
            if m_rw:
                stats["rw_n"] = int(m_rw.group(1))
                stats["rw_rank"] = int(m_rw.group(2))
                stats["rw_steps"] = int(m_rw.group(3))
                stats["rw_steps_uniform"] = int(m_rw.group(4))
                stats["rw_ksub"] = int(m_rw.group(5))
                stats["rw_pairs_l"] = int(m_rw.group(6)) if m_rw.group(6) else 0
                stats["rw_step_time"] = float(m_rw.group(7))
                stats["rw_threads"] = int(m_rw.group(8))
            continue
        if line_s.startswith("# RW pairs (p=2"):  # the pairs checked, and the codewords found by pairs and singles
            m_p = re.search(r"([0-9.eE+-]+) pairs checked per step; .*: (\d+) from pairs, (\d+) from single columns",
                            line_s)
            if m_p:
                stats["rw_pairs_per_step"] = float(m_p.group(1))
                stats["rw_hits_pairs"] = int(m_p.group(2))
                stats["rw_hits_single"] = int(m_p.group(3))
            continue
        if line_s.startswith("# RW step types, w="):  # the codewords found by the uniform and by the window steps
            m_st = re.search(r"w=(\d+): uniform steps: cws=(\d+), hits=(\d+); window steps: cws=(\d+), hits=(\d+); "
                             r"both: cws=(\d+) \‍(of (\d+) cws\‍)", line_s)
            if m_st:
                v = [int(x) for x in m_st.groups()]
                stats.setdefault("rw_step_types", {})[v[0]] = {
                    "uniform_cws": v[1], "uniform_hits": v[2], "window_cws": v[3], "window_hits": v[4],
                    "both_cws": v[5], "cws": v[6]}
            continue
        if line_s.startswith("#   rounds of the DEM:"):  # the input summary (debug & 1, a DEM)
            m_r = re.search(r"D=(\d+) detectors and L=(\d+) columns per round \‍(estimated: score ([0-9.]+)\‍)", line_s)
            m_n = re.search(r"best score ([0-9.]+)", line_s)
            if m_r:
                stats["rounds"] = {"D": int(m_r.group(1)), "L": int(m_r.group(2)), "score": float(m_r.group(3))}
            elif m_n:
                stats["rounds"] = {"D": 0, "L": 0, "score": float(m_n.group(1))}
            continue
        if line_s.startswith("# CC round w=") and " work: " in line_s:  # debug & 8: a completed CC round
            m_cc = re.match(r"# CC round w=(\d+) work: ([0-9.eE+-]+) thread-s measured, (unknown|([0-9.eE+-]+) "
                            r"thread-s) predicted \‍(([0-9.]+)s(?: on (\d+) threads|, (\d+) CC threads at the end)\‍)"
                            r"(?:, (\d+) nodes)?", line_s)
            if m_cc:
                g = m_cc.groups()
                stats.setdefault("cc_rounds", []).append({
                    "w": int(g[0]), "work": float(g[1]), "predicted": float(g[3]) if g[3] else None,
                    "time": float(g[4]), "threads": int(g[5] or g[6]), "nodes": int(g[7]) if g[7] else None})
            continue
        if "RW convergence reached" in line_s:  # progress line (debug & 2) or the stop reason (debug & 1)
            stats["rw_converged"] = True
        if line_s.startswith("# codewords accumulated: total=0"):
            stats["total_cws"] = 0
        elif line_s.startswith("# codewords accumulated:"):
            m = re.search(
                r"total=(\d+),\s*min_w=(\d+):\s*cws=(\d+),\s*total_hits=(\d+),\s*"
                r"hits min=(\d+),\s*max=(\d+),\s*avg=([0-9.]+),\s*stdev=([0-9.]+)",
                line_s
            )
            if m:
                stats["total_cws"] = int(m.group(1))
                stats["min_w"] = int(m.group(2))
                stats["cws"] = int(m.group(3))
                stats["total_hits"] = int(m.group(4))
                stats["hits_min"] = int(m.group(5))
                stats["hits_max"] = int(m.group(6))
                stats["hits_avg"] = float(m.group(7))
                stats["hits_stdev"] = float(m.group(8))
            m_set = re.search(
                r"<n>=([0-9.]+) over (\d+) cws of w=(\d+)\.\.(\d+) \‍(min_hits=(\d+), cov_cws=(-?\d+)\‍)", line_s
            )
            if m_set:
                stats["avg_hits"] = float(m_set.group(1))
                stats["set_cws"] = int(m_set.group(2))
                stats["set_w_lo"] = int(m_set.group(3))
                stats["set_w_hi"] = int(m_set.group(4))
                stats["min_hits"] = int(m_set.group(5))
                stats["cov_cws"] = int(m_set.group(6))
        elif line_s.startswith("# codewords w="):
            m_w = re.search(
                r"w=(\d+):\s*cws=(\d+),\s*total_hits=(\d+),\s*"
                r"hits min=(\d+),\s*max=(\d+),\s*avg=([0-9.]+),\s*stdev=([0-9.]+)",
                line_s
            )
            if m_w:
                stats["extra_weights"].append({
                    "w": int(m_w.group(1)),
                    "cws": int(m_w.group(2)),
                    "total_hits": int(m_w.group(3)),
                    "hits_min": int(m_w.group(4)),
                    "hits_max": int(m_w.group(5)),
                    "hits_avg": float(m_w.group(6)),
                    "hits_stdev": float(m_w.group(7)),
                })
    if hit_warning is not None:
        stats["hit_warnings"].append(" ".join(hit_warning))
    cc_rounds = stats.get("cc_rounds")
    if cc_rounds and all(r["nodes"] is not None for r in cc_rounds):
        stats["cc_nodes"] = sum(r["nodes"] for r in cc_rounds)
    return stats
 
 
def explain_bounds(
    bounds: List[int],
    method: Optional[int] = None,
    label: str = "",
    stats: Optional[Dict[str, Any]] = None,
    dstop: int = 0
) -> str:
    """
    Returns a human-readable explanation of [dmin, dmax, num_rw] following README.md.
 
    Args:
        bounds: [dmin, dmax, rw_steps] list.
        method: Optional solver method (1=RW, 2=CC, 3=Bracketing).
        label: Optional prefix/label (e.g. "dX", "dZ", "").
        stats: Optional dictionary of codeword and hit statistics parsed from dist_m4ri.
        dstop: Stop target of the search (0: none); once dmin >= dstop, the upper bound is not needed, and the
            estimates of the probability that RW missed a lighter codeword are skipped.
 
    Returns:
        Multi-line formatted explanation string.
    """
    dmin, dmax, num_rw = bounds[0], bounds[1], bounds[2]
    lines = []
    prefix = f"{label} " if label else ""
    stopped = dstop > 0 and dmin >= dstop and not (dmin > 0 and dmin == dmax)
 
    # Lower bound explanation
    if dmin > 0 and dmin == dmax:
        lines.append(f"  {prefix}Lower bound (dmin = {dmin}): Exact distance certified (dmin == dmax == {dmin}).")
    elif dmin > 1:
        lines.append(f"  {prefix}Lower bound (dmin = {dmin}): All cluster weights w <= {dmin - 1} "
                     f"were exhaustively analyzed by CC without finding any non-trivial codewords.")
    else:
        lines.append(f"  {prefix}Lower bound (dmin = {dmin}): No non-trivial lower bound certified (dmin <= 1).")
 
    # Upper bound explanation
    if dmax > 0:
        lines.append(f"  {prefix}Upper bound (dmax = {dmax}): Weight of the smallest non-trivial codeword discovered.")
    else:
        lines.append(f"  {prefix}Upper bound (dmax = {dmax}): No non-trivial codeword discovered yet (dmax = 0).")
    if stopped:
        lines.append(f"  {prefix}Stop target (dstop = {dstop}): reached, the search ended once dmin >= {dstop} was "
                     f"certified (no codeword of weight < {dstop}); the upper bound is not needed.")
 
    # RW steps explanation (and why it is zero if num_rw == 0)
    if num_rw > 0:
        lines.append(f"  {prefix}Random window steps (rw_steps = {num_rw}): {num_rw} completed random "
                     f"information set searches across worker threads.")
    else:
        if dmin > 0 and dmin == dmax:
            lines.append(f"  {prefix}Random window steps (rw_steps = 0): Set to 0 because the exact distance "
                     f"d = {dmin} was proven by Connected Cluster search or certified bounds coincided.")
        elif method == 2:
            lines.append(f"  {prefix}Random window steps (rw_steps = 0): Set to 0 because Method 2 (Connected Cluster) "
                     f"is an exhaustive search that does not perform random information set (RW) sampling.")
        else:
            lines.append(f"  {prefix}Random window steps (rw_steps = 0): 0 completed random information set steps.")
 
    if stats and "total_cws" in stats:
        if stats["total_cws"] > 0:
            lines.append(
                f"  {prefix}Codewords accumulated: {stats['total_cws']} distinct "
                f"(w = {stats['min_w']}: {stats['cws']} codewords, {stats['total_hits']} total hits; "
                f"hits min = {stats['hits_min']}, max = {stats['hits_max']}, "
                f"avg = {stats['hits_avg']:.2f}, stdev = {stats['hits_stdev']:.2f})."
            )
            if stats.get("min_hits", 0) > 0 and "avg_hits" in stats:
                import math
                conv_str = "CONVERGED" if stats.get("rw_converged") else "not converged"
                lines.append(
                    f"  {prefix}Hit convergence (min_hits = {stats['min_hits']}, "
                    f"cov_cws = {stats['cov_cws']}): <n> = {stats['avg_hits']:.2f} average hits per codeword "
                    f"({stats['set_cws']} codewords of weight {stats['set_w_lo']}..{stats['set_w_hi']}), "
                    f"P_fail ~ exp(-<n>) = {math.exp(-stats['avg_hits']):.2g} ({conv_str})."
                )
            for ew in stats.get("extra_weights", []):
                lines.append(
                    f"  {prefix}Codewords (w = {ew['w']}): {ew['cws']} codewords, "
                    f"{ew['total_hits']} total hits; hits min = {ew['hits_min']}, "
                    f"max = {ew['hits_max']}, avg = {ew['hits_avg']:.2f}, "
                    f"stdev = {ew['hits_stdev']:.2f}."
                )
            n_all, n_unif = stats.get("rw_steps", 0), stats.get("rw_steps_uniform", 0)
            for w, st in sorted(stats.get("rw_step_types", {}).items()):
                lines.append(
                    f"  {prefix}Codewords (w = {w}) by RW step type: {st['uniform_cws']} found in the {n_unif} uniform "
                    f"steps ({st['uniform_hits']} hits), {st['window_cws']} in the {n_all - n_unif} window steps "
                    f"({st['window_hits']} hits), {st['both_cws']} in both (of {st['cws']} codewords)."
                )
            if stats.get("rw_pairs_l", 0) > 0 and "rw_pairs_per_step" in stats:
                lines.append(
                    f"  {prefix}RW pairs (p=2, buckets of l = {stats['rw_pairs_l']} pivot rows): "
                    f"{stats['rw_pairs_per_step']:.3g} pairs checked per RW step; codewords recorded with weight up to "
                    f"the upper bound: {stats['rw_hits_pairs']} from pairs, {stats['rw_hits_single']} from single "
                    f"columns."
                )
            for hw in stats.get("hit_warnings", []):
                lines.append(f"  {prefix}WARNING: {hw}")
        else:
            lines.append(f"  {prefix}Codewords accumulated: 0 distinct non-trivial codewords found.")
 
    # The RW upper bound is not certified: estimated probability that RW missed a lighter codeword
    if stats and num_rw > 0 and dmax > max(dmin, 1) and not stopped:
        import math
        rw_threads = stats.get("rw_threads", 0)
        step_wall = stats.get("rw_step_time", 0.0) / rw_threads if rw_threads > 0 else 0.0
        avg = stats.get("avg_hits", 0.0)
        if stats.get("min_hits", 0) > 0 and avg > 0.0:
            p_hit = math.exp(-avg)
            if p_hit > 0.01:
                need = math.ceil(num_rw * math.log(100.0) / avg)  # the average number of hits grows with the steps
                t_str = f", ~{_format_duration((need - num_rw) * step_wall)} more" if step_wall > 0.0 else ""
                lines.append(f"  {prefix}Hit-based estimate: P_fail ~ exp(-<n>) = {p_hit:.2g}; 1% after about {need} "
                             f"RW steps in total{t_str}.")
            else:
                lines.append(f"  {prefix}Hit-based estimate: P_fail ~ exp(-<n>) = {p_hit:.2g} (below 1%).")
        n_unif = stats.get("rw_steps_uniform", 0)
        if stats.get("rw_n", 0) > 0 and stats.get("rw_ksub", 0) == 0 and n_unif > 0:
            n_cols, rank = stats["rw_n"], stats["rw_rank"]
            pairs_l = stats.get("rw_pairs_l", 0)
            est = rw_infoset_estimate(n_cols, rank, n_unif, dmax, dmin=max(dmin, 1), step_time=step_wall,
                                      steps_total=stats.get("rw_steps", n_unif), pairs_l=pairs_l)
            if est is not None and est["steps_target"] is None:
                lines.append(f"  {prefix}Information-set estimate: a codeword of weight {est['w']} cannot be found "
                             f"by RW (n = {n_cols}, rank(H) = {rank}).")
            elif est is not None:
                t_str = (f", ~{_format_duration(est['time_target'])}" if est["time_target"] is not None else "")
                p_str = f" with pairs, l = {pairs_l}" if pairs_l > 0 else ""
                lines.append(
                    f"  {prefix}Information-set estimate (uniform random information sets{p_str}; n = {n_cols}, "
                    f"rank(H) = {rank}, {n_unif} of {stats.get('rw_steps', n_unif)} RW steps uniform): a single "
                    f"codeword of weight {est['w']} < {dmax} is found with probability {est['p_find']:.3g} per RW "
                    f"step and would be missed with probability {est['p_miss']:.2g}; 1% after about "
                    f"{est['steps_target']} RW steps in total{t_str}."
                )
                # (with min_hits=0, the binary does not count the hits: each codeword then has a single hit)
                if stats.get("min_w") == dmax and "hits_avg" in stats and stats.get("min_hits", 0) > 0:
                    n_all = stats.get("rw_steps", n_unif)
                    p1 = rw_infoset_find_prob(n_cols, rank, dmax, pairs_l)
                    st = stats.get("rw_step_types", {}).get(dmax)
                    if st is not None and st["cws"] > 0:  # the hits of the uniform steps only
                        n_ref, obs, note = n_unif, st["uniform_hits"] / st["cws"], " in the uniform steps"
                    else:
                        n_ref, obs = n_all, stats["hits_avg"]
                        note = "" if n_unif == n_all else ", including the steps with localized windows"
                    exp_hits = n_ref * p1
                    verdict = ("the uniform model is conservative here" if obs >= exp_hits else
                               "codewords are found less often than in the uniform model, the information-set "
                               "estimate may be optimistic")
                    lines.append(
                        f"  {prefix}Model check: expected hits per codeword of weight {dmax} in {n_ref} uniform RW "
                        f"steps: {exp_hits:.3g}, observed average {obs:.2f}{note} ({verdict})."
                    )
        elif stats.get("rw_n", 0) > 0:
            lines.append(f"  {prefix}Information-set estimate: not available (ksub > 0 or kwin > 0: no uniform "
                         f"random information sets).")
 
    return "\n".join(lines)
 
 
def get_cached_distance(
    H: Optional[Any] = None,
    G: Optional[Any] = None,
    L: Optional[Any] = None,
    Hx: Optional[Any] = None,
    Hz: Optional[Any] = None,
    Lx: Optional[Any] = None,
    Lz: Optional[Any] = None,
    dem: Optional[Any] = None,
    circuit: Optional[Any] = None,
    pmin: float = 0.0,
    cache_file: Optional[Union[str, Path]] = None,
    start: Optional[Union[int, str, Sequence[int]]] = None,
    simple: Optional[bool] = None,
    full: Optional[bool] = None,
    basis: Optional[str] = None,
    rounds: Optional[int] = None,
    p_noise: float = 0.001,
    force_noise: bool = False,
    start_scan: bool = False
) -> Optional[Dict[str, Any]]:
    """
    Retrieves the cached distance entry (including bounds and cumulative rw_steps)
    for a given code matrix, CSS code, or DEM.
 
    If the expert CC start-column list `start` is given (see compute_classical_distance), the
    separate start-list record (cache key suffix ':start=a,b,c', or ':start=a,b,c:scan' with start_scan=True) is
    returned instead of the main record.
 
    For a CSS code (Hx and Hz, optionally Lx / Lz), the entry is assembled from the records of its two sectors,
    the quantum codes (H=Hx, G=Hz) -> dZ and (H=Hz, G=Hx) -> dX (shared with compute_quantum_distance()): the fields
    dmin_X, dmax_X, rw_steps_X, dX, cws_X (the same for Z), and dist, dmin, dmax, rw_steps of d = min(dX, dZ).
 
    For a Stim circuit (circuit, or dem with a .stim file), the cache key is that of the DEM processed as in
    compute_dem_distance(), with the same options rounds, p_noise, and force_noise (simple and full are disabled since
    version 0.13.0: ignored with a warning to stderr; basis does not change the DEM).
 
    Returns:
        dict with keys {"dist", "dmin", "dmax", "rw_steps", ...} or None if not cached.
    """
    global _distance_cache, _distance_cache_file
    eff_cache_file = str(Path(cache_file).resolve()) if cache_file is not None else _distance_cache_file
    if eff_cache_file:
        load_distance_cache(eff_cache_file)
    sfx = _start_key_suffix(_scan_start_list(_normalize_start_list(start), start_scan))
 
    if H is not None:
        entry = _distance_cache.get(_matrix_cache_key(H, G, L, classical=(G is None and L is None)) + sfx)
        if entry:
            entry = dict(entry)
            entry["d_info"] = format_bounds_list(entry.get("dmin", 0), entry.get("dmax", 0), entry.get("rw_steps", 0))
        return entry
    elif Hx is not None or Hz is not None:
        # a CSS code is cached as its two sectors (H=Hx, G=Hz) -> dZ and (H=Hz, G=Hx) -> dX, see compute_css_distance()
        if Hx is None or Hz is None:
            return None
        _migrate_css_records(Hx, Hz, Lx, Lz, eff_cache_file)
        codes = _css_sector_codes(Hx, Hz, Lx, Lz)
        sec = {s: _distance_cache.get(_matrix_cache_key(*codes[s]) + sfx) for s in ("X", "Z")}
        if not sec["X"] and not sec["Z"]:
            return None
        entry = {}
        bounds = {}
        for s in ("X", "Z"):
            rec = sec[s] or {}
            b = (rec.get("dmin", 0) or 0, rec.get("dmax", 0) or 0, rec.get("rw_steps", 0) or 0)
            bounds[s] = b
            entry[f"dmin_{s}"], entry[f"dmax_{s}"], entry[f"rw_steps_{s}"] = b
            entry[f"d{s}"] = format_bounds_list(*b)
            entry[f"cws_{s}"] = list(rec.get("cws", []))
        dist, d_lo, d_hi, rw = _css_combine(bounds["X"], bounds["Z"])
        entry.update({"dist": dist, "dmin": d_lo, "dmax": d_hi, "rw_steps": rw})
        return entry
    elif dem is not None or circuit is not None:
        # the key of compute_dem_distance(): a Stim circuit is processed and converted in the same way
        _warn_disabled_simple_full(simple, full)
        dem_obj, _, _ = _dem_from_input(dem, circuit, basis=basis, rounds=rounds, p_noise=p_noise,
                                        force_noise=force_noise)
        entry = _distance_cache.get(_dem_cache_key(dem_obj, pmin) + sfx)
        if entry:
            entry = dict(entry)
            entry["d_info"] = format_bounds_list(entry.get("dmin", 0), entry.get("dmax", 0), entry.get("rw_steps", 0))
        return entry
    return None
 
 
# Backward-compatibility aliases
clear_css_distance_cache = clear_distance_cache
enable_css_distance_cache = enable_distance_cache
disable_css_distance_cache = disable_distance_cache
 
 
def get_sparse_array_state(A) -> str:
    """Returns a deterministic string representation for JSON-compatible cache keys."""
    if A is None:
        return "none"
    if isinstance(A, (str, Path)):
        path_str = str(Path(A).resolve())
        if os.path.isfile(path_str):
            try:
                with open(path_str, "rb") as f:
                    content_h = hashlib.sha256(f.read()).hexdigest()
                return f"file:{path_str}:{content_h}"
            except Exception:
                return f"file:{path_str}"
        return path_str
    if hasattr(A, 'shape') and hasattr(A, 'dtype') and hasattr(A, 'tobytes'):
        h = hashlib.sha256(A.tobytes()).hexdigest()
        dtype_str = getattr(A.dtype, 'str', str(A.dtype))
        return f"ndarray:{A.shape}:{dtype_str}:{h}"
    if hasattr(A, 'tocsr'):
        csr = A.tocsr()
        h = hashlib.sha256(csr.data.tobytes() + csr.indices.tobytes() + csr.indptr.tobytes()).hexdigest()
        return f"csr:{csr.shape}:{h}"
    if hasattr(A, 'tobytes'):
        h = hashlib.sha256(A.tobytes()).hexdigest()
        return f"bytes:{h}"
    h = hashlib.sha256(str(A).encode('utf-8')).hexdigest()
    return f"str_sha256:{h}"
 
 
def create_unique_file(directory: Union[str, Path] = "tmp", extension: str = ".tmp") -> str:
    """Creates a unique temporary file path and ensures the parent directory exists."""
    try:
        os.makedirs(directory, exist_ok=True)
        fd, path = tempfile.mkstemp(suffix=extension, dir=directory)
    except OSError:
        fd, path = tempfile.mkstemp(suffix=extension)
    os.close(fd)
    return path
 
 
def _remove_temp_files(files: Sequence[Optional[str]], debug: int = 0) -> None:
    """Removes the temporary files `files` (None entries are skipped); with the debug bit PY_DBG_KEEP_FILES, the
    files are kept and listed instead."""
    for f in files:
        if not f or not os.path.exists(f):
            continue
        if debug & PY_DBG_KEEP_FILES:
            print(f"[dist_m4ri] Kept temporary file: {f}")
            continue
        try:
            os.remove(f)
        except OSError:
            pass
 
 
def read_sparse_vectors(filepath: str) -> List[List[int]]:
    """
    Reads a list of sparse vectors from a text file in NZLIST format,
    converting from 1-based indexing (in the file) to 0-based indexing (in Python).
 
    Args:
        filepath (str): The path to the text file.
 
    Returns:
        list of list of int: A list where each element is a 0-based sparse vector.
    """
    sparse_vectors = []
    if not os.path.exists(filepath) or os.path.getsize(filepath) == 0:
        return sparse_vectors
 
    with open(filepath, 'r') as f:
        first_line = f.readline().strip()
        if not first_line:
            return sparse_vectors
        if first_line != '%% NZLIST':
            raise ValueError(f"Invalid file format in {filepath}: Missing '%% NZLIST' header.")
 
        for line_num, line in enumerate(f, start=2):
            line = line.strip()
            if not line or line.startswith('%'):
                continue
            try:
                parts = list(map(int, line.split()))
            except ValueError:
                raise ValueError(f"Non-integer data found on line {line_num}: {line}")
 
            stated_length = parts[0]
            vector_elements = [x - 1 for x in parts[1:]]
            if len(vector_elements) != stated_length:
                raise ValueError(
                    f"Length mismatch on line {line_num}. "
                    f"Expected {stated_length} elements, but found {len(vector_elements)}."
                )
            sparse_vectors.append(vector_elements)
 
    return sparse_vectors
 
 
def find_dist_m4ri_binary(custom_path: Optional[str] = None) -> str:
    """Finds the dist_m4ri executable."""
    if custom_path:
        if os.path.isfile(custom_path) and os.access(custom_path, os.X_OK):
            return os.path.abspath(custom_path)
        raise FileNotFoundError(
            f"Specified executable '{custom_path}' not found or not executable."
        )
 
    pkg_dir = os.path.dirname(os.path.abspath(__file__))
    candidates = [
        os.path.join(pkg_dir, "src", "dist_m4ri"),
        os.path.join(pkg_dir, "dist_m4ri"),
        os.path.join(pkg_dir, "bin", "dist_m4ri"),
        os.path.join(pkg_dir, "..", "dist-m4ri", "src", "dist_m4ri"),
        os.path.join(os.getcwd(), "src", "dist_m4ri"),
        os.path.join(os.getcwd(), "dist_m4ri"),
        os.path.join(os.getcwd(), "bin", "dist_m4ri"),
    ]
 
    for cand in candidates:
        if os.path.isfile(cand) and os.access(cand, os.X_OK):
            return os.path.abspath(cand)
 
    which_path = shutil.which("dist_m4ri")
    if which_path:
        return which_path
 
    raise FileNotFoundError(
        "Could not find executable 'dist_m4ri'. Please run 'make -C src' to build it."
    )
 
 
def _parse_version(v_str: str) -> Tuple[int, ...]:
    import re
    parts = re.findall(r"\d+", v_str)
    return tuple(int(p) for p in parts) if parts else (0,)
 
 
def _binary_version(binary_path: Optional[str] = None) -> Tuple[Optional[str], Optional[str], Optional[str]]:
    """
    The dist_m4ri binary and its version (from `dist_m4ri --version`).
 
    Returns:
        (path, version, error): path is None if the binary is not found; version is None if it is unknown (then
        error is the reason, or None if the binary does not support --version).
    """
    try:
        path = find_dist_m4ri_binary(binary_path)
    except (RuntimeError, FileNotFoundError):
        return None, None, None
    try:
        proc = subprocess.run([path, "--version"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
                              timeout=2.0)
    except Exception as e:
        return path, None, str(e)
    if proc.returncode == 0 and "version" in proc.stdout:
        return path, proc.stdout.strip().split()[-1], None
    return path, None, None
 
 
def check_binary_compatibility(binary_path: Optional[str] = None) -> Optional[str]:
    """
    Checks if the backend dist_m4ri binary exists and is compatible (version >= __version__).
    Returns a warning message string if missing or older, or None if compatible (silent).
    """
    path, bin_ver, error = _binary_version(binary_path)
    if path is None:
        return "Warning: backend binary 'dist_m4ri' not found (run 'make -C src' to build it)"
    if error is not None:
        return f"Warning: failed to check binary '{path}': {error}"
    if bin_ver is None:
        return (
            f"Warning: backend binary '{path}' does not support --version "
            f"(expected >= {__version__}; run 'make -C src' to rebuild)"
        )
    if _parse_version(bin_ver) < _parse_version(__version__):
        return (
            f"Warning: backend binary '{path}' is version {bin_ver} "
            f"(expected >= {__version__}; run 'make -C src' to rebuild)"
        )
    return None  # Compatible and up-to-date: silent!
 
 
def parse_dist_m4ri_output(stdout: str) -> Tuple[int, int, int]:
    """
    Parses the standard output of dist_m4ri.
    Expected format on stdout: "dmin dmax rw_steps", "dmin dmax", or a single integer.
    
    Returns:
        tuple (dmin, dmax, rw_steps)
    """
    lines = stdout.strip().split('\n')
    for line in reversed(lines):
        line = line.strip()
        if not line or line.startswith('#'):
            continue
        parts = line.split()
        if len(parts) >= 3:
            try:
                return int(parts[0]), int(parts[1]), int(parts[2])
            except ValueError:
                continue
        elif len(parts) == 2:
            try:
                return int(parts[0]), int(parts[1]), 0
            except ValueError:
                continue
        elif len(parts) == 1:
            try:
                val = int(parts[0])
                return val, val, 0
            except ValueError:
                continue
 
    raise RuntimeError(f"Could not parse dist_m4ri output: {stdout}")
 
 
class DistanceResult:
    """
    Structured result for code distance calculations containing:
    - dmin: lower bound on distance
    - dmax: upper bound on distance (minimum non-trivial codeword weight found)
    - rw_steps: cumulative number of completed random window information sets
    - cws: discovered codewords (if requested)
    """
    def __init__(
        self,
        dmin: int,
        dmax: int,
        rw_steps: int = 0,
        cws: Optional[List[List[int]]] = None,
        cws_X: Optional[List[List[int]]] = None,
        cws_Z: Optional[List[List[int]]] = None,
        dmin_X: Optional[int] = None,
        dmax_X: Optional[int] = None,
        rw_steps_X: Optional[int] = None,
        dmin_Z: Optional[int] = None,
        dmax_Z: Optional[int] = None,
        rw_steps_Z: Optional[int] = None,
    ):
        self.dmin = dmin
        self.dmax = dmax
        self.rw_steps = rw_steps
        self.cws = cws
        self.cws_X = cws_X
        self.cws_Z = cws_Z
        self.dmin_X = dmin_X
        self.dmax_X = dmax_X
        self.rw_steps_X = rw_steps_X
        self.dmin_Z = dmin_Z
        self.dmax_Z = dmax_Z
        self.rw_steps_Z = rw_steps_Z
 
    @property
    def is_exact(self) -> bool:
        return self.dmin > 0 and self.dmin == self.dmax
 
    @property
    def dist(self) -> int:
        return self.dmin if self.is_exact else (self.dmax if self.dmax > 0 else self.dmin)
 
    def __int__(self) -> int:
        return self.dist
 
    def __index__(self) -> int:
        return self.dist
 
    def __eq__(self, other: Any) -> bool:
        if isinstance(other, DistanceResult):
            return (self.dmin, self.dmax, self.rw_steps) == (other.dmin, other.dmax, other.rw_steps)
        if isinstance(other, (tuple, list)):
            return self._fields() == tuple(other)
        if isinstance(other, numbers.Integral):  # int, bool, and numpy integers
            return self.dist == other
        return False
 
    def _fields(self) -> tuple:
        """The result as a tuple (dmin, dmax, rw_steps[, cws] or [, cws_X, cws_Z])."""
        if self.cws_X is not None or self.cws_Z is not None:
            return (self.dmin, self.dmax, self.rw_steps, self.cws_X or [], self.cws_Z or [])
        if self.cws is not None:
            return (self.dmin, self.dmax, self.rw_steps, self.cws)
        return (self.dmin, self.dmax, self.rw_steps)
 
    def __iter__(self):
        return iter(self._fields())
 
    def __getitem__(self, index: int):
        return self._fields()[index]
 
    def __len__(self) -> int:  # (not len(tuple(self)): tuple() calls __len__)
        return len(self._fields())
 
    def __str__(self) -> str:
        if self.is_exact:
            return f"{self.dmin} {self.dmax} {self.rw_steps} (exact)"
        return f"{self.dmin} {self.dmax} {self.rw_steps}"
 
    def __repr__(self) -> str:
        if self.is_exact:
            return f"DistanceResult({self.dmin} {self.dmax} {self.rw_steps} (exact))"
        return f"DistanceResult(dmin={self.dmin}, dmax={self.dmax}, rw_steps={self.rw_steps})"
 
 
def check_finc_outc(finC: Optional[str], outC: Optional[str], verbose: bool = False) -> Optional[str]:
    """
    When finC and outC names are identical, an empty or non-existent file is silently ignored
    (with a warning if verbose is True).
 
    Returns:
        The effective finC filepath to use (or None if ignored).
    """
    if not finC:
        return None
    if outC and (finC == outC or os.path.abspath(finC) == os.path.abspath(outC)):
        if not os.path.exists(finC) or os.path.getsize(finC) == 0:
            if verbose:
                print(f"[dist_m4ri] Warning: finC='{finC}' (identical to outC) is empty or non-existent; "
                      f"silently ignoring input codewords.")
            return None
    return finC
 
 
# ---------------------------------------------------------------------------------------------------------------
# Expert CC options: `start` list of CC start columns, `trust_start`, and the disabled options noscan, cbeg, cend.
#
# - start=a,b,c: CC clusters are grown only from the listed columns, and they are NOT limited to larger column
#   indices (unlike cbeg/cend in the dist_m4ri binary).  The lower bound dmin (and an exact result) is valid only
#   if a code symmetry maps every codeword to one whose support contains a listed column (e.g., one column per
#   block of a quasi-cyclic code); the upper bound dmax is always valid.  Results are cached under the separate
#   key '<key>:start=a,b,c' (sorted, distinct columns).  Only dmax and the codewords are merged into the main
#   record, unless the expert option trust_start is set (then dmin and rw_steps are merged as well, and an
#   existing exact start-list record is copied to the main record even if no calculation is needed).
# - start_scan (since version 0.15.1, with start): a cluster grown from a listed column c only uses the columns > c,
#   as in the scan of all columns; valid if a code symmetry maps every codeword to one whose smallest column is
#   listed, e.g., the smallest columns of the orbits of a group of code automorphisms (start=0,l for the two blocks
#   of a two-block group-algebra code over an abelian group).  Cached under '<key>:start=a,b,c:scan'.
# - noscan, cbeg, cend: disabled in the Python interface (ignored with a warning to stderr); use the dist_m4ri
#   binary directly (noscan: CC only at w=wmax; cbeg/cend: start-column range for split multi-run use, where
#   each column is eventually listed in one of the runs).
# - irred (since version 0.14.8): the CLI ignores irred=0 with a warning (see _warn_cli_conflicts()); the binary
#   always runs with its default irred=1, so that the codewords recorded (and cached) are irreducible.
# ---------------------------------------------------------------------------------------------------------------
 
def _normalize_start_list(start: Any) -> Optional[List[int]]:
    """
    Normalizes the expert CC start-column specification `start` into a sorted list of distinct
    non-negative (0-based) column indices, or None if unset.
 
    Accepts None, an integer, a comma-separated string (e.g., "0,48"), or a sequence of integers.
    A single negative value (e.g., -1, the default of the dist_m4ri binary) means unset (all columns).
 
    Raises:
        ValueError: on malformed input or on negative entries in a list of several columns.
    """
    import operator
    if start is None:
        return None
    err_msg = f"invalid start={start!r}: expected a comma-separated list of column indices, e.g., start=0,48"
    vals: List[int] = []
    if isinstance(start, str):
        s = start.strip()
        if not s:
            return None
        try:
            vals = [int(tok) for tok in s.split(",")]
        except ValueError:
            raise ValueError(err_msg) from None
    else:
        try:
            items = list(start)
        except TypeError:
            items = [start]
        for v in items:
            if isinstance(v, (bool, str, bytes)):
                raise ValueError(err_msg)
            try:
                vals.append(operator.index(v))
            except TypeError:
                raise ValueError(err_msg) from None
    if not vals:
        return None
    if len(vals) == 1 and vals[0] < 0:
        return None
    if any(v < 0 for v in vals):
        raise ValueError(f"invalid start={start!r}: column indices must be non-negative")
    return sorted(set(vals))
 
 
class _StartList(list):
    """A normalized CC start list (sorted distinct columns, see _normalize_start_list()) with the expert flag `scan`
    (start_scan=1 of the binary: a cluster grown from a listed column c only uses the columns > c), which selects
    its own cache key (see _start_key_suffix())."""
    scan: bool = False
 
 
def _scan_start_list(start_list: Optional[List[int]], start_scan: bool) -> Optional[List[int]]:
    """The start list with the flag `scan` set if start_scan (None or the list itself otherwise)."""
    if not start_list or not start_scan:
        return start_list
    out = _StartList(start_list)
    out.scan = True
    return out
 
 
def _start_key_suffix(start_list: Optional[List[int]]) -> str:
    """Returns the cache key suffix ':start=a,b,c' for a normalized start list ('' if unset), with ':scan' for
    start_scan."""
    if not start_list:
        return ""
    return ":start=" + ",".join(str(c) for c in start_list) + (":scan" if getattr(start_list, "scan", False) else "")
 
 
def _format_start_list(start_list: List[int], max_show: int = 8) -> str:
    """Formats a start list for messages, showing at most `max_show` entries (as the dist_m4ri binary)."""
    shown = ",".join(str(c) for c in start_list[:max_show])
    return shown + (",..." if len(start_list) > max_show else "")
 
 
_report_ignored = True  # warnings on stderr for the inputs which are ignored (off: set_silent(), the CLI's --silent)
 
 
def set_silent(silent: bool = True) -> None:
    """
    Turns off (silent=True) or on again (silent=False) the warnings written to stderr for the inputs which are
    ignored (the CLI option --silent).  The warnings on the validity of a result (e.g., for ksub, ortho=0, or start)
    are always written.
    """
    global _report_ignored
    _report_ignored = not silent
 
 
def _warn_ignored(msg: str) -> None:
    """Writes the warning '# Warning: msg' on an input which is ignored to stderr, unless set_silent() is on."""
    if _report_ignored:
        sys.stderr.write(f"# Warning: {msg}\n")
 
 
# The options of the dist_m4ri binary in the compute_*() functions, with their defaults there, which
# solver="codedistance" does not use (it uses the matrices or the DEM, num_steps, seed, codedistance_method, and
# codedistance_params): see _warn_codedistance_ignored().  (start, ortho, noscan, cbeg, cend, outD, and out_reduced
# have warnings of their own, and outC and do_cws are errors.)
_CODEDISTANCE_UNUSED: Dict[str, Any] = {
    "method": 3, "threads": None, "timeout": 60.0, "d_exp": 0, "dmin": 0, "dmax": 0, "d_min": 0, "d_max": 0,
    "dstop": 0, "wmin": 1, "wmax": 0, "smax": None, "dW": -1, "maxC": 0, "finC": None, "nothrottle": False,
    "chunk_size": 0, "ksub": 0, "kwin": 0, "win_mode": 0, "win_hyb": 0, "pairs": -1, "sort_rows": None,
    "cc_prune": None, "min_hits": None, "cov_cws": 100, "refresh": None, "dist_m4ri": None, "pmin": 0.0,
    "merge": True, "drop": None, "expand": False,
}
 
 
def _warn_codedistance_ignored(values: Dict[str, Any]) -> None:
    """
    With solver="codedistance": a warning (see _warn_ignored()) on the options of the dist_m4ri binary in `values`
    (the locals() of a compute_*() function) which are not at their defaults (see _CODEDISTANCE_UNUSED).
    """
    names = [k for k, v in _CODEDISTANCE_UNUSED.items() if k in values and values[k] != v]
    if names:
        _warn_ignored(f"{', '.join(k + '=' for k in names)}: not used with solver='codedistance'; ignored")
 
 
def _warn_disabled_options(noscan: Any = 0, cbeg: Any = None, cend: Any = None) -> None:
    """
    Issues a warning to stderr for each of the expert options noscan, cbeg, and cend that is set.
    These options are disabled in the Python interface: they are accepted for backward compatibility
    but ignored, since their results are not valid distance bounds on their own.
    """
    for name, val, is_flag in (("noscan", noscan, True), ("cbeg", cbeg, False), ("cend", cend, False)):
        if val is None:
            continue
        try:
            ival = int(val)
            active = (ival != 0) if is_flag else (ival >= 0)
        except (TypeError, ValueError):
            active = True
        if active:
            _warn_ignored(f"{name}={val} is disabled in the Python interface (ignored); use the dist_m4ri binary "
                          f"directly")
 
 
def _start_warning_text(start_list: List[int]) -> str:
    """Returns the stderr warning for a CC start list (same wording as the dist_m4ri binary)."""
    if getattr(start_list, "scan", False):
        return (
            f"# WARNING: start={_format_start_list(start_list)} start_scan=1 (expert options): CC clusters are grown "
            f"only from {len(start_list)} listed column(s), each with\n"
            f"#   the larger columns only; dmin is valid only if a code symmetry maps every minimum-weight codeword\n"
            f"#   to one whose smallest column is listed\n"
        )
    return (
        f"# WARNING: start={_format_start_list(start_list)} (expert option): CC clusters are grown only from "
        f"{len(start_list)} listed column(s)\n"
        f"#   (not limited to larger column indices); dmin is valid only if a code symmetry maps every\n"
        f"#   minimum-weight codeword to one containing a listed column\n"
    )
 
 
def _ksub_warning_text(ksub: int) -> str:
    """Returns the stderr warning for the experimental RW option ksub (same wording as the dist_m4ri binary)."""
    return (
        f"# WARNING: ksub={ksub} is experimental and should not be used: a RW step reduces the span of ksub rows\n"
        f"#   of a fixed basis of ker(H), so that a few codewords are found much more often than others; with\n"
        f"#   min_hits, RW may end early, and exp(-<n>) underestimates the probability to miss a lighter codeword\n"
    )
 
 
def _warn_experimental_ksub(ksub: Any, method: int, solver: str = "dist_m4ri") -> None:
    """
    Issues the warning for the experimental RW option ksub > 0 to stderr (with or without min_hits), if RW runs
    (method=1 or 3) with the dist_m4ri binary.
    """
    try:
        ival = int(ksub or 0)
    except (TypeError, ValueError):
        return
    if ival > 0 and (int(method) & 1) and solver != "codedistance":
        sys.stderr.write(_ksub_warning_text(ival))
 
 
def _ortho_warning_text() -> str:
    """Returns the stderr warning for the expert option ortho=0 (same wording as the dist_m4ri binary)."""
    return (
        "# WARNING: ortho=0 (expert option): the rows of H and G are not checked for orthogonality\n"
        "#   (H G^T = 0); the result is valid only if they are orthogonal\n"
    )
 
 
def _warn_ortho(ortho: Any, has_g: bool, solver: str = "dist_m4ri") -> None:
    """
    Issues the warning for the expert option ortho=False to stderr: the dist_m4ri binary does not check that the rows
    of H and G are orthogonal (if has_g: a matrix G is given), or the option has no effect (without G, or with the
    codedistance solver).
    """
    if ortho:
        return
    if solver == "codedistance":
        _warn_ignored("ortho=0 is ignored with solver='codedistance'")
    elif has_g:
        sys.stderr.write(_ortho_warning_text())
    else:
        _warn_ignored("ortho=0 has no effect without G (the check H G^T = 0 needs G)")
 
 
def _check_kwargs(func: Callable[..., Any], kwargs: Dict[str, Any], aliases: Sequence[str] = ("win",)) -> None:
    """
    Raises TypeError for the keyword arguments in kwargs (the **kwargs of func) other than the accepted aliases
    (`win` for kwin), e.g., misspelled or unsupported options, with the closest parameter names as hints.
    """
    unknown = [k for k in kwargs if k not in aliases]
    if not unknown:
        return
    import difflib
    import inspect
    names = [n for n, p in inspect.signature(func).parameters.items() if p.kind is not inspect.Parameter.VAR_KEYWORD]
    names += list(aliases)
    items = []
    for k in unknown:
        close = difflib.get_close_matches(k, names, n=1)
        items.append(f"'{k}'" + (f" (did you mean '{close[0]}'?)" if close else ""))
    if len(items) == 1:
        raise TypeError(f"{func.__name__}() got an unexpected keyword argument {items[0]}")
    raise TypeError(f"{func.__name__}() got unexpected keyword arguments {', '.join(items)}")
 
 
def _prepare_start_option(
    start: Any,
    trust_start: bool = False,
    noscan: Any = 0,
    cbeg: Any = None,
    cend: Any = None,
    solver: str = "dist_m4ri",
    start_scan: bool = False
) -> Optional[List[int]]:
    """
    Validates the expert CC options of a compute_*_distance() call and issues the warnings to stderr.
 
    Returns:
        The normalized start list (with the flag `scan` for start_scan, see _StartList), or None if unset (or not
        applicable to the selected solver).
    """
    _warn_disabled_options(noscan, cbeg, cend)
    start_list = _normalize_start_list(start)
    if start_list is None:
        if trust_start:
            _warn_ignored("trust_start=1 has no effect without a start list")
        if start_scan:
            _warn_ignored("start_scan=1 has no effect without a start list")
        return None
    if solver == "codedistance":
        _warn_ignored(f"start={_format_start_list(start_list)} is ignored with solver='codedistance'")
        return None
    start_list = _scan_start_list(start_list, start_scan)
    msg = _start_warning_text(start_list)
    if _use_distance_cache and trust_start:
        msg += "#   trust_start=1: start-list results are accepted as valid and copied to the main cache record\n"
    elif _use_distance_cache:
        msg += (
            "#   results are cached under a separate ':start=...' key; only dmax and codewords update the\n"
            "#   main cache record (use trust_start=1 to also accept dmin)\n"
        )
    sys.stderr.write(msg)
    return start_list
 
 
def _seed_bounds_from_entry(eff_dmin: int, eff_dmax: int, entry: Optional[Dict[str, Any]]) -> Tuple[int, int]:
    """
    Tightens the bounds (eff_dmin, eff_dmax) with those stored in a cache entry (a CSS code is cached as the
    records of its two sectors, see _matrix_cache_key()).
    """
    if not entry:
        return eff_dmin, eff_dmax
    c_dmin = entry.get("dmin", 0) or 0
    c_dmax = entry.get("dmax", 0) or 0
    if c_dmax > 0:
        eff_dmax = min(eff_dmax, c_dmax) if eff_dmax > 0 else c_dmax
    if c_dmin > 1:
        eff_dmin = max(eff_dmin, c_dmin) if eff_dmin > 1 else c_dmin
    return eff_dmin, eff_dmax
 
 
def _union_cws(base: Optional[List[List[int]]], extra: Optional[List[List[int]]]) -> List[List[int]]:
    """Returns the union of two codeword lists (duplicates removed, sorted by weight)."""
    combined = [list(cw) for cw in (base or [])]
    seen = {tuple(cw) for cw in combined}
    for cw in (extra or []):
        t = tuple(cw)
        if t not in seen:
            combined.append(list(cw))
            seen.add(t)
    combined.sort(key=len)
    return combined
 
 
def _dist_from_bounds(dmin: int, dmax: int) -> int:
    """The distance reported for the bounds [dmin, dmax]: dmin if exact or without an upper bound, otherwise dmax."""
    return dmin if (dmin == dmax or dmax == 0) else dmax
 
 
def _single_entry_is_exact(entry: Dict[str, Any], need_cws: bool = False, dstop: int = 0) -> bool:
    """
    Cache hit test for a classical / quantum / DEM entry: the exact distance, or with the stop target dstop > 0 a
    lower bound dmin >= dstop (and codewords if needed).
    """
    c_dmin = entry.get("dmin", 0) or 0
    if not ((c_dmin > 0 and c_dmin == entry.get("dmax")) or (dstop > 0 and c_dmin >= dstop)):
        return False
    return (not need_cws) or bool(entry.get("cws"))
 
 
def _resolve_cert_engine(solver: str = "dist_m4ri", engine: Optional[str] = None) -> str:
    """
    Resolves the qec_cert delegation mode ('off', 'auto', or 'cert') from `solver` and `engine`.
    Default ('dist_m4ri', engine=None) returns 'off'.
    """
    if engine is not None:
        e = str(engine).strip().lower()
        if e in ("", "dist_m4ri", "m4ri", "native", "off", "0", "false", "none"):
            return "off"
        if e == "auto":
            return "auto"
        if e in ("cert", "qec_cert", "qec-cert"):
            return "cert"
        if e == "codedistance":
            return "off"
        raise ValueError(f"invalid engine={engine!r}: expected 'dist_m4ri', 'auto', or 'cert'")
    s = str(solver or "dist_m4ri").strip().lower()
    if s in ("dist_m4ri", "codedistance"):
        return "off"
    if s == "auto":
        return "auto"
    if s in ("cert", "qec_cert", "qec-cert"):
        return "cert"
    raise ValueError(f"invalid solver={solver!r}: expected 'dist_m4ri', 'codedistance', 'auto', or 'cert'")
 
 
def _can_delegate_to_cert(
    mode: str,
    *,
    method: int = 3,
    do_cws: bool = False,
    outC: Optional[str] = None,
    finC: Optional[str] = None,
    smax: Optional[int] = None,
    dW: int = -1,
    maxC: int = 0,
    start_list: Optional[List[int]] = None,
    outD: Optional[Any] = None,
    out_reduced: Optional[Any] = None,
    pmin: float = 0.0,
) -> bool:
    """
    Whether a distance calculation should be delegated to `qec_cert`.
    In 'auto' mode, delegates only when safe (no codeword enumeration, finC, smax, start list, outD, out_reduced,
    pmin > 0, or single-sided method 1/2, and `qec_cert` is importable).
    """
    if mode == "off":
        return False
    if do_cws or outC:
        if mode == "cert":
            raise ValueError("Codeword extraction is not supported with engine='cert'; use solver='dist_m4ri'.")
        return False
    if mode == "auto":
        if (
            method != 3 or finC or (smax is not None and smax > 0) or dW >= 0 or maxC > 0
            or start_list is not None or outD or out_reduced or pmin > 0.0
        ):
            return False
        return _has_qec_cert()
    _get_qec_cert()
    if outD or out_reduced:
        _warn_ignored("outD and out_reduced are only used with solver='dist_m4ri'; ignored")
    return True
 
 
def _cert_to_csr(M: Any, qec_io: Any) -> Any:
    """Converts a matrix (file path, numpy array, or scipy sparse matrix) to a binary CSR matrix for qec_cert."""
    if M is None:
        return None
    if isinstance(M, (str, Path)):
        return qec_io.read_mtx(str(M))
    return qec_io.binary_csr(M)
 
 
def _cert_is_conditional(cert: Any) -> bool:
    """Whether a qec_cert Certificate (or dict) has a conditional lower bound (e.g., unverified symmetry)."""
    get = cert.get if isinstance(cert, dict) else lambda k, d=None: getattr(cert, k, d)
    if get("status") == "conditional" or bool(get("lb_conditional", False)):
        return True
    for s in get("stages", ()) or ():
        if isinstance(s, dict) and s.get("lb_conditional"):
            return True
    for r in get("reductions", ()) or ():
        if isinstance(r, dict) and (r.get("conditional") or (r.get("params") or {}).get("lb_conditional")):
            return True
    return False
 
 
def _cert_extract_bounds(cert: Any, certified_dmin: int = 1) -> Tuple[int, int]:
    """
    Extracts unconditional (dmin, dmax) from a qec_cert Certificate for dist_m4ri reporting and caching:
    - An exact result (dmin = dmax = d) only if status == 'exact', witness_verified is True, and not conditional.
    - For bounds, an upper bound dmax only if witness_verified is True, and a lower bound dmin only when
      status in ('exact', 'bounds', 'timeout') and not lb_conditional.
    """
    get = cert.get if isinstance(cert, dict) else lambda k, d=None: getattr(cert, k, d)
    status = str(get("status", "") or "")
    wit_ver = get("witness_verified") is True
    is_cond = _cert_is_conditional(cert)
    raw_lb = int(get("lower_bound") or 0)
    raw_ub = int(get("upper_bound") or 0)
    if is_cond and certified_dmin > 1 and _cert_wmin_discharged(cert, certified_dmin):
        is_cond = False
    if status == "exact" and wit_ver and not is_cond and raw_ub > 0 and raw_lb == raw_ub:
        return raw_ub, raw_ub
    c_ub = raw_ub if (wit_ver and raw_ub > 0) else 0
    c_lb = raw_lb if (status in ("exact", "bounds", "timeout") and not is_cond and raw_lb > 1) else 0
    if c_ub > 0 and c_lb > c_ub:
        c_lb = c_ub
    return c_lb, c_ub
 
 
def _cert_wmin_discharged(cert: Any, certified_dmin: int) -> bool:
    """
    True iff the certificate's conditionality is caused solely by an assumed lower bound
    lb_assumed_wmin <= certified_dmin (already certified in _distance_cache), with no trust
    flags, no precondition violation, and no other conditional stage or reduction.
    """
    if certified_dmin <= 1:
        return False
    get = cert.get if isinstance(cert, dict) else lambda k, d=None: getattr(cert, k, d)
    if get("status") == "conditional" or bool(get("precondition_violated", False)):
        return False
    if bool(get("trust_sym", False)) or bool(get("trust_quot", False)):
        return False
    inst = get("instance", None)
    inst_d = inst if isinstance(inst, dict) else {}
    if (
        bool(inst_d.get("trust_sym", False))
        or bool(inst_d.get("trust_quot", False))
        or bool(inst_d.get("precondition_violated", False))
    ):
        return False
    assumed_wmin = int(get("lb_assumed_wmin", None) or inst_d.get("lb_assumed_wmin", 0) or 0)
    if not (1 < assumed_wmin <= certified_dmin):
        return False
    sectors = inst_d.get("sectors")
    if isinstance(sectors, dict):
        for sec in sectors.values():
            if _cert_is_conditional(sec) and not _cert_wmin_discharged(sec, certified_dmin):
                return False
    stages = get("stages", ()) or ()
    pinned_ok = any(
        isinstance(s, dict) and s.get("name") == "polymer_pinning" and s.get("shift_verified") is True
        for s in stages
    )
    for s in stages:
        if isinstance(s, dict) and s.get("lb_conditional"):
            sname = str(s.get("name", "") or "")
            if bool(s.get("trust_sym", False)) or bool(s.get("trust_quot", False)):
                return False
            if sname == "search":
                sym_ok = bool(s.get("sym_verified", True)) or (
                    s.get("sym_kind") == "pinned" and pinned_ok
                )
                if not sym_ok:
                    return False
            elif sname != "p1_projection_lb" and not sname.startswith("fold_mod_"):
                return False
    reductions = get("reductions", ()) or ()
    pinned_red_ok = pinned_ok or any(
        isinstance(r, dict)
        and r.get("name") == "polymer_pinning"
        and (r.get("params") or {}).get("shift_verified") is True
        for r in reductions
    )
    for r in reductions:
        if not isinstance(r, dict):
            continue
        rp = r.get("params") or {}
        if r.get("conditional"):
            return False
        if rp.get("lb_conditional"):
            rname = str(r.get("name", "") or "")
            if rname == "cc_mitm_search":
                sym_ok = bool(rp.get("sym_verified", True)) or (
                    rp.get("sym_kind") == "pinned" and pinned_red_ok
                )
                wmin_r = int(rp.get("wmin", 0) or 0)
                if not sym_ok or (wmin_r > certified_dmin):
                    return False
            elif rname not in ("p1_projection_lb", "capped_spacetime_folding"):
                return False
    return True
 
 
def _cert_code_distance(
    key_fn: Callable[[], str],
    run_cert_fn: Callable[[int, int], Any],
    *,
    label: str = "code",
    dmin: int = 0,
    dmax: int = 0,
    dstop: int = 0,
    wmax: int = 0,
    eff_cache_file: Optional[str] = None,
    debug: int = 0,
    verbose: bool = False,
) -> Dict[str, Any]:
    """
    Runs a qec_cert certification callback with dist_m4ri cache lookup and safe cache write-back.
    """
    global _distance_cache
    code_key: Optional[str] = None
    entry: Optional[Dict[str, Any]] = None
    eff_dmin, eff_dmax = dmin, dmax
    if _use_distance_cache:
        if eff_cache_file:
            load_distance_cache(eff_cache_file)
        code_key = key_fn()
        entry = _distance_cache.get(code_key)
        if entry is not None and _single_entry_is_exact(entry, need_cws=False, dstop=dstop):
            if verbose or (debug & PY_DBG_CACHE):
                c_dmin = entry.get("dmin", 0) or 0
                found = ("exact distance" if c_dmin == entry.get("dmax") else f"dmin={c_dmin} >= dstop={dstop}")
                print(f"[dist_m4ri] Cache hit for {label} distance ({found} known)!")
            return {
                "dist": entry["dist"], "dmin": entry["dmin"], "dmax": entry["dmax"],
                "rw_steps": entry.get("rw_steps", 0), "d_info": list(entry["d_info"]),
                "cws": list(entry.get("cws", [])), "cached": True,
            }
        eff_dmin, eff_dmax = _seed_bounds_from_entry(eff_dmin, eff_dmax, entry)
    w_lo = max(1, eff_dmin)
    w_hi = wmax if wmax > 0 else 40
    if eff_dmax > 0:
        w_hi = min(w_hi, max(1, eff_dmax - 1)) if wmax > 0 else max(1, eff_dmax - 1)
    if dstop > 0:
        w_hi = min(w_hi, max(1, dstop - 1)) if (wmax > 0 or eff_dmax > 0) else max(1, dstop - 1)
    cert = run_cert_fn(w_lo, max(w_lo, w_hi))
    c_lb, c_ub = _cert_extract_bounds(cert, (entry.get("dmin", 0) or 0) if entry else 0)
    p_dmin = (entry.get("dmin", 0) or 0) if entry else 0
    p_dmax = (entry.get("dmax", 0) or 0) if entry else 0
    p_rw = (entry.get("rw_steps", 0) or 0) if entry else 0
    p_cws = list(entry.get("cws", [])) if entry else []
    cache_dmin = max(p_dmin, c_lb)
    cache_dmax = min(p_dmax, c_ub) if (p_dmax > 0 and c_ub > 0) else max(p_dmax, c_ub)
    if cache_dmax > 0 and cache_dmin > cache_dmax:
        cache_dmin = cache_dmax
    if _use_distance_cache and code_key is not None and (c_lb > 1 or c_ub > 0):
        record = _sector_record(cache_dmin, cache_dmax, p_rw, p_cws)
        if entry is not None and "dmin_model" in entry:
            record["dmin_model"] = entry["dmin_model"]
        if record != entry:
            _distance_cache[code_key] = record
            if eff_cache_file:
                save_distance_cache(eff_cache_file)
    dmin_res = max(eff_dmin, cache_dmin)
    pos_ub = [x for x in (eff_dmax, cache_dmax) if x > 0]
    dmax_res = min(pos_ub) if pos_ub else 0
    if dmax_res > 0 and dmin_res > dmax_res:
        dmin_res = dmax_res
    dist = _dist_from_bounds(dmin_res, dmax_res)
    return {
        "dist": dist, "dmin": dmin_res, "dmax": dmax_res, "rw_steps": p_rw,
        "d_info": format_bounds_list(dmin_res, dmax_res, p_rw), "cws": p_cws, "cached": False,
    }
 
 
def _merge_start_into_plain(
    plain_key: str,
    src: Dict[str, Any],
    trust: bool = False,
    rw_delta: Optional[Dict[str, int]] = None
) -> bool:
    """
    Merges the start-list cache record `src` (key plain_key + ':start=...') into the main record `plain_key`.
 
    The upper bound dmax (minimum of the positive values) and the codewords (union) are always valid and
    are always merged.  Only with `trust` (expert option trust_start) the lower bound dmin is merged as well
    (maximum, capped at dmax), and rw_steps are either incremented by the steps of the run, `rw_delta`
    (after a calculation), or set to the maximum of the two records (copy of a cached record, rw_delta=None).
    (A CSS code is cached as the records of its two sectors, see _matrix_cache_key().)
 
    Args:
        plain_key: Main cache key.
        src: Start-list cache record.
        trust: Accept the start-list lower bound as valid.
        rw_delta: RW steps of the run, {'': steps}.
 
    Returns:
        True if the main record was created or modified.
    """
    global _distance_cache
    prev = _distance_cache.get(plain_key)
    new: Dict[str, Any] = dict(prev) if prev else {}
    s_dmin = src.get("dmin", 0) or 0
    s_dmax = src.get("dmax", 0) or 0
    p_dmin = new.get("dmin", 0) or 0
    p_dmax = new.get("dmax", 0) or 0
    p_rw = new.get("rw_steps", 0) or 0
    dmax = min(p_dmax, s_dmax) if (p_dmax > 0 and s_dmax > 0) else (p_dmax if p_dmax > 0 else s_dmax)
    dmin, rw = p_dmin, p_rw
    if trust:
        dmin = max(p_dmin, s_dmin)
        if rw_delta is not None:
            rw = p_rw + (rw_delta.get("", 0) or 0)
        else:
            rw = max(p_rw, src.get("rw_steps", 0) or 0)
    if dmax > 0 and dmin > dmax:
        dmin = dmax
    s_cws = src.get("cws", []) or []
    if not prev and not (trust or s_dmax > 0 or s_cws):
        return False
    new["cws"] = _union_cws(new.get("cws", []), s_cws)
    new["dist"] = _dist_from_bounds(dmin, dmax)
    new["dmin"], new["dmax"], new["rw_steps"] = dmin, dmax, rw
    new["d_info"] = format_bounds_list(dmin, dmax, rw)
    _distance_cache[plain_key] = new
    return True
 
 
def _resolve_start_cache(
    plain_key: str,
    start_list: Optional[List[int]],
    is_hit: Callable[[Dict[str, Any]], bool],
    trust_start: bool,
    merge_copy: Callable[[Dict[str, Any]], bool],
    eff_cache_file: Optional[str],
    verbose: bool = False
) -> Tuple[str, Optional[Dict[str, Any]], Optional[Dict[str, Any]]]:
    """
    Resolves the cache record of a run with an optional expert CC start list.
 
    Without a start list, or if the main record already holds the requested exact result, the main record
    is used.  Otherwise the separate start-list record (key plain_key + ':start=a,b,c') is used; with
    trust_start, an existing exact start-list record is copied to the main record (via `merge_copy`), and
    the cache file is saved, even though no calculation is needed.
 
    Returns:
        (code_key, cached_entry, plain_entry): the key and the existing record (or None) for the results of
        this run, and the main record (or None) used to seed the bounds of a start-list run.
    """
    plain_entry = _distance_cache.get(plain_key)
    if not start_list:
        return plain_key, plain_entry, None
    if plain_entry is not None and is_hit(plain_entry):
        if verbose:
            print(f"[dist_m4ri] Start list not needed: the main record '{plain_key}' has the exact distance")
        return plain_key, plain_entry, None
    code_key = plain_key + _start_key_suffix(start_list)
    cached_entry = _distance_cache.get(code_key)
    if trust_start and cached_entry is not None and is_hit(cached_entry):
        if merge_copy(cached_entry) and eff_cache_file:
            save_distance_cache(eff_cache_file)
        if verbose:
            print(f"[dist_m4ri] trust_start: copied the exact start-list record to the main record '{plain_key}'")
    return code_key, cached_entry, plain_entry
 
 
def run_dist_m4ri(
    dist_m4ri_path: Optional[str] = None,
    method: int = 3,
    finH: Optional[str] = None,
    finG: Optional[str] = None,
    finL: Optional[str] = None,
    fin: Optional[str] = None,
    finC: Optional[str] = None,
    fdem: Optional[str] = None,
    dmin: int = 0,
    dmax: int = 0,
    wmax: int = 0,
    wmin: int = 1,
    dexp: int = 0,
    dest: int = 0,
    dstop: int = 0,
    steps: Optional[int] = None,
    threads: Optional[int] = None,
    timeout: float = 60.0,
    smax: Optional[int] = None,
    start: Optional[Union[int, str, Sequence[int]]] = None,
    cbeg: Optional[int] = None,
    cend: Optional[int] = None,
    css: Optional[int] = None,
    noscan: int = 0,
    classical: int = -1,
    dW: int = -1,
    maxC: int = 0,
    pmin: float = 0.0,
    merge: bool = True,
    drop: Optional[str] = None,
    outD: Optional[str] = None,
    sort_rows: Optional[bool] = None,
    cc_prune: Optional[int] = None,
    outC: Optional[str] = None,
    seed: int = 0,
    debug: int = 0,
    nothrottle: bool = False,
    chunk_size: int = 0,
    ksub: int = 0,
    kwin: int = 0,
    win_mode: int = 0,
    win_hyb: int = 0,
    pairs: int = -1,
    min_hits: Optional[int] = None,
    cov_cws: int = 100,
    refresh: Optional[int] = None,
    verbose: bool = False,
    stop_event: Optional[threading.Event] = None,
    warn_start: bool = True,
    warn_ksub: bool = True,
    start_scan: bool = False,
    ortho: bool = True,
    warn_ortho: bool = True
) -> Tuple[int, int, int]:
    """
    Low-level invocation of the multithreaded dist_m4ri binary.
 
    DEM input:
        merge: If True (default), the binary merges the equal columns of the DEM fdem (error mechanisms with the
            same detectors and observables).  Exact: dropping two equal columns of a codeword gives a lighter one,
            so the distance does not change.  Column indices (finC, outC, start) are those of the DEM; the codewords
            found use the first one of each set of equal columns.  merge=False passes merge=0 (all columns are
            kept, e.g., to enumerate the codewords with each of them).  Ignored without fdem.
        drop: The detectors of the DEM fdem to drop if this is verified to be exact, passed as drop=...: None (the
            binary's default, drop=auto: a search for the largest such set in the DEM), "auto" or "1" (the same), "0"
            (keep all detectors), or a file with the detectors to drop (0-based; otherwise, the binary uses the full DEM
            and prints a note, see _parse_stderr_stats()).  Ignored without fdem.
        outD: File to which the binary writes the detectors dropped from the DEM fdem (0-based; only the comment line
            '# N of M detectors dropped ...' if none, see read_drop_file()).  Ignored without fdem.
 
    Orthogonality check:
        ortho: If True (default), the binary checks that the rows of H and G (finG, or fin without finL) are
            orthogonal (H G^T = 0) and stops with an error otherwise.  False (expert option, since version 0.15.2)
            passes ortho=0: the check is skipped, e.g., to screen many codes which are orthogonal by construction; the
            result is then valid only if H G^T = 0.  No effect without G.  The cache key does not depend on it.
        warn_ortho: If True (default), issue the warning for ortho=False to stderr (see _warn_ortho()).
 
    Row order:
        sort_rows: Passed as sort_rows=1 (True) or sort_rows=0 (False); None (default): the binary's default, i.e.,
            1 for matrices and 0 for a DEM.  With sort_rows=1, the binary sorts the rows of H by increasing weight
            (stable).  With cc_prune=0, this reduces the CC work for matrices with very different row weights (e.g.,
            1.7-4x with the hook columns of an extended CSS distance), while the detectors of a DEM are in time
            order, which is better for CC (use sort_rows=False also for matrices exported from a DEM); with the
            default cc_prune=1, the order of the rows only breaks ties.  The distance and RW do not depend on the
            order of the rows; CC enumerates the same codewords, possibly in another order (with cc_prune=0, also with
            other hit counts).
 
    CC search:
        cc_prune: Passed as cc_prune=N if not None (0, 1, or 2; None, the default: the binary's default 1).  The CC
            search with smax=0: 0, the walk of the versions before 0.15.0 (a cluster is extended by the columns of the
            first unsatisfied row of its syndrome); 1, the branch and bound (the unsatisfied row with the fewest
            available columns, the columns of the earlier branches forbidden in the later ones, so that each codeword
            is found once, and pruning by lower bounds on the number of columns needed: an unsatisfied row without
            available columns, a packing of unsatisfied rows with disjoint sets of available columns); 2, also the
            coverage and fractional cover bounds.  The same codewords and distances (doc/cc_completeness.tex); with
            the expert start list (and start_scan=False), cc_prune=1 and 2 forbid the columns listed before the start
            column.  The cache key does not depend on it.
 
    RW windows:
        kwin / win_mode: A window of kwin columns in every RW step (win_mode=0: a Tanner graph ball, 1: an index
            window).  kwin=0 (default): the automatic hybrid for n >= 500, an index window of win_hyb columns in every
            other step and uniform random permutations in the others.  kwin=-1 (any negative value): no windows,
            uniform random permutations in every step.
        win_hyb: Window size of the hybrid RW steps, passed as win_hyb=N if nonzero; 0 (default): 256 columns for a
            DEM, 512 for matrices (at most 3n/4).  The windows of 192-256 columns find the minimum-weight codewords of
            circuit DEMs 2-10 times faster than 512, and windows of one round of columns are much slower.  With
            debug & 1 (or verbose=True), the binary prints the rounds of a DEM (estimated from the time translation of
            its errors: D detectors and L columns per round, also in _last_run_stats["rounds"]) and the codewords found
            by the uniform and by the window steps (see _parse_stderr_stats()).
 
    RW pairs:
        pairs: The RW pairs of non-pivot columns (p=2, as in Lee-Brickell and Stern), passed as pairs=N if not -1: a
            RW step also finds the codewords with two non-pivot columns, checking only the pairs which agree on N
            random pivot rows (0: off).  -1 (default): auto, about one non-pivot column per bucket, with fewer rows
            while a codeword of the weight of the upper bound would be kept with probability below 0.8, but enough
            rows to keep the pairs of a step within about the work of its elimination (e.g., at least 6 for large
            circuit DEMs while the upper bound is far above the distance).  The pairs find the minimum-weight
            codewords of circuit DEMs 7-26 times faster (per wall time) and lighter codewords of codes with a large
            distance.  With debug & 1, the binary prints the pairs checked per step and the codewords found by pairs
            and by single columns (also in _last_run_stats).  The pairs of disjoint codewords are skipped (their sum
            is reducible: the binary records only irreducible codewords, its default irred=1).
 
    RW stopping criterion:
        min_hits: Passed as min_hits=N if not None and >= 0 (None, the default, or a negative value: the binary's
            default 5): RW ends once the average number of hits <n> per codeword reaches N, both for the codewords
            of the minimum weight found and for a representative set of cov_cws lowest-weight codewords (the hits of
            all RW steps, with or without windows, and those of CC and finC count).  0: off; then, unless the
            codewords are collected (outC or maxC), RW records only the codewords lighter than the upper bound, so
            that the repeated hits are not counted.
        cov_cws: Size of the representative set of lowest-weight codewords for min_hits, passed as cov_cws=N if not
            100 (the default, as in the binary; 0: only the minimum weight).
 
    Stop target:
        dstop: The run (method=2 or 3) ends once CC has certified dmin >= dstop, i.e., that there is no codeword of
            weight < dstop, unless a lighter codeword is found (default: 0 = off).  Unlike dmax, dstop is not an
            upper bound and is not reported as dmax: the result is (dmin, w, rw_steps), where w is the weight of the
            lightest codeword found (0: none).
 
    Expert CC options:
        start: List of CC start columns (int, comma-separated string "a,b,c", or sequence of ints;
            None or a single negative value: all columns), passed as start=a,b,c (sorted, distinct).
            CC clusters are grown only from the listed columns, and they are not limited to larger
            column indices.  WARNING: the returned dmin (and an exact result) is valid only if a code
            symmetry maps every minimum-weight codeword to one containing a listed column (e.g., one
            column per block of a quasi-cyclic code); dmax is always valid.
        start_scan: With start (expert option, since version 0.15.1): passed as start_scan=1, so that a cluster
            grown from a listed column c only uses the columns > c, as in the scan of all columns (not with fdem).
            WARNING: dmin is then valid only if a code symmetry maps every minimum-weight codeword to one whose
            smallest column is listed, e.g., if the listed columns are the smallest columns of the orbits of a
            group of code automorphisms, one per orbit (start=[0, l] for the two blocks of a two-block
            group-algebra code of length 2l over an abelian group).  The later start columns then need much less
            work, the least if each orbit is a range of consecutive columns.
        warn_start: If True (default), issue the start-list warning to stderr.
        noscan / cbeg / cend: Disabled in the Python interface: accepted for backward compatibility,
            but ignored with a warning to stderr (use the dist_m4ri binary directly).
 
    Experimental RW options:
        ksub: Experimental, should not be used: subspace dimension sampled from ker(H) in RW (0: full-matrix RW).
            A RW step reduces the span of ksub rows of a fixed basis of ker(H), so that a few codewords are found
            much more often than others (min_hits may end RW early).
        refresh: RW steps between the basis refreshes of the experimental ksub RW (passed if not None; None, the
            default: the binary's 5000 with ksub > 0; 0: no refresh).
        warn_ksub: If True (default), issue the warning for ksub > 0 to stderr (with method=1 or 3).
 
    Debug output:
        debug: Debug bitmap; the bits in BIN_DBG_MASK are passed to the binary (its diagnostic output on stderr
            is printed), and PY_DBG_COMMANDS echoes the command line and the run time.  verbose=True implies
            the bits VERBOSE_DEBUG.
 
    Cancellation:
        stop_event: Optional threading.Event; once it is set, the binary is terminated and RuntimeError is raised
            (the binary is also terminated on any other exception, e.g., KeyboardInterrupt).
 
    Returns:
        tuple (dmin, dmax, rw_steps)
    """
    global _last_run_stats
    exec_path = find_dist_m4ri_binary(dist_m4ri_path)
 
    start_list = _normalize_start_list(start)
    _warn_disabled_options(noscan, cbeg, cend)
    if start_scan and not start_list:
        _warn_ignored("start_scan=1 has no effect without a start list")
    if start_scan and start_list and fdem:
        raise ValueError("start_scan=1 is not available with fdem (the equal columns of a DEM are merged)")
    start_list = _scan_start_list(start_list, start_scan)
    if start_list and warn_start:
        sys.stderr.write(_start_warning_text(start_list))
    if warn_ksub:
        _warn_experimental_ksub(ksub, method)
    has_g = not fdem and bool(finG or (fin and not finL))  # (fin=PREFIX: finG=PREFIX + 'Z.mtx' unless finL)
    if warn_ortho:
        _warn_ortho(ortho, has_g)
 
    finC = check_finc_outc(finC, outC, verbose=False)
 
    if cc_prune is not None and cc_prune not in (0, 1, 2):
        raise ValueError(f"invalid cc_prune={cc_prune!r}: cc_prune should be 0, 1, or 2")
 
    if method == 2 and wmax <= 0:
        if dmax > 0:
            wmax = dmax
        elif timeout <= 0.0 and dstop <= 0:
            raise ValueError(
                "either parameter wmax>0, dmax>0, dstop>0, or timeout>0 should be specified for CC method=2."
            )
 
    eff_debug = (debug | VERBOSE_DEBUG) if verbose else debug
    bin_debug = eff_debug & BIN_DBG_MASK  # the higher bits are used by the Python wrapper only
    cmd = [exec_path, f"debug={bin_debug}", f"method={method}"]
 
    if finH: cmd.append(f"finH={finH}")
    if finG: cmd.append(f"finG={finG}")
    if finL: cmd.append(f"finL={finL}")
    if fin: cmd.append(f"fin={fin}")
    if has_g and not ortho: cmd.append("ortho=0")
    if finC: cmd.append(f"finC={finC}")
    if fdem: cmd.append(f"fdem={fdem}")
    if dmin > 0: cmd.append(f"dmin={dmin}")
    if dmax > 0: cmd.append(f"dmax={dmax}")
    if dstop > 0: cmd.append(f"dstop={dstop}")
    if wmax > 0: cmd.append(f"wmax={wmax}")
    if wmin is not None and wmin != 1: cmd.append(f"wmin={wmin}")
    if dexp > 0: cmd.append(f"dexp={dexp}")
    elif dest > 0: cmd.append(f"dest={dest}")
    if steps is not None and steps >= 0: cmd.append(f"steps={steps}")
    if threads is not None and threads > 0: cmd.append(f"threads={threads}")
    if timeout is not None and timeout >= 0: cmd.append(f"timeout={timeout}")
    if smax is not None: cmd.append(f"smax={smax}")
    if start_list: cmd.append("start=" + ",".join(str(c) for c in start_list))
    if start_list and start_scan: cmd.append("start_scan=1")
    if css is not None: cmd.append(f"css={css}")
    if classical >= 0: cmd.append(f"classical={classical}")
    if dW >= 0: cmd.append(f"dW={dW}")
    if maxC > 0: cmd.append(f"maxC={maxC}")
    if pmin > 0.0: cmd.append(f"pmin={pmin}")
    if fdem and not merge: cmd.append("merge=0")
    if fdem and drop: cmd.append(f"drop={drop}")
    if fdem and outD: cmd.append(f"outD={outD}")
    if sort_rows is not None: cmd.append(f"sort_rows={1 if sort_rows else 0}")
    if cc_prune is not None: cmd.append(f"cc_prune={int(cc_prune)}")
    if outC: cmd.append(f"outC={outC}")
    if seed != 0: cmd.append(f"seed={seed}")
    if nothrottle: cmd.append("nothrottle=1")
    if chunk_size > 0: cmd.append(f"chunk_size={chunk_size}")
    if ksub > 0: cmd.append(f"ksub={ksub}")
    if kwin != 0: cmd.append(f"kwin={kwin}")  # (kwin < 0: no windows)
    if win_mode != 0: cmd.append(f"win_mode={win_mode}")
    if win_hyb != 0: cmd.append(f"win_hyb={win_hyb}")
    if pairs != -1: cmd.append(f"pairs={pairs}")
    if min_hits is not None and min_hits >= 0: cmd.append(f"min_hits={min_hits}")
    if cov_cws != 100: cmd.append(f"cov_cws={cov_cws}")
    if refresh is not None: cmd.append(f"refresh={refresh}")
 
    if eff_debug & PY_DBG_COMMANDS:
        print(f"[dist_m4ri] Running: {' '.join(cmd)}")
 
    t_start = time.time()
    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
    try:
        if stop_event is None:
            stdout, stderr = proc.communicate()
        else:
            while True:  # communicate() with a timeout keeps draining the pipes (no deadlock on a full pipe)
                try:
                    stdout, stderr = proc.communicate(timeout=0.05)
                    break
                except subprocess.TimeoutExpired:
                    if stop_event.is_set():
                        raise RuntimeError("dist_m4ri execution cancelled by stop_event")
    except BaseException:  # cancelled, KeyboardInterrupt, ...: do not leave the child process running
        try:
            proc.terminate()
            proc.communicate(timeout=1.0)
        except Exception:
            try:
                proc.kill()
                proc.wait()
            except Exception:
                pass
        raise
 
    if eff_debug & PY_DBG_COMMANDS:
        print(f"[dist_m4ri] Finished in {time.time() - t_start:.3f} s (exit code {proc.returncode})")
 
    if proc.returncode != 0:
        raise RuntimeError(f"dist_m4ri failed with exit code {proc.returncode}:\n{stderr}")
 
    _last_run_stats = _parse_stderr_stats(stderr)
    if (verbose or bin_debug > 0) and stderr:
        print(stderr.rstrip())
 
    return parse_dist_m4ri_output(stdout)
 
 
_MTX_PY_MAX_NNZ = 1 << 16  # temporary MatrixMarket files with up to this many entries are formatted in Python
 
 
def _gf2_entries(matrix: Any) -> Tuple[int, int, Any, Any]:
    """
    The shape (m, n) and the nonzero entries (0-based row and column index arrays, in row-major order) of a binary
    matrix given as a numpy array (or an array-like, e.g., a list of lists) or a scipy sparse matrix (or array): an
    entry is nonzero iff its value is odd (floats are truncated to integers, and the duplicate entries of a sparse
    matrix are summed first), as the dist_m4ri binary reads the integer entries of a MatrixMarket file.
    """
    import numpy as np
 
    def odd(v: Any) -> Any:  # the mask of the odd entries
        if v.dtype == np.bool_:
            return v
        if not np.issubdtype(v.dtype, np.integer):
            v = v.astype(np.int64)
        v = v & 1
        return v.view(np.bool_) if v.itemsize == 1 else v != 0
 
    if hasattr(matrix, "tocsr"):  # a scipy sparse matrix or array
        csr = matrix.tocsr()
        if not csr.has_canonical_format:  # duplicates summed and columns sorted (not in the caller's matrix)
            csr = csr.copy() if csr is matrix else csr
            csr.sum_duplicates()
        m, n = csr.shape
        keep = odd(csr.data)
        rows = np.repeat(np.arange(m, dtype=np.int64), np.diff(csr.indptr))[keep]
        return m, n, rows, csr.indices[keep]
    A = np.asarray(matrix)
    if A.ndim != 2:
        raise ValueError(f"a matrix should have two dimensions, got the shape {A.shape}")
    m, n = A.shape
    if m == 0 or n == 0:
        empty = np.zeros(0, dtype=np.int64)
        return m, n, empty, empty
    rows, cols = np.divmod(np.flatnonzero(odd(A)), n)  # (flatnonzero of a bool array is fast, unlike nonzero)
    return m, n, rows, cols
 
 
def _write_mtx_gf2(path: str, matrix: Any) -> None:
    """
    Writes a binary matrix (numpy array, array-like, or scipy sparse matrix; see _gf2_entries()) to the file `path` in
    the MatrixMarket coordinate pattern format (the 1-based indices of the nonzero entries, in row-major order), which
    the dist_m4ri binary reads.  With up to _MTX_PY_MAX_NNZ nonzero entries, the file is formatted in Python (e.g.,
    about 1 ms for 6000 entries); larger matrices are written by scipy.io.mmwrite, which is faster per entry, but has a
    fixed cost of about 10 ms per call on a 128-core machine (the thread pool of its parallel writer).
    """
    import numpy as np
    m, n, rows, cols = _gf2_entries(matrix)
    nnz = len(rows)
    if nnz > _MTX_PY_MAX_NNZ:
        from scipy.io import mmwrite
        from scipy.sparse import coo_matrix
        mmwrite(path, coo_matrix((np.ones(nnz, dtype=np.int8), (rows, cols)), shape=(m, n)), field="pattern",
                symmetry="general")
        return
    rc = np.empty(2 * nnz, dtype=np.int64)  # the interleaved 1-based row and column indices
    rc[0::2], rc[1::2] = rows, cols
    rc += 1
    with open(path, "w") as f:
        f.write(f"%%MatrixMarket matrix coordinate pattern general\n{m} {n} {nnz}\n")
        f.write(("%d %d\n" * nnz) % tuple(rc.tolist()))
 
 
def _matrix_to_file(matrix, extension: str = ".mtx", temp_dir: str = "tmp") -> str:
    """
    The MatrixMarket file of a matrix for the dist_m4ri binary: a file path is returned as is; a numpy array (or an
    array-like) or a scipy sparse matrix is written to a new temporary file in temp_dir with _write_mtx_gf2() (its
    nonzero entries over GF(2), i.e., those with an odd value; before version 0.15.2, scipy.io.mmwrite wrote the int8
    entries, which took 10-13 ms per matrix with up to 1000 columns on a 128-core machine).
    """
    if isinstance(matrix, (str, Path)):
        return str(matrix)
    path = create_unique_file(directory=temp_dir, extension=extension)
    _write_mtx_gf2(path, matrix)
    return path
 
 
def has_noise(circuit: Any) -> bool:
    """
    Checks if a Stim circuit has noise: a noise channel (e.g., DEPOLARIZE1, X_ERROR, PAULI_CHANNEL_2, E, or
    HERALDED_ERASE), or a measurement with a flip probability (e.g., M(0.001) or MPP(0.01)), i.e., if strip_noise()
    changes it.
    """
    try:
        stim = _get_stim()
    except ImportError:
        return False
    if not isinstance(circuit, stim.Circuit):
        return False
    return circuit.without_noise() != circuit
 
 
def strip_noise(circuit: Any) -> Any:
    """
    Removes all noise from a Stim circuit (stim.Circuit or a .stim file), see stim.Circuit.without_noise(): the noise
    channels (e.g., DEPOLARIZE1, X_ERROR, PAULI_CHANNEL_2, E) are removed, the measurements lose their flip
    probabilities (M(0.001) becomes M), and heralded noise (e.g., HERALDED_ERASE) is replaced by MPAD, so that the
    measurement record does not change.  E.g., add_noise(strip_noise(circuit), p) (or add_noise(circuit, p,
    force=True); CLI: --force-noise) gives circuits with the same noise model.
 
    Returns:
        The noiseless stim.Circuit.
    """
    stim = _get_stim()
    if isinstance(circuit, (str, Path)):
        circuit = stim.Circuit.from_file(str(circuit))
    return circuit.without_noise()
 
 
def _add_noise_recursive(
    circuit: Any, p: float, num_qubits: int, active_qubits: Set[int]
) -> Any:
    """Recursively adds uniform circuit-level noise to a Stim circuit (see add_noise())."""
    stim = _get_stim()
    p1 = 0.1 * p  # one-qubit depolarizing noise (after one-qubit gates, on idle qubits)
    noisy_circuit = stim.Circuit()
    for inst in circuit:
        if isinstance(inst, stim.CircuitRepeatBlock):
            noisy_body = _add_noise_recursive(
                inst.body_copy(), p, num_qubits, active_qubits
            )
            noisy_circuit.append(
                stim.CircuitRepeatBlock(inst.repeat_count, noisy_body)
            )
            continue
        name = inst.name
        if name == "TICK":
            idle_qubits = set(range(num_qubits)) - active_qubits
            if idle_qubits:
                noisy_circuit.append("DEPOLARIZE1", sorted(idle_qubits), p1)
            noisy_circuit.append(inst)
            active_qubits.clear()
            continue
        gd = stim.gate_data(name)
        noise_channel = gd.is_noisy_gate and (not gd.produces_measurements or 0 not in gd.num_parens_arguments_range)
        if name == "MPAD" or noise_channel or not (gd.is_unitary or gd.is_reset or gd.produces_measurements):
            # annotations (DETECTOR, OBSERVABLE_INCLUDE, QUBIT_COORDS, SHIFT_COORDS), MPAD (its targets are bits, not
            # qubits), and the noise channels of a noisy circuit (also HERALDED_ERASE): no noise, not an operation
            noisy_circuit.append(inst)
            continue
        targets = inst.targets_copy()
        # qubit_value is None for measurement records (rec[-k]), sweep bits (sweep[k]), and combiners (*)
        qubits = [t.qubit_value for t in targets if t.qubit_value is not None]
        active_qubits.update(qubits)
        flip = "Z_ERROR" if name.endswith("X") else "X_ERROR"  # (RX, MX, MRX: X basis; Z or Y basis otherwise)
        if gd.produces_measurements and gd.is_single_qubit_gate:  # M, MX, MY, MR, MRX, MRY
            if qubits:
                noisy_circuit.append(flip, qubits, p)
            noisy_circuit.append(inst)
            if gd.is_reset and qubits:
                noisy_circuit.append(flip, qubits, p)
        elif gd.is_reset and not gd.produces_measurements:  # R, RX, RY
            noisy_circuit.append(inst)
            if qubits:
                noisy_circuit.append(flip, qubits, p)
        elif gd.is_unitary and gd.is_single_qubit_gate:  # I, X, H, H_XY, S, SQRT_X, C_XYZ, ...
            noisy_circuit.append(inst)
            if qubits:
                noisy_circuit.append("DEPOLARIZE1", qubits, p1)
        elif gd.is_unitary and gd.is_two_qubit_gate:  # CX, CZ, XCY, SWAP, ISWAP, SQRT_XX, CXSWAP, II, ...
            noisy_circuit.append(inst)
            pair_qubits: List[int] = []
            ctrl_qubits: List[int] = []  # the qubits of the classically controlled pairs (e.g., CX rec[-1] 5)
            for a, b in zip(targets[::2], targets[1::2]):
                if a.qubit_value is not None and b.qubit_value is not None:
                    pair_qubits += [a.qubit_value, b.qubit_value]
                else:
                    ctrl_qubits += [t.qubit_value for t in (a, b) if t.qubit_value is not None]
            if pair_qubits:
                noisy_circuit.append("DEPOLARIZE2", pair_qubits, p)
            if ctrl_qubits:
                noisy_circuit.append("DEPOLARIZE1", ctrl_qubits, p1)
        else:  # multi-qubit measurements (MPP, MXX, MYY, MZZ) and Pauli product gates (SPP, SPP_DAG): no noise
            noisy_circuit.append(inst)
    return noisy_circuit
 
 
def add_noise(circuit: Any, p: float = 0.001, force: bool = False) -> Any:
    """
    Adds uniform circuit-level noise of strength p to a Stim circuit (the gates are classified by stim.gate_data()):
    - DEPOLARIZE2(p) after two-qubit gates (CX, CY, CZ, XCX, XCY, XCZ, YCX, YCY, YCZ, SWAP, ISWAP, ISWAP_DAG, SQRT_XX,
      SQRT_YY, SQRT_ZZ and their _DAG versions, CXSWAP, SWAPCX, CZSWAP, II); a classically controlled gate (e.g.,
      CX rec[-1] 5 or CZ sweep[0] 5) gets DEPOLARIZE1(p/10) on its qubit;
    - DEPOLARIZE1(p/10) after one-qubit gates (I, X, Y, Z, H, H_XY, H_YZ, S, S_DAG, SQRT_X, SQRT_Y and their _DAG
      versions, C_XYZ, C_ZYX, and the other variants), and on the qubits idle since the previous TICK (at each TICK,
      and at the end of the circuit);
    - X (Z) flips with probability p after Z-basis or Y-basis (X-basis) resets and before measurements, both before and
      after a measurement with reset (MR, MRX, MRY);
    - none for the multi-qubit measurements (MPP, MXX, MYY, MZZ) and the Pauli product gates (SPP, SPP_DAG).
    The noise of a noisy circuit is kept and the uniform noise is added to it, unless force=True: then it is replaced
    (see strip_noise()).
 
    Args:
        circuit: stim.Circuit or path to a .stim file.
        p: Noise strength (for the distance, only which errors are possible matters); p=0: no noise is added.
        force: If True, all noise of the circuit is removed first (with p=0: only that).
 
    Returns:
        The noisy stim.Circuit (a copy).
    """
    stim = _get_stim()
    if isinstance(circuit, (str, Path)):
        circuit = stim.Circuit.from_file(str(circuit))
    if force:
        circuit = strip_noise(circuit)
    if p <= 0.0:
        return circuit.copy()
    num_qubits = circuit.num_qubits
    active_qubits: Set[int] = set()
    noisy_circuit = _add_noise_recursive(circuit, p, num_qubits, active_qubits)
    if active_qubits:
        final_idle_qubits = set(range(num_qubits)) - active_qubits
        if final_idle_qubits:
            noisy_circuit.append("DEPOLARIZE1", sorted(final_idle_qubits), 0.1 * p)
    return noisy_circuit
 
 
def remove_empty_detectors(circuit: Any) -> Tuple[Any, int]:
    """Removes DETECTOR instructions that have no measurement record targets."""
    stim = _get_stim()
    new_circuit = stim.Circuit()
    removed = 0
    for inst in circuit:
        if isinstance(inst, stim.CircuitRepeatBlock):
            body, r = remove_empty_detectors(inst.body_copy())
            removed += r * inst.repeat_count
            new_circuit.append(stim.CircuitRepeatBlock(inst.repeat_count, body))
        elif inst.name == "DETECTOR":
            rec_targets = [
                t for t in inst.targets_copy()
                if t.is_measurement_record_target
            ]
            if not rec_targets:
                removed += 1
            else:
                new_circuit.append(inst)
        else:
            new_circuit.append(inst)
    return new_circuit, removed
 
 
def has_repeat_block(circuit: Any) -> bool:
    """Checks if a Stim circuit contains at least one REPEAT block."""
    stim = _get_stim()
    if isinstance(circuit, (str, Path)):
        circuit = stim.Circuit.from_file(str(circuit))
    if not isinstance(circuit, stim.Circuit):
        return False
    for inst in circuit:
        if isinstance(inst, stim.CircuitRepeatBlock):
            return True
    return False
 
 
def set_circuit_rounds(circuit: Any, rounds: int) -> Any:
    """Sets the repeat_count of CircuitRepeatBlocks in a Stim circuit.
 
    For circuits with a single repeat block, sets its repeat_count to rounds.
    For circuits with two repeat blocks (e.g. preamble + periodic body),
    adjusts them to achieve total requested rounds.
 
    Args:
        circuit: A stim.Circuit instance.
        rounds: The new repetition count to set for repeat blocks. If <= 0,
            repeat blocks are omitted.
 
    Returns:
        A new stim.Circuit instance with modified repeat counts.
    """
    stim = _get_stim()
    if isinstance(circuit, (str, Path)):
        circuit = stim.Circuit.from_file(str(circuit))
    if not isinstance(circuit, stim.Circuit):
        return circuit
    if rounds < 0:
        raise ValueError(f"Invalid rounds={rounds}; must be >= 0.")
 
    top_blocks = [
        inst.repeat_count for inst in circuit
        if isinstance(inst, stim.CircuitRepeatBlock)
    ]
    if len(top_blocks) > 1:
        sys.stderr.write(
            f"# Warning: Circuit has {len(top_blocks)} repeat blocks "
            f"({top_blocks}) which may not be handled correctly by this "
            "script.\n"
        )
 
    new_circuit = stim.Circuit()
    if len(top_blocks) == 2:
        preamble = top_blocks[0]
        b1_count = min(preamble, rounds)
        b2_count = max(0, rounds - preamble)
        block_idx = 0
        for inst in circuit:
            if isinstance(inst, stim.CircuitRepeatBlock):
                cnt = b1_count if block_idx == 0 else b2_count
                block_idx += 1
                if cnt > 0:
                    new_body = set_circuit_rounds(inst.body_copy(), cnt)
                    new_circuit.append(stim.CircuitRepeatBlock(cnt, new_body))
            else:
                new_circuit.append(inst)
    else:
        for inst in circuit:
            if isinstance(inst, stim.CircuitRepeatBlock):
                if rounds > 0:
                    new_body = set_circuit_rounds(inst.body_copy(), rounds)
                    new_circuit.append(
                        stim.CircuitRepeatBlock(rounds, new_body)
                    )
            else:
                new_circuit.append(inst)
    return new_circuit
 
 
def count_circuit_rounds(circuit: Any) -> int:
    """Returns total repeat count of all repeat blocks in circuit, or 1 if unrolled."""
    stim = _get_stim()
    if isinstance(circuit, (str, Path)):
        circuit = stim.Circuit.from_file(str(circuit))
    if not isinstance(circuit, stim.Circuit):
        return 1
    blocks = [
        inst.repeat_count for inst in circuit
        if isinstance(inst, stim.CircuitRepeatBlock)
    ]
    if len(blocks) > 1:
        sys.stderr.write(
            f"# Warning: Circuit has {len(blocks)} repeat blocks "
            f"({blocks}) which may not be handled correctly by this "
            "script.\n"
        )
    return sum(blocks) if blocks else 1
 
 
def detect_basis(
    circuit: Any,
    filepath: Optional[Union[str, Path]] = None,
    basis_arg: Optional[str] = None
) -> str:
    """Determines the primary memory basis ('X' or 'Z') of a Stim circuit."""
    if basis_arg is not None and str(basis_arg).upper() in ["X", "Z"]:
        return str(basis_arg).upper()
 
    if filepath is not None:
        stem = Path(filepath).stem.upper()
        parts = stem.replace("-", "_").split("_")
        if "X" in parts or "HX" in parts or stem.endswith("X"):
            return "X"
        if "Z" in parts or "HZ" in parts or stem.endswith("Z"):
            return "Z"
 
    stim = _get_stim()
    if isinstance(circuit, (str, Path)):
        circuit = stim.Circuit.from_file(str(circuit))
 
    rx_count = 0
    rz_count = 0
    for inst in circuit:
        if isinstance(inst, stim.CircuitRepeatBlock):
            break
        if inst.name == "RX":
            rx_count += len(inst.targets_copy())
        elif inst.name in ["R", "RZ"]:
            rz_count += len(inst.targets_copy())
        elif inst.name in ["M", "MX", "MZ", "MR", "MRX", "MRZ"]:
            break
    if rx_count > rz_count:
        return "X"
    if rz_count > rx_count:
        return "Z"
 
    mx_count = 0
    mz_count = 0
    for inst in reversed(list(circuit)):
        if isinstance(inst, stim.CircuitRepeatBlock):
            break
        if inst.name in ["MX", "MRX"]:
            mx_count += len(inst.targets_copy())
        elif inst.name in ["M", "MZ", "MR", "MRZ"]:
            mz_count += len(inst.targets_copy())
    if mx_count > mz_count:
        return "X"
    return "Z"
 
 
def track_circuit_carriers(circuit: Any) -> List[List[int]]:
    """Dynamically tracks logical syndrome carriers across the circuit to measurements.
 
    Accounts for physical qubit permutations via SWAP, CXSWAP, CZSWAP, ISWAP,
    and ISWAP_DAG gates, as well as CNOT/CZ syndrome handoffs onto fresh ancilla
    or routing qubits.
 
    Returns:
        meas_carriers: List mapping each measurement index to a list of initial
            logical qubit IDs whose syndrome or state is carried into that
            measurement.
    """
    stim = _get_stim()
    if isinstance(circuit, (str, Path)):
        circuit = stim.Circuit.from_file(str(circuit))
    num_qubits = circuit.num_qubits
    phys_to_log = {q: q for q in range(num_qubits)}
 
    tot_resets: Dict[int, int] = {q: 0 for q in range(num_qubits)}
    tot_meas: Dict[int, int] = {q: 0 for q in range(num_qubits)}
 
    def pass1(block: Any, p_to_l: Dict[int, int], mult: int = 1) -> None:
        for inst in block:
            if isinstance(inst, stim.CircuitRepeatBlock):
                rep_count = inst.repeat_count
                body = inst.body_copy()
                map_copy = dict(p_to_l)
                for sub_inst in body:
                    if not isinstance(sub_inst, stim.CircuitRepeatBlock):
                        if sub_inst.name in [
                            "SWAP", "CXSWAP", "CZSWAP", "ISWAP", "ISWAP_DAG"
                        ]:
                            t_vals = [
                                t.value for t in sub_inst.targets_copy()
                                if t.is_qubit_target
                            ]
                            for idx in range(0, len(t_vals), 2):
                                q1, q2 = t_vals[idx], t_vals[idx + 1]
                                map_copy[q1], map_copy[q2] = (
                                    map_copy[q2], map_copy[q1]
                                )
                if map_copy == p_to_l:
                    pass1(body, p_to_l, mult * rep_count)
                else:
                    for _ in range(rep_count):
                        pass1(body, p_to_l, mult)
                continue
            name = inst.name
            t_vals = [
                t.value for t in inst.targets_copy() if t.is_qubit_target
            ]
            if name in [
                "R", "RX", "RY", "RZ", "MR", "MRX", "MRY", "MRZ"
            ]:
                for q in t_vals:
                    tot_resets[p_to_l[q]] += mult
            if name in [
                "M", "MX", "MY", "MZ", "MR", "MRX", "MRY", "MRZ"
            ]:
                for q in t_vals:
                    tot_meas[p_to_l[q]] += mult
            if name in ["SWAP", "CXSWAP", "CZSWAP", "ISWAP", "ISWAP_DAG"]:
                for idx in range(0, len(t_vals), 2):
                    q1, q2 = t_vals[idx], t_vals[idx + 1]
                    p_to_l[q1], p_to_l[q2] = p_to_l[q2], p_to_l[q1]
 
    pass1(circuit, dict(phys_to_log), 1)
    max_resets = max(tot_resets.values()) if tot_resets else 0
    max_meas = max(tot_meas.values()) if tot_meas else 0
    data_log = set()
    for q in range(num_qubits):
        if max_resets > 1:
            if tot_resets[q] <= 1:
                data_log.add(q)
        elif max_meas > 1:
            if tot_meas[q] <= 1:
                data_log.add(q)
 
    active_carriers: Dict[int, Set[int]] = {
        q: {q} for q in range(num_qubits)
    }
    fresh_anc: Set[int] = set(range(num_qubits)) - data_log
    meas_carriers: List[List[int]] = []
 
    def pass2(block: Any, p_to_l: Dict[int, int]) -> None:
        for inst in block:
            if isinstance(inst, stim.CircuitRepeatBlock):
                rep_count = inst.repeat_count
                body = inst.body_copy()
                if rep_count <= 0:
                    continue
                map_copy = dict(p_to_l)
                for sub_inst in body:
                    if not isinstance(sub_inst, stim.CircuitRepeatBlock):
                        if sub_inst.name in [
                            "SWAP", "CXSWAP", "CZSWAP", "ISWAP", "ISWAP_DAG"
                        ]:
                            t_vals = [
                                t.value for t in sub_inst.targets_copy()
                                if t.is_qubit_target
                            ]
                            for idx in range(0, len(t_vals), 2):
                                q1, q2 = t_vals[idx], t_vals[idx + 1]
                                map_copy[q1], map_copy[q2] = (
                                    map_copy[q2], map_copy[q1]
                                )
                if map_copy == p_to_l:
                    idx0 = len(meas_carriers)
                    pass2(body, p_to_l)
                    idx1 = len(meas_carriers)
                    if rep_count > 1 and idx1 > idx0:
                        body_carriers = meas_carriers[idx0:idx1]
                        meas_carriers.extend(body_carriers * (rep_count - 1))
                else:
                    for _ in range(rep_count):
                        pass2(body, p_to_l)
                continue
            name = inst.name
            t_vals = [
                t.value for t in inst.targets_copy() if t.is_qubit_target
            ]
            if name in ["R", "RX", "RY", "RZ"]:
                for q in t_vals:
                    lq = p_to_l[q]
                    active_carriers[lq] = {lq}
                    if lq not in data_log:
                        fresh_anc.add(lq)
            elif name in ["M", "MX", "MY", "MZ"]:
                for q in t_vals:
                    lq = p_to_l[q]
                    meas_carriers.append(sorted(list(active_carriers[lq])))
            elif name in ["MR", "MRX", "MRY", "MRZ"]:
                for q in t_vals:
                    lq = p_to_l[q]
                    meas_carriers.append(sorted(list(active_carriers[lq])))
                    active_carriers[lq] = {lq}
                    if lq not in data_log:
                        fresh_anc.add(lq)
            elif name in [
                "CX", "ZCX", "CY", "ZCY", "CZ", "ZCZ",
                "XCX", "XCY", "XCZ", "YCX", "YCY", "YCZ"
            ]:
                for idx in range(0, len(t_vals), 2):
                    q1, q2 = t_vals[idx], t_vals[idx + 1]
                    l1, l2 = p_to_l[q1], p_to_l[q2]
                    if l1 not in data_log and l2 not in data_log:
                        if l2 in fresh_anc and l1 not in fresh_anc:
                            active_carriers[l2] = set(active_carriers[l1])
                            fresh_anc.discard(l2)
                        elif l1 in fresh_anc and l2 not in fresh_anc:
                            active_carriers[l1] = set(active_carriers[l2])
                            fresh_anc.discard(l1)
                        else:
                            comb = active_carriers[l1] | active_carriers[l2]
                            active_carriers[l1] = set(comb)
                            active_carriers[l2] = set(comb)
                            fresh_anc.discard(l1)
                            fresh_anc.discard(l2)
                    elif l1 in data_log and l2 not in data_log:
                        fresh_anc.discard(l2)
                    elif l2 in data_log and l1 not in data_log:
                        fresh_anc.discard(l1)
            elif name == "SWAP":
                for idx in range(0, len(t_vals), 2):
                    q1, q2 = t_vals[idx], t_vals[idx + 1]
                    p_to_l[q1], p_to_l[q2] = p_to_l[q2], p_to_l[q1]
            elif name in ["CXSWAP", "CZSWAP", "ISWAP", "ISWAP_DAG"]:
                for idx in range(0, len(t_vals), 2):
                    q1, q2 = t_vals[idx], t_vals[idx + 1]
                    l1, l2 = p_to_l[q1], p_to_l[q2]
                    if l1 in data_log and l2 not in data_log:
                        fresh_anc.discard(l2)
                    elif l2 in data_log and l1 not in data_log:
                        fresh_anc.discard(l1)
                    p_to_l[q1], p_to_l[q2] = p_to_l[q2], p_to_l[q1]
 
    pass2(circuit, dict(phys_to_log))
    return meas_carriers
 
 
def _rewrite_circuit_internal(
    circ: Any,
    phys_to_log: Dict[int, int],
    active_gates_count: Dict[int, int]
) -> Any:
    """Rewrites a Stim circuit by tracking SWAPs virtually."""
    stim = _get_stim()
    new_circ = stim.Circuit()
    non_active_instructions = {
        "QUBIT_COORDS", "SHIFT_COORDS", "TICK",
        "DETECTOR", "OBSERVABLE_INCLUDE", "MPAD"
    }
 
    for inst in circ:
        if isinstance(inst, stim.CircuitRepeatBlock):
            rep_count = inst.repeat_count
            body = inst.body_copy()
            map_copy = dict(phys_to_log)
            for sub_inst in body:
                if not isinstance(sub_inst, stim.CircuitRepeatBlock):
                    if sub_inst.name in [
                        "SWAP", "CXSWAP", "CZSWAP", "ISWAP", "ISWAP_DAG"
                    ]:
                        targets = sub_inst.targets_copy()
                        for idx in range(0, len(targets), 2):
                            q1 = targets[idx].value
                            q2 = targets[idx + 1].value
                            map_copy[q1], map_copy[q2] = (
                                map_copy[q2], map_copy[q1]
                            )
            if map_copy == phys_to_log:
                new_body = _rewrite_circuit_internal(
                    body, phys_to_log, active_gates_count
                )
                new_circ.append(stim.CircuitRepeatBlock(rep_count, new_body))
            else:
                for _ in range(rep_count):
                    unrolled_body = _rewrite_circuit_internal(
                        body, phys_to_log, active_gates_count
                    )
                    new_circ += unrolled_body
            continue
 
        name = inst.name
        targets = inst.targets_copy()
        args = inst.gate_args_copy()
 
        if name == "SWAP":
            for idx in range(0, len(targets), 2):
                q1 = targets[idx].value
                q2 = targets[idx + 1].value
                phys_to_log[q1], phys_to_log[q2] = (
                    phys_to_log[q2], phys_to_log[q1]
                )
        elif name == "CXSWAP":
            cx_targets = []
            for idx in range(0, len(targets), 2):
                q1 = targets[idx].value
                q2 = targets[idx + 1].value
                l1 = phys_to_log[q1]
                l2 = phys_to_log[q2]
                cx_targets.extend([l1, l2])
                active_gates_count[l1] = active_gates_count.get(l1, 0) + 1
                active_gates_count[l2] = active_gates_count.get(l2, 0) + 1
                phys_to_log[q1], phys_to_log[q2] = (
                    phys_to_log[q2], phys_to_log[q1]
                )
            new_circ.append("CX", cx_targets, args)
        elif name == "CZSWAP":
            cz_targets = []
            for idx in range(0, len(targets), 2):
                q1 = targets[idx].value
                q2 = targets[idx + 1].value
                l1 = phys_to_log[q1]
                l2 = phys_to_log[q2]
                cz_targets.extend([l1, l2])
                active_gates_count[l1] = active_gates_count.get(l1, 0) + 1
                active_gates_count[l2] = active_gates_count.get(l2, 0) + 1
                phys_to_log[q1], phys_to_log[q2] = (
                    phys_to_log[q2], phys_to_log[q1]
                )
            new_circ.append("CZ", cz_targets, args)
        elif name in ["ISWAP", "ISWAP_DAG"]:
            cz_targets = []
            s_targets = []
            for idx in range(0, len(targets), 2):
                q1 = targets[idx].value
                q2 = targets[idx + 1].value
                l1 = phys_to_log[q1]
                l2 = phys_to_log[q2]
                cz_targets.extend([l1, l2])
                s_targets.extend([l1, l2])
                active_gates_count[l1] = active_gates_count.get(l1, 0) + 1
                active_gates_count[l2] = active_gates_count.get(l2, 0) + 1
                phys_to_log[q1], phys_to_log[q2] = (
                    phys_to_log[q2], phys_to_log[q1]
                )
            new_circ.append("CZ", cz_targets)
            s_gate = "S" if name == "ISWAP" else "S_DAG"
            new_circ.append(s_gate, s_targets)
        else:
            new_targets = []
            for t in targets:
                if t.is_qubit_target:
                    l_q = phys_to_log[t.value]
                    if name not in non_active_instructions:
                        active_gates_count[l_q] = (
                            active_gates_count.get(l_q, 0) + 1
                        )
                    if t.is_inverted_result_target:
                        new_targets.append(stim.target_inv(l_q))
                    else:
                        new_targets.append(l_q)
                elif t.is_x_target:
                    l_q = phys_to_log[t.value]
                    if name not in non_active_instructions:
                        active_gates_count[l_q] = (
                            active_gates_count.get(l_q, 0) + 1
                        )
                    new_targets.append(stim.target_x(l_q))
                elif t.is_y_target:
                    l_q = phys_to_log[t.value]
                    if name not in non_active_instructions:
                        active_gates_count[l_q] = (
                            active_gates_count.get(l_q, 0) + 1
                        )
                    new_targets.append(stim.target_y(l_q))
                elif t.is_z_target:
                    l_q = phys_to_log[t.value]
                    if name not in non_active_instructions:
                        active_gates_count[l_q] = (
                            active_gates_count.get(l_q, 0) + 1
                        )
                    new_targets.append(stim.target_z(l_q))
                else:
                    new_targets.append(t)
            new_circ.append(name, new_targets, args)
    return new_circ
 
 
def classify_qubits_thorough(
    circuit: Any,
    verbose: bool = False,
    basis_arg: Optional[str] = None,
    filepath: Optional[Union[str, Path]] = None
) -> Dict[str, Any]:
    """Classifies qubits and checks via virtual SWAP rewriting and Pauli basis tracking.
 
    Tracks both ancilla stabilizer evolution and data qubit initial basis
    evolution through 1-qubit and 2-qubit Clifford gates. Supports standard
    CSS codes as well as locally basis-rotated CSS codes (such as XZZX codes)
    via 2-coloring of the check-data Pauli compatibility graph.
 
    Returns:
        Dictionary with keys:
        - 'x_ancillas': Sorted list of X-type (or X-sector) ancilla qubit IDs.
        - 'z_ancillas': Sorted list of Z-type (or Z-sector) ancilla qubit IDs.
        - 'data_qubits': Sorted list of data qubit IDs.
        - 'routing_qubits': Sorted list of idle/routing qubit IDs.
        - 'rotated_data_qubits': Sorted list of data qubits with rotated local basis.
        - 'is_css': True if the circuit implements a (possibly locally rotated) CSS code.
        - 'is_rotated_css': True if CSS only after local data basis rotations (e.g. XZZX).
        - 'basis': Primary memory basis ('X' or 'Z').
        - 'rewritten_circuit': Circuit with SWAPs virtually eliminated.
    """
    stim = _get_stim()
    if isinstance(circuit, (str, Path)):
        if filepath is None:
            filepath = circuit
        circuit = stim.Circuit.from_file(str(circuit))
 
    all_qubits_set: Set[int] = set()
 
    def collect_qubits(blk: Any) -> None:
        for inst in blk:
            if isinstance(inst, stim.CircuitRepeatBlock):
                collect_qubits(inst.body_copy())
            else:
                for t in inst.targets_copy():
                    if (
                        t.is_qubit_target or t.is_x_target
                        or t.is_y_target or t.is_z_target
                    ):
                        all_qubits_set.add(t.value)
 
    collect_qubits(circuit)
    max_q = max(all_qubits_set) if all_qubits_set else -1
    phys_to_log = {q: q for q in range(max_q + 1)}
    active_gates_count = {q: 0 for q in all_qubits_set}
 
    def cap_repeats(blk: Any) -> Any:
        out = stim.Circuit()
        for inst in blk:
            if isinstance(inst, stim.CircuitRepeatBlock):
                out.append(
                    stim.CircuitRepeatBlock(
                        min(inst.repeat_count, 2),
                        cap_repeats(inst.body_copy())
                    )
                )
            else:
                out.append(inst)
        return out
 
    capped_circuit = cap_repeats(circuit)
    rewritten_circ = _rewrite_circuit_internal(
        capped_circuit, phys_to_log, active_gates_count
    )
    routing_qubits = {
        q for q, count in active_gates_count.items() if count == 0
    }
    active_qubits = all_qubits_set - routing_qubits
 
    flat_circ = rewritten_circ.flattened()
 
    tot_resets: Dict[int, int] = {q: 0 for q in active_qubits}
    tot_meas: Dict[int, int] = {q: 0 for q in active_qubits}
    meas_records: List[int] = []
    used_in_detector: Set[int] = set()
    used_in_observable: Set[int] = set()
    first_detector_seen = False
    meas_before_first_det: Set[int] = set()
    r1_single_det_anc: Set[int] = set()
    multi_det_groups: List[Set[int]] = []
 
    for inst in flat_circ:
        name = inst.name
        targets = inst.targets_copy()
        if name in ["R", "RX", "RY", "RZ"]:
            for t in targets:
                if t.is_qubit_target and t.value in tot_resets:
                    tot_resets[t.value] += 1
        elif name in ["M", "MX", "MY", "MZ"]:
            for t in targets:
                if t.is_qubit_target:
                    if t.value in tot_meas:
                        tot_meas[t.value] += 1
                    meas_records.append(t.value)
                    if not first_detector_seen:
                        meas_before_first_det.add(t.value)
        elif name in ["MR", "MRX", "MRY", "MRZ"]:
            for t in targets:
                if t.is_qubit_target:
                    if t.value in tot_resets:
                        tot_resets[t.value] += 1
                    if t.value in tot_meas:
                        tot_meas[t.value] += 1
                    meas_records.append(t.value)
                    if not first_detector_seen:
                        meas_before_first_det.add(t.value)
        elif name == "DETECTOR":
            first_detector_seen = True
            recs = [
                meas_records[len(meas_records) + t.value]
                for t in targets
                if t.is_measurement_record_target
                and 0 <= len(meas_records) + t.value < len(meas_records)
            ]
            for q in recs:
                used_in_detector.add(q)
            if len(recs) == 1:
                r1_single_det_anc.add(recs[0])
            elif len(recs) > 1:
                multi_det_groups.append(set(recs))
        elif name == "OBSERVABLE_INCLUDE":
            for t in targets:
                if t.is_measurement_record_target:
                    idx = len(meas_records) + t.value
                    if 0 <= idx < len(meas_records):
                        used_in_observable.add(meas_records[idx])
 
    max_resets = max(tot_resets.values()) if tot_resets else 0
    max_meas = max(tot_meas.values()) if tot_meas else 0
 
    data_qubits: Set[int] = set()
    anc_candidates: Set[int] = set()
 
    for q in active_qubits:
        if max_resets > 1:
            is_data = (tot_resets[q] <= 1)
        elif max_meas > 1:
            is_data = (tot_meas[q] <= 1)
        else:
            if q not in used_in_detector:
                is_data = True
            else:
                is_data = (
                    (q not in meas_before_first_det)
                    or (q in used_in_observable)
                )
        if is_data:
            data_qubits.add(q)
        else:
            anc_candidates.add(q)
 
    # First-round stabilizer & data-basis tracking
    reset_basis: Dict[int, str] = {}
    meas_basis: Dict[int, str] = {}
    first_round_insts: List[Tuple[str, List[int]]] = []
    measured_anc: Set[int] = set()
    has_any_anc_meas = False
 
    for inst in flat_circ:
        name = inst.name
        t_vals = [t.value for t in inst.targets_copy() if t.is_qubit_target]
        if name in ["R", "RZ", "RX", "RY"]:
            if has_any_anc_meas and any(
                q in anc_candidates and q in measured_anc for q in t_vals
            ):
                break
            b = "X" if name == "RX" else ("Y" if name == "RY" else "Z")
            for q in t_vals:
                if q not in reset_basis:
                    reset_basis[q] = b
            first_round_insts.append((name, t_vals))
        elif name in ["M", "MZ", "MX", "MY", "MR", "MRZ", "MRX", "MRY"]:
            if any(q in data_qubits for q in t_vals) and has_any_anc_meas:
                break
            if any(q in anc_candidates and q in measured_anc for q in t_vals):
                break
            b = (
                "X" if name in ["MX", "MRX"]
                else ("Y" if name in ["MY", "MRY"] else "Z")
            )
            for q in t_vals:
                if q in anc_candidates:
                    meas_basis[q] = b
                    measured_anc.add(q)
                    has_any_anc_meas = True
                    if q not in reset_basis and name in [
                        "MR", "MRZ", "MRX", "MRY"
                    ]:
                        reset_basis[q] = b
            first_round_insts.append((name, t_vals))
        elif name in [
            "H", "H_XZ", "H_XY", "H_YZ", "S", "S_DAG",
            "SQRT_Z", "SQRT_Z_DAG", "SQRT_X", "SQRT_X_DAG",
            "SQRT_Y", "SQRT_Y_DAG",
            "CX", "ZCX", "CZ", "ZCZ", "CY", "ZCY",
            "XCX", "XCY", "XCZ", "YCX", "YCY", "YCZ"
        ]:
            first_round_insts.append((name, t_vals))
 
    def conj_1q(gate: str, p: str) -> str:
        if p == "I":
            return "I"
        if gate in ["H", "H_XZ"]:
            return "Z" if p == "X" else ("X" if p == "Z" else "Y")
        if gate in ["S", "S_DAG", "SQRT_Z", "SQRT_Z_DAG", "H_XY"]:
            return "Y" if p == "X" else ("X" if p == "Y" else "Z")
        if gate in ["SQRT_X", "SQRT_X_DAG", "H_YZ"]:
            return "Z" if p == "Y" else ("Y" if p == "Z" else "X")
        if gate in ["SQRT_Y", "SQRT_Y_DAG"]:
            return "Z" if p == "X" else ("X" if p == "Z" else "Y")
        return p
 
    mul_tab = {
        ("I", "I"): "I", ("I", "X"): "X", ("I", "Y"): "Y", ("I", "Z"): "Z",
        ("X", "I"): "X", ("X", "X"): "I", ("X", "Y"): "Z", ("X", "Z"): "Y",
        ("Y", "I"): "Y", ("Y", "X"): "Z", ("Y", "Y"): "I", ("Y", "Z"): "X",
        ("Z", "I"): "Z", ("Z", "X"): "Y", ("Z", "Y"): "X", ("Z", "Z"): "I",
    }
 
    def conj_2q(gate: str, p1: str, p2: str) -> Tuple[str, str]:
        if p1 == "I" and p2 == "I":
            return "I", "I"
        if gate in ["CX", "ZCX"]:
            a, b = "Z", "X"
        elif gate in ["CZ", "ZCZ"]:
            a, b = "Z", "Z"
        elif gate in ["CY", "ZCY"]:
            a, b = "Z", "Y"
        elif gate == "XCX":
            a, b = "X", "X"
        elif gate == "XCY":
            a, b = "X", "Y"
        elif gate == "XCZ":
            a, b = "X", "Z"
        elif gate == "YCX":
            a, b = "Y", "X"
        elif gate == "YCY":
            a, b = "Y", "Y"
        elif gate == "YCZ":
            a, b = "Y", "Z"
        else:
            return p1, p2
        anti1 = (p1 != "I" and p1 != a)
        anti2 = (p2 != "I" and p2 != b)
        np1 = mul_tab[(p1, a)] if anti2 else p1
        np2 = mul_tab[(p2, b)] if anti1 else p2
        return np1, np2
 
    # Simultaneously evolve all ancilla stabilizers and data initial bases
    # using bitmasks over sorted anc_list for O(1) gate updates.
    anc_list = sorted(list(anc_candidates))
    anc_to_bit = {anc: (1 << i) for i, anc in enumerate(anc_list)}
    all_anc_mask = (1 << len(anc_list)) - 1
    active_anc_mask = 0
    qx: Dict[int, int] = {q: 0 for q in all_qubits_set}
    qz: Dict[int, int] = {q: 0 for q in all_qubits_set}
 
    for anc in anc_list:
        b = reset_basis.get(anc, meas_basis.get(anc, "Z"))
        bit = anc_to_bit[anc]
        if b in ["X", "Y"]:
            qx[anc] |= bit
        if b in ["Z", "Y"]:
            qz[anc] |= bit
        if anc not in reset_basis:
            active_anc_mask |= bit
 
    data_init_basis: Dict[int, str] = {q: "Z" for q in data_qubits}
 
    for name, t_vals in first_round_insts:
        if name in ["R", "RZ", "RX", "RY"]:
            b = "X" if name == "RX" else ("Y" if name == "RY" else "Z")
            for q in t_vals:
                if q in data_qubits:
                    data_init_basis[q] = b
                if q in anc_to_bit:
                    bit = anc_to_bit[q]
                    if not (active_anc_mask & bit):
                        active_anc_mask |= bit
                        if b in ["X", "Y"]:
                            qx[q] |= bit
                        else:
                            qx[q] &= ~bit
                        if b in ["Z", "Y"]:
                            qz[q] |= bit
                        else:
                            qz[q] &= ~bit
        elif name in ["M", "MZ", "MX", "MY", "MR", "MRZ", "MRX", "MRY"]:
            for q in t_vals:
                if q in anc_to_bit:
                    active_anc_mask &= ~anc_to_bit[q]
        elif name in [
            "H", "H_XZ", "H_XY", "H_YZ", "S", "S_DAG",
            "SQRT_Z", "SQRT_Z_DAG", "SQRT_X", "SQRT_X_DAG",
            "SQRT_Y", "SQRT_Y_DAG"
        ]:
            for q in t_vals:
                if q in data_qubits:
                    data_init_basis[q] = conj_1q(name, data_init_basis[q])
                if q not in qx:
                    continue
                # on a data qubit, the Paulis of all checks are transformed, also of the checks already measured:
                # all checks are then expressed in the same frame (that of the data qubits at the end of the first
                # round), e.g., for X checks measured in the Hadamard frame of the data qubits before the closing H
                # gates (with active_anc_mask, such checks would look like Z checks; see the tests)
                mask = active_anc_mask if q in anc_candidates else all_anc_mask
                x_m = qx[q] & mask
                z_m = qz[q] & mask
                if name in ["H", "H_XZ", "SQRT_Y", "SQRT_Y_DAG"]:
                    nx_m, nz_m = z_m, x_m
                elif name in [
                    "S", "S_DAG", "SQRT_Z", "SQRT_Z_DAG", "H_XY"
                ]:
                    nx_m, nz_m = x_m, x_m ^ z_m
                elif name in ["SQRT_X", "SQRT_X_DAG", "H_YZ"]:
                    nx_m, nz_m = x_m ^ z_m, z_m
                else:
                    nx_m, nz_m = x_m, z_m
                qx[q] = (qx[q] & ~mask) | nx_m
                qz[q] = (qz[q] & ~mask) | nz_m
        elif name in [
            "CX", "ZCX", "CZ", "ZCZ", "CY", "ZCY",
            "XCX", "XCY", "XCZ", "YCX", "YCY", "YCZ"
        ]:
            if name in ["CX", "ZCX"]:
                ax, az, bx, bz = 0, all_anc_mask, all_anc_mask, 0
            elif name in ["CZ", "ZCZ"]:
                ax, az, bx, bz = 0, all_anc_mask, 0, all_anc_mask
            elif name in ["CY", "ZCY"]:
                ax, az, bx, bz = 0, all_anc_mask, all_anc_mask, all_anc_mask
            elif name == "XCX":
                ax, az, bx, bz = all_anc_mask, 0, all_anc_mask, 0
            elif name == "XCY":
                ax, az, bx, bz = all_anc_mask, 0, all_anc_mask, all_anc_mask
            elif name == "XCZ":
                ax, az, bx, bz = all_anc_mask, 0, 0, all_anc_mask
            elif name == "YCX":
                ax, az, bx, bz = all_anc_mask, all_anc_mask, all_anc_mask, 0
            elif name == "YCY":
                ax, az, bx, bz = (
                    all_anc_mask, all_anc_mask, all_anc_mask, all_anc_mask
                )
            elif name == "YCZ":
                ax, az, bx, bz = all_anc_mask, all_anc_mask, 0, all_anc_mask
            else:
                continue
 
            for idx in range(0, len(t_vals), 2):
                q1, q2 = t_vals[idx], t_vals[idx + 1]
                if q1 not in qx or q2 not in qx:
                    continue
                mask = active_anc_mask
                if q1 in anc_to_bit and not (active_anc_mask & anc_to_bit[q1]):
                    mask &= ~anc_to_bit[q1]
                if q2 in anc_to_bit and not (active_anc_mask & anc_to_bit[q2]):
                    mask &= ~anc_to_bit[q2]
                x1 = qx[q1] & mask
                z1 = qz[q1] & mask
                x2 = qx[q2] & mask
                z2 = qz[q2] & mask
                anti1 = (x1 & (az & mask)) ^ (z1 & (ax & mask))
                anti2 = (x2 & (bz & mask)) ^ (z2 & (bx & mask))
                nx1 = x1 ^ (anti2 & ax)
                nz1 = z1 ^ (anti2 & az)
                nx2 = x2 ^ (anti1 & bx)
                nz2 = z2 ^ (anti1 & bz)
                qx[q1] = (qx[q1] & ~mask) | nx1
                qz[q1] = (qz[q1] & ~mask) | nz1
                qx[q2] = (qx[q2] & ~mask) | nx2
                qz[q2] = (qz[q2] & ~mask) | nz2
 
    anc_data_paulis: Dict[int, Dict[int, str]] = {
        anc: {} for anc in anc_list
    }
    for q in data_qubits:
        xm = qx[q]
        zm = qz[q]
        active_m = xm | zm
        while active_m:
            lsb = active_m & -active_m
            anc_idx = lsb.bit_length() - 1
            anc = anc_list[anc_idx]
            has_x = bool(xm & lsb)
            has_z = bool(zm & lsb)
            p_str = (
                "Y" if (has_x and has_z)
                else ("X" if has_x else "Z")
            )
            anc_data_paulis[anc][q] = p_str
            active_m ^= lsb
 
    active_ancillas = [a for a in anc_list if len(anc_data_paulis[a]) > 0]
    idle_ancillas = [a for a in anc_list if len(anc_data_paulis[a]) == 0]
    routing_qubits.update(idle_ancillas)
 
    # Check commutation among active ancillas
    checks_commute = True
    for i in range(len(active_ancillas)):
        a1 = active_ancillas[i]
        s1 = anc_data_paulis[a1]
        for j in range(i + 1, len(active_ancillas)):
            a2 = active_ancillas[j]
            s2 = anc_data_paulis[a2]
            anti = 0
            for q, p1 in s1.items():
                p2 = s2.get(q)
                if p2 is not None and p1 != p2:
                    anti ^= 1
            if anti != 0:
                checks_commute = False
                break
        if not checks_commute:
            break
 
    # Build check-relation graph on active_ancillas via shared data qubits
    adj: Dict[int, Dict[int, int]] = {a: {} for a in active_ancillas}
    bipartite_paulis = True
    for q in data_qubits:
        touching = [
            (a, anc_data_paulis[a][q])
            for a in active_ancillas
            if q in anc_data_paulis[a]
        ]
        if not touching:
            continue
        pauli_set = {p for _, p in touching}
        if len(pauli_set) > 2:
            bipartite_paulis = False
            break
        a0, p0 = touching[0]
        for ak, pk in touching[1:]:
            rel = 0 if pk == p0 else 1
            if ak in adj[a0] and adj[a0][ak] != rel:
                bipartite_paulis = False
                break
            adj[a0][ak] = rel
            adj[ak][a0] = rel
        if not bipartite_paulis:
            break
 
    # 2-color connected components of active_ancillas
    color: Dict[int, int] = {}
    components: List[Tuple[List[int], List[int]]] = []
    if bipartite_paulis:
        for a in active_ancillas:
            if a in color:
                continue
            c0: List[int] = []
            c1: List[int] = []
            color[a] = 0
            queue = [a]
            idx_q = 0
            while idx_q < len(queue):
                u = queue[idx_q]
                idx_q += 1
                if color[u] == 0:
                    c0.append(u)
                else:
                    c1.append(u)
                for v, rel in adj[u].items():
                    expected = color[u] ^ rel
                    if v not in color:
                        color[v] = expected
                        queue.append(v)
                    elif color[v] != expected:
                        bipartite_paulis = False
                        break
                if not bipartite_paulis:
                    break
            if not bipartite_paulis:
                break
            components.append((c0, c1))
 
    # Determine if all checks are already pure-X or pure-Z (standard CSS)
    all_pure_xz = True
    for a in active_ancillas:
        ps = set(anc_data_paulis[a].values())
        if not (ps == {"X"} or ps == {"Z"}):
            all_pure_xz = False
            break
 
    # Detect color code (pure X and pure Z checks with identical support)
    native_basis = detect_basis(
        circuit, filepath=filepath, basis_arg=basis_arg
    )
    final_det_anc: Set[int] = set()
    for grp in multi_det_groups:
        if grp & data_qubits:
            final_det_anc.update(grp & set(active_ancillas))
 
    x_ancillas: Set[int] = set()
    z_ancillas: Set[int] = set()
    rotated_data_qubits: Set[int] = set()
    is_css = False
    is_rotated_css = False
 
    if checks_commute and bipartite_paulis and active_ancillas:
        if all_pure_xz:
            for a in active_ancillas:
                ps = set(anc_data_paulis[a].values())
                if ps == {"X"}:
                    x_ancillas.add(a)
                else:
                    z_ancillas.add(a)
            x_supps = {
                frozenset(anc_data_paulis[a].keys()) for a in x_ancillas
            }
            z_supps = {
                frozenset(anc_data_paulis[a].keys()) for a in z_ancillas
            }
            is_color_code = (
                len(x_supps) > 0 and x_supps == z_supps
                and len(x_ancillas) == len(z_ancillas)
            )
            is_css = not is_color_code
            is_rotated_css = False
        else:
            is_css = True
            is_rotated_css = True
            for c0, c1 in components:
                # Score which sector is the primary memory basis
                def score_primary(sector: List[int]) -> Tuple[int, int, int]:
                    r1_cnt = sum(1 for a in sector if a in r1_single_det_anc)
                    fin_cnt = sum(1 for a in sector if a in final_det_anc)
                    init_cnt = sum(
                        1 for a in sector
                        if all(
                            anc_data_paulis[a][q] == data_init_basis.get(q, "Z")
                            for q in anc_data_paulis[a]
                        )
                    )
                    return (r1_cnt, fin_cnt, init_cnt)
 
                sc0 = score_primary(c0)
                sc1 = score_primary(c1)
                if sc0 >= sc1:
                    primary_sec, minority_sec = c0, c1
                else:
                    primary_sec, minority_sec = c1, c0
 
                if native_basis == "Z":
                    z_ancillas.update(primary_sec)
                    x_ancillas.update(minority_sec)
                else:
                    x_ancillas.update(primary_sec)
                    z_ancillas.update(minority_sec)
 
            # Determine rotated data qubits (where check Pauli != sector label)
            for q in data_qubits:
                for a in active_ancillas:
                    if q in anc_data_paulis[a]:
                        sector_label = "X" if a in x_ancillas else "Z"
                        if anc_data_paulis[a][q] != sector_label:
                            rotated_data_qubits.add(q)
                        break
    else:
        # Non-CSS fallback classification by majority Pauli weight
        is_css = False
        is_rotated_css = False
        for a in active_ancillas:
            s = anc_data_paulis[a]
            nx = sum(1 for p in s.values() if p == "X")
            nz = sum(1 for p in s.values() if p == "Z")
            if nz > nx:
                z_ancillas.add(a)
            else:
                x_ancillas.add(a)
 
    return {
        "x_ancillas": sorted(list(x_ancillas)),
        "z_ancillas": sorted(list(z_ancillas)),
        "data_qubits": sorted(list(data_qubits)),
        "routing_qubits": sorted(list(routing_qubits)),
        "rotated_data_qubits": sorted(list(rotated_data_qubits)),
        "is_css": is_css,
        "is_rotated_css": is_rotated_css,
        "basis": native_basis,
        "rewritten_circuit": rewritten_circ,
    }
 
 
def verify_qubit_metadata(
    circuit: Any,
    verbose: bool = False,
    basis_arg: Optional[str] = None,
    filepath: Optional[Union[str, Path]] = None
) -> Dict[str, Any]:
    """Verifies qubit classification and returns basis tracking metadata."""
    return classify_qubits_thorough(
        circuit, verbose=verbose, basis_arg=basis_arg, filepath=filepath
    )
 
 
def strip_minority_detectors(
    circuit: Any,
    basis: str,
    verbose: bool = False,
    thorough: bool = True,
    thorough_res: Optional[Dict[str, Any]] = None,
    mask_out: Optional[List[bool]] = None
) -> Tuple[Any, int, int]:
    """Strips detectors corresponding to the minority basis from a Stim circuit.
 
    Always uses ancilla and data basis tracking (and dynamic carrier tracking
    across SWAPs and syndrome handoffs) to identify each detector's basis.
 
    Args:
        circuit: A stim.Circuit object or path to a .stim file.
        basis: Primary memory basis ('X' or 'Z'). Detectors of the opposite
            basis are removed.
        verbose: Whether to print warnings/statistics.
        thorough: Kept for API compatibility (basis tracking is always enabled).
        thorough_res: Optional precomputed result from classify_qubits_thorough.
        mask_out: Optional list, extended by one entry per detector of the circuit (in the order of the detectors of
            its DEM, REPEAT blocks unrolled): True if the detector is stripped, False if it is kept.
 
    Returns:
        Tuple of (simplified_circuit, stripped_count, kept_count).
    """
    stim = _get_stim()
    if isinstance(circuit, (str, Path)):
        circuit = stim.Circuit.from_file(str(circuit))
 
    t_res = (
        thorough_res
        if thorough_res is not None
        else classify_qubits_thorough(circuit, verbose=False, basis_arg=basis)
    )
    x_anc = set(t_res["x_ancillas"])
    z_anc = set(t_res["z_ancillas"])
    minority_basis = "Z" if basis.upper() == "X" else "X"
 
    meas_carriers = track_circuit_carriers(circuit)
 
    # Coordinate metadata for consistency check on standard (non-rotated) CSS
    qubit_coords: Dict[int, Tuple[float, ...]] = {}
 
    def get_coords(blk: Any) -> None:
        for inst in blk:
            if isinstance(inst, stim.CircuitRepeatBlock):
                get_coords(inst.body_copy())
            elif inst.name == "QUBIT_COORDS":
                args = inst.gate_args_copy()
                for t in inst.targets_copy():
                    if t.is_qubit_target:
                        qubit_coords[t.value] = tuple(float(x) for x in args)
 
    get_coords(circuit)
    x_coords = {
        qubit_coords[q][:2]
        for q in x_anc
        if q in qubit_coords and len(qubit_coords[q]) >= 2
    }
    z_coords = {
        qubit_coords[q][:2]
        for q in z_anc
        if q in qubit_coords and len(qubit_coords[q]) >= 2
    }
    layout_well_defined = (
        not t_res.get("is_rotated_css", False)
        and len(x_coords) > 0
        and len(z_coords) > 0
        and x_coords.isdisjoint(z_coords)
    )
 
    meas_history: List[int] = []
    det_mask: List[bool] = []  # one entry per detector (REPEAT blocks unrolled): True if stripped
    stripped_count = 0
    kept_count = 0
    contradictions_c_count = 0
    floquet_suspected = False
 
    def process_block(block: Any) -> Any:
        nonlocal stripped_count, kept_count
        nonlocal contradictions_c_count, floquet_suspected
        new_block = stim.Circuit()
        for inst in block:
            if isinstance(inst, stim.CircuitRepeatBlock):
                rep_count = inst.repeat_count
                if rep_count <= 0:
                    continue
                body_copy = inst.body_copy()
                meas_before = len(meas_history)
                mask_before = len(det_mask)
                strip_before = stripped_count
                kept_before = kept_count
                new_body = process_block(body_copy)
                meas_after = len(meas_history)
                meas_per_rep = meas_after - meas_before
                if rep_count > 1:
                    stripped_count += (stripped_count - strip_before) * (
                        rep_count - 1
                    )
                    kept_count += (kept_count - kept_before) * (rep_count - 1)
                    det_mask.extend(det_mask[mask_before:] * (rep_count - 1))
                    if meas_per_rep > 0:
                        meas_history.extend(
                            meas_history[meas_before:meas_after]
                            * (rep_count - 1)
                        )
                new_block.append(stim.CircuitRepeatBlock(rep_count, new_body))
            elif inst.name in [
                "M", "MX", "MY", "MZ", "MR", "MRX", "MRY", "MRZ"
            ]:
                if inst.name in ["MY", "MRY"]:
                    floquet_suspected = True
                for t in inst.targets_copy():
                    if t.is_qubit_target:
                        meas_history.append(t.value)
                new_block.append(inst)
            elif inst.name == "DETECTOR":
                cur_meas = len(meas_history)
                rec_targets = [
                    t for t in inst.targets_copy()
                    if t.is_measurement_record_target
                ]
                if not rec_targets:
                    stripped_count += 1
                    det_mask.append(True)
                    continue
 
                qubits = [
                    meas_history[cur_meas + t.value]
                    for t in rec_targets
                    if 0 <= cur_meas + t.value < cur_meas
                ]
                is_x_qubit = any(q in x_anc for q in qubits)
                is_z_qubit = any(q in z_anc for q in qubits)
                class_qubit = (
                    "Both" if (is_x_qubit and is_z_qubit)
                    else "X" if is_x_qubit
                    else "Z" if is_z_qubit
                    else "Unknown"
                )
 
                args = inst.gate_args_copy()
                class_b = "Unknown"
                if layout_well_defined and args and len(args) >= 2:
                    det_xy = (float(args[0]), float(args[1]))
                    if det_xy in x_coords:
                        class_b = "X"
                    elif det_xy in z_coords:
                        class_b = "Z"
 
                class_c = "Unknown"
                if meas_carriers:
                    carriers = [
                        c
                        for t in rec_targets
                        if 0 <= cur_meas + t.value < len(meas_carriers)
                        for c in meas_carriers[cur_meas + t.value]
                    ]
                    is_x_c = any(c in x_anc for c in carriers)
                    is_z_c = any(c in z_anc for c in carriers)
                    class_c = (
                        "Both" if (is_x_c and is_z_c)
                        else "X" if is_x_c
                        else "Z" if is_z_c
                        else "Unknown"
                    )
 
                is_minority = False
                if class_c != "Unknown":
                    if class_c == "Both":
                        contradictions_c_count += 1
                        floquet_suspected = True
                    elif class_b != "Unknown" and class_c != class_b:
                        contradictions_c_count += 1
                    elif len(rec_targets) == 1 and class_c == minority_basis:
                        contradictions_c_count += 1
                    is_minority = (class_c == minority_basis)
                elif layout_well_defined and class_b != "Unknown":
                    is_minority = (class_b == minority_basis)
                elif len(rec_targets) == 1:
                    is_minority = False
                else:
                    if class_qubit == "Both":
                        floquet_suspected = True
                    is_minority = (class_qubit == minority_basis)
 
                if is_minority:
                    stripped_count += 1
                else:
                    kept_count += 1
                    new_block.append(inst)
                det_mask.append(is_minority)
            else:
                new_block.append(inst)
        return new_block
 
    simp_circuit = process_block(circuit)
    if mask_out is not None:
        mask_out.extend(det_mask)
 
    if contradictions_c_count > 0 and verbose:
        sys.stderr.write(
            f"# Warning: {contradictions_c_count} detector contradiction(s) "
            "detected during dynamic carrier tracking.\n"
        )
    if floquet_suspected and verbose:
        sys.stderr.write(
            "# Warning: Floquet or dynamic measurement structure suspected; "
            "simplified circuit distance may be invalid.\n"
        )
 
    return simp_circuit, stripped_count, kept_count
 
 
def _matrix_cache_key(H: Any, G: Optional[Any] = None, L: Optional[Any] = None, classical: bool = False) -> str:
    """
    Cache key of a classical code (H), or of a quantum code given by H with G (or with L).  The two sectors of a CSS
    code are stored as the quantum codes (H=Hx, G=Hz) -> dZ and (H=Hz, G=Hx) -> dX (with L=Lx / L=Lz if given), so
    that compute_css_distance() and compute_quantum_distance() share their cache records.
    """
    h_state = get_sparse_array_state(H)
    if classical:
        return f"classical:{h_state}"
    if G is not None:
        return f"quantum:H={h_state}:G={get_sparse_array_state(G)}"
    return f"quantum:H={h_state}:L={get_sparse_array_state(L)}"
 
 
def _dem_cache_key(dem: Any, pmin: float = 0.0) -> str:
    """Cache key of a DEM (a stim.DetectorErrorModel or a .dem file) with the probability cutoff pmin."""
    dem_state = get_sparse_array_state(dem)
    return f"dem:{dem_state}" if pmin <= 0.0 else f"dem:{dem_state}:pmin={pmin}"
 
 
def _write_dem_file(dem: Any, path: str) -> None:
    """Writes a stim.DetectorErrorModel (flattened) or the text of a DEM to the file `path`."""
    if hasattr(dem, 'flattened'):
        dem.flattened().to_file(path)
    elif hasattr(dem, 'to_file'):
        dem.to_file(path)
    else:
        with open(path, 'w') as f:
            f.write(str(dem))
 
 
def _dem_error_columns(dem: Any, pmin: float = 0.0, with_prob: bool = False) -> List[Tuple[Any, ...]]:
    """
    The columns of a DEM (a stim.DetectorErrorModel, or a .dem file) as read by the dist_m4ri binary: the detector and
    observable sets of its error mechanisms, in their order in the flattened DEM (repeat blocks unrolled, with
    shift_detectors), after the probability cutoff pmin (an error with probability < pmin is skipped).  The components
    of a decomposed error (separated by '^') are summed mod 2, so that a target listed twice cancels.  With
    with_prob=True, each column also has the probability of the error, as written: (detectors, observables, p).
    """
    if isinstance(dem, (str, Path)):
        with open(str(dem)) as f:
            lines = f.read().splitlines()
    else:
        lines = str(dem.flattened() if hasattr(dem, 'flattened') else dem).splitlines()
    cols: List[Tuple[Any, ...]] = []
 
    def block(i: int, shift: int) -> Tuple[int, int]:
        # runs the instructions from line i up to the closing brace (or the end): (next line, detector shift)
        while i < len(lines):
            s = lines[i].split('#', 1)[0].strip()
            i += 1
            if not s:
                continue
            if s.startswith('}'):
                return i, shift
            if s.startswith('repeat'):
                count = int(s.split()[1])
                body, end = i, i
                for _ in range(count):
                    end, shift = block(body, shift)
                if count <= 0:  # skip the body
                    depth = 1
                    while end < len(lines) and depth > 0:
                        t = lines[end].split('#', 1)[0].strip()
                        end += 1
                        depth += t.startswith('repeat') - t.startswith('}')
                i = end
            elif s.startswith('shift_detectors'):
                shift += int(s.rsplit(None, 1)[-1])
            elif s.startswith('error'):
                p_text = s[s.index('(') + 1:s.index(')')].strip()
                if float(p_text) < pmin:
                    continue
                dets: Set[int] = set()
                obs: Set[int] = set()
                for tok in s[s.index(')') + 1:].split():
                    if tok[0] == 'D':
                        dets ^= {int(tok[1:]) + shift}
                    elif tok[0] == 'L':
                        obs ^= {int(tok[1:])}
                col = (frozenset(dets), frozenset(obs))
                cols.append(col + (p_text,) if with_prob else col)
        return i, shift
 
    block(0, 0)
    return cols
 
 
def _drop_mode(drop: Any) -> str:
    """
    The drop option of compute_dem_distance(): "auto" (for None, True, 1, "1", or "auto"), "0" (False, 0, or "0"),
    "css", or the name of an existing file (ValueError otherwise).
    """
    if drop is None or drop is True:
        return "auto"
    if drop is False:
        return "0"
    if isinstance(drop, numbers.Integral):
        if drop in (0, 1):
            return "auto" if drop == 1 else "0"
        raise ValueError(f"invalid drop={drop}: use 0, 1, 'auto', 'css', or a file with the detectors to drop")
    s = str(drop).strip()
    if s.lower() in ("1", "auto"):
        return "auto"
    if s == "0":
        return "0"
    if s.lower() == "css":
        return "css"
    if not os.path.isfile(s):
        raise ValueError(f"drop={s}: no such file (use 0, 1, auto, css, or a file with the detectors to drop)")
    return s
 
 
def _reduced_out_prefix(spec: Union[bool, str, Path], src: str, out_dir: Optional[Union[str, Path]] = None) -> str:
    """
    The prefix PREFIX of the files PREFIX_red.dem and PREFIX_red.json of compute_dem_distance(out_reduced=spec) for the
    input src (a file name, or e.g. 'stim.Circuit'): for True (also '', '1', 'true', 'yes', 'auto'), the basename of
    the input file (without a suffix _full or _simp; 'dem' for an object); a bare name goes to out_dir (default: the
    directory of the input file, as for --out-dem), and a path is used as given.
    """
    src_path = Path(src) if os.path.exists(src) else None
    eff_dir = Path(out_dir) if out_dir is not None else (src_path.parent if src_path is not None else Path("."))
    if spec is True or (isinstance(spec, str) and spec.strip().lower() in ("", "1", "true", "yes", "auto")):
        stem = src_path.stem if src_path is not None else "dem"
        if stem.endswith(("_full", "_simp")):
            stem = stem[:-5]
        return str(eff_dir / stem)
    spec_s = str(spec)
    return str(eff_dir / spec_s) if (not os.path.isabs(spec_s) and os.path.dirname(spec_s) == "") else spec_s
 
 
def read_drop_file(path: Union[str, Path]) -> Tuple[List[int], Optional[int]]:
    """
    Reads a drop file: the 0-based detector indices (k for Dk) separated by white space or commas, where lines starting
    with '#' or '%' are comments, e.g., the detectors dropped from a DEM written by the binary (outD=FILE).
 
    Returns:
        (detectors, num_detectors): the sorted distinct detectors, and the number of detectors of the DEM from the
        comment line '# N of M detectors dropped ...' written by the binary (None if there is none).
    """
    import re
    dets: Set[int] = set()
    num: Optional[int] = None
    with open(str(path)) as f:
        for line in f:
            s = line.strip()
            if s.startswith('#') or s.startswith('%'):
                mm = re.match(r"#\s*\d+ of (\d+) detectors dropped", s)
                if mm and num is None:
                    num = int(mm.group(1))
                continue
            dets.update(int(tok) for tok in s.replace(',', ' ').split())
    return sorted(dets), num
 
 
def write_reduced_dem(
    dem: Any,
    dropped: Sequence[int],
    prefix: Union[str, Path],
    pmin: float = 0.0,
    num_detectors: Optional[int] = None,
    meta: Optional[Dict[str, Any]] = None
) -> Tuple[str, str]:
    """
    Writes the DEM (a stim.DetectorErrorModel or a .dem file) without the detectors `dropped` (0-based, e.g., those
    dropped by the binary, see compute_dem_distance(outD=..., out_reduced=...)) to PREFIX_red.dem: the errors which
    touch none of them (after the cutoff pmin, in the order of the flattened DEM; a decomposed error as the sum of its
    components), with the other detectors numbered consecutively, and the observables unchanged.  The maps go to
    PREFIX_red.json: "detectors" (the original index of each detector of the reduced DEM, i.e., the complement of
    "dropped"), "errors" (the original index of each error of the reduced DEM, 0-based in the order of the flattened DEM
    after the cutoff pmin, as the columns of the codewords in outC), "dropped", "num_detectors", "num_errors", "pmin",
    and the entries of meta.  If dropping the detectors is exact (as verified by the binary), the reduced DEM has the
    same distance, and its codewords map to codewords of the DEM with "errors".
 
    Returns:
        (dem_path, json_path): the files written.
    """
    cols = _dem_error_columns(dem, pmin, with_prob=True)
    drop_set = set(int(r) for r in dropped)
    m = 1 + max([d for S, _, _ in cols for d in S] + list(drop_set), default=-1)
    if num_detectors is not None:
        m = max(m, int(num_detectors))
    k = 1 + max((o for _, O, _ in cols for o in O), default=-1)
    kept = [r for r in range(m) if r not in drop_set]
    new_index = {r: i for i, r in enumerate(kept)}
    dem_path, json_path = f"{prefix}_red.dem", f"{prefix}_red.json"
    errors: List[int] = []
    lines = [f"# reduced DEM: {len(drop_set)} of {m} detectors dropped (dist_m4ri.py {__version__}); the maps to the "
             f"original DEM are in {os.path.basename(json_path)}"]
    max_det = max_obs = -1
    for j, (S, O, p) in enumerate(cols):
        if S & drop_set:
            continue
        dets = sorted(new_index[d] for d in S)
        obs = sorted(O)
        if dets:
            max_det = max(max_det, dets[-1])
        if obs:
            max_obs = max(max_obs, obs[-1])
        lines.append(f"error({p})" + "".join(f" D{d}" for d in dets) + "".join(f" L{o}" for o in obs))
        errors.append(j)
    if max_det < len(kept) - 1:  # (keeps the number of detectors and observables)
        lines.append(f"detector D{len(kept) - 1}")
    if max_obs < k - 1:
        lines.append(f"logical_observable L{k - 1}")
    parent_dir = os.path.dirname(os.path.abspath(dem_path))
    os.makedirs(parent_dir, exist_ok=True)
    with open(dem_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    info: Dict[str, Any] = {"__version__": __version__}
    info.update(meta or {})
    info.update({"pmin": pmin, "num_detectors": m, "num_errors": len(cols), "dropped": sorted(drop_set),
                 "detectors": kept, "errors": errors})
    with open(json_path, "w") as f:
        json.dump(info, f, separators=(",", ":"))
        f.write("\n")
    return dem_path, json_path
 
 
def _expand_equal_columns(
    cws: List[List[int]],
    dem: Any,
    pmin: float = 0.0,
    maxC: int = 0,
    verbose: bool = False
) -> List[List[int]]:
    """
    The expanded list of the DEM codewords cws (0-based columns of the DEM, see _dem_error_columns()): every version
    over the choices among equal columns (the same detectors and observables), which the binary merges (merge=1).
    Each codeword is mapped to the first columns of its sets of equal columns (two equal columns cancel), and every
    distinct result c is expanded into the prod_{j in c} |set(j)| codewords with one column from each set (sorted, in
    the order of cws).  With maxC > 0, at most maxC codewords are returned, with a warning to stderr if some are
    dropped.
    """
    if not cws:
        return []
    cols = _dem_error_columns(dem, pmin)
    sets: Dict[Tuple[frozenset, frozenset], List[int]] = {}
    for j, c in enumerate(cols):
        sets.setdefault(c, []).append(j)
    members = [sets[c] for c in cols]  # the sorted set of the columns equal to column j (j included)
    keys: List[Tuple[int, ...]] = []
    seen: Set[Tuple[int, ...]] = set()
    for cw in cws:
        if any(j < 0 or j >= len(members) for j in cw):
            raise ValueError(f"expand: codeword column out of range (the DEM has {len(members)} columns after the "
                             f"pmin={pmin} cutoff)")
        odd: Set[int] = set()
        for j in cw:
            odd ^= {members[j][0]}
        key = tuple(sorted(odd))
        if key and key not in seen:
            seen.add(key)
            keys.append(key)
    total = 0
    for key in keys:
        num = 1
        for r in key:
            num *= len(members[r])
        total += num
    limit = total if maxC <= 0 else min(total, maxC)
    out: List[List[int]] = []
    for key in keys:
        if len(out) >= limit:
            break
        for choice in itertools.product(*(members[r] for r in key)):
            out.append(sorted(choice))
            if len(out) >= limit:
                break
    if limit < total:
        sys.stderr.write(f"# Warning: expand: the expanded list has {total} codewords ({len(keys)} up to equal "
                         f"columns); only the first maxC={maxC} are written (the list is incomplete)\n")
    elif verbose:
        print(f"[dist_m4ri] expand: {len(keys)} codewords up to equal columns -> {total} codewords")
    return out
 
 
def _css_sector_codes(Hx: Any, Hz: Any, Lx: Optional[Any], Lz: Optional[Any]) -> Dict[str, Tuple[Any, Any, Any]]:
    """The quantum codes (H, G, L) of the two sectors of a CSS code: Z -> (Hx, Hz or Lx), X -> (Hz, Hx or Lz)."""
    return {
        "Z": (Hx, Hz if Lx is None else None, Lx),
        "X": (Hz, Hx if Lz is None else None, Lz),
    }
 
 
def _css_combine(
    x: Tuple[int, int, int], z: Tuple[int, int, int], dmax: int = 0
) -> Tuple[int, int, int, int]:
    """
    Bounds of the CSS distance d = min(dX, dZ) from the sector bounds x, z = (dmin, dmax, rw_steps), and an upper
    bound `dmax` on d supplied by the user (0: none).
 
    Returns:
        (dist, dmin, dmax, rw_steps): dist is the smaller sector distance (see _dist_from_bounds(); the larger one if
        a sector distance is 0), at most the user's dmax; dmin = min(dmin_X, dmin_Z); dmax is the smallest of the
        positive upper bounds (0: none).
    """
    d_lo = min(x[0], z[0])
    uppers = [v for v in (x[1], z[1], dmax) if v > 0]
    d_hi = min(uppers) if uppers else 0
    if d_hi > 0 and d_lo > d_hi:
        d_lo = d_hi
    dist_x, dist_z = _dist_from_bounds(x[0], x[1]), _dist_from_bounds(z[0], z[1])
    dist = min(dist_x, dist_z) if (dist_x > 0 and dist_z > 0) else max(dist_x, dist_z)
    if dmax > 0 and dist > dmax:
        dist = dmax
    if d_lo > 0 and d_lo == d_hi:
        dist = d_lo
    return dist, d_lo, d_hi, x[2] + z[2]
 
 
def _sector_record(dmin: int, dmax: int, rw_steps: int, cws: List[List[int]]) -> Dict[str, Any]:
    """A cache record of a classical or quantum code (or of a CSS sector) with the bounds [dmin, dmax]."""
    if dmax > 0 and dmin > dmax:
        dmin = dmax
    return {
        "dist": _dist_from_bounds(dmin, dmax),
        "dmin": dmin,
        "dmax": dmax,
        "rw_steps": rw_steps,
        "d_info": format_bounds_list(dmin, dmax, rw_steps),
        "cws": cws,
    }
 
 
def _migrate_css_records(
    Hx: Any, Hz: Any, Lx: Optional[Any] = None, Lz: Optional[Any] = None, eff_cache_file: Optional[str] = None
) -> bool:
    """
    Converts the CSS cache records written before version 0.12.0 (key 'css:X=<Hx>:Z=<Hz>[:Lx=<Lx>:Lz=<Lz>]', also
    with a ':start=...' suffix) into the records of the two sectors (see _matrix_cache_key()), and removes them.
 
    The lower bounds dmin_X and dmin_Z are kept.  An upper bound dmax_X or dmax_Z is kept only if a stored codeword
    confirms it, or if it is smaller than the upper bound of the other sector: earlier versions passed an upper bound
    dmax given to compute_css_distance() (a bound on min(dX, dZ)) to both sectors, where it was reported back as the
    upper bound of the sector, which is not valid for the sector with the larger distance.  Otherwise, the weight of
    the lightest stored codeword (if any) is used.
 
    Returns:
        True if a record was converted (the cache file, if any, is then saved).
    """
    global _distance_cache
    old = f"css:X={get_sparse_array_state(Hx)}:Z={get_sparse_array_state(Hz)}"
    if Lx is not None or Lz is not None:
        old = f"{old}:Lx={get_sparse_array_state(Lx)}:Lz={get_sparse_array_state(Lz)}"
    old_keys = [k for k in list(_distance_cache) if k == old or k.startswith(old + ":start=")]
    if not old_keys:
        return False
    codes = _css_sector_codes(Hx, Hz, Lx, Lz)
    base = {s: _matrix_cache_key(*codes[s]) for s in ("X", "Z")}
    for key in old_keys:
        rec = _distance_cache.pop(key)
        if not isinstance(rec, dict):
            continue
        sfx = key[len(old):]
        for s, other in (("X", "Z"), ("Z", "X")):
            dmin = int(rec.get(f"dmin_{s}", rec.get("dmin", 0)) or 0)
            dmax = int(rec.get(f"dmax_{s}", 0) or 0)
            other_dmax = int(rec.get(f"dmax_{other}", 0) or 0)
            cws = [list(cw) for cw in (rec.get(f"cws_{s}") or [])]
            w_cw = min((len(cw) for cw in cws), default=0)
            if dmax > 0 and w_cw != dmax and not (dmax < other_dmax):
                dmax = 0  # possibly the upper bound on min(dX, dZ) reported back by the binary
            if w_cw > 0:
                dmax = min(dmax, w_cw) if dmax > 0 else w_cw
            rw = int(rec.get(f"rw_steps_{s}", 0) or 0)
            skey = base[s] + sfx
            prev = _distance_cache.get(skey)
            if prev:
                p_dmax = prev.get("dmax", 0) or 0
                dmax = min(p_dmax, dmax) if (p_dmax > 0 and dmax > 0) else max(p_dmax, dmax)
                dmin = max(prev.get("dmin", 0) or 0, dmin)
                rw = max(prev.get("rw_steps", 0) or 0, rw)
                cws = _union_cws(prev.get("cws", []), cws)
            _distance_cache[skey] = _sector_record(dmin, dmax, rw, cws)
    if eff_cache_file:
        save_distance_cache(eff_cache_file)
    return True
 
 
def _cached_code_distance(
    H: Any,
    G: Optional[Any],
    L: Optional[Any],
    classical: bool,
    kind: str,
    dist_m4ri: Optional[str],
    method: int,
    threads: Optional[int],
    timeout: float,
    num_steps: Optional[int],
    d_exp: int,
    dmin: int,
    dmax: int,
    dstop: int,
    wmin: int,
    wmax: int,
    smax: Optional[int],
    start_list: Optional[List[int]],
    dW: int,
    maxC: int,
    finC: Optional[str],
    outC: Optional[str],
    need_cws: bool,
    eff_cache_file: Optional[str],
    seed: int,
    debug: int,
    verbose: bool,
    nothrottle: bool,
    chunk_size: int,
    ksub: int,
    kwin: int,
    win_mode: int,
    min_hits: Optional[int],
    cov_cws: int,
    refresh: Optional[int],
    trust_start: bool,
    fdem: Optional[Any] = None,
    pmin: float = 0.0,
    merge: bool = True,
    key_fn: Optional[Callable[[], str]] = None,
    cws_out_fn: Optional[Callable[[List[List[int]]], List[List[int]]]] = None,
    fdrop: Optional[Union[str, Path, List[int]]] = None,
    outD: Optional[str] = None,
    sort_rows: Optional[bool] = None,
    win_hyb: int = 0,
    pairs: int = -1,
    cc_prune: Optional[int] = None,
    ortho: bool = True
) -> Dict[str, Any]:
    """
    Distance of a classical code (H), of a quantum code (H with G or L), or of a DEM (fdem: a stim DEM object or a .dem
    file, with the probability cutoff pmin, merge, the detectors to drop fdrop ("auto", "0", a file, or a list), and
    the file outD for the detectors dropped: see run_dist_m4ri()) with the dist_m4ri binary, using the distance cache
    shared by compute_classical_distance(), compute_quantum_distance(), the two sectors of compute_css_distance(), and
    compute_dem_distance() (the warnings for the expert options are issued by the callers).  The row order sort_rows
    and the CC search cc_prune (see run_dist_m4ri()) do not change the result, nor the cache key; nor do the RW window
    size win_hyb, the RW pairs (pairs), and the expert option ortho (False: the binary does not check H G^T = 0) change
    the cache key.
 
    A cache record (key: key_fn() if given, otherwise see _matrix_cache_key()) answers the request if it holds the
    exact distance, or with the stop target dstop > 0 a lower bound dmin >= dstop (and the codewords, if needed).
    Otherwise, the binary is run, starting from the cached bounds, and the merged bounds are stored.  The returned
    codewords (those of the run merged with the cached ones, or the cached ones) are written to outC; with finC
    identical to outC, the codewords already in the file are kept.  If given, cws_out_fn transforms the codewords
    returned and written to outC (e.g., the expansion over equal DEM columns, see _expand_equal_columns()); the cache
    keeps the codewords as found.
 
    Returns:
        dict with the distance "dist" (see _dist_from_bounds()), the bounds "dmin", "dmax", "rw_steps", "d_info"
        (see format_bounds_list()), the codewords "cws" (empty unless need_cws), and "cached" (True if no binary run).
    """
    global _distance_cache, _last_run_stats
    _last_run_stats = {}  # the statistics of the binary run (none if the result is cached)
    same_file = bool(finC and outC) and os.path.abspath(str(finC)) == os.path.abspath(str(outC))
    finC = check_finc_outc(finC, outC, verbose=verbose)
 
    def write_out(cws_res: List[List[int]]) -> List[List[int]]:
        # the codewords returned (transformed by cws_out_fn) and written to outC; with finC identical to outC, the
        # codewords already in the file are kept
        if cws_out_fn is not None and cws_res:
            cws_res = cws_out_fn(cws_res)
        if outC and cws_res:
            out = cws_res
            if same_file and os.path.isfile(outC):
                out = _union_cws(read_sparse_vectors(outC), cws_res)
            _write_nzlist_file(outC, out)
        return cws_res
 
    code_key = cached_entry = plain_key = plain_entry = None
    hit: Optional[Dict[str, Any]] = None  # the result of a cache hit
    eff_dmin, eff_dmax = dmin, dmax
    if _use_distance_cache:
        if eff_cache_file:
            load_distance_cache(eff_cache_file)
        try:
            plain_key = key_fn() if key_fn is not None else _matrix_cache_key(H, G, L, classical)
            code_key, cached_entry, plain_entry = _resolve_start_cache(
                plain_key, start_list, lambda e: _single_entry_is_exact(e, need_cws, dstop), trust_start,
                lambda e: _merge_start_into_plain(plain_key, e, True), eff_cache_file, verbose
            )
            eff_dmin, eff_dmax = _seed_bounds_from_entry(eff_dmin, eff_dmax, plain_entry)
            if cached_entry is not None:
                c_dmin, c_dmax = cached_entry.get("dmin", 0) or 0, cached_entry.get("dmax", 0) or 0
                if _single_entry_is_exact(cached_entry, need_cws, dstop):
                    c_rw = cached_entry.get("rw_steps", 0) or 0
                    d_info = format_bounds_list(c_dmin, c_dmax, c_rw)
                    found = "exact distance" if (c_dmin > 0 and c_dmin == c_dmax) else f"dmin={c_dmin} >= dstop={dstop}"
                    if verbose:
                        print(f"[dist_m4ri] Cache retrieval: SUCCESS (found cached {found} for '{code_key}')")
                        print(f"[dist_m4ri] Cached result: dist={_dist_from_bounds(c_dmin, c_dmax)}, "
                              f"bounds={format_bounds_str(d_info)}")
                    elif debug & PY_DBG_CACHE:
                        print(f"[dist_m4ri] Cache hit for {kind} distance ({found} known)!")
                    cws_res = [list(cw) for cw in cached_entry.get("cws", [])] if need_cws else []
                    hit = {"dist": _dist_from_bounds(c_dmin, c_dmax), "dmin": c_dmin, "dmax": c_dmax,
                           "rw_steps": c_rw, "d_info": d_info, "cws": cws_res, "cached": True}
                else:
                    if verbose:
                        print(f"[dist_m4ri] Cache retrieval: PARTIAL (cached bounds: dmin={c_dmin}, dmax={c_dmax}, "
                              f"rw_steps={cached_entry.get('rw_steps', 0)}; continuing search)")
                    eff_dmin, eff_dmax = _seed_bounds_from_entry(eff_dmin, eff_dmax, cached_entry)
            elif verbose:
                print(f"[dist_m4ri] Cache retrieval: MISS (no entry for '{code_key}')")
        except Exception:
            code_key = cached_entry = plain_key = plain_entry = hit = None
    elif verbose:
        print("[dist_m4ri] Cache retrieval: DISABLED (cache is turned off)")
    if hit is not None:
        hit["cws"] = write_out(hit["cws"])
        return hit
 
    if wmax > 0 and eff_dmin > max(wmax, dmin):  # a cached lower bound beyond wmax (the binary needs dmin <= wmax)
        src = cached_entry or plain_entry
        if not (method & 1) and src is not None:  # CC only: all weights up to wmax have been analyzed already
            c_dmin, c_dmax, c_rw = src.get("dmin", 0) or 0, src.get("dmax", 0) or 0, src.get("rw_steps", 0) or 0
            if verbose:
                print(f"[dist_m4ri] Cached lower bound dmin={c_dmin} > wmax={wmax}: no CC round needed")
            cws_res = write_out([list(cw) for cw in src.get("cws", [])] if need_cws else [])
            return {"dist": _dist_from_bounds(c_dmin, c_dmax), "dmin": c_dmin, "dmax": c_dmax, "rw_steps": c_rw,
                    "d_info": format_bounds_list(c_dmin, c_dmax, c_rw), "cws": cws_res, "cached": True}
        eff_dmin = max(wmax, dmin)
 
    temp_files: List[str] = []
    try:
        def input_file(M: Any, ext: str) -> Optional[str]:
            if M is None:
                return None
            if isinstance(M, (str, Path)) and os.path.exists(str(M)):
                return str(M)
            path = _matrix_to_file(M, extension=ext)
            temp_files.append(path)
            return path
 
        file_dem = None
        if fdem is not None:  # a DEM: the file, or the object written to a temporary file
            if isinstance(fdem, (str, Path)) and os.path.exists(str(fdem)):
                file_dem = str(fdem)
            else:
                file_dem = create_unique_file(extension=".dem")
                temp_files.append(file_dem)
                _write_dem_file(fdem, file_dem)
        file_H, file_G, file_L = input_file(H, "_H.mtx"), input_file(G, "_G.mtx"), input_file(L, "_L.mtx")
        file_drop = None
        if fdem is not None and fdrop is not None:  # the detectors to drop: the file, or the list written to a file
            if isinstance(fdrop, (str, Path)):
                file_drop = str(fdrop)
            elif len(fdrop) > 0:
                file_drop = create_unique_file(extension="_drop.txt")
                temp_files.append(file_drop)
                with open(file_drop, "w") as f:
                    f.write(" ".join(str(r) for r in fdrop) + "\n")
        outC_file = None
        if need_cws:
            outC_file = create_unique_file(extension="_cws.nz")
            temp_files.append(outC_file)
 
        dmin_res, dmax_res, rw_steps = run_dist_m4ri(
            dist_m4ri_path=dist_m4ri,
            method=method,
            finH=file_H,
            finG=file_G,
            finL=file_L,
            fdem=file_dem,
            finC=finC,
            classical=-1 if fdem is not None else (1 if classical else 0),
            dmin=eff_dmin,
            dmax=eff_dmax,
            dstop=dstop,
            wmin=wmin,
            wmax=wmax,
            smax=smax,
            start=start_list,
            start_scan=bool(getattr(start_list, "scan", False)),
            warn_start=False,
            warn_ksub=False,
            ortho=ortho,
            warn_ortho=False,
            dexp=d_exp,
            steps=num_steps,
            threads=threads,
            timeout=timeout,
            pmin=pmin,
            merge=merge,
            drop=file_drop,
            outD=outD if fdem is not None else None,
            sort_rows=sort_rows,
            cc_prune=cc_prune,
            dW=dW,
            maxC=maxC,
            outC=outC_file,
            seed=seed,
            debug=debug,
            nothrottle=nothrottle,
            chunk_size=chunk_size,
            ksub=ksub,
            kwin=kwin,
            win_mode=win_mode,
            win_hyb=win_hyb,
            pairs=pairs,
            min_hits=min_hits,
            cov_cws=cov_cws,
            refresh=refresh,
            verbose=verbose
        )
 
        cws: List[List[int]] = []
        if need_cws and outC_file and os.path.exists(outC_file):
            cws = read_sparse_vectors(outC_file)
            cws.sort(key=len)
 
        if _use_distance_cache and code_key is not None:
            prev = cached_entry or {}
            p_dmax = prev.get("dmax", 0) or 0
            best_dmax = min(p_dmax, dmax_res) if (p_dmax > 0 and dmax_res > 0) else max(p_dmax, dmax_res)
            best_dmin = max(prev.get("dmin", 0) or 0, dmin_res)
            total_rw = (prev.get("rw_steps", 0) or 0) + rw_steps
            record = _sector_record(best_dmin, best_dmax, total_rw, _union_cws(prev.get("cws", []), cws))
            if "dmin_model" in prev:  # (a bound from the code-sized model, see compute_model_lower_bound())
                record["dmin_model"] = prev["dmin_model"]
            _distance_cache[code_key] = record
            if plain_key is not None and code_key != plain_key:
                # start-list run: merge the valid part (or all, with trust_start) into the main record
                _merge_start_into_plain(plain_key, record, trust_start, {"": rw_steps})
            if eff_cache_file:
                save_distance_cache(eff_cache_file)
            res = {"dist": record["dist"], "dmin": record["dmin"], "dmax": record["dmax"], "rw_steps": total_rw,
                   "d_info": record["d_info"], "cws": record["cws"] if need_cws else [], "cached": False}
        else:
            res = {"dist": _dist_from_bounds(dmin_res, dmax_res), "dmin": dmin_res, "dmax": dmax_res,
                   "rw_steps": rw_steps, "d_info": format_bounds_list(dmin_res, dmax_res, rw_steps), "cws": cws,
                   "cached": False}
        res["cws"] = write_out(res["cws"])
        return res
    finally:
        _remove_temp_files(temp_files, debug)
 
 
def compute_classical_distance(
    H: Any,
    dist_m4ri: Optional[str] = None,
    method: int = 3,
    threads: Optional[int] = None,
    timeout: float = 60.0,
    num_steps: Optional[int] = None,
    d_exp: int = 0,
    d_min: int = 0,
    d_max: int = 0,
    dmin: int = 0,
    dmax: int = 0,
    dstop: int = 0,
    wmin: int = 1,
    wmax: int = 0,
    smax: Optional[int] = None,
    start: Optional[Union[int, str, Sequence[int]]] = None,
    cbeg: Optional[int] = None,
    cend: Optional[int] = None,
    noscan: int = 0,
    dW: int = -1,
    maxC: int = 0,
    finC: Optional[str] = None,
    outC: Optional[str] = None,
    do_cws: bool = False,
    return_info: bool = False,
    cache_file: Optional[Union[str, Path]] = None,
    solver: str = "dist_m4ri",
    codedistance_method: str = "QDistEvol",
    codedistance_params: Optional[Dict[str, Any]] = None,
    seed: int = 0,
    debug: int = 0,
    verbose: bool = False,
    nothrottle: bool = False,
    chunk_size: int = 0,
    ksub: int = 0,
    kwin: int = 0,
    win_mode: int = 0,
    win_hyb: int = 0,
    pairs: int = -1,
    min_hits: Optional[int] = None,
    cov_cws: int = 100,
    refresh: Optional[int] = None,
    trust_start: bool = False,
    start_scan: bool = False,
    sort_rows: Optional[bool] = None,
    cc_prune: Optional[int] = None,
    engine: Optional[str] = None,
    **kwargs
) -> Any:
    """
    Computes the minimum distance of a classical linear code given parity check matrix H.
 
    Args:
        H: Parity check matrix (numpy array, scipy sparse matrix, or file path).
        dist_m4ri: Path to dist_m4ri executable (optional).
        method: Solver method (1=RW, 2=CC, 3=Bracketing default).
        threads: Maximum number of worker threads (default: all logical CPUs available; subject to throttling).
        timeout: Execution timeout in seconds (default: 60.0; 0: no limit).
        nothrottle: If True, the automatic thread throttling of the binary is disabled (default: False).
        chunk_size: Maximum RW batch claimed at once by a thread (default: 0: adaptive, 25-500 steps).
        num_steps: Maximum RW steps.
        min_hits: RW stops once the average number of hits per codeword reaches min_hits, both for the codewords of
            the minimum weight found and for a representative set of cov_cws lowest-weight codewords (see
            run_dist_m4ri()); passed if not None and >= 0 (None, the default: the binary's 5; 0: off, and then the
            repeated hits are not counted, unless codewords are collected with do_cws, outC, or maxC).
        cov_cws: Size of the representative set of lowest-weight codewords for min_hits (default: 100; 0: only the
            minimum weight).
        kwin / win_mode: A window of kwin columns in every RW step (alias: win; win_mode=0, the default: a Tanner
            graph ball, 1: an index window); kwin=0 (default): the automatic hybrid windows for n >= 500, see
            win_hyb and run_dist_m4ri(); kwin=-1: no windows (uniform random permutations in every step).
        refresh: RW steps between the basis refreshes of the experimental ksub RW (passed if not None; None,
            the default: the binary's 5000 with ksub > 0; 0: no refresh).
        d_exp: Expected distance estimate.
        d_min / dmin: Known lower bound on distance.
        d_max / dmax: Known upper bound on distance.
        dstop: Stop target for the lower bound (default: 0 = off): the search ends once CC has certified
            dmin >= dstop (method=2 or 3), unless a lighter codeword is found.  Unlike dmax, dstop is not an upper
            bound, and it is not reported as dmax: d_info = [dmin, w, rw_steps] with dmin >= dstop and the weight w
            of the lightest codeword found (0: none).  A cached lower bound dmin >= dstop answers the request without
            a calculation.
        wmin: Minimum distance of interest (terminate early if cw of weight <= wmin is found in RW or CC, default: 1).
        wmax: Maximum weight to search in CC.
        smax: Maximum syndrome weight for CC confinement profile.
        start: Expert option: list of CC start columns (int, comma-separated string "a,b,c", or
            sequence of ints; None or -1: all columns).  CC clusters are grown only from the listed
            columns, and they are not limited to larger column indices.  WARNING: the lower bound
            (and an exact result) is valid only if a code symmetry maps every minimum-weight codeword
            to one containing a listed column (e.g., one column per block of a quasi-cyclic code);
            the upper bound is always valid.  Results are cached under the separate key
            '<key>:start=a,b,c'; only dmax and codewords update the main cache record.
        trust_start: Expert option: accept the start-list results as valid, i.e., also merge dmin and
            rw_steps into the main cache record, and copy an existing exact start-list record to the
            main record even if no calculation is needed (default: False).
        start_scan: Expert option, with start (default: False): a cluster grown from a listed column c only
            uses the columns > c (see run_dist_m4ri()), e.g., start=[0, l] for the two blocks of a two-block
            group-algebra code over an abelian group; cached under the key suffix ':start=a,b,c:scan' (not for a
            DEM: ignored with a warning).
        cbeg / cend / noscan: Disabled in the Python interface: accepted for backward compatibility,
            but ignored with a warning to stderr (use the dist_m4ri binary directly).
        sort_rows: Row order of H in the binary (see run_dist_m4ri()): True sorts the rows by increasing weight
            (faster CC for very different row weights with cc_prune=0), False keeps their order, and None (default)
            leaves the binary's default (sorted for matrices; the detectors of a DEM are kept in time order).  The
            result and the cache key do not depend on it.
        cc_prune: The CC search of the binary (see run_dist_m4ri()): 0, the walk of the versions before 0.15.0; 1,
            the branch and bound (each codeword found once); 2, also the coverage and fractional cover bounds; None
            (default): the binary's default 1.  The result and the cache key do not depend on it.
        win_hyb: Window size of the automatic hybrid RW steps (kwin=0, n >= 500: a window on every other step; see
            run_dist_m4ri()); 0 (default): 256 columns for a DEM, 512 for matrices.  The cache key does not depend on
            it.
        pairs: The RW pairs of non-pivot columns (p=2, see run_dist_m4ri()): the number of random pivot rows of
            their buckets (0: off; -1, the default: auto).  The cache key does not depend on it.
        ksub: Experimental, should not be used (a warning is printed to stderr for ksub > 0 with method=1 or 3):
            subspace dimension sampled from ker(H) in RW (default: 0, full-matrix RW).
        dW: Extra weight window above dmin to collect codewords (only irreducible ones: not the union of a
            codeword and a disjoint nonzero vector with zero syndrome; the binary's default irred=1).
        maxC: Maximum number of codewords to collect.
        finC: Input file with initial codewords.
        outC: Output file to save codewords (NZLIST format).
        do_cws: Whether to return extracted codewords.
        return_info: If True, return (dist, d_info) or (dist, d_info, cws) where d_info is [dmin, dmax, num_rw].
        cache_file: Optional JSON file path for persistent distance caching.
        solver: "dist_m4ri" or "codedistance".
        codedistance_method: Method if using codedistance library.
        codedistance_params: Extra parameters for codedistance library.
        seed: Random seed.
        debug: Debug bitmap: the bits in BIN_DBG_MASK for the dist_m4ri binary, and the PY_DBG_* bits.
        verbose: Verbose reporting flag.
 
    Returns:
        dist or (dist, cws) if do_cws is True (or (dist, d_info) / (dist, d_info, cws) if return_info=True)
 
    Raises:
        TypeError: for an unknown keyword argument (e.g., a misspelled option).
        ValueError: for an invalid option value (e.g., start, or cc_prune other than 0, 1, or 2), for method=2 with
            timeout <= 0 but without wmax, dmax, or dstop, or for do_cws / outC with solver="codedistance".
        FileNotFoundError: if the dist_m4ri binary is not found (see find_dist_m4ri_binary()).
        RuntimeError: if the binary exits with an error (e.g., for a missing input file).
        ImportError: if solver="codedistance" but the codedistance package is not installed.
    """
    eff_dmin = dmin if dmin > 0 else d_min
    eff_dmax = dmax if dmax > 0 else d_max
    _check_kwargs(compute_classical_distance, kwargs)
    cert_mode = _resolve_cert_engine(solver, engine)
    start_list = _prepare_start_option(start, trust_start, noscan, cbeg, cend, solver, start_scan=start_scan)
    _warn_experimental_ksub(ksub, method, solver)
 
    if solver == "codedistance" or str(engine or "").strip().lower() == "codedistance":
        if do_cws or outC:
            raise ValueError("Codeword extraction is not supported with codedistance solver; use solver='dist_m4ri'.")
        _warn_codedistance_ignored(locals())
        codedistance = _get_codedistance()
        import numpy as np
        params = dict(codedistance_params or {})
        if num_steps is not None and "iterCount" not in params:
            params["iterCount"] = num_steps
 
        H_mat = H.toarray() if hasattr(H, 'toarray') else (
            np.asarray(H, dtype=np.int8) if isinstance(H, (np.ndarray, list)) else None
        )
        res = codedistance.codeDistance(
            H_mat, None, tB=1, method=codedistance_method, params=params,
            seed=seed if seed != 0 else None
        )
        d = res.get("d", -1)
        if return_info:
            d_info = format_bounds_list(d, d, 0) if d > 0 else [0, 0, 0]
            return d, d_info
        return d
 
    eff_cache_file = str(Path(cache_file).resolve()) if cache_file is not None else _distance_cache_file
    if _can_delegate_to_cert(
        cert_mode, method=method, do_cws=do_cws, outC=outC, finC=finC, smax=smax, dW=dW, maxC=maxC,
        start_list=start_list,
    ):
        _, qec_io, qec_pipeline = _get_qec_cert()
        mode_arg = "ub" if method == 1 else "auto"
        res = _cert_code_distance(
            lambda: _matrix_cache_key(H, None, None, True),
            lambda w_lo, w_hi: qec_pipeline.certify(
                qec_io.DistanceProblem(_cert_to_csr(H, qec_io), None, None),
                wmin=w_lo, wmax=w_hi, threads=threads or (os.cpu_count() or 8),
                seed=seed if seed != 0 else 1,
                time_limit=float(timeout) if timeout and timeout > 0 else 0.0,
                mode=mode_arg,
            ),
            label="classical", dmin=eff_dmin, dmax=eff_dmax, dstop=dstop, wmax=wmax,
            eff_cache_file=eff_cache_file, debug=debug, verbose=verbose,
        )
        dist, d_info = res["dist"], res["d_info"]
        return (dist, d_info) if return_info else dist
 
    # Solver is native multithreaded dist_m4ri (supports bounds caching and cumulative RW steps)
    res = _cached_code_distance(
        H, None, None, True, "classical", dist_m4ri=dist_m4ri, method=method, threads=threads, timeout=timeout,
        num_steps=num_steps, d_exp=d_exp, dmin=eff_dmin, dmax=eff_dmax, dstop=dstop, wmin=wmin, wmax=wmax,
        smax=smax, start_list=start_list, dW=dW, maxC=maxC, finC=finC, outC=outC, need_cws=bool(do_cws or outC),
        eff_cache_file=eff_cache_file, seed=seed, debug=debug, verbose=verbose, nothrottle=nothrottle,
        chunk_size=chunk_size, ksub=ksub, kwin=kwin if kwin != 0 else int(kwargs.get("win", 0) or 0),
        win_mode=win_mode, min_hits=min_hits, cov_cws=cov_cws, refresh=refresh, trust_start=trust_start,
        sort_rows=sort_rows, win_hyb=win_hyb, pairs=pairs, cc_prune=cc_prune
    )
    dist, d_info, cws = res["dist"], res["d_info"], res["cws"]
    if return_info:
        return (dist, d_info, cws) if do_cws else (dist, d_info)
    return (dist, cws) if do_cws else dist
 
 
def compute_quantum_distance(
    H: Any,
    G: Optional[Any] = None,
    L: Optional[Any] = None,
    dist_m4ri: Optional[str] = None,
    method: int = 3,
    threads: Optional[int] = None,
    timeout: float = 60.0,
    num_steps: Optional[int] = None,
    d_exp: int = 0,
    d_min: int = 0,
    d_max: int = 0,
    dmin: int = 0,
    dmax: int = 0,
    dstop: int = 0,
    wmin: int = 1,
    wmax: int = 0,
    smax: Optional[int] = None,
    start: Optional[Union[int, str, Sequence[int]]] = None,
    cbeg: Optional[int] = None,
    cend: Optional[int] = None,
    noscan: int = 0,
    dW: int = -1,
    maxC: int = 0,
    finC: Optional[str] = None,
    outC: Optional[str] = None,
    do_cws: bool = False,
    return_info: bool = False,
    cache_file: Optional[Union[str, Path]] = None,
    solver: str = "dist_m4ri",
    codedistance_method: str = "QDistEvol",
    codedistance_params: Optional[Dict[str, Any]] = None,
    seed: int = 0,
    debug: int = 0,
    verbose: bool = False,
    nothrottle: bool = False,
    chunk_size: int = 0,
    ksub: int = 0,
    kwin: int = 0,
    win_mode: int = 0,
    win_hyb: int = 0,
    pairs: int = -1,
    min_hits: Optional[int] = None,
    cov_cws: int = 100,
    refresh: Optional[int] = None,
    trust_start: bool = False,
    start_scan: bool = False,
    sort_rows: Optional[bool] = None,
    cc_prune: Optional[int] = None,
    ortho: bool = True,
    engine: Optional[str] = None,
    **kwargs
) -> Any:
    """
    Computes the minimum distance of a single-sided quantum code given parity check matrix H
    and degeneracy generator G (or logical operator matrix L).
 
    Args:
        H: Parity check matrix (numpy array, scipy sparse matrix, or file path).
        G: Degeneracy generator matrix (numpy array, scipy sparse matrix, or file path); the binary constructs the
            logical operators from H and G.  Either G or L is required, not both (ValueError).
        L: Logical operator matrix (numpy array, scipy sparse matrix, or file path), instead of G.
        ortho: Expert option (default: True; since version 0.15.2): False skips the check of the binary that the rows
            of H and G are orthogonal (H G^T = 0; True: an error otherwise), e.g., to screen many codes which are
            orthogonal by construction; a warning is printed to stderr, and the result is valid only if H G^T = 0.  No
            effect without G.  The cache key does not depend on it.
        dist_m4ri: Path to dist_m4ri executable (optional).
        method: Solver method (1=RW, 2=CC, 3=Bracketing default).
        threads: Maximum number of worker threads (default: all logical CPUs available; subject to throttling).
        timeout: Execution timeout in seconds (default: 60.0; 0: no limit).
        nothrottle: If True, the automatic thread throttling of the binary is disabled (default: False).
        chunk_size: Maximum RW batch claimed at once by a thread (default: 0: adaptive, 25-500 steps).
        num_steps: Maximum RW steps.
        min_hits: RW stops once the average number of hits per codeword reaches min_hits, both for the codewords of
            the minimum weight found and for a representative set of cov_cws lowest-weight codewords (see
            run_dist_m4ri()); passed if not None and >= 0 (None, the default: the binary's 5; 0: off, and then the
            repeated hits are not counted, unless codewords are collected with do_cws, outC, or maxC).
        cov_cws: Size of the representative set of lowest-weight codewords for min_hits (default: 100; 0: only the
            minimum weight).
        kwin / win_mode: A window of kwin columns in every RW step (alias: win; win_mode=0, the default: a Tanner
            graph ball, 1: an index window); kwin=0 (default): the automatic hybrid windows for n >= 500, see
            win_hyb and run_dist_m4ri(); kwin=-1: no windows (uniform random permutations in every step).
        refresh: RW steps between the basis refreshes of the experimental ksub RW (passed if not None; None,
            the default: the binary's 5000 with ksub > 0; 0: no refresh).
        d_exp: Expected distance estimate.
        d_min / dmin: Known lower bound on distance.
        d_max / dmax: Known upper bound on distance.
        dstop: Stop target for the lower bound (default: 0 = off): the search ends once CC has certified
            dmin >= dstop (method=2 or 3), unless a lighter codeword is found.  Unlike dmax, dstop is not an upper
            bound, and it is not reported as dmax: d_info = [dmin, w, rw_steps] with dmin >= dstop and the weight w
            of the lightest codeword found (0: none).  A cached lower bound dmin >= dstop answers the request without
            a calculation.
        wmin: Minimum distance of interest (terminate early if cw of weight <= wmin is found in RW or CC, default: 1).
        wmax: Maximum weight to search in CC.
        smax: Maximum syndrome weight for CC confinement profile.
        start: Expert option: list of CC start columns (int, comma-separated string "a,b,c", or
            sequence of ints; None or -1: all columns).  CC clusters are grown only from the listed
            columns, and they are not limited to larger column indices.  WARNING: the lower bound
            (and an exact result) is valid only if a code symmetry maps every minimum-weight codeword
            to one containing a listed column (e.g., one column per block of a quasi-cyclic code);
            the upper bound is always valid.  Results are cached under the separate key
            '<key>:start=a,b,c'; only dmax and codewords update the main cache record.
        trust_start: Expert option: accept the start-list results as valid, i.e., also merge dmin and
            rw_steps into the main cache record, and copy an existing exact start-list record to the
            main record even if no calculation is needed (default: False).
        start_scan: Expert option, with start (default: False): a cluster grown from a listed column c only
            uses the columns > c (see run_dist_m4ri()), e.g., start=[0, l] for the two blocks of a two-block
            group-algebra code over an abelian group; cached under the key suffix ':start=a,b,c:scan' (not for a
            DEM: ignored with a warning).
        cbeg / cend / noscan: Disabled in the Python interface: accepted for backward compatibility,
            but ignored with a warning to stderr (use the dist_m4ri binary directly).
        sort_rows: Row order of H in the binary (see run_dist_m4ri()): True sorts the rows by increasing weight
            (faster CC for very different row weights with cc_prune=0), False keeps their order, and None (default)
            leaves the binary's default (sorted for matrices; the detectors of a DEM are kept in time order).  The
            result and the cache key do not depend on it.
        cc_prune: The CC search of the binary (see run_dist_m4ri()): 0, the walk of the versions before 0.15.0; 1,
            the branch and bound (each codeword found once); 2, also the coverage and fractional cover bounds; None
            (default): the binary's default 1.  The result and the cache key do not depend on it.
        win_hyb: Window size of the automatic hybrid RW steps (kwin=0, n >= 500: a window on every other step; see
            run_dist_m4ri()); 0 (default): 256 columns for a DEM, 512 for matrices.  The cache key does not depend on
            it.
        pairs: The RW pairs of non-pivot columns (p=2, see run_dist_m4ri()): the number of random pivot rows of
            their buckets (0: off; -1, the default: auto).  The cache key does not depend on it.
        ksub: Experimental, should not be used (a warning is printed to stderr for ksub > 0 with method=1 or 3):
            subspace dimension sampled from ker(H) in RW (default: 0, full-matrix RW).
        dW: Extra weight window above dmin to collect codewords (only irreducible ones: not the union of a
            codeword and a disjoint nonzero vector with zero syndrome; the binary's default irred=1).
        maxC: Maximum number of codewords to collect.
        finC: Input file with initial codewords.
        outC: Output file to save codewords (NZLIST format).
        do_cws: Whether to return extracted codewords.
        return_info: If True, return (dist, d_info) or (dist, d_info, cws) where d_info is [dmin, dmax, num_rw].
        cache_file: Optional JSON file path for persistent distance caching.
        solver: "dist_m4ri" or "codedistance".
        codedistance_method: Method if using codedistance library.
        codedistance_params: Extra parameters for codedistance library.
        seed: Random seed.
        debug: Debug bitmap: the bits in BIN_DBG_MASK for the dist_m4ri binary, and the PY_DBG_* bits.
        verbose: Verbose reporting flag.
 
    Returns:
        dist or (dist, cws) if do_cws is True (or (dist, d_info) / (dist, d_info, cws) if return_info=True)
 
    Raises:
        TypeError: for an unknown keyword argument (e.g., a misspelled option).
        ValueError: if neither or both of G and L are given (or G is not given, with solver="codedistance"), for an
            invalid option value (e.g., start, or cc_prune other than 0, 1, or 2), for method=2 with timeout <= 0
            but without wmax, dmax, or dstop, or for do_cws / outC with solver="codedistance".
        FileNotFoundError: if the dist_m4ri binary is not found (see find_dist_m4ri_binary()).
        RuntimeError: if the binary exits with an error (e.g., for a missing input file, or with ortho=True for rows
            of H and G which are not orthogonal).
        ImportError: if solver="codedistance" but the codedistance package is not installed.
    """
    eff_dmin = dmin if dmin > 0 else d_min
    eff_dmax = dmax if dmax > 0 else d_max
    _check_kwargs(compute_quantum_distance, kwargs)
    cert_mode = _resolve_cert_engine(solver, engine)
    start_list = _prepare_start_option(start, trust_start, noscan, cbeg, cend, solver, start_scan=start_scan)
    _warn_experimental_ksub(ksub, method, solver)
 
    if G is None and L is None:
        raise ValueError(
            "Either G (dual generator matrix) or L (logical operator matrix) "
            "must be specified for quantum distance."
        )
    if G is not None and L is not None:
        raise ValueError("Either G or L should be specified for quantum distance, not both.")
    _warn_ortho(ortho, G is not None, solver)
 
    if solver == "codedistance" or str(engine or "").strip().lower() == "codedistance":
        if do_cws or outC:
            raise ValueError("Codeword extraction is not supported with codedistance solver; use solver='dist_m4ri'.")
        _warn_codedistance_ignored(locals())
        codedistance = _get_codedistance()
        import numpy as np
        params = dict(codedistance_params or {})
        if num_steps is not None and "iterCount" not in params:
            params["iterCount"] = num_steps
 
        H_mat = H.toarray() if hasattr(H, 'toarray') else (
            np.asarray(H, dtype=np.int8) if isinstance(H, (np.ndarray, list)) else None
        )
        if G is None and L is not None:
            raise ValueError(
                "The 'codedistance' solver requires the stabilizer generator matrix G, "
                "not the logical operator matrix L. Use solver='dist_m4ri' with L."
            )
        dual_mat = G if G is not None else L
        dual_arr = dual_mat.toarray() if hasattr(dual_mat, 'toarray') else (
            np.asarray(dual_mat, dtype=np.int8) if isinstance(dual_mat, (np.ndarray, list)) else None
        )
 
        res = codedistance.codeDistance(
            H_mat, dual_arr, tB=1, method=codedistance_method, params=params,
            seed=seed if seed != 0 else None
        )
        d = res.get("d", -1)
        if return_info:
            d_info = format_bounds_list(d, d, 0) if d > 0 else [0, 0, 0]
            return d, d_info
        return d
 
    eff_cache_file = str(Path(cache_file).resolve()) if cache_file is not None else _distance_cache_file
    if _can_delegate_to_cert(
        cert_mode, method=method, do_cws=do_cws, outC=outC, finC=finC, smax=smax, dW=dW, maxC=maxC,
        start_list=start_list,
    ):
        _, qec_io, qec_pipeline = _get_qec_cert()
        mode_arg = "ub" if method == 1 else "auto"
        res = _cert_code_distance(
            lambda: _matrix_cache_key(H, G, L, False),
            lambda w_lo, w_hi: qec_pipeline.certify(
                qec_io.DistanceProblem(
                    _cert_to_csr(H, qec_io), _cert_to_csr(L, qec_io), _cert_to_csr(G, qec_io)
                ),
                wmin=w_lo, wmax=w_hi, threads=threads or (os.cpu_count() or 8),
                seed=seed if seed != 0 else 1,
                time_limit=float(timeout) if timeout and timeout > 0 else 0.0,
                mode=mode_arg,
            ),
            label="quantum", dmin=eff_dmin, dmax=eff_dmax, dstop=dstop, wmax=wmax,
            eff_cache_file=eff_cache_file, debug=debug, verbose=verbose,
        )
        dist, d_info = res["dist"], res["d_info"]
        return (dist, d_info) if return_info else dist
 
    # Solver is native multithreaded dist_m4ri (the cache records are shared with the sectors of CSS codes)
    res = _cached_code_distance(
        H, G, L, False, "quantum", dist_m4ri=dist_m4ri, method=method, threads=threads, timeout=timeout,
        num_steps=num_steps, d_exp=d_exp, dmin=eff_dmin, dmax=eff_dmax, dstop=dstop, wmin=wmin, wmax=wmax,
        smax=smax, start_list=start_list, dW=dW, maxC=maxC, finC=finC, outC=outC, need_cws=bool(do_cws or outC),
        eff_cache_file=eff_cache_file, seed=seed, debug=debug, verbose=verbose, nothrottle=nothrottle,
        chunk_size=chunk_size, ksub=ksub, kwin=kwin if kwin != 0 else int(kwargs.get("win", 0) or 0),
        win_mode=win_mode, min_hits=min_hits, cov_cws=cov_cws, refresh=refresh, trust_start=trust_start,
        sort_rows=sort_rows, win_hyb=win_hyb, pairs=pairs, cc_prune=cc_prune, ortho=ortho
    )
    dist, d_info, cws = res["dist"], res["d_info"], res["cws"]
    if return_info:
        return (dist, d_info, cws) if do_cws else (dist, d_info)
    return (dist, cws) if do_cws else dist
 
 
def _split_css_filename(filepath: Optional[str], sector: str) -> Optional[str]:
    """Generates sector-suffixed filename for CSS codewords (e.g. 'cws.nz' -> 'cws_X.nz')."""
    if not filepath:
        return None
    base, ext = os.path.splitext(filepath)
    if not ext:
        ext = ".nz"
    if base.endswith(f"_{sector}"):
        return f"{base}{ext}"
    elif base.endswith("_X") or base.endswith("_Z"):
        base = base[:-2]
    return f"{base}_{sector}{ext}"
 
 
def _css_sector_finc(finC: Optional[str], outC: Optional[str]) -> Tuple[Optional[str], Optional[str]]:
    """
    Input codeword files (finC_X, finC_Z) of the two CSS sectors: the sector files (e.g. 'cws.nz' -> 'cws_X.nz' and
    'cws_Z.nz') which exist and are not empty; if there are none, finC itself for both sectors (codewords which are
    not valid in a sector are skipped by the binary), unless finC is identical to outC and does not exist or is
    empty (see check_finc_outc()).
    """
    if not finC:
        return None, None
    files = [_split_css_filename(finC, s) for s in ("X", "Z")]
    files = [f if (os.path.isfile(f) and os.path.getsize(f) > 0) else None for f in files]
    if files[0] or files[1]:
        return files[0], files[1]
    raw = check_finc_outc(finC, outC)
    return raw, raw
 
 
def compute_css_distance(
    Hx: Any,
    Hz: Any,
    Lx: Optional[Any] = None,
    Lz: Optional[Any] = None,
    dist_m4ri: Optional[str] = None,
    method: int = 3,
    threads: Optional[int] = None,
    timeout: float = 60.0,
    num_steps: Optional[int] = None,
    d_exp: int = 0,
    d_min: int = 0,
    d_max: int = 0,
    dmin: int = 0,
    dmax: int = 0,
    dstop: int = 0,
    wmin: int = 1,
    wmax: int = 0,
    smax: Optional[int] = None,
    start: Optional[Union[int, str, Sequence[int]]] = None,
    cbeg: Optional[int] = None,
    cend: Optional[int] = None,
    noscan: int = 0,
    dW: int = -1,
    maxC: int = 0,
    finC: Optional[str] = None,
    outC: Optional[str] = None,
    do_cws: bool = False,
    cache_file: Optional[Union[str, Path]] = None,
    solver: str = "dist_m4ri",
    codedistance_method: str = "QDistEvol",
    codedistance_params: Optional[Dict[str, Any]] = None,
    seed: int = 0,
    debug: int = 0,
    verbose: bool = False,
    nothrottle: bool = False,
    chunk_size: int = 0,
    ksub: int = 0,
    kwin: int = 0,
    win_mode: int = 0,
    win_hyb: int = 0,
    pairs: int = -1,
    min_hits: Optional[int] = None,
    cov_cws: int = 100,
    refresh: Optional[int] = None,
    trust_start: bool = False,
    start_scan: bool = False,
    sort_rows: Optional[bool] = None,
    cc_prune: Optional[int] = None,
    ortho: bool = True,
    engine: Optional[str] = None,
    **kwargs
) -> Tuple[Any, ...]:
    """
    Computes CSS quantum code distance d = min(d_X, d_Z).
 
    Args:
        Hx: X-stabilizer parity check matrix (required, at least one row).
        Hz: Z-stabilizer parity check matrix (required, at least one row).
        Lx: Optional X-logical operator matrix (alternative to Hz as finG).
        Lz: Optional Z-logical operator matrix (alternative to Hx as finG).
        ortho: Expert option (default: True; since version 0.15.2): False skips the checks of the binary that the
            rows of Hx and Hz are orthogonal (Hx Hz^T = 0, in each sector with G; True: an error otherwise), e.g., to
            screen many codes which are orthogonal by construction; a warning is printed to stderr, and the result is
            valid only if Hx Hz^T = 0.  No effect with both Lx and Lz.  The cache key does not depend on it.
        dist_m4ri: Path to dist_m4ri executable (optional).
        method: Solver method (1=RW, 2=CC, 3=Bracketing default).
        threads: Maximum number of worker threads (default: all logical CPUs available; subject to throttling).
        timeout: Execution timeout in seconds (default: 60.0; 0: no limit).
        nothrottle: If True, the automatic thread throttling of the binary is disabled (default: False).
        chunk_size: Maximum RW batch claimed at once by a thread (default: 0: adaptive, 25-500 steps).
        num_steps: Maximum RW steps.
        min_hits: RW stops once the average number of hits per codeword reaches min_hits, both for the codewords of
            the minimum weight found and for a representative set of cov_cws lowest-weight codewords (see
            run_dist_m4ri()); passed if not None and >= 0 (None, the default: the binary's 5; 0: off, and then the
            repeated hits are not counted, unless codewords are collected with do_cws, outC, or maxC).
        cov_cws: Size of the representative set of lowest-weight codewords for min_hits (default: 100; 0: only the
            minimum weight).
        kwin / win_mode: A window of kwin columns in every RW step (alias: win; win_mode=0, the default: a Tanner
            graph ball, 1: an index window); kwin=0 (default): the automatic hybrid windows for n >= 500, see
            win_hyb and run_dist_m4ri(); kwin=-1: no windows (uniform random permutations in every step).
        refresh: RW steps between the basis refreshes of the experimental ksub RW (passed if not None; None,
            the default: the binary's 5000 with ksub > 0; 0: no refresh).
        d_exp: Expected distance estimate.
        d_min / dmin: Known lower bound on d = min(dX, dZ), inclusive (a lower bound of both sectors).
        d_max / dmax: Known upper bound on d = min(dX, dZ), inclusive.  As it is not an upper bound of either
            sector, it is passed to both sector runs as the stop target dstop (each sector is needed only up to this
            weight), and it is not stored in the sector cache records; the returned d is at most dmax.
        dstop: Stop target for the lower bound of d (default: 0 = off): both sector runs end once CC has certified
            dmin >= dstop, unless a lighter codeword is found (see compute_classical_distance()).
        wmin: Minimum distance of interest (terminate early if cw of weight <= wmin is found in RW or CC, default: 1).
        wmax: Maximum weight to search in CC.
        smax: Maximum syndrome weight for CC confinement profile.
        start: Expert option: list of CC start columns (int, comma-separated string "a,b,c", or
            sequence of ints; None or -1: all columns).  CC clusters are grown only from the listed
            columns, and they are not limited to larger column indices.  WARNING: the lower bound
            (and an exact result) is valid only if a code symmetry maps every minimum-weight codeword
            to one containing a listed column (e.g., one column per block of a quasi-cyclic code);
            the upper bound is always valid.  Results are cached under the separate key
            '<key>:start=a,b,c'; only dmax and codewords update the main cache record.
        trust_start: Expert option: accept the start-list results as valid, i.e., also merge dmin and
            rw_steps into the main cache record, and copy an existing exact start-list record to the
            main record even if no calculation is needed (default: False).
        start_scan: Expert option, with start (default: False): a cluster grown from a listed column c only
            uses the columns > c (see run_dist_m4ri()), e.g., start=[0, l] for the two blocks of a two-block
            group-algebra code over an abelian group; cached under the key suffix ':start=a,b,c:scan' (not for a
            DEM: ignored with a warning).
        cbeg / cend / noscan: Disabled in the Python interface: accepted for backward compatibility,
            but ignored with a warning to stderr (use the dist_m4ri binary directly).
        sort_rows: Row order of H in the binary (see run_dist_m4ri()): True sorts the rows by increasing weight
            (faster CC for very different row weights with cc_prune=0), False keeps their order, and None (default)
            leaves the binary's default (sorted for matrices; the detectors of a DEM are kept in time order).  The
            result and the cache key do not depend on it.
        cc_prune: The CC search of the binary (see run_dist_m4ri()): 0, the walk of the versions before 0.15.0; 1,
            the branch and bound (each codeword found once); 2, also the coverage and fractional cover bounds; None
            (default): the binary's default 1.  The result and the cache key do not depend on it.
        win_hyb: Window size of the automatic hybrid RW steps (kwin=0, n >= 500: a window on every other step; see
            run_dist_m4ri()); 0 (default): 256 columns for a DEM, 512 for matrices.  The cache key does not depend on
            it.
        pairs: The RW pairs of non-pivot columns (p=2, see run_dist_m4ri()): the number of random pivot rows of
            their buckets (0: off; -1, the default: auto).  The cache key does not depend on it.
        ksub: Experimental, should not be used (a warning is printed to stderr for ksub > 0 with method=1 or 3):
            subspace dimension sampled from ker(H) in RW (default: 0, full-matrix RW).
        dW: Extra weight window above dmin to collect codewords (only irreducible ones: not the union of a
            codeword and a disjoint nonzero vector with zero syndrome; the binary's default irred=1).
        maxC: Maximum number of codewords to collect.
        finC: Input file with initial codewords.
        outC: Output file to save codewords (NZLIST format).
        do_cws: Whether to return extracted X and Z codewords.
        cache_file: Optional JSON file path for persistent distance caching.  The two sectors are cached as the
            quantum codes (H=Hx, G=Hz) -> dZ and (H=Hz, G=Hx) -> dX (with L=Lx / L=Lz if given), i.e., they share
            the records of compute_quantum_distance(); CSS records written before version 0.12.0 are converted.
        solver: "dist_m4ri" or "codedistance".
        codedistance_method: Method if using codedistance library.
        codedistance_params: Extra parameters for codedistance library.
        seed: Random seed.
        debug: Debug bitmap: the bits in BIN_DBG_MASK for the dist_m4ri binary, and the PY_DBG_* bits.
        verbose: Verbose reporting flag.
 
    Returns:
        tuple (dist, dX_info, dZ_info, cws_X, cws_Z) if do_cws
        else (dist, dX_info, dZ_info)
 
    Raises:
        ValueError: if Hx or Hz is missing or empty (use compute_quantum_distance() for one sector, or
            compute_classical_distance() for a classical code), for an invalid option value (e.g., start, or
            cc_prune other than 0, 1, or 2), for method=2 with timeout <= 0 but without wmax, dmax, or dstop, or
            for do_cws / outC with solver="codedistance".
        TypeError: for an unknown keyword argument (e.g., a misspelled option).
        FileNotFoundError: if the dist_m4ri binary is not found (see find_dist_m4ri_binary()).
        RuntimeError: if the binary exits with an error (e.g., for a missing input file, or with ortho=True for
            rows of Hx and Hz which are not orthogonal).
        ImportError: if solver="codedistance" but the codedistance package is not installed.
    """
    def _as_matrix(M: Any) -> Any:  # an array-like (e.g., a list of rows) as a NumPy array
        if M is None or isinstance(M, (str, Path)) or hasattr(M, 'shape'):
            return M
        import numpy as np
        return np.asarray(M)
 
    Hx, Hz, Lx, Lz = (_as_matrix(M) for M in (Hx, Hz, Lx, Lz))
 
    def _nonempty(M: Any) -> bool:
        return M is not None and (isinstance(M, (str, Path)) or (hasattr(M, 'shape') and M.shape[0] > 0))
 
    if not (_nonempty(Hx) and _nonempty(Hz)):
        raise ValueError(
            "compute_css_distance() requires both Hx and Hz (file names, or matrices with at least one row); "
            "use compute_quantum_distance() for one sector, or compute_classical_distance() for a classical code."
        )
 
    eff_dmin = dmin if dmin > 0 else d_min
    eff_dmax = dmax if dmax > 0 else d_max  # an upper bound on d = min(dX, dZ), not on either sector
    _check_kwargs(compute_css_distance, kwargs)
    cert_mode = _resolve_cert_engine(solver, engine)
    start_list = _prepare_start_option(start, trust_start, noscan, cbeg, cend, solver, start_scan=start_scan)
    _warn_experimental_ksub(ksub, method, solver)
    _warn_ortho(ortho, Lx is None or Lz is None, solver)  # (G of the sectors: Hz unless Lx, Hx unless Lz)
 
    if solver == "codedistance" or str(engine or "").strip().lower() == "codedistance":
        if do_cws or outC:
            raise ValueError("Codeword extraction is not supported with codedistance solver; use solver='dist_m4ri'.")
        _warn_codedistance_ignored(locals())
        codedistance = _get_codedistance()
        import numpy as np
        params = dict(codedistance_params or {})
        if num_steps is not None and "iterCount" not in params:
            params["iterCount"] = num_steps
 
        Hx_mat = Hx.toarray() if hasattr(Hx, 'toarray') else (
            np.asarray(Hx, dtype=np.int8) if isinstance(Hx, (np.ndarray, list)) else None
        )
        Hz_mat = Hz.toarray() if hasattr(Hz, 'toarray') else (
            np.asarray(Hz, dtype=np.int8) if isinstance(Hz, (np.ndarray, list)) else None
        )
        sector_d: Dict[str, int] = {}
        sector_info: Dict[str, List[int]] = {}
        for s in ("Z", "X"):
            res_s = codedistance.CSScodeDistance(
                Hx_mat, Hz_mat, method=codedistance_method, params=params.copy(),
                component=s, seed=seed if seed != 0 else None
            )
            sector_d[s] = res_s.get("d", -1)
            sector_info[s] = format_bounds_list(sector_d[s], sector_d[s], 0) if sector_d[s] > 0 else [0, 0, 0]
        d_z, d_x = sector_d["Z"], sector_d["X"]
        dist = min(d_z, d_x) if (d_z > 0 and d_x > 0) else max(d_z, d_x)
        return (dist, sector_info["X"], sector_info["Z"])
 
    # Solver is native multithreaded dist_m4ri: the two sectors are quantum codes, (H=Hx, G=Hz) -> dZ and
    # (H=Hz, G=Hx) -> dX (with L=Lx / L=Lz instead if given), with the same cache records as compute_quantum_distance().
    # A user dmax (a bound on min(dX, dZ)) is not an upper bound of either sector: it is passed as the stop target.
    eff_cache_file = str(Path(cache_file).resolve()) if cache_file is not None else _distance_cache_file
    stops = [v for v in (dstop, eff_dmax) if v > 0]
    sector_stop = min(stops) if stops else 0
    need_cws = bool(do_cws or outC)
 
    # Sector-specific input codewords: the files finC_X / finC_Z if they exist, otherwise finC itself
    finC_X, finC_Z = _css_sector_finc(finC, outC)
    if verbose and finC and not (finC_X or finC_Z):
        print(f"[dist_m4ri] Warning: finC='{finC}' (identical to outC) and its sector files are empty or "
              f"non-existent; silently ignoring input codewords.")
    if _use_distance_cache:
        if eff_cache_file:
            load_distance_cache(eff_cache_file)
        try:
            if _migrate_css_records(Hx, Hz, Lx, Lz, eff_cache_file) and verbose:
                print("[dist_m4ri] Converted the CSS cache records written before version 0.12.0 into sector records")
        except Exception:
            pass
 
    codes = _css_sector_codes(Hx, Hz, Lx, Lz)
    res: Dict[str, Dict[str, Any]] = {}
    for s, finC_s in (("Z", finC_Z), ("X", finC_X)):
        H_s, G_s, L_s = codes[s]
        if verbose:
            dual = ("Hx" if s == "X" else "Hz") if G_s is not None else ("Lz" if s == "X" else "Lx")
            print(f"[dist_m4ri] CSS sector d{s}: H={'Hz' if s == 'X' else 'Hx'} with "
                  f"{'G' if G_s is not None else 'L'}={dual}")
        if _can_delegate_to_cert(
            cert_mode, method=method, do_cws=do_cws, outC=outC, finC=finC_s, smax=smax,
            dW=dW, maxC=maxC, start_list=start_list,
        ):
            _, qec_io, qec_pipeline = _get_qec_cert()
            mode_arg = "ub" if method == 1 else "auto"
            res[s] = _cert_code_distance(
                lambda H_s=H_s, G_s=G_s, L_s=L_s: _matrix_cache_key(H_s, G_s, L_s, False),
                lambda w_lo, w_hi, H_s=H_s, G_s=G_s, L_s=L_s: qec_pipeline.certify(
                    qec_io.DistanceProblem(
                        _cert_to_csr(H_s, qec_io), _cert_to_csr(L_s, qec_io), _cert_to_csr(G_s, qec_io)
                    ),
                    wmin=w_lo, wmax=w_hi, threads=threads or (os.cpu_count() or 8),
                    seed=seed if seed != 0 else 1,
                    time_limit=float(timeout) if timeout and timeout > 0 else 0.0,
                    mode=mode_arg,
                ),
                label=f"CSS {s}-sector", dmin=eff_dmin, dmax=0, dstop=sector_stop, wmax=wmax,
                eff_cache_file=eff_cache_file, debug=debug, verbose=verbose,
            )
        else:
            res[s] = _cached_code_distance(
                H_s, G_s, L_s, False, f"CSS {s}-sector", dist_m4ri=dist_m4ri, method=method, threads=threads,
                timeout=timeout, num_steps=num_steps, d_exp=d_exp, dmin=eff_dmin, dmax=0, dstop=sector_stop, wmin=wmin,
                wmax=wmax, smax=smax, start_list=start_list, dW=dW, maxC=maxC, finC=finC_s,
                outC=_split_css_filename(outC, s) if outC else None, need_cws=need_cws, eff_cache_file=eff_cache_file,
                seed=seed, debug=debug, verbose=verbose, nothrottle=nothrottle, chunk_size=chunk_size, ksub=ksub,
                kwin=kwin if kwin != 0 else int(kwargs.get("win", 0) or 0), win_mode=win_mode, min_hits=min_hits,
                cov_cws=cov_cws, refresh=refresh, trust_start=trust_start, sort_rows=sort_rows, win_hyb=win_hyb,
                pairs=pairs, cc_prune=cc_prune, ortho=ortho
            )
        _last_css_stats[s] = dict(_last_run_stats)
 
    rx, rz = res["X"], res["Z"]
    dist, d_lo, d_hi, _ = _css_combine((rx["dmin"], rx["dmax"], rx["rw_steps"]),
                                       (rz["dmin"], rz["dmax"], rz["rw_steps"]), eff_dmax)
    if rx["cached"] and rz["cached"] and (debug & PY_DBG_CACHE) and not verbose:
        found = ("exact distance" if (d_lo > 0 and d_lo == d_hi) else
                 f"dmin={d_lo} >= dstop={sector_stop}" if (sector_stop > 0 and d_lo >= sector_stop) else
                 f"bounds dmin={d_lo}, dmax={d_hi}")
        print(f"[dist_m4ri] Cache hit for CSS distance ({found} known)!")
    if do_cws:
        return (dist, rx["d_info"], rz["d_info"], rx["cws"], rz["cws"])
    return (dist, rx["d_info"], rz["d_info"])
 
 
def _resolve_stim_dem_out_path(
    out_spec: Optional[Union[bool, str, Path]],
    circuit_src: str,
    mode_tag: str,
    ext: str,
    out_dir: Optional[Union[str, Path]] = None
) -> Optional[str]:
    """Resolves output filepath for --out-dem or --out-stim."""
    if out_spec is None or out_spec is False:
        return None
    if isinstance(out_spec, str) and out_spec.strip().lower() in (
        "0", "false", "no", "off", "none"
    ):
        return None
 
    src_path = (
        Path(circuit_src)
        if (circuit_src and circuit_src != "stim.Circuit")
        else None
    )
    eff_out_dir = (
        Path(out_dir)
        if out_dir is not None
        else (src_path.parent if src_path is not None else Path("."))
    )
 
    is_auto = (out_spec is True) or (
        isinstance(out_spec, str)
        and out_spec.strip().lower() in ("", "1", "true", "yes", "auto")
    )
    if is_auto:
        if src_path is not None:
            stem = src_path.stem
            if stem.endswith("_full") or stem.endswith("_simp"):
                stem = stem[:-5]
        else:
            stem = "circuit"
        out_path = eff_out_dir / f"{stem}{mode_tag}{ext}"
    else:
        spec_str = str(out_spec)
        spec_path = Path(spec_str)
        if not spec_path.is_absolute() and os.path.dirname(spec_str) == "":
            out_path = eff_out_dir / spec_path
        else:
            out_path = spec_path
 
    parent_dir = os.path.dirname(os.path.abspath(str(out_path)))
    if parent_dir:
        os.makedirs(parent_dir, exist_ok=True)
    return str(out_path)
 
 
def _circuit_dem(circuit: Any) -> Tuple[Any, bool, bool]:
    """
    The DEM of a Stim circuit: with decompose_errors=True if stim can decompose its errors (otherwise without).  An
    error channel with disjoint cases which stim cannot write as independent error mechanisms (e.g., a PAULI_CHANNEL_1
    with X and Z but no Y errors, PAULI_CHANNEL_2, or ELSE_CORRELATED_ERROR) needs approximate_disjoint_errors=True,
    which is used only if the conversion fails without it: it only changes the probabilities of the error mechanisms,
    not which errors are possible (so neither the distance, unless pmin > 0, nor the codewords).
 
    Returns:
        (dem, decompose_errors, approximate_disjoint_errors): the DEM, and the options used.
    """
    error: Optional[Exception] = None
    for approx in (False, True):
        for decomp in (True, False):
            try:
                return circuit.detector_error_model(decompose_errors=decomp, approximate_disjoint_errors=approx), \
                    decomp, approx
            except Exception as e:  # (stim raises ValueError)
                error = e
    assert error is not None
    raise error
 
 
def _warn_disabled_simple_full(simple: Optional[bool] = None, full: Optional[bool] = None, cli: bool = False) -> None:
    """
    Writes a warning to stderr if the options simple or full (CLI: --simple, --full) are given: they are disabled since
    version 0.13.0 (accepted for backward compatibility, but ignored).  The DEM of a Stim circuit always has all
    detectors, and the binary drops detectors if this is exact (drop=auto, the default; e.g., the minority-basis
    detectors of a CSS circuit, which the simple mode stripped): as fast, with the distance of the full DEM (the
    simplified DEM only gives a lower bound when dropping them is not exact).
    """
    names = [f"--{n}" if cli else f"{n}=" for n, v in (("simple", simple), ("full", full)) if v is not None]
    if names:
        _warn_ignored(f"{', '.join(names)}: disabled since version 0.13.0, ignored: the DEM of a Stim circuit has all "
                      f"detectors, and the binary drops detectors if this is exact (drop=auto, the default, e.g., the "
                      f"minority-basis detectors of a CSS circuit; drop=0 keeps them)")
 
 
def _dem_from_input(
    dem: Optional[Any],
    circuit: Optional[Any],
    basis: Optional[str] = None,
    rounds: Optional[int] = None,
    p_noise: float = 0.001,
    out_dir: Optional[Union[str, Path]] = None,
    out_dem: Optional[Union[bool, str, Path]] = None,
    out_stim: Optional[Union[bool, str, Path]] = None,
    circ_verbose: bool = False,
    drop_out: Optional[List[int]] = None,
    force_noise: bool = False
) -> Tuple[Any, Optional[Any], Optional[str]]:
    """
    The DEM of compute_dem_distance() (also used by get_cached_distance() for the cache key).  A DEM
    (stim.DetectorErrorModel or .dem file) is used as given.  A Stim circuit (stim.Circuit or .stim file, also when
    given as `dem`) is processed: the empty detectors are removed, the qubits are classified, the REPEAT count is set
    (rounds), and circuit-level noise of strength p_noise is added to a noiseless circuit (see add_noise(); none for
    p_noise=0), or with force_noise=True replaces the noise of the circuit (see strip_noise(); with p_noise=0, all noise
    is removed); then it is converted to a DEM (with all detectors).  The processed circuit and the DEM are saved if
    requested (out_stim, out_dem, out_dir; see compute_dem_distance()).  For a CSS circuit, the list drop_out (if given)
    is extended by the minority-basis detectors (0-based detectors of the DEM, see strip_minority_detectors()), which
    the binary drops if this is exact (drop=css, passed as drop=FILE).  The qubits are only classified for drop_out and
    circ_verbose.
 
    Returns:
        (dem, circuit, saved_dem_path): the DEM (object or file name), the processed circuit (None for a DEM input),
        and the file to which the DEM was saved (None if it was not saved).
    """
    if dem is not None and circuit is not None:
        _warn_ignored("both 'dem' and 'circuit' were given; using 'dem' (the circuit is ignored).")
        circuit = None
    if dem is not None and isinstance(dem, (str, Path)) and str(dem).endswith(".stim"):
        circuit = dem
        dem = None
 
    if rounds is not None and circuit is None:
        raise ValueError(
            "--rounds option is only supported for Stim circuit (.stim) inputs."
        )
 
    saved_dem_path: Optional[str] = None
    if dem is None and circuit is not None:
        circuit_src = str(circuit) if isinstance(circuit, (str, Path)) else "stim.Circuit"
        if isinstance(circuit, (str, Path)):
            stim = _get_stim()
            circuit = stim.Circuit.from_file(str(circuit))
        if not hasattr(circuit, 'detector_error_model'):
            raise ValueError("Provided circuit object does not have detector_error_model() method.")
        has_rep = False
        if rounds is not None:
            if rounds < 0:
                raise ValueError(f"Invalid rounds={rounds}; must be >= 0.")
            has_rep = has_repeat_block(circuit)
            if not has_rep:
                sys.stderr.write(
                    f"# Warning: Circuit '{circuit_src}' does not contain a "
                    f"REPEAT block; ignoring rounds={rounds}.\n"
                )
 
        circuit, empty_removed = remove_empty_detectors(circuit)
        if empty_removed > 0 and circ_verbose:
            print(f"[dist_m4ri] Removed {empty_removed} empty DETECTOR(s) from '{circuit_src}'")
 
        filepath_hint = circuit_src if circuit_src != "stim.Circuit" else None
        t_res: Optional[Dict[str, Any]] = None  # the classification of the qubits (only for drop=css and verbose)
        if circ_verbose or drop_out is not None:
            t_res = classify_qubits_thorough(circuit, verbose=False, basis_arg=basis, filepath=filepath_hint)
 
        if rounds is not None and has_rep:
            circuit = set_circuit_rounds(circuit, rounds)
 
        n_minority = None
        if t_res is not None and t_res["is_css"] and drop_out is not None:
            # the minority-basis detectors, for the exact reduction of the DEM in the binary (drop=css)
            mask: List[bool] = []
            strip_minority_detectors(circuit, t_res["basis"], verbose=False, thorough=True, thorough_res=t_res,
                                     mask_out=mask)
            if len(mask) == circuit.num_detectors:
                drop_out.extend(i for i, s in enumerate(mask) if s)
                n_minority = sum(mask)
            elif circ_verbose:
                print(f"[dist_m4ri] Warning: {len(mask)} detectors classified, but the circuit has "
                      f"{circuit.num_detectors}; no detectors to drop")
 
        mode_tag = "_full"  # (the default names of the saved files, see _resolve_stim_dem_out_path())
 
        if circ_verbose and t_res is not None:
            is_css_circ, is_rot_css = t_res["is_css"], t_res.get("is_rotated_css", False)
            css_type = "rotated-CSS (e.g. XZZX)" if is_rot_css else ("CSS" if is_css_circ else "non-CSS")
            rot_info = f", rotated_data={len(t_res.get('rotated_data_qubits', []))}" if is_rot_css else ""
            rnd_cnt = count_circuit_rounds(circuit)
            print(
                f"[dist_m4ri] Circuit basis tracking: type={css_type}, "
                f"basis={t_res['basis']}, data={len(t_res['data_qubits'])}, "
                f"X_anc={len(t_res['x_ancillas'])}, "
                f"Z_anc={len(t_res['z_ancillas'])}, "
                f"routing={len(t_res['routing_qubits'])}{rot_info}, "
                f"rounds={rnd_cnt}"
            )
            minority = (f", minority-basis={n_minority} (drop=css: the binary drops them if this is exact)"
                        if n_minority is not None else "")
            print(f"[dist_m4ri] Circuit detectors: {circuit.num_detectors}{minority}")
 
        if force_noise:  # the noise of the circuit is replaced (p_noise=0: removed)
            noise_msg = (f"replaced the noise by circuit-level noise (p={p_noise})" if p_noise > 0.0 else
                         "removed all noise (p_noise=0)")
            circuit = add_noise(circuit, p=p_noise, force=True)
        elif has_noise(circuit):
            noise_msg = "existing noise detected"
        elif p_noise > 0.0:
            noise_msg = f"added circuit-level noise (p={p_noise})"
            circuit = add_noise(circuit, p=p_noise)
        else:
            noise_msg = "no noise added (p_noise=0)"
 
        stim_out_path = _resolve_stim_dem_out_path(out_stim, circuit_src, mode_tag, ".stim", out_dir=out_dir)
        if stim_out_path is not None:
            circuit.to_file(stim_out_path)
            if circ_verbose:
                print(f"[dist_m4ri] Saved Stim circuit to '{stim_out_path}'")
 
        dem, decomp_used, approx_used = _circuit_dem(circuit)
        if circ_verbose:
            approx_msg = ", approximate_disjoint_errors=True" if approx_used else ""
            print(f"[dist_m4ri] Converted '{circuit_src}' to DEM ({noise_msg}, decompose_errors={decomp_used}"
                  f"{approx_msg})")
            if all(hasattr(dem, a) for a in ("num_detectors", "num_observables", "num_errors")):
                print(
                    f"[dist_m4ri] DEM size: {dem.num_detectors} detectors, {dem.num_observables} observables, "
                    f"{dem.num_errors} error mechanisms"
                )
 
        dem_out_path = _resolve_stim_dem_out_path(out_dem, circuit_src, mode_tag, ".dem", out_dir=out_dir)
        if dem_out_path is not None:
            _write_dem_file(dem, dem_out_path)
            saved_dem_path = dem_out_path
            if circ_verbose:
                print(f"[dist_m4ri] Saved DEM to '{dem_out_path}'")
    elif dem is not None and out_dem is not None and out_dem is not False:
        dem_src = str(dem) if isinstance(dem, (str, Path)) else "stim.Circuit"
        dem_out_path = _resolve_stim_dem_out_path(out_dem, dem_src, "_full", ".dem", out_dir=out_dir)
        if dem_out_path is not None:
            if isinstance(dem, (str, Path)) and os.path.exists(str(dem)):
                if os.path.abspath(str(dem)) != os.path.abspath(dem_out_path):
                    shutil.copyfile(str(dem), dem_out_path)
            else:
                _write_dem_file(dem, dem_out_path)
            saved_dem_path = dem_out_path
            if circ_verbose:
                print(f"[dist_m4ri] Saved DEM to '{dem_out_path}'")
 
    if dem is None:
        raise ValueError("Either 'dem' or 'circuit' must be provided.")
    return dem, circuit, saved_dem_path
 
 
def compute_dem_distance(
    dem: Optional[Any] = None,
    circuit: Optional[Any] = None,
    dist_m4ri: Optional[str] = None,
    method: int = 3,
    threads: Optional[int] = None,
    timeout: float = 60.0,
    num_steps: Optional[int] = None,
    d_exp: int = 0,
    d_min: int = 0,
    d_max: int = 0,
    dmin: int = 0,
    dmax: int = 0,
    dstop: int = 0,
    wmin: int = 1,
    wmax: int = 0,
    smax: Optional[int] = None,
    start: Optional[Union[int, str, Sequence[int]]] = None,
    cbeg: Optional[int] = None,
    cend: Optional[int] = None,
    noscan: int = 0,
    dW: int = -1,
    maxC: int = 0,
    pmin: float = 0.0,
    merge: bool = True,
    expand: bool = False,
    drop: Optional[Union[bool, int, str, Path]] = None,
    outD: Optional[Union[str, Path]] = None,
    out_reduced: Optional[Union[bool, str, Path]] = None,
    finC: Optional[str] = None,
    outC: Optional[str] = None,
    do_cws: bool = False,
    cache_file: Optional[Union[str, Path]] = None,
    solver: str = "dist_m4ri",
    codedistance_method: str = "UndetectableErrorStim",
    codedistance_params: Optional[Dict[str, Any]] = None,
    seed: int = 0,
    debug: int = 0,
    verbose: bool = False,
    nothrottle: bool = False,
    chunk_size: int = 0,
    ksub: int = 0,
    kwin: int = 0,
    win_mode: int = 0,
    win_hyb: int = 0,
    pairs: int = -1,
    min_hits: Optional[int] = None,
    cov_cws: int = 100,
    refresh: Optional[int] = None,
    simple: Optional[bool] = None,
    full: Optional[bool] = None,
    basis: Optional[str] = None,
    rounds: Optional[int] = None,
    out_dir: Optional[Union[str, Path]] = None,
    out_dem: Optional[Union[bool, str, Path]] = None,
    out_stim: Optional[Union[bool, str, Path]] = None,
    p_noise: float = 0.001,
    force_noise: bool = False,
    trust_start: bool = False,
    start_scan: bool = False,
    sort_rows: Optional[bool] = None,
    cc_prune: Optional[int] = None,
    engine: Optional[str] = None,
    **kwargs
) -> Tuple[Any, ...]:
    """
    Computes minimum graph/hypergraph distance of a Stim Detector Error Model (DEM).
 
    Args:
        dem: stim.DetectorErrorModel object or path to .dem / .stim file.
        circuit: stim.Circuit object or path to .stim file (converted to DEM; if stim cannot write an error channel with
            disjoint cases, e.g., a PAULI_CHANNEL_1 without Y errors, as independent error mechanisms, with
            approximate_disjoint_errors=True, which only changes the probabilities of the error mechanisms).
        dist_m4ri: Path to dist_m4ri executable (optional).
        method: Solver method (1=RW, 2=CC, 3=Bracketing default).
        threads: Maximum number of worker threads (default: all logical CPUs available; subject to throttling).
        timeout: Execution timeout in seconds (default: 60.0; 0: no limit).
        nothrottle: If True, the automatic thread throttling of the binary is disabled (default: False).
        chunk_size: Maximum RW batch claimed at once by a thread (default: 0: adaptive, 25-500 steps).
        num_steps: Maximum RW steps.
        min_hits: RW stops once the average number of hits per codeword reaches min_hits, both for the codewords of
            the minimum weight found and for a representative set of cov_cws lowest-weight codewords (see
            run_dist_m4ri()); passed if not None and >= 0 (None, the default: the binary's 5; 0: off, and then the
            repeated hits are not counted, unless codewords are collected with do_cws, outC, or maxC).
        cov_cws: Size of the representative set of lowest-weight codewords for min_hits (default: 100; 0: only the
            minimum weight).
        kwin / win_mode: A window of kwin columns in every RW step (alias: win; win_mode=0, the default: a Tanner
            graph ball, 1: an index window); kwin=0 (default): the automatic hybrid windows for n >= 500, see
            win_hyb and run_dist_m4ri(); kwin=-1: no windows (uniform random permutations in every step).
        refresh: RW steps between the basis refreshes of the experimental ksub RW (passed if not None; None,
            the default: the binary's 5000 with ksub > 0; 0: no refresh).
        d_exp: Expected distance estimate.
        d_min / dmin: Known lower bound on distance, inclusive.
        d_max / dmax: Known upper bound on distance, inclusive.
        dstop: Stop target for the lower bound (see compute_classical_distance(); default: 0 = off).
        wmin: Minimum distance of interest (terminate early if cw of weight <= wmin is found in RW or CC, default: 1).
        wmax: Maximum weight to search in CC.
        smax: Maximum syndrome weight for CC confinement profile.
        start: Expert option: list of CC start columns (int, comma-separated string "a,b,c", or
            sequence of ints; None or -1: all columns).  CC clusters are grown only from the listed
            columns, and they are not limited to larger column indices.  WARNING: the lower bound
            (and an exact result) is valid only if a code symmetry maps every minimum-weight codeword
            to one containing a listed column (e.g., one column per block of a quasi-cyclic code);
            the upper bound is always valid.  Results are cached under the separate key
            '<key>:start=a,b,c'; only dmax and codewords update the main cache record.
        trust_start: Expert option: accept the start-list results as valid, i.e., also merge dmin and
            rw_steps into the main cache record, and copy an existing exact start-list record to the
            main record even if no calculation is needed (default: False).
        start_scan: Expert option, with start (default: False): a cluster grown from a listed column c only
            uses the columns > c (see run_dist_m4ri()), e.g., start=[0, l] for the two blocks of a two-block
            group-algebra code over an abelian group; cached under the key suffix ':start=a,b,c:scan' (not for a
            DEM: ignored with a warning).
        cbeg / cend / noscan: Disabled in the Python interface: accepted for backward compatibility,
            but ignored with a warning to stderr (use the dist_m4ri binary directly).
        sort_rows: Row order of H in the binary (see run_dist_m4ri()): True sorts the rows by increasing weight
            (faster CC for very different row weights with cc_prune=0), False keeps their order, and None (default)
            leaves the binary's default (sorted for matrices; the detectors of a DEM are kept in time order).  The
            result and the cache key do not depend on it.
        cc_prune: The CC search of the binary (see run_dist_m4ri()): 0, the walk of the versions before 0.15.0; 1,
            the branch and bound (each codeword found once); 2, also the coverage and fractional cover bounds; None
            (default): the binary's default 1.  The result and the cache key do not depend on it.
        win_hyb: Window size of the automatic hybrid RW steps (kwin=0, n >= 500: a window on every other step; see
            run_dist_m4ri()); 0 (default): 256 columns for a DEM, 512 for matrices.  The cache key does not depend on
            it.
        pairs: The RW pairs of non-pivot columns (p=2, see run_dist_m4ri()): the number of random pivot rows of
            their buckets (0: off; -1, the default: auto).  The cache key does not depend on it.
        ksub: Experimental, should not be used (a warning is printed to stderr for ksub > 0 with method=1 or 3):
            subspace dimension sampled from ker(H) in RW (default: 0, full-matrix RW).
        dW: Extra weight window above dmin to collect codewords (only irreducible ones: not the union of a
            codeword and a disjoint nonzero vector with zero syndrome; the binary's default irred=1).
        maxC: Maximum number of codewords to collect (with expand=True, also the maximum number of codewords of the
            expanded list returned and written to outC; a warning is printed to stderr if some are dropped).
        pmin: Probability cutoff for error mechanisms in DEM.
            Note: CC start columns (start) and the codewords (finC, outC, do_cws) index the error mechanisms in
            their order of appearance in the (flattened) DEM, after the pmin cutoff: with another pmin, the columns
            (and the codewords) change.
        merge: Merge the equal columns of the DEM (error mechanisms with the same detectors and observables) in the
            binary (default: True).  Exact: dropping two equal columns of a codeword gives a lighter one, so the
            distance does not change (and the cache key does not depend on merge).  Column indices (finC, outC,
            start, the returned codewords) are those of the DEM; the codewords found use the first one of each set
            of equal columns (merge=False: all columns are kept, e.g., to enumerate the codewords with each of them;
            or expand=True to expand the list found).
        expand: If True, the codewords returned and written to outC are expanded in Python: each codeword is listed
            once for every choice among equal columns (default: False; see _expand_equal_columns()).  The binary
            and the cache keep the merged list.  With dW <= 1, the expanded list is that of merge=False (with
            dW >= 2, merge=False also lists lighter codewords with two equal columns added).  The expanded list can
            be much longer (it grows quickly with the weight); with maxC > 0, it is cut at maxC codewords.
        drop: The detectors which the binary drops if this is verified to be exact, so that the distance (and every
            codeword found) is that of the DEM, found from the DEM without these detectors and the errors touching
            them (fewer detectors and errors: as fast as the DEM with only the primary-basis detectors of a CSS
            circuit).  None, True, 1, or "auto" (default): the binary searches for the largest such set in the DEM alone
            (drop=auto, see the README), e.g., the minority-basis detectors of a CSS circuit (with the usual noise).
            "css": for a Stim circuit classified as CSS, its minority-basis detectors (see strip_minority_detectors()),
            passed as a file (otherwise, e.g., for a DEM, drop=auto is used, with a warning).  False or 0: no detectors
            are dropped.  A file name: the file with the detectors to drop (0-based, k for Dk; see read_drop_file()),
            for any DEM.  With "css" or a file, if dropping the detectors is not exact, a note is printed to stderr and
            the full DEM is used.  The codewords found use only the errors touching no dropped detector.
        outD: File to which the binary writes the detectors dropped (0-based, see read_drop_file()); with a cached
            result, the binary is run only to find them (with dmin = dmax: no search).
        out_reduced: True or a prefix PREFIX: writes the DEM without the detectors dropped (see outD) to
            PREFIX_red.dem, and the maps to the original DEM (its detectors and errors) to PREFIX_red.json, see
            write_reduced_dem() (True: PREFIX = <basename>, in out_dir or the directory of the input file).
        finC: Input file with initial codewords.
        outC: Output file to save codewords (NZLIST format).
        do_cws: Whether to return extracted error mechanisms / codewords.
        cache_file: Optional JSON file path for persistent distance caching.
        solver: "dist_m4ri" or "codedistance".
        codedistance_method: Method if using codedistance library.
        codedistance_params: Extra parameters for codedistance library.
        seed: Random seed.
        debug: Debug bitmap: the bits in BIN_DBG_MASK for the dist_m4ri binary, and the PY_DBG_* bits.
        verbose: Verbose reporting flag.
        simple / full: Disabled since version 0.13.0 (accepted for backward compatibility, but ignored with a warning
            to stderr): the DEM of a Stim circuit always has all detectors, and the minority-basis detectors of a CSS
            circuit (which simple=True stripped) are dropped by the binary if this is exact (see drop).  The distance
            of the simplified circuit (a lower bound) can still be found by passing the circuit stripped with
            strip_minority_detectors().
        basis: Optional primary memory basis override ('X' or 'Z') for .stim circuits, only used with drop="css" (the
            other basis is that of the minority-basis detectors) and for the verbose report of the classification.
        rounds: Optional number of REPEAT rounds for .stim circuits (warns if no REPEAT block).
        out_dir: Optional output directory for saved DEM and/or Stim circuit files.
        out_dem: Optional bool or filename to save the constructed DEM (True = auto-named <basename>_full.dem).  The
            codewords (outC, do_cws) index its error lines (in the order of the flattened DEM): save the DEM in the
            same run, since a DEM generated again from the circuit may differ (e.g., with another stim version); with
            outC but without out_dem, a warning is printed to stderr for a Stim circuit.
        out_stim: Optional bool or filename to save the processed (noisy, rounds-adjusted) Stim circuit
            (True = auto-named <basename>_full.stim).
        p_noise: Strength of the uniform circuit-level noise added to a noiseless Stim circuit (see add_noise();
            default: 0.001; 0: no noise is added, and a noiseless circuit gives no distance, with a note).  The
            distance does not depend on it (unless pmin > 0), only on which faults are possible.  A circuit with noise
            (a noise channel or a noisy measurement such as M(0.001), see has_noise()) is used as is, unless
            force_noise=True.
        force_noise: If True, the noise of a Stim circuit is replaced by the uniform noise of strength p_noise (see
            strip_noise(); with p_noise=0, all noise is removed, e.g., to save the noiseless circuit with out_stim),
            e.g., to compare circuits with the same noise model (default: False).
 
    Returns:
        tuple (dist, d_info, cws) if do_cws else (dist, d_info)
 
    Raises:
        TypeError: for an unknown keyword argument (e.g., a misspelled option).
        ValueError: if neither dem nor circuit is given, for rounds without a Stim circuit (or rounds < 0), for
            p_noise outside [0, 0.5], for an invalid drop (e.g., a file which does not exist) or another invalid
            option value (e.g., start, or cc_prune other than 0, 1, or 2), for method=2 with timeout <= 0 but
            without wmax, dmax, or dstop, or for do_cws / outC with solver="codedistance".
        FileNotFoundError: if the dist_m4ri binary is not found (see find_dist_m4ri_binary()).
        RuntimeError: if the binary exits with an error.
        ImportError: if stim is needed (e.g., for a Stim circuit) or solver="codedistance", but the package is not
            installed.
    """
    global _last_run_stats
    eff_dmin = dmin if dmin > 0 else d_min
    eff_dmax = dmax if dmax > 0 else d_max
    _check_kwargs(compute_dem_distance, kwargs)
    cert_mode = _resolve_cert_engine(solver, engine)
    if start_scan:  # (the binary merges the equal columns of a DEM, which changes the order of the columns)
        _warn_ignored("start_scan=1 is not available for a DEM (ignored)")
        start_scan = False
    start_list = _prepare_start_option(start, trust_start, noscan, cbeg, cend, solver, start_scan=start_scan)
    _warn_experimental_ksub(ksub, method, solver)
    _warn_disabled_simple_full(simple, full)
 
    circ_verbose = verbose or bool(debug & PY_DBG_CIRCUITS)  # Stim circuit to DEM conversion details
    if not 0.0 <= p_noise <= 0.5:
        raise ValueError(f"invalid p_noise={p_noise}: the noise strength must be in [0, 0.5]")
    drop_mode = _drop_mode(drop)  # "auto", "0", "css", or a file name
    src_in = dem if dem is not None else circuit  # (the input, for the names of the files of out_reduced)
    src_name = str(src_in) if isinstance(src_in, (str, Path)) else f"stim.{type(src_in).__name__}"
    is_codedist = solver == "codedistance" or str(engine or "").strip().lower() == "codedistance"
    css_list: List[int] = []  # the minority-basis detectors of a CSS circuit (drop=css)
    dem, circuit, saved_dem_path = _dem_from_input(
        dem, circuit, basis=basis, rounds=rounds, p_noise=p_noise, out_dir=out_dir, out_dem=out_dem,
        out_stim=out_stim, circ_verbose=circ_verbose,
        drop_out=css_list if (drop_mode == "css" and not is_codedist) else None, force_noise=force_noise
    )
    if getattr(dem, "num_errors", None) == 0:  # (a stim object; e.g., a noiseless circuit with p_noise=0)
        sys.stderr.write("# Note: the DEM has no error mechanisms (no noise, e.g., p_noise=0 for a noiseless circuit "
                         "or with force_noise): no distance computed\n")
        return (0, [0, 0, 0], []) if do_cws else (0, [0, 0, 0])
 
    if is_codedist:
        if do_cws or outC:
            raise ValueError("Codeword extraction is not supported with codedistance solver; use solver='dist_m4ri'.")
        if outD or out_reduced:
            _warn_ignored("outD and out_reduced are only used with solver='dist_m4ri'; ignored")
        _warn_codedistance_ignored(locals())
        codedistance = _get_codedistance()
        params = dict(codedistance_params or {})
        params.setdefault("filterCircuit", False)
        if num_steps is not None and "iterCount" not in params:
            params["iterCount"] = num_steps
 
        if circuit is not None:
            res = codedistance.circuitDistance(
                circuit, method=codedistance_method, params=params,
                seed=seed if seed != 0 else None
            )
        else:
            H, L, priors = codedistance.StimDEM2HL(dem)
            if "priors" not in params and len(priors) > 0:
                params["priors"] = priors
            res = codedistance.codeDistance(
                H, L, tB=1, method=codedistance_method, params=params,
                seed=seed if seed != 0 else None
            )
        d = res.get("d", -1)
        d_info = format_bounds_list(d, d, 0) if d > 0 else [0, 0, 0]
        return d, d_info
 
    # Solver is native multithreaded dist_m4ri (the cache key is that of the processed DEM, see get_cached_distance())
    if outC and circuit is not None and saved_dem_path is None:
        sys.stderr.write(f"# Warning: outC={outC}: the codewords index the error lines of the DEM generated from the "
                         f"Stim circuit in this run (after the pmin cutoff), which is not saved; save it with "
                         f"--out-dem (out_dem=...), since a DEM generated again later (e.g., with another stim "
                         f"version) may not fit\n")
    fdem_run = saved_dem_path if (saved_dem_path is not None and os.path.exists(saved_dem_path)) else dem
    temp_files: List[str] = []
    try:
        fdrop = drop_mode  # "auto", "0", or a file (drop=css: the minority-basis detectors written to a file)
        if drop_mode == "css":
            if css_list:
                fdrop = create_unique_file(extension="_drop.txt")
                temp_files.append(fdrop)
                with open(fdrop, "w") as f:
                    f.write(f"# {len(css_list)} minority-basis detectors (drop=css)\n" +
                            " ".join(str(r) for r in css_list) + "\n")
                if circ_verbose:
                    print(f"[dist_m4ri] drop=css: the binary drops the {len(css_list)} minority-basis detectors if "
                          f"this is exact")
            else:
                fdrop = "auto"
                _warn_ignored("drop=css: no minority-basis detectors (they are only known for a Stim circuit "
                              "classified as CSS); using drop=auto (the detectors to drop found from the DEM)")
        outd_file = str(outD) if outD else None
        if out_reduced and outd_file is None:
            outd_file = create_unique_file(extension="_outD.txt")
            temp_files.append(outd_file)
        if outd_file is not None and not isinstance(fdem_run, (str, Path)):  # (the same DEM file for the runs)
            fdem_file = create_unique_file(extension=".dem")
            temp_files.append(fdem_file)
            _write_dem_file(fdem_run, fdem_file)
            fdem_run = fdem_file
        cws_out_fn = None
        if expand and (do_cws or outC):
            def cws_out_fn(cws_in: List[List[int]]) -> List[List[int]]:
                return _expand_equal_columns(cws_in, fdem_run, pmin=pmin, maxC=maxC, verbose=verbose)
        eff_cache_file = str(Path(cache_file).resolve()) if cache_file is not None else _distance_cache_file
        if _can_delegate_to_cert(
            cert_mode, method=method, do_cws=do_cws, outC=outC, finC=finC, smax=smax,
            dW=dW, maxC=maxC, start_list=start_list, outD=outD, out_reduced=out_reduced, pmin=pmin
        ):
            _, _, qec_pipeline = _get_qec_cert()
            mode_arg = "ub" if method == 1 else "auto"
            t_lim = float(timeout) if timeout and timeout > 0 else 0.0
            n_thr = threads or (os.cpu_count() or 8)
            r_seed = seed if seed != 0 else 1
            res = _cert_code_distance(
                lambda: _dem_cache_key(dem, pmin),
                lambda w_lo, w_hi: (
                    qec_pipeline.certify_circuit(
                        circuit, wmin=w_lo, wmax=w_hi, threads=n_thr, seed=r_seed, time_limit=t_lim, mode=mode_arg
                    )
                    if circuit is not None else
                    qec_pipeline.certify_dem(
                        fdem_run, wmin=w_lo, wmax=w_hi, threads=n_thr, seed=r_seed, time_limit=t_lim, mode=mode_arg
                    )
                ),
                label="DEM", dmin=eff_dmin, dmax=eff_dmax, dstop=dstop, wmax=wmax,
                eff_cache_file=eff_cache_file, debug=debug, verbose=verbose,
            )
            dist, d_info, cws = res["dist"], res["d_info"], res["cws"]
            return (dist, d_info, cws) if do_cws else (dist, d_info)
        res = _cached_code_distance(
            None, None, None, False, "DEM", dist_m4ri=dist_m4ri, method=method, threads=threads, timeout=timeout,
            num_steps=num_steps, d_exp=d_exp, dmin=eff_dmin, dmax=eff_dmax, dstop=dstop, wmin=wmin, wmax=wmax,
            smax=smax if smax is not None else 0, start_list=start_list, dW=dW, maxC=maxC, finC=finC, outC=outC,
            need_cws=bool(do_cws or outC), eff_cache_file=eff_cache_file, seed=seed, debug=debug, verbose=verbose,
            nothrottle=nothrottle, chunk_size=chunk_size, ksub=ksub,
            kwin=kwin if kwin != 0 else int(kwargs.get("win", 0) or 0), win_mode=win_mode, min_hits=min_hits,
            cov_cws=cov_cws, refresh=refresh, trust_start=trust_start, fdem=fdem_run, pmin=pmin,
            merge=merge, key_fn=lambda: _dem_cache_key(dem, pmin), cws_out_fn=cws_out_fn, fdrop=fdrop, outD=outd_file,
            sort_rows=sort_rows, win_hyb=win_hyb, pairs=pairs, cc_prune=cc_prune
        )
        ran = not res["cached"]
        drop_stats = _last_run_stats if ran else {}
        if outd_file is not None and res["cached"]:  # a run only to find the detectors dropped (bounds coincide)
            if verbose:
                print("[dist_m4ri] Cached result: running the binary only for the detectors dropped (outD)")
            cached_stats = _last_run_stats
            run_dist_m4ri(dist_m4ri_path=dist_m4ri, method=2, fdem=str(fdem_run), dmin=1, dmax=1, wmax=1, threads=1,
                          pmin=pmin, merge=merge, drop=fdrop, outD=outd_file, debug=debug & ~BIN_DBG_MASK)
            drop_stats, _last_run_stats = _last_run_stats, cached_stats  # (the statistics of the cached result)
            ran = True
        if ran and fdrop not in ("auto", "0") and drop_stats.get("drop_note"):
            what = "the minority-basis detectors (drop=css)" if drop_mode == "css" else f"the detectors in {fdrop}"
            sys.stderr.write(f"# Note: dropping {what} is not exact for this DEM ({drop_stats['drop_note']}); "
                             f"the full DEM was used\n")
        elif ran and fdrop not in ("auto", "0") and drop_stats.get("drop_none_listed"):
            sys.stderr.write(f"# Note: none of the detectors in {fdrop} is in the DEM; nothing dropped\n")
        if drop_mode == "css" and fdrop != "auto" and outd_file is not None and os.path.isfile(outd_file):
            with open(outd_file) as f:  # the comment line: drop=css instead of the temporary file
                text = f.read()
            with open(outd_file, "w") as f:
                f.write(text.replace(f"(drop={fdrop}", "(drop=css", 1))
        if out_reduced and outd_file is not None:
            dropped, num_det = read_drop_file(outd_file)
            prefix = _reduced_out_prefix(out_reduced, src_name, out_dir)
            drop_label = "css" if (drop_mode == "css" and fdrop != "auto") else str(fdrop)
            dem_red, json_red = write_reduced_dem(
                fdem_run, dropped, prefix, pmin=pmin, num_detectors=num_det,
                meta={"source": src_name, "dem": saved_dem_path if saved_dem_path else
                      (str(fdem_run) if str(fdem_run) not in temp_files else None), "drop": drop_label})
            if verbose or (debug & PY_DBG_CIRCUITS):
                print(f"[dist_m4ri] Saved the reduced DEM ({len(dropped)} detectors dropped) to '{dem_red}' and the "
                      f"maps to '{json_red}'")
    finally:
        _remove_temp_files(temp_files, debug)
    dist, d_info, cws = res["dist"], res["d_info"], res["cws"]
    return (dist, d_info, cws) if do_cws else (dist, d_info)
 
 
def _model_detector_groups(circuit: Any) -> Tuple[List[int], List[bool], int]:
    """
    The groups of the detectors of a Stim circuit for its code-sized model (see compute_model_lower_bound()): two
    detectors are in the same group if they share a measurement record other than a final data measurement.  The final
    data measurements are the measurements in the final measurement block (after the last detector which precedes the
    last measurement) of qubits not measured before it, or all measurements of the final block if there are none
    (e.g., if every qubit is measured in each round).  In a memory circuit, the groups are the chains of the detectors
    of the checks, linked by the measurements of their ancillas in consecutive rounds; the chain of a check of the
    measured basis ends with its detector of the final data measurements.
 
    Returns:
        (group, final, num_final): the group of each detector (numbered in the order of their first detectors), for
        each group whether one of its detectors has a final data measurement, and the number of final data
        measurements.
    """
    stim = _get_stim()
    det_recs: List[List[int]] = []         # the measurement records of each detector (absolute indices)
    det_pos: List[int] = []                # its position in the flattened circuit
    meas_pos: List[int] = []               # the position of the instruction of each measurement record
    meas_qubits: List[frozenset] = []      # and its qubits
    last_gate_pos = -1                     # the position of the last unitary gate (for end-of-circuit DETECTORs)
    for pos, inst in enumerate(circuit.flattened()):
        if inst.name == "DETECTOR":
            n = len(meas_pos)
            det_recs.append([n + t.value for t in inst.targets_copy() if t.is_measurement_record_target])
            det_pos.append(pos)
        else:
            gd = stim.gate_data(inst.name)
            if gd.produces_measurements:
                for grp in inst.target_groups():  # (one record per group, e.g., per Pauli product of MPP)
                    meas_pos.append(pos)
                    meas_qubits.append(frozenset() if inst.name == "MPAD" else
                                       frozenset(t.qubit_value for t in grp if t.qubit_value is not None))
            elif gd.is_unitary:
                last_gate_pos = pos
    last_meas = meas_pos[-1] if meas_pos else -1
    last_det = max((p for p in det_pos if p < last_meas), default=-1)
    cutoff = max(last_det, last_gate_pos)
    before: Set[int] = set()  # the qubits measured before the final measurement block
    for p, qs in zip(meas_pos, meas_qubits):
        if p <= cutoff:
            before |= qs
    final_data = {r for r, (p, qs) in enumerate(zip(meas_pos, meas_qubits)) if p > cutoff and qs and not qs & before}
    if not final_data:  # (e.g., all qubits are measured in every round): all measurements of the final block
        final_data = {r for r, p in enumerate(meas_pos) if p > cutoff}
    parent = list(range(len(det_recs)))
 
    def find(a: int) -> int:
        while parent[a] != a:
            parent[a] = parent[parent[a]]
            a = parent[a]
        return a
 
    first_det: Dict[int, int] = {}  # the first detector of each measurement record (other than final data)
    for d, recs in enumerate(det_recs):
        for r in recs:
            if r not in final_data:
                a, b = find(d), find(first_det.setdefault(r, d))
                if a != b:
                    parent[max(a, b)] = min(a, b)  # (the root of a group is its first detector)
    ids: Dict[int, int] = {}
    group = [ids.setdefault(find(d), len(ids)) for d in range(len(det_recs))]
    final = [False] * len(ids)
    for d, recs in enumerate(det_recs):
        if any(r in final_data for r in recs):
            final[group[d]] = True
    return group, final, len(final_data)
 
 
def _dem_detector_groups(dem: Any, pmin: float = 0.0) -> Tuple[List[int], List[bool], int, int, int]:
    """
    Pure-DEM detector chains for compute_model_lower_bound() when no Stim circuit is available (or when the circuit
    groups are trivial).  Uses detector coordinates (x, y, ..., t) when present in the DEM to group detectors with the
    same spatial coordinates across rounds, and falls back to linking consecutive-round detectors via dominant weight-2
    observable-free (ancilla measurement) error mechanisms when coordinates are absent.
 
    Returns:
        (group, final, num_final, num_detectors, num_observables).
    """
    if isinstance(dem, (str, Path)):
        with open(str(dem)) as f:
            lines = f.read().splitlines()
    else:
        lines = str(dem.flattened() if hasattr(dem, "flattened") else dem).splitlines()
 
    det_coords: Dict[int, Tuple[float, ...]] = {}
    max_det = -1
    max_obs = -1
 
    def parse_block(i: int, det_shift: int, c_shift: Tuple[float, ...]) -> Tuple[int, int, Tuple[float, ...]]:
        nonlocal max_det, max_obs
        while i < len(lines):
            s = lines[i].split("#", 1)[0].strip()
            i += 1
            if not s:
                continue
            if s.startswith("}"):
                return i, det_shift, c_shift
            if s.startswith("repeat"):
                count = int(s.split()[1])
                body, end = i, i
                for _ in range(count):
                    end, det_shift, c_shift = parse_block(body, det_shift, c_shift)
                if count <= 0:
                    depth = 1
                    while end < len(lines) and depth > 0:
                        t = lines[end].split("#", 1)[0].strip()
                        end += 1
                        depth += t.startswith("repeat") - t.startswith("}")
                i = end
            elif s.startswith("shift_detectors"):
                if "(" in s and ")" in s:
                    vals = [float(x) for x in s[s.index("(") + 1:s.index(")")].split(",") if x.strip()]
                    n_c = max(len(c_shift), len(vals))
                    c_shift = tuple(
                        (c_shift[k] if k < len(c_shift) else 0.0) + (vals[k] if k < len(vals) else 0.0)
                        for k in range(n_c)
                    )
                    rest = s[s.index(")") + 1:].strip()
                else:
                    rest = s.split(None, 1)[1].strip() if len(s.split()) > 1 else "0"
                if rest:
                    det_shift += int(rest.rsplit(None, 1)[-1])
            elif s.startswith("detector"):
                coords: Tuple[float, ...] = ()
                if "(" in s and ")" in s:
                    vals = [float(x) for x in s[s.index("(") + 1:s.index(")")].split(",") if x.strip()]
                    coords = tuple(vals[k] + (c_shift[k] if k < len(c_shift) else 0.0) for k in range(len(vals)))
                    rest = s[s.index(")") + 1:]
                else:
                    rest = s[len("detector"):]
                for tok in rest.split():
                    if tok.startswith("D"):
                        d = int(tok[1:]) + det_shift
                        max_det = max(max_det, d)
                        if coords:
                            det_coords[d] = coords
            elif s.startswith("logical_observable"):
                for tok in s.split()[1:]:
                    if tok.startswith("L"):
                        max_obs = max(max_obs, int(tok[1:]))
            elif s.startswith("error"):
                p_text = s[s.index("(") + 1:s.index(")")].strip()
                if float(p_text) < pmin:
                    continue
                for tok in s[s.index(")") + 1:].split():
                    if tok.startswith("D"):
                        max_det = max(max_det, int(tok[1:]) + det_shift)
                    elif tok.startswith("L"):
                        max_obs = max(max_obs, int(tok[1:]))
        return i, det_shift, c_shift
 
    parse_block(0, 0, ())
    num_det = int(getattr(dem, "num_detectors", max_det + 1) or (max_det + 1))
    num_obs = int(getattr(dem, "num_observables", max_obs + 1) or (max_obs + 1))
    if num_det <= 0:
        return [], [], 0, 0, max(0, num_obs)
 
    if len(det_coords) == num_det and all(len(c) >= 2 for c in det_coords.values()):
        spatial_ids: Dict[Tuple[float, ...], int] = {}
        group = [spatial_ids.setdefault(det_coords[d][:-1], len(spatial_ids)) for d in range(num_det)]
        if 1 <= len(spatial_ids) < num_det:
            max_t = max(c[-1] for c in det_coords.values())
            final = [False] * len(spatial_ids)
            for d in range(num_det):
                if det_coords[d][-1] == max_t:
                    final[group[d]] = True
            if all(final):
                counts = [0] * len(spatial_ids)
                for g in group:
                    counts[g] += 1
                max_c = max(counts, default=0)
                if max_c > 1 and 0 < sum(c == max_c for c in counts) < len(spatial_ids):
                    final = [c == max_c for c in counts]
            return group, final, sum(final), num_det, max(0, num_obs)
 
    cols_prob = _dem_error_columns(dem, pmin, with_prob=True)
    pair_prob: Dict[Tuple[int, int], float] = {}
    best_inc = [0.0] * num_det
    for dets, obs, p_text in cols_prob:
        if len(dets) == 2 and not obs:
            u, v = sorted(dets)
            if 0 <= u < v < num_det:
                p = float(p_text)
                if p > pair_prob.get((u, v), -1.0):
                    pair_prob[(u, v)] = p
                if p > best_inc[u]:
                    best_inc[u] = p
                if p > best_inc[v]:
                    best_inc[v] = p
 
    parent = list(range(num_det))
 
    def find(a: int) -> int:
        while parent[a] != a:
            parent[a] = parent[parent[a]]
            a = parent[a]
        return a
 
    has_next = [False] * num_det
    has_prev = [False] * num_det
    cand_edges = [
        (p, u, v) for (u, v), p in pair_prob.items()
        if p >= 0.5 * max(best_inc[u], best_inc[v])
    ]
    cand_edges.sort(key=lambda item: (-item[0], item[1], item[2]))
    for _, u, v in cand_edges:
        if not has_next[u] and not has_prev[v]:
            ru, rv = find(u), find(v)
            if ru != rv:
                parent[max(ru, rv)] = min(ru, rv)
                has_next[u] = True
                has_prev[v] = True
 
    ids: Dict[int, int] = {}
    group = [ids.setdefault(find(d), len(ids)) for d in range(num_det)]
    counts = [0] * len(ids)
    for g in group:
        counts[g] += 1
    max_len = max(counts, default=0)
    if max_len > 1 and 0 < sum(c == max_len for c in counts) < len(ids):
        final = [c == max_len for c in counts]
    else:
        final = [True] * len(ids)
    return group, final, sum(final), num_det, max(0, num_obs)
 
 
def _model_matrices(
    cols: List[Tuple[Any, ...]], group: List[int], use: List[bool], num_observables: int
) -> Dict[str, Any]:
    """
    The matrices of a code-sized model (see compute_model_lower_bound()): one row per group of detectors with use[g]
    (the sum of the rows of its detectors), and one column per distinct pair (model column, observables) of the error
    mechanisms `cols` (see _dem_error_columns()); the errors with no effect on the rows nor on the observables are
    dropped.
 
    Returns:
        dict with "H" and "L" (scipy.sparse.csr_matrix), "col_map" (the model column of each error mechanism, -1 if
        it is dropped), "groups" (the group of each row), and "trivial" (the error mechanisms which flip an observable
        but no row: then the model has a codeword of weight 1).
    """
    import numpy as np
    import scipy.sparse as sp
    index: Dict[Tuple[frozenset, frozenset], int] = {}
    col_map: List[int] = []
    trivial: List[int] = []
    for j, (dets, obs) in enumerate(cols):
        rows: Set[int] = set()
        for d in dets:
            if use[group[d]]:
                rows ^= {group[d]}
        if not rows:
            col_map.append(-1)
            if obs:
                trivial.append(j)
            continue
        col_map.append(index.setdefault((frozenset(rows), obs), len(index)))
    used = sorted({g for rows, _ in index for g in rows})
    row_of = {g: i for i, g in enumerate(used)}
    hi: List[int] = []
    hj: List[int] = []
    li: List[int] = []
    lj: List[int] = []
    for c, (rows, obs) in enumerate(index):
        hi.extend(row_of[g] for g in rows)
        hj.extend([c] * len(rows))
        li.extend(obs)
        lj.extend([c] * len(obs))
    H = sp.csr_matrix((np.ones(len(hi), dtype=np.int8), (hi, hj)), shape=(len(used), len(index)))
    L = sp.csr_matrix((np.ones(len(li), dtype=np.int8), (li, lj)), shape=(num_observables, len(index)))
    return {"H": H, "L": L, "col_map": col_map, "groups": used, "trivial": trivial}
 
 
def compute_model_lower_bound(
    circuit: Any = None,
    dist_m4ri: Optional[str] = None,
    method: int = 3,
    threads: Optional[int] = None,
    timeout: float = 60.0,
    num_steps: Optional[int] = None,
    dstop: int = 0,
    wmax: int = 0,
    minority: bool = False,
    pmin: float = 0.0,
    rounds: Optional[int] = None,
    p_noise: float = 0.001,
    force_noise: bool = False,
    out_model: Optional[Union[str, Path]] = None,
    cache_file: Optional[Union[str, Path]] = None,
    seed: int = 0,
    debug: int = 0,
    verbose: bool = False,
    nothrottle: bool = False,
    pairs: int = -1,
    sort_rows: Optional[bool] = None,
    cc_prune: Optional[int] = None,
    return_info: bool = False,
    dem: Optional[Any] = None,
    **kwargs
) -> Any:
    """
    Certified lower bound on the circuit-level distance of a Stim memory circuit from its code-sized model.
 
    The model is a row reduction of the DEM (H, L) of the circuit (processed as in compute_dem_distance(), with the
    options rounds, p_noise, force_noise, and pmin): two detectors are linked if they share a measurement record other
    than a final data measurement, and each group of linked detectors gives one row, the sum of the rows of its
    detectors (see _model_detector_groups()).  In a memory circuit, the groups are the chains of the detectors of the
    checks over the rounds: the chain of a check h of the measured basis telescopes to the parity of the final data
    measurements on its support, so that the column of an error mechanism is the syndrome of its net data error (a
    data error or a hook error), and the chains of the minority-basis checks (with minority=True) add the net change
    of their values between their first and last measurements.  Equal columns are merged, and the errors with no effect
    on the rows nor on the observables (e.g., ancilla measurement errors) are dropped; the model has a few columns per
    data qubit.  Since every row is a sum of detector rows, every codeword x of the DEM (Hx = 0, Lx != 0) gives a model
    codeword of weight at most |x|: the distance of the model, as certified by CC (its dmin), is a lower bound on the
    distance of the DEM.  It ignores the timing within the rounds, so it is not tight in general (e.g., 5 for the
    bb_72 circuit of distance 6).  Any circuit gives a valid bound, but a useful one needs this structure; if an error
    flips an observable but no row, the bound is 1 (with a note to stderr).
 
    The binary runs on the model with the rows of the measured-basis chains first, and then (with minority=True) on
    the model with all rows, starting from that bound (the extra rows can only raise it): RW first, which ends as soon
    as it finds a model codeword of that weight (then the bound is not raised), and only otherwise with `method` (CC
    from dmin).  The minority-basis rows are off by default: with depolarizing-type noise, every net data error which
    flips the measured-basis observable also occurs without a component of the other basis, so that a lightest model
    codeword has a version which the minority-basis rows do not detect (they never raised the bound of the benchmark
    circuits or of the surface-code circuits of stim, and cost up to 9 s for the mitten_270 circuits); they may raise
    it for other noise models (e.g., biased noise).  The certified bound is stored as dmin in the cache record of the
    DEM (the same key as compute_dem_distance(); "dmin_model": the bound), so that a later compute_dem_distance()
    starts CC from it; the distances of the models are cached under their own keys.
 
    Args:
        circuit: Stim memory circuit (stim.Circuit or .stim file).
        dist_m4ri: Path to dist_m4ri executable (optional).
        method: Solver method for the model (1=RW, 2=CC, 3=Bracketing default); only CC certifies a bound.
        threads / timeout / num_steps / seed / nothrottle / pairs: As for compute_dem_distance(), for each run of the
            binary (at most three).
        sort_rows / cc_prune: The row order and the CC search of the binary (see run_dist_m4ri(); None, the default:
            the binary's defaults, i.e., the rows of the model sorted by weight, and the branch and bound), for each
            run.  The bound and the cache keys do not depend on them.
        dstop: Stop target (see compute_dem_distance()): the runs end once CC has certified dmin >= dstop.
        wmax: Maximum weight of the CC rounds on the model (0: until the bounds meet or the timeout).
        minority: If True, the groups without a final data measurement (e.g., the chains of the minority-basis
            checks of a CSS circuit) are rows of the model as well (default: False; CLI: --model-minority).
        pmin: Probability cutoff for the error mechanisms of the DEM.
        rounds / p_noise / force_noise: The processing of the circuit, as in compute_dem_distance().
        out_model: If given, the model (with all rows used) is written to PREFIX_HR.mtx and PREFIX_LR.mtx.
        cache_file: Optional JSON file path for persistent distance caching.
        debug / verbose: As for compute_dem_distance().
        return_info: If True, return (bound, info).
 
    Returns:
        The certified lower bound, or (bound, info) with return_info=True, where info has "d_info" (the bounds
        [dmin, dmax, rw_steps] of the circuit's DEM from the cache record, with dmin including the bound; [bound, 0, 0]
        without the cache), "model_d_info" and "measured_d_info" (the bounds of the model and of its measured-basis
        part, [] if not run), the sizes "rows", "cols", "rows_measured", "cols_measured", "groups", "groups_final",
        "detectors", "final_data", "dem_cols", "trivial" (the error mechanisms which flip an observable but no row),
        the model "H", "L", and "col_map" (the model column of each error mechanism of the DEM, -1 if dropped), and
        "files" (the files written with out_model).
 
    Raises:
        TypeError: for an unknown keyword argument (e.g., a misspelled option).
        ValueError: if the input is not a Stim circuit.
    """
    global _distance_cache
    _check_kwargs(compute_model_lower_bound, kwargs, aliases=())
    src = dem if dem is not None else circuit
    if src is None:
        raise ValueError("compute_model_lower_bound: a Stim circuit (.stim) or DEM (.dem) is required")
    is_dem_input = dem is not None or (
        isinstance(src, (str, Path)) and str(src).endswith(".dem")
    ) or (not isinstance(src, (str, Path)) and not hasattr(src, "detector_error_model"))
    if isinstance(src, (str, Path)) and not str(src).endswith((".stim", ".dem")):
        raise ValueError(f"compute_model_lower_bound: {src} is not a Stim circuit (.stim) or DEM (.dem)")
    if not 0.0 <= p_noise <= 0.5:
        raise ValueError(f"invalid p_noise={p_noise}: the noise strength must be in [0, 0.5]")
    circ_verbose = verbose or bool(debug & PY_DBG_CIRCUITS)
    dem_obj, circ, _ = _dem_from_input(
        src if is_dem_input else None, None if is_dem_input else src,
        rounds=rounds, p_noise=p_noise, circ_verbose=circ_verbose, force_noise=force_noise
    )
    dem = dem_obj
    info: Dict[str, Any] = {"d_info": [0, 0, 0], "model_d_info": [], "measured_d_info": [], "files": []}
    if getattr(dem, "num_errors", None) == 0:
        sys.stderr.write("# Note: the DEM has no error mechanisms (no noise, e.g., p_noise=0 for a noiseless circuit "
                         "or with force_noise): no bound computed\n")
        return (0, info) if return_info else 0
    cols = _dem_error_columns(dem, pmin)
    if not cols:
        sys.stderr.write("# Note: the DEM has no error mechanisms (no noise, e.g., p_noise=0 for a noiseless circuit "
                         "or with force_noise): no bound computed\n")
        return (0, info) if return_info else 0
    if circ is not None:
        group, final, num_final = _model_detector_groups(circ)
        num_det = int(getattr(dem, "num_detectors", len(group)))
        num_obs = int(getattr(dem, "num_observables", 0))
        if len(group) != num_det:
            raise ValueError(f"compute_model_lower_bound: {len(group)} detectors in the circuit, {num_det} in its DEM")
        if len(final) == len(group) and len(group) > 1:
            dem_group, dem_final, dem_num_final, _, _ = _dem_detector_groups(dem, pmin)
            if len(dem_group) == len(group) and len(dem_final) < len(group):
                group, final, num_final = dem_group, dem_final, dem_num_final
    else:
        group, final, num_final, num_det, num_obs = _dem_detector_groups(dem, pmin)
    part = _model_matrices(cols, group, final, num_obs)  # the rows of the measured-basis chains
    full = _model_matrices(cols, group, [True] * len(final), num_obs) if minority else part
    info.update(rows=full["H"].shape[0], cols=full["H"].shape[1], rows_measured=part["H"].shape[0],
                cols_measured=part["H"].shape[1], groups=len(final), groups_final=sum(final), detectors=len(group),
                final_data=num_final, dem_cols=len(cols), trivial=len(full["trivial"]), H=full["H"], L=full["L"],
                col_map=full["col_map"])
    if verbose:
        print(f"[dist_m4ri] Code-sized model: {info['rows']} x {info['cols']} ({info['rows_measured']} rows of the "
              f"chains with final data measurements, {info['rows'] - info['rows_measured']} other), from "
              f"{len(cols)} error mechanisms and {len(group)} detectors in {len(final)} groups ({num_final} final data "
              f"measurements)")
    if out_model:
        from scipy.io import mmwrite
        for name, M in (("HR", full["H"]), ("LR", full["L"])):
            path = f"{out_model}_{name}.mtx"
            parent_dir = os.path.dirname(os.path.abspath(path))
            os.makedirs(parent_dir, exist_ok=True)
            mmwrite(path, M, symmetry="general")
            info["files"].append(path)
        if verbose:
            print(f"[dist_m4ri] Saved the code-sized model to '{info['files'][0]}' and '{info['files'][1]}'")
    eff_cache_file = str(Path(cache_file).resolve()) if cache_file is not None else _distance_cache_file
 
    def run(model: Dict[str, Any], dmin: int, run_method: int, wmin: int = 1) -> List[int]:
        # the bounds [dmin, dmax, rw_steps] of the model
        res = _cached_code_distance(
            model["H"], None, model["L"], False, "code-sized model", dist_m4ri=dist_m4ri, method=run_method,
            threads=threads, timeout=timeout, num_steps=num_steps, d_exp=0, dmin=dmin, dmax=0, dstop=dstop,
            wmin=wmin, wmax=wmax, smax=0, start_list=None, dW=-1, maxC=0, finC=None, outC=None, need_cws=False,
            eff_cache_file=eff_cache_file, seed=seed, debug=debug, verbose=verbose, nothrottle=nothrottle,
            chunk_size=0, ksub=0, kwin=0, win_mode=0, min_hits=None, cov_cws=100, refresh=None, trust_start=False,
            pairs=pairs, sort_rows=sort_rows, cc_prune=cc_prune)
        return list(res["d_info"])
 
    if full["trivial"]:
        sys.stderr.write(f"# Note: code-sized model: {len(full['trivial'])} error mechanisms flip an observable but no "
                         f"group of detectors (e.g., the first one, column {full['trivial'][0]} of the DEM), so that "
                         f"the model has a codeword of weight 1: the bound is 1\n")
        bound = 1
    else:
        bound = 1
        if not part["trivial"]:
            info["measured_d_info"] = run(part, 0, method)
            bound = max(bound, info["measured_d_info"][0])
        info["model_d_info"] = info["measured_d_info"]
        if full is not part and (dstop <= 0 or bound < dstop) and (wmax <= 0 or bound <= wmax):
            # all rows: RW first (a model codeword of weight `bound` ends the search), then CC from the bound
            dmin = bound if bound > 1 else 0
            info["model_d_info"] = run(full, dmin, 1, wmin=bound)
            if method != 1 and not 0 < info["model_d_info"][1] <= bound:
                info["model_d_info"] = run(full, dmin, method)
            bound = max(bound, info["model_d_info"][0])
    info["d_info"] = [bound, 0, 0]
    if _use_distance_cache:  # the bound as dmin in the cache record of the DEM
        if eff_cache_file:
            load_distance_cache(eff_cache_file)
        key = _dem_cache_key(dem, pmin)
        prev = _distance_cache.get(key) or {}
        p_dmin, p_dmax, p_rw = (prev.get("dmin", 0) or 0), (prev.get("dmax", 0) or 0), (prev.get("rw_steps", 0) or 0)
        if p_dmax > 0 and bound > p_dmax:
            sys.stderr.write(f"# Warning: the code-sized model bound {bound} exceeds the cached upper bound "
                             f"{p_dmax} of the DEM: not stored\n")
            info["d_info"] = format_bounds_list(p_dmin, p_dmax, p_rw)
        else:
            record = _sector_record(max(p_dmin, bound), p_dmax, p_rw, prev.get("cws", []))
            record["dmin_model"] = max(bound, prev.get("dmin_model", 0) or 0)
            if record != prev:
                _distance_cache[key] = record
                if eff_cache_file:
                    save_distance_cache(eff_cache_file)
            info["d_info"] = list(record["d_info"])
    if verbose:
        print(f"[dist_m4ri] Code-sized model: certified lower bound d >= {bound} on the circuit distance (model bounds "
              f"{info['model_d_info']}; measured-basis rows only: {info['measured_d_info']})")
    return (bound, info) if return_info else bound
 
 
def _write_nzlist_file(filepath: str, cws: List[List[int]]) -> None:
    """Writes codewords to a text file in NZLIST format (1-based indices).
    Skips creating the file if cws is empty.
    """
    if not cws:
        return
    with open(filepath, "w") as f:
        f.write("%% NZLIST\n")
        f.write(f"% {len(cws)} codewords\n")
        for cw in cws:
            f.write(f"{len(cw)} " + " ".join(str(idx + 1) for idx in cw) + "\n")
 
 
def parse_cli_args(argv: List[str]) -> Dict[str, Any]:
    """Parses CLI arguments supporting both key=value pairs and standard --flags."""
    args: Dict[str, Any] = {
        "method": 3,
        "finH": None,
        "finG": None,
        "finL": None,
        "fin": None,
        "fdem": None,
        "Hx": None,
        "Hz": None,
        "Lx": None,
        "Lz": None,
        "finC": None,
        "outC": None,
        "dmin": 0,
        "dmax": 0,
        "dstop": 0,
        "wmin": 1,
        "wmax": 0,
        "smax": None,
        "start": None,
        "cbeg": None,
        "cend": None,
        "trust_start": False,
        "start_scan": False,
        "css": None,
        "dexp": 0,
        "steps": None,
        "threads": None,
        "timeout": 60.0,
        "dW": -1,
        "maxC": 0,
        "pmin": 0.0,
        "merge": None,
        "expand": None,
        "drop": None,
        "outD": None,
        "out_reduced": None,
        "sort_rows": None,
        "cc_prune": None,
        "ortho": True,
        "noscan": 0,
        "irred": None,
        "classical": -1,
        "seed": 0,
        "debug": 0,
        "solver": "dist_m4ri",
        "engine": None,
        "cache_file": "tmp_dist_cache.json",
        "use_cache": True,
        "do_cws": False,
        "verbose": False,
        "silent": False,
        "nothrottle": False,
        "chunk_size": 0,
        "ksub": 0,
        "kwin": 0,
        "win_mode": 0,
        "win_hyb": 0,
        "pairs": -1,
        "min_hits": None,
        "cov_cws": 100,
        "refresh": None,
        "simple": None,
        "full": None,
        "basis": None,
        "rounds": None,
        "p_noise": None,
        "force_noise": False,
        "out_dir": None,
        "out_dem": None,
        "out_stim": None,
        "model_lb": False,
        "model_minority": False,
        "out_model": None,
        "morehelp": False,
        "morehelp_topic": None,
        "version": False,
        "unrecognized": [],
        "ignored_files": [],
    }
 
    def _has_later_input_file(start_idx: int) -> bool:
        for tok in argv[start_idx:]:
            if (
                not tok.startswith("-")
                and "=" not in tok
                and tok.endswith((".stim", ".dem", ".mtx", ".mmx"))
                and os.path.exists(tok)
            ):
                return True
        return False
 
    def _add_help_topic(topic: Optional[str]) -> None:  # --morehelp TOPIC, --help TOPIC (several: comma-separated)
        args["morehelp"] = True
        if topic and topic != "1":
            args["morehelp_topic"] = f"{args['morehelp_topic']},{topic}" if args["morehelp_topic"] else topic
 
    def _help_topic_at(j: int) -> Optional[str]:  # the topic after --morehelp / --help: not an option or a file
        nxt = argv[j] if j < len(argv) else None
        return nxt if nxt and not nxt.startswith("-") and "=" not in nxt and not os.path.exists(nxt) else None
 
    i = 0
    while i < len(argv):
        arg = argv[i]
        if not arg:
            i += 1
            continue
 
        if arg in ("--version", "-version", "version"):
            args["version"] = True
            i += 1
            continue
 
        if arg in ("--morehelp", "-morehelp", "--more-help", "-more-help", "morehelp"):
            topic = _help_topic_at(i + 1)
            _add_help_topic(topic)  # --morehelp TOPIC: only the entries of this parameter
            i += 2 if topic else 1
            continue
 
        if arg in ("-h", "--help", "help", "-?"):
            topic = _help_topic_at(i + 1)
            if topic:
                _add_help_topic(topic)  # --help TOPIC: the same as --morehelp TOPIC
            else:
                args["help"] = True
            i += 2 if topic else 1
            continue
 
        if arg in ("--no-throttle", "-no-throttle", "nothrottle", "--nothrottle"):
            args["nothrottle"] = True
            i += 1
            continue
 
        if arg in ("-v", "--verbose", "verbose", "-verbose"):
            args["verbose"] = True
            i += 1
            continue
 
        if arg in ("-q", "--silent", "-silent", "silent", "--quiet"):
            args["silent"] = True
            i += 1
            continue
 
        if arg in ("--no-cache", "-no-cache", "nocache", "--nocache"):
            args["use_cache"] = False
            args["cache_file"] = None
            i += 1
            continue
 
        if arg in ("--trust-start", "-trust-start", "--trust_start", "-trust_start", "trust_start", "trust-start"):
            args["trust_start"] = True
            i += 1
            continue
 
        if arg in ("--start-scan", "-start-scan", "--start_scan", "-start_scan", "start_scan", "start-scan"):
            args["start_scan"] = True
            i += 1
            continue
 
        if arg in ("--cws", "-cws", "cws", "do_cws=1", "--do_cws"):
            args["do_cws"] = True
            i += 1
            continue
 
        if arg in ("--model-lb", "-model-lb", "--model_lb", "-model_lb", "model_lb", "model-lb"):
            args["model_lb"] = True
            i += 1
            continue
 
        if arg in ("--model-minority", "-model-minority", "--model_minority", "-model_minority", "model_minority",
                   "model-minority"):
            args["model_minority"] = True
            i += 1
            continue
 
        if arg in (
            "--simple", "-simple", "--simplified", "-simplified",
            "simple", "simplified"
        ):
            args["simple"] = True  # disabled since version 0.13.0 (ignored with a warning)
            i += 1
            continue
 
        if arg in ("--full", "-full", "full"):
            args["full"] = True  # disabled since version 0.13.0 (ignored with a warning)
            i += 1
            continue
 
        if arg in ("--force-noise", "-force-noise", "--force_noise", "-force_noise", "force_noise", "force-noise",
                   "--force", "-force"):
            args["force_noise"] = True
            i += 1
            continue
 
        if arg in ("--rounds", "-rounds", "rounds"):
            if (
                i + 1 < len(argv)
                and "=" not in argv[i + 1]
                and argv[i + 1].lstrip("-").isdigit()
            ):
                args["rounds"] = int(argv[i + 1])
                i += 2
            else:
                args["rounds"] = 2
                i += 1
            continue
 
        if arg in ("--out-dem", "-out-dem", "--out_dem", "-out_dem", "out_dem"):
            next_tok = argv[i + 1] if i + 1 < len(argv) else None
            if (
                next_tok is not None
                and not next_tok.startswith("-")
                and "=" not in next_tok
                and not next_tok.endswith((".stim", ".mtx", ".mmx"))
                and not (
                    next_tok.endswith(".dem")
                    and os.path.exists(next_tok)
                    and args["fdem"] is None
                    and not _has_later_input_file(i + 2)
                )
            ):
                args["out_dem"] = next_tok
                i += 2
            else:
                args["out_dem"] = True
                i += 1
            continue
 
        if arg in ("--out-stim", "-out-stim", "--out_stim", "-out_stim", "out_stim"):
            next_tok = argv[i + 1] if i + 1 < len(argv) else None
            if (
                next_tok is not None
                and not next_tok.startswith("-")
                and "=" not in next_tok
                and not next_tok.endswith((".dem", ".mtx", ".mmx"))
                and not (
                    next_tok.endswith(".stim")
                    and os.path.exists(next_tok)
                    and args["fdem"] is None
                    and not _has_later_input_file(i + 2)
                )
            ):
                args["out_stim"] = next_tok
                i += 2
            else:
                args["out_stim"] = True
                i += 1
            continue
 
        if arg in ("--out-reduced", "-out-reduced", "--out_reduced", "-out_reduced", "out_reduced", "out-reduced"):
            next_tok = argv[i + 1] if i + 1 < len(argv) else None
            if (  # the prefix: not an option, nor an existing input file
                next_tok is not None
                and not next_tok.startswith("-")
                and "=" not in next_tok
                and not (next_tok.endswith((".stim", ".dem", ".mtx", ".mmx")) and os.path.exists(next_tok))
            ):
                args["out_reduced"] = next_tok
                i += 2
            else:
                args["out_reduced"] = True
                i += 1
            continue
 
        key = None
        val = None
        if "=" in arg:
            key, val = arg.split("=", 1)
            if key.startswith("--"):
                key = key[2:]
            elif key.startswith("-"):
                key = key[1:]
        elif arg.startswith("--") or arg.startswith("-"):
            key = arg.lstrip("-")
            if i + 1 < len(argv) and not argv[i + 1].startswith("-") and "=" not in argv[i + 1]:
                val = argv[i + 1]
                i += 1
            else:
                val = "1"
        else:
            if os.path.exists(arg):
                if arg.endswith(".dem") or arg.endswith(".stim"):
                    args["fdem"] = arg
                elif arg.endswith(".mmx") or arg.endswith(".mtx"):
                    if args["finH"] is None:
                        args["finH"] = arg
                    elif args["finG"] is None and args["finL"] is None:
                        args["finG"] = arg
                    else:
                        args["ignored_files"].append(arg)
                else:
                    args["ignored_files"].append(arg)
            else:
                args["unrecognized"].append(arg)
            i += 1
            continue
 
        if key:
            key_lower = key.lower()
            if key_lower in ("cache", "cache_file", "cachefile"):
                if val.lower() in ("0", "none", "false", "off", "no"):
                    args["use_cache"] = False
                    args["cache_file"] = None
                else:
                    args["use_cache"] = True
                    args["cache_file"] = val
            elif key_lower in ("fdem", "dem"):
                args["fdem"] = val
            elif key_lower == "finh":
                args["finH"] = val
            elif key_lower == "fing":
                args["finG"] = val
            elif key_lower == "finl":
                args["finL"] = val
            elif key_lower == "fin":
                args["fin"] = val
            elif key_lower in ("hx", "finhx"):
                args["Hx"] = val
            elif key_lower in ("hz", "finhz"):
                args["Hz"] = val
            elif key_lower in ("lx", "finlx"):
                args["Lx"] = val
            elif key_lower in ("lz", "finlz"):
                args["Lz"] = val
            elif key_lower == "finc":
                args["finC"] = val
            elif key_lower == "outc":
                args["outC"] = val
                args["do_cws"] = True
            elif key_lower in ("method", "m"):
                args["method"] = int(val)
            elif key_lower in ("dmin", "d_min"):
                args["dmin"] = int(val)
            elif key_lower in ("dmax", "d_max"):
                args["dmax"] = int(val)
            elif key_lower == "dstop":
                args["dstop"] = int(val)
                if args["dstop"] < 0:
                    raise ValueError(f"invalid '{arg}': dstop must be non-negative")
            elif key_lower in ("wmin", "w_min"):
                args["wmin"] = int(val)
            elif key_lower in ("wmax", "w_max"):
                args["wmax"] = int(val)
            elif key_lower == "smax":
                args["smax"] = int(val)
            elif key_lower == "start":
                args["start"] = _normalize_start_list(val)
            elif key_lower in ("trust_start", "trust-start", "truststart"):
                args["trust_start"] = (
                    bool(int(val)) if val.isdigit() else (val.lower() not in ("0", "false", "no", "off"))
                )
            elif key_lower in ("start_scan", "start-scan", "startscan"):
                if val not in ("0", "1"):
                    raise ValueError(f"invalid '{arg}': start_scan should be 0 or 1")
                args["start_scan"] = val == "1"
            elif key_lower == "cbeg":
                args["cbeg"] = int(val)
            elif key_lower == "cend":
                args["cend"] = int(val)
            elif key_lower == "css":
                args["css"] = int(val)
            elif key_lower in ("dexp", "dest", "d_exp"):
                args["dexp"] = int(val)
            elif key_lower in ("steps", "num_steps", "nsteps"):
                args["steps"] = int(val)
            elif key_lower in ("threads", "num_threads", "t"):
                args["threads"] = int(val)
            elif key_lower in ("timeout", "time"):
                args["timeout"] = float(val)
            elif key_lower == "dw":
                args["dW"] = int(val)
            elif key_lower in ("maxc", "max_c"):
                args["maxC"] = int(val)
            elif key_lower == "pmin":
                args["pmin"] = float(val)
            elif key_lower in ("merge", "expand"):
                if val.lower() in ("1", "true", "yes", "on"):
                    args[key_lower] = True
                elif val.lower() in ("0", "false", "no", "off"):
                    args[key_lower] = False
                else:
                    raise ValueError(f"invalid '{arg}': {key_lower} should be 0 or 1")
            elif key_lower in ("sort_rows", "sort-rows", "sortrows"):
                if val.lower() in ("1", "true", "yes", "on"):
                    args["sort_rows"] = True
                elif val.lower() in ("0", "false", "no", "off"):
                    args["sort_rows"] = False
                else:
                    raise ValueError(f"invalid '{arg}': sort_rows should be 0 or 1")
            elif key_lower in ("cc_prune", "cc-prune", "ccprune"):
                if val not in ("0", "1", "2"):
                    raise ValueError(f"invalid '{arg}': cc_prune should be 0, 1, or 2")
                args["cc_prune"] = int(val)
            elif key_lower == "ortho":
                if val not in ("0", "1"):
                    raise ValueError(f"invalid '{arg}': ortho should be 0 or 1")
                args["ortho"] = val == "1"
            elif key_lower == "drop":  # (the values take precedence over files with these names, as in the binary)
                if val.lower() in ("1", "true", "yes", "on", "auto"):
                    args["drop"] = True  # drop=auto
                elif val.lower() in ("0", "false", "no", "off"):
                    args["drop"] = False
                elif val.lower() == "css":
                    args["drop"] = "css"
                else:
                    args["drop"] = val  # a file with the detectors to drop
            elif key_lower == "outd":
                args["outD"] = val
            elif key_lower in ("out-reduced", "out_reduced", "outreduced"):
                if val.lower() in ("0", "false", "no", "off", "none"):
                    args["out_reduced"] = None
                elif val.lower() in ("1", "true", "yes", "auto", ""):
                    args["out_reduced"] = True
                else:
                    args["out_reduced"] = val
            elif key_lower in ("morehelp", "more-help", "more_help"):
                _add_help_topic(val)  # (morehelp=1: the full help)
            elif key_lower in ("help", "h"):
                if val in ("", "1"):
                    args["help"] = True
                else:
                    _add_help_topic(val)  # help=TOPIC: the same as morehelp=TOPIC
            elif key_lower == "noscan":
                args["noscan"] = int(val)
            elif key_lower == "irred":  # (disabled: ignored with a warning, see _warn_cli_conflicts())
                args["irred"] = int(val)
            elif key_lower == "classical":
                args["classical"] = int(val)
            elif key_lower == "seed":
                args["seed"] = int(val)
            elif key_lower in ("debug", "dbg"):
                args["debug"] |= parse_debug_value(val)  # OR-combined (the default is 0)
            elif key_lower == "solver":
                args["solver"] = val
            elif key_lower == "engine":
                args["engine"] = val
            elif key_lower in ("verbose", "v"):
                args["verbose"] = bool(int(val)) if val.isdigit() else (val.lower() not in ("0", "false", "no", "off"))
            elif key_lower == "cws":
                args["do_cws"] = bool(int(val)) if val.isdigit() else (val.lower() not in ("0", "false", "no"))
            elif key_lower in ("nothrottle", "no_throttle"):
                args["nothrottle"] = (
                    bool(int(val)) if val.isdigit() else (val.lower() not in ("0", "false", "no", "off"))
                )
            elif key_lower in ("chunk_size", "chunksize", "batch", "chunk"):
                args["chunk_size"] = int(val)
            elif key_lower == "ksub":
                args["ksub"] = int(val)
            elif key_lower in ("kwin", "win"):
                args["kwin"] = int(val)
            elif key_lower in ("win_mode", "winmode"):
                args["win_mode"] = int(val)
            elif key_lower in ("win_hyb", "winhyb"):
                args["win_hyb"] = int(val)
                if args["win_hyb"] < 0:
                    raise ValueError(f"invalid '{arg}': win_hyb should be 0 (256 columns for a DEM, 512 for "
                                     f"matrices) or positive")
            elif key_lower == "pairs":
                args["pairs"] = int(val)
                if not -1 <= args["pairs"] <= 64:
                    raise ValueError(f"invalid '{arg}': pairs should be -1 (auto), 0 (off), or 1 to 64 (random pivot "
                                     f"rows of the buckets)")
            elif key_lower in ("min_hits", "minhits", "max_hits", "maxhits"):
                args["min_hits"] = int(val)
            elif key_lower in ("cov_cws", "covcws"):
                args["cov_cws"] = int(val)
            elif key_lower == "refresh":
                args["refresh"] = int(val)
            elif key_lower in ("simple", "simplified", "full"):  # disabled since version 0.13.0 (ignored, a warning)
                args["full" if key_lower == "full" else "simple"] = (
                    bool(int(val)) if val.isdigit()
                    else (val.lower() not in ("0", "false", "no", "off"))
                )
            elif key_lower == "basis":
                if val.upper() not in ("X", "Z"):
                    raise ValueError(
                        f"Invalid basis '{val}'; must be 'X' or 'Z'."
                    )
                args["basis"] = val.upper()
            elif key_lower == "rounds":
                args["rounds"] = int(val)
            elif key_lower in ("p_noise", "p-noise", "pnoise"):
                args["p_noise"] = float(val)
                if not 0.0 <= args["p_noise"] <= 0.5:
                    raise ValueError(f"invalid '{arg}': the noise strength must be in [0, 0.5]")
            elif key_lower in ("force_noise", "force-noise", "forcenoise", "force"):
                args["force_noise"] = (
                    bool(int(val)) if val.isdigit() else (val.lower() not in ("0", "false", "no", "off"))
                )
            elif key_lower in ("out-dir", "out_dir", "outdir"):
                args["out_dir"] = val
            elif key_lower in ("out-dem", "out_dem", "outdem"):
                if val.lower() in ("0", "false", "no", "off", "none"):
                    args["out_dem"] = None
                elif val.lower() in ("1", "true", "yes", "auto", ""):
                    args["out_dem"] = True
                else:
                    args["out_dem"] = val
            elif key_lower in ("model-lb", "model_lb", "modellb"):
                args["model_lb"] = (
                    bool(int(val)) if val.isdigit() else (val.lower() not in ("0", "false", "no", "off"))
                )
            elif key_lower in ("model-minority", "model_minority", "modelminority"):
                args["model_minority"] = (
                    bool(int(val)) if val.isdigit() else (val.lower() not in ("0", "false", "no", "off"))
                )
            elif key_lower in ("out-model", "out_model", "outmodel"):
                args["out_model"] = val
            elif key_lower in ("out-stim", "out_stim", "outstim"):
                if val.lower() in ("0", "false", "no", "off", "none"):
                    args["out_stim"] = None
                elif val.lower() in ("1", "true", "yes", "auto", ""):
                    args["out_stim"] = True
                else:
                    args["out_stim"] = val
            else:
                args["unrecognized"].append(arg)
 
        i += 1
 
    # Auto-infer classical mode when not explicitly set (matching src/util_io.c)
    if args["classical"] == -1:
        if (
            args["finG"] is not None or args["finL"] is not None
            or args["Hz"] is not None or args["Lz"] is not None
            or args["Lx"] is not None
            or args["fdem"] is not None or args["fin"] is not None
        ):
            args["classical"] = 0
        elif args["finH"] is not None or args["Hx"] is not None:
            args["classical"] = 1
 
    return args
 
 
def print_cli_short_help(file: Optional[Any] = None) -> None:
    text = f"""dist_m4ri.py (version {__version__}): Multithreaded distance calculator Python CLI
Usage: dist_m4ri.py [key=val | --flag val ...]
 
Allowed parameters:
  fdem, finH, finG, finL, fin, Hx, Hz, Lx, Lz, pmin, merge, drop, outD,
  --out-reduced, classical, --simple, --full, basis, --rounds, --out-dir,
  --out-dem, --out-stim, --p-noise, --force-noise, --model-lb, --model-minority,
  --out-model, method, dmin, dmax, dstop, dexp (dest), steps, wmin, wmax,
  timeout, threads, nothrottle, chunk_size (batch), ksub, kwin (win), win_mode,
  win_hyb, pairs, min_hits, cov_cws, refresh, smax, noscan, start, start_scan,
  cbeg, cend, finC, outC, maxC, expand, dW, irred, seed, debug, solver, engine,
  cache, --no-cache, --verbose, --silent, --cws, --trust-start, sort_rows,
  cc_prune, ortho
 
Help options:
  -h, --help    : display help for commonly used parameters (fits 80 rows; --help TOPIC: as --morehelp TOPIC)
  --morehelp    : display full help for all available parameters (or for TOPIC: --morehelp TOPIC)
  --version     : display the versions of dist_m4ri.py and of the dist_m4ri binary
"""
    print(text, file=file)
 
 
def print_cli_help(file: Optional[Any] = None) -> None:
    help_text = f"""dist_m4ri.py (version {__version__}): Multithreaded distance calculator Python CLI
Usage: dist_m4ri.py [key=val | --flag val ...]
 
Input matrices & models:
  fdem=FILE             Detector Error Model (.dem) or Stim circuit (.stim) file
  finH=FILE             Parity check matrix H (classical) or Hx (CSS quantum) (.mmx/.mtx)
  finG=FILE, finL=FILE  Hz check matrix or Lx logical operator matrix (quantum CSS)
  fin=PREFIX            Base prefix for CSS matrices (loads ${{fin}}X.mtx, ${{fin}}Z.mtx, e.g. try -> tryX.mtx)
  Hx=FILE, Hz=FILE      CSS check matrices, both required (computes dX and dZ)
  Lx=FILE, Lz=FILE      CSS logical operators (optional, constructed if omitted)
  pmin=PROB             Minimum error probability threshold for DEM errors (default: 0.0)
  merge=0|1             Merge equal DEM columns (exact; codewords use the first one) (default: 1)
  drop=auto|0|css|FILE  DEM detectors to drop if verified exact: auto=1 (default), 0 (none), css, or a file
  outD=FILE             Write the DEM detectors dropped (0-based) to FILE
  --out-reduced [PFX]   Save the reduced DEM and its maps to the DEM: PFX_red.dem and PFX_red.json
  classical=0|1         1: classical code (finH only), 0: quantum CSS (auto-detected)
  basis=X|Z             Override primary memory basis ('X' or 'Z') for .stim circuits (with drop=css)
  --rounds [N]          Set the REPEAT count of a .stim circuit (N=2 if omitted; warns if no REPEAT)
  --out-dir DIR         Output directory for saved .dem/.stim files (default: input file dir)
  --out-dem [FILE]      Save constructed DEM (default: <basename>_full.dem)
  --out-stim [FILE]     Save processed/noisy Stim circuit (default: <basename>_full.stim)
  --p-noise P           Strength of the noise added to a noiseless .stim circuit (default: 0.001; 0: none)
  --force-noise         Replace the noise of a .stim circuit by that of --p-noise (with P=0: remove it)
  --model-lb            Certified lower bound for a .stim circuit from its code-sized model
  --model-minority      With --model-lb, also the rows of the minority-basis checks (default: off)
 
Method and distance bounds:
  method=1|2|3          1=RW (upper bound), 2=CC (lower bound/exact), 3=Bracketing (default: 3)
  dmin=N                Certified lower bound, inclusive (CC starts from dmin) (default: 0)
  dmax=N                Known upper bound, inclusive (CC up to w=dmax-1 only) (default: 0)
  dstop=N               Stop once CC certifies dmin>=dstop (not an upper bound) (default: 0)
  dexp=N                Expected distance estimate (alias: dest) (default: 0)
 
Search limits and stopping criteria:
  steps=N               Maximum RW steps / information sets (default: 100000)
  wmax=N                Maximum cluster weight to search in CC (0=until bound/timeout)
  wmin=N                Stop immediately if cw with weight <= wmin is found (default: 1)
  min_hits=N            Stop RW when lowest-weight cws are hit N times on average (default: 5)
  timeout=SEC           Execution timeout in seconds, 0 for infinite (default: 60.0)
 
Multithreading & execution:
  threads=N             Max worker threads (default: all logical CPUs; throttled unless nothrottle=1)
  solver=NAME           Distance solver backend: 'dist_m4ri' (default), 'cert', 'auto', or 'codedistance' (also engine=)
 
Codeword collection & caching:
  --cws                 Collect and output non-trivial minimum-weight codewords
  outC=FILE             Save output codewords (for CSS, auto-suffixed _X.nz / _Z.nz)
  finC=FILE             Input initial candidate codewords (.nz file)
  expand=0|1            DEM codewords: list all choices among equal columns (merge) (default: 0)
  cache=FILE            Persistent JSON cache file (default: tmp_dist_cache.json)
  --no-cache / nocache  Disable persistent JSON caching
  --verbose / -v        Explain bounds, steps, cache status, and miss probability estimates
  --silent / -q         No warnings on stderr for the inputs which are ignored
 
Extra parameters (see --morehelp for details):
  smax=N (0)            Max syndrome weight for CC confinement profile (0 to disable)
  start=LIST (-1)       Expert: CC from listed columns only, e.g. start=0,48 (also start_scan=1; see --morehelp)
  --trust-start         Expert: accept start-list results as valid (copied to main cache record)
  noscan, cbeg, cend    Disabled in Python (ignored with a warning; also irred=0, --simple, --full)
  ortho=0|1 (1)         Expert: 0 skips the check H G^T = 0 of G (valid only if it holds)
  sort_rows=0|1         Sort the rows of H by weight for CC (default: 1 for matrices, 0 for a DEM)
  cc_prune=0|1|2 (1)    CC search: 0 first-row walk, 1 branch and bound, 2 also cover bounds
  nothrottle=1 (0)      Disable automatic thread throttling (also --no-throttle)
  chunk_size=N (0)      Max RW batch per claim (default: 0 for adaptive 25-500, alias: batch)
  ksub=N (0)            EXPERIMENTAL, do not use: RW subspace sketch dimension (0: full matrix)
  kwin=N (0)            RW localized window size (0: auto/hybrid for n>=500, -1: none, alias: win)
  win_mode=0|1 (0)      RW window metric: 0=Tanner graph BFS, 1=index proximity
  win_hyb=N (0)         Hybrid RW window size (0: 256 for a DEM, 512 for matrices)
  pairs=N (-1)          RW pairs of non-pivot columns (p=2; -1: auto, 0: off)
  cov_cws=N (100)       Number of lowest-weight cws used for the min_hits statistic
  refresh=N (5000)      Basis refresh interval in RW steps (experimental ksub only; 0 = off)
  maxC=N (0)            Maximum number of codewords to collect (0: unlimited)
  dW=N (0)              Extra weight window above dmin to collect codewords
  seed=N (0)            Random number generator seed
  debug=N (0)           Debug bitmap, OR-combined (1: summary, 2: progress, 4: status, ...)
 
Help options:
  -h, --help [TOPIC]    Display this help message (with TOPIC: the same as --morehelp TOPIC)
  --morehelp [TOPIC]    Display full help for all parameters (or only for TOPIC, e.g., maxC or windows)
  --version             Display the versions of dist_m4ri.py and of the dist_m4ri binary
"""
    print(help_text, file=file)
 
 
def _cli_morehelp_text() -> str:
    """The full help text of the CLI (--morehelp)."""
    return f"""dist_m4ri.py (version {__version__}): Multithreaded distance calculator Python CLI
Usage: dist_m4ri.py [key=val | --flag val ...]
 
Required input (at least one matrix/model specification):
  fdem=FILE             Detector Error Model (.dem) or Stim circuit (.stim) file.
                        Automatically constructs parity check H and logical L matrices.  An error
                        channel which stim cannot write as independent errors (e.g., PAULI_CHANNEL_1
                        without Y errors) is converted with approximate_disjoint_errors=True (only the
                        probabilities change).
  finH=FILE             Parity check matrix file in Matrix Market (.mmx / .mtx) format.
                        For classical codes, this is check matrix H. For CSS codes, Hx.
  finG=FILE             Generator / Hz matrix for quantum CSS codes in Matrix Market format.
  finL=FILE             Logical operator matrix Lx for quantum CSS codes in Matrix Market format.
                        Note: For a quantum CSS code, either finL (Lx) or finG (Hz) is required.
  fin=PREFIX            Base prefix for CSS matrices (loads ${{fin}}X.mtx and ${{fin}}Z.mtx, e.g. try -> tryX.mtx).
  Hx=FILE, Hz=FILE      CSS check matrices Hx and Hz, both required: computes both dX and dZ, and
                        d = min(dX, dZ) (finH=Hx with finG=Hz gives dZ only).
  Lx=FILE, Lz=FILE      Alternative syntax for specifying CSS logical operator matrices.
  ortho=0|1             Expert option (default: 1): 1, the dist_m4ri binary checks that the rows of H
                        and G (finG, fin without finL, or Hx and Hz in each sector of a CSS code without
                        Lx or Lz) are orthogonal, H G^T = 0, and stops with an error otherwise; 0 skips
                        the check (a warning is printed), e.g., to screen many codes which are
                        orthogonal by construction (the check takes O(nnz(G) times the column weight
                        of H) operations).  The result is valid only if H G^T = 0.  The cache key does
                        not depend on it.  No effect without G (a warning).
  pmin=PROB             Minimum error probability threshold for DEM parsing (default: 0.0).
                        Error mechanisms with probability < pmin are filtered out.  The column
                        indices (start, finC, outC) count only the error mechanisms kept: with
                        another pmin, the columns (and the codewords) change.
  merge=0|1             Merge the equal columns of the DEM (error mechanisms with the same detectors
                        and observables) in the dist_m4ri binary (default: 1).  Exact: dropping two
                        equal columns of a codeword gives a lighter one, so the distance does not
                        change (nor does the cache key).  Column indices (finC, outC, start) are those
                        of the DEM; the codewords found use the first one of each set of equal columns
                        (use merge=0 to enumerate the codewords with each of them, or expand=1 to
                        expand the list found).
  drop=auto|0|css|FILE  The detectors which the binary drops from the DEM if this is verified to be
                        exact (default: auto; drop=1 is the same as drop=auto; drop=0 keeps all
                        detectors).  Exact if every error touching them has a twin, an error with the
                        same other detectors which touches none of them (or none if it has no other
                        detector), with the same observables (or with L + A H for one matrix A):
                        then the distance of the DEM is found from the smaller DEM without these
                        detectors and the errors touching them, and the codewords found (outC) are
                        codewords of the DEM which use only errors touching no dropped detector.
                        drop=auto: the binary searches for the largest such set (with the same
                        observables) in the DEM alone, e.g., the minority-basis detectors of a CSS
                        circuit with the usual noise (see the README).  drop=css: for a Stim circuit
                        classified as CSS (including locally rotated CSS such as XZZX codes, by
                        ancilla and data basis tracking), its minority-basis detectors (the basis
                        other than the memory basis, see basis); otherwise (e.g., for a DEM),
                        drop=auto is used, with a warning.  drop=FILE: the detectors in FILE, for any
                        DEM (a text file with the 0-based detector indices, k for Dk, separated by
                        white space or commas; lines starting with '#' or '%' are comments; e.g.,
                        written by outD).  With css or FILE, if dropping the detectors is not exact, a
                        note is printed and the full DEM is used.  The values 0, 1, auto, and css take
                        precedence over files with these names (write ./1 for a file named 1).
  outD=FILE             Write the detectors dropped from the DEM by the binary to FILE (0-based, in
                        the format of a drop file; only the comment line '# 0 of M detectors
                        dropped ...' if none).  With a cached result, the binary is run only for
                        this (with dmin = dmax: no search).
  --out-reduced [PREFIX]
                        Save the DEM without the detectors dropped (see drop and outD) to
                        PREFIX_red.dem: the errors touching none of them (after the cutoff pmin, in
                        the order of the flattened DEM), with the other detectors numbered
                        consecutively.  Its maps to the DEM go to PREFIX_red.json: "detectors" (the
                        original index of each detector of the reduced DEM, i.e., those not in
                        outD), "errors" (the original index of each error, as the columns of outC),
                        "dropped", "num_detectors", "num_errors", "pmin", "source", "dem", "drop",
                        and "__version__" (also out_reduced=PREFIX; default PREFIX: the basename of
                        the input file, without _full or _simp, in --out-dir or the directory of
                        the input file).  The reduced DEM has the same distance, and its codewords
                        are mapped to codewords of the DEM by "errors".
  classical=0|1         Code type override:
                        1: Classical linear code (finH only; ignored with a warning if finG, finL,
                           fin, fdem, Hz, Lx, or Lz is given).
                        0: Quantum CSS code (requires logicals or Hz).
                        Default: auto-detected (1 if only finH is given; 0 otherwise).
  --simple / --full     Disabled since version 0.13.0 (also simple=1, full=1): accepted for backward
                        compatibility, but ignored with a warning to stderr.  The DEM of a Stim circuit
                        always has all detectors: the binary drops detectors if this is exact (see
                        drop; e.g., the minority-basis detectors which --simple stripped), which is
                        as fast and gives the distance of the full DEM (the stripped DEM only gives a
                        lower bound when dropping them is not exact).
  basis=X|Z             Explicitly set primary memory basis ('X' or 'Z') for .stim circuits
                        (default: auto-detected from filename or initial/final resets/measurements);
                        with drop=css, the detectors of the other basis are dropped if this is exact
                        (otherwise only used for the --verbose report; ignored with a warning).
  --rounds [N]          Construct DEM from a .stim circuit with N repetitions in its REPEAT block
                        (default: 2 when --rounds is given without a number; also rounds=N).
                        Issues a warning and continues with the original circuit if no REPEAT block.
  --out-dir DIR         Output directory for saving constructed DEM and/or processed Stim circuit
                        files (also out_dir=DIR; default: directory of the input .stim/.dem file).
  --out-dem [FILE]      Save constructed (flattened) DEM to FILE. If given without a filename (or
                        out_dem=1), automatically saves as <basename>_full.dem.
                        The codewords (outC) index its error lines: save the DEM in the same run (a DEM
                        generated again from the circuit may differ, e.g., with another stim version).
  --out-stim [FILE]     Save processed (noisy, rounds-adjusted) Stim circuit to FILE. If given without
                        a filename (or out_stim=1), automatically saves as <basename>_full.stim.
  --p-noise P           Strength p of the uniform circuit-level noise added to a noiseless Stim circuit
                        (also p_noise=P; default: 0.001; 0: no noise is added, and then a noiseless
                        circuit gives no distance): DEPOLARIZE2(p) after two-qubit gates (CX, CZ,
                        XCY, SWAP, ISWAP, SQRT_XX, CXSWAP, ..., also II), DEPOLARIZE1(p/10) after
                        one-qubit gates (I, X, H, H_XY, S, SQRT_X, C_XYZ, ...), on the qubit of a
                        classically controlled gate (e.g., CX rec[-1] 5), and on the qubits idle since
                        the previous TICK, and X (Z) flips with probability p after Z-basis or Y-basis
                        (X-basis) resets and before measurements (before and after MR, MRX, MRY); the
                        multi-qubit measurements (MPP, MXX, MYY, MZZ) and Pauli product gates (SPP,
                        SPP_DAG) get no noise.  A circuit with noise (a noise channel, or a noisy
                        measurement such as M(0.001)) is used as is, unless --force-noise.  The
                        distance does not depend on p (unless pmin > 0), only on which faults exist.
  --force-noise         Replace the noise of a Stim circuit (also --force or force_noise=1): all of its
                        noise is removed (noise channels, measurement flip probabilities, heralded
                        noise; see stim's Circuit.without_noise()), and then the uniform noise of
                        --p-noise is added (none with --p-noise 0, e.g., to save the noiseless circuit
                        with --out-stim), e.g., to compare circuits with the same noise model.
  --model-lb            Certified lower bound on the distance of a Stim memory circuit (fdem=FILE.stim)
                        from its code-sized model, instead of the distance of its DEM (also
                        model_lb=1; see compute_model_lower_bound()): the detectors linked by shared
                        measurements, other than the final data measurements, form chains (one per
                        check of a memory circuit), and each chain gives a row of the model, the sum
                        of its detector rows (the chain of a check of the measured basis telescopes
                        to the parity of the final data measurements on the check; the chains of the
                        minority-basis checks only with --model-minority), with the equal columns
                        merged.  Each codeword of the DEM gives a model codeword of no larger weight,
                        so the model distance certified by CC is a lower bound on the circuit
                        distance; it ignores the timing within the rounds (not tight in general, e.g.,
                        5 for the bb_72 circuit of distance 6).  The binary runs on the model with the
                        measured-basis rows, then (with --model-minority) with all rows from that bound
                        (RW first; method, threads, timeout, steps, dstop, wmax, seed, nothrottle,
                        pairs, sort_rows, and cc_prune apply to each run).  The bound is stored as dmin
                        in the cache record of the DEM, and the bounds of the circuit are printed.
  --model-minority      With --model-lb, also the chains of the minority-basis checks are rows of the
                        model (also model_minority=1; default: off).  With depolarizing-type noise,
                        they do not raise the bound (a lightest model codeword has a version without
                        components of the other basis), but they may for other noise models.
  --out-model PREFIX    With --model-lb, write the model to PREFIX_HR.mtx and PREFIX_LR.mtx (also
                        out_model=PREFIX).
  (positional files)    A file name without a key (the file must exist): a .dem or .stim file is used
                        as fdem=FILE, and a .mtx or .mmx file as finH=FILE, or as finG=FILE if finH is
                        already given (and neither finG nor finL); other files are ignored.
  (conflicting inputs)  The input is selected in the order fdem, Hx/Hz (CSS code), and
                        finH/finG/finL/fin (fin only supplies the missing finH and finG, while the
                        binary ignores fin followed by finH, finG, or finL, and fin after them is an
                        error); the ignored inputs (e.g., matrices with fdem, pmin, merge, expand,
                        drop, or outD without fdem, basis, --p-noise, or --force-noise without a Stim
                        circuit, basis without drop=css, fin with finH, classical=1 with finG,
                        ortho=0 without G) give a warning (unless --silent).
 
Calculation method:
  method=1|2|3          Calculation method (default: 3):
                        1: Random Window (RW) algorithm (upper bound on distance).
                           Repeatedly samples random information sets to find low-weight
                           codewords. Fast for discovering small errors.
                        2: Connected Cluster (CC) algorithm (lower bound / exact distance).
                           Exhaustive cluster search finding certified lower bound dmin or
                           exact distance if run to completion.
                        3: Bracketing mode (concurrent RW and CC).
                           Dynamically allocates worker threads between CC (lower bound) and
                           RW (upper bound) to converge on the exact distance rapidly, based on
                           the measured CC and RW times, the bounds, and the remaining timeout.
 
Distance bounds and guidance:
  dmin=N                Known certified lower bound on distance (default: 0).
                        CC search begins at weight w = max(1, dmin).
  dmax=N                Known upper bound on distance (default: 0).
                        CC ends once dmin = dmax (with outC, after the rounds w = dmax..dmax+dW);
                        RW ignores candidate codewords of weight >= dmax unless collecting codewords
                        or needed for min_hits.  For a CSS code (Hx=, Hz=), dmax is a bound on
                        d = min(dX, dZ), not on either sector: it is used as dstop for both sectors.
  dstop=N               Stop target for the lower bound (default: 0 = off): the search (method=2
                        or 3) ends once CC has certified dmin >= dstop, unless a lighter codeword is
                        found.  Unlike dmax, dstop is not an upper bound and is not reported as dmax
                        (the bounds are 'dmin w steps' with dmin >= dstop, w: the lightest codeword
                        found, or 0); a cached lower bound dmin >= dstop answers the request without
                        a calculation.  E.g., dstop=U wmin=U-1 decides whether d >= U.
  dexp=N                Expected code distance estimate (alias: dest) (default: 0).
                        Hint for method=3: as long as RW has found no codeword, CC rounds at
                        w > dexp run only on threads which cannot run RW (CC pauses if RW can
                        use all threads); CC resumes once RW finds a codeword or ends.
 
Search limits and stopping criteria:
  steps=N               Maximum number of RW steps / information sets across all threads
                        (default: 100000).
  wmax=N                Maximum cluster weight to analyze in CC (default: 0 = until bound/timeout;
                        with method=2, a known dmax is used as wmax).
  wmin=N                Minimum distance threshold (default: 1).
                        If a codeword of weight w <= wmin is discovered, search halts immediately
                        (not when collecting codewords with outC or maxC).
  timeout=SEC           Execution timeout in seconds (default: 60.0; set 0 for infinite).
                        In method=3, it guides the CC vs RW thread balance, and a CC round predicted
                        not to finish in time is not started while RW runs (in method=2, and with
                        steps=0, it is started anyway: it may still find a codeword of weight dmin).
 
Multithreading & throttling:
  threads=N             Maximum number of worker threads to allocate (default: all logical CPUs
                        available to the process, i.e., its CPU affinity mask, e.g., with taskset).
                        Subject to automatic thread throttling unless nothrottle=1 is specified:
                        - Small codes, methods 1 and 3 (<= 4 threads for n < 60, or for m*n < 2e4
                          with a small RW workload m*n*steps < 5e7; otherwise <= 16 threads for
                          n < 150 or m*n < 1e5, if m*n*steps < 2e8; m: number of rows of H).
                          Method 2 starts 4 threads, and the others once a CC round takes longer
                          (predicted > 2 ms on the threads started, or running for 5 ms).
                        - Large memory matrices (above 15 MB of dense RW working memory per thread:
                          at most 32 RW threads, within a quarter of the physical memory).
                        - Small RW step counts (RW threads clamped to <= (steps + 9) / 10).
                        The last two limits apply to RW threads only: CC (method=2) is not
                        limited, and in method=3 CC rounds can use all threads.
                        CC rounds with few start columns per thread are split into work units
                        which also fix the first 1-3 cluster extensions (balanced load).
  nothrottle=1          Disable automatic thread throttling (also --no-throttle).
                        Forces allocation of the exact number of threads requested.
  chunk_size=N          Maximum RW batch claimed at once by a thread (default: 0 = adaptive
                        25-500). Near the end of the steps, batches shrink to at most
                        ceil(remaining / (4 * RW threads)) steps. Alias: batch=N.
  ksub=N                EXPERIMENTAL, should not be used (a warning is printed): subspace sketch
                        dimension for RW (default: 0 = full matrix).
                        Precomputes N = ker(H) once; each thread echelonizes a compact
                        ksub x n sampled subspace in L1/L2 cache (e.g. ksub=32 or 64).
                        Automatically falls back to ksub=0 if m < nu = dim(ker H) (a warning is
                        printed with --verbose or debug&1).  Each step reduces the span of ksub
                        distinct rows of N, so that a few codewords are found much more often than
                        others, and min_hits may end RW early.
  kwin=N                Localized column permutation window size W around a random seed
                        column j0, used in every RW step (alias: win=N).  Default: 0 = automatic
                        hybrid for n>=500: every other step uses an index window (win_mode=1) of
                        win_hyb columns, and the other steps uniform random permutations (also
                        for codewords which are not local in the column order).  kwin=-1 (any
                        negative value): no windows, uniform random permutations in every step.
  win_mode=0|1          Locality metric for kwin > 0: 0 = Tanner graph BFS neighbors
                        (default), 1 = contiguous column index window.
  win_hyb=N             Window size of the hybrid RW steps (kwin=0, n>=500; at most 3n/4).
                        Default: 0 = 256 columns for a DEM, 512 for matrices.  The window
                        columns come first in the elimination order; in a DEM, they are errors
                        close in time, which touch few detectors: windows of 192-256 columns find
                        circuit codewords 2-10 times faster than 512, and windows of one round of
                        columns much slower.  With --verbose (or debug&1), the binary prints the
                        rounds of a DEM (estimated from the time translation of its errors: D
                        detectors and L columns per round) and the codewords found by the
                        uniform and by the window steps.
  pairs=N               RW pairs of non-pivot columns (p=2, as in Lee-Brickell and Stern): a RW
                        step also finds the codewords with exactly two non-pivot columns,
                        checking only the pairs of columns which agree on N random pivot rows
                        (at most 64; 0 = off).  Default: -1 = auto, about one non-pivot column per
                        bucket, with fewer rows while a codeword of the weight of the upper bound
                        would be kept with probability below 0.8, but enough rows to keep the
                        pairs of a step within about the work of its elimination (e.g., at least
                        6 for large circuit DEMs while the upper bound is far above the
                        distance).  The pairs find the minimum-weight codewords of circuit DEMs
                        7-26 times faster, and lighter codewords of codes with a large distance.
                        Not with ksub.  With --verbose (or debug&1), the binary prints the pairs
                        checked per step and the codewords found by pairs and by single columns.
  min_hits=N            QDistRnd-style RW stopping criterion (default: 5, 0 = off; alias: max_hits).
                        Stops RW when the average number of hits <n> per codeword (by all RW steps,
                        with or without windows, and by CC or finC) reaches min_hits, both for the
                        codewords of the minimum weight found and for a representative set of
                        cov_cws lowest-weight codewords (heavier codewords are kept until enough
                        lighter ones are found).  A single codeword suffices.  A lighter codeword is
                        missed with probability about exp(-<n>), assuming that lighter codewords
                        are found at least as often.  With debug&1 (or --verbose), a warning is
                        printed at the end if the hit counts of codewords of the same weight are
                        strongly non-uniform (then exp(-<n>) is optimistic), together with an
                        information-set estimate (uniform random information sets) of the
                        probability to miss a lighter codeword and of the RW steps needed for 1%.
                        With --verbose, both estimates are always shown for a result which is not
                        certified.  With min_hits=0, RW records only the codewords lighter than the
                        upper bound (unless collecting codewords with outC, maxC, or --cws), so
                        that the repeated hits are not counted.
  cov_cws=N             Size of the representative set of lowest-weight codewords for min_hits
                        (default: 100; 0 = only the minimum weight).  Without outC and maxC, at
                        most cov_cws minimum-weight codewords are tracked (all if cov_cws=0).
                        With fewer minimum-weight codewords, a smaller cov_cws may stop RW
                        earlier.
  refresh=N             Periodic adaptive basis refresh interval in RW steps, only with the
                        experimental ksub > 0 (default: 5000 when ksub > 0, 0 to disable).
                        Re-echelonizes N and replaces one heavier basis row by a discovered
                        minimum-weight codeword.
 
Connected Cluster (CC) search options:
  smax=N                Maximum syndrome weight for confinement profile (default: 0).
                        When smax > 0, tracks minimum syndrome weights for each error weight.
                        When smax=0, confinement is not computed.  The binary disables it if
                        dmin > 1 (also a lower bound from the cache), as the small cluster weights
                        are then skipped.
  sort_rows=0|1         Sort the rows of H by increasing weight (stable) in the dist_m4ri binary
                        (default: the binary's, 1 for matrices and 0 for a DEM).  With cc_prune=0,
                        CC extends a cluster by the columns of the first row of its syndrome (in
                        row order), so that light rows first reduce the CC work for matrices with
                        very different row weights (e.g., 1.7-4x with the hook columns of an
                        extended CSS distance), while the detectors of a DEM are in time order,
                        which is better (use sort_rows=0 also for matrices exported from a DEM).
                        With cc_prune=1 or 2, the order of the rows only breaks ties.  The
                        distance, RW, and the cache key do not depend on the order of the rows; CC
                        enumerates the same codewords (outC), possibly in another order (with
                        cc_prune=0, also with other hit counts).
  cc_prune=0|1|2        The CC search of the dist_m4ri binary (with smax=0; default: the binary's,
                        1; also --cc-prune N).  0: the walk of the versions before 0.15.0, which
                        extends a cluster by the columns of the first unsatisfied row of its
                        syndrome.  1: the branch and bound: it branches on the unsatisfied row
                        with the fewest available columns, the columns of the earlier branches are
                        forbidden in the later ones (each codeword is found once: one CC hit), and
                        a branch is pruned by lower bounds on the number of columns needed (an
                        unsatisfied row without available columns, or a packing of unsatisfied
                        rows with disjoint sets of available columns).  2: also the coverage and
                        fractional cover bounds (fewer nodes, more work per node).  All values
                        find the same codewords and distances (doc/cc_completeness.tex); with the
                        expert start list (and start_scan=0), cc_prune=1 and 2 forbid the columns
                        listed before the start column.  The cache key does not depend on it.
  start=LIST            Expert option: comma-separated list of CC start columns (0-based), e.g.,
                        start=0,48,96 (default: -1 = all columns; start=N is a one-element list).
                        CC clusters are grown only from the listed columns, and they are NOT
                        limited to larger column indices.  Use, e.g., one column per block of a
                        quasi-cyclic code.  WARNING: dmin (and an exact result) is valid only if a
                        code symmetry maps every minimum-weight codeword to one containing a listed
                        column; dmax is always valid.  For DEM input, columns index the error
                        mechanisms in their order in the (flattened) DEM, after the pmin cutoff.
                        Results are cached under a separate key '<key>:start=a,b,c'; only dmax and
                        codewords are merged into the main cache record.  (Before version 0.10.0,
                        start=N limited CC to clusters started at column N using only larger
                        columns; this is now cbeg=N cend=N of the dist_m4ri binary.)
  start_scan=0|1        Expert option, with start (also --start-scan; default: 0): 1: a cluster grown
                        from a listed column c only uses the columns > c, as in the scan of all
                        columns.  WARNING: dmin is then valid only if a code symmetry maps every
                        minimum-weight codeword to one whose smallest column is listed, e.g., if
                        the listed columns are the smallest columns of the orbits of a group of code
                        automorphisms, one per orbit (start=0,l for the two blocks of a two-block
                        group-algebra code of length 2l over an abelian group).  The later start
                        columns then need much less work, the least if each orbit is a range of
                        consecutive columns.  Cached under '<key>:start=a,b,c:scan'.  Not for a DEM.
  --trust-start         Expert option (also trust_start=1): accept the start-list results as valid,
                        i.e., also merge dmin and rw_steps into the main cache record, and copy an
                        existing exact start-list record to the main record even if no calculation
                        is needed.  Only use it if the code symmetry assumption above holds.
  noscan, cbeg, cend    Disabled in the Python interface: accepted for backward compatibility, but
                        ignored with a warning to stderr.  These expert options of the dist_m4ri
                        binary do not give valid bounds on their own: noscan=1 runs CC only at
                        weight w=wmax (method=2); cbeg/cend limit CC start columns to a range for
                        split runs, where every column is eventually covered by one of the runs.
                        Run the dist_m4ri binary directly to use them (see its --morehelp).
 
Codeword collection and export:
  --cws                 Collect and display non-trivial minimum-weight codewords.
  outC=FILE             Export found codewords of weight up to min_w + dW (min_w: minimum weight
                        found) to file in .nz format.  In method=2/3, once the distance d is
                        known, CC rounds w = d..d+dW enumerate all such irreducible codewords
                        (see irred; unless the timeout is hit; for a DEM, up to the choice of
                        equal columns: see merge).
                        In CSS mode, automatically saves X-codewords to FILE_X.nz and
                        Z-codewords to FILE_Z.nz.  The codewords of the run are merged with the
                        cached ones; with finC=FILE (the same file), those already in FILE are kept
                        (also reducible ones recorded before version 0.14.8).
  finC=FILE             Import initial candidate codewords from file in .nz format.
                        In CSS mode (Hx=, Hz=), each sector reads its own file FILE_X.nz or FILE_Z.nz
                        if at least one of them exists and is not empty (a sector without its file
                        gets no input codewords); otherwise, FILE itself is given to both sectors
                        (the binary skips the codewords which are not valid in a sector).  If FILE
                        is the same file as outC, a missing or empty file is ignored.  The binary
                        replaces a reducible codeword by an irreducible part (see irred).
  maxC=N                Maximum number of codewords to collect (default: 0 = unlimited); with
                        expand=1, also the maximum number of codewords of the expanded list.
  dW=N                  Extra weight window above minimum distance to collect codewords
                        (w <= min_w + dW) (default: 0).
  irred=0|1             Disabled in the Python interface: irred=0, an expert option of the
                        dist_m4ri binary, is ignored with a warning to stderr.  Only irreducible
                        codewords are recorded (irred=1, the default of the binary): a codeword
                        which is the union of a codeword and a disjoint nonzero vector with zero
                        syndrome (e.g., a trivial weight-3 vector of a circuit DEM, from weight
                        d+3 on) is not.  Minimum-weight codewords are always irreducible.
  expand=0|1            Python only, for a DEM: list each codeword found once for every choice
                        among equal columns, which the binary merges (see merge; default: 0).  The
                        binary and the cache keep the merged list.  With dW <= 1, the expanded list
                        is that of merge=0 (with dW >= 2, merge=0 also lists lighter codewords with
                        two equal columns added).  The list grows quickly with the weight: with
                        maxC > 0, at most maxC codewords are written (a warning if some are dropped).
  (DEM codewords)       The indices refer to the error lines of the DEM in the order of the flattened
                        DEM, after the pmin cutoff.  For a Stim circuit, save the DEM with --out-dem in
                        the same run (a warning is printed otherwise): a DEM generated again from the
                        circuit may differ (e.g., with another stim version).
 
Distance caching (Python CLI):
  cache=FILE            Path to persistent JSON cache file (default: tmp_dist_cache.json).
  --no-cache / nocache  Disable reading and writing to the persistent JSON cache.
 
General options:
  solver=NAME, engine=NAME
                        Distance calculation engine: 'dist_m4ri' (default), 'cert' ('qec_cert'),
                        'auto' (delegates distance-only calls to qec_cert if installed), or
                        'codedistance'.
  --verbose / -v        Enable verbose output with detailed explanations of bounds,
                        timings, steps, and cache status (implies the debug bits 1, 2,
                        65536, and 131072).  For a RW upper bound which is not certified,
                        also estimates the probability that a lighter codeword was missed
                        (from the average hits <n>, and from uniform random information sets
                        with n, rank(H), and the RW steps), with the RW steps and time needed
                        for a 1% miss probability.
  --silent / -q         No warnings on stderr for the inputs which are ignored (e.g., matrices with
                        fdem, the options of the binary with solver=codedistance, or the options
                        not used with --model-lb); the warnings on the validity of a result are
                        still written.  In Python: set_silent().
  seed=N                Random number generator seed (default: 0; the binary replaces seed<=0 by
                        time(NULL) + 10*pid - 1000*seed).
  debug=N               Debug bitmap (default: 0), a decimal or hexadecimal (0x...) integer;
                        multiple debug arguments are OR-combined.  Bits 1 to 32768 are passed
                        to the dist_m4ri binary, which prints diagnostic output to stderr (see
                        its --morehelp; lower bits are more informative):
                          1: summary (input matrices, rounds of a DEM, RW windows, stop reason,
                             codeword statistics, codewords found by each kind of RW step),
                          2: progress (run plan, finished CC rounds, new upper bounds),
                          4: periodic status (after 1, 2, 4, ... s, then every 60 s),
                          8: thread allocation and timing, 16: code parameters (ranks, k),
                          32: codeword supports, 64: arguments, 128: matrices,
                          256: codeword dump, 2048: no size cutoff.
                        Bits 65536 and above are used by the Python wrapper only:
                          65536: dist_m4ri command lines and run times,
                          131072: cache messages,
                          262144: Stim circuit to DEM conversion details,
                          524288: keep (and list) the temporary files.
 
Option groups (--help GROUP prints all entries of GROUP):
  windows               kwin, win_mode, win_hyb
  stopping, stop        steps, wmin, timeout, min_hits, cov_cws
  bounds                dmin, dmax, dstop, dexp, wmax
  dem                   fdem, pmin, merge, drop, outD, --out-reduced, expand
  stim                  fdem, basis, --rounds, --out-dir, --out-dem, --out-stim, --p-noise,
                        --force-noise, --model-lb, --model-minority, --out-model
  matrices, matrix      finH, finG, finL, fin, Hx, Lx, classical, ortho
  codewords             --cws, outC, finC, maxC, dW, irred, expand
  threading             threads, nothrottle, chunk_size
  cache                 cache, --no-cache, --trust-start
  expert                start, start_scan, --trust-start, noscan
  experimental          ksub, refresh
 
Help options:
  -h, --help [TOPIC]    Display summary help message (fits 80 rows); with TOPIC, the same as
                        --morehelp TOPIC (also --help=TOPIC).
  --morehelp [TOPIC]    Display this full help message with all parameters, or only the entries of
                        TOPIC, e.g., --morehelp maxC (also --morehelp=TOPIC; several topics separated
                        by commas, e.g., maxC,dW; the names are case-insensitive, without '-' or '_'
                        (and '=VALUE' in --help=TOPIC and --morehelp=TOPIC: a separate argument with
                        '=' is not a TOPIC), and include aliases such as dest or batch; an unknown
                        name gives the closest names on stderr, and the exit code 1).  A group name
                        (see Option groups, also as singular or plural, e.g., window) gives all
                        entries of the group, and a parameter of a group also the other entries of
                        its group (see also).
  --version             Display the versions of dist_m4ri.py and of the dist_m4ri binary.
"""
 
 
def _help_entries(text: str) -> List[Tuple[str, List[str], Dict[str, str]]]:
    """
    The entries of a help text (see _cli_morehelp_text()): (section header, the lines of the entry, its names).  An
    entry starts with a line indented by 2 spaces (the names, then the description), and continues with the lines
    indented by more; a section header is a line without indentation ending with ':'.  The names (a dict: normalized
    name -> name as written) are those in the first column (e.g., 'Hx=FILE, Hz=FILE' -> Hx, Hz; '--no-cache /
    nocache'), without the values (FILE, [N], ...; but all words of a note such as '(DEM codewords)'), and the aliases
    in the description ('alias: dest', 'Alias: win=N', 'also --no-throttle', 'also rounds=N'); normalized: lowercase,
    without '-' and '_'.
    """
    import re
    entries: List[Tuple[str, List[str], Dict[str, str]]] = []
    section = ""
    for line in text.splitlines():
        if line and not line[0].isspace() and line.rstrip().endswith(":"):
            section = line.rstrip()
            continue
        m = re.match(r"^  (\S.*?)(?:\s{2,}|$)", line)
        if m:  # a new entry
            names: Dict[str, str] = {}
            for tok in re.split(r"[,/\s]+", m.group(1)):
                tok = tok.strip("()[]").split("=", 1)[0]
                # (not a value, e.g., FILE or N; all words of a note, e.g., '(DEM codewords)')
                if tok.strip("-") and (m.group(1).startswith("(") or not tok.isupper()):
                    names.setdefault(_help_name_key(tok), tok)
            entries.append((section, [line], names))
        elif line.startswith("   ") and entries:
            entries[-1][1].append(line)
    for _, lines, names in entries:
        desc = " ".join(s.strip() for s in lines)
        for a in re.findall(r"(?i)\balias(?:es)?:\s*(-{0,2}[\w-]+)", desc) + re.findall(r"\balso (--?[\w-]+)", desc) + \
                re.findall(r"\balso ([\w-]+)=", desc):
            names.setdefault(_help_name_key(a), a)
    return entries
 
 
def _help_name_key(name: str) -> str:
    """A name of a help entry normalized for matching (see _help_entries()): lowercase, without '-' and '_'."""
    return name.lower().replace("-", "").replace("_", "")
 
 
def _help_group_members(entry: Tuple[str, List[str], Dict[str, str]]) -> Optional[Set[str]]:
    """
    The normalized names of the members of a group (an entry of the section 'Option groups' of the full help: the
    names listed after its first column), or None for another entry.
    """
    import re
    section, lines, _ = entry
    if not section.startswith("Option groups"):
        return None
    m = re.match(r"^  \S.*?(?:\s{2,}|$)", lines[0])
    text = " ".join([lines[0][m.end():] if m else ""] + [s.strip() for s in lines[1:]])
    return {_help_name_key(t) for t in re.split(r"[,\s]+", text) if t.strip("-")}
 
 
def _help_group_key_match(gkey: str, key: str) -> bool:
    """Whether the topic key matches the name gkey of a group, also as singular or plural (e.g., window, windows)."""
    return key in (gkey, gkey + "s") or (gkey.endswith("s") and key == gkey[:-1])
 
 
def print_cli_morehelp(file: Optional[Any] = None, topic: Optional[str] = None) -> int:
    """
    Prints the full help of the CLI (--morehelp), or with `topic` (one or more names separated by commas, see
    _help_entries()) only the entries of these parameters, in the order of the full help under their section headers.
    A topic may also be a group of the section 'Option groups' (also as singular or plural, e.g., window): then all
    its members are printed; and an entry of a group also gives the other members of its groups and these groups
    (one level: 'see also').  Returns 0, or 1 if some topic has no entry (then the closest names are suggested on
    stderr).
    """
    import difflib
    text = _cli_morehelp_text()
    keys = [(t, _help_name_key(t.split("=", 1)[0])) for t in (s.strip() for s in (topic or "").split(","))]
    keys = [(t, k) for t, k in keys if k]
    if not keys:
        print(text, file=file)
        return 0
    entries = _help_entries(text)
    members = [_help_group_members(e) for e in entries]
    status = 0
    asked: Set[int] = set()
    for t, key in keys:
        found = [i for i, e in enumerate(entries)
                 if (key in e[2] if members[i] is None else any(_help_group_key_match(g, key) for g in e[2]))]
        if not found:
            names = {k: v for e in entries for k, v in e[2].items()}
            close = [names[k] for k in difflib.get_close_matches(key, list(names), n=5, cutoff=0.6)]
            hint = f"; did you mean {', '.join(close)}?" if close else ""
            sys.stderr.write(f"dist_m4ri.py: no help entry for '{t}'{hint} (--morehelp lists all parameters)\n")
            status = 1
        asked.update(found)
    chosen: Set[int] = set(asked)
    for g, mem in enumerate(members):  # the groups asked for or with a member asked for: the group and its members
        if mem is None:
            continue
        in_group = [i for i, e in enumerate(entries) if members[i] is None and mem & set(e[2])]
        if g in asked or asked & set(in_group):
            chosen.add(g)
            chosen.update(in_group)
    out: List[str] = []
    section = None
    for i in sorted(chosen):  # in the order of the full help, under their section headers
        sec, lines, _ = entries[i]
        if sec != section:
            if out:
                out.append("")
            out.append(sec)
            section = sec
        out.extend(lines)
    if out:
        print("\n".join(out), file=file)
    return status
 
 
def _warn_cli_conflicts(args: Dict[str, Any]) -> None:
    """
    Writes warnings to stderr for the CLI inputs which are ignored.  The input is selected in the order fdem (a DEM or
    a Stim circuit), Hx / Hz (a CSS code), and finH / finG / finL / fin (one sector of a quantum code, or a classical
    code); fin=PREFIX supplies only the missing finH (PREFIX + 'X.mtx') and finG (PREFIX + 'Z.mtx', unless finL).  The
    disabled options --simple and --full always give a warning (see _warn_disabled_simple_full()), and so does the
    expert option irred of the dist_m4ri binary, unless irred=1 (the codewords recorded are always irreducible).  The
    expert option ortho=0 gives a warning here for a DEM or a classical code (for a quantum code, see _warn_ortho()).
    """
    def given(*keys: str) -> List[str]:
        return [k for k in keys if args.get(k) is not None]
 
    _warn_disabled_simple_full(args.get("simple"), args.get("full"), cli=True)  # (not passed on)
    if args.get("irred") is not None and args["irred"] != 1:  # (not passed on: the binary's default irred=1)
        _warn_ignored(f"irred={args['irred']} is disabled in the Python interface (ignored: only irreducible "
                      f"codewords are recorded); use the dist_m4ri binary directly")
    stim_opts = [opt for opt, on in (("basis=", args.get("basis") is not None),
                                     ("--out-stim", args.get("out_stim") is not None),
                                     ("--p-noise", args.get("p_noise") is not None),
                                     ("--force-noise", bool(args.get("force_noise")))) if on]
    warns = []
    if args.get("fdem"):
        ign = given("finH", "finG", "finL", "fin", "Hx", "Hz", "Lx", "Lz")
        if ign:
            warns.append(f"fdem={args['fdem']} given: ignoring {', '.join(k + '=' for k in ign)}")
        if stim_opts and not str(args["fdem"]).endswith(".stim"):
            warns.append(f"{', '.join(stim_opts)}: only used for a Stim circuit (.stim); ignored")
        elif (args.get("basis") is not None and str(args.get("drop")).lower() != "css"
              and not args.get("verbose")):  # (with --verbose, the basis of the classification is reported)
            warns.append("basis=: only used with drop=css (the minority-basis detectors of a CSS circuit); ignored")
        if args.get("expand") and not (args.get("outC") or args.get("do_cws")):
            warns.append("expand=: only used with outC= or --cws; ignored")
    else:
        dem_opts = stim_opts + [opt for opt, on in (("--out-dir", args.get("out_dir") is not None),
                                                    ("--out-dem", args.get("out_dem") is not None)) if on]
        if (args.get("pmin") or 0.0) > 0.0:
            dem_opts.append("pmin=")
        if args.get("merge") is not None:
            dem_opts.append("merge=")
        if args.get("expand") is not None:
            dem_opts.append("expand=")
        if args.get("drop") is not None:
            dem_opts.append("drop=")
        if args.get("outD") is not None:
            dem_opts.append("outD=")
        if args.get("out_reduced") is not None:
            dem_opts.append("--out-reduced")
        if dem_opts:
            warns.append(f"{', '.join(dem_opts)}: only used with fdem= (a DEM or Stim circuit); ignored")
        if args.get("Hx") is not None or args.get("Hz") is not None:
            ign = given("finH", "finG", "finL", "fin")
            if ign:
                warns.append(f"Hx=/Hz= given (CSS code): ignoring {', '.join(k + '=' for k in ign)}")
        else:
            ign = given("Lx", "Lz")
            if ign:
                warns.append(f"{', '.join(k + '=' for k in ign)}: only used for a CSS code (Hx= and Hz=); ignored")
            ign = given("finH", "finG", "finL")
            if args.get("fin") is not None and ign:
                warns.append(f"fin={args['fin']} together with {', '.join(k + '=' for k in ign)}: the explicit file "
                             "names take precedence")
    if args.get("classical") == 1 and given("finG", "finL", "fin", "fdem", "Hz", "Lx", "Lz"):
        warns.append("classical=1 ignored: the input is a quantum code or a DEM")
    if args.get("ortho") is False:  # (a quantum code: compute_quantum_distance() and compute_css_distance() warn)
        quantum = bool(given("Hx", "Hz", "finG", "finL", "fin")) or args.get("classical") == 0
        if args.get("fdem") or not quantum:
            warns.append("ortho=0: only used for a quantum code with G (finG=, fin=, or Hx= and Hz=); ignored")
    if args.get("css") is not None:
        warns.append(f"css={args['css']}: not used by the Python interface (CSS codes only); ignored")
    for f in args.get("ignored_files") or []:
        warns.append(f"{f}: a positional file which is not used (not a .dem, .stim, .mtx, or .mmx file, or a third "
                     f"matrix file); ignored")
    if args.get("model_lb"):  # the code-sized model of a Stim circuit (compute_model_lower_bound())
        ign = [opt for opt, on in (("outC=", args.get("outC") is not None), ("finC=", args.get("finC") is not None),
                                   ("--cws", bool(args.get("do_cws")) and args.get("outC") is None),
                                   ("drop=", args.get("drop") is not None),
                                   ("outD=", args.get("outD") is not None),
                                   ("--out-reduced", args.get("out_reduced") is not None),
                                   ("--out-dir", args.get("out_dir") is not None),
                                   ("--out-dem", args.get("out_dem") is not None),
                                   ("--out-stim", args.get("out_stim") is not None),
                                   ("start=", args.get("start") is not None), ("dmin=", bool(args.get("dmin"))),
                                   ("dmax=", bool(args.get("dmax"))), ("dexp=", bool(args.get("dexp"))),
                                   ("maxC=", bool(args.get("maxC"))), ("dW=", args.get("dW", -1) >= 0),
                                   ("merge=", args.get("merge") is not None),
                                   ("expand=", args.get("expand") is not None),
                                   ("wmin=", args.get("wmin", 1) != 1), ("smax=", args.get("smax") is not None),
                                   ("noscan=", bool(args.get("noscan"))), ("cbeg=", args.get("cbeg") is not None),
                                   ("cend=", args.get("cend") is not None),
                                   ("--trust-start", bool(args.get("trust_start"))),
                                   ("start_scan=", bool(args.get("start_scan"))),
                                   ("chunk_size=", bool(args.get("chunk_size"))), ("ksub=", bool(args.get("ksub"))),
                                   ("kwin=", bool(args.get("kwin"))), ("win_mode=", bool(args.get("win_mode"))),
                                   ("win_hyb=", bool(args.get("win_hyb"))),
                                   ("min_hits=", args.get("min_hits") is not None),
                                   ("cov_cws=", args.get("cov_cws", 100) != 100),
                                   ("refresh=", args.get("refresh") is not None),
                                   ("solver=", args.get("solver") not in (None, "dist_m4ri")),
                                   ("engine=", args.get("engine") not in (None, "dist_m4ri"))) if on]
        if ign:
            warns.append(f"{', '.join(ign)}: not used with --model-lb; ignored")
    else:
        if args.get("out_model") is not None:
            warns.append("--out-model: only used with --model-lb; ignored")
        if args.get("model_minority"):
            warns.append("--model-minority: only used with --model-lb; ignored")
    for w in warns:
        _warn_ignored(w)
 
 
def main(argv: Optional[List[str]] = None) -> int:
    """The CLI (see print_cli_help()); with --silent, set_silent() is on during the run, and restored at its end."""
    report = _report_ignored
    try:
        return _main(argv)
    finally:
        set_silent(not report)
 
 
def _main(argv: Optional[List[str]] = None) -> int:
    if argv is None:
        argv = sys.argv[1:]
 
    try:
        args = parse_cli_args(argv)
    except ValueError as e:
        sys.stderr.write(f"Error: {e}\n")
        return 1
    if args.get("silent"):  # no warnings on the inputs which are ignored
        set_silent(True)
 
    if args.get("version"):
        print(f"dist_m4ri.py version {__version__}")
        bin_path, bin_ver, _ = _binary_version()
        if bin_ver is not None:
            print(f"dist_m4ri version {bin_ver} (binary '{bin_path}')")
        compat_warn = check_binary_compatibility()
        if compat_warn:
            print(f"dist_m4ri.py: {compat_warn}", file=sys.stderr)
        return 0
 
    if args.get("morehelp") or args.get("help"):
        compat_warn = check_binary_compatibility()
        if compat_warn:
            print(f"dist_m4ri.py: {compat_warn}", file=sys.stderr)
        if args.get("morehelp"):
            return print_cli_morehelp(topic=args.get("morehelp_topic"))
        print_cli_help()
        return 0
 
    if args.get("unrecognized"):
        for u in args["unrecognized"]:
            print(f"dist_m4ri.py: unrecognized parameter '{u}'", file=sys.stderr)
        print_cli_short_help(file=sys.stderr)
        return 255
 
    if (
        not args.get("fdem") and not args.get("finH")
        and not args.get("Hx") and not args.get("Hz") and not args.get("fin")
    ):
        print("dist_m4ri.py: no input matrix or model specified", file=sys.stderr)
        print_cli_short_help(file=sys.stderr)
        return 255
 
    _warn_cli_conflicts(args)
 
    # When finC and outC are identical, an empty or non-existent file is silently ignored (with a warning if verbose)
    # by the compute_*_distance() functions (for CSS codes, after checking the sector files finC_X and finC_Z)
 
    cache_file = args["cache_file"] if args["use_cache"] else None
    if not args["use_cache"]:
        disable_distance_cache()
 
    try:
        if args.get("model_lb"):  # the certified lower bound of a Stim circuit or DEM from its code-sized model
            if not args["fdem"] or not str(args["fdem"]).endswith((".stim", ".dem")):
                raise ValueError("--model-lb needs a Stim circuit (.stim) or DEM (.dem) (fdem=FILE)")
            bound, info = compute_model_lower_bound(
                circuit=args["fdem"],
                method=args["method"],
                threads=args["threads"],
                timeout=args["timeout"],
                num_steps=args["steps"],
                dstop=args["dstop"],
                wmax=args["wmax"],
                minority=args["model_minority"],
                pmin=args["pmin"],
                rounds=args["rounds"],
                p_noise=args["p_noise"] if args["p_noise"] is not None else 0.001,
                force_noise=args["force_noise"],
                out_model=args["out_model"],
                cache_file=cache_file,
                seed=args["seed"],
                debug=args["debug"],
                verbose=args["verbose"],
                nothrottle=args["nothrottle"],
                pairs=args["pairs"],
                sort_rows=args["sort_rows"],
                cc_prune=args["cc_prune"],
                return_info=True
            )
            if args["verbose"]:
                print("=== Code-Sized Model Lower Bound ===")
                print(f"  Model: {info.get('rows', 0)} rows ({info.get('rows_measured', 0)} chains of the "
                      f"measured-basis checks, {info.get('rows', 0) - info.get('rows_measured', 0)} other) x "
                      f"{info.get('cols', 0)} columns, from {info.get('dem_cols', 0)} error mechanisms and "
                      f"{info.get('detectors', 0)} detectors of the DEM.")
                if info["model_d_info"]:
                    print(f"  Model bounds (CC certifies dmin): {format_bounds_str(info['model_d_info'])}"
                          + (f"; measured-basis rows only: {format_bounds_str(info['measured_d_info'])}"
                             if info["measured_d_info"] and info["measured_d_info"] != info["model_d_info"] else ""))
                print(f"  Certified lower bound on the circuit distance: d >= {bound}.")
                print(f"  Circuit bounds (with the cache): {format_bounds_str(info['d_info'])}")
            print(format_bounds_str(info["d_info"]))
            return 0
 
        if args["fdem"]:
            res = compute_dem_distance(
                dem=args["fdem"],
                method=args["method"],
                threads=args["threads"],
                timeout=args["timeout"],
                num_steps=args["steps"],
                d_exp=args["dexp"],
                dmin=args["dmin"],
                dmax=args["dmax"],
                dstop=args["dstop"],
                wmin=args["wmin"],
                wmax=args["wmax"],
                smax=args["smax"],
                start=args["start"],
                cbeg=args["cbeg"],
                cend=args["cend"],
                noscan=args["noscan"],
                dW=args["dW"],
                maxC=args["maxC"],
                pmin=args["pmin"],
                merge=args["merge"] is not False,
                expand=bool(args["expand"]),
                drop=args["drop"],
                outD=args["outD"],
                out_reduced=args["out_reduced"],
                finC=args["finC"],
                outC=args["outC"],
                do_cws=args["do_cws"] or (args["outC"] is not None),
                cache_file=cache_file,
                solver=args["solver"],
                engine=args["engine"],
                seed=args["seed"],
                debug=args["debug"],
                verbose=args["verbose"],
                nothrottle=args["nothrottle"],
                chunk_size=args["chunk_size"],
                ksub=args["ksub"],
                kwin=args["kwin"],
                win_mode=args["win_mode"],
                win_hyb=args["win_hyb"],
                pairs=args["pairs"],
                sort_rows=args["sort_rows"],
                cc_prune=args["cc_prune"],
                min_hits=args["min_hits"],
                cov_cws=args["cov_cws"],
                refresh=args["refresh"],
                basis=args["basis"],
                rounds=args["rounds"],
                p_noise=args["p_noise"] if args["p_noise"] is not None else 0.001,
                force_noise=args["force_noise"],
                out_dir=args["out_dir"],
                out_dem=args["out_dem"],
                out_stim=args["out_stim"],
                trust_start=args["trust_start"],
                start_scan=args["start_scan"]
            )
            dist, d_info = res[0], res[1]  # (compute_*_distance() writes the codewords to outC)
 
            if args["verbose"]:
                print("=== DEM Distance Results ===")
                print(explain_bounds(
                    d_info, method=args["method"], label="DEM", stats=_last_run_stats, dstop=args["dstop"]
                ))
                print(f"  Summary bounds: {format_bounds_str(d_info)}")
            print(format_bounds_str(d_info))
            return 0
 
        if args.get("rounds") is not None:
            raise ValueError(
                "--rounds option is only supported for Stim circuit (.stim) inputs."
            )
 
        if args["Hx"] is not None or args["Hz"] is not None:
            res = compute_css_distance(
                Hx=args["Hx"],
                Hz=args["Hz"],
                Lx=args["Lx"],
                Lz=args["Lz"],
                method=args["method"],
                threads=args["threads"],
                timeout=args["timeout"],
                num_steps=args["steps"],
                d_exp=args["dexp"],
                dmin=args["dmin"],
                dmax=args["dmax"],
                dstop=args["dstop"],
                wmin=args["wmin"],
                wmax=args["wmax"],
                smax=args["smax"],
                start=args["start"],
                cbeg=args["cbeg"],
                cend=args["cend"],
                noscan=args["noscan"],
                dW=args["dW"],
                maxC=args["maxC"],
                finC=args["finC"],
                outC=args["outC"],
                do_cws=args["do_cws"] or (args["outC"] is not None),
                cache_file=cache_file,
                solver=args["solver"],
                engine=args["engine"],
                seed=args["seed"],
                debug=args["debug"],
                verbose=args["verbose"],
                nothrottle=args["nothrottle"],
                chunk_size=args["chunk_size"],
                ksub=args["ksub"],
                kwin=args["kwin"],
                win_mode=args["win_mode"],
                win_hyb=args["win_hyb"],
                pairs=args["pairs"],
                sort_rows=args["sort_rows"],
                cc_prune=args["cc_prune"],
                min_hits=args["min_hits"],
                cov_cws=args["cov_cws"],
                refresh=args["refresh"],
                trust_start=args["trust_start"],
                start_scan=args["start_scan"],
                ortho=args["ortho"]
            )
            dist, dx_info, dz_info = res[0], res[1], res[2]  # (the sector files outC_X / outC_Z are written by
            # compute_css_distance())
 
            # d = min(dX, dZ) is exact if its bounds coincide (a user dmax is a bound on d, see compute_css_distance)
            _, d_lo, d_hi, _ = _css_combine(tuple(dx_info), tuple(dz_info), args["dmax"])
            exact_tag = " (exact)" if (d_lo > 0 and d_lo == d_hi) else ""
            stops = [v for v in (args["dstop"], args["dmax"]) if v > 0]
            sector_stop = min(stops) if stops else 0
 
            if args["verbose"]:
                print("=== CSS Quantum Code Distance Results ===")
                if dx_info:
                    print("--- X-Component Distance (dX) ---")
                    print(explain_bounds(
                        dx_info, method=args["method"], label="dX",
                        stats=_last_css_stats.get("X"), dstop=sector_stop
                    ))
                    print(f"  dX bounds: {format_bounds_str(dx_info)}")
                if dz_info:
                    print("--- Z-Component Distance (dZ) ---")
                    print(explain_bounds(
                        dz_info, method=args["method"], label="dZ",
                        stats=_last_css_stats.get("Z"), dstop=sector_stop
                    ))
                    print(f"  dZ bounds: {format_bounds_str(dz_info)}")
                print("--- Overall CSS Code Distance ---")
                print(f"  d = min(dX, dZ) = {dist}{exact_tag}")
 
            dx_str = format_bounds_str(dx_info) if dx_info else "none"
            dz_str = format_bounds_str(dz_info) if dz_info else "none"
            print(f"dX: {dx_str}  dZ: {dz_str}  (d = {dist}){exact_tag}")
            return 0
 
        # Handle fin prefix (e.g. fin=examples/try -> tryX.mtx and tryZ.mtx)
        finH = args["finH"]
        finG = args["finG"]
        if args["fin"]:
            if finH is None: finH = f"{args['fin']}X.mtx"
            if finG is None and args["finL"] is None: finG = f"{args['fin']}Z.mtx"
 
        # Quantum single-sided distance (finH with finG or finL, or classical=0)
        if finH and (finG is not None or args["finL"] is not None or args["classical"] == 0):
            res = compute_quantum_distance(
                H=finH,
                G=finG,
                L=args["finL"],
                method=args["method"],
                threads=args["threads"],
                timeout=args["timeout"],
                num_steps=args["steps"],
                d_exp=args["dexp"],
                dmin=args["dmin"],
                dmax=args["dmax"],
                dstop=args["dstop"],
                wmin=args["wmin"],
                wmax=args["wmax"],
                smax=args["smax"],
                start=args["start"],
                cbeg=args["cbeg"],
                cend=args["cend"],
                noscan=args["noscan"],
                dW=args["dW"],
                maxC=args["maxC"],
                finC=args["finC"],
                outC=args["outC"],
                do_cws=args["do_cws"] or (args["outC"] is not None),
                return_info=True,
                cache_file=cache_file,
                solver=args["solver"],
                engine=args["engine"],
                seed=args["seed"],
                debug=args["debug"],
                verbose=args["verbose"],
                nothrottle=args["nothrottle"],
                chunk_size=args["chunk_size"],
                ksub=args["ksub"],
                kwin=args["kwin"],
                win_mode=args["win_mode"],
                win_hyb=args["win_hyb"],
                pairs=args["pairs"],
                sort_rows=args["sort_rows"],
                cc_prune=args["cc_prune"],
                min_hits=args["min_hits"],
                cov_cws=args["cov_cws"],
                refresh=args["refresh"],
                trust_start=args["trust_start"],
                start_scan=args["start_scan"],
                ortho=args["ortho"]
            )
            dist, d_info = res[0], res[1]  # (compute_*_distance() writes the codewords to outC)
 
            if args["verbose"]:
                print("=== Quantum Code Distance Results (Single-Sided) ===")
                print(explain_bounds(
                    d_info, method=args["method"], label="Quantum", stats=_last_run_stats, dstop=args["dstop"]
                ))
                print(f"  Summary bounds: {format_bounds_str(d_info)}")
            print(format_bounds_str(d_info))
            return 0
 
        # Classical distance (finH only or classical=1)
        if finH:
            res = compute_classical_distance(
                H=finH,
                method=args["method"],
                threads=args["threads"],
                timeout=args["timeout"],
                num_steps=args["steps"],
                d_exp=args["dexp"],
                dmin=args["dmin"],
                dmax=args["dmax"],
                dstop=args["dstop"],
                wmin=args["wmin"],
                wmax=args["wmax"],
                smax=args["smax"],
                start=args["start"],
                cbeg=args["cbeg"],
                cend=args["cend"],
                noscan=args["noscan"],
                dW=args["dW"],
                maxC=args["maxC"],
                finC=args["finC"],
                outC=args["outC"],
                do_cws=args["do_cws"] or (args["outC"] is not None),
                return_info=True,
                cache_file=cache_file,
                solver=args["solver"],
                engine=args["engine"],
                seed=args["seed"],
                debug=args["debug"],
                verbose=args["verbose"],
                nothrottle=args["nothrottle"],
                chunk_size=args["chunk_size"],
                ksub=args["ksub"],
                kwin=args["kwin"],
                win_mode=args["win_mode"],
                win_hyb=args["win_hyb"],
                pairs=args["pairs"],
                sort_rows=args["sort_rows"],
                cc_prune=args["cc_prune"],
                min_hits=args["min_hits"],
                cov_cws=args["cov_cws"],
                refresh=args["refresh"],
                trust_start=args["trust_start"],
                start_scan=args["start_scan"]
            )
            dist, d_info = res[0], res[1]  # (compute_*_distance() writes the codewords to outC)
 
            if args["verbose"]:
                print("=== Classical Code Distance Results ===")
                print(explain_bounds(
                    d_info, method=args["method"], label="Classical", stats=_last_run_stats, dstop=args["dstop"]
                ))
                print(f"  Summary bounds: {format_bounds_str(d_info)}")
            print(format_bounds_str(d_info))
            return 0
    except ValueError as e:
        sys.stderr.write(f"Error: {e}\n")
        return 1
 
    return 0
 
 
if __name__ == "__main__":
    sys.exit(main())