flopscope 0.2.0__py3-none-any.whl

flopscope/_accumulation/_cost_descriptions.py

@@ -0,0 +1,63 @@
+"""LaTeX and human-readable descriptions, built on demand from regime metadata."""
+
+from __future__ import annotations
+
+LATEX_BY_REGIME: dict[str, str] = {
+    "trivial": r"\alpha = M = |X| = \prod_{\ell \in L} n_\ell",
+    "functionalProjection": r"\alpha = M = |X / G|",
+    "singleton": (
+        r"\alpha = \frac{n_\Omega}{|G|}\sum_{g}\left(\prod_{c \in R} n_c\right)"
+        r"\left(n_\Omega^{c_\Omega(g)} - (n_\Omega-1)^{c_\Omega(g)}\right)"
+    ),
+    "young": r"\alpha = \binom{n_L+|V|-1}{|V|}\binom{n_L+|W|-1}{|W|}",
+    "partitionCount": (
+        r"\alpha = \sum_{\tilde{x}\in P_{\mathrm{typed}}(L)/G} "
+        r"\frac{\prod_s (n_s)_{b_s(\tilde{x})}}{|\overline{G}_{\tilde{x}}|}"
+        r"\,|A_{\tilde{x}}/H|"
+    ),
+    "unavailable": r"\alpha = \text{unavailable}",
+}
+
+LATEX_SYMBOLIC_BY_REGIME: dict[str, str] = {
+    "trivial": r"\alpha = M",
+    "functionalProjection": r"\alpha = M",
+    "singleton": r"\alpha = \#\{(O,Q): \pi_V(O)\cap Q\ne\varnothing\},\ |V|=1",
+    "young": r"\alpha = |\mathrm{Multiset}_n(V)|\,|\mathrm{Multiset}_n(W)|",
+    "partitionCount": r"\alpha = \#\{(O,Q): \pi_V(O)\cap Q\ne\varnothing\}",
+    "unavailable": r"\alpha = \text{unavailable}",
+}
+
+
+def describe_component(component) -> dict[str, str]:
+    """LaTeX strings for a single component."""
+    return {
+        "latex": LATEX_BY_REGIME.get(component.regime_id, ""),
+        "latex_symbolic": LATEX_SYMBOLIC_BY_REGIME.get(component.regime_id, ""),
+    }
+
+
+def describe_total(cost) -> dict:
+    """Summary dict for a whole-einsum AccumulationCost."""
+    return {
+        "total": cost.total,
+        "mu": cost.mu,
+        "alpha": cost.alpha,
+        "m_total": cost.m_total,
+        "dense_baseline": cost.dense_baseline,
+        "num_terms": cost.num_terms,
+        "savings_ratio": cost.savings_ratio,
+        "fallback_used": cost.fallback_used,
+        "unavailable_components": cost.unavailable_components,
+        "per_component": [
+            {
+                "labels": c.labels,
+                "m": c.m,
+                "alpha": c.alpha,
+                "regime_id": c.regime_id,
+                "shape": c.shape,
+                "group_name": c.group_name,
+                **c.describe(),
+            }
+            for c in cost.per_component
+        ],
+    }

flopscope/_accumulation/_detection.py

