resolutions_cs

quiverlab.resolutions_cs

quiverlab.resolutions_cs: the Chouhy-Solotar general bimodule resolution (arXiv:1406.2300 = J. Algebra 432 (2015)). Domain-generic; consumes the Plan-03 groebner.ReductionSystem and the Plan-01 core.Algebra. See the plan and docs/internals/09-chouhy-solotar.md for the mathematics (S-sequence = Bardzell associated paths of the tip monomial algebra; differentials = CS f_n leading map + order-condition-pinned correction; two collapse maps for HH_• and HH^•).

Public surface (the frozen interface Plan 05 and later consume from this package; see the Plan-04 T14 frozen-interface note). Re-exported here so the package root exposes the documented API — the guards/errors themselves live canonically in quiverlab.errors.

CSResolution

CSResolution(A, max_cells=4000000)

Bases: Resolution

Test-only surface: gate-free by design. It enforces admissibility and prime-field scope but does NOT run the two binding gates (assert_dd_zero / assert_order_condition) that the public path in homology.py runs; its certificate is the cross-check batteries instead. The public Algebra dispatch always routes to the gated homology.py, never here.

Source code in src/quiverlab/resolutions_cs/engine_facade.py

def __init__(self, A, max_cells=4_000_000):
    from quiverlab.errors import FieldError
    from quiverlab.fields.primefield import PrimeField
    if not isinstance(A.domain, PrimeField):
        raise FieldError(
            f"the CS int64 engine facade computes over prime fields only; this "
            f"algebra is over {A.domain.name}",
            hint="use the domain-generic cs_(co)homology_dims for any field, or "
                 "construct the algebra over GF(p)")
    self.A = A
    self.max_cells = max_cells
    self._res = None
    self._top = -1

ChouhySolotarResolution

ChouhySolotarResolution(A, rs, max_degree, max_cells=4000000, coefficients=None)

Source code in src/quiverlab/resolutions_cs/resolution.py

def __init__(self, A, rs, max_degree, max_cells=4_000_000, coefficients=None):
    self.A = A
    self.rs = rs
    self.dom = A.domain
    self.ss = SSequence(rs, max_degree, max_cells)
    self.ar = AArith(A, rs)
    # Plan 52: an optional coefficient bimodule M. The RESOLUTION of A over A^e is
    # coefficient-independent (d_terms unchanged); only the collapse in matrix()
    # swaps the corner e_t A e_o -> e_t M e_o and the two outer muls -> M's actions.
    self.coefficients = coefficients
    self._chain_index = {}
    self._d_cache = {}
    self._rdec_cache = {}

assert_order_condition

assert_order_condition(upto)

CS Theorem 4.1 condition (2): every correction term's loop path b·p·b' is strictly ≺ σ.

Source code in src/quiverlab/resolutions_cs/resolution.py

def assert_order_condition(self, upto):
    """CS Theorem 4.1 condition (2): every correction term's loop path b·p·b' is strictly ≺ σ."""
    order = self.rs.order
    for n in range(3, upto + 1):
        for sigma in self.ss.S(n):
            lead = {(a, tw, cc): c for (c, a, tw, cc) in self.delta_terms(n, sigma)}
            for (c, a, tw, cc) in self.d_terms(n, sigma):
                if lead.get((a, tw, cc)) == c:
                    continue                                 # a leading term
                if not order.key(a + tw + cc) < order.key(sigma.word):
                    raise AssertionError(
                        f"order condition violated at degree {n}, chain {sigma.word}: "
                        f"correction {(a, tw, cc)} is not ≺ σ")

Comparison

Comparison(A, window=None, max_cells=4000000)

Source code in src/quiverlab/resolutions_cs/comparison.py

def __init__(self, A, window=None, max_cells=4_000_000):
    if not isinstance(A.domain, PrimeField):
        raise FieldError(
            f"the CS<->bar comparison uses engine.tt_calculus (the GF(p) facade); "
            f"this algebra is over {A.domain.name}",
            hint="construct the algebra over GF(p); the domain-generic bar/CS "
                 "(co)homology dims serve any field")
    if A.quiver is None or A.relations is None:
        raise ValueError("Comparison needs an algebra built by Quiver.algebra "
                         "(quiver + relations present)")
    from quiverlab.engine.adapter import to_engine
    from quiverlab.resolutions_cs.build import reduction_system_of
    from quiverlab.resolutions_cs.homology import _require_admissible

    self.A = A
    self.dom = A.domain
    self.p = self.dom.p
    self.max_cells = max_cells
    self.B = A.unit_adapted()
    self.m = self.B.dim
    self.E = to_engine(self.B)
    self._rs = reduction_system_of(A)
    _require_admissible(self._rs)
    self._monomial = all(len(r.tail) == 0 for r in self._rs.rules)
    self._build_change_of_basis()
    self.window = self._default_window() if window is None else window
    # lazily grown CS resolution + degreewise caches
    self._res = None
    self._maxdeg = -1
    self._phi_cache = {}
    self._dcs_cache = {}
    self._dbar_cache = {}
    self._zbar_cache = {}
    self._barbasis_cache = {}
    self._exp_cache = {}
    self._pathB_cache = {}
    self._phihom_cache = {}
    self._barchain_cache = {}

