Skip to content

commalg · RationalFunction

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

Worked example

The complete checked program Calculate trace and norm in a concrete quadratic finite field uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Calculate trace and norm in a concrete quadratic finite field."""

from noether.numthy import FiniteField


def main() -> None:
    field = FiniteField.extension(5, 2)
    generator = field.generator()
    assert generator**2 + field(4) * generator + field(2) == field.zero()
    assert generator.trace() == field(1)
    assert generator.norm() == field(2)
    print(f"{field}: Tr(a)={generator.trace()}, Nm(a)={generator.norm()}")


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/08_finite_field_extensions.py.

commalg.RationalFunction

One reduced rational function carrying its complete field context.

class RationalFunction

noether::commalg::RationalFunction · Direct Rust declaration

pub struct RationalFunction<R: Field> { /* private fields */ }
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: validation/unit/commalg/test_context_tower_workload.py:11 · validation/unit/commalg/test_context_tower_workload.py:79 · validation/unit/commalg/test_rational_function_facade.py:108 · validation/unit/commalg/test_rational_function_facade.py:15 · validation/unit/commalg/test_rational_function_facade.py:28 · validation/unit/commalg/test_rational_function_facade.py:97

commalg.RationalFunction.__add__

Add another compatible value to this value.

Detailed contract

Returns the argument unchanged.

(self, other: RationalFunction[C] | Polynomial[C] | FunctionCoefficient) -> RationalFunction[C]

noether::commalg::RationalFunction::add · Direct Rust declaration

fn add(self, rhs: &RationalFunction<R>) -> Self::Output
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

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

commalg.RationalFunction.__mul__

Multiply this value by another compatible value.

(self, other: RationalFunction[C] | Polynomial[C] | FunctionCoefficient) -> RationalFunction[C]

noether::commalg::RationalFunction::mul · Direct Rust declaration

fn mul(self, rhs: &RationalFunction<R>) -> Self::Output
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

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

commalg.RationalFunction.__neg__

Return the additive inverse of this value.

(self) -> RationalFunction[C]

noether::commalg::RationalFunction::neg · Direct Rust declaration

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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

commalg.RationalFunction.__pow__

Raise this value to the supplied power.

(self, exponent: int, modulus: None=None) -> RationalFunction[C]

noether::commalg::RationalFunction · 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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

commalg.RationalFunction.__radd__

Add this value to a compatible value on its left.

(self, other: Polynomial[C] | FunctionCoefficient) -> RationalFunction[C]

noether::commalg::RationalFunction · 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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

commalg.RationalFunction.__rmul__

Multiply this value by a compatible value on its left.

(self, other: Polynomial[C] | FunctionCoefficient) -> RationalFunction[C]

noether::commalg::RationalFunction · 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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

commalg.RationalFunction.__rsub__

Subtract this value from a compatible value on its left.

(self, other: Polynomial[C] | FunctionCoefficient) -> RationalFunction[C]

noether::commalg::RationalFunction · 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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

commalg.RationalFunction.__rtruediv__

Divide a compatible value on the left by this value.

(self, other: Polynomial[C] | FunctionCoefficient) -> RationalFunction[C]

noether::commalg::RationalFunction · 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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

commalg.RationalFunction.__sub__

Subtract another compatible value from this value.

(self, other: RationalFunction[C] | Polynomial[C] | FunctionCoefficient) -> RationalFunction[C]

noether::commalg::RationalFunction::sub · Direct Rust declaration

fn sub(self, rhs: &RationalFunction<R>) -> Self::Output
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

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

commalg.RationalFunction.__truediv__

Divide this value by another compatible value.

(self, other: RationalFunction[C] | Polynomial[C] | FunctionCoefficient) -> RationalFunction[C]

noether::commalg::RationalFunction · 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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

commalg.RationalFunction.denominator

Return the denominator recorded by this RationalFunction.

Detailed contract

Reduced, monic denominator.

(self) -> Polynomial[C]

noether::commalg::RationalFunction::denominator · Direct Rust declaration

pub fn denominator(&self) -> &Polynomial<R>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: validation/unit/commalg/test_curve_facade.py:51 · validation/unit/commalg/test_curve_facade.py:52 · validation/unit/commalg/test_curve_facade.py:93 · validation/unit/commalg/test_curve_facade.py:96 · validation/unit/commalg/test_local_algebra.py:30 · validation/unit/commalg/test_local_algebra.py:46

commalg.RationalFunction.field

Return the field recorded by this RationalFunction.

Detailed contract

Owning rational function field.

(self) -> RationalFunctionField[C]

noether::commalg::RationalFunction::field · Direct Rust declaration

pub fn field(&self) -> &RationalFunctionField<R>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: examples/08_finite_field_extensions.py:10 · examples/08_finite_field_extensions.py:11 · examples/08_finite_field_extensions.py:12 · examples/08_finite_field_extensions.py:13 · examples/08_finite_field_extensions.py:14 · examples/08_finite_field_extensions.py:3

commalg.RationalFunction.from_json

Deserialize and revalidate a supported canonical rational function.

Detailed contract

Deserialize and revalidate a canonical reduced rational function.

(cls, value: str) -> RationalFunction[FunctionCoefficientRing]

noether::commalg::RationalFunction::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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@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

commalg.RationalFunction.inverse

Compute inverse for this RationalFunction.

(self) -> RationalFunction[C]

noether::commalg::RationalFunction · 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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: examples/distributed/f2_linear_algebra.py:37 · examples/distributed/f2_linear_algebra.py:39 · validation/unit/commalg/test_context_tower_workload.py:121 · validation/unit/commalg/test_context_tower_workload.py:122 · validation/unit/commalg/test_context_tower_workload.py:75 · validation/unit/commalg/test_context_tower_workload.py:77

commalg.RationalFunction.is_nth_power

Whether this rational function is an exact positive integral power.

Detailed contract

Whether this rational function is an exact exponent-th power over Q. Whether this rational function is an exact exponent-th power.

(self, exponent: int) -> bool

noether::commalg::RationalFunction::is_nth_power · Direct Rust declaration

pub fn is_nth_power(&self, exponent: u64) -> Result<bool, PerfectPowerError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: validation/unit/commalg/test_polynomial_facade.py:179 · validation/unit/commalg/test_rational_function_facade.py:58 · validation/corpus/commalg/k3-univariate-certificates.py:63

commalg.RationalFunction.is_one

Test whether this RationalFunction is one.

Detailed contract

Whether this value is one.

(self) -> bool

noether::commalg::RationalFunction::is_one · Direct Rust declaration

pub fn is_one(&self) -> bool
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: validation/unit/commalg/test_rational_function_facade.py:31 · validation/unit/commalg/test_residue_ring_facade.py:25 · validation/unit/numthy/test_number_field_facade.py:29 · validation/corpus/commalg/evolution-algebra-isomorphism.py:34 · validation/corpus/numthy/diagonal-quadric-local-density-sums.py:36

commalg.RationalFunction.is_zero

Test whether this RationalFunction is zero.

Detailed contract

Whether this value is zero.

(self) -> bool

noether::commalg::RationalFunction::is_zero · Direct Rust declaration

pub fn is_zero(&self) -> bool
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: examples/17_weighted_power_series.py:16 · examples/17_weighted_power_series.py:17 · examples/39_kahler_differentials.py:20 · validation/unit/commalg/test_graded_commutative_facade.py:26 · validation/unit/commalg/test_kahler_differentials.py:113 · validation/unit/commalg/test_kahler_differentials.py:38

commalg.RationalFunction.nth_root

Extract a deterministic exact root, or return None when none exists.

Detailed contract

Extract an exact rational-function root, checking numerator and denominator valuations.

(self, exponent: int) -> RationalFunction[C] | None

noether::commalg::RationalFunction::nth_root · Direct Rust declaration

pub fn nth_root(&self, exponent: u64) -> Result<Option<Self>, PerfectPowerError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: validation/unit/commalg/test_polynomial_facade.py:180 · validation/unit/commalg/test_polynomial_facade.py:181 · validation/unit/commalg/test_polynomial_facade.py:183 · validation/unit/commalg/test_polynomial_facade.py:189 · validation/unit/commalg/test_rational_function_facade.py:59 · validation/unit/commalg/test_rational_function_facade.py:60

commalg.RationalFunction.numerator

Return the numerator recorded by this RationalFunction.

Detailed contract

Reduced numerator.

(self) -> Polynomial[C]

noether::commalg::RationalFunction::numerator · Direct Rust declaration

pub fn numerator(&self) -> &Polynomial<R>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: validation/unit/commalg/test_curve_facade.py:51 · validation/unit/commalg/test_curve_facade.py:52 · validation/unit/commalg/test_curve_facade.py:93 · validation/unit/commalg/test_curve_facade.py:95 · validation/unit/commalg/test_local_algebra.py:29 · validation/unit/commalg/test_monomial_ideal_facade.py:86

commalg.RationalFunction.pow

Compute pow for this RationalFunction.

Detailed contract

Raise to a nonnegative machine-word power.

(self, exponent: int) -> RationalFunction[C]

noether::commalg::RationalFunction::pow · Direct Rust declaration

pub fn pow(&self, exponent: u64) -> Result<Self, RationalFunctionError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: examples/17_weighted_power_series.py:18 · validation/unit/commalg/test_polynomial_ideal_facade.py:368 · validation/unit/commalg/test_polynomial_ideal_facade.py:369 · validation/unit/commalg/test_polynomial_ideal_facade.py:370 · validation/unit/commalg/test_polynomial_ideal_facade.py:373 · validation/unit/commalg/test_polynomial_ideal_facade.py:381

commalg.RationalFunction.specialize

Compute specialize for this RationalFunction.

Detailed contract

Evaluate at one coefficient-field value, failing at a pole.

(self, value: FunctionCoefficient) -> FunctionCoefficient

noether::commalg::RationalFunction::specialize · Direct Rust declaration

pub fn specialize( &self, value: &R::Element, ) -> Result<R::Element, RationalFunctionError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@1

Executable usage: examples/16_rational_functions.py:16 · examples/16_rational_functions.py:3 · validation/unit/commalg/test_rational_function_facade.py:33 · validation/unit/commalg/test_rational_function_facade.py:45 · validation/unit/commalg/test_rational_function_facade.py:80

commalg.RationalFunction.to_json

Serialize the field context and canonical reduced fraction.

(self) -> str

noether::commalg::RationalFunction::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, module-core, poly-core, resolution-kernel
GIL attached / bounded
Semantic ID noether/commalg/RationalFunction@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