From 5ffc7d100bda8733c20f984ea51f85c3f8aa433c Mon Sep 17 00:00:00 2001 From: Andrew Tawfeek Date: Fri, 19 Jun 2026 10:21:13 -0700 Subject: [PATCH 1/6] Document aring headers --- M2/Macaulay2/e/basic-rings/aring-CC.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-CCC.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-CCi.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-QQ.hpp | 6 ++++++ M2/Macaulay2/e/basic-rings/aring-RR.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-RRR.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-RRi.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-ZZp.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-glue.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring-tower.hpp | 8 ++++++++ M2/Macaulay2/e/basic-rings/aring-translate.hpp | 7 +++++++ M2/Macaulay2/e/basic-rings/aring.hpp | 7 +++++++ 21 files changed, 147 insertions(+) diff --git a/M2/Macaulay2/e/basic-rings/aring-CC.hpp b/M2/Macaulay2/e/basic-rings/aring-CC.hpp index c3cc3ab8843..00cfb7ba1ae 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CC.hpp @@ -1,5 +1,12 @@ // Copyright 2012 Michael E. Stillman +/// \file aring-CC.hpp +/// \brief Defines ARingCC, the machine-precision complex arithmetic ring. +/// +/// This header implements complex numbers as pairs of doubles and supplies the +/// ARing operations, comparisons, randomization, and ring_elem conversions used +/// by the ConcreteRing wrapper. + #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..bf490bdd897 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCC.hpp @@ -1,5 +1,12 @@ // Copyright 2012 Michael E. Stillman +/// \file aring-CCC.hpp +/// \brief Defines ARingCCC, the arbitrary-precision complex arithmetic ring. +/// +/// This header represents complex numbers as pairs of MPFR real values at a +/// selected precision and provides the ARing operations and conversions needed +/// for high-precision complex 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..9476e5323dc 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCi.hpp @@ -1,5 +1,12 @@ // Copyright 2012 Michael E. Stillman +/// \file aring-CCi.hpp +/// \brief Defines ARingCCi, the arbitrary-precision complex interval ring. +/// +/// This header stores real and imaginary parts as MPFI intervals and provides +/// precision-aware arithmetic, containment predicates, and conversions for +/// complex interval elements. + #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..60707ad3413 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,12 @@ // Copyright 2014 Michael E. Stillman +/// \file aring-GF-flint-big.hpp +/// \brief Defines ARingGFFlintBig, a FLINT fq_nmod finite field ring. +/// +/// This header wraps FLINT's fq_nmod representation for finite field +/// extensions, retaining the FLINT context needed for element lifetime, +/// arithmetic, generator access, and ring_elem conversion. + #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..7369a0fafd6 100644 --- a/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp @@ -1,5 +1,12 @@ // Copyright 2014 Michael E. Stillman +/// \file aring-GF-flint.hpp +/// \brief Defines ARingGFFlint, a FLINT fq_zech finite field ring. +/// +/// This header wraps FLINT's Zech-log finite field representation, including +/// context-owning element helpers, arithmetic, discrete logarithms, and +/// conversions for extension field elements. + #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..89dbec303de 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp @@ -1,5 +1,12 @@ // Copyright 2013 Michael E. Stillman +/// \file aring-QQ-flint.hpp +/// \brief Defines ARingQQFlint, the FLINT-backed rational arithmetic ring. +/// +/// This header wraps FLINT fmpq elements and implements rational arithmetic, +/// comparison, initialization, promotion, and conversion to and from Macaulay2 +/// ring elements. + #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..5f99127db82 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp @@ -1,5 +1,12 @@ // Copyright 2013 Michael E. Stillman +/// \file aring-QQ-gmp.hpp +/// \brief Defines ARingQQGMP, the GMP-backed rational arithmetic ring. +/// +/// This header wraps GMP mpq values and implements rational arithmetic, +/// comparison, initialization, promotion, randomization, and conversion to and +/// from Macaulay2 ring elements. + #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..c0122ecae80 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ.hpp @@ -1,5 +1,11 @@ // Copyright 2013 Michael E. Stillman. +/// \file aring-QQ.hpp +/// \brief Selects the default ARing implementation for rational numbers. +/// +/// This header includes the available FLINT and GMP rational implementations +/// and aliases ARingQQ to the implementation currently used by the engine. + #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..226bdc0317d 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RR.hpp @@ -1,5 +1,12 @@ // Copyright 2012 Michael E. Stillman +/// \file aring-RR.hpp +/// \brief Defines ARingRR, the machine-precision real arithmetic ring. +/// +/// This header implements approximate real numbers as doubles and supplies the +/// ARing operations, comparisons, randomization, and ring_elem conversions used +/// by the ConcreteRing wrapper. + #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..a9741bfd368 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRR.hpp @@ -1,5 +1,12 @@ // Copyright 2012 Michael E. Stillman +/// \file aring-RRR.hpp +/// \brief Defines ARingRRR, the arbitrary-precision real arithmetic ring. +/// +/// This header wraps MPFR real values at a selected precision and provides the +/// ARing operations, comparisons, randomization, and conversions needed for +/// high-precision real rings. + #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..2c32296af53 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRi.hpp @@ -1,5 +1,12 @@ // Copyright 2012 Michael E. Stillman +/// \file aring-RRi.hpp +/// \brief Defines ARingRRi, the arbitrary-precision real interval ring. +/// +/// This header wraps MPFI intervals and provides precision-aware arithmetic, +/// containment predicates, comparisons, randomization, and conversions for real +/// interval elements. + #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..5862c0d88e5 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp @@ -1,5 +1,12 @@ // Copyright 2013 Michael E. Stillman +/// \file aring-ZZ-flint.hpp +/// \brief Defines ARingZZ, the FLINT-backed integer arithmetic ring. +/// +/// This header wraps FLINT fmpz values and implements integer arithmetic, +/// comparison, initialization, randomization, and conversion to and from +/// Macaulay2 ring elements. + #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..b1621b940cb 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp @@ -1,5 +1,12 @@ // Copyright 2013 Michael E. Stillman +/// \file aring-ZZ-gmp.hpp +/// \brief Defines ARingZZGMP, the GMP-backed integer arithmetic ring. +/// +/// This header wraps GMP mpz values and implements integer arithmetic, +/// comparison, initialization, randomization, and conversion to and from +/// Macaulay2 ring elements. + #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..01e9ccf0699 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp @@ -1,5 +1,12 @@ // Copyright 2011 Michael E. Stillman +/// \file aring-ZZp-ffpack.hpp +/// \brief Defines ARingZZpFFPACK, an FFPACK/Givaro prime finite field ring. +/// +/// This header wraps a Givaro modular field for arithmetic over ZZ/p, including +/// generator access, balanced coefficient conversion, arithmetic operations, +/// and integration with dense linear algebra code. + #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..09049168a05 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp @@ -1,5 +1,12 @@ // Copyright 2013 Michael E. Stillman +/// \file aring-ZZp-flint.hpp +/// \brief Defines ARingZZpFlint, a FLINT-backed prime finite field ring. +/// +/// This header uses FLINT nmod arithmetic for word-sized prime moduli and +/// provides modular arithmetic, generator and discrete-log support, and +/// conversion to and from Macaulay2 ring elements. + #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..2be83c77431 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp @@ -1,5 +1,12 @@ // Copyright 2011 Michael E. Stillman +/// \file aring-ZZp.hpp +/// \brief Defines ARingZZp, Macaulay2's table-based prime finite field ring. +/// +/// This header implements arithmetic over ZZ/p using exponent and logarithm +/// tables for a primitive element, along with element packaging, generator +/// access, and modular arithmetic helpers. + #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..4993408df97 100644 --- a/M2/Macaulay2/e/basic-rings/aring-glue.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-glue.hpp @@ -1,5 +1,12 @@ // Copyright 2011 Michael E. Stillman +/// \file aring-glue.hpp +/// \brief Connects ARing implementations to the high-level Ring interface. +/// +/// This header defines ConcreteRing, mutable matrix construction hooks, and +/// promotion/coercion helpers that adapt concrete ARing classes to the rest of +/// the Macaulay2 engine. + #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..cb447583aac 100644 --- a/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp @@ -1,5 +1,12 @@ // Copyright 2012 Michael E. Stillman +/// \file aring-m2-GF.hpp +/// \brief Defines ARingGFM2, Macaulay2's table-based Galois field ring. +/// +/// This header builds finite extension fields from a primitive element using +/// GaloisFieldTable lookup data and implements arithmetic, generator access, +/// discrete logarithms, and conversions for GF(p^n) elements. + #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..391f963a264 100644 --- a/M2/Macaulay2/e/basic-rings/aring-tower.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-tower.hpp @@ -1,4 +1,12 @@ // Copyright 2010-2012 Michael E. Stillman. + +/// \file aring-tower.hpp +/// \brief Defines ARingTower, a recursive polynomial tower arithmetic ring. +/// +/// This header represents tower elements as recursive polynomial structures +/// over a finite base ring and implements the RingInterface operations, +/// element lifetime helpers, evaluation, and conversion utilities for towers. + #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..b2b39e461e9 100644 --- a/M2/Macaulay2/e/basic-rings/aring-translate.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-translate.hpp @@ -1,5 +1,12 @@ // Copyright 2013 Michael E. Stillman +/// \file aring-translate.hpp +/// \brief Provides generic conversion helpers between ARing implementations. +/// +/// This header detects available source and target ring conversion operations +/// and implements the mylift and mypromote paths used to translate elements +/// among integers, rationals, finite fields, real rings, and complex rings. + #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..cf88ce07c7e 100644 --- a/M2/Macaulay2/e/basic-rings/aring.hpp +++ b/M2/Macaulay2/e/basic-rings/aring.hpp @@ -1,5 +1,12 @@ // Copyright 2011 Michael E. Stillman +/// \file aring.hpp +/// \brief Defines the shared interfaces and helpers for ARing implementations. +/// +/// This header declares RingID values, the RingInterface marker, ElementImpl, +/// and the SimpleARing template used by concrete arithmetic ring classes in +/// this directory. + #ifndef M2_BASIC_RINGS_ARING_HPP_ #define M2_BASIC_RINGS_ARING_HPP_ From 83ac1a5f6faa039491a112a1b706810aab59bcd8 Mon Sep 17 00:00:00 2001 From: Andrew Tawfeek Date: Fri, 19 Jun 2026 10:22:55 -0700 Subject: [PATCH 2/6] Add ARing implementation guide --- M2/Macaulay2/e/basic-rings/arings.md | 230 +++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 M2/Macaulay2/e/basic-rings/arings.md diff --git a/M2/Macaulay2/e/basic-rings/arings.md b/M2/Macaulay2/e/basic-rings/arings.md new file mode 100644 index 00000000000..f581e9ea139 --- /dev/null +++ b/M2/Macaulay2/e/basic-rings/arings.md @@ -0,0 +1,230 @@ +# ARing implementation guide + +An ARing is the engine-level arithmetic object used by `ConcreteRing` to +implement a Macaulay2 `Ring`. The ARing owns the representation of one element +type and provides the operations needed to create, convert, compare, print, and +compute with those elements. + +Most ARings live in an `aring-*.hpp` and matching `.cpp` file. Simple rings +inherit from `SimpleARing`, which supplies RAII element wrappers when +the ARing provides `init`, `init_set`, and `clear`. Rings whose elements need a +ring-specific context for destruction, such as FLINT finite fields, inherit from +`RingInterface` and define their own nested `Element` and `ElementArray` +wrappers. + +## Required ring data + +Every concrete ARing should provide these basic declarations and ring metadata. + +```c++ +class ARingExample : public SimpleARing +{ + public: + static const RingID ringID = ring_example; + + typedef ExampleElement ElementType; + typedef ElementType elem; + + size_t characteristic() const; + unsigned int computeHashValue(const ElementType& a) const; + void text_out(buffer& o) const; +}; +``` + +`ringID` identifies the ring implementation to dispatch code in +`aring-glue.hpp`; add a new value to `RingID` in `aring.hpp` before using one. +`ElementType` is the raw element representation. `elem` is the older local +alias used by many ARing files. + +Several rings also provide `cardinality()` and +`typedef std::vector ElementContainerType`. Add `cardinality()` when the +size of the ring is meaningful and cheap to report. Add `ElementContainerType` +when matrix or vector code needs a standard container of raw elements. + +Constructors should store all data needed to interpret an element: modulus, +precision, FLINT/GMP/Givaro context, original polynomial ring, primitive +element, tower variables, or any lookup tables. If elements depend on that +context for memory management, define custom `Element` and `ElementArray` +wrappers instead of using `SimpleARing`. + +## Element lifetime + +For a `SimpleARing`, implement the lifecycle functions for `ElementType`. + +```c++ +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; +``` + +`init` must create a valid zero-like element. `init_set` creates a new valid +element initialized from another element. `set` assigns into an already +initialized element. `clear` releases resources held by an initialized element. +For POD element types, these functions are often simple assignments and `clear` +can be a no-op. + +## Conversion to ring_elem + +`ConcreteRing` stores public ring values as `ring_elem`, so an ARing must define +how to pack and unpack its `ElementType`. + +```c++ +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; +``` + +`to_ring_elem` creates the engine-facing value. `from_ring_elem` copies or +reconstructs into an initialized `ElementType`. `from_ring_elem_const` should +return a read-only view when the stored `ring_elem` representation allows it. +If no stable reference is possible, follow the patterns of existing rings with +similar storage. + +## Constructors from common values + +The high-level `Ring` interface calls these methods when creating elements from +integers, rationals, variables, and approximate values. + +```c++ +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; +``` + +`set_from_mpq` returns `false` when the rational cannot be represented, for +example when a denominator maps to zero in a finite field. Approximate and +interval rings should also provide whichever of these conversions are natural: + +```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; +``` + +`aring-translate.hpp` detects these methods and uses them for promotion and +lifting between ARing implementations. + +## Predicates and ordering + +Implement the basic predicates and comparison used by `Ring`. + +```c++ +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; +``` + +`compare_elems` should return `-1`, `0`, or `1`. The ordering only needs to be +consistent for engine use; it does not have to be mathematically canonical +unless callers rely on that for the ring. + +## Arithmetic + +`ConcreteRing` forwards public arithmetic to methods on the ARing. The result +argument is already initialized before each call. + +```c++ +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 syzygy(const ElementType& a, const ElementType& b, ElementType& x, ElementType& y) const; +``` + +`subtract_multiple` updates `result` by subtracting `a * b`. Division and +inversion should throw the appropriate engine exception, such as +`exc::division_by_zero_error`, when the operation is invalid. + +## Output, random elements, and evaluation + +These methods connect an ARing to printing, random element generation, and ring +maps. + +```c++ +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; +``` + +`text_out` prints the ring itself, while `elem_text_out` prints an element. +`eval` is used when applying a `RingMap`; for constant rings this is often just +conversion into the target ring. + +## Optional hooks + +Some ARings support additional behavior used by finite field, approximate, or +factory code. Add these only when they are meaningful for the new ring. + +```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; +unsigned long get_precision() const; +``` + +Prime finite fields commonly provide integer coercion, generators, and +discrete logarithms. Extension fields usually keep the original quotient +polynomial ring and provide access to modulus and generator data. Real and +complex rings provide precision and approximate-value conversions. + +## Promotion and lifting + +Promotion and lifting happen in two layers. `ConcreteRing::promote` and +`ConcreteRing::lift` in `aring-glue.hpp` dispatch by `RingID`; the actual +element-level conversions are implemented in `aring-translate.hpp`. + +When adding a ring, update `aring-glue.hpp` if the new ring participates in a +new source or target pair. Update `aring-translate.hpp` with `mypromote` or +`mylift` overloads when conversion cannot be handled by the generic +`set_from_*` helpers. + +## Integration checklist + +Create the header and implementation files under `basic-rings/`. + +Add a `RingID` value in `aring.hpp`. + +Add source files and installed headers to `M2/Macaulay2/e/CMakeLists.txt` and +the matching autotools source lists if they are still in use. + +Include the new header from `aring-glue.hpp` or `aring-translate.hpp` only when +dispatch or conversion code needs the complete type. + +Add a factory entry in `interface/aring.cpp` when Macaulay2 code needs to create +the ring directly. + +Add promotion and lifting dispatch in `aring-glue.hpp` and element conversion +helpers in `aring-translate.hpp` when the ring has natural maps to or from +existing ARings. + +Check matrix and vector arithmetic support. Generic mutable matrices work +through `ConcreteRing`, but specialized dense vector arithmetic may require an +entry in `vector-arithmetic.hpp`. + +Add focused unit tests under `unit-tests/` and, when the ring is user-visible, +normal Macaulay2 tests for construction, coercion, arithmetic, printing, +promotion, and failure cases. From 481ba1b1b7e2509fc1f81ebb17516c591cb2a811 Mon Sep 17 00:00:00 2001 From: Andrew Tawfeek Date: Fri, 19 Jun 2026 10:26:14 -0700 Subject: [PATCH 3/6] Mark AI-generated aring header comments --- M2/Macaulay2/e/basic-rings/aring-CC.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-CCC.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-CCi.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-QQ.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-RR.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-RRR.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-RRi.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-ZZp.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-glue.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-tower.hpp | 1 + M2/Macaulay2/e/basic-rings/aring-translate.hpp | 1 + M2/Macaulay2/e/basic-rings/aring.hpp | 1 + 21 files changed, 21 insertions(+) diff --git a/M2/Macaulay2/e/basic-rings/aring-CC.hpp b/M2/Macaulay2/e/basic-rings/aring-CC.hpp index 00cfb7ba1ae..d968d363aa6 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CC.hpp @@ -1,5 +1,6 @@ // Copyright 2012 Michael E. Stillman +/// AI: /// \file aring-CC.hpp /// \brief Defines ARingCC, the machine-precision complex arithmetic ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-CCC.hpp b/M2/Macaulay2/e/basic-rings/aring-CCC.hpp index bf490bdd897..7440a3722cd 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCC.hpp @@ -1,5 +1,6 @@ // Copyright 2012 Michael E. Stillman +/// AI: /// \file aring-CCC.hpp /// \brief Defines ARingCCC, the arbitrary-precision complex arithmetic ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-CCi.hpp b/M2/Macaulay2/e/basic-rings/aring-CCi.hpp index 9476e5323dc..b95231ef169 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCi.hpp @@ -1,5 +1,6 @@ // Copyright 2012 Michael E. Stillman +/// AI: /// \file aring-CCi.hpp /// \brief Defines ARingCCi, the arbitrary-precision complex interval ring. /// 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 60707ad3413..dabc4ebcebc 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,6 @@ // Copyright 2014 Michael E. Stillman +/// AI: /// \file aring-GF-flint-big.hpp /// \brief Defines ARingGFFlintBig, a FLINT fq_nmod finite field ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp b/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp index 7369a0fafd6..95f1930c01b 100644 --- a/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp @@ -1,5 +1,6 @@ // Copyright 2014 Michael E. Stillman +/// AI: /// \file aring-GF-flint.hpp /// \brief Defines ARingGFFlint, a FLINT fq_zech finite field ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp b/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp index 89dbec303de..83a88764cda 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp @@ -1,5 +1,6 @@ // Copyright 2013 Michael E. Stillman +/// AI: /// \file aring-QQ-flint.hpp /// \brief Defines ARingQQFlint, the FLINT-backed rational arithmetic ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp b/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp index 5f99127db82..617f1ed3183 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp @@ -1,5 +1,6 @@ // Copyright 2013 Michael E. Stillman +/// AI: /// \file aring-QQ-gmp.hpp /// \brief Defines ARingQQGMP, the GMP-backed rational arithmetic ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-QQ.hpp b/M2/Macaulay2/e/basic-rings/aring-QQ.hpp index c0122ecae80..b665a918c0a 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ.hpp @@ -1,5 +1,6 @@ // Copyright 2013 Michael E. Stillman. +/// AI: /// \file aring-QQ.hpp /// \brief Selects the default ARing implementation for rational numbers. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-RR.hpp b/M2/Macaulay2/e/basic-rings/aring-RR.hpp index 226bdc0317d..2592222b789 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RR.hpp @@ -1,5 +1,6 @@ // Copyright 2012 Michael E. Stillman +/// AI: /// \file aring-RR.hpp /// \brief Defines ARingRR, the machine-precision real arithmetic ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-RRR.hpp b/M2/Macaulay2/e/basic-rings/aring-RRR.hpp index a9741bfd368..c4553a340f7 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRR.hpp @@ -1,5 +1,6 @@ // Copyright 2012 Michael E. Stillman +/// AI: /// \file aring-RRR.hpp /// \brief Defines ARingRRR, the arbitrary-precision real arithmetic ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-RRi.hpp b/M2/Macaulay2/e/basic-rings/aring-RRi.hpp index 2c32296af53..39e5368ace2 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRi.hpp @@ -1,5 +1,6 @@ // Copyright 2012 Michael E. Stillman +/// AI: /// \file aring-RRi.hpp /// \brief Defines ARingRRi, the arbitrary-precision real interval ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp index 5862c0d88e5..90e4a1bc1c3 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp @@ -1,5 +1,6 @@ // Copyright 2013 Michael E. Stillman +/// AI: /// \file aring-ZZ-flint.hpp /// \brief Defines ARingZZ, the FLINT-backed integer arithmetic ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp index b1621b940cb..e6f10f706fb 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp @@ -1,5 +1,6 @@ // Copyright 2013 Michael E. Stillman +/// AI: /// \file aring-ZZ-gmp.hpp /// \brief Defines ARingZZGMP, the GMP-backed integer arithmetic ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp index 01e9ccf0699..ccdf9ef92ac 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp @@ -1,5 +1,6 @@ // Copyright 2011 Michael E. Stillman +/// AI: /// \file aring-ZZp-ffpack.hpp /// \brief Defines ARingZZpFFPACK, an FFPACK/Givaro prime finite field ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp index 09049168a05..bbe27d626f1 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp @@ -1,5 +1,6 @@ // Copyright 2013 Michael E. Stillman +/// AI: /// \file aring-ZZp-flint.hpp /// \brief Defines ARingZZpFlint, a FLINT-backed prime finite field ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp b/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp index 2be83c77431..06f594a2867 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp @@ -1,5 +1,6 @@ // Copyright 2011 Michael E. Stillman +/// AI: /// \file aring-ZZp.hpp /// \brief Defines ARingZZp, Macaulay2's table-based prime finite field ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-glue.hpp b/M2/Macaulay2/e/basic-rings/aring-glue.hpp index 4993408df97..12e7d74443d 100644 --- a/M2/Macaulay2/e/basic-rings/aring-glue.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-glue.hpp @@ -1,5 +1,6 @@ // Copyright 2011 Michael E. Stillman +/// AI: /// \file aring-glue.hpp /// \brief Connects ARing implementations to the high-level Ring interface. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp b/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp index cb447583aac..c41c271e556 100644 --- a/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp @@ -1,5 +1,6 @@ // Copyright 2012 Michael E. Stillman +/// AI: /// \file aring-m2-GF.hpp /// \brief Defines ARingGFM2, Macaulay2's table-based Galois field ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-tower.hpp b/M2/Macaulay2/e/basic-rings/aring-tower.hpp index 391f963a264..32819443b49 100644 --- a/M2/Macaulay2/e/basic-rings/aring-tower.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-tower.hpp @@ -1,5 +1,6 @@ // Copyright 2010-2012 Michael E. Stillman. +/// AI: /// \file aring-tower.hpp /// \brief Defines ARingTower, a recursive polynomial tower arithmetic ring. /// diff --git a/M2/Macaulay2/e/basic-rings/aring-translate.hpp b/M2/Macaulay2/e/basic-rings/aring-translate.hpp index b2b39e461e9..91b55a23062 100644 --- a/M2/Macaulay2/e/basic-rings/aring-translate.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-translate.hpp @@ -1,5 +1,6 @@ // Copyright 2013 Michael E. Stillman +/// AI: /// \file aring-translate.hpp /// \brief Provides generic conversion helpers between ARing implementations. /// diff --git a/M2/Macaulay2/e/basic-rings/aring.hpp b/M2/Macaulay2/e/basic-rings/aring.hpp index cf88ce07c7e..4a625208b2b 100644 --- a/M2/Macaulay2/e/basic-rings/aring.hpp +++ b/M2/Macaulay2/e/basic-rings/aring.hpp @@ -1,5 +1,6 @@ // Copyright 2011 Michael E. Stillman +/// AI: /// \file aring.hpp /// \brief Defines the shared interfaces and helpers for ARing implementations. /// From b7905c121291687aac6debc7698dc0e248d6af9e Mon Sep 17 00:00:00 2001 From: Andrew Tawfeek Date: Fri, 19 Jun 2026 11:09:18 -0700 Subject: [PATCH 4/6] Expand ARing documentation guidance --- M2/Macaulay2/e/basic-rings/aring-CC.hpp | 15 +- M2/Macaulay2/e/basic-rings/aring-CCC.hpp | 14 +- M2/Macaulay2/e/basic-rings/aring-CCi.hpp | 14 +- .../e/basic-rings/aring-GF-flint-big.hpp | 17 +- M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp | 15 +- M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp | 15 +- M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp | 15 +- M2/Macaulay2/e/basic-rings/aring-QQ.hpp | 12 +- M2/Macaulay2/e/basic-rings/aring-RR.hpp | 14 +- M2/Macaulay2/e/basic-rings/aring-RRR.hpp | 13 +- M2/Macaulay2/e/basic-rings/aring-RRi.hpp | 14 +- M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp | 14 +- M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp | 13 +- .../e/basic-rings/aring-ZZp-ffpack.hpp | 14 +- .../e/basic-rings/aring-ZZp-flint.hpp | 13 +- M2/Macaulay2/e/basic-rings/aring-ZZp.hpp | 14 +- M2/Macaulay2/e/basic-rings/aring-glue.hpp | 16 +- M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp | 16 +- M2/Macaulay2/e/basic-rings/aring-tower.hpp | 15 +- .../e/basic-rings/aring-translate.hpp | 14 +- M2/Macaulay2/e/basic-rings/aring.hpp | 13 +- M2/Macaulay2/e/basic-rings/arings.md | 343 +++++++++--------- 22 files changed, 415 insertions(+), 228 deletions(-) diff --git a/M2/Macaulay2/e/basic-rings/aring-CC.hpp b/M2/Macaulay2/e/basic-rings/aring-CC.hpp index d968d363aa6..ee1faaed26f 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CC.hpp @@ -4,9 +4,18 @@ /// \file aring-CC.hpp /// \brief Defines ARingCC, the machine-precision complex arithmetic ring. /// -/// This header implements complex numbers as pairs of doubles and supplies the -/// ARing operations, comparisons, randomization, and ring_elem conversions used -/// by the ConcreteRing wrapper. +/// ARingCC is the coefficient-ring implementation for approximate complex +/// numbers stored as `cc_doubles_struct`, a pair of machine doubles. It +/// inherits from `SimpleARing`, so `ConcreteRing` obtains element +/// lifetime management from `init`, `init_set`, `set`, and `clear`. +/// +/// The methods in this class are the low-level targets for the high-level +/// `Ring` interface in `aring-glue.hpp`: `to_ring_elem` and +/// `from_ring_elem_const` move values across the `ring_elem` boundary, while +/// arithmetic, comparison, printing, and randomization methods are called +/// directly by `ConcreteRing`. The companion real ring `ARingRR` supplies the +/// real component type used by generic real-to-complex promotion paths in +/// `aring-translate.hpp`. #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 7440a3722cd..bf579a18da7 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCC.hpp @@ -4,9 +4,17 @@ /// \file aring-CCC.hpp /// \brief Defines ARingCCC, the arbitrary-precision complex arithmetic ring. /// -/// This header represents complex numbers as pairs of MPFR real values at a -/// selected precision and provides the ARing operations and conversions needed -/// for high-precision complex rings. +/// ARingCCC stores complex numbers as two MPFR values in a `cc_struct`, using +/// an `ARingRRR` member with the same precision for operations on real parts. +/// It inherits from `SimpleARing`, so the MPFR initialization and cleanup +/// routines in this class define how `ConcreteRing` manages element +/// lifetime. +/// +/// This class provides the conversion layer between MPFR-backed elements and +/// Macaulay2 `ring_elem` values, plus the arithmetic, comparison, text output, +/// and random element hooks invoked from `aring-glue.hpp`. Promotion and lift +/// code in `aring-translate.hpp` uses the high-precision real and complex +/// setters here to move values 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 b95231ef169..630c95b182b 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCi.hpp @@ -4,9 +4,17 @@ /// \file aring-CCi.hpp /// \brief Defines ARingCCi, the arbitrary-precision complex interval ring. /// -/// This header stores real and imaginary parts as MPFI intervals and provides -/// precision-aware arithmetic, containment predicates, and conversions for -/// complex interval elements. +/// ARingCCi represents a complex interval as real and imaginary MPFI intervals +/// stored in `cci_struct`. It follows the `SimpleARing` interface, so its +/// precision-aware initialization, assignment, and clearing methods are used by +/// `ConcreteRing` whenever ring elements are created or destroyed. +/// +/// The class connects interval arithmetic to the rest of the engine through +/// `ring_elem` packing/unpacking, containment predicates, arithmetic, text +/// output, and randomization. Its setters from real, complex, and interval +/// source types are part of the promotion/lift graph implemented in +/// `aring-translate.hpp`, especially for paths involving RRi, RRR, CCC, and +/// exact rational 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 dabc4ebcebc..8599857f82c 100644 --- a/M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp @@ -4,9 +4,20 @@ /// \file aring-GF-flint-big.hpp /// \brief Defines ARingGFFlintBig, a FLINT fq_nmod finite field ring. /// -/// This header wraps FLINT's fq_nmod representation for finite field -/// extensions, retaining the FLINT context needed for element lifetime, -/// arithmetic, generator access, and ring_elem conversion. +/// ARingGFFlintBig wraps FLINT's `fq_nmod` representation for finite field +/// extensions built from a quotient polynomial ring and a chosen primitive +/// element. Because each FLINT element must be initialized and cleared with +/// the field context, this class inherits from `RingInterface` directly and +/// defines context-aware `Element` and `ElementArray` wrappers instead of using +/// `SimpleARing`. +/// +/// The ARing owns the FLINT context, original polynomial ring, characteristic, +/// extension degree, and generator data needed by factory code and finite-field +/// algorithms. `ConcreteRing` calls the conversion, +/// arithmetic, comparison, evaluation, and printing methods declared here, and +/// specialized promotion/lift code uses `originalRing`, generator access, and +/// polynomial coefficient helpers to connect GF(p^n) elements with their +/// quotient-ring representation. #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 95f1930c01b..b120de35dfd 100644 --- a/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp @@ -4,9 +4,18 @@ /// \file aring-GF-flint.hpp /// \brief Defines ARingGFFlint, a FLINT fq_zech finite field ring. /// -/// This header wraps FLINT's Zech-log finite field representation, including -/// context-owning element helpers, arithmetic, discrete logarithms, and -/// conversions for extension field elements. +/// ARingGFFlint wraps FLINT's `fq_zech` Zech-log representation for finite +/// field extensions. Like the `fq_nmod` wrapper, each element depends on a +/// FLINT context for initialization and destruction, so this class derives from +/// `RingInterface` and provides its own context-carrying `Element` and +/// `ElementArray` helpers. +/// +/// This ARing is the bridge between FLINT field arithmetic and the engine's +/// `Ring` API: `ConcreteRing` delegates element conversion, +/// arithmetic, discrete logarithms, evaluation through `RingMap`, and text +/// output to the methods here. Factory and promotion code use the stored +/// quotient-ring data, primitive generator, and coefficient extraction 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 83a88764cda..c6996986bd7 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp @@ -4,9 +4,18 @@ /// \file aring-QQ-flint.hpp /// \brief Defines ARingQQFlint, the FLINT-backed rational arithmetic ring. /// -/// This header wraps FLINT fmpq elements and implements rational arithmetic, -/// comparison, initialization, promotion, and conversion to and from Macaulay2 -/// ring elements. +/// ARingQQFlint stores rational numbers as FLINT `fmpq` values. It implements +/// the `SimpleARing` contract for initialization, assignment, clearing, +/// arithmetic, comparison, hashing, and random value construction so that +/// `ConcreteRing` can expose the implementation as a Macaulay2 +/// `Ring`. +/// +/// The conversion methods in this class translate between `fmpq` and +/// `ring_elem`, preserving the ownership expectations of both FLINT and the +/// engine. Setters from GMP integers and rationals feed the generic +/// construction paths in `aring-glue.hpp`, while `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 617f1ed3183..52cb522429c 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp @@ -4,9 +4,18 @@ /// \file aring-QQ-gmp.hpp /// \brief Defines ARingQQGMP, the GMP-backed rational arithmetic ring. /// -/// This header wraps GMP mpq values and implements rational arithmetic, -/// comparison, initialization, promotion, randomization, and conversion to and -/// from Macaulay2 ring elements. +/// ARingQQGMP stores rational numbers as GMP `mpq` values and is the current +/// `ARingQQ` implementation selected by `aring-QQ.hpp`. It follows the +/// `SimpleARing` lifecycle contract, so its GMP initialization, assignment, and +/// clearing functions define how `ConcreteRing` manages rational +/// elements. +/// +/// This class provides the exact rational operations consumed by +/// `aring-glue.hpp`: construction from integers and rationals, conversion to +/// and from `ring_elem`, arithmetic, comparison, hashing, printing, and random +/// element generation. It also acts as a central source type for +/// `aring-translate.hpp`, where exact QQ values promote 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 b665a918c0a..03f109d840f 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ.hpp @@ -4,8 +4,16 @@ /// \file aring-QQ.hpp /// \brief Selects the default ARing implementation for rational numbers. /// -/// This header includes the available FLINT and GMP rational implementations -/// and aliases ARingQQ to the implementation currently used by the engine. +/// This small coordination header includes both rational ARing backends and +/// defines the `ARingQQ` typedef used throughout the rest of `basic-rings`. +/// Code that dispatches on the abstract rational ARing name, including +/// `aring-glue.hpp` and `aring-translate.hpp`, should include this header +/// rather than committing to a concrete backend directly. +/// +/// Changing the typedef changes which rational implementation is used by +/// `RingQQ::create()` and by promotion/lift code that names `ARingQQ`. Backend +/// headers still remain available for tests or factory paths that need to +/// instantiate a specific GMP or FLINT implementation explicitly. #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 2592222b789..d39f1011393 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RR.hpp @@ -4,9 +4,17 @@ /// \file aring-RR.hpp /// \brief Defines ARingRR, the machine-precision real arithmetic ring. /// -/// This header implements approximate real numbers as doubles and supplies the -/// ARing operations, comparisons, randomization, and ring_elem conversions used -/// by the ConcreteRing wrapper. +/// ARingRR is the double-precision real-number ARing. Its `ElementType` is a +/// machine `double`, so the `SimpleARing` lifecycle functions are lightweight +/// assignments while `ConcreteRing` supplies the high-level Macaulay2 +/// `Ring` interface. +/// +/// This class defines the conversion boundary between doubles and `ring_elem`, +/// along with arithmetic, comparison, hashing, text output, and random element +/// generation. It is also the real component ring for `ARingCC` and participates +/// heavily in `aring-translate.hpp`, where exact rational, high-precision real, +/// interval, and complex values promote or lift through machine-precision real +/// approximations. #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 c4553a340f7..df411a9eb29 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRR.hpp @@ -4,9 +4,16 @@ /// \file aring-RRR.hpp /// \brief Defines ARingRRR, the arbitrary-precision real arithmetic ring. /// -/// This header wraps MPFR real values at a selected precision and provides the -/// ARing operations, comparisons, randomization, and conversions needed for -/// high-precision real rings. +/// ARingRRR stores real numbers as MPFR values at a precision carried by the +/// ring object. It inherits from `SimpleARing`, so every element created by +/// `ConcreteRing` is initialized, copied, and cleared with that +/// precision through the methods in this class. +/// +/// The class supplies MPFR-backed arithmetic, comparison, hashing, printing, +/// randomization, and `ring_elem` conversion. Its `set_from_BigReal` and +/// related conversion methods form the high-precision real nodes in +/// `aring-translate.hpp`, connecting exact QQ input, machine RR input, +/// intervals, 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 39e5368ace2..35605486786 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRi.hpp @@ -4,9 +4,17 @@ /// \file aring-RRi.hpp /// \brief Defines ARingRRi, the arbitrary-precision real interval ring. /// -/// This header wraps MPFI intervals and provides precision-aware arithmetic, -/// containment predicates, comparisons, randomization, and conversions for real -/// interval elements. +/// ARingRRi represents real intervals with MPFI and stores the precision on the +/// ring object. As a `SimpleARing`, it provides the initialization, +/// assignment, and cleanup routines that `ConcreteRing` uses for +/// interval element lifetime. +/// +/// This header connects interval-specific operations to the generic `Ring` +/// interface: `ring_elem` conversion, arithmetic, comparisons, containment and +/// subset predicates, text output, and randomization. The interval setters are +/// used by `aring-translate.hpp` to promote exact rationals and real numbers +/// into interval rings and to move compatible interval data into complex +/// interval rings such as `ARingCCi`. #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 90e4a1bc1c3..f512109fd66 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp @@ -4,9 +4,17 @@ /// \file aring-ZZ-flint.hpp /// \brief Defines ARingZZ, the FLINT-backed integer arithmetic ring. /// -/// This header wraps FLINT fmpz values and implements integer arithmetic, -/// comparison, initialization, randomization, and conversion to and from -/// Macaulay2 ring elements. +/// ARingZZ stores integers as FLINT `fmpz` values and exposes them through the +/// `SimpleARing` interface. The initialization and cleanup methods here manage +/// FLINT integer storage for every element allocated through +/// `ConcreteRing`. +/// +/// The class implements the exact integer operations expected by +/// `aring-glue.hpp`: construction from C longs and GMP integers, conversion to +/// and from `ring_elem`, arithmetic, comparison, hashing, printing, and random +/// element generation. Integer ARings are the root of many promotion paths, +/// since `ConcreteRing::promote` handles ZZ-to-target construction before +/// delegating more specialized conversions to `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 e6f10f706fb..256b4f2c99e 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp @@ -4,9 +4,16 @@ /// \file aring-ZZ-gmp.hpp /// \brief Defines ARingZZGMP, the GMP-backed integer arithmetic ring. /// -/// This header wraps GMP mpz values and implements integer arithmetic, -/// comparison, initialization, randomization, and conversion to and from -/// Macaulay2 ring elements. +/// ARingZZGMP stores integers as GMP `mpz` values. It provides the +/// `SimpleARing` lifecycle operations needed by `ConcreteRing` and +/// mirrors the exact integer API used by the FLINT-backed integer ring. +/// +/// This header defines integer construction, `ring_elem` conversion, +/// arithmetic, comparison, hashing, printing, randomization, and GMP-specific +/// memory normalization. It is useful both as an alternate integer backend and +/// as a reference for how exact ARings supply the operations consumed by +/// `aring-glue.hpp` before higher-level promotion code maps integers into +/// rationals, finite fields, or approximate 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 ccdf9ef92ac..707a23558b8 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp @@ -4,9 +4,17 @@ /// \file aring-ZZp-ffpack.hpp /// \brief Defines ARingZZpFFPACK, an FFPACK/Givaro prime finite field ring. /// -/// This header wraps a Givaro modular field for arithmetic over ZZ/p, including -/// generator access, balanced coefficient conversion, arithmetic operations, -/// and integration with dense linear algebra code. +/// ARingZZpFFPACK wraps a Givaro modular field used by FFPACK/FFLAS dense +/// linear algebra routines. Its raw element type is the Givaro field element, +/// and it follows `SimpleARing` so `ConcreteRing` can delegate +/// element lifetime and arithmetic directly to the wrapped modular field. +/// +/// The class provides prime-field construction from integers and rationals, +/// balanced integer coercion, generator and discrete-log support, arithmetic, +/// comparison, text output, and `ring_elem` conversion. It is one of the +/// finite-field cases explicitly recognized in `aring-glue.hpp` for promotion, +/// lifting, finite-prime-field detection, mutable matrix creation, and +/// specialized vector arithmetic. #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 bbe27d626f1..6b5b74c4216 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp @@ -4,9 +4,16 @@ /// \file aring-ZZp-flint.hpp /// \brief Defines ARingZZpFlint, a FLINT-backed prime finite field ring. /// -/// This header uses FLINT nmod arithmetic for word-sized prime moduli and -/// provides modular arithmetic, generator and discrete-log support, and -/// conversion to and from Macaulay2 ring elements. +/// ARingZZpFlint implements prime finite fields with 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. +/// +/// `ConcreteRing` calls the methods here for modular +/// construction from ZZ/QQ, `ring_elem` conversion, arithmetic, comparison, +/// hashing, printing, randomization, and integer lifting. The ring ID is used +/// by `aring-glue.hpp` to recognize finite prime fields and by vector/matrix +/// code that selects 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 06f594a2867..43a8d35ce3f 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp @@ -4,9 +4,17 @@ /// \file aring-ZZp.hpp /// \brief Defines ARingZZp, Macaulay2's table-based prime finite field ring. /// -/// This header implements arithmetic over ZZ/p using exponent and logarithm -/// tables for a primitive element, along with element packaging, generator -/// access, and modular arithmetic helpers. +/// ARingZZp implements a prime finite field using logarithm and exponent tables +/// for a primitive element. Elements are stored as compact integers in the +/// table representation, and `SimpleARing` supplies the wrapper objects used by +/// `ConcreteRing`. +/// +/// This class defines the table-based versions of finite-field construction, +/// `ring_elem` packing, arithmetic, comparison, randomization, generator +/// access, discrete logarithms, and integer lifting. `aring-glue.hpp` treats +/// this ring as one of the finite prime field implementations and provides +/// explicit promotion/lift dispatch between it 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 12e7d74443d..bd3fd05f619 100644 --- a/M2/Macaulay2/e/basic-rings/aring-glue.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-glue.hpp @@ -4,9 +4,19 @@ /// \file aring-glue.hpp /// \brief Connects ARing implementations to the high-level Ring interface. /// -/// This header defines ConcreteRing, mutable matrix construction hooks, and -/// promotion/coercion helpers that adapt concrete ARing classes to the rest of -/// the Macaulay2 engine. +/// This header is the adapter layer between concrete ARing classes and the +/// virtual `Ring` API used throughout the engine. `ConcreteRing` +/// owns a specific ARing instance, initializes the common `Ring` constants, and +/// forwards public operations such as construction, arithmetic, comparison, +/// printing, random elements, and evaluation to methods on `RingType`. +/// +/// The template also provides the default dense/sparse mutable matrix hooks and +/// finite-field predicates used by matrix and vector code. Promotion and lift +/// dispatch is centralized here by `RingID`; once a source/target pair is +/// selected, `RingPromoter` calls the element-level `mypromote` and `mylift` +/// routines from `aring-translate.hpp`. Adding a new ARing usually requires +/// wiring its `RingID` into this dispatch table when it has natural maps to or +/// from existing rings. #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 c41c271e556..233b3d264c6 100644 --- a/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp @@ -4,9 +4,19 @@ /// \file aring-m2-GF.hpp /// \brief Defines ARingGFM2, Macaulay2's table-based Galois field ring. /// -/// This header builds finite extension fields from a primitive element using -/// GaloisFieldTable lookup data and implements arithmetic, generator access, -/// discrete logarithms, and conversions for GF(p^n) elements. +/// ARingGFM2 implements finite extension fields GF(p^n) using +/// `GaloisFieldTable`, which records powers of a primitive element, integer +/// representatives, the original quotient polynomial ring, and generator data. +/// Elements are stored as table indices, allowing `SimpleARing` to manage them +/// with simple initialization and cleanup. +/// +/// The class supplies the extension-field operations consumed by +/// `ConcreteRing`: construction from the original polynomial ring, +/// arithmetic, comparison, `ring_elem` conversion, text output, generator +/// access, discrete logarithms, and lifting back to the quotient-ring +/// representation. Specialized promotion code in `aring-glue.hpp` uses these +/// hooks to map from compatible polynomial quotient rings into the table-based +/// finite 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 32819443b49..2b6099fadcb 100644 --- a/M2/Macaulay2/e/basic-rings/aring-tower.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-tower.hpp @@ -4,9 +4,18 @@ /// \file aring-tower.hpp /// \brief Defines ARingTower, a recursive polynomial tower arithmetic ring. /// -/// This header represents tower elements as recursive polynomial structures -/// over a finite base ring and implements the RingInterface operations, -/// element lifetime helpers, evaluation, and conversion utilities for towers. +/// ARingTower represents iterated algebraic extensions as recursive polynomial +/// structures 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 +/// rather than relying on `SimpleARing`. +/// +/// The methods here provide the `ConcreteRing` surface for tower +/// creation, element lifetime, arithmetic, comparison, text output, evaluation +/// through `RingMap`, and conversion between `ring_elem` and recursive tower +/// storage. Factory code in `interface/aring.cpp` builds towers by extending a +/// base ARing or an existing tower, and the stored variable names and base ring +/// determine how the 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 91b55a23062..b24330e0cd3 100644 --- a/M2/Macaulay2/e/basic-rings/aring-translate.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-translate.hpp @@ -4,9 +4,17 @@ /// \file aring-translate.hpp /// \brief Provides generic conversion helpers between ARing implementations. /// -/// This header detects available source and target ring conversion operations -/// and implements the mylift and mypromote paths used to translate elements -/// among integers, rationals, finite fields, real rings, and complex rings. +/// This header contains the element-level conversion layer used after +/// `ConcreteRing::promote` or `ConcreteRing::lift` has selected a source and +/// target ARing pair. It uses compile-time detection of optional +/// `set_from_*` methods to route common conversions without forcing every ARing +/// to implement every possible source type. +/// +/// The `mypromote` and `mylift` overloads here describe the actual natural maps +/// among exact rings, prime fields, real rings, complex rings, and interval +/// rings. Source elements are unpacked from `ring_elem` in `aring-glue.hpp`, +/// translated here using ARing-specific setters and membership tests, and then +/// packed back into the target ring with `to_ring_elem`. #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 4a625208b2b..a51c0686133 100644 --- a/M2/Macaulay2/e/basic-rings/aring.hpp +++ b/M2/Macaulay2/e/basic-rings/aring.hpp @@ -4,9 +4,16 @@ /// \file aring.hpp /// \brief Defines the shared interfaces and helpers for ARing implementations. /// -/// This header declares RingID values, the RingInterface marker, ElementImpl, -/// and the SimpleARing template used by concrete arithmetic ring classes in -/// this directory. +/// This header defines the minimal vocabulary shared by all concrete ARing +/// classes. `RingID` is the dispatch key used by `aring-glue.hpp` for +/// promotion, lifting, finite-field detection, and specialized wrapper logic. +/// `RingInterface` marks classes that can be wrapped by `ConcreteRing`. +/// +/// `ElementImpl` and `SimpleARing` provide the standard RAII element wrappers +/// for ARings whose raw `ElementType` can be initialized, copied, and cleared +/// without additional context. More complex rings, such as FLINT extension +/// fields and towers, still use `RingInterface` but define their own nested +/// element wrappers when destruction requires access to ring-owned data. #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 index f581e9ea139..47e3e8365ae 100644 --- a/M2/Macaulay2/e/basic-rings/arings.md +++ b/M2/Macaulay2/e/basic-rings/arings.md @@ -1,20 +1,49 @@ -# ARing implementation guide +# 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. 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`. +That means a new ARing must define both the mathematical operations and the +conversion boundary between `ring_elem` and its own element representation. + +## 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. -An ARing is the engine-level arithmetic object used by `ConcreteRing` to -implement a Macaulay2 `Ring`. The ARing owns the representation of one element -type and provides the operations needed to create, convert, compare, print, and -compute with those elements. +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. -Most ARings live in an `aring-*.hpp` and matching `.cpp` file. Simple rings -inherit from `SimpleARing`, which supplies RAII element wrappers when -the ARing provides `init`, `init_set`, and `clear`. Rings whose elements need a -ring-specific context for destruction, such as FLINT finite fields, inherit from -`RingInterface` and 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. -## Required ring data +## Minimal class shape -Every concrete ARing should provide these basic declarations and ring metadata. +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 @@ -25,78 +54,140 @@ class ARingExample : public SimpleARing 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; }; ``` -`ringID` identifies the ring implementation to dispatch code in -`aring-glue.hpp`; add a new value to `RingID` in `aring.hpp` before using one. -`ElementType` is the raw element representation. `elem` is the older local -alias used by many ARing files. - -Several rings also provide `cardinality()` and -`typedef std::vector ElementContainerType`. Add `cardinality()` when the -size of the ring is meaningful and cheap to report. Add `ElementContainerType` -when matrix or vector code needs a standard container of raw elements. - -Constructors should store all data needed to interpret an element: modulus, -precision, FLINT/GMP/Givaro context, original polynomial ring, primitive -element, tower variables, or any lookup tables. If elements depend on that -context for memory management, define custom `Element` and `ElementArray` -wrappers instead of using `SimpleARing`. +## 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. + +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. -## Element lifetime +Hashing is mandatory. `computeHashValue` is called through `ConcreteRing` and +should be stable for equal elements. -For a `SimpleARing`, implement the lifecycle functions for `ElementType`. +## Important integration work -```c++ -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; -``` +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. -`init` must create a valid zero-like element. `init_set` creates a new valid -element initialized from another element. `set` assigns into an already -initialized element. `clear` releases resources held by an initialized element. -For POD element types, these functions are often simple assignments and `clear` -can be a no-op. +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`. -## Conversion to ring_elem +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. -`ConcreteRing` stores public ring values as `ring_elem`, so an ARing must define -how to pack and unpack its `ElementType`. +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`. -```c++ -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; -``` +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. -`to_ring_elem` creates the engine-facing value. `from_ring_elem` copies or -reconstructs into an initialized `ElementType`. `from_ring_elem_const` should -return a read-only view when the stored `ring_elem` representation allows it. -If no stable reference is possible, follow the patterns of existing rings with -similar storage. +## Optional or specialized hooks -## Constructors from common values +Only add these when the ring actually supports the behavior or when a caller +needs the hook. -The high-level `Ring` interface calls these methods when creating elements from -integers, rationals, variables, and approximate values. +`cardinality()` is useful for finite rings where the size is meaningful and +cheap to report. -```c++ -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; -``` +`ElementContainerType` is useful when vector or matrix code needs a standard +container of raw elements. -`set_from_mpq` returns `false` when the rational cannot be represented, for -example when a denominator maps to zero in a finite field. Approximate and -interval rings should also provide whichever of these conversions are natural: +Approximate and interval setters are useful for real and complex rings: ```c++ bool set_from_double(ElementType& result, double a) const; @@ -107,72 +198,7 @@ bool set_from_BigComplex(ElementType& result, gmp_CC a) const; bool set_from_ComplexInterval(ElementType& result, gmp_CCi a) const; ``` -`aring-translate.hpp` detects these methods and uses them for promotion and -lifting between ARing implementations. - -## Predicates and ordering - -Implement the basic predicates and comparison used by `Ring`. - -```c++ -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; -``` - -`compare_elems` should return `-1`, `0`, or `1`. The ordering only needs to be -consistent for engine use; it does not have to be mathematically canonical -unless callers rely on that for the ring. - -## Arithmetic - -`ConcreteRing` forwards public arithmetic to methods on the ARing. The result -argument is already initialized before each call. - -```c++ -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 syzygy(const ElementType& a, const ElementType& b, ElementType& x, ElementType& y) const; -``` - -`subtract_multiple` updates `result` by subtracting `a * b`. Division and -inversion should throw the appropriate engine exception, such as -`exc::division_by_zero_error`, when the operation is invalid. - -## Output, random elements, and evaluation - -These methods connect an ARing to printing, random element generation, and ring -maps. - -```c++ -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; -``` - -`text_out` prints the ring itself, while `elem_text_out` prints an element. -`eval` is used when applying a `RingMap`; for constant rings this is often just -conversion into the target ring. - -## Optional hooks - -Some ARings support additional behavior used by finite field, approximate, or -factory code. Add these only when they are meaningful for the new ring. +Finite-field and extension-field hooks are specialized: ```c++ long coerceToLongInteger(const ElementType& a) const; @@ -183,48 +209,33 @@ 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; -unsigned long get_precision() const; ``` -Prime finite fields commonly provide integer coercion, generators, and -discrete logarithms. Extension fields usually keep the original quotient -polynomial ring and provide access to modulus and generator data. Real and -complex rings provide precision and approximate-value conversions. - -## Promotion and lifting - -Promotion and lifting happen in two layers. `ConcreteRing::promote` and -`ConcreteRing::lift` in `aring-glue.hpp` dispatch by `RingID`; the actual -element-level conversions are implemented in `aring-translate.hpp`. +`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. -When adding a ring, update `aring-glue.hpp` if the new ring participates in a -new source or target pair. Update `aring-translate.hpp` with `mypromote` or -`mylift` overloads when conversion cannot be handled by the generic -`set_from_*` helpers. +Precision hooks such as `get_precision()` are specialized for real, complex, +and interval rings. -## Integration checklist +## Quick checklist -Create the header and implementation files under `basic-rings/`. +Choose the closest existing ARing and copy its structure. -Add a `RingID` value in `aring.hpp`. +Decide between `SimpleARing` and custom `RingInterface` wrappers. -Add source files and installed headers to `M2/Macaulay2/e/CMakeLists.txt` and -the matching autotools source lists if they are still in use. +Define `RingID`, `ElementType`, constructor data, and lifetime management. -Include the new header from `aring-glue.hpp` or `aring-translate.hpp` only when -dispatch or conversion code needs the complete type. +Implement `ring_elem` conversion, construction from ZZ/QQ, predicates, +comparison, hashing, core arithmetic, printing, random elements, and evaluation. -Add a factory entry in `interface/aring.cpp` when Macaulay2 code needs to create -the ring directly. +Wire the ring into build files and factory code. -Add promotion and lifting dispatch in `aring-glue.hpp` and element conversion -helpers in `aring-translate.hpp` when the ring has natural maps to or from -existing ARings. +Add promotion/lift dispatch only for natural maps that should exist. -Check matrix and vector arithmetic support. Generic mutable matrices work -through `ConcreteRing`, but specialized dense vector arithmetic may require an -entry in `vector-arithmetic.hpp`. +Add unit tests and user-visible Macaulay2 tests. -Add focused unit tests under `unit-tests/` and, when the ring is user-visible, -normal Macaulay2 tests for construction, coercion, arithmetic, printing, -promotion, and failure cases. +Run the ARing tests and at least the relevant engine/Macaulay2 smoke tests +before sending the PR. From 98345765fc488095af1aa6e5fb8f693d2bf11833 Mon Sep 17 00:00:00 2001 From: Andrew Tawfeek Date: Fri, 26 Jun 2026 10:23:13 -0700 Subject: [PATCH 5/6] Refine ARing documentation comments --- M2/Macaulay2/e/basic-rings/aring-CC.hpp | 21 ++++++++-------- M2/Macaulay2/e/basic-rings/aring-CCC.hpp | 20 ++++++++-------- M2/Macaulay2/e/basic-rings/aring-CCi.hpp | 21 ++++++++-------- .../e/basic-rings/aring-GF-flint-big.hpp | 24 +++++++++---------- M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp | 23 +++++++++--------- M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp | 21 ++++++++-------- M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp | 19 +++++++-------- M2/Macaulay2/e/basic-rings/aring-QQ.hpp | 18 +++++++------- M2/Macaulay2/e/basic-rings/aring-RR.hpp | 20 ++++++++-------- M2/Macaulay2/e/basic-rings/aring-RRR.hpp | 19 ++++++++------- M2/Macaulay2/e/basic-rings/aring-RRi.hpp | 20 ++++++++-------- M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp | 20 ++++++++-------- M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp | 20 +++++++++------- .../e/basic-rings/aring-ZZp-ffpack.hpp | 20 ++++++++-------- .../e/basic-rings/aring-ZZp-flint.hpp | 18 +++++++------- M2/Macaulay2/e/basic-rings/aring-ZZp.hpp | 20 ++++++++-------- M2/Macaulay2/e/basic-rings/aring-glue.hpp | 22 ++++++++--------- M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp | 22 ++++++++--------- M2/Macaulay2/e/basic-rings/aring-tower.hpp | 18 +++++++------- .../e/basic-rings/aring-translate.hpp | 20 ++++++++-------- M2/Macaulay2/e/basic-rings/aring.hpp | 16 +++++++------ M2/Macaulay2/e/basic-rings/arings.md | 24 ++++++++++++++----- 22 files changed, 229 insertions(+), 217 deletions(-) diff --git a/M2/Macaulay2/e/basic-rings/aring-CC.hpp b/M2/Macaulay2/e/basic-rings/aring-CC.hpp index ee1faaed26f..bdb8e7b74c8 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CC.hpp @@ -4,18 +4,17 @@ /// \file aring-CC.hpp /// \brief Defines ARingCC, the machine-precision complex arithmetic ring. /// -/// ARingCC is the coefficient-ring implementation for approximate complex -/// numbers stored as `cc_doubles_struct`, a pair of machine doubles. It -/// inherits from `SimpleARing`, so `ConcreteRing` obtains element -/// lifetime management from `init`, `init_set`, `set`, and `clear`. +/// 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. /// -/// The methods in this class are the low-level targets for the high-level -/// `Ring` interface in `aring-glue.hpp`: `to_ring_elem` and -/// `from_ring_elem_const` move values across the `ring_elem` boundary, while -/// arithmetic, comparison, printing, and randomization methods are called -/// directly by `ConcreteRing`. The companion real ring `ARingRR` supplies the -/// real component type used by generic real-to-complex promotion paths in -/// `aring-translate.hpp`. +/// `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 bf579a18da7..a0e80aa7fb6 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCC.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCC.hpp @@ -4,17 +4,17 @@ /// \file aring-CCC.hpp /// \brief Defines ARingCCC, the arbitrary-precision complex arithmetic ring. /// -/// ARingCCC stores complex numbers as two MPFR values in a `cc_struct`, using -/// an `ARingRRR` member with the same precision for operations on real parts. -/// It inherits from `SimpleARing`, so the MPFR initialization and cleanup -/// routines in this class define how `ConcreteRing` manages element -/// lifetime. +/// 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. /// -/// This class provides the conversion layer between MPFR-backed elements and -/// Macaulay2 `ring_elem` values, plus the arithmetic, comparison, text output, -/// and random element hooks invoked from `aring-glue.hpp`. Promotion and lift -/// code in `aring-translate.hpp` uses the high-precision real and complex -/// setters here to move values among QQ, RR/RRR, CC/CCC, and interval rings. +/// `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 630c95b182b..3ed664de4ca 100644 --- a/M2/Macaulay2/e/basic-rings/aring-CCi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-CCi.hpp @@ -4,17 +4,18 @@ /// \file aring-CCi.hpp /// \brief Defines ARingCCi, the arbitrary-precision complex interval ring. /// -/// ARingCCi represents a complex interval as real and imaginary MPFI intervals -/// stored in `cci_struct`. It follows the `SimpleARing` interface, so its -/// precision-aware initialization, assignment, and clearing methods are used by -/// `ConcreteRing` whenever ring elements are created or destroyed. +/// 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. /// -/// The class connects interval arithmetic to the rest of the engine through -/// `ring_elem` packing/unpacking, containment predicates, arithmetic, text -/// output, and randomization. Its setters from real, complex, and interval -/// source types are part of the promotion/lift graph implemented in -/// `aring-translate.hpp`, especially for paths involving RRi, RRR, CCC, and -/// exact rational input. +/// `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 8599857f82c..72809c5b87f 100644 --- a/M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp @@ -4,20 +4,18 @@ /// \file aring-GF-flint-big.hpp /// \brief Defines ARingGFFlintBig, a FLINT fq_nmod finite field ring. /// -/// ARingGFFlintBig wraps FLINT's `fq_nmod` representation for finite field -/// extensions built from a quotient polynomial ring and a chosen primitive -/// element. Because each FLINT element must be initialized and cleared with -/// the field context, this class inherits from `RingInterface` directly and -/// defines context-aware `Element` and `ElementArray` wrappers instead of using -/// `SimpleARing`. +/// 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`. /// -/// The ARing owns the FLINT context, original polynomial ring, characteristic, -/// extension degree, and generator data needed by factory code and finite-field -/// algorithms. `ConcreteRing` calls the conversion, -/// arithmetic, comparison, evaluation, and printing methods declared here, and -/// specialized promotion/lift code uses `originalRing`, generator access, and -/// polynomial coefficient helpers to connect GF(p^n) elements with their -/// quotient-ring representation. +/// `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 b120de35dfd..a03ab0f22e6 100644 --- a/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp @@ -4,18 +4,19 @@ /// \file aring-GF-flint.hpp /// \brief Defines ARingGFFlint, a FLINT fq_zech finite field ring. /// -/// ARingGFFlint wraps FLINT's `fq_zech` Zech-log representation for finite -/// field extensions. Like the `fq_nmod` wrapper, each element depends on a -/// FLINT context for initialization and destruction, so this class derives from -/// `RingInterface` and provides its own context-carrying `Element` and -/// `ElementArray` helpers. +/// 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`. /// -/// This ARing is the bridge between FLINT field arithmetic and the engine's -/// `Ring` API: `ConcreteRing` delegates element conversion, -/// arithmetic, discrete logarithms, evaluation through `RingMap`, and text -/// output to the methods here. Factory and promotion code use the stored -/// quotient-ring data, primitive generator, and coefficient extraction helpers -/// to relate Zech elements back to polynomial representatives. +/// `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 c6996986bd7..68c89c859ec 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp @@ -4,18 +4,17 @@ /// \file aring-QQ-flint.hpp /// \brief Defines ARingQQFlint, the FLINT-backed rational arithmetic ring. /// -/// ARingQQFlint stores rational numbers as FLINT `fmpq` values. It implements -/// the `SimpleARing` contract for initialization, assignment, clearing, -/// arithmetic, comparison, hashing, and random value construction so that -/// `ConcreteRing` can expose the implementation as a Macaulay2 -/// `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. /// -/// The conversion methods in this class translate between `fmpq` and -/// `ring_elem`, preserving the ownership expectations of both FLINT and the -/// engine. Setters from GMP integers and rationals feed the generic -/// construction paths in `aring-glue.hpp`, while `aring-translate.hpp` uses the -/// rational representation as a source for approximate real, interval, and -/// complex promotion. +/// `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 52cb522429c..5ea21e6eefd 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp @@ -4,17 +4,16 @@ /// \file aring-QQ-gmp.hpp /// \brief Defines ARingQQGMP, the GMP-backed rational arithmetic ring. /// -/// ARingQQGMP stores rational numbers as GMP `mpq` values and is the current -/// `ARingQQ` implementation selected by `aring-QQ.hpp`. It follows the -/// `SimpleARing` lifecycle contract, so its GMP initialization, assignment, and -/// clearing functions define how `ConcreteRing` manages rational -/// elements. +/// 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. /// -/// This class provides the exact rational operations consumed by -/// `aring-glue.hpp`: construction from integers and rationals, conversion to -/// and from `ring_elem`, arithmetic, comparison, hashing, printing, and random -/// element generation. It also acts as a central source type for -/// `aring-translate.hpp`, where exact QQ values promote into real, complex, and +/// `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_ diff --git a/M2/Macaulay2/e/basic-rings/aring-QQ.hpp b/M2/Macaulay2/e/basic-rings/aring-QQ.hpp index 03f109d840f..677e193090c 100644 --- a/M2/Macaulay2/e/basic-rings/aring-QQ.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-QQ.hpp @@ -4,16 +4,16 @@ /// \file aring-QQ.hpp /// \brief Selects the default ARing implementation for rational numbers. /// -/// This small coordination header includes both rational ARing backends and -/// defines the `ARingQQ` typedef used throughout the rest of `basic-rings`. -/// Code that dispatches on the abstract rational ARing name, including -/// `aring-glue.hpp` and `aring-translate.hpp`, should include this header -/// rather than committing to a concrete backend directly. +/// 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. /// -/// Changing the typedef changes which rational implementation is used by -/// `RingQQ::create()` and by promotion/lift code that names `ARingQQ`. Backend -/// headers still remain available for tests or factory paths that need to -/// instantiate a specific GMP or FLINT implementation explicitly. +/// `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 d39f1011393..ef0386cdaaa 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RR.hpp @@ -4,17 +4,17 @@ /// \file aring-RR.hpp /// \brief Defines ARingRR, the machine-precision real arithmetic ring. /// -/// ARingRR is the double-precision real-number ARing. Its `ElementType` is a -/// machine `double`, so the `SimpleARing` lifecycle functions are lightweight -/// assignments while `ConcreteRing` supplies the high-level Macaulay2 -/// `Ring` interface. +/// 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. /// -/// This class defines the conversion boundary between doubles and `ring_elem`, -/// along with arithmetic, comparison, hashing, text output, and random element -/// generation. It is also the real component ring for `ARingCC` and participates -/// heavily in `aring-translate.hpp`, where exact rational, high-precision real, -/// interval, and complex values promote or lift through machine-precision real -/// approximations. +/// `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 df411a9eb29..4d64f86c457 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRR.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRR.hpp @@ -4,16 +4,17 @@ /// \file aring-RRR.hpp /// \brief Defines ARingRRR, the arbitrary-precision real arithmetic ring. /// -/// ARingRRR stores real numbers as MPFR values at a precision carried by the -/// ring object. It inherits from `SimpleARing`, so every element created by -/// `ConcreteRing` is initialized, copied, and cleared with that -/// precision through the methods in this class. +/// 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. /// -/// The class supplies MPFR-backed arithmetic, comparison, hashing, printing, -/// randomization, and `ring_elem` conversion. Its `set_from_BigReal` and -/// related conversion methods form the high-precision real nodes in -/// `aring-translate.hpp`, connecting exact QQ input, machine RR input, -/// intervals, and complex rings that use `ARingRRR` as their real component. +/// `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 35605486786..6e9b77d0059 100644 --- a/M2/Macaulay2/e/basic-rings/aring-RRi.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-RRi.hpp @@ -4,17 +4,17 @@ /// \file aring-RRi.hpp /// \brief Defines ARingRRi, the arbitrary-precision real interval ring. /// -/// ARingRRi represents real intervals with MPFI and stores the precision on the -/// ring object. As a `SimpleARing`, it provides the initialization, -/// assignment, and cleanup routines that `ConcreteRing` uses for -/// interval element lifetime. +/// 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. /// -/// This header connects interval-specific operations to the generic `Ring` -/// interface: `ring_elem` conversion, arithmetic, comparisons, containment and -/// subset predicates, text output, and randomization. The interval setters are -/// used by `aring-translate.hpp` to promote exact rationals and real numbers -/// into interval rings and to move compatible interval data into complex -/// interval rings such as `ARingCCi`. +/// `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 f512109fd66..f085a802aa5 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp @@ -4,17 +4,17 @@ /// \file aring-ZZ-flint.hpp /// \brief Defines ARingZZ, the FLINT-backed integer arithmetic ring. /// -/// ARingZZ stores integers as FLINT `fmpz` values and exposes them through the -/// `SimpleARing` interface. The initialization and cleanup methods here manage -/// FLINT integer storage for every element allocated through -/// `ConcreteRing`. +/// 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. /// -/// The class implements the exact integer operations expected by -/// `aring-glue.hpp`: construction from C longs and GMP integers, conversion to -/// and from `ring_elem`, arithmetic, comparison, hashing, printing, and random -/// element generation. Integer ARings are the root of many promotion paths, -/// since `ConcreteRing::promote` handles ZZ-to-target construction before -/// delegating more specialized conversions to `aring-translate.hpp`. +/// `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 256b4f2c99e..2eed71dc754 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp @@ -4,16 +4,18 @@ /// \file aring-ZZ-gmp.hpp /// \brief Defines ARingZZGMP, the GMP-backed integer arithmetic ring. /// -/// ARingZZGMP stores integers as GMP `mpz` values. It provides the -/// `SimpleARing` lifecycle operations needed by `ConcreteRing` and -/// mirrors the exact integer API used by the FLINT-backed integer 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. /// -/// This header defines integer construction, `ring_elem` conversion, -/// arithmetic, comparison, hashing, printing, randomization, and GMP-specific -/// memory normalization. It is useful both as an alternate integer backend and -/// as a reference for how exact ARings supply the operations consumed by -/// `aring-glue.hpp` before higher-level promotion code maps integers into -/// rationals, finite fields, or approximate rings. +/// `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 707a23558b8..f06c1442982 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp @@ -4,17 +4,17 @@ /// \file aring-ZZp-ffpack.hpp /// \brief Defines ARingZZpFFPACK, an FFPACK/Givaro prime finite field ring. /// -/// ARingZZpFFPACK wraps a Givaro modular field used by FFPACK/FFLAS dense -/// linear algebra routines. Its raw element type is the Givaro field element, -/// and it follows `SimpleARing` so `ConcreteRing` can delegate -/// element lifetime and arithmetic directly to the wrapped modular field. +/// 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. /// -/// The class provides prime-field construction from integers and rationals, -/// balanced integer coercion, generator and discrete-log support, arithmetic, -/// comparison, text output, and `ring_elem` conversion. It is one of the -/// finite-field cases explicitly recognized in `aring-glue.hpp` for promotion, -/// lifting, finite-prime-field detection, mutable matrix creation, and -/// specialized vector arithmetic. +/// `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 6b5b74c4216..0f68bebdebb 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp @@ -4,16 +4,18 @@ /// \file aring-ZZp-flint.hpp /// \brief Defines ARingZZpFlint, a FLINT-backed prime finite field ring. /// -/// ARingZZpFlint implements prime finite fields with 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. +/// 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. /// -/// `ConcreteRing` calls the methods here for modular +/// `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, and integer lifting. The ring ID is used -/// by `aring-glue.hpp` to recognize finite prime fields and by vector/matrix -/// code that selects FLINT-backed dense arithmetic paths. +/// 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 43a8d35ce3f..1c4081546e5 100644 --- a/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-ZZp.hpp @@ -4,17 +4,17 @@ /// \file aring-ZZp.hpp /// \brief Defines ARingZZp, Macaulay2's table-based prime finite field ring. /// -/// ARingZZp implements a prime finite field using logarithm and exponent tables -/// for a primitive element. Elements are stored as compact integers in the -/// table representation, and `SimpleARing` supplies the wrapper objects used by -/// `ConcreteRing`. +/// 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. /// -/// This class defines the table-based versions of finite-field construction, -/// `ring_elem` packing, arithmetic, comparison, randomization, generator -/// access, discrete logarithms, and integer lifting. `aring-glue.hpp` treats -/// this ring as one of the finite prime field implementations and provides -/// explicit promotion/lift dispatch between it and the FFPACK-backed prime -/// field when their characteristics are compatible. +/// `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 bd3fd05f619..e988c97bdb0 100644 --- a/M2/Macaulay2/e/basic-rings/aring-glue.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-glue.hpp @@ -4,19 +4,17 @@ /// \file aring-glue.hpp /// \brief Connects ARing implementations to the high-level Ring interface. /// -/// This header is the adapter layer between concrete ARing classes and the -/// virtual `Ring` API used throughout the engine. `ConcreteRing` -/// owns a specific ARing instance, initializes the common `Ring` constants, and -/// forwards public operations such as construction, arithmetic, comparison, -/// printing, random elements, and evaluation to methods on `RingType`. +/// 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 template also provides the default dense/sparse mutable matrix hooks and -/// finite-field predicates used by matrix and vector code. Promotion and lift -/// dispatch is centralized here by `RingID`; once a source/target pair is -/// selected, `RingPromoter` calls the element-level `mypromote` and `mylift` -/// routines from `aring-translate.hpp`. Adding a new ARing usually requires -/// wiring its `RingID` into this dispatch table when it has natural maps to or -/// from existing rings. +/// 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 233b3d264c6..2915c462fb6 100644 --- a/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-m2-GF.hpp @@ -4,19 +4,17 @@ /// \file aring-m2-GF.hpp /// \brief Defines ARingGFM2, Macaulay2's table-based Galois field ring. /// -/// ARingGFM2 implements finite extension fields GF(p^n) using -/// `GaloisFieldTable`, which records powers of a primitive element, integer -/// representatives, the original quotient polynomial ring, and generator data. -/// Elements are stored as table indices, allowing `SimpleARing` to manage them -/// with simple initialization and cleanup. +/// 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. /// -/// The class supplies the extension-field operations consumed by -/// `ConcreteRing`: construction from the original polynomial ring, -/// arithmetic, comparison, `ring_elem` conversion, text output, generator -/// access, discrete logarithms, and lifting back to the quotient-ring -/// representation. Specialized promotion code in `aring-glue.hpp` uses these -/// hooks to map from compatible polynomial quotient rings into the table-based -/// finite field. +/// `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 2b6099fadcb..c1aef7c8f82 100644 --- a/M2/Macaulay2/e/basic-rings/aring-tower.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-tower.hpp @@ -4,18 +4,18 @@ /// \file aring-tower.hpp /// \brief Defines ARingTower, a recursive polynomial tower arithmetic ring. /// -/// ARingTower represents iterated algebraic extensions as recursive polynomial -/// structures over an `ARingZZpFFPACK` base ring. Tower elements have custom +/// 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 -/// rather than relying on `SimpleARing`. +/// instead of using `SimpleARing`. /// -/// The methods here provide the `ConcreteRing` surface for tower -/// creation, element lifetime, arithmetic, comparison, text output, evaluation -/// through `RingMap`, and conversion between `ring_elem` and recursive tower -/// storage. Factory code in `interface/aring.cpp` builds towers by extending a -/// base ARing or an existing tower, and the stored variable names and base ring -/// determine how the recursive coefficients are interpreted. +/// `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 b24330e0cd3..f5df718a347 100644 --- a/M2/Macaulay2/e/basic-rings/aring-translate.hpp +++ b/M2/Macaulay2/e/basic-rings/aring-translate.hpp @@ -4,17 +4,17 @@ /// \file aring-translate.hpp /// \brief Provides generic conversion helpers between ARing implementations. /// -/// This header contains the element-level conversion layer used after -/// `ConcreteRing::promote` or `ConcreteRing::lift` has selected a source and -/// target ARing pair. It uses compile-time detection of optional -/// `set_from_*` methods to route common conversions without forcing every ARing -/// to implement every possible source type. +/// 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 here describe the actual natural maps -/// among exact rings, prime fields, real rings, complex rings, and interval -/// rings. Source elements are unpacked from `ring_elem` in `aring-glue.hpp`, -/// translated here using ARing-specific setters and membership tests, and then -/// packed back into the target ring with `to_ring_elem`. +/// 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 a51c0686133..d7a9f86ccbe 100644 --- a/M2/Macaulay2/e/basic-rings/aring.hpp +++ b/M2/Macaulay2/e/basic-rings/aring.hpp @@ -4,16 +4,18 @@ /// \file aring.hpp /// \brief Defines the shared interfaces and helpers for ARing implementations. /// -/// This header defines the minimal vocabulary shared by all concrete ARing -/// classes. `RingID` is the dispatch key used by `aring-glue.hpp` for -/// promotion, lifting, finite-field detection, and specialized wrapper logic. -/// `RingInterface` marks classes that can be wrapped by `ConcreteRing`. +/// 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 additional context. More complex rings, such as FLINT extension -/// fields and towers, still use `RingInterface` but define their own nested -/// element wrappers when destruction requires access to ring-owned data. +/// 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 index 47e3e8365ae..a5f58f908ff 100644 --- a/M2/Macaulay2/e/basic-rings/arings.md +++ b/M2/Macaulay2/e/basic-rings/arings.md @@ -16,11 +16,14 @@ Macaulay2 code -> raw ElementType storage, often backed by GMP, FLINT, MPFR, MPFI, or Givaro ``` -`ConcreteRing` is the adapter. 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`. -That means a new ARing must define both the mathematical operations and the -conversion boundary between `ring_elem` and its own element representation. +`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 @@ -198,7 +201,16 @@ 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: +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; From 7734999870c347c309c3918e4429a703ae51db8e Mon Sep 17 00:00:00 2001 From: Andrew Tawfeek Date: Fri, 26 Jun 2026 10:57:59 -0700 Subject: [PATCH 6/6] Document ARing GC ownership --- M2/Macaulay2/e/basic-rings/arings.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/M2/Macaulay2/e/basic-rings/arings.md b/M2/Macaulay2/e/basic-rings/arings.md index a5f58f908ff..20ee97e5bc4 100644 --- a/M2/Macaulay2/e/basic-rings/arings.md +++ b/M2/Macaulay2/e/basic-rings/arings.md @@ -129,6 +129,16 @@ 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 @@ -240,8 +250,9 @@ Decide between `SimpleARing` and custom `RingInterface` wrappers. Define `RingID`, `ElementType`, constructor data, and lifetime management. -Implement `ring_elem` conversion, construction from ZZ/QQ, predicates, -comparison, hashing, core arithmetic, printing, random elements, and evaluation. +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.