Phi

Phi(n)

Matrix of the comparison cochain map Phi# : C^n_bar -> C^n_cs (rows = CS coh basis, cols = engine bar cochain basis), int mod p.

Source code in src/quiverlab/resolutions_cs/comparison.py

def Phi(self, n):
    """Matrix of the comparison cochain map Phi# : C^n_bar -> C^n_cs
    (rows = CS coh basis, cols = engine bar cochain basis), int mod p."""
    M = self._phi_cache.get(n)
    if M is not None:
        return M
    self._ensure(n)
    p, m = self.p, self.m
    csb = self._res._basis(n, "coh")
    bcb = self._bar_basis(n)
    Pi = self._P
    M = [[0] * len(bcb) for _ in range(len(csb))]
    exps = {}
    vals = {}                                    # (s, word) -> original-coords m-vec
    for ri, (sigma, j) in enumerate(csb):
        key = sigma.word
        if key not in exps:
            exps[key] = self._expansion(n, sigma)
        ex = exps[key]
        for ci, (w, s) in enumerate(bcb):
            cvec = ex.get(tuple(w))
            if cvec is None:
                continue
            # (Phi# g)(sigma) for g = (w |-> e_s):  1 . e_s . c, back to original
            # coords through P, paired with the CS basis coordinate j.
            vk = (s, tuple(w), key)
            val = vals.get(vk)
            if val is None:
                es = np.zeros(m, dtype=np.int64)
                es[s] = 1
                vB = self._mult_B(es, cvec)
                val = [sum(Pi[r][k] * int(vB[k]) for k in range(m)) % p
                       for r in range(m)]
                vals[vk] = val
            if val[j]:
                M[ri][ci] = (M[ri][ci] + val[j]) % p
    self._phi_cache[n] = M
    return M

PhiHom

PhiHom(n)

Matrix of the covariant collapse A (x)_{A^e} Phi : C_n_cs -> C_n_bar (rows = engine cn_basis, cols = CS hom basis [(sigma, j)]), int mod p. A CS chain (sigma, x) goes to sum_w ( c_w . x ; w ) — the homology collapse puts the right outer factor on the left (the A^e op-twist), and the left outer factor of every lifted Phi term is 1.

Source code in src/quiverlab/resolutions_cs/comparison.py

def PhiHom(self, n):
    """Matrix of the covariant collapse A (x)_{A^e} Phi : C_n_cs -> C_n_bar
    (rows = engine cn_basis, cols = CS hom basis [(sigma, j)]), int mod p.
    A CS chain (sigma, x) goes to sum_w ( c_w . x ; w ) — the homology collapse
    puts the right outer factor on the left (the A^e op-twist), and the left
    outer factor of every lifted Phi term is 1."""
    M = self._phihom_cache.get(n)
    if M is not None:
        return M
    self._ensure(n)
    p, m = self.p, self.m
    csb = self._res._basis(n, "hom")
    bcb = self._bar_chain_basis(n)
    idx = {gen: i for i, gen in enumerate(bcb)}
    M = [[0] * len(csb) for _ in range(len(bcb))]
    exps = {}
    for ci, (sigma, j) in enumerate(csb):
        key = sigma.word
        if key not in exps:
            exps[key] = self._expansion(n, sigma)
        xB = np.array([self._Pinv[k][j] for k in range(m)], dtype=np.int64)
        for w, cvec in exps[key].items():
            slot = self._mult_B(cvec, xB)             # c . x (b-left twist)
            for a0 in np.nonzero(slot % p)[0]:
                r = idx.get((int(a0),) + tuple(w))
                if r is not None:
                    M[r][ci] = (M[r][ci] + int(slot[a0])) % p
    self._phihom_cache[n] = M
    return M

Psi

Psi(n)

