start documenting functions in the MathSpecial namespace

doc/doxygen/Doxyfile.in

@@ -2,7 +2,7 @@
 
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "LAMMPS Programmer's Guide"
-PROJECT_NUMBER         = "24 August 2020"
+PROJECT_NUMBER         = "4 May 2022"
 PROJECT_BRIEF          = "Documentation of the LAMMPS library interface and Python wrapper"
 PROJECT_LOGO           = lammps-logo.png
 CREATE_SUBDIRS         = NO
@@ -437,6 +437,8 @@ INPUT                  = @LAMMPS_SOURCE_DIR@/utils.cpp                 \
                          @LAMMPS_SOURCE_DIR@/math_eigen.h              \
                          @LAMMPS_SOURCE_DIR@/platform.h                \
                          @LAMMPS_SOURCE_DIR@/platform.cpp              \
+                         @LAMMPS_SOURCE_DIR@/math_special.h            \
+                         @LAMMPS_SOURCE_DIR@/math_special.cpp          \
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

doc/src/Developer_utils.rst

@@ -246,6 +246,23 @@ Customized standard functions
 
 ---------------------------
 
+Special Math functions
+----------------------
+
+The ``MathSpecial`` namespace implements a selection of custom and optimized
+mathematical functions for a variety of applications.
+
+.. doxygenfunction:: factorial
+   :project: progguide
+
+.. doxygenfunction:: exp2_x86
+   :project: progguide
+
+.. doxygenfunction:: fm_exp
+   :project: progguide
+
+---------------------------
+
 Tokenizer classes
 -----------------
 

src/math_special.cpp

@@ -706,6 +706,7 @@ static const double fm_exp2_p[] = {
 
 double MathSpecial::exp2_x86(double x)
 {
+#if defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__)
     double   ipart, fpart, px, qx;
     udi_t    epart;
 
@@ -726,6 +727,9 @@ double MathSpecial::exp2_x86(double x)
 
     x = 1.0 + 2.0*(px/(qx-px));
     return epart.f*x;
+#else
+    return pow(2.0, x);
+#endif
 }
 
 double MathSpecial::fm_exp(double x)

src/math_special.h

@@ -20,20 +20,50 @@ namespace LAMMPS_NS {
 
 namespace MathSpecial {
 
-  // tabulated factorial function
+  /*! Fast tabulated factorial function
+   *
+   *  This function looks up precomputed factorial values for arguments of n = 0
+   *  to a maximum of 167, which is the maximal value representable by a double
+   *  precision floating point number.  For other values of n a NaN value is returned.
+   *
+   *  \param   n  argument (valid: 0 <= n <= 167)
+   *  \return  value of n! as double precision number or NaN */
 
-  extern double factorial(const int);
+  extern double factorial(const int n);
+
+  /*! Fast implementation of 2^x without argument checks for little endian CPUs
+   *
+   *  This function implements an optimized version of pow(2.0, x) that does not
+   *  check for valid arguments and thus may only be used where arguments are well
+   *  behaved.  The implementation makes assumptions about the layout of double
+   *  precision floating point numbers in memory and thus will only work on little
+   *  endian CPUs.  If little endian cannot be safely detected, the result of
+   *  calling pow(2.0, x) will be returned.  This function also is the basis for
+   *  the fast exponential fm_exp(x).
+   *
+   *  \param   x argument
+   *  \return  value of 2^x as double precision number */
+
+  extern double exp2_x86(double x);
+
+  /*! Fast implementation of exp(x) for little endian CPUs
+   *
+   *  This function implements an optimized version of exp(x) for little endian CPUs.
+   *  It calls the exp2_x86(x) function with a suitable prefactor to x to return exp(x).
+   *  The implementation makes assumptions about the layout of double
+   *  precision floating point numbers in memory and thus will only work on little
+   *  endian CPUs.  If little endian cannot be safely detected, the result of
+   *  calling the exp(x) implementation in the libm math library will be returned.
+   *
+   *  \param   x argument
+   *  \return  value of e^x as double precision number */
+
+  extern double fm_exp(double x);
 
   // support function for scaled error function complement
 
   extern double erfcx_y100(const double y100);
 
-  // fast 2**x function without argument checks for little endian CPUs
-  extern double exp2_x86(double x);
-
-  // fast e**x function for little endian CPUs, falls back to libc on other platforms
-  extern double fm_exp(double x);
-
   // scaled error function complement exp(x*x)*erfc(x) for coul/long styles
 
   static inline double my_erfcx(const double x)