Document ARing headers and implementation guide

M2/Macaulay2/e/basic-rings/aring-CC.hpp

@@ -1,5 +1,21 @@
 // Copyright 2012 Michael E. Stillman
 
+/// AI:
+/// \file aring-CC.hpp
+/// \brief Defines ARingCC, the machine-precision complex arithmetic ring.
+///
+/// This header declares the ARing implementation for approximate complex
+/// numbers stored as `cc_doubles_struct`, a pair of machine doubles.  The class
+/// follows the `SimpleARing` contract: its lifetime functions initialize, copy,
+/// assign, and clear the raw element storage used by wrapper code.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingCC>` 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_
 

M2/Macaulay2/e/basic-rings/aring-CCC.hpp

@@ -1,5 +1,21 @@
 // Copyright 2012 Michael E. Stillman
 
+/// AI:
+/// \file aring-CCC.hpp
+/// \brief Defines ARingCCC, the arbitrary-precision complex arithmetic ring.
+///
+/// This header declares the ARing implementation for arbitrary-precision
+/// complex numbers stored as two MPFR values in a `cc_struct`.  The ring
+/// carries an `ARingRRR` with the same precision for real-part operations.  Its
+/// `SimpleARing` lifetime methods handle MPFR initialization and cleanup.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingCCC>` 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_
 

M2/Macaulay2/e/basic-rings/aring-CCi.hpp

@@ -1,5 +1,22 @@
 // Copyright 2012 Michael E. Stillman
 
+/// AI:
+/// \file aring-CCi.hpp
+/// \brief Defines ARingCCi, the arbitrary-precision complex interval ring.
+///
+/// This header declares the ARing implementation for arbitrary-precision
+/// complex intervals stored as real and imaginary MPFI intervals in
+/// `cci_struct`.  The ring carries the precision used by those intervals, and
+/// its `SimpleARing` lifetime methods initialize, copy, assign, and clear the
+/// interval storage.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingCCi>` 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_
 

M2/Macaulay2/e/basic-rings/aring-GF-flint-big.hpp

@@ -1,5 +1,22 @@
 // Copyright 2014 Michael E. Stillman
 
+/// AI:
+/// \file aring-GF-flint-big.hpp
+/// \brief Defines ARingGFFlintBig, a FLINT fq_nmod finite field ring.
+///
+/// This header declares the ARing implementation for finite-field extensions
+/// stored with FLINT's `fq_nmod` representation.  The ring owns the FLINT
+/// context, original polynomial ring, characteristic, extension degree, and
+/// generator data, so it derives from `RingInterface` and defines context-aware
+/// `Element` and `ElementArray` wrappers instead of using `SimpleARing`.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingGFFlintBig>` 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_
 

M2/Macaulay2/e/basic-rings/aring-GF-flint.hpp

@@ -1,5 +1,23 @@
 // Copyright 2014 Michael E. Stillman
 
+/// AI:
+/// \file aring-GF-flint.hpp
+/// \brief Defines ARingGFFlint, a FLINT fq_zech finite field ring.
+///
+/// This header declares the ARing implementation for finite-field extensions
+/// stored with FLINT's `fq_zech` Zech-log representation.  Each element depends
+/// on a FLINT context for initialization and destruction, so the class derives
+/// from `RingInterface` and defines context-aware `Element` and `ElementArray`
+/// wrappers instead of using `SimpleARing`.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingGFFlint>` 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_
 

M2/Macaulay2/e/basic-rings/aring-QQ-flint.hpp

@@ -1,5 +1,21 @@
 // Copyright 2013 Michael E. Stillman
 
+/// AI:
+/// \file aring-QQ-flint.hpp
+/// \brief Defines ARingQQFlint, the FLINT-backed rational arithmetic ring.
+///
+/// This header declares the ARing implementation for rational numbers stored
+/// as FLINT `fmpq` values.  The class follows the `SimpleARing` contract: its
+/// lifetime functions initialize, copy, assign, and clear the FLINT rational
+/// storage used by wrapper code.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingQQFlint>` 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_
 

M2/Macaulay2/e/basic-rings/aring-QQ-gmp.hpp

@@ -1,5 +1,21 @@
 // Copyright 2013 Michael E. Stillman
 
