homalg · FreeModule¶

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

Worked example¶

The complete checked program Reduce a module element and certify a minimal free resolution uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Reduce a module element and certify a minimal free resolution."""

from noether import Q
from noether.commalg import Degree, MonomialOrder, PolynomialRing
from noether.homalg import (
    FreeModule,
    ModuleElement,
    ModuleHomomorphism,
    ModuleMonomialOrder,
    PresentedModule,
    Submodule,
)
from noether.linalg import Matrix, Vector


def main() -> None:
    ring = PolynomialRing(Q, ["x", "y", "z", "w"])
    x, y, z, w = ring.generators()
    order = ModuleMonomialOrder.term_over_position(MonomialOrder.GREVLEX)

    ambient = FreeModule(ring, 2)
    first = ModuleElement(ambient, Vector.from_values(ring, [x, y]))
    second = ModuleElement(ambient, Vector.from_values(ring, [y, 1]))
    submodule = Submodule.from_generators(ambient, [first, second])
    basis = submodule.groebner_basis(order)
    reduction = basis.reduce(first + second * x)
    basis.verify()
    reduction.verify()
    assert reduction.is_member()

    target = FreeModule(ring, 1, grading_rank=1, degree_shifts=[Degree([0])])
    source = FreeModule(ring, 3, grading_rank=1, degree_shifts=[Degree([-2])] * 3)
    twisted_cubic = PresentedModule(
        ModuleHomomorphism(
            source,
            target,
            Matrix.from_rows(ring, [[x * z - y**2, x * w - y * z, y * w - z**2]]),
        )
    )
    resolution = twisted_cubic.minimal_free_resolution(order)
    resolution.verify()
    betti = resolution.graded_betti_table()
    betti.verify()
    assert betti.entries == [
        (0, Degree([0]), 1),
        (1, Degree([2]), 3),
        (2, Degree([3]), 2),
    ]
    print(f"module member certified; minimal Betti entries={betti.entries}")


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/30_modules_and_resolutions.py.

`homalg.FreeModule`¶

A finite based free module over a supported polynomial or quotient ring.

PythonRust

FreeModule(ring: _BasicModuleRing, rank: int, *, basis_labels: Sequence[str] | None=None, grading_rank: int | None=None, degree_shifts: Sequence[Degree] | None=None)

noether::homalg::FreeModule · Direct Rust declaration

pub struct FreeModule<R: Ring> { /* 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/FreeModule@1

Executable usage: examples/30_modules_and_resolutions.py:23 · examples/30_modules_and_resolutions.py:33 · examples/30_modules_and_resolutions.py:34 · examples/30_modules_and_resolutions.py:8 · examples/38_exact_linear_systems.py:49 · examples/38_exact_linear_systems.py:64

`homalg.FreeModule.basis_element`¶

Compute basis element for this FreeModule.

Detailed contract

Construct the requested standard basis element.

PythonRust

(self, position: int) -> ModuleElement[_BasicModuleRing]

noether::homalg::FreeModule::basis_element · Direct Rust declaration

pub fn basis_element( &self, position: usize, ) -> Result<ModuleElement<R>, ModuleError>

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/FreeModule@1

Executable usage: validation/unit/homalg/test_exact_submodules.py:98 · validation/unit/homalg/test_exterior_algebra.py:355 · validation/unit/homalg/test_exterior_algebra.py:357 · validation/unit/homalg/test_module_facade.py:133 · validation/unit/homalg/test_module_facade.py:251 · validation/unit/homalg/test_module_facade.py:253

`homalg.FreeModule.basis_labels`¶

Return the basis labels recorded by this FreeModule.

Detailed contract

Optional ordered basis labels.

PythonRust

(self) -> list[str] | None

noether::homalg::FreeModule::basis_labels · Direct Rust declaration

pub fn basis_labels(&self) -> Option<&[String]>

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/FreeModule@1

Executable usage: examples/40_exterior_algebra.py:13 · validation/unit/homalg/test_exterior_algebra.py:207 · validation/unit/homalg/test_exterior_algebra.py:67 · validation/unit/homalg/test_module_facade.py:233 · validation/unit/homalg/test_module_facade.py:240 · validation/unit/homalg/test_module_facade.py:580

`homalg.FreeModule.degree_shifts`¶

Return the degree shifts recorded by this FreeModule.

Detailed contract

Optional degree shift of every ordered basis vector.

PythonRust

(self) -> list[Degree] | None

noether::homalg::FreeModule::degree_shifts · Direct Rust declaration

pub fn degree_shifts(&self) -> Option<&[Degree]>

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/FreeModule@1

Executable usage: examples/30_modules_and_resolutions.py:33 · examples/30_modules_and_resolutions.py:34 · validation/unit/homalg/test_module_facade.py:235 · validation/unit/homalg/test_module_facade.py:242 · validation/unit/homalg/test_module_facade.py:484 · validation/unit/homalg/test_module_facade.py:490

`homalg.FreeModule.direct_sum`¶

Compute direct sum for this FreeModule.

Detailed contract

Direct sum of two based free modules over the same exact ring context.

PythonRust

(self, rhs: FreeModule[_BasicModuleRing]) -> FreeModule[_BasicModuleRing]

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

pub fn direct_sum(&self, rhs: &Self) -> Result<Self, ModuleError>

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/FreeModule@1

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

`homalg.FreeModule.dual`¶

Compute dual for this FreeModule.

Detailed contract

Dual based free module. Degree shifts are negated.

PythonRust

(self) -> FreeModule[_BasicModuleRing]

noether::homalg::FreeModule::dual · Direct Rust declaration

pub fn dual(&self) -> Result<Self, ModuleError>where R: CommutativeRing,

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/FreeModule@1

Executable usage: examples/40_exterior_algebra.py:28 · validation/unit/category/test_category.py:18 · validation/unit/groups/test_weight_characters.py:47 · validation/unit/homalg/test_exterior_algebra.py:123 · validation/unit/homalg/test_exterior_algebra.py:124 · validation/unit/homalg/test_exterior_algebra.py:125

`homalg.FreeModule.exterior_algebra`¶

Construct the exact exterior algebra on this based module.

Detailed contract

Construct the exact exterior-algebra parent on this based module.

PythonRust

(self) -> ExteriorAlgebra[_BasicModuleRing]

noether::homalg::FreeModule::exterior_algebra · Direct Rust declaration

pub fn exterior_algebra(&self) -> ExteriorAlgebra<R>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Dispatch / backing	noether, module-core
GIL	attached / bounded
Semantic ID	noether/homalg/FreeModule@1
Contexts	supported exact commutative coefficient contexts
Failures	unsupported coefficient context

Executable usage: examples/40_exterior_algebra.py:14 · validation/unit/homalg/test_exterior_algebra.py:140 · validation/unit/homalg/test_exterior_algebra.py:198 · validation/unit/homalg/test_exterior_algebra.py:208 · validation/unit/homalg/test_exterior_algebra.py:229 · validation/unit/homalg/test_exterior_algebra.py:304

`homalg.FreeModule.exterior_power`¶

Compute exterior power for this FreeModule.

Detailed contract

Construct the degree-degree exterior power.

PythonRust

(self, degree: int) -> FreeModulePower[_BasicModuleRing]

noether::homalg::FreeModule::exterior_power · Direct Rust declaration

pub fn exterior_power( &self, degree: usize, ) -> Result<FreeModulePower<R>, ModulePowerError>

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	released
Semantic ID	noether/homalg/FreeModule@1

Executable usage: examples/40_exterior_algebra.py:36 · validation/unit/homalg/test_exterior_algebra.py:163 · validation/unit/homalg/test_exterior_algebra.py:164 · validation/unit/homalg/test_exterior_algebra.py:165 · validation/unit/homalg/test_exterior_algebra.py:242 · validation/unit/homalg/test_exterior_algebra.py:246

`homalg.FreeModule.from_json`¶

Deserialize and revalidate a FreeModule from typed JSON.

Detailed contract

Deserialize and revalidate a based free module.

PythonRust

(cls, value: str) -> FreeModule[_BasicModuleRing]

noether::homalg::FreeModule::from_json · Direct Rust declaration

pub fn from_json(value: &str) -> Result<Self, NoetherError>where R: for<'de> Deserialize<'de>,

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/FreeModule@1

Executable usage: validation/unit/category/test_category.py:14 · validation/unit/combin/test_acceptance_workload.py:65 · validation/unit/combin/test_acceptance_workload.py:86 · validation/unit/combin/test_graph_facade.py:106 · validation/unit/combin/test_graph_facade.py:25 · validation/unit/combinatorics/test_kashiwara_crystal.py:32

`homalg.FreeModule.grading_rank`¶

Return the grading rank recorded by this FreeModule.

Detailed contract

Rank of the grading group when degree shifts are present.

PythonRust

(self) -> int | None

noether::homalg::FreeModule::grading_rank · Direct Rust declaration

pub fn grading_rank(&self) -> Option<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/FreeModule@1

Executable usage: examples/30_modules_and_resolutions.py:33 · examples/30_modules_and_resolutions.py:34 · validation/unit/commalg/test_polynomial_facade.py:434 · validation/unit/homalg/test_module_facade.py:234 · validation/unit/homalg/test_module_facade.py:241 · validation/unit/homalg/test_module_facade.py:483

`homalg.FreeModule.is_graded`¶

Test whether this FreeModule is graded.

Detailed contract

Whether this based module carries degree shifts.

PythonRust

(self) -> bool

noether::homalg::FreeModule::is_graded · Direct Rust declaration

pub fn is_graded(&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/FreeModule@1

Executable usage: validation/unit/commalg/test_construction_algebras.py:72 · validation/unit/commalg/test_quotient_facade.py:140 · validation/unit/commalg/test_quotient_facade.py:145 · validation/unit/commalg/test_quotient_facade.py:31

`homalg.FreeModule.rank`¶

Return the rank recorded by this FreeModule.

Detailed contract

Number of ordered basis vectors.

PythonRust

(self) -> int

noether::homalg::FreeModule::rank · Direct Rust declaration

pub fn 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/FreeModule@1

Executable usage: examples/38_exact_linear_systems.py:78 · examples/distributed/f2_linear_algebra.py:34 · examples/distributed/f2_linear_algebra.py:54 · examples/distributed/f2_linear_algebra.py:55 · examples/distributed/f2_linear_algebra.py:60 · validation/unit/combin/test_acceptance_workload.py:74

`homalg.FreeModule.ring`¶

Return the ring recorded by this FreeModule.

Detailed contract

Exact coefficient context.

PythonRust

(self) -> _BasicModuleRing

noether::homalg::FreeModule::ring · Direct Rust declaration

pub fn ring(&self) -> &R

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/FreeModule@1

Executable usage: examples/11_qadic_witt_vectors.py:3 · examples/13_chinese_remainder_theorem.py:10 · examples/13_chinese_remainder_theorem.py:12 · examples/13_chinese_remainder_theorem.py:9 · examples/14_weighted_polynomials.py:10 · examples/14_weighted_polynomials.py:11

`homalg.FreeModule.symmetric_power`¶

Compute symmetric power for this FreeModule.

Detailed contract

Construct the degree-degree symmetric power.

PythonRust

(self, degree: int) -> FreeModulePower[_BasicModuleRing]

noether::homalg::FreeModule::symmetric_power · Direct Rust declaration

pub fn symmetric_power( &self, degree: usize, ) -> Result<FreeModulePower<R>, ModulePowerError>

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	released
Semantic ID	noether/homalg/FreeModule@1

Executable usage: validation/unit/homalg/test_exterior_algebra.py:242 · validation/unit/homalg/test_exterior_algebra.py:286 · validation/unit/homalg/test_exterior_algebra.py:443 · validation/unit/homalg/test_module_powers.py:119 · validation/unit/homalg/test_module_powers.py:141 · validation/unit/homalg/test_module_powers.py:157

`homalg.FreeModule.tensor`¶

Compute tensor for this FreeModule.

Detailed contract

Tensor product of two based free modules over the same commutative context, with lexicographically ordered tensor basis.

PythonRust

(self, rhs: FreeModule[_BasicModuleRing]) -> FreeModule[_BasicModuleRing]

noether::homalg::FreeModule::tensor · Direct Rust declaration

pub fn tensor(&self, rhs: &Self) -> Result<Self, ModuleError>where R: CommutativeRing,

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	released
Semantic ID	noether/homalg/FreeModule@1

Executable usage: examples/23_kashiwara_crystals.py:10 · examples/23_kashiwara_crystals.py:3 · validation/unit/combin/test_acceptance_workload.py:58 · validation/unit/combinatorics/test_kashiwara_crystal.py:41 · validation/unit/combinatorics/test_kashiwara_crystal.py:42 · validation/unit/combinatorics/test_kashiwara_crystal.py:44

`homalg.FreeModule.to_json`¶

Serialize this FreeModule to its canonical typed JSON representation.

Detailed contract

Serialize the complete based module and coefficient context.

PythonRust

(self) -> str

noether::homalg::FreeModule::to_json · Direct Rust declaration

pub fn to_json(&self) -> Result<String, NoetherError>where R: Serialize,

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/FreeModule@1

Executable usage: validation/unit/category/test_category.py:14 · validation/unit/category/test_category.py:15 · validation/unit/combin/test_acceptance_workload.py:30 · validation/unit/combin/test_acceptance_workload.py:65 · validation/unit/combin/test_acceptance_workload.py:86 · validation/unit/combin/test_graph_facade.py:106

homalg · FreeModule¶

Worked example¶

homalg.FreeModule¶

homalg.FreeModule.basis_element¶

homalg.FreeModule.basis_labels¶

homalg.FreeModule.degree_shifts¶

homalg.FreeModule.direct_sum¶

homalg.FreeModule.dual¶

homalg.FreeModule.exterior_algebra¶

homalg.FreeModule.exterior_power¶

homalg.FreeModule.from_json¶

homalg.FreeModule.grading_rank¶

homalg.FreeModule.is_graded¶

homalg.FreeModule.rank¶

homalg.FreeModule.ring¶

homalg.FreeModule.symmetric_power¶

homalg.FreeModule.tensor¶

homalg.FreeModule.to_json¶

`homalg.FreeModule`¶

`homalg.FreeModule.basis_element`¶

`homalg.FreeModule.basis_labels`¶

`homalg.FreeModule.degree_shifts`¶

`homalg.FreeModule.direct_sum`¶

`homalg.FreeModule.dual`¶

`homalg.FreeModule.exterior_algebra`¶

`homalg.FreeModule.exterior_power`¶

`homalg.FreeModule.from_json`¶

`homalg.FreeModule.grading_rank`¶

`homalg.FreeModule.is_graded`¶

`homalg.FreeModule.rank`¶

`homalg.FreeModule.ring`¶

`homalg.FreeModule.symmetric_power`¶

`homalg.FreeModule.tensor`¶

`homalg.FreeModule.to_json`¶