Document ARing headers and implementation guide

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

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

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

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

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

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

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

@@ -1,5 +1,13 @@
 // Copyright 2014 Michael E. Stillman
 
+/// AI:
+/// \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_
 

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

@@ -1,5 +1,13 @@
 // Copyright 2014 Michael E. Stillman
 
+/// AI:
+/// \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_
 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,4 +1,13 @@
 // Copyright 2010-2012 Michael E. Stillman.
+
+/// AI:
+/// \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_
 

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

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

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

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