+/// AI:
+/// \file aring-QQ-gmp.hpp
+/// \brief Defines ARingQQGMP, the GMP-backed rational arithmetic ring.
+///
+/// This header declares the ARing implementation for rational numbers stored
+/// as GMP `mpq` values.  It is the current `ARingQQ` backend selected by
+/// `aring-QQ.hpp`, and its `SimpleARing` lifetime methods initialize, copy,
+/// assign, and clear the GMP rational storage used by wrapper code.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingQQGMP>` and forwards
+/// exact rational operations through the methods declared here: `ring_elem`
+/// conversion, construction from integers and rationals, arithmetic,
+/// comparison, hashing, printing, and randomization.  `aring-translate.hpp`
+/// uses QQ as a central exact source for promotion into real, complex, and
+/// interval ARings through the relevant `set_from_*` methods.
+
 #ifndef M2_BASIC_RINGS_ARING_QQ_GMP_HPP_
 #define M2_BASIC_RINGS_ARING_QQ_GMP_HPP_
 

M2/Macaulay2/e/basic-rings/aring-QQ.hpp

@@ -1,5 +1,20 @@
 // Copyright 2013 Michael E. Stillman.
 
+/// AI:
+/// \file aring-QQ.hpp
+/// \brief Selects the default ARing implementation for rational numbers.
+///
+/// This header is the coordination point for rational ARings.  It includes the
+/// available QQ backends and defines the `ARingQQ` typedef used by code that
+/// wants the default rational implementation rather than a specific GMP or
+/// FLINT class.
+///
+/// `aring-glue.hpp`, `aring-translate.hpp`, factory code, and tests include
+/// this header when they need the selected QQ backend.  Changing the typedef
+/// changes the implementation used by `RingQQ::create()` and by promotion/lift
+/// code that names `ARingQQ`, while the backend headers remain available for
+/// places that need an explicit implementation.
+
 #ifndef M2_BASIC_RINGS_ARING_QQ_HPP_
 #define M2_BASIC_RINGS_ARING_QQ_HPP_
 

M2/Macaulay2/e/basic-rings/aring-RR.hpp

@@ -1,5 +1,21 @@
 // Copyright 2012 Michael E. Stillman
 
+/// AI:
+/// \file aring-RR.hpp
+/// \brief Defines ARingRR, the machine-precision real arithmetic ring.
+///
+/// This header declares the ARing implementation for machine-precision real
+/// numbers stored as `double` values.  The class follows the `SimpleARing`
+/// contract, and its lifetime functions are lightweight initialization, copy,
+/// assignment, and clear operations for plain double storage.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingRR>` 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_
 

M2/Macaulay2/e/basic-rings/aring-RRR.hpp

@@ -1,5 +1,21 @@
 // Copyright 2012 Michael E. Stillman
 
+/// AI:
+/// \file aring-RRR.hpp
+/// \brief Defines ARingRRR, the arbitrary-precision real arithmetic ring.
+///
+/// This header declares the ARing implementation for arbitrary-precision real
+/// numbers stored as MPFR values.  The ring object carries the precision, and
+/// its `SimpleARing` lifetime methods initialize, copy, assign, and clear each
+/// MPFR element with that precision.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingRRR>` 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_
 

M2/Macaulay2/e/basic-rings/aring-RRi.hpp

@@ -1,5 +1,21 @@
 // Copyright 2012 Michael E. Stillman
 
+/// AI:
+/// \file aring-RRi.hpp
+/// \brief Defines ARingRRi, the arbitrary-precision real interval ring.
+///
+/// This header declares the ARing implementation for arbitrary-precision real
+/// intervals stored with MPFI.  The ring object carries the precision, and its
+/// `SimpleARing` lifetime methods initialize, copy, assign, and clear the
+/// interval storage.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingRRi>` 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_
 

M2/Macaulay2/e/basic-rings/aring-ZZ-flint.hpp

@@ -1,5 +1,21 @@
 // Copyright 2013 Michael E. Stillman
 
+/// AI:
+/// \file aring-ZZ-flint.hpp
+/// \brief Defines ARingZZ, the FLINT-backed integer arithmetic ring.
+///
+/// This header declares the ARing implementation for integers stored as FLINT
+/// `fmpz` values.  The class follows the `SimpleARing` contract: its lifetime
+/// functions initialize, copy, assign, and clear the FLINT integer storage used
+/// by wrapper code.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingZZ>` 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_
 

M2/Macaulay2/e/basic-rings/aring-ZZ-gmp.hpp