@@ -0,0 +1,318 @@
+"""σ-loop, π-canonical derivation, and whole-expression G_pt construction."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from flopscope._perm_group import _Permutation as Permutation
+
+from ._bipartite import BipartiteGraph, IncidenceMatrix
+from ._wreath import WreathElement
+
+
+@dataclass(frozen=True)
+class SigmaResult:
+    """One row of the σ-loop. Either σ is identity (skipped, π=identity), or σ is
+    non-identity and we either accepted a π or rejected (no fingerprint match)."""
+
+    is_valid: bool
+    is_identity: bool
+    skipped: bool
+    pi: dict[str, str] | None
+    pi_kind: Literal["identity", "v-only", "w-only", "cross-v-w"] | None
+    reason: str | None = None
+    sigma_row_perm: tuple[int, ...] | None = None
+
+
+def derive_pi_canonical(
+    sigma_col_of: dict[str, tuple[int, ...]],
+    fp_to_labels: dict[tuple[int, ...], frozenset[str]],
+    v_labels: frozenset[str],
+    w_labels: frozenset[str],
+) -> dict[str, str] | None:
+    """For each label, look up σ(M)'s column fingerprint in fp_to_labels and pick the
+    lex-first unused candidate. Validates bijectivity. Returns None when no
+    consistent π exists.
+
+    Note: π may legitimately mix V and W labels — cross-V/W actions are part of
+    the detected symmetry. The deprecated 'partition-preserving rejection' is NOT
+    reintroduced here. Mirrors algorithm.js#derivePi.
+    """
+    pi: dict[str, str] = {}
+    used: set[str] = set()
+    for label in sorted(v_labels | w_labels):
+        fp = sigma_col_of[label]
+        candidates = fp_to_labels.get(fp)
+        if not candidates:
+            return None
+        pick = next((c for c in sorted(candidates) if c not in used), None)
+        if pick is None:
+            return None
+        pi[label] = pick
+        used.add(pick)
+    return pi
+
+
+def classify_pi(
+    pi: dict[str, str],
+    v_labels: frozenset[str],
+    w_labels: frozenset[str],
+) -> dict[str, object]:
+    """Classify a π's action: identity, v-only (preserves W pointwise),
+    w-only (preserves V pointwise), or cross-v-w."""
+    pi_is_identity = all(pi[lbl] == lbl for lbl in pi)
+    moves_v = any(pi[lbl] != lbl for lbl in v_labels if lbl in pi)
+    moves_w = any(pi[lbl] != lbl for lbl in w_labels if lbl in pi)
+    crosses_vw = any(
+        (lbl in v_labels and pi[lbl] in w_labels)
+        or (lbl in w_labels and pi[lbl] in v_labels)
+        for lbl in pi
+    )
+
+    if pi_is_identity:
+        kind = "identity"
+    elif crosses_vw:
+        kind = "cross-v-w"
+    elif moves_v and not moves_w:
+        kind = "v-only"
+    elif moves_w and not moves_v:
+        kind = "w-only"
+    else:
+        kind = "cross-v-w"  # both V and W move, but no V↔W swap — still classified as cross
+
+    return {
+        "piIsIdentity": pi_is_identity,
+        "piKind": kind,
+        "crosses": crosses_vw,
+        "movesV": moves_v,
+        "movesW": moves_w,
+    }
+
+
+def run_sigma_loop(
+    graph: BipartiteGraph,
+    matrix_data: IncidenceMatrix,
+    wreath_elements: Sequence[WreathElement],
+) -> tuple[SigmaResult, ...]:
+    """Run the σ-loop: for each wreath element, derive π and classify it.
+    Mirrors algorithm.js#runSigmaLoop."""
+    results: list[SigmaResult] = []
+    v_labels = graph.free_labels
+    w_labels = graph.summed_labels
+    all_labels = graph.all_labels
+
+    for element in wreath_elements:
+        sigma_row_perm = tuple(element.row_perm.array_form)
+        is_identity = all(v == i for i, v in enumerate(sigma_row_perm))
+
+        if is_identity:
+            identity_pi = {lbl: lbl for lbl in all_labels}
+            results.append(
+                SigmaResult(
+                    is_valid=True,
+                    is_identity=True,
+                    skipped=True,
+                    pi=identity_pi,
+                    pi_kind="identity",
+                    sigma_row_perm=sigma_row_perm,
+                )
+            )
+            continue
+
+        # Compute σ(M) column fingerprints.
+        sigma_col_of: dict[str, tuple[int, ...]] = {}
+        for label in all_labels:
+            sigma_col_of[label] = tuple(
+                graph.incidence[sigma_row_perm[k]].get(label, 0)
+                for k in range(len(sigma_row_perm))
+            )
+
+        pi = derive_pi_canonical(
+            sigma_col_of, matrix_data.fp_to_labels, v_labels, w_labels
+        )
+        if pi is None:
+            results.append(
+                SigmaResult(
+                    is_valid=False,
+                    is_identity=False,
+                    skipped=False,
+                    pi=None,
+                    pi_kind=None,
+                    reason="No matching π (fingerprint mismatch)",
+                    sigma_row_perm=sigma_row_perm,
+                )
+            )
+            continue
+
+        classification = classify_pi(pi, v_labels, w_labels)
+        results.append(
+            SigmaResult(
+                is_valid=True,
+                is_identity=False,
+                skipped=False,
+                pi=pi,
+                pi_kind=classification["piKind"],  # type: ignore[arg-type]
+                sigma_row_perm=sigma_row_perm,
+            )
+        )
+
+    return tuple(results)
+
+
+# ── build_full_group ─────────────────────────────────────────────────
+
+
+import math
+
+from flopscope._perm_group import _dimino
+
+
+@dataclass(frozen=True)
+class DetectedGroup:
+    """The whole-expression G_pt."""
+
+    all_labels: tuple[str, ...]
+    generators: tuple[Permutation, ...]
+    elements: tuple[Permutation, ...]
+    group_name: str
+    action_summary: str
+    valid_pi_results: tuple[SigmaResult, ...]
+
+
+def _minimal_generators(
+    candidates: Sequence[Permutation],
+) -> list[Permutation]:
+    """Greedy minimal generating set: keep only generators that grow the closure."""
+    if len(candidates) <= 1:
+        return list(candidates)
+    selected: list[Permutation] = []
+    current_size = 1
+    for candidate in candidates:
+        trial = (*selected, candidate)
+        elements = _dimino(trial)
+        if len(elements) > current_size:
+            selected.append(candidate)
+            current_size = len(elements)
+    return selected
+
+
+def _classify_group_name(
+    labels: Sequence[str],
+    generators: Sequence[Permutation],
+    elements: Sequence[Permutation],
+) -> str:
+    """Mirror of fullGroup.js + algorithm.js#classifyGroupName.
+
+    Recognizes S_n, C_n, D_n, Z_2, S_2, and falls back to PermGroup⟨...⟩."""
+    order = len(elements)
+    degree = len(labels)
+    if degree < 2 or order <= 1:
+        return "trivial"
+
+    moved_set: set[int] = set()
+    for el in elements:
+        for i, v in enumerate(el.array_form):
+            if v != i:
+                moved_set.add(i)
+    moved_indices = sorted(moved_set)
+    moved_labels = [labels[i] for i in moved_indices] if moved_indices else list(labels)
+    effective_degree = len(moved_labels) or degree
+    label_set = "{" + ",".join(moved_labels) + "}"
+
+    if order == math.factorial(effective_degree):
+        return f"S{effective_degree}{label_set}"
+    if order == effective_degree and effective_degree >= 3:
+        # Cyclic check
+        for el in elements:
+            cycles = el.cyclic_form
+            if len(cycles) == 1 and len(cycles[0]) == effective_degree:
+                return f"C{effective_degree}{label_set}"
+    if order == 2 * effective_degree and effective_degree >= 3:
+        return (
+            f"D{effective_degree}{label_set}"  # heuristic — matches JS classification
+        )
+    if order == 2 and degree == 2:
+        return f"S2{label_set}"
+    if order == 2 and effective_degree > 2:
+        return f"Z2{label_set}"
+
+    # Fallback: build cycle notation inline using cyclic_form + label substitution
+    def _gen_cycle_str(gen: Permutation, lbl_list: Sequence[str]) -> str:
+        cycles = gen.cyclic_form
+        if not cycles:
+            return "()"
+        return "".join(
+            "(" + " ".join(lbl_list[idx] for idx in cycle) + ")" for cycle in cycles
+        )
+
+    gen_str = ", ".join(_gen_cycle_str(g, labels) for g in generators)
+    return f"PermGroup⟨{gen_str}⟩"
+
+
+def _action_summary(
+    pi_kinds_seen: set[str],
+) -> str:
+    """Summarize the action of G as 'V-only' / 'W-only' / 'cross-V/W' / 'trivial'."""
+    if not pi_kinds_seen or pi_kinds_seen <= {"identity"}:
+        return "trivial"
+    if "cross-v-w" in pi_kinds_seen:
+        return "cross-V/W"
+    if "v-only" in pi_kinds_seen and "w-only" in pi_kinds_seen:
+        return "V-only × W-only"
+    if "v-only" in pi_kinds_seen:
+        return "V-only"
+    if "w-only" in pi_kinds_seen:
+        return "W-only"
+    return "trivial"
+
+
+def build_full_group(
+    sigma_results: Sequence[SigmaResult],
+    *,
+    all_labels: Sequence[str],
+) -> DetectedGroup:
+    """Collect valid πs as full-degree permutations on `all_labels`, dedupe, find
+    a minimal generating set via greedy growth, run dimino. Mirrors fullGroup.js#buildFullGroup."""
+    label_idx = {lbl: i for i, lbl in enumerate(all_labels)}
+    candidates: list[Permutation] = []
+    seen_keys: set[tuple[int, ...]] = set()
+    pi_kinds_seen: set[str] = set()
+    valid: list[SigmaResult] = []
+
+    for r in sigma_results:
+        if not r.is_valid:
+            continue
+        if r.pi is not None:
+            valid.append(r)
+        if r.skipped or r.pi_kind == "identity":
+            if r.pi_kind is not None:
+                pi_kinds_seen.add(r.pi_kind)
+            continue
+        if r.pi is None:
+            continue
+        if r.pi_kind is not None:
+            pi_kinds_seen.add(r.pi_kind)
+        arr = tuple(label_idx[r.pi[lbl]] for lbl in all_labels)
+        if arr in seen_keys:
+            continue
+        seen_keys.add(arr)
+        candidates.append(Permutation(list(arr)))
+
+    minimal = _minimal_generators(candidates)
+    if minimal:
+        elements = _dimino(tuple(minimal))
+    else:
+        elements = [Permutation.identity(len(all_labels))] if all_labels else []
+
+    group_name = _classify_group_name(all_labels, minimal, elements)
+
+    return DetectedGroup(
+        all_labels=tuple(all_labels),
+        generators=tuple(minimal),
+        elements=tuple(elements),
+        group_name=group_name,
+        action_summary=_action_summary(pi_kinds_seen),
+        valid_pi_results=tuple(valid),
+    )

