uconf.homology

Chain-complex construction and homology helpers for dg-modules.

Given any module exposing graded_basis(d) and boundary (as used by operad/cooperad components, bar/cobar constructions, free algebras, cofree coalgebras, etc.), this module builds a SageMath ChainComplex and provides helpers to extract homology representatives as native module elements.

EXAMPLES:

sage: from sage.all import QQ
sage: from uconf import Surjection
sage: from uconf.homology import compute_chain_complex, homology_basis
sage: S2 = Surjection(2, QQ)
sage: C = compute_chain_complex(S2, degrees=range(4))
sage: 0 in C.betti()
True
sage: homology_basis(S2, degree=0)
[{2 1}]
uconf.homology.compute_chain_complex(module, degrees, *, weight=None, check=False, sparse=True, n_jobs=1, progress=False, verbose=False, prewarm=True, prewarm_profiler=None, worker_profile_paths=None, worker_profile_parent=None)[source]

Build a SageMath ChainComplex from a dg-module.

Parameters

module:

Any object exposing graded_basis(d) (returning a Family of basis elements), boundary (a linear map), and base_ring(). All operad/cooperad components, bar/cobar constructions, free algebras, cofree coalgebras, and similar objects from uconf satisfy this interface.

degrees:

A range of integer degrees. The returned chain complex covers degrees plus one additional degree above (max(degrees)+1) so that the differential into max(degrees) is fully accounted for. Homology is correct for every degree in degrees; the Betti number at max(degrees)+1 may be inflated by the truncation.

weight:

Optional fixed weight. When provided, only basis elements of the given weight are included. The module must expose graded_basis_by_weight(d, weight); if it does not, a ValueError is raised. Weight is the total number of “tensor factors” as defined by the module’s _weight_on_basis (for free algebras: the arity; for tree modules: the sum of leaf weights; for plain modules: the number of leaves).

sparse:

Whether to build differential matrices in sparse format. This is usually faster and significantly lighter in memory for dg-modules with sparse boundaries.

n_jobs:

Number of worker processes to use for boundary-matrix assembly on the on_basis fast path. Values above 1 currently use Linux fork-based multiprocessing and otherwise fall back to serial assembly.

progress:

When True, emit a low-overhead progress indicator showing how many boundary columns have been assembled across all requested degrees.

worker_profile_paths:

Optional mutable list that receives per-worker .prof files when parallel boundary assembly is active. These files can be merged into a parent pstats report with Stats.add(*worker_profile_paths).

worker_profile_parent:

Optional active top-level cProfile.Profile. When provided for a parallel run, forked workers disable their inherited copy before starting a per-worker profiler.

Returns

A SageMath ChainComplex with degree_of_differential=-1.

EXAMPLES:

sage: from sage.all import QQ
sage: from uconf import Surjection
sage: from uconf.homology import compute_chain_complex
sage: S2 = Surjection(2, QQ)
sage: C = compute_chain_complex(S2, degrees=range(4))
sage: C.betti()[0]
1
Parameters:

  • module (Any)

  • degrees (range)

  • weight (int | None)

  • check (bool)

  • sparse (bool)

  • n_jobs (int)

  • progress (bool)

  • verbose (bool)

  • prewarm (bool)

  • prewarm_profiler (Profile | None)

  • worker_profile_paths (list[str] | None)

  • worker_profile_parent (Profile | None)

Return type:

Any

uconf.homology.compute_homology_representatives(module, degree, weight, cc, *, algorithm='fast')[source]

Compute cycle representatives for a basis of H_{degree}(cc).

Two algorithms are available, controlled by the algorithm keyword:

"fast" (default)

Uses explicit linear algebra without invoking SageMath’s Smith normal form machinery:

  1. Compute ker = ker(d_degree: C_degree → C_{degree-1}) via right_kernel() on the outgoing differential matrix.

  2. Compute im = im(d_{degree+1}: C_{degree+1} → C_degree) via the column space of the incoming differential.

  3. Row-reduce [im_basis; ker_basis] to echelon form. The rows beyond the first dim(im) give homology representatives — they are in ker and their pivot columns are outside those of im, so they are linearly independent modulo the image.

This avoids the expensive generators=True path in SageMath and is significantly faster for large chain complexes.

"sage"

Delegates to cc.homology(degree, generators=True). Slower but produces representatives whose coefficients are expressed in SageMath’s canonical reduced form, which can be easier to read.

Parameters:

  • module (Any) – The dg-module for which to compute representative cycles.

  • degree (int) – The homological degree at which to compute representatives.

  • weight (int | None) – Weight filter for basis selection, or None.

  • cc – A SageMath ChainComplex built from module via compute_chain_complex(). Must contain differentials for degree and degree + 1.

  • algorithm (Literal['fast', 'sage']) – Which algorithm to use: "fast" (default) or "sage".

Returns:

A list of module elements that are cycles (boundary(x) == 0) whose homology classes form a basis of H_{degree}(cc).

Raises:

ValueError – If algorithm is not "fast" or "sage".

Return type:

list

uconf.homology.homology_basis(module, degree, *, degrees=None, weight=None)[source]

Return cycle representatives for a basis of the homology in degree.

Parameters

module:

A dg-module (same requirements as compute_chain_complex()).

degree:

The homological degree in which to compute homology.

degrees:

Optional range of degrees to use when constructing the underlying chain complex. Must include at least degree - 1, degree, and degree + 1 so that both the incoming and outgoing differentials are available. If None, a minimal range range(degree - 1, degree + 2) is used (negative degrees are clamped to 0). Pass a wider range if the module has non-trivial basis below degree - 1.

weight:

Passed through to compute_chain_complex(). See its documentation.

Returns

A list of elements of module that are cycles (boundary(x) == 0) and whose homology classes form a basis of H_degree(module).

EXAMPLES:

sage: from sage.all import QQ
sage: from uconf import Surjection
sage: from uconf.homology import homology_basis
sage: S2 = Surjection(2, QQ)
sage: homology_basis(S2, 0)
[{2 1}]
Parameters:

  • module (Any)

  • degree (int)

  • degrees (range | None)

  • weight (int | None)

Return type:

list