diff --git a/M2/Macaulay2/e/basic-rings/aring-CC.hpp b/M2/Macaulay2/e/basic-rings/aring-CC.hpp index c3cc3ab8843..bdb8e7b74c8 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CC.hpp @@ -1,5 +1,21 @@ // Copyright 2012 Michael E. Stillman +/// AI: +/// \file aring-CC.hpp +/// \brief Defines ARingCC, the machine-precision complex arithmetic ring. +/// +/// This header declares the ARing implementation for approximate complex +/// numbers stored as `cc_doubles_struct`, a pair of machine doubles. The class +/// follows the `SimpleARing` contract: its lifetime functions initialize, copy, +/// assign, and clear the raw element storage used by wrapper code. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// complex-ring operations through the methods declared here: `ring_elem` +/// conversion, arithmetic, comparison, printing, randomization, and precision +/// helpers. `aring-translate.hpp` uses the real and complex setters here for +/// promotion and lifting among RR, CC, higher-precision complex rings, interval +/// rings, and exact input. + #ifndef M2_BASIC_RINGS_ARING_CC_HPP_ #define M2_BASIC_RINGS_ARING_CC_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-CCC.hpp b/M2/Macaulay2/e/basic-rings/aring-CCC.hpp index 1995cb669fc..a0e80aa7fb6 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCC.hpp @@ -1,5 +1,21 @@ // Copyright 2012 Michael E. Stillman +/// AI: +/// \file aring-CCC.hpp +/// \brief Defines ARingCCC, the arbitrary-precision complex arithmetic ring. +/// +/// This header declares the ARing implementation for arbitrary-precision +/// complex numbers stored as two MPFR values in a `cc_struct`. The ring +/// carries an `ARingRRR` with the same precision for real-part operations. Its +/// `SimpleARing` lifetime methods handle MPFR initialization and cleanup. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// complex-ring operations through the methods declared here: `ring_elem` +/// conversion, arithmetic, comparison, printing, randomization, and precision +/// helpers. `aring-translate.hpp` uses the high-precision real and complex +/// setters here for promotion and lifting among QQ, RR/RRR, CC/CCC, and +/// interval rings. + #ifndef M2_BASIC_RINGS_ARING_CCC_HPP_ #define M2_BASIC_RINGS_ARING_CCC_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-CCi.hpp b/M2/Macaulay2/e/basic-rings/aring-CCi.hpp index 4dee4f9a163..3ed664de4ca 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCi.hpp @@ -1,5 +1,22 @@ // Copyright 2012 Michael E. Stillman +/// AI: +/// \file aring-CCi.hpp +/// \brief Defines ARingCCi, the arbitrary-precision complex interval ring. +/// +/// This header declares the ARing implementation for arbitrary-precision +/// complex intervals stored as real and imaginary MPFI intervals in +/// `cci_struct`. The ring carries the precision used by those intervals, and +/// its `SimpleARing` lifetime methods initialize, copy, assign, and clear the +/// interval storage. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// complex-interval operations through the methods declared here: `ring_elem` +/// conversion, arithmetic, containment and subset predicates, printing, and +/// randomization. `aring-translate.hpp` uses the real, complex, and interval +/// setters here for promotion and lifting among RRi, RRR, CCC, CCi, and exact +/// input. + #ifndef M2_BASIC_RINGS_ARING_CCI_HPP_ #define M2_BASIC_RINGS_ARING_CCI_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp b/M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp index 77ebdd41840..72809c5b87f 100644 --- a/M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp @@ -1,5 +1,22 @@ // Copyright 2014 Michael E. Stillman +/// AI: +/// \file aring-GF-flint-big.hpp +/// \brief Defines ARingGFFlintBig, a FLINT fq_nmod finite field ring. +/// +/// This header declares the ARing implementation for finite-field extensions +/// stored with FLINT's `fq_nmod` representation. The ring owns the FLINT +/// context, original polynomial ring, characteristic, extension degree, and +/// generator data, so it derives from `RingInterface` and defines context-aware +/// `Element` and `ElementArray` wrappers instead of using `SimpleARing`. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and +/// forwards extension-field operations through the methods declared here: +/// `ring_elem` conversion, arithmetic, comparison, evaluation, printing, and +/// finite-field metadata. Factory, promotion, lift, and representation code +/// use `originalRing`, generator access, and polynomial coefficient helpers to +/// connect GF(p^n) elements with quotient-ring representatives. + #ifndef M2_BASIC_RINGS_ARING_GF_FLINT_BIG_HPP_ #define M2_BASIC_RINGS_ARING_GF_FLINT_BIG_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp b/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp index 081dd902075..a03ab0f22e6 100644 --- a/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp @@ -1,5 +1,23 @@ // Copyright 2014 Michael E. Stillman +/// AI: +/// \file aring-GF-flint.hpp +/// \brief Defines ARingGFFlint, a FLINT fq_zech finite field ring. +/// +/// This header declares the ARing implementation for finite-field extensions +/// stored with FLINT's `fq_zech` Zech-log representation. Each element depends +/// on a FLINT context for initialization and destruction, so the class derives +/// from `RingInterface` and defines context-aware `Element` and `ElementArray` +/// wrappers instead of using `SimpleARing`. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and +/// forwards extension-field operations through the methods declared here: +/// `ring_elem` conversion, arithmetic, comparison, discrete logarithms, +/// evaluation, printing, and finite-field metadata. Factory, promotion, lift, +/// and representation code use the stored quotient-ring data, primitive +/// generator, and coefficient helpers to relate Zech elements back to +/// polynomial representatives. + #ifndef M2_BASIC_RINGS_ARING_GF_FLINT_HPP_ #define M2_BASIC_RINGS_ARING_GF_FLINT_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp b/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp index d39be513537..68c89c859ec 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp @@ -1,5 +1,21 @@ // Copyright 2013 Michael E. Stillman +/// AI: +/// \file aring-QQ-flint.hpp +/// \brief Defines ARingQQFlint, the FLINT-backed rational arithmetic ring. +/// +/// This header declares the ARing implementation for rational numbers stored +/// as FLINT `fmpq` values. The class follows the `SimpleARing` contract: its +/// lifetime functions initialize, copy, assign, and clear the FLINT rational +/// storage used by wrapper code. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` when this +/// backend is selected and forwards exact rational operations through the +/// methods declared here: `ring_elem` conversion, construction from integers +/// and rationals, arithmetic, comparison, hashing, printing, and randomization. +/// `aring-translate.hpp` uses the rational representation as a source for +/// approximate real, interval, and complex promotion. + #ifndef M2_BASIC_RINGS_ARING_QQ_FLINT_HPP_ #define M2_BASIC_RINGS_ARING_QQ_FLINT_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp b/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp index 540220c9914..5ea21e6eefd 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp @@ -1,5 +1,21 @@ // Copyright 2013 Michael E. Stillman +/// AI: +/// \file aring-QQ-gmp.hpp +/// \brief Defines ARingQQGMP, the GMP-backed rational arithmetic ring. +/// +/// This header declares the ARing implementation for rational numbers stored +/// as GMP `mpq` values. It is the current `ARingQQ` backend selected by +/// `aring-QQ.hpp`, and its `SimpleARing` lifetime methods initialize, copy, +/// assign, and clear the GMP rational storage used by wrapper code. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// exact rational operations through the methods declared here: `ring_elem` +/// conversion, construction from integers and rationals, arithmetic, +/// comparison, hashing, printing, and randomization. `aring-translate.hpp` +/// uses QQ as a central exact source for promotion into real, complex, and +/// interval ARings through the relevant `set_from_*` methods. + #ifndef M2_BASIC_RINGS_ARING_QQ_GMP_HPP_ #define M2_BASIC_RINGS_ARING_QQ_GMP_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-QQ.hpp b/M2/Macaulay2/e/basic-rings/aring-QQ.hpp index 21e53f91920..677e193090c 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ.hpp @@ -1,5 +1,20 @@ // Copyright 2013 Michael E. Stillman. +/// AI: +/// \file aring-QQ.hpp +/// \brief Selects the default ARing implementation for rational numbers. +/// +/// This header is the coordination point for rational ARings. It includes the +/// available QQ backends and defines the `ARingQQ` typedef used by code that +/// wants the default rational implementation rather than a specific GMP or +/// FLINT class. +/// +/// `aring-glue.hpp`, `aring-translate.hpp`, factory code, and tests include +/// this header when they need the selected QQ backend. Changing the typedef +/// changes the implementation used by `RingQQ::create()` and by promotion/lift +/// code that names `ARingQQ`, while the backend headers remain available for +/// places that need an explicit implementation. + #ifndef M2_BASIC_RINGS_ARING_QQ_HPP_ #define M2_BASIC_RINGS_ARING_QQ_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-RR.hpp b/M2/Macaulay2/e/basic-rings/aring-RR.hpp index 686172c6879..ef0386cdaaa 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RR.hpp @@ -1,5 +1,21 @@ // Copyright 2012 Michael E. Stillman +/// AI: +/// \file aring-RR.hpp +/// \brief Defines ARingRR, the machine-precision real arithmetic ring. +/// +/// This header declares the ARing implementation for machine-precision real +/// numbers stored as `double` values. The class follows the `SimpleARing` +/// contract, and its lifetime functions are lightweight initialization, copy, +/// assignment, and clear operations for plain double storage. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// real-ring operations through the methods declared here: `ring_elem` +/// conversion, arithmetic, comparison, hashing, printing, randomization, and +/// precision helpers. `aring-translate.hpp` uses RR as both a target and a +/// source for promotion and lifting among exact, high-precision real, interval, +/// and complex rings. + #ifndef M2_BASIC_RINGS_ARING_RR_HPP_ #define M2_BASIC_RINGS_ARING_RR_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-RRR.hpp b/M2/Macaulay2/e/basic-rings/aring-RRR.hpp index 006dda679ad..4d64f86c457 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRR.hpp @@ -1,5 +1,21 @@ // Copyright 2012 Michael E. Stillman +/// AI: +/// \file aring-RRR.hpp +/// \brief Defines ARingRRR, the arbitrary-precision real arithmetic ring. +/// +/// This header declares the ARing implementation for arbitrary-precision real +/// numbers stored as MPFR values. The ring object carries the precision, and +/// its `SimpleARing` lifetime methods initialize, copy, assign, and clear each +/// MPFR element with that precision. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// real-ring operations through the methods declared here: `ring_elem` +/// conversion, arithmetic, comparison, hashing, printing, randomization, and +/// precision helpers. `aring-translate.hpp` uses the high-precision real +/// setters here for promotion and lifting among QQ, RR, RRR, interval rings, +/// and complex rings that use `ARingRRR` as their real component. + #ifndef M2_BASIC_RINGS_ARING_RRR_HPP_ #define M2_BASIC_RINGS_ARING_RRR_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-RRi.hpp b/M2/Macaulay2/e/basic-rings/aring-RRi.hpp index 22ba45aa215..6e9b77d0059 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRi.hpp @@ -1,5 +1,21 @@ // Copyright 2012 Michael E. Stillman +/// AI: +/// \file aring-RRi.hpp +/// \brief Defines ARingRRi, the arbitrary-precision real interval ring. +/// +/// This header declares the ARing implementation for arbitrary-precision real +/// intervals stored with MPFI. The ring object carries the precision, and its +/// `SimpleARing` lifetime methods initialize, copy, assign, and clear the +/// interval storage. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// real-interval operations through the methods declared here: `ring_elem` +/// conversion, arithmetic, containment and subset predicates, printing, and +/// randomization. `aring-translate.hpp` uses the interval setters here for +/// promotion and lifting among exact rational, real, complex, and complex +/// interval rings. + #ifndef M2_BASIC_RINGS_ARING_RRI_HPP_ #define M2_BASIC_RINGS_ARING_RRI_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp index 1e64612232a..f085a802aa5 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp @@ -1,5 +1,21 @@ // Copyright 2013 Michael E. Stillman +/// AI: +/// \file aring-ZZ-flint.hpp +/// \brief Defines ARingZZ, the FLINT-backed integer arithmetic ring. +/// +/// This header declares the ARing implementation for integers stored as FLINT +/// `fmpz` values. The class follows the `SimpleARing` contract: its lifetime +/// functions initialize, copy, assign, and clear the FLINT integer storage used +/// by wrapper code. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// exact integer operations through the methods declared here: `ring_elem` +/// conversion, construction from C longs and GMP integers, arithmetic, +/// comparison, hashing, printing, randomization, and integer lifting. ZZ is a +/// root source for many promotion paths before more specialized conversions +/// continue in `aring-translate.hpp`. + #ifndef M2_BASIC_RINGS_ARING_ZZ_FLINT_HPP_ #define M2_BASIC_RINGS_ARING_ZZ_FLINT_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp index 3b3029641f2..2eed71dc754 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp @@ -1,5 +1,22 @@ // Copyright 2013 Michael E. Stillman +/// AI: +/// \file aring-ZZ-gmp.hpp +/// \brief Defines ARingZZGMP, the GMP-backed integer arithmetic ring. +/// +/// This header declares the ARing implementation for integers stored as GMP +/// `mpz` values. The class follows the `SimpleARing` contract: its lifetime +/// functions initialize, copy, assign, and clear the GMP integer storage used +/// by wrapper code. +/// +/// `aring-glue.hpp` can wrap this ARing in `ConcreteRing` and +/// forward exact integer operations through the methods declared here: +/// `ring_elem` conversion, construction from C longs and GMP integers, +/// arithmetic, comparison, hashing, printing, randomization, and memory +/// normalization. It also serves as an alternate backend and reference for the +/// operations integer ARings provide before promotion code maps ZZ into other +/// coefficient rings. + #ifndef M2_BASIC_RINGS_ARING_ZZ_GMP_HPP_ #define M2_BASIC_RINGS_ARING_ZZ_GMP_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp index a608f5b9da4..f06c1442982 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp @@ -1,5 +1,21 @@ // Copyright 2011 Michael E. Stillman +/// AI: +/// \file aring-ZZp-ffpack.hpp +/// \brief Defines ARingZZpFFPACK, an FFPACK/Givaro prime finite field ring. +/// +/// This header declares the ARing implementation for prime finite fields backed +/// by a Givaro modular field for FFPACK/FFLAS dense linear algebra. The raw +/// element type is the Givaro field element, and the class follows the +/// `SimpleARing` contract for lifetime and arithmetic over that storage. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and +/// forwards prime-field operations through the methods declared here: +/// construction from integers and rationals, `ring_elem` conversion, +/// arithmetic, comparison, balanced integer coercion, generator access, +/// discrete logarithms, and printing. Matrix and vector code use this backend +/// when selecting FFPACK/FFLAS dense arithmetic paths. + #ifndef M2_BASIC_RINGS_ARING_FFPACK_HPP_ #define M2_BASIC_RINGS_ARING_FFPACK_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp index 3f8097fa1f0..0f68bebdebb 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp @@ -1,5 +1,22 @@ // Copyright 2013 Michael E. Stillman +/// AI: +/// \file aring-ZZp-flint.hpp +/// \brief Defines ARingZZpFlint, a FLINT-backed prime finite field ring. +/// +/// This header declares the ARing implementation for prime finite fields backed +/// by FLINT `nmod` arithmetic for word-sized moduli. Its `ElementType` is an +/// `mp_limb_t`, so `SimpleARing` can manage elements with inexpensive +/// initialization and no-op cleanup while the ring object stores the modulus +/// and generator data. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and +/// forwards prime-field operations through the methods declared here: +/// construction from ZZ/QQ, `ring_elem` conversion, arithmetic, comparison, +/// hashing, printing, randomization, integer lifting, generator access, and +/// discrete logarithms. Vector and matrix code use this backend when selecting +/// FLINT-backed dense arithmetic paths. + #ifndef M2_BASIC_RINGS_ARING_ZZP_FLINT_HPP_ #define M2_BASIC_RINGS_ARING_ZZP_FLINT_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp index 177acba081d..1c4081546e5 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp @@ -1,5 +1,21 @@ // Copyright 2011 Michael E. Stillman +/// AI: +/// \file aring-ZZp.hpp +/// \brief Defines ARingZZp, Macaulay2's table-based prime finite field ring. +/// +/// This header declares the ARing implementation for table-based prime finite +/// fields. Elements are compact integers interpreted through logarithm and +/// exponent tables for a primitive element, and the class follows the +/// `SimpleARing` contract for lifetime and arithmetic over that storage. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// prime-field operations through the methods declared here: construction from +/// ZZ/QQ, `ring_elem` conversion, arithmetic, comparison, randomization, +/// integer lifting, generator access, and discrete logarithms. Promotion and +/// lift code includes explicit dispatch between this table backend and the +/// FFPACK-backed prime field when their characteristics are compatible. + #ifndef M2_BASIC_RINGS_ARING_ZZP_HPP_ #define M2_BASIC_RINGS_ARING_ZZP_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-glue.hpp b/M2/Macaulay2/e/basic-rings/aring-glue.hpp index 363763f52d9..e988c97bdb0 100644 --- a/M2/Macaulay2/e/basic-rings/aring-glue.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-glue.hpp @@ -1,5 +1,21 @@ // Copyright 2011 Michael E. Stillman +/// AI: +/// \file aring-glue.hpp +/// \brief Connects ARing implementations to the high-level Ring interface. +/// +/// This header contains the adapter that makes an ARing usable through the +/// engine's virtual `Ring` API. `ConcreteRing` owns one ARing +/// object, creates ARing element wrappers around incoming `ring_elem` values, +/// calls the corresponding `RingType` method, and converts results back to +/// `ring_elem`. +/// +/// The adapter also supplies common hooks for mutable matrices, finite-field +/// predicates, generators, representations, precision, and integer coercion. +/// Promotion and lift dispatch starts here by inspecting `RingID`; after a +/// source/target pair is selected, `RingPromoter` delegates the element-level +/// conversion to `mypromote` or `mylift` in `aring-translate.hpp`. + #ifndef M2_BASIC_RINGS_RING_GLUE_HH_ #define M2_BASIC_RINGS_RING_GLUE_HH_ diff --git a/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp b/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp index f5a1726e4ea..2915c462fb6 100644 --- a/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp @@ -1,5 +1,21 @@ // Copyright 2012 Michael E. Stillman +/// AI: +/// \file aring-m2-GF.hpp +/// \brief Defines ARingGFM2, Macaulay2's table-based Galois field ring. +/// +/// This header declares the ARing implementation for table-based Galois fields +/// GF(p^n). `GaloisFieldTable` records powers of a primitive element, integer +/// representatives, the original quotient polynomial ring, and generator data; +/// elements are table indices managed through the `SimpleARing` contract. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// extension-field operations through the methods declared here: construction +/// from the original polynomial ring, `ring_elem` conversion, arithmetic, +/// comparison, printing, generator access, discrete logarithms, and lifting +/// back to the quotient-ring representation. Specialized promotion code uses +/// these hooks to map compatible quotient-ring elements into this field. + #ifndef M2_BASIC_RINGS_ARING_GF_M2_HPP_ #define M2_BASIC_RINGS_ARING_GF_M2_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-tower.hpp b/M2/Macaulay2/e/basic-rings/aring-tower.hpp index 61bdc119502..c1aef7c8f82 100644 --- a/M2/Macaulay2/e/basic-rings/aring-tower.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-tower.hpp @@ -1,4 +1,22 @@ // Copyright 2010-2012 Michael E. Stillman. + +/// AI: +/// \file aring-tower.hpp +/// \brief Defines ARingTower, a recursive polynomial tower arithmetic ring. +/// +/// This header declares the ARing implementation for recursive polynomial +/// towers over an `ARingZZpFFPACK` base ring. Tower elements have custom +/// allocation and recursive destruction requirements, so the class derives from +/// `RingInterface` and defines ring-aware `Element` and `ElementArray` wrappers +/// instead of using `SimpleARing`. +/// +/// `aring-glue.hpp` wraps this ARing in `ConcreteRing` and forwards +/// tower operations through the methods declared here: `ring_elem` conversion, +/// element lifetime, arithmetic, comparison, printing, and evaluation through +/// `RingMap`. Factory code in `interface/aring.cpp` builds towers by extending +/// a base ARing or an existing tower, and the stored variable names determine +/// how recursive coefficients are interpreted. + #ifndef M2_BASIC_RINGS_ARING_TOWER_HPP_ #define M2_BASIC_RINGS_ARING_TOWER_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring-translate.hpp b/M2/Macaulay2/e/basic-rings/aring-translate.hpp index 718787389d1..f5df718a347 100644 --- a/M2/Macaulay2/e/basic-rings/aring-translate.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-translate.hpp @@ -1,5 +1,21 @@ // Copyright 2013 Michael E. Stillman +/// AI: +/// \file aring-translate.hpp +/// \brief Provides generic conversion helpers between ARing implementations. +/// +/// This header contains the element-level conversion layer used by +/// `aring-glue.hpp` after `ConcreteRing::promote` or `ConcreteRing::lift` +/// selects a source and target ARing pair. It detects optional `set_from_*` +/// methods at compile time so common conversions can be routed without forcing +/// every ARing to implement every possible source type. +/// +/// The `mypromote` and `mylift` overloads describe natural maps among exact +/// rings, prime fields, real rings, complex rings, and interval rings. The +/// caller unpacks source `ring_elem` values into ARing elements, these helpers +/// translate them with ARing-specific setters and membership tests, and the +/// target ARing packs successful results back into `ring_elem` storage. + #ifndef M2_BASIC_RINGS_ARING_TRANSLATE_HPP_ #define M2_BASIC_RINGS_ARING_TRANSLATE_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/aring.hpp b/M2/Macaulay2/e/basic-rings/aring.hpp index 0f7483bbbef..d7a9f86ccbe 100644 --- a/M2/Macaulay2/e/basic-rings/aring.hpp +++ b/M2/Macaulay2/e/basic-rings/aring.hpp @@ -1,5 +1,22 @@ // Copyright 2011 Michael E. Stillman +/// AI: +/// \file aring.hpp +/// \brief Defines the shared interfaces and helpers for ARing implementations. +/// +/// This header defines the shared vocabulary used by ARing implementations. +/// `RingID` is the dispatch key used by `aring-glue.hpp` for promotion, +/// lifting, finite-field detection, and specialized wrapper logic. +/// `RingInterface` marks classes that provide the method surface expected by +/// `ConcreteRing`. +/// +/// `ElementImpl` and `SimpleARing` provide the standard RAII element wrappers +/// for ARings whose raw `ElementType` can be initialized, copied, and cleared +/// without ring-owned context. More complex rings, such as FLINT extension +/// fields and towers, still implement `RingInterface` but define their own +/// nested element wrappers when destruction needs access to data stored on the +/// ring object. + #ifndef M2_BASIC_RINGS_ARING_HPP_ #define M2_BASIC_RINGS_ARING_HPP_ diff --git a/M2/Macaulay2/e/basic-rings/arings.md b/M2/Macaulay2/e/basic-rings/arings.md new file mode 100644 index 00000000000..20ee97e5bc4 --- /dev/null +++ b/M2/Macaulay2/e/basic-rings/arings.md @@ -0,0 +1,264 @@ +# ARing quick-start guide + +This guide is for contributors adding a new arithmetic ring, or ARing, under +`M2/Macaulay2/e/basic-rings`. An ARing is the low-level C++ object that knows +how to store and compute with one coefficient type. `ConcreteRing` +wraps that object and exposes it through the virtual Macaulay2 `Ring` +interface. + +The big picture is: + +```text +Macaulay2 code + -> Ring virtual methods + -> ConcreteRing + -> ARingType methods + -> raw ElementType storage, often backed by GMP, FLINT, MPFR, MPFI, or Givaro +``` + +`ConcreteRing` is the adapter for the usual ARing path. It receives a +`ring_elem` from the rest of the engine, asks the ARing to unpack it into the +ARing's `ElementType`, calls the ARing operation, and asks the ARing to pack the +result back into a `ring_elem`. Some hooks are used by factory, translation, +matrix, vector, or finite-field representation code rather than by the simple +forwarding methods, so a new ARing is best understood as a bundle of small +contracts: storage, conversion, arithmetic, presentation, and integration with +nearby coefficient rings. + +## The shortest path + +Start from an existing ARing whose storage model is close to yours. + +Use `SimpleARing` when elements can be initialized, copied, and +cleared without carrying extra context. Examples include many integer, +rational, prime-field, real, and interval rings. + +Use `RingInterface` directly when each element needs ring-owned context for +destruction or array management. Examples include FLINT extension fields and +recursive tower elements; these rings define their own nested `Element` and +`ElementArray` wrappers. + +Create `aring-your-ring.hpp` and usually `aring-your-ring.cpp`. Add a `RingID` +in `aring.hpp`, add the source/header to the build lists, add factory support in +`interface/aring.cpp` if Macaulay2 code should construct the ring directly, and +add tests before opening the PR. + +## Minimal class shape + +Most simple ARings start with this shape. Exact signatures may pass small POD +types by value instead of by const reference, but the roles are the same. + +```c++ +class ARingExample : public SimpleARing +{ + public: + static const RingID ringID = ring_example; + + typedef ExampleElement ElementType; + typedef ElementType elem; + + ARingExample(/* modulus, precision, context, etc. */); + + size_t characteristic() const; + unsigned int computeHashValue(const ElementType& a) const; + void text_out(buffer& o) const; + + void init(ElementType& result) const; + void init_set(ElementType& result, const ElementType& a) const; + void set(ElementType& result, const ElementType& a) const; + static void clear(ElementType& result); + void set_zero(ElementType& result) const; + + void to_ring_elem(ring_elem& result, const ElementType& a) const; + void from_ring_elem(ElementType& result, const ring_elem& a) const; + const ElementType& from_ring_elem_const(const ring_elem& a) const; + + void set_from_long(ElementType& result, long a) const; + void set_from_mpz(ElementType& result, mpz_srcptr a) const; + bool set_from_mpq(ElementType& result, mpq_srcptr a) const; + void set_var(ElementType& result, int v) const; + + bool is_unit(const ElementType& a) const; + bool is_zero(const ElementType& a) const; + bool is_equal(const ElementType& a, const ElementType& b) const; + int compare_elems(const ElementType& a, const ElementType& b) const; + + void negate(ElementType& result, const ElementType& a) const; + void add(ElementType& result, const ElementType& a, const ElementType& b) const; + void subtract(ElementType& result, const ElementType& a, const ElementType& b) const; + void mult(ElementType& result, const ElementType& a, const ElementType& b) const; + void divide(ElementType& result, const ElementType& a, const ElementType& b) const; + void invert(ElementType& result, const ElementType& a) const; + void power(ElementType& result, const ElementType& a, int n) const; + void power_mpz(ElementType& result, const ElementType& a, mpz_srcptr n) const; + void subtract_multiple(ElementType& result, + const ElementType& a, + const ElementType& b) const; + + void elem_text_out(buffer& o, + const ElementType& a, + bool p_one, + bool p_plus, + bool p_parens) const; + void random(ElementType& result) const; + void eval(const RingMap* map, + const ElementType& f, + int first_var, + ring_elem& result) const; +}; +``` + +## Mandatory pieces + +These are the pieces a normal `ConcreteRing` needs in order to be a +usable ring. + +Ring identity and element storage are mandatory. Provide a unique `ringID`, +the raw `ElementType`, and any constructor data needed to interpret an element: +modulus, characteristic, precision, coefficient field, FLINT context, original +polynomial ring, primitive element, lookup tables, or tower variables. + +Element lifetime is mandatory. `ConcreteRing` creates temporary ARing elements +before almost every operation. `init`, `init_set`, `set`, `set_zero`, and +`clear` must leave elements valid and must not leak memory. If `clear` needs +ring context, do not use `SimpleARing`; define custom wrappers as in the FLINT +field and tower ARings. + +`ring_elem` conversion is mandatory. The rest of the engine does not know your +raw `ElementType`. Implement `to_ring_elem`, `from_ring_elem`, and +`from_ring_elem_const` carefully, following a nearby ring with similar storage +ownership. + +Garbage-collection ownership is mandatory when a `ring_elem` stores pointers. +Temporary ARing elements are cleaned up through `clear`, but `ring_elem` values +returned to the rest of the engine may be copied freely and are not normally +freed by `ConcreteRing::remove`. If `to_ring_elem` creates heap-backed storage, +put the storage, and any GMP/MPFR/MPFI limbs reachable from it, in the engine's +GC-managed memory using the established `getmem*`, `newarray*`, or +`moveTo_gmp*` helpers. Do not pack a pointer to a temporary `ElementType` into +a `ring_elem`, and do not put the same mutable object into two independent +`ring_elem` values. + +Construction from common values is mandatory for the usual coefficient-ring +paths. Implement `set_from_long`, `set_from_mpz`, `set_from_mpq`, and +`set_var`. `set_from_mpq` should return `false` when the rational cannot be +represented, such as a denominator becoming zero in a finite field. + +Predicates and comparison are mandatory. Implement `is_zero`, `is_unit`, +`is_equal`, and `compare_elems`. The comparison only needs to be consistent for +engine use unless the ring has a mathematically meaningful canonical order. + +Core arithmetic is mandatory. At minimum, implement `negate`, `add`, +`subtract`, `mult`, `divide`, `invert`, `power`, `power_mpz`, and +`subtract_multiple`. `add` and `subtract` are not optional; many algorithms +assume they are cheap and correct. Operations that are mathematically invalid +should fail explicitly, usually by throwing an engine exception such as +`exc::division_by_zero_error`. + +Printing, random elements, and evaluation are mandatory for a fully integrated +ring. Implement `text_out` for the ring, `elem_text_out` for elements, +`random`, and `eval`. For a constant coefficient ring, `eval` is often a +conversion into the target ring. + +Hashing is mandatory. `computeHashValue` is called through `ConcreteRing` and +should be stable for equal elements. + +## Important integration work + +Build-system updates are important. Add new `.hpp` and `.cpp` files to +`M2/Macaulay2/e/CMakeLists.txt` and any active source lists used by the build. + +Factory support is important when the ring is user-visible. Add creation code +in `interface/aring.cpp` or the relevant factory path so Macaulay2 can request +the new `ConcreteRing`. + +Promotion and lifting are important when there are natural maps to or from +existing rings. `aring-glue.hpp` dispatches by `RingID`, then +`aring-translate.hpp` performs element-level `mypromote` or `mylift` work. If +generic `set_from_*` methods already cover your case, keep the wiring small; +otherwise add explicit overloads and tests for success and failure cases. + +Matrix and vector support is important for performance-sensitive coefficient +rings. Generic dense and sparse mutable matrices work through `ConcreteRing`, +but specialized dense arithmetic may require an entry in +`vector-arithmetic.hpp`. + +Tests are important, not optional. Add focused unit tests for the ARing itself +and normal Macaulay2 tests when the ring is user-visible. Cover construction, +coercion, equality, zero and unit predicates, add/subtract/multiply, division +or division failure, powers, printing, promotion/lifting, and representative +error cases. + +## Optional or specialized hooks + +Only add these when the ring actually supports the behavior or when a caller +needs the hook. + +`cardinality()` is useful for finite rings where the size is meaningful and +cheap to report. + +`ElementContainerType` is useful when vector or matrix code needs a standard +container of raw elements. + +Approximate and interval setters are useful for real and complex rings: + +```c++ +bool set_from_double(ElementType& result, double a) const; +bool set_from_BigReal(ElementType& result, gmp_RR a) const; +bool set_from_Interval(ElementType& result, gmp_RRi a) const; +bool set_from_complex_double(ElementType& result, double re, double im) const; +bool set_from_BigComplex(ElementType& result, gmp_CC a) const; +bool set_from_ComplexInterval(ElementType& result, gmp_CCi a) const; +``` + +Finite-field and extension-field hooks are specialized. Their common theme is +that they expose the chosen presentation of the field, not just its arithmetic: +how to coerce elements to small integer representatives, which generator is +distinguished, how discrete logarithms are computed, and how elements are lifted +back to the quotient polynomial ring used to construct the field. Those hooks +let `aring-glue.hpp`, factory code, and interface routines answer +questions such as "what is the generator?", "what quotient ring does this field +come from?", and "how should this field element be represented in Macaulay2?" + +The usual hooks are: + +```c++ +long coerceToLongInteger(const ElementType& a) const; +void getGenerator(ElementType& result) const; +long discreteLog(const ElementType& a) const; +const PolynomialRing& originalRing() const; +void lift_to_original_ring(ring_elem& result, const ElementType& a) const; +M2_arrayint getModPolynomialCoeffs() const; +M2_arrayint getGeneratorCoeffs() const; +M2_arrayint fieldElementToM2Array(ElementType a) const; +``` + +`syzygy` is optional algorithmic support, not part of the basic arithmetic +definition in the same way that `add` and `subtract` are. Implement it when +algorithms targeting the ring need coefficient syzygies. If the ring cannot +support it, keep the behavior explicit and covered by tests rather than letting +callers silently get nonsense. + +Precision hooks such as `get_precision()` are specialized for real, complex, +and interval rings. + +## Quick checklist + +Choose the closest existing ARing and copy its structure. + +Decide between `SimpleARing` and custom `RingInterface` wrappers. + +Define `RingID`, `ElementType`, constructor data, and lifetime management. + +Implement `ring_elem` conversion, garbage-collection ownership for pointer-backed +results, construction from ZZ/QQ, predicates, comparison, hashing, core +arithmetic, printing, random elements, and evaluation. + +Wire the ring into build files and factory code. + +Add promotion/lift dispatch only for natural maps that should exist. + +Add unit tests and user-visible Macaulay2 tests. + +Run the ARing tests and at least the relevant engine/Macaulay2 smoke tests +before sending the PR.