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.
noether::homalg::ModuleHomomorphism · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::add · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism · Python projection
| 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.
noether::homalg::ModuleHomomorphism::sub · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::apply · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::compose · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::dual · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::exterior_power · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::from_json · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::identity · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::image · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::is_sparse · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::matrix · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::source · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::sparse_matrix · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::symmetric_power · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::target · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::tensor · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::to_json · Direct Rust declaration
| 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.
noether::homalg::ModuleHomomorphism::zero · Direct Rust declaration
| 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