exceptional

quiverlab.tautilting.exceptional

tau-exceptional sequences (Buan-Marsh) via the Jasso tau-perpendicular reduction (Plan 65 / R27; Buan-Marsh J. Algebra 585 (2021); Jasso IMRN 2015; Demonet-Iyama-Jasso 2019).

Over a tau-tilting-finite A = kQ/I the signed tau-exceptional sequences are built on the shipped P45 tau-tilting engine:

• a length-1 signed tau-exceptional object is either an indecomposable tau-rigid module (M, +) or a shifted projective (P_v[1], -) (one per vertex);
• a complete signed tau-exceptional sequence (M_1, ..., M_n) has, at one end, a signed object M of A, and the remaining n-1 terms form a complete signed tau-exceptional sequence of the reduction algebra C(M) -- the Jasso tau-perpendicular category J(M) ~ mod C(M), of rank n - |M|.

The reduction dispatches on the SIGN of the outer object (H2):

• tau-rigid module U -> the DIJ idempotent quotient C(U) = End(T_U)/<e_U> (T_U a genuine tau-tilting module -- an empty-support exchange-graph vertex -- with U in add T_U). We build End(T_U) in the hom_basis and quotient by the two-sided ideal generated by the summand projector e_U at the structure-constant level, THEN present the quotient (presented_form). This sidesteps a fragile vertex-identification in the presented End(T_U) (H5): the quotient is intrinsic and C(S_1) of kA_3 comes out kA_2 (connected, dim 3), not k x k (dim 2).

The algebra C(U) is completion-DEPENDENT (H-1). Different tau-tilting completions T_U of the SAME U give End(T_U)/<e_U> of different dimension / quiver (live- proved on kD4). Only the CATEGORY J(U), hence the invariant #sTt(C(U)), is completion-independent (DIJ) -- and the enumeration relies ONLY on #sTt. We pick the first empty-support completion in BFS order (deterministic) and self-certify: when a second completion exists, #sTt(C(U)) over it must match (a loud raise otherwise). So the returned algebra is one valid presentation of C(U); the trustworthy datum is its #sTt. - shifted projective P_v[1] -> the support quotient C(P_v[1]) = A/<e_v> (delete vertex v), with F the tautological restriction mod(A/<e_v>) ~ {M in mod A : M_v = 0} (Recollement.i_upper_star).

Enumeration is the Buan-Marsh ordered-support-tau-tilt bijection: #(complete signed tau-exceptional sequences) = n! * #(support tau-tilting pairs), with #sTt = len(exchange_graph(A).vertices) from P45. It is NOT a mutation-BFS (mutation transitivity is proven only in rank 2, Buan-Hanson-Marsh arXiv:2402.10301). The formula identity signed_count == n! * #sTt is a SELF-CERT (tautological); the genuine cross-check is the materialisation of the reduction towers (want_sequences=True): their number equals signed_count, they are pairwise distinct, and each is recognized.

Honest gates (M1): the count is trustworthy only from a status="complete" exchange graph; status in {"budget","error"} -> a loud refusal report, never a count off a non-complete graph. tau-tilting-infinite -> refusal. Char <= dim over GF(p) -> the shipped decompose/is_isomorphic/presented_form caveat raises loudly.

TauExcObject dataclass

TauExcObject(sign: int, module: object = None, vertex: object = None)

A length-1 signed tau-exceptional object: sign = +1 for an indecomposable tau-rigid module (module), sign = -1 for a shifted projective P_vertex[1] (module = None, vertex set).

dvt

dvt()

A hashable signature: (sign, dim-vector-tuple) for a module; (sign, ('P', vertex)) for a shifted projective.

Source code in src/quiverlab/tautilting/exceptional.py

def dvt(self):
    """A hashable signature: (sign, dim-vector-tuple) for a module; (sign, ('P', vertex))
    for a shifted projective."""
    if self.sign < 0:
        return (-1, ("P", self.vertex))
    dv = self.module.dimension_vector()
    return (1, tuple(dv[w] for w in sorted(dv)))