flopscope/_accumulation/_ladder.py

@@ -0,0 +1,191 @@
+"""Regime ladder dispatcher and supporting data types.
+
+The ladder runs per-component:
+    Stage 1: trivial short-circuit (|G| ≤ 1)
+    Stage 2a: functionalProjection takes priority (covers shape ∈ {allVisible, allSummed,
+              and mixed-but-functional})
+    Stage 2b: mixed regimes ladder — singleton, young, partitionCount
+    Fallthrough: 'unavailable' (brute-force orbit B.8 is excluded by policy)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Literal, cast
+
+from flopscope._perm_group import _Permutation as Permutation
+
+from ._shape import Shape
+
+RegimeId = Literal[
+    "trivial",
+    "functionalProjection",
+    "singleton",
+    "young",
+    "partitionCount",
+    "unavailable",
+]
+
+Decision = Literal["fired", "refused"]
+
+
+@dataclass(frozen=True)
+class RegimeContext:
+    """Input to a regime's recognize() and compute()."""
+
+    labels: tuple[str, ...]
+    va: tuple[str, ...]
+    wa: tuple[str, ...]
+    elements: tuple[Permutation, ...]
+    generators: tuple[Permutation, ...]
+    sizes: tuple[int, ...]
+    visible_positions: tuple[int, ...]
+    partition_budget: int
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """Output of regime.recognize()."""
+
+    fired: bool
+    reason: str
+
+
+@dataclass(frozen=True)
+class RegimeOutput:
+    """Output of regime.compute()."""
+
+    count: int
+    sub_steps: tuple[dict, ...] = ()
+
+
+@dataclass(frozen=True)
+class Regime:
+    """A regime is identified by id and consists of recognize + compute callables."""
+
+    id: RegimeId
+    recognize: Callable[[RegimeContext], Verdict]
+    compute: Callable[[RegimeContext], RegimeOutput]
+
+
+@dataclass(frozen=True)
+class RegimeStep:
+    """One entry in the regime-dispatch trace."""
+
+    regime_id: RegimeId
+    decision: Decision
+    reason: str
+    sub_steps: tuple[dict, ...] = ()
+
+
+@dataclass(frozen=True)
+class AccumulationResult:
+    """Output of compute_accumulation() — the ladder's primitive output for one
+    component. Reused by future reduction-cost.
+
+    `count` is None when regime_id == 'unavailable' (partition budget exceeded
+    with brute-force disabled by policy)."""
+
+    count: int | None
+    regime_id: RegimeId
+    shape: Shape
+    trace: tuple[RegimeStep, ...]
+
+
+# ── Dispatcher ───────────────────────────────────────────────────────
+
+
+import math
+
+from flopscope._config import get_setting
+
+from ._regimes import FUNCTIONAL_PROJECTION_REGIME, MIXED_REGIMES
+from ._shape import detect_shape
+
+
+def compute_accumulation(
+    *,
+    labels: Sequence[str],
+    va: Sequence[str],
+    wa: Sequence[str],
+    elements: Sequence[Permutation],
+    generators: Sequence[Permutation],
+    sizes: Sequence[int],
+    visible_positions: Sequence[int],
+    partition_budget: int | None = None,
+) -> AccumulationResult:
+    """Run the regime ladder for a single component.
+
+    Stages mirror accumulationCount.js:
+      1. trivial short-circuit for |G| <= 1
+      2a. functionalProjection priority check (covers shape allVisible/allSummed
+          and mixed-but-functional)
+      2b. mixed-shape ladder: singleton, young, partitionCount
+
+    Returns AccumulationResult with count=None when no regime fires within
+    the partition budget (brute-force orbit B.8 is excluded by policy).
+    """
+    if partition_budget is None:
+        partition_budget = cast(int, get_setting("partition_budget"))
+
+    shape = detect_shape(va=va, wa=wa, elements=elements)
+
+    # Stage 1: trivial short-circuit
+    if not elements or len(elements) <= 1:
+        return AccumulationResult(
+            count=math.prod(sizes) if sizes else 1,
+            regime_id="trivial",
+            shape=shape,
+            trace=(RegimeStep("trivial", "fired", "|G| = 1"),),
+        )
+
+    ctx = RegimeContext(
+        labels=tuple(labels),
+        va=tuple(va),
+        wa=tuple(wa),
+        elements=tuple(elements),
+        generators=tuple(generators),
+        sizes=tuple(sizes),
+        visible_positions=tuple(visible_positions),
+        partition_budget=partition_budget,
+    )
+
+    trace: list[RegimeStep] = []
+
+    # Stage 2a: functionalProjection priority
+    verdict = FUNCTIONAL_PROJECTION_REGIME.recognize(ctx)
+    if verdict.fired:
+        out = FUNCTIONAL_PROJECTION_REGIME.compute(ctx)
+        trace.append(
+            RegimeStep(
+                "functionalProjection",
+                "fired",
+                verdict.reason,
+                out.sub_steps,
+            )
+        )
+        return AccumulationResult(
+            out.count, "functionalProjection", shape, tuple(trace)
+        )
+    trace.append(RegimeStep("functionalProjection", "refused", verdict.reason))
+
+    # Stage 2b: mixed-shape ladder
+    for regime in MIXED_REGIMES:
+        verdict = regime.recognize(ctx)
+        if not verdict.fired:
+            trace.append(RegimeStep(regime.id, "refused", verdict.reason))
+            continue
+        out = regime.compute(ctx)
+        trace.append(RegimeStep(regime.id, "fired", verdict.reason, out.sub_steps))
+        return AccumulationResult(out.count, regime.id, shape, tuple(trace))
+
+    # Fallthrough: brute-force is excluded by policy → unavailable
+    trace.append(
+        RegimeStep(
+            "unavailable",
+            "fired",
+            "no exact regime fired within partition budget; brute-force disabled by policy",
+        )
+    )
+    return AccumulationResult(None, "unavailable", shape, tuple(trace))

