Skip to content

homalg · ModuleHomomorphism

21 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.ModuleHomomorphism

An exact homomorphism between two based free modules.

ModuleHomomorphism(source: FreeModule[_BasicModuleRing], target: FreeModule[_BasicModuleRing], matrix: Matrix[_BasicModuleRing] | SparseMatrix[_BasicModuleRing])

noether::homalg::ModuleHomomorphism · Direct Rust declaration

pub struct ModuleHomomorphism<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/ModuleHomomorphism@1

Executable usage: examples/30_modules_and_resolutions.py:10 · examples/30_modules_and_resolutions.py:36 · examples/38_exact_linear_systems.py:63 · examples/38_exact_linear_systems.py:9 · examples/40_exterior_algebra.py:31 · examples/40_exterior_algebra.py:7

homalg.ModuleHomomorphism.__add__

Add another compatible value to this value.

Detailed contract

Add maps with identical source and target based modules. Returns the argument unchanged.

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

noether::homalg::ModuleHomomorphism::add · Direct Rust declaration

pub fn add(&self, rhs: &Self) -> Result<Self, ModuleError>
fn add(self, rhs: &ModuleHomomorphism<R>) -> Self::Output
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/ModuleHomomorphism@1

Executable usage: validation/unit/infra/test_discovery.py:211 · validation/unit/infra/test_public_api_index.py:293

homalg.ModuleHomomorphism.__call__

Coerce the supplied input through this context or mathematical map.

(self, element: ModuleElement[_BasicModuleRing]) -> ModuleElement[_BasicModuleRing]

noether::homalg::ModuleHomomorphism · Python projection

Python projection convenience over this Rust mathematical type
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/ModuleHomomorphism@1

Executable usage: validation/unit/infra/test_discovery.py:57 · validation/unit/infra/test_public_api_index.py:155 · validation/unit/infra/test_public_api_index.py:169

homalg.ModuleHomomorphism.__sub__

Subtract another compatible value from this value.

Detailed contract

Subtract maps with identical source and target based modules.

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

noether::homalg::ModuleHomomorphism::sub · Direct Rust declaration

pub fn sub(&self, rhs: &Self) -> Result<Self, ModuleError>
fn sub(self, rhs: &ModuleHomomorphism<R>) -> Self::Output
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/ModuleHomomorphism@1

Executable usage: validation/unit/infra/test_discovery.py:212

homalg.ModuleHomomorphism.apply

Apply this ModuleHomomorphism to the supplied value.

Detailed contract

Apply this map to an element of its exact source module.

(self, element: ModuleElement[_BasicModuleRing]) -> ModuleElement[_BasicModuleRing]

noether::homalg::ModuleHomomorphism::apply · Direct Rust declaration

pub fn apply( &self, element: &ModuleElement<R>, ) -> 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/ModuleHomomorphism@1

Executable usage: examples/05_sparse_exact_operators.py:16 · validation/unit/commalg/test_local_algebra.py:94 · validation/unit/commalg/test_local_algebra.py:97 · validation/unit/commalg/test_polynomial_facade.py:199 · validation/unit/commalg/test_quotient_facade.py:186 · validation/unit/groups/test_weight_characters.py:39

homalg.ModuleHomomorphism.compose

Compose this ModuleHomomorphism with another compatible map.

Detailed contract

Compose self after inner.

(self, inner: ModuleHomomorphism[_BasicModuleRing]) -> ModuleHomomorphism[_BasicModuleRing]

noether::homalg::ModuleHomomorphism::compose · Direct Rust declaration

