homalg · ModuleElement

12 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.ModuleElement

An exact coordinate vector in one based free module.

PythonRust

ModuleElement(module: FreeModule[_BasicModuleRing], coordinates: Vector[_BasicModuleRing])

noether::homalg::ModuleElement · Direct Rust declaration

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

Executable usage: examples/30_modules_and_resolutions.py:24 · examples/30_modules_and_resolutions.py:25 · examples/30_modules_and_resolutions.py:9 · examples/38_exact_linear_systems.py:52 · examples/38_exact_linear_systems.py:53 · examples/38_exact_linear_systems.py:9

homalg.ModuleElement.__add__

Add another compatible value to this value.

Detailed contract

Add two elements of the same based module. Returns the argument unchanged.

PythonRust

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

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

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

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

homalg.ModuleElement.__mul__

Multiply this value by another compatible value.

PythonRust

(self, scalar: ModuleScalar) -> ModuleElement[_BasicModuleRing]

noether::homalg::ModuleElement · 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/ModuleElement@1

Executable usage: validation/unit/infra/test_public_api_index.py:214

homalg.ModuleElement.__neg__

Return the additive inverse of this value.

Detailed contract

Negate every coordinate.

PythonRust

(self) -> ModuleElement[_BasicModuleRing]

noether::homalg::ModuleElement::neg · Direct Rust declaration

pub fn neg(&self) -> Result<Self, ModuleError>
fn neg(self) -> 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/ModuleElement@1

homalg.ModuleElement.__rmul__

Multiply this value by a compatible value on its left.

PythonRust

(self, scalar: ModuleScalar) -> ModuleElement[_BasicModuleRing]

noether::homalg::ModuleElement · 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/ModuleElement@1

homalg.ModuleElement.__sub__

Subtract another compatible value from this value.

Detailed contract

Subtract two elements of the same based module.

PythonRust

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

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

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

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

homalg.ModuleElement.coordinates

Return the coordinates recorded by this ModuleElement.

Detailed contract

Exact coordinate vector in basis order.

PythonRust

(self) -> Vector[_BasicModuleRing]

noether::homalg::ModuleElement::coordinates · Direct Rust declaration

pub fn coordinates(&self) -> &Vector<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/ModuleElement@1

Executable usage: validation/unit/commalg/test_base_change.py:114 · validation/unit/commalg/test_base_change.py:54 · validation/unit/commalg/test_base_change.py:62 · validation/unit/commalg/test_kahler_differentials.py:131 · validation/unit/commalg/test_polynomial_ideal_facade.py:171 · validation/unit/commalg/test_quotient_facade.py:142

homalg.ModuleElement.from_json

Deserialize and revalidate a ModuleElement from typed JSON.

Detailed contract

Deserialize and revalidate a module element.

PythonRust

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

noether::homalg::ModuleElement::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/ModuleElement@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.ModuleElement.module

Return the module recorded by this ModuleElement.

Detailed contract

Ambient based free module.

PythonRust

(self) -> FreeModule[_BasicModuleRing]

noether::homalg::ModuleElement::module · Direct Rust declaration

pub fn module(&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/ModuleElement@1

Executable usage: examples/30_modules_and_resolutions.py:3 · examples/30_modules_and_resolutions.py:51 · examples/40_exterior_algebra.py:13 · examples/40_exterior_algebra.py:14 · examples/40_exterior_algebra.py:20 · examples/40_exterior_algebra.py:21

homalg.ModuleElement.scalar_mul

Compute scalar mul for this ModuleElement.

Detailed contract

Multiply every coordinate by a scalar in the base ring.

PythonRust

(self, scalar: ModuleScalar) -> ModuleElement[_BasicModuleRing]

noether::homalg::ModuleElement::scalar_mul · Direct Rust declaration

pub fn scalar_mul(&self, scalar: &R::Element) -> 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/ModuleElement@1

Executable usage: validation/unit/commalg/test_intersection_theory.py:30 · validation/unit/commalg/test_intersection_theory.py:37 · validation/unit/commalg/test_intersection_theory.py:51 · validation/unit/commalg/test_power_series_facade.py:152 · validation/unit/numthy/test_elliptic_curve_facade.py:36 · validation/bench/macaulay2_derived.py:693

homalg.ModuleElement.to_json

Serialize this ModuleElement to its canonical typed JSON representation.

Detailed contract

Serialize the ambient module and exact coordinates.

PythonRust

(self) -> str

noether::homalg::ModuleElement::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/ModuleElement@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.ModuleElement.zero

Construct a ModuleElement using zero.

Detailed contract

Zero element of one based free module.

PythonRust

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

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

pub fn zero(module: FreeModule<R>) -> 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/ModuleElement@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