mathhook_core/core/
polynomial.rs

1//! Unified Polynomial Module
2//!
3//! This module provides comprehensive polynomial operations with automatic classification,
4//! smart dispatch, and optional educational explanations.
5//!
6//! # Architecture
7//!
8//! The polynomial module is designed around these principles:
9//!
10//! 1. **Automatic Classification**: Users don't need to manually wrap expressions.
11//!    The system automatically detects polynomial structure and routes to optimized algorithms.
12//!
13//! 2. **Decomposed Traits**: Instead of a monolithic trait, functionality is split into:
14//!    - `PolynomialClassification` - Type detection and variable extraction
15//!    - `PolynomialProperties` - Degree, leading coefficient, content, primitive part
16//!    - `PolynomialArithmetic` - Division operations
17//!    - `PolynomialGcdOps` - GCD, LCM, cofactors
18//!    - `PolynomialEducational` - Step-by-step explanations (opt-in)
19//!
20//! 3. **Side-Table Caching**: Expensive computations (degree, classification) are cached
21//!    using thread-local LRU cache, preserving the 32-byte Expression size constraint.
22//!
23//! 4. **Smart Dispatch**: GCD and other functions check cheap cases
24//!    (integers, zero, one, symbols) BEFORE expensive classification.
25//!
26//! 5. **Unified Dispatch**: The `dispatch` module automatically routes operations to
27//!    the optimal `Poly<T>` implementation based on coefficient type analysis:
28//!    - All integers → `IntPoly` (fastest)
29//!    - Any rationals → `RationalPoly` (field operations)
30//!    - Multivariate → symbolic fallback
31//!
32//! # Example
33//!
34//! ```rust,ignore
35//! use mathhook_core::{expr, symbol};
36//!
37//! let x = symbol!(x);
38//! let p1 = expr!(x^2 - 1);
39//! let p2 = expr!(x - 1);
40//!
41//! // Automatic polynomial GCD - no wrapping needed!
42//! let gcd = p1.gcd(&p2);  // Returns x - 1
43//! ```
44//!
45//! # Submodules
46//!
47//! - `algorithms` - Core polynomial algorithms (division, GCD, factorization)
48//! - `dispatch` - Unified dispatch to optimal `Poly<T>` implementations
49//! - `educational` - Step-by-step explanation generation
50//! - `groebner` - Groebner basis computation (migrated from algebra/groebner)
51//! - `sparse_polynomial` - Efficient sparse polynomial representation
52//! - `special_families` - Orthogonal polynomials (Legendre, Hermite, etc.)
53
54pub mod algorithms;
55mod arithmetic;
56mod cache;
57mod classification;
58mod coefficients;
59pub mod dispatch;
60pub mod educational;
61mod error;
62pub mod finite_field;
63mod gcd_ops;
64pub mod groebner;
65pub mod poly;
66mod properties;
67pub mod sparse_polynomial;
68pub mod special_families;
69pub mod traits;
70
71pub use cache::{
72    cache_stats, clear_cache, get_or_compute_intpoly, with_cache, CacheStats, CachedClassification,
73    PolynomialCache,
74};
75pub use classification::PolynomialClassification;
76pub use error::PolynomialError;
77pub use properties::PolynomialProperties;
78
79pub use arithmetic::PolynomialArithmetic;
80pub use gcd_ops::PolynomialGcdOps;
81
82pub use educational::PolynomialEducational;
83
84pub use coefficients::{
85    coefficient_at, coefficients_list, constant_term, extract_coefficient_map, is_monic,
86};
87
88pub use poly::{IntPoly, Poly, RationalPoly};
89
90pub use traits::{EuclideanDomain, Field, Ring};
91
92// Expression-based GCD operations imported from algebra
93pub use crate::algebra::gcd::{polynomial_gcd, univariate_gcd};
94
95// Pure i64 integer GCD
96pub use algorithms::integer_gcd;
97
98// Pure Poly<T> factorization
99pub use algorithms::square_free_factorization_poly;
100
101pub use sparse_polynomial::{
102    expression_to_sparse_polynomial, sparse_polynomial_to_expression, Monomial, SparsePolynomial,
103};
mathhook_core/core/polynomial.rs

mathhook_core/core/
polynomial.rs
