Skip to content

homalg · FinitelyGeneratedAbelianGroup

11 accepted declarations. Python and Rust forms, contracts, evidence, failure boundaries, and checked usages are kept together below.

Worked example

The complete checked program Compute exact additive and Cartan--Serre invariants of Eilenberg--Mac Lane spaces uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Compute exact additive and Cartan--Serre invariants of Eilenberg--Mac Lane spaces."""

from noether.homalg import FinitelyGeneratedAbelianGroup
from noether.numthy import FiniteField
from noether.topology import EilenbergMacLaneSpace


def main() -> None:
    integral_space = EilenbergMacLaneSpace(FinitelyGeneratedAbelianGroup(2), 2)
    homology = integral_space.integral_homology(6)
    homology.verify()
    assert [group.free_rank for group in homology.groups] == [1, 0, 2, 0, 3, 0, 4]

    modular_space = EilenbergMacLaneSpace(FinitelyGeneratedAbelianGroup(1), 3)
    cohomology = modular_space.modular_cohomology_through_degree(FiniteField.prime(2), 16)
    cohomology.verify()
    assert [generator.degree for generator in cohomology.generators] == [3, 5, 9]
    print(
        f"K(Z^2,2) ranks={[group.free_rank for group in homology.groups]}; "
        f"K(Z,3) mod-two generators="
        f"{[generator.display_name for generator in cohomology.generators]}"
    )


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/35_eilenberg_maclane_spaces.py.

homalg.FinitelyGeneratedAbelianGroup

A finitely generated abelian group in canonical invariant-factor form.

FinitelyGeneratedAbelianGroup(free_rank: int, torsion_coefficients: list[int]=...)

noether::homalg::FinitelyGeneratedAbelianGroup · Direct Rust declaration

pub struct FinitelyGeneratedAbelianGroup { /* private fields */ }
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

Executable usage: examples/35_eilenberg_maclane_spaces.py:11 · examples/35_eilenberg_maclane_spaces.py:16 · examples/35_eilenberg_maclane_spaces.py:5 · validation/unit/homalg/test_chain_complex.py:14 · validation/unit/homalg/test_chain_complex.py:150 · validation/unit/homalg/test_chain_complex.py:151

homalg.FinitelyGeneratedAbelianGroup.direct_sum

Canonical direct sum.

Detailed contract

Direct sum, returned in canonical invariant-factor form.

(self, other: FinitelyGeneratedAbelianGroup) -> FinitelyGeneratedAbelianGroup

noether::homalg::FinitelyGeneratedAbelianGroup::direct_sum · Direct Rust declaration

pub fn direct_sum(&self, other: &Self) -> Result<Self, AbelianGroupError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

Executable usage: validation/unit/topology/test_eilenberg_maclane.py:28

homalg.FinitelyGeneratedAbelianGroup.ext_1_to_integers

First Ext over the integers into Z.

Detailed contract

Ext_Z^1(self, Z) as a canonical finitely generated abelian group.

(self) -> FinitelyGeneratedAbelianGroup

noether::homalg::FinitelyGeneratedAbelianGroup::ext_1_to_integers · Direct Rust declaration

pub fn ext_1_to_integers(&self) -> Self
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

homalg.FinitelyGeneratedAbelianGroup.free_rank

Rank of the free abelian summand.

(self) -> int

noether::homalg::FinitelyGeneratedAbelianGroup::free_rank · Direct Rust declaration

pub fn free_rank(&self) -> usize
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

Executable usage: examples/28_steiner_categories.py:16 · examples/32_poset_core_and_morse.py:19 · examples/35_eilenberg_maclane_spaces.py:14 · examples/35_eilenberg_maclane_spaces.py:21 · validation/unit/category/test_acceptance_workload.py:15 · validation/unit/combinatorics/test_poset.py:107

homalg.FinitelyGeneratedAbelianGroup.from_cyclic_summands

Construct from arbitrary positive cyclic summand orders.

Detailed contract

Construct and canonically normalize a direct sum of cyclic groups. Every supplied order must be a positive nonunit. For example, cyclic summands of orders 2 and 3 normalize to the single invariant factor 6, while orders 4 and 6 normalize to 2, 12.

(free_rank: int, cyclic_orders: list[int]) -> FinitelyGeneratedAbelianGroup

noether::homalg::FinitelyGeneratedAbelianGroup::from_cyclic_summands · Direct Rust declaration

pub fn from_cyclic_summands( free_rank: usize, cyclic_orders: Vec<Integer>, ) -> Result<Self, AbelianGroupError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

Executable usage: validation/unit/topology/test_eilenberg_maclane.py:23

homalg.FinitelyGeneratedAbelianGroup.hom_to_integers

Hom over the integers into Z.

Detailed contract

Hom_Z(self, Z) as a canonical finitely generated abelian group.

(self) -> FinitelyGeneratedAbelianGroup

noether::homalg::FinitelyGeneratedAbelianGroup::hom_to_integers · Direct Rust declaration

pub fn hom_to_integers(&self) -> Self
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

homalg.FinitelyGeneratedAbelianGroup.is_trivial

Whether this is the zero group.

Detailed contract

Whether this is the zero abelian group.

(self) -> bool

noether::homalg::FinitelyGeneratedAbelianGroup::is_trivial · Direct Rust declaration

pub fn is_trivial(&self) -> bool
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

Executable usage: validation/unit/topology/test_eilenberg_maclane.py:31 · validation/unit/topology/test_eilenberg_maclane.py:32 · validation/corpus/topology/incremental-dialogue-nerve.py:37

homalg.FinitelyGeneratedAbelianGroup.tensor_product

Tensor product over the integers.

Detailed contract

Tensor product over the integers, in canonical invariant-factor form.

(self, other: FinitelyGeneratedAbelianGroup) -> FinitelyGeneratedAbelianGroup

noether::homalg::FinitelyGeneratedAbelianGroup::tensor_product · Direct Rust declaration

pub fn tensor_product(&self, other: &Self) -> Result<Self, AbelianGroupError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

Executable usage: validation/unit/topology/test_eilenberg_maclane.py:29

homalg.FinitelyGeneratedAbelianGroup.tor_1

First Tor group over the integers.

Detailed contract

Tor_1^Z(self, other), in canonical invariant-factor form.

(self, other: FinitelyGeneratedAbelianGroup) -> FinitelyGeneratedAbelianGroup

noether::homalg::FinitelyGeneratedAbelianGroup::tor_1 · Direct Rust declaration

pub fn tor_1(&self, other: &Self) -> Self
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

Executable usage: validation/unit/topology/test_eilenberg_maclane.py:30

homalg.FinitelyGeneratedAbelianGroup.torsion_coefficients

Positive nonunit torsion factors in divisibility order.

Detailed contract

Positive nonunit torsion factors in divisibility order. A factor d represents one summand Z/d.

(self) -> list[int]

noether::homalg::FinitelyGeneratedAbelianGroup::torsion_coefficients · Direct Rust declaration

pub fn torsion_coefficients(&self) -> &[Integer]
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

Executable usage: validation/unit/homalg/test_acceptance_workload.py:42 · validation/unit/homalg/test_acceptance_workload.py:44 · validation/unit/homalg/test_acceptance_workload.py:46 · validation/unit/homalg/test_chain_complex.py:153 · validation/unit/homalg/test_chain_complex.py:166 · validation/unit/homalg/test_chain_complex.py:172

homalg.FinitelyGeneratedAbelianGroup.verify

Check the canonical invariant-factor representation.

Detailed contract

Check positivity, nontriviality, and the invariant-factor divisibility chain. This validates the group value itself; it does not recompute the chain complex from which the value may have been obtained.

(self) -> None

noether::homalg::FinitelyGeneratedAbelianGroup::verify · Direct Rust declaration

pub fn verify(&self) -> Result<(), VerificationError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL attached / bounded
Semantic ID noether/homalg/FinitelyGeneratedAbelianGroup@1

Executable usage: examples/01_bezout_certificates.py:10 · examples/01_bezout_certificates.py:3 · examples/03_exact_linear_systems.py:13 · examples/03_exact_linear_systems.py:3 · examples/04_smith_normal_form.py:12 · examples/06_shortest_lattice_vectors.py:12