flopscope/_accumulation/_output_orbit.py

@@ -0,0 +1,104 @@
+"""H = Stab_G(V)|_V helpers and canonical tuple operations.
+
+Permutation convention matches `_perm_group.py`: source -> target arrays.
+For tuple action: out[perm.arr[source]] = tuple[source].
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+
+from flopscope._perm_group import _Permutation as Permutation
+
+
+def tuple_array_key(tup: Sequence) -> str:
+    """Stable string key for a tuple, used for orbit dedup. Mirrors JS tupleArrayKey."""
+    return "|".join(str(v) for v in tup)
+
+
+def preserves_position_set(perm: Permutation, positions: Sequence[int]) -> bool:
+    """True iff perm maps the position set into itself (setwise stabilizer test)."""
+    position_set = set(positions)
+    for source in positions:
+        if perm.array_form[source] not in position_set:
+            return False
+    return True
+
+
+def restrict_to_positions(
+    perm: Permutation, positions: Sequence[int]
+) -> Permutation | None:
+    """Restrict perm to the given positions, returning a local-coordinate Permutation.
+    Returns None when perm doesn't preserve the position set.
+    """
+    if not preserves_position_set(perm, positions):
+        return None
+    local_index = {
+        global_pos: local_pos for local_pos, global_pos in enumerate(positions)
+    }
+    arr = [local_index[perm.array_form[global_source]] for global_source in positions]
+    return Permutation(arr)
+
+
+def restrict_stabilizer_to_positions(
+    elements: Iterable[Permutation], positions: Sequence[int]
+) -> tuple[Permutation, ...]:
+    """Restrict every G element that preserves `positions` to the local action on `positions`.
+    Deduplicates by string key (kernel of restriction collapses to one local element)."""
+    degree = len(positions)
+    if degree == 0:
+        return (Permutation.identity(0),)
+
+    by_key: dict[str, Permutation] = {}
+    for element in elements:
+        restricted = restrict_to_positions(element, positions)
+        if restricted is not None:
+            by_key[",".join(str(v) for v in restricted.array_form)] = restricted
+
+    if not by_key:
+        identity = Permutation.identity(degree)
+        return (identity,)
+
+    return tuple(by_key.values())
+
+
+def apply_permutation_to_tuple_array(tup: Sequence, perm: Permutation) -> list:
+    """Apply perm to a tuple under the source-to-target convention:
+    out[perm.array_form[source]] = tup[source].
+    Mirrors JS applyPermutationToTupleArray.
+    """
+    next_tuple: list = [None] * len(tup)
+    for source in range(len(tup)):
+        next_tuple[perm.array_form[source]] = tup[source]
+    return next_tuple
+
+
+def canonical_tuple_under_group(tup: Sequence, elements: Iterable[Permutation]) -> str:
+    """Return the lex-smallest tuple key over the orbit of `tup` under `elements`."""
+    elements_tuple = tuple(elements)
+    if not elements_tuple:
+        return tuple_array_key(tup)
+    best: str | None = None
+    for element in elements_tuple:
+        moved = apply_permutation_to_tuple_array(tup, element)
+        key = tuple_array_key(moved)
+        if best is None or key < best:
+            best = key
+    assert best is not None
+    return best
+
+
+def visible_tuple_from_full_tuple(
+    full_tuple: Sequence, visible_positions: Sequence[int]
+) -> list:
+    """Project a full assignment tuple to its visible-label coordinates."""
+    return [full_tuple[position] for position in visible_positions]
+
+
+def projection_is_functional(
+    elements: Iterable[Permutation], visible_positions: Sequence[int]
+) -> bool:
+    """True iff every g in elements preserves the visible position set as a set.
+    When True, projection π_V descends to a well-defined map X/G → Y/H.
+    """
+    return all(preserves_position_set(g, visible_positions) for g in elements)