TauExcReport dataclass

TauExcReport(algebra: object, n: int, signed_count: int = 0, stt_count: int = 0, sequences: list | None = None, is_complete: bool = False, status: str = 'unsupported', note: str = '')

The signed tau-exceptional-sequence report of a tau-tilting-finite algebra (Plan 65 / R27).

TauReduction dataclass

TauReduction(reduction_algebra: object, bongartz: object = None, u_vertices: object = None, kind: str = 'tau_rigid', equivalence: object = None)

The Jasso tau-perpendicular reduction C(U) of a signed object U (Plan 65 / R27). reduction_algebra is a genuine kQ'/I' Algebra of rank n - |U|; kind is "tau_rigid" (DIJ End(T_U)/<e_U>) or "shifted" (A/<e_v>); bongartz is the tau-tilting completion T_U (the pair, tau-rigid case) or None; u_vertices records the killed summand indices / the deleted vertex; equivalence is the object-transport mod C(U) -> J(U) inverse (a callable, shifted case only -- the cheap restriction; None for the tau-rigid case, whose deep lift is scope-bounded -- see the module docstring).

exceptional_sequences_block

exceptional_sequences_block(A, budget=4096)

The shared exceptional_sequences compute block (Plan 65 Task G1): the CLASSICAL hereditary surface (counts + braid-orbit transitivity + Dynkin closed form, if hereditary) AND the tau-exceptional surface (the signed count n!*#sTt, if tau-tilting-finite), each honest about applicability. Sequences themselves are NOT shipped (they explode -- D_4 has 162 classical / 1200 signed); the block reports counts + status. Presentation-less -> a typed error dict, never a 500.

DoS cap (H-3). budget caps the tau exchange-graph BFS -- the only unbounded axis (a non-hereditary tau-tilting-INFINITE input would otherwise grind). The block default is a SANE 4096 (not the 100_000 library default, which stays on :meth:Algebra.tau_exceptional_sequences). The classical side is NEVER a DoS (it refuses a rep-infinite hereditary input INSTANTLY via Gabriel, and a non-hereditary one is N/A), so it uses its own generous internal tuple budget regardless of budget.

Shared by hpc/spec.py and docs/gui/runner.py so the blocks are byte-identical.

Source code in src/quiverlab/tautilting/exceptional.py

def exceptional_sequences_block(A, budget=4096):
    """The shared ``exceptional_sequences`` compute block (Plan 65 Task G1): the CLASSICAL
    hereditary surface (counts + braid-orbit transitivity + Dynkin closed form, if
    hereditary) AND the tau-exceptional surface (the signed count ``n!*#sTt``, if
    tau-tilting-finite), each honest about applicability. Sequences themselves are NOT
    shipped (they explode -- ``D_4`` has 162 classical / 1200 signed); the block reports
    counts + status. Presentation-less -> a typed error dict, never a 500.

    **DoS cap (H-3).** ``budget`` caps the tau exchange-graph BFS -- the only unbounded axis
    (a non-hereditary tau-tilting-INFINITE input would otherwise grind). The block default is
    a SANE ``4096`` (not the ``100_000`` library default, which stays on
    :meth:`Algebra.tau_exceptional_sequences`). The classical side is NEVER a DoS (it refuses
    a rep-infinite hereditary input INSTANTLY via Gabriel, and a non-hereditary one is N/A),
    so it uses its own generous internal tuple budget regardless of ``budget``.

    Shared by ``hpc/spec.py`` and ``docs/gui/runner.py`` so the blocks are byte-identical."""
    if getattr(A, "quiver", None) is None:
        return {"error": ("exceptional sequences require a quiver-presented algebra kQ/I "
                          "(a structure-constant-only algebra has no exceptional-sequence "
                          "surface)"),
                "references": list(_EXC_REFERENCES)}
    from quiverlab.invariants.dynkin_type import dynkin_type
    from quiverlab.invariants.recognizers import is_hereditary
    n = _rank(A)
    dt = dynkin_type(A.quiver)
    dtype_str = f"{dt[0]}_{dt[1]}" if (dt and dt[0] in ("A", "D", "E")) else None
    hereditary = bool(is_hereditary(A))
    notes = []

    classical = None
    if hereditary:
        rep = A.exceptional_sequences(budget=100_000)   # self-caps; never a DoS (Gabriel gate)
        classical = {"count": rep.count, "closed_form_count": rep.closed_form_count,
                     "transitive": rep.transitive, "complete": rep.is_complete,
                     "status": rep.status}
        if rep.note:
            notes.append(rep.note)
    else:
        notes.append("not hereditary: the classical (braid-orbit) surface does not apply")

    trep = A.tau_exceptional_sequences(budget=max(budget, 512), want_sequences=False)
    tau = None
    if trep.is_complete:
        tau = {"signed_count": trep.signed_count, "stt_count": trep.stt_count,
               "complete": trep.is_complete, "status": trep.status}
    else:
        notes.append("tau-exceptional: " + (trep.note or "not tau-tilting-finite"))

    return {"kind": "exceptional_sequences", "n": n,
            "hereditary": hereditary, "dynkin_type": dtype_str,
            "classical": classical, "tau": tau,
            "note": ("; ".join(notes) if notes else None),
            "references": list(_EXC_REFERENCES)}

is_tau_exceptional_sequence

is_tau_exceptional_sequence(A, seq)

True iff seq is a complete-or-partial signed tau-exceptional sequence of A (Plan 65 / R27; the (inner, ..., outer) convention -- the outer term is the reduced-away end seq[-1]).

Two input forms are accepted:

• a reduction tower (a list of :class:_TowerEntry, as produced by :func:tau_exceptional_sequences): verified rung-by-rung;
• an ambient sequence (a list of :class:Module / :class:TauExcObject): recognized recursively -- the outer signed object reduces, the remaining terms are transported into C(outer) and recognized there. Over a hereditary A an all-module sequence is recognized by the classical criterion (the Buan-Marsh coincidence, tau-exc = classical exc for hereditary).

Source code in src/quiverlab/tautilting/exceptional.py

def is_tau_exceptional_sequence(A, seq):
    """True iff ``seq`` is a complete-or-partial signed tau-exceptional sequence of ``A``
    (Plan 65 / R27; the ``(inner, ..., outer)`` convention -- the outer term is the
    reduced-away end ``seq[-1]``).

    Two input forms are accepted:

    - a **reduction tower** (a list of :class:`_TowerEntry`, as produced by
      :func:`tau_exceptional_sequences`): verified rung-by-rung;
    - an **ambient sequence** (a list of :class:`Module` / :class:`TauExcObject`): recognized
      recursively -- the outer signed object reduces, the remaining terms are transported
      into ``C(outer)`` and recognized there. Over a hereditary ``A`` an all-module sequence
      is recognized by the classical criterion (the Buan-Marsh coincidence, tau-exc =
      classical exc for hereditary)."""
    _require_quiver(A, "is_tau_exceptional_sequence")
    seq = list(seq)
    if not seq:
        return True
    if all(isinstance(e, _TowerEntry) for e in seq):
        return _verify_tower(A, seq)
    return _recognize_ambient(A, seq)

tau_exceptional_objects

tau_exceptional_objects(A, *, budget=512)

The length-1 signed tau-exceptional objects of A (Plan 65 / R27): every indecomposable tau-rigid module (sign +1, from the exchange-graph module universe) plus one shifted projective P_v[1] per vertex (sign -1). Requires a tau-tilting-finite A for the module part (loud refusal otherwise).

Source code in src/quiverlab/tautilting/exceptional.py

def tau_exceptional_objects(A, *, budget=512):
    """The length-1 signed tau-exceptional objects of ``A`` (Plan 65 / R27): every
    indecomposable **tau-rigid** module (sign ``+1``, from the exchange-graph module
    universe) plus one **shifted projective** ``P_v[1]`` per vertex (sign ``-1``). Requires a
    tau-tilting-finite ``A`` for the module part (loud refusal otherwise)."""
    _require_quiver(A, "tau_exceptional_objects")
    if _provably_tau_tilting_infinite(A):
        raise QuiverlabError(
            "tau_exceptional_objects: a hereditary connected non-Dynkin algebra is "
            "representation-infinite (Gabriel), hence tau-tilting-infinite; the tau-rigid "
            "module universe is infinite")
    from quiverlab.tautilting.mutation import exchange_graph
    eg = exchange_graph(A, budget_pairs=budget)
    if eg.status != "complete":
        raise QuiverlabError(
            "tau_exceptional_objects: the exchange graph is not complete "
            f"(status={eg.status!r}); the tau-rigid module universe is unavailable "
            "(tau-tilting-infinite or a P45 mutation failure)")
    return _objects_from_eg(A, eg)

tau_exceptional_sequences

tau_exceptional_sequences(A, *, budget=4096, want_sequences=True, _reverse_objects=False)

The complete signed tau-exceptional sequences of a tau-tilting-finite A (Plan 65 / R27). The count is the ordered-support-tau-tilt bijection signed_count = n! * #sTt with #sTt = len(exchange_graph(A).vertices) -- computed WITHOUT enumerating, so it is exact even when materialisation is budget-capped.

want_sequences=True also MATERIALISES the reduction towers (the H1 cross-check: len(sequences) == signed_count, pairwise distinct, each recognized), capped at budget towers (signed_count stays exact via the formula). Returns a :class:TauExcReport.

Gate (M1): only a status="complete" exchange graph yields a count; status in {"budget","error"} -> an honest refusal report, NEVER a count off a non-complete graph.

Source code in src/quiverlab/tautilting/exceptional.py

def tau_exceptional_sequences(A, *, budget=4096, want_sequences=True, _reverse_objects=False):
    """The complete signed tau-exceptional sequences of a **tau-tilting-finite** ``A``
    (Plan 65 / R27). The count is the ordered-support-tau-tilt bijection
    ``signed_count = n! * #sTt`` with ``#sTt = len(exchange_graph(A).vertices)`` -- computed
    WITHOUT enumerating, so it is exact even when materialisation is budget-capped.

    ``want_sequences=True`` also MATERIALISES the reduction towers (the H1 cross-check:
    ``len(sequences) == signed_count``, pairwise distinct, each recognized), capped at
    ``budget`` towers (``signed_count`` stays exact via the formula). Returns a
    :class:`TauExcReport`.

    Gate (M1): only a ``status="complete"`` exchange graph yields a count; ``status in
    {"budget","error"}`` -> an honest refusal report, NEVER a count off a non-complete graph."""
    _require_quiver(A, "tau_exceptional_sequences")
    from quiverlab.tautilting.mutation import exchange_graph
    n = _rank(A)
    if _provably_tau_tilting_infinite(A):
        return TauExcReport(
            A, n, 0, 0, None, False, "budget",
            "hereditary connected non-Dynkin => representation-infinite (Gabriel) => "
            "tau-tilting-infinite; the signed tau-exceptional count is infinite (no count "
            "derived)")
    eg = exchange_graph(A, budget_pairs=max(budget, 512))
    if eg.status != "complete":
        note = ("the exchange graph is not complete "
                f"(status={eg.status!r}); tau-tilting-infinite or a P45 mutation failure -- "
                "no signed tau-exceptional count is derived from a non-complete graph (M1)")
        status = eg.status if eg.status in ("budget", "error") else "unsupported"
        return TauExcReport(A, n, 0, 0, None, False, status, note)
    stt = len(eg.vertices)
    signed = factorial(n) * stt
    if not want_sequences:
        return TauExcReport(A, n, signed, stt, None, True, "complete", "")
    if signed > budget:
        return TauExcReport(
            A, n, signed, stt, None, True, "complete",
            f"materialisation capped: signed_count={signed} > budget={budget}; the count is "
            "exact via the bijection formula, sequences not materialised")
    towers = _enumerate_towers(A, eg, reverse=_reverse_objects)
    note = ""
    if len(towers) != signed:                           # a genuine reduction bug -> loud note
        note = (f"materialised {len(towers)} towers != signed_count {signed} -- a bug in the "
                "tau-perpendicular reduction or object enumeration (report it)")
    return TauExcReport(A, n, signed, stt, towers, True, "complete", note)

tau_perpendicular_reduction

tau_perpendicular_reduction(A, U, *, budget=512, certify=True, _eg=None)

The Jasso tau-perpendicular reduction C(U) of a signed tau-exceptional object U (Plan 65 / R27), dispatching on the sign of U (H2):

• U a tau-rigid module (a :class:~quiverlab.modules.module.Module, or a positive :class:TauExcObject): the DIJ quotient C(U) = End(T_U)/<e_U> (rank n - |U|);
• U a shifted projective P_v[1] (a negative :class:TauExcObject): the support quotient C(P_v[1]) = A/<e_v> (rank n - 1), with the tautological restriction transport.

Returns a :class:TauReduction. Self-certifies rk C(U) = n - |U| and (tau-rigid case) is discriminated by the C(S_1 of kA_3) = kA_2 iso pin (H5). certify=True (default, the public path) runs the H-1 completion-independence certificate (#sTt(C(U)) invariant across completions); the internal materialiser passes certify=False (its aggregate count is the guard).

Source code in src/quiverlab/tautilting/exceptional.py

def tau_perpendicular_reduction(A, U, *, budget=512, certify=True, _eg=None):
    """The Jasso tau-perpendicular reduction ``C(U)`` of a signed tau-exceptional object
    ``U`` (Plan 65 / R27), dispatching on the sign of ``U`` (H2):

    - ``U`` a **tau-rigid module** (a :class:`~quiverlab.modules.module.Module`, or a
      positive :class:`TauExcObject`): the DIJ quotient ``C(U) = End(T_U)/<e_U>`` (rank
      ``n - |U|``);
    - ``U`` a **shifted projective** ``P_v[1]`` (a negative :class:`TauExcObject`): the
      support quotient ``C(P_v[1]) = A/<e_v>`` (rank ``n - 1``), with the tautological
      restriction transport.

    Returns a :class:`TauReduction`. Self-certifies ``rk C(U) = n - |U|`` and (tau-rigid
    case) is discriminated by the ``C(S_1 of kA_3) = kA_2`` iso pin (H5). ``certify=True``
    (default, the public path) runs the H-1 completion-independence certificate
    (``#sTt(C(U))`` invariant across completions); the internal materialiser passes
    ``certify=False`` (its aggregate count is the guard)."""
    _require_quiver(A, "tau_perpendicular_reduction")
    if isinstance(U, TauExcObject) and U.sign < 0:      # shifted projective P_v[1]
        from quiverlab.modules.recollement import Recollement
        v = U.vertex
        recoll = Recollement(A, [v])
        return TauReduction(
            reduction_algebra=recoll.quotient, bongartz=None, u_vertices=[v],
            kind="shifted", equivalence=(lambda M, _r=recoll: _r.i_upper_star(M)))
    Umod = U.module if isinstance(U, TauExcObject) else U
    if Umod is None:
        raise QuiverlabError(
            "tau_perpendicular_reduction: a positive TauExcObject with no module")
    from quiverlab.tautilting.mutation import exchange_graph
    eg = _eg if _eg is not None else exchange_graph(A, budget_pairs=max(budget, 512))
    if eg.status != "complete":
        raise QuiverlabError(
            "tau_perpendicular_reduction: the exchange graph is not complete "
            f"(status={eg.status!r}); U cannot be tau-Bongartz-completed")
    C, pair, uverts = _reduction_tau_rigid(A, Umod, eg, certify=certify)
    return TauReduction(reduction_algebra=C, bongartz=pair, u_vertices=uverts,
                        kind="tau_rigid", equivalence=None)