@@ -1,5 +1,22 @@
 // Copyright 2013 Michael E. Stillman
 
+/// AI:
+/// \file aring-ZZ-gmp.hpp
+/// \brief Defines ARingZZGMP, the GMP-backed integer arithmetic ring.
+///
+/// This header declares the ARing implementation for integers stored as GMP
+/// `mpz` values.  The class follows the `SimpleARing` contract: its lifetime
+/// functions initialize, copy, assign, and clear the GMP integer storage used
+/// by wrapper code.
+///
+/// `aring-glue.hpp` can wrap this ARing in `ConcreteRing<ARingZZGMP>` 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_
 

M2/Macaulay2/e/basic-rings/aring-ZZp-ffpack.hpp

@@ -1,5 +1,21 @@
 // Copyright 2011 Michael E. Stillman
 
+/// AI:
+/// \file aring-ZZp-ffpack.hpp
+/// \brief Defines ARingZZpFFPACK, an FFPACK/Givaro prime finite field ring.
+///
+/// This header declares the ARing implementation for prime finite fields backed
+/// by a Givaro modular field for FFPACK/FFLAS dense linear algebra.  The raw
+/// element type is the Givaro field element, and the class follows the
+/// `SimpleARing` contract for lifetime and arithmetic over that storage.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingZZpFFPACK>` 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_
 

M2/Macaulay2/e/basic-rings/aring-ZZp-flint.hpp

@@ -1,5 +1,22 @@
 // Copyright 2013 Michael E. Stillman
 
+/// AI:
+/// \file aring-ZZp-flint.hpp
+/// \brief Defines ARingZZpFlint, a FLINT-backed prime finite field ring.
+///
+/// This header declares the ARing implementation for prime finite fields backed
+/// by FLINT `nmod` arithmetic for word-sized moduli.  Its `ElementType` is an
+/// `mp_limb_t`, so `SimpleARing` can manage elements with inexpensive
+/// initialization and no-op cleanup while the ring object stores the modulus
+/// and generator data.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingZZpFlint>` and
+/// forwards prime-field operations through the methods declared here:
+/// construction from ZZ/QQ, `ring_elem` conversion, arithmetic, comparison,
+/// hashing, printing, randomization, integer lifting, generator access, and
+/// discrete logarithms.  Vector and matrix code use this backend when selecting
+/// FLINT-backed dense arithmetic paths.
+
 #ifndef M2_BASIC_RINGS_ARING_ZZP_FLINT_HPP_
 #define M2_BASIC_RINGS_ARING_ZZP_FLINT_HPP_
 

M2/Macaulay2/e/basic-rings/aring-ZZp.hpp

@@ -1,5 +1,21 @@
 // Copyright 2011 Michael E. Stillman
 
+/// AI:
+/// \file aring-ZZp.hpp
+/// \brief Defines ARingZZp, Macaulay2's table-based prime finite field ring.
+///
+/// This header declares the ARing implementation for table-based prime finite
+/// fields.  Elements are compact integers interpreted through logarithm and
+/// exponent tables for a primitive element, and the class follows the
+/// `SimpleARing` contract for lifetime and arithmetic over that storage.
+///
+/// `aring-glue.hpp` wraps this ARing in `ConcreteRing<ARingZZp>` 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_
 

M2/Macaulay2/e/basic-rings/aring-glue.hpp

@@ -1,5 +1,21 @@
 // Copyright 2011 Michael E. Stillman
 
+/// AI:
+/// \file aring-glue.hpp
+/// \brief Connects ARing implementations to the high-level Ring interface.
+///
+/// This header contains the adapter that makes an ARing usable through the
+/// engine's virtual `Ring` API.  `ConcreteRing<RingType>` owns one ARing
+/// object, creates ARing element wrappers around incoming `ring_elem` values,
+/// calls the corresponding `RingType` method, and converts results back to
+/// `ring_elem`.
+///
+/// The adapter also supplies common hooks for mutable matrices, finite-field
+/// predicates, generators, representations, precision, and integer coercion.
+/// Promotion and lift dispatch starts here by inspecting `RingID`; after a
+/// source/target pair is selected, `RingPromoter` delegates the element-level
+/// conversion to `mypromote` or `mylift` in `aring-translate.hpp`.
+
 #ifndef M2_BASIC_RINGS_RING_GLUE_HH_
 #define M2_BASIC_RINGS_RING_GLUE_HH_