The inverse comparison on cohomology, HH^n_cs -> HH^n_bar, as a matrix in the (CS / bar) cohomology-representative bases. Psi = (Phi#|_{HH})^{-1}: the Hom-dual of the CS projection Psi: B -> P, delivered on HH^* (the resolution- level projection is the Skoldberg splitting, a later phase).

Source code in src/quiverlab/resolutions_cs/comparison.py

def Psi(self, n):
    """The inverse comparison on cohomology, HH^n_cs -> HH^n_bar, as a matrix in
    the (CS / bar) cohomology-representative bases.  Psi = (Phi#|_{HH})^{-1}: the
    Hom-dual of the CS projection Psi: B -> P, delivered on HH^* (the resolution-
    level projection is the Skoldberg splitting, a later phase)."""
    Fstar, _, _ = self._induced_on_cohomology(n)
    inv = self._invert_modp(Fstar)
    if inv is None:
        raise AssertionError(
            f"comparison is not invertible on HH^{n}: Phi# fails to be a "
            f"quasi-isomorphism at degree {n} (a bug, never an approximation)")
    return inv

assert_chain_map

assert_chain_map(upto=2)

The comparison morphism intertwines the two differentials, as matrix identities over GF(p):

(1) delta_cs^n Phi#n = Phi#{n+1} delta_bar^n (Phi# is a cochain map; the Hom form of b_bar Phi = Phi d_cs), for n = 0..upto-1; and (2) on HH^k the induced Phi is a two-sided isomorphism -- its inverse Psi (the CS projection on cohomology) satisfies Phi Psi = Psi Phi = id (the Hom form of d_cs Psi = Psi b_bar), for k = 0..upto.

The identities are asserted only where genuinely non-vacuous: (1) requires a nonzero delta on BOTH sides at some tested degree (guarded), and (2) is a matrix identity on the actual (nonzero) HH bases.

Source code in src/quiverlab/resolutions_cs/comparison.py

def assert_chain_map(self, upto=2):
    """The comparison morphism intertwines the two differentials, as matrix
    identities over GF(p):

      (1) delta_cs^n Phi#_n = Phi#_{n+1} delta_bar^n   (Phi# is a cochain map;
          the Hom form of b_bar Phi = Phi d_cs), for n = 0..upto-1; and
      (2) on HH^k the induced Phi* is a two-sided isomorphism -- its inverse Psi*
          (the CS projection on cohomology) satisfies Phi* Psi* = Psi* Phi* = id
          (the Hom form of d_cs Psi = Psi b_bar), for k = 0..upto.

    The identities are asserted only where genuinely non-vacuous: (1) requires a
    nonzero delta on BOTH sides at some tested degree (guarded), and (2) is a
    matrix identity on the actual (nonzero) HH bases.
    """
    saw_nontrivial = False
    for n in range(upto):
        dcs = self._dcs(n)
        dbar = self._dbar(n)
        lhs = self._matmul(dcs, self.Phi(n))            # C^n_bar -> C^{n+1}_cs
        rhs = self._matmul(self.Phi(n + 1), dbar)
        if lhs != rhs:
            raise AssertionError(
                f"comparison is not a cochain map at degree {n}: "
                f"delta_cs Phi# != Phi# delta_bar")
        nz_cs = any(v % self.p for row in dcs for v in row)
        nz_bar = any(v % self.p for row in dbar for v in row)
        if nz_cs and nz_bar:
            saw_nontrivial = True
    if upto >= 1 and not saw_nontrivial:
        raise AssertionError(
            "assert_chain_map is vacuous: no tested degree has nonzero "
            "differentials on both sides")
    for k in range(upto + 1):
        Fstar, cs_reps, _ = self._induced_on_cohomology(k)
        inv = self._invert_modp(Fstar)
        if inv is None:
            raise AssertionError(
                f"comparison is not invertible on HH^{k}: Phi* has no inverse "
                f"(not a quasi-isomorphism -- a bug)")
        d = len(cs_reps)
        ident = [[1 if i == j else 0 for j in range(d)] for i in range(d)]
        if self._matmul(Fstar, inv) != ident or self._matmul(inv, Fstar) != ident:
            raise AssertionError(
                f"Phi* Psi* != id on HH^{k}: the CS projection is not a genuine "
                f"inverse comparison")

assert_transport_roundtrip_identity

assert_transport_roundtrip_identity(upto=3)

Psi(Phi(c)) = c on HH^n for every basis class c (n = 0..upto): each CS class is transported to the bar and pulled straight back, and must land in its own CS cohomology class. Asserted on genuinely nonzero HH^n.

Source code in src/quiverlab/resolutions_cs/comparison.py

def assert_transport_roundtrip_identity(self, upto=3):
    """Psi*(Phi*(c)) = c on HH^n for every basis class c (n = 0..upto): each CS
    class is transported to the bar and pulled straight back, and must land in
    its own CS cohomology class.  Asserted on genuinely nonzero HH^n."""
    for n in range(upto + 1):
        reps = self.cs_cohomology_basis(n)
        for c in reps:
            g = self.transport_cocycle_cs_to_bar(c, n)         # Phi*(c): to bar
            back = self.transport_class_bar_to_cs(g, n)         # Psi*(...): to CS
            if not self.same_cohomology_class(back, c, degree=n):
                raise AssertionError(
                    f"transport round-trip Psi*Phi* != id on HH^{n}: a class "
                    f"failed to return to itself (a bug, never an approximation)")

bracket_of_cs_classes

bracket_of_cs_classes(u, v, engine='auto')

The CS-side Hochschild Gerstenhaber bracket [u, v] at degree u.degree+v.degree-1. Two routes, selected by engine exactly as cup_of_cs_classes / cap_of_cs_classes do (Plan 51):

• "transport" (and "auto" in-window, i.e. max(p, q) <= self.window): Psi( [Phi(u), Phi*(v)]_bar ) -- transport representatives to the bar, take the classical Gerstenhaber bracket there (engine.tt_calculus. gerstenhaber_bracket_cochain), and pull the result back through Phi#. This is window-bounded (a degree-n operation needs bar cochains up to degree 2n+1); "transport" keeps that refusal at any degree, so past the window it raises NotImplementedError.
• "native" (and "auto" PAST the window): the native CS bracket assembled from two Negron-Witherspoon / Volkov homotopy liftings on the SAME lifted diagonal (resolutions_cs.bracket.native_bracket, Plan 51) -- no bar object is ever built, so it works at ANY degree over any exact Domain; in-window it is cohomologous to the transported route (the permanent anchor oracle, which fixes the sign, tests/resolutions_cs/test_native_bracket.py).

"auto" is byte-for-byte the transported behavior (and all its cross-checks) wherever the transport does NOT refuse -- exactly max(p, q) <= self.window -- and routes native only where the transport used to raise. The stale "needs the CS brace/circle machinery" note is retired: the homotopy lifting IS the brace-free native route (Plan 51 DD3).

Source code in src/quiverlab/resolutions_cs/comparison.py

def bracket_of_cs_classes(self, u, v, engine="auto"):
    """The CS-side Hochschild Gerstenhaber bracket [u, v] at degree
    u.degree+v.degree-1.  Two routes, selected by ``engine`` exactly as
    ``cup_of_cs_classes`` / ``cap_of_cs_classes`` do (Plan 51):

    * ``"transport"`` (and ``"auto"`` in-window, i.e. max(p, q) <= self.window):
      Psi*( [Phi*(u), Phi*(v)]_bar ) -- transport representatives to the bar, take
      the classical Gerstenhaber bracket there (engine.tt_calculus.
      gerstenhaber_bracket_cochain), and pull the result back through Phi#.  This is
      window-bounded (a degree-n operation needs bar cochains up to degree 2n+1);
      ``"transport"`` keeps that refusal at any degree, so past the window it raises
      NotImplementedError.
    * ``"native"`` (and ``"auto"`` PAST the window): the native CS bracket assembled
      from two Negron-Witherspoon / Volkov homotopy liftings on the SAME lifted
      diagonal (resolutions_cs.bracket.native_bracket, Plan 51) -- no bar object is
      ever built, so it works at ANY degree over any exact Domain; in-window it is
      cohomologous to the transported route (the permanent anchor oracle, which fixes
      the sign, tests/resolutions_cs/test_native_bracket.py).

    ``"auto"`` is byte-for-byte the transported behavior (and all its cross-checks)
    wherever the transport does NOT refuse -- exactly max(p, q) <= self.window -- and
    routes native only where the transport used to raise.  The stale
    "needs the CS brace/circle machinery" note is retired: the homotopy lifting IS
    the brace-free native route (Plan 51 DD3)."""
    if engine not in ("auto", "native", "transport"):
        raise ValueError(
            "engine must be one of 'auto', 'native', 'transport'; got "
            f"{engine!r}")
    p, q = u.degree, v.degree
    if engine == "native" or (engine == "auto" and max(p, q) > self.window):
        # native CS route: no bar object; any degree.  native_bracket needs S up to
        # p+q-1 and Delta to p+q-1; ensure p+q+1 (the conservative margin matching
        # the cup route, comparison.py cup_of_cs_classes).
        from quiverlab.resolutions_cs.bracket import native_bracket
        self._ensure(p + q + 1)
        return native_bracket(self._res, u.vec, p, v.vec, q)
    # transported route (engine == "transport", or "auto" in-window): byte-for-byte
    # the original behavior, INCLUDING the window refusal via _check_window.
    from quiverlab.engine import tt_calculus as TT
    self._check_window(p, q)
    gu, gv = self._bar_cochain_of(u), self._bar_cochain_of(v)
    br = TT.gerstenhaber_bracket_cochain(self.E, p, q, gu, gv)  # bar (p+q-1)-cochain
    self._ensure(p + q - 1)
    return self.transport_class_bar_to_cs([int(x) % self.p for x in br], p + q - 1)

cap_of_cs_classes

cap_of_cs_classes(f, z, engine='auto')

The CS-side cap product f ∩ z (f a CS cohomology class of degree p, z a CS homology class of degree n >= p), at degree n - p. Two routes, selected by engine exactly as cup_of_cs_classes does:

• "transport" (and "auto" in-window, i.e. max(p, n) <= self.window): transport f, z to the bar, cap there with engine.tt_calculus.cap_cochain, and pull the degree-(n-p) chain class back through the covariant collapse. This is window-bounded (a degree-n operation needs bar cochains up to degree 2n+1); "transport" keeps that refusal at any degree, so past the window it raises NotImplementedError.
• "native" (and "auto" PAST the window): the native CS cap on the lifted diagonal (resolutions_cs.cap.native_cap, Plan 21) -- the homology-side b·w·a collapse of the SAME Δ the native cup uses. No bar object is ever built, so it works at ANY degree; in-window it is homologous to the transported route (the permanent anchor oracle, tests/resolutions_cs/test_native_cap.py).

"auto" is byte-for-byte the transported behavior (and all its cross-checks) wherever the transport does NOT refuse -- exactly max(p, n) <= self.window -- and routes native only where the transport used to raise. Raises ValueError for p > n (a cap into negative degree) on both routes.

Source code in src/quiverlab/resolutions_cs/comparison.py

def cap_of_cs_classes(self, f, z, engine="auto"):
    """The CS-side cap product f ∩ z (f a CS cohomology class of degree p, z a CS
    homology class of degree n >= p), at degree n - p.  Two routes, selected by
    ``engine`` exactly as ``cup_of_cs_classes`` does:

    * ``"transport"`` (and ``"auto"`` in-window, i.e. max(p, n) <= self.window):
      transport f, z to the bar, cap there with engine.tt_calculus.cap_cochain, and
      pull the degree-(n-p) chain class back through the covariant collapse.  This is
      window-bounded (a degree-n operation needs bar cochains up to degree 2n+1);
      ``"transport"`` keeps that refusal at any degree, so past the window it raises
      NotImplementedError.
    * ``"native"`` (and ``"auto"`` PAST the window): the native CS cap on the lifted
      diagonal (resolutions_cs.cap.native_cap, Plan 21) -- the homology-side `b·w·a`
      collapse of the SAME Δ the native cup uses.  No bar object is ever built, so it
      works at ANY degree; in-window it is homologous to the transported route (the
      permanent anchor oracle, tests/resolutions_cs/test_native_cap.py).

    ``"auto"`` is byte-for-byte the transported behavior (and all its cross-checks)
    wherever the transport does NOT refuse -- exactly max(p, n) <= self.window -- and
    routes native only where the transport used to raise.  Raises ValueError for
    p > n (a cap into negative degree) on both routes."""
    if engine not in ("auto", "native", "transport"):
        raise ValueError(
            "engine must be one of 'auto', 'native', 'transport'; got "
            f"{engine!r}")
    p_deg, n_deg = f.degree, z.degree
    if engine == "native" or (engine == "auto" and max(p_deg, n_deg) > self.window):
        # native CS route: no bar object; any degree.  native_cap iterates Δ_n and
        # reads the hom collapse, so ensure the resolution one past n (mirrors the
        # cup's p+q+1) so downstream homology-class checks have their differential.
        from quiverlab.resolutions_cs.cap import native_cap
        self._ensure(n_deg + 1)
        return native_cap(self._res, f.vec, p_deg, z.vec, n_deg)
    # transported route (engine == "transport", or "auto" in-window): byte-for-byte
    # the original behavior, INCLUDING the window refusal via _check_window.
    from quiverlab.engine import tt_calculus as TT
    self._check_window(p_deg, n_deg)
    fb = self.transport_cocycle_cs_to_bar(f.vec, p_deg)
    zb = self.transport_cycle_cs_to_bar(z.vec, n_deg)
    capped = TT.cap_cochain(self.E, p_deg, n_deg,
                            np.array(fb, dtype=np.int64),
                            np.array(zb, dtype=np.int64))
    return self.transport_class_bar_to_cs_hom(
        [int(v) % self.p for v in capped], n_deg - p_deg)

cs_cohomology_basis

cs_cohomology_basis(n)

Representative CS cocycles of a basis of HH^n_cs (int mod p vectors).

Source code in src/quiverlab/resolutions_cs/comparison.py

def cs_cohomology_basis(self, n):
    """Representative CS cocycles of a basis of HH^n_cs (int mod p vectors)."""
    from quiverlab.resolutions_cs.homology import cs_hh_basis
    reps = cs_hh_basis(self.A, n, "coh", max_cells=self.max_cells)
    return [[int(x) % self.p for x in v] for v in reps]

cs_homology_basis

cs_homology_basis(n)

Representative CS cycles of a basis of HH_n (int mod p vectors).

Source code in src/quiverlab/resolutions_cs/comparison.py

def cs_homology_basis(self, n):
    """Representative CS cycles of a basis of HH_n (int mod p vectors)."""
    from quiverlab.resolutions_cs.homology import cs_hh_basis
    reps = cs_hh_basis(self.A, n, "hom", max_cells=self.max_cells)
    return [[int(x) % self.p for x in v] for v in reps]

cup_of_cs_classes

cup_of_cs_classes(u, v, engine='auto')

The CS-side Hochschild cup of two CS classes, at degree u.degree+v.degree. Two routes, selected by engine:

• "transport" (and "auto" in-window, i.e. max(deg) <= self.window): Psi( Phi(u) cup_bar Phi*(v) ) -- transport representatives to the bar, cup there with the Tamarkin-Tsygan calculus (engine.tt_calculus.cup_cochain), and pull the result back through Phi#. This is window-bounded (a degree-n cup needs bar cochains up to degree 2n+1); "transport" keeps that refusal at any degree, so past the window it raises NotImplementedError.
• "native" (and "auto" PAST the window): the native CS cup on the lifted diagonal (resolutions_cs.cup.native_cup) -- no bar object is ever built, so it works at ANY degree (Plan 20). In-window it is cohomologous to the transported route (the permanent anchor oracle, tests/resolutions_cs/test_native_cup.py).

"auto" is byte-for-byte the transported behavior (and all its internal cross-checks) wherever the transport does NOT refuse -- exactly max(p,q) <= self.window -- and routes native only where the transport used to raise.

Source code in src/quiverlab/resolutions_cs/comparison.py

def cup_of_cs_classes(self, u, v, engine="auto"):
    """The CS-side Hochschild cup of two CS classes, at degree u.degree+v.degree.
    Two routes, selected by ``engine``:

    * ``"transport"`` (and ``"auto"`` in-window, i.e. max(deg) <= self.window):
      Psi*( Phi*(u) cup_bar Phi*(v) ) -- transport representatives to the bar, cup
      there with the Tamarkin-Tsygan calculus (engine.tt_calculus.cup_cochain), and
      pull the result back through Phi#.  This is window-bounded (a degree-n cup
      needs bar cochains up to degree 2n+1); ``"transport"`` keeps that refusal at
      any degree, so past the window it raises NotImplementedError.
    * ``"native"`` (and ``"auto"`` PAST the window): the native CS cup on the lifted
      diagonal (resolutions_cs.cup.native_cup) -- no bar object is ever built, so it
      works at ANY degree (Plan 20).  In-window it is cohomologous to the transported
      route (the permanent anchor oracle, tests/resolutions_cs/test_native_cup.py).

    ``"auto"`` is byte-for-byte the transported behavior (and all its internal
    cross-checks) wherever the transport does NOT refuse -- exactly max(p,q) <=
    self.window -- and routes native only where the transport used to raise."""
    if engine not in ("auto", "native", "transport"):
        raise ValueError(
            "engine must be one of 'auto', 'native', 'transport'; got "
            f"{engine!r}")
    p, q = u.degree, v.degree
    if engine == "native" or (engine == "auto" and max(p, q) > self.window):
        # native CS route: no bar object; any degree.  native_cup needs S up to
        # p+q and the coh collapse reads one degree of differential, so ensure
        # p+q+1 (resolution.py:158-165).
        from quiverlab.resolutions_cs.cup import native_cup
        self._ensure(p + q + 1)
        return native_cup(self._res, u.vec, p, v.vec, q)
    # transported route (engine == "transport", or "auto" in-window): byte-for-byte
    # the original behavior, INCLUDING the window refusal via _check_window.
    from quiverlab.engine import tt_calculus as TT
    self._check_window(p, q)
    gu, gv = self._bar_cochain_of(u), self._bar_cochain_of(v)
    cup = TT.cup_cochain(self.E, p, q, gu, gv)          # bar (p+q)-cochain
    self._ensure(p + q)
    return self.transport_class_bar_to_cs([int(x) % self.p for x in cup], p + q)

hh_class_cs

hh_class_cs(n, i)

The i-th representative class of HH^n on the CS side.

Source code in src/quiverlab/resolutions_cs/comparison.py

def hh_class_cs(self, n, i):
    """The i-th representative class of HH^n on the CS side."""
    reps = self.cs_cohomology_basis(n)
    if i >= len(reps):
        raise IndexError(f"HH^{n}(CS) has {len(reps)} basis classes; no index {i}")
    return CSClass(n, reps[i])

hh_class_cs_hom

hh_class_cs_hom(n, i)

The i-th representative class of HH_n on the CS side.

Source code in src/quiverlab/resolutions_cs/comparison.py

def hh_class_cs_hom(self, n, i):
    """The i-th representative class of HH_n on the CS side."""
    reps = self.cs_homology_basis(n)
    if i >= len(reps):
        raise IndexError(f"HH_{n}(CS) has {len(reps)} basis classes; no index {i}")
    return CSClass(n, reps[i])

same_cohomology_class

same_cohomology_class(x, y, degree)

True iff x - y is a CS coboundary at the given degree (fields.linalg.solve against im delta_cs^{degree-1}).

Source code in src/quiverlab/resolutions_cs/comparison.py

def same_cohomology_class(self, x, y, degree):
    """True iff x - y is a CS coboundary at the given degree (fields.linalg.solve
    against im delta_cs^{degree-1})."""
    dom, p = self.dom, self.p
    self._ensure(degree)
    diff = [(int(x[i]) - int(y[i])) % p for i in range(len(x))]
    Bcs = self._cols(self._dcs(degree - 1)) if degree >= 1 else []
    if not Bcs:
        return all(d % p == 0 for d in diff)
    Mat = [[dom.coerce(Bcs[c][r]) for c in range(len(Bcs))] for r in range(len(diff))]
    rhs = [dom.coerce(d) for d in diff]
    return solve(Mat, rhs, dom) is not None

same_homology_class

same_homology_class(x, y, degree)

True iff x - y is a CS boundary at the given degree.

Source code in src/quiverlab/resolutions_cs/comparison.py

def same_homology_class(self, x, y, degree):
    """True iff x - y is a CS boundary at the given degree."""
    dom, p = self.dom, self.p
    self._ensure(degree + 1)
    Mb = self._res.matrix(degree + 1, "hom")
    Bcs = self._cols(Mb) if Mb and Mb[0] else []
    diff = [(int(a) - int(b)) % p for a, b in zip(x, y)]
    if not Bcs:
        return not any(diff)
    Mat = [[dom.coerce(Bcs[c][r]) for c in range(len(Bcs))]
           for r in range(len(diff))]
    return solve(Mat, [dom.coerce(v) for v in diff], dom) is not None

transport_class_bar_to_cs

transport_class_bar_to_cs(bar_cocycle, n)

A bar cocycle -> the CS cocycle Phi#(bar_cocycle). Direct: Phi# is the Hom-dual (transpose) of the inclusion chain map.

Source code in src/quiverlab/resolutions_cs/comparison.py

def transport_class_bar_to_cs(self, bar_cocycle, n):
    """A bar cocycle -> the CS cocycle Phi#(bar_cocycle).  Direct: Phi# is the
    Hom-dual (transpose) of the inclusion chain map."""
    return self._matvec(self.Phi(n), [int(x) % self.p for x in bar_cocycle])

transport_class_bar_to_cs_hom

transport_class_bar_to_cs_hom(bar_chain, n)

A bar n-cycle -> a CS n-cycle z with PhiHom(z) homologous to it (solve against PhiHom(CS cycles) and the bar boundaries; the homology mirror of transport_cocycle_cs_to_bar).

Source code in src/quiverlab/resolutions_cs/comparison.py

def transport_class_bar_to_cs_hom(self, bar_chain, n):
    """A bar n-cycle -> a CS n-cycle z with PhiHom(z) homologous to it (solve
    against PhiHom(CS cycles) and the bar boundaries; the homology mirror of
    transport_cocycle_cs_to_bar)."""
    dom, p = self.dom, self.p
    zb = [int(x) % p for x in bar_chain]
    cyc = self._cs_cycles(n)
    cols = [self.transport_cycle_cs_to_bar(c, n) for c in cyc]
    cols = cols + self._bar_boundary_cols(n)
    if not cols:
        if any(x % p for x in zb):
            raise AssertionError("bar->cs homology transport: nonzero class in a "
                                 "zero space")
        return [0] * len(self._res._basis(n, "hom"))
    Mat = [[dom.coerce(cols[cc][rr]) for cc in range(len(cols))]
           for rr in range(len(zb))]
    x = solve(Mat, [dom.coerce(v) for v in zb], dom)
    if x is None:
        raise AssertionError(
            f"bar->cs homology transport is inconsistent at degree {n}: the "
            f"comparison is not a quasi-isomorphism here (a bug, never an "
            f"approximation)")
    d = len(self._res._basis(n, "hom"))
    out = [0] * d
    for i, ci in enumerate(x[:len(cyc)]):
        c = int(ci) % p
        if c:
            for k in range(d):
                out[k] = (out[k] + c * cyc[i][k]) % p
    return out

transport_cocycle_cs_to_bar

transport_cocycle_cs_to_bar(cs_cocycle, n)

A CS cocycle c -> a bar cocycle g with Phi#(g) cohomologous to c (the inverse comparison, realised by solve against the bar cocycles and the CS coboundaries).

Source code in src/quiverlab/resolutions_cs/comparison.py

def transport_cocycle_cs_to_bar(self, cs_cocycle, n):
    """A CS cocycle c -> a bar cocycle g with Phi#(g) cohomologous to c (the
    inverse comparison, realised by solve against the bar cocycles and the CS
    coboundaries)."""
    dom, p = self.dom, self.p
    self._ensure(n)
    c = [int(x) % p for x in cs_cocycle]
    Z = self._zbar(n)
    PhiZ = [self._matvec(self.Phi(n), g) for g in Z]
    Bcs = self._cols(self._dcs(n - 1)) if n >= 1 else []
    columns = PhiZ + Bcs
    nrows = len(c)
    if not columns:
        if any(x % p for x in c):
            raise AssertionError("cs->bar transport: nonzero class in a zero space")
        return [0] * len(self._bar_basis(n))
    Mat = [[dom.coerce(columns[cc][rr]) for cc in range(len(columns))]
           for rr in range(nrows)]
    rhs = [dom.coerce(c[rr]) for rr in range(nrows)]
    x = solve(Mat, rhs, dom)
    if x is None:
        raise AssertionError(
            f"cs->bar transport is inconsistent at degree {n}: the comparison is "
            f"not a quasi-isomorphism here (a bug, never an approximation)")
    a = [int(x[i]) % p for i in range(len(Z))]
    g = [0] * len(self._bar_basis(n))
    for i, ai in enumerate(a):
        if ai:
            Zi = Z[i]
            for k in range(len(g)):
                g[k] = (g[k] + ai * Zi[k]) % p
    return g

transport_cycle_cs_to_bar

transport_cycle_cs_to_bar(z, n)

A CS n-chain -> its bar image under the covariant collapse (direct).

Source code in src/quiverlab/resolutions_cs/comparison.py

def transport_cycle_cs_to_bar(self, z, n):
    """A CS n-chain -> its bar image under the covariant collapse (direct)."""
    return self._matvec(self.PhiHom(n), [int(x) % self.p for x in z])

transport_then_bar_cup

transport_then_bar_cup(u, v)

A second, engine-native route to the transported cup: transport u, v to bar CLASSES, cup them with the induced structure-constant tensor (tt_calculus.cup_product_matrix), reconstruct a bar cocycle representative from the resulting class, and pull it back through Phi#. Cohomologous to cup_of_cs_classes -- a cross-check of the cochain-level and class-level cups.

Source code in src/quiverlab/resolutions_cs/comparison.py

def transport_then_bar_cup(self, u, v):
    """A second, engine-native route to the transported cup: transport u, v to
    bar CLASSES, cup them with the induced structure-constant tensor
    (tt_calculus.cup_product_matrix), reconstruct a bar cocycle representative
    from the resulting class, and pull it back through Phi#.  Cohomologous to
    cup_of_cs_classes -- a cross-check of the cochain-level and class-level cups."""
    from quiverlab.engine import tt_calculus as TT
    p, q = u.degree, v.degree
    self._check_window(p, q)
    gu, gv = self._bar_cochain_of(u), self._bar_cochain_of(v)
    Hp = TT.cohomology_classes(self.E, p, self.p)
    Hq = TT.cohomology_classes(self.E, q, self.p)
    Hpq = TT.cohomology_classes(self.E, p + q, self.p)
    cu = Hp.coords(gu % self.p)
    cv = Hq.coords(gv % self.p)
    C, dp, dq, dpq = TT.cup_product_matrix(self.E, p, q, self.p)
    cls = np.zeros(dpq, dtype=np.int64)
    for k in range(dpq):
        acc = 0
        for i in range(dp):
            for j in range(dq):
                acc += int(C[k, i, j]) * int(cu[i]) * int(cv[j])
        cls[k] = acc % self.p
    rep = np.zeros(Hpq.reps.shape[0], dtype=np.int64)
    for k in range(Hpq.dim):
        rep = (rep + int(cls[k]) * Hpq.reps[:, k]) % self.p
    self._ensure(p + q)
    return self.transport_class_bar_to_cs([int(x) % self.p for x in rep], p + q)

cs_hh_basis

cs_hh_basis(A, n, side, max_cells=4000000)

Representative (co)cycles of HH^n (side="coh") / HH_n (side="hom"): a basis of Z modulo the relevant image, each returned as a coordinate vector in C^n / C_n (the CS basis order of dim_C). Admissibility-gated; the (co)cycle space comes from fields.linalg.nullspace of the relevant differential (with the 0-dimensional-codomain edge handled -- the whole C_n is then the kernel).

Source code in src/quiverlab/resolutions_cs/homology.py

def cs_hh_basis(A, n, side, max_cells=4_000_000):
    """Representative (co)cycles of HH^n (side="coh") / HH_n (side="hom"): a basis
    of Z modulo the relevant image, each returned as a coordinate vector in C^n / C_n
    (the CS basis order of dim_C). Admissibility-gated; the (co)cycle space comes from
    fields.linalg.nullspace of the relevant differential (with the 0-dimensional-codomain
    edge handled -- the whole C_n is then the kernel)."""
    from quiverlab.resolutions_cs.build import reduction_system_of
    from quiverlab.resolutions_cs.resolution import ChouhySolotarResolution
    rs = reduction_system_of(A); _require_admissible(rs)
    res = ChouhySolotarResolution(A, rs, max_degree=n + 1, max_cells=max_cells)
    dom = A.domain
    if side == "coh":
        # delta^n : C^n -> C^{n+1}; kernel is all of C^n when C^{n+1} = 0.
        cycles = _cycle_space(res, n, "coh", res.dim_C(n + 1, "coh"), dom)
        image = _columns(res.matrix(n - 1, "coh")) if n else []  # B^n = im delta^{n-1}
    elif side == "hom":
        # b_n : C_n -> C_{n-1}; kernel is all of C_n when C_{n-1} = 0 (and b_0 = 0).
        codim = 0 if n == 0 else res.dim_C(n - 1, "hom")
        cycles = _cycle_space(res, n, "hom", codim, dom)
        image = _columns(res.matrix(n + 1, "hom"))             # B_n = im b_{n+1}
    else:
        raise ValueError(f"side must be 'coh' or 'hom', got {side!r}")
    return _reps_mod_image(cycles, image, dom)