pub fn compose(&self, inner: &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/ModuleHomomorphism@1

Executable usage: validation/unit/commalg/test_context_tower_workload.py:3 · validation/unit/commalg/test_polynomial_facade.py:200 · validation/unit/commalg/test_power_series_facade.py:151 · validation/unit/commalg/test_power_series_facade.py:245 · validation/unit/commalg/test_power_series_facade.py:248 · validation/unit/groups/test_permutation_group_facade.py:41

homalg.ModuleHomomorphism.dual

Compute dual for this ModuleHomomorphism.

Detailed contract

Dual map between the dual based free modules.

(self) -> ModuleHomomorphism[_BasicModuleRing]

noether::homalg::ModuleHomomorphism::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/ModuleHomomorphism@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.ModuleHomomorphism.exterior_power

Map induced on the degree-degree exterior power.

Detailed contract

Map induced on the degree-degree exterior powers.

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

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

pub fn exterior_power( &self, degree: usize, ) -> Result<ModulePowerHomomorphism<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/ModuleHomomorphism@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.ModuleHomomorphism.from_json

Deserialize and revalidate a ModuleHomomorphism from typed JSON.

Detailed contract

Deserialize and revalidate an exact module homomorphism.

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

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

pub fn from_json(value: &str) -> Result<Self, NoetherError>where R: for<'de> Deserialize<'de>, R::Element: 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/ModuleHomomorphism@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.ModuleHomomorphism.identity

Construct a ModuleHomomorphism using identity.

Detailed contract

Sparse identity map of one based free module.

(cls, module: FreeModule[_BasicModuleRing]) -> ModuleHomomorphism[_BasicModuleRing]

noether::homalg::ModuleHomomorphism::identity · Direct Rust declaration

pub fn identity(module: FreeModule<R>) -> 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/ModuleHomomorphism@1

Executable usage: examples/01_bezout_certificates.py:10 · examples/01_bezout_certificates.py:12 · examples/01_bezout_certificates.py:14 · examples/01_bezout_certificates.py:9 · examples/02_ball_arithmetic.py:3 · examples/distributed/f2_linear_algebra.py:20

homalg.ModuleHomomorphism.image

Image as the canonical submodule generated by this map.

Detailed contract

Canonical image lattice with map-bound completeness evidence. Canonical image submodule with map-bound completeness evidence.

(self: ModuleHomomorphism[_ExactModuleRing]) -> ImageSubmodule[_ExactModuleRing]
(self: ModuleHomomorphism[_ModuleRing]) -> Submodule[_ModuleRing]

noether::homalg::ModuleHomomorphism::image · Direct Rust declaration

pub fn image(&self) -> Result<ImageSubmodule<IntegerRing>, ModuleError>
pub fn image(&self) -> Result<ImageSubmodule<ResidueRing>, 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 released
Semantic ID noether/homalg/ModuleHomomorphism@1

Executable usage: examples/05_sparse_exact_operators.py:16 · examples/05_sparse_exact_operators.py:17 · examples/05_sparse_exact_operators.py:19 · examples/33_simplicial_cohomology_operations.py:30 · examples/33_simplicial_cohomology_operations.py:31 · examples/38_exact_linear_systems.py:69

homalg.ModuleHomomorphism.is_sparse

Test whether this ModuleHomomorphism is sparse.

Detailed contract

Whether the map retains canonical sparse storage.

(self) -> bool

noether::homalg::ModuleHomomorphism::is_sparse · Direct Rust declaration

pub fn is_sparse(&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/ModuleHomomorphism@1

Executable usage: validation/unit/homalg/test_module_facade.py:637

homalg.ModuleHomomorphism.kernel

Exact kernel; polynomial contexts additionally require a monomial order.

Detailed contract

Canonical complete kernel lattice with map-bound evidence. Canonical complete kernel with evidence over a possibly composite modulus. Exact kernel as a generated integral polynomial submodule. Exact kernel as a generated submodule of this map’s source. Exact kernel over a polynomial quotient, computed through the lifted graph [lift(self), -I e_j] in the ambient polynomial ring.

(self: ModuleHomomorphism[_ExactModuleRing], order: None=None) -> KernelSubmodule[_ExactModuleRing]
(self: ModuleHomomorphism[_GroebnerModuleRing], order: ModuleMonomialOrder) -> Submodule[_GroebnerModuleRing]
(self: ModuleHomomorphism[_IntegralModuleRing], order: ModuleMonomialOrder) -> Submodule[_IntegralModuleRing]

noether::homalg::ModuleHomomorphism::kernel · Direct Rust declaration

pub fn kernel(&self) -> Result<KernelSubmodule<IntegerRing>, ModuleError>
pub fn kernel(&self) -> Result<KernelSubmodule<ResidueRing>, ModuleError>
pub fn kernel( &self, order: ModuleMonomialOrder, ) -> Result<Submodule<PolynomialRing<IntegerRing>>, ModuleGroebnerError>
pub fn kernel( &self, order: ModuleMonomialOrder, ) -> Result<Submodule<PolynomialRing<C>>, ModuleGroebnerError>
pub fn kernel( &self, order: ModuleMonomialOrder, ) -> Result<Submodule<QuotientRing<PolynomialRing<C>>>, ModuleGroebnerError>
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/ModuleHomomorphism@1

Executable usage: examples/38_exact_linear_systems.py:68 · examples/38_exact_linear_systems.py:70 · examples/38_exact_linear_systems.py:72 · validation/unit/homalg/test_exact_submodules.py:78 · validation/unit/homalg/test_exact_submodules.py:93 · validation/unit/homalg/test_exact_submodules.py:95

homalg.ModuleHomomorphism.matrix

Return the matrix recorded by this ModuleHomomorphism.

Detailed contract

Losslessly materialize the presentation matrix.

(self) -> Matrix[_BasicModuleRing]

noether::homalg::ModuleHomomorphism::matrix · Direct Rust declaration

pub fn matrix(&self) -> Matrix<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/ModuleHomomorphism@1

Executable usage: examples/03_exact_linear_systems.py:10 · examples/03_exact_linear_systems.py:12 · examples/03_exact_linear_systems.py:14 · examples/04_smith_normal_form.py:10 · examples/04_smith_normal_form.py:11 · examples/29_integral_line_configurations.py:28

homalg.ModuleHomomorphism.source

Return the source recorded by this ModuleHomomorphism.

Detailed contract

Source based free module.

(self) -> FreeModule[_BasicModuleRing]

noether::homalg::ModuleHomomorphism::source · Direct Rust declaration

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

Executable usage: examples/09_finite_field_isomorphisms.py:11 · examples/09_finite_field_isomorphisms.py:13 · examples/09_finite_field_isomorphisms.py:9 · examples/30_modules_and_resolutions.py:34 · examples/30_modules_and_resolutions.py:37 · validation/unit/category/test_acceptance_workload.py:25

homalg.ModuleHomomorphism.sparse_matrix

Return the sparse matrix recorded by this ModuleHomomorphism.

Detailed contract

Borrow the sparse presentation when this map retains sparse storage.

(self) -> SparseMatrix[_BasicModuleRing] | None

noether::homalg::ModuleHomomorphism::sparse_matrix · Direct Rust declaration

pub fn sparse_matrix(&self) -> Option<&SparseMatrix<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/ModuleHomomorphism@1

Executable usage: validation/unit/numthy/test_padic_ring_facade.py:103 · validation/unit/numthy/test_padic_ring_facade.py:96

homalg.ModuleHomomorphism.symmetric_power

Map induced on the degree-degree symmetric power.

Detailed contract

Map induced on the degree-degree symmetric powers.

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

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

pub fn symmetric_power( &self, degree: usize, ) -> Result<ModulePowerHomomorphism<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/ModuleHomomorphism@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.ModuleHomomorphism.target

Return the target recorded by this ModuleHomomorphism.

Detailed contract

Target based free module.

(self) -> FreeModule[_BasicModuleRing]

noether::homalg::ModuleHomomorphism::target · Direct Rust declaration

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

Executable usage: examples/09_finite_field_isomorphisms.py:10 · examples/09_finite_field_isomorphisms.py:11 · examples/30_modules_and_resolutions.py:33 · examples/30_modules_and_resolutions.py:38 · examples/31_local_fields_and_precision.py:27 · examples/36_affine_normalization.py:16

homalg.ModuleHomomorphism.tensor

Compute tensor for this ModuleHomomorphism.

Detailed contract

Tensor product of maps between finite based free modules. The tensor bases use the same lexicographic order as FreeModule::tensor: the left basis position is the outer index and the right basis position is the inner index. Sparse inputs retain a sparse Kronecker product without materializing zero coefficients.

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

noether::homalg::ModuleHomomorphism::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 attached / bounded
Semantic ID noether/homalg/ModuleHomomorphism@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.ModuleHomomorphism.to_json

Serialize this ModuleHomomorphism to its canonical typed JSON representation.

Detailed contract

Serialize both endpoint modules and the retained matrix layout.

(self) -> str

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

pub fn to_json(&self) -> Result<String, NoetherError>where R: Serialize, R::Element: 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/ModuleHomomorphism@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.ModuleHomomorphism.zero

Construct a ModuleHomomorphism using zero.

Detailed contract

Sparse zero map between two modules over the same exact ring context.

(cls, source: FreeModule[_BasicModuleRing], target: FreeModule[_BasicModuleRing]) -> ModuleHomomorphism[_BasicModuleRing]

noether::homalg::ModuleHomomorphism::zero · Direct Rust declaration

pub fn zero( source: FreeModule<R>, target: FreeModule<R>, ) -> 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/ModuleHomomorphism@1

Executable usage: examples/08_finite_field_extensions.py:11 · examples/10_padic_hensel_lifting.py:15 · examples/40_exterior_algebra.py:26 · examples/distributed/f2_linear_algebra.py:28 · examples/distributed/f2_linear_algebra.py:29 · examples/distributed/f2_linear_algebra.py:30