Module polynomial 

Unified Polynomial Module

This module provides comprehensive polynomial operations with automatic classification, smart dispatch, and optional educational explanations.

Architecture

The polynomial module is designed around these principles:

1. Automatic Classification: Users don’t need to manually wrap expressions. The system automatically detects polynomial structure and routes to optimized algorithms.

2. Decomposed Traits: Instead of a monolithic trait, functionality is split into:

   • PolynomialClassification - Type detection and variable extraction
   • PolynomialProperties - Degree, leading coefficient, content, primitive part
   • PolynomialArithmetic - Division operations
   • PolynomialGcdOps - GCD, LCM, cofactors
   • PolynomialEducational - Step-by-step explanations (opt-in)

3. Side-Table Caching: Expensive computations (degree, classification) are cached using thread-local LRU cache, preserving the 32-byte Expression size constraint.

4. Smart Dispatch: GCD and other functions check cheap cases (integers, zero, one, symbols) BEFORE expensive classification.

5. Unified Dispatch: The dispatch module automatically routes operations to the optimal Poly<T> implementation based on coefficient type analysis:

   • All integers → IntPoly (fastest)
   • Any rationals → RationalPoly (field operations)
   • Multivariate → symbolic fallback

Example

use mathhook_core::{expr, symbol};

let x = symbol!(x);
let p1 = expr!(x^2 - 1);
let p2 = expr!(x - 1);

// Automatic polynomial GCD - no wrapping needed!
let gcd = p1.gcd(&p2);  // Returns x - 1

Submodules

• algorithms - Core polynomial algorithms (division, GCD, factorization)
• dispatch - Unified dispatch to optimal Poly<T> implementations
• educational - Step-by-step explanation generation
• groebner - Groebner basis computation (migrated from algebra/groebner)
• sparse_polynomial - Efficient sparse polynomial representation
• special_families - Orthogonal polynomials (Legendre, Hermite, etc.)

Re-exports

pub use educational::PolynomialEducational;

pub use poly::IntPoly;

pub use poly::Poly;

pub use poly::RationalPoly;

pub use traits::EuclideanDomain;

pub use traits::Field;

pub use traits::Ring;

pub use crate::algebra::gcd::polynomial_gcd;

pub use crate::algebra::gcd::univariate_gcd;

pub use algorithms::integer_gcd;

pub use algorithms::square_free_factorization_poly;

pub use sparse_polynomial::expression_to_sparse_polynomial;

pub use sparse_polynomial::sparse_polynomial_to_expression;

pub use sparse_polynomial::Monomial;

pub use sparse_polynomial::SparsePolynomial;

Modules

algorithms

Polynomial Algorithm Implementations

dispatch

Unified polynomial dispatch layer

educational

Polynomial Educational Module

finite_field

Finite Field Arithmetic for Modular GCD Algorithms

groebner

Groebner Basis Computation

poly

Generic univariate polynomial over any ring

sparse_polynomial

Efficient Sparse Polynomial Representation for Gröbner Basis

special_families

Special Polynomial Families

traits

Algebraic trait hierarchy for polynomial coefficient types

Structs

CacheStats

Cache statistics for monitoring

PolynomialCache

Thread-local polynomial computation cache

Enums

CachedClassification

Cached classification result

PolynomialError

Errors that can occur during polynomial operations

Traits

PolynomialArithmetic

Trait for polynomial arithmetic operations

PolynomialClassification

Trait for polynomial classification

PolynomialGcdOps

Trait for polynomial GCD operations

PolynomialProperties

Trait for polynomial properties

Functions

cache_stats

Get statistics from the thread-local polynomial cache

clear_cache

Clear the thread-local polynomial cache

coefficient_at

Get the coefficient at a specific degree

coefficients_list

Get all coefficients as a vector ordered by degree (ascending)

constant_term

Extract the constant term (coefficient of degree 0)

extract_coefficient_map

Extract all coefficients of a polynomial as a map from degree to coefficient

get_or_compute_intpoly

Get or compute IntPoly representation with caching

is_monic

Check if polynomial is monic (leading coefficient is 1)

with_cache

Access the thread-local polynomial cache