Document ARing headers and implementation guide

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

@@ -1,5 +1,22 @@
 // Copyright 2012 Michael E. Stillman
 
+/// AI:
+/// \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<ARingCC>` 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_
 

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.
+///
+/// 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<ARingCCC>` 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_
 

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

@@ -1,5 +1,21 @@
 // Copyright 2012 Michael E. Stillman
 
+/// AI:
+/// \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<ARingCCi>` 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_
 

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

@@ -1,5 +1,24 @@
 // Copyright 2014 Michael E. Stillman
 
+/// AI:
+/// \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`.
+///
+/// The ARing owns the FLINT context, original polynomial ring, characteristic,
+/// extension degree, and generator data needed by factory code and finite-field
+/// algorithms.  `ConcreteRing<ARingGFFlintBig>` 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_
 

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

@@ -1,5 +1,22 @@
 // Copyright 2014 Michael E. Stillman
 
+/// AI:
+/// \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 ARing is the bridge between FLINT field arithmetic and the engine's
+/// `Ring` API: `ConcreteRing<ARingGFFlint>` 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_
 

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

@@ -1,5 +1,22 @@
 // Copyright 2013 Michael E. Stillman
 
+/// AI:
+/// \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<ARingQQFlint>` 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_
 

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

@@ -1,5 +1,22 @@
 // Copyright 2013 Michael E. Stillman
 
+/// AI:
+/// \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<ARingQQGMP>` 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_
 

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 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_
 

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.
+///
+/// ARingRR is the double-precision real-number ARing.  Its `ElementType` is a
+/// machine `double`, so the `SimpleARing` lifecycle functions are lightweight
+/// assignments while `ConcreteRing<ARingRR>` 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_
 

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

@@ -1,5 +1,20 @@
 // Copyright 2012 Michael E. Stillman
 
+/// AI:
+/// \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<ARingRRR>` 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_
 

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.
+///
+/// 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<ARingRRi>` 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_
 

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.
+///
+/// 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<ARingZZ>`.
+///
+/// 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_
 

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

@@ -1,5 +1,20 @@
 // Copyright 2013 Michael E. Stillman
 
+/// AI:
+/// \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<ARingZZGMP>` 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_
 

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.
+///
+/// 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<ARingZZpFFPACK>` 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_
 

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

@@ -1,5 +1,20 @@
 // Copyright 2013 Michael E. Stillman
 
+/// AI:
+/// \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.
+///
+/// `ConcreteRing<ARingZZpFlint>` 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_
 

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.
+///
+/// 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<ARingZZp>`.
+///
+/// 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_
 

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

@@ -1,5 +1,23 @@
 // Copyright 2011 Michael E. Stillman
 
+/// AI:
+/// \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<RingType>`
+/// 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_