[lmi-commits] [lmi] master 1b9395f2 03/11: Improve documentation

[Greg Chicares]

branch: master
commit 1b9395f22d50b2bb2a0cc31cae651cf618c64052
Author: Gregory W. Chicares <gchicares@sbcglobal.net>
Commit: Gregory W. Chicares <gchicares@sbcglobal.net>

    Improve documentation
    
    In comments, don't qualify function names with 'std::' where a
    nonstandard implementation might be substituted, rendering the
    comment incorrect.
    
    State the transformation
      (1+i)^n - 1 <-> expm1(log1p(i) * n)
    OAOO, instead of repeating it several times.
    
    pow() is both slower and less accurate than the combination of
    expm1() and log1p(): not "less inaccurate" as previously stated.
---
 math_functions.hpp      |  7 +------
 math_functions_test.cpp | 22 +++++++++++-----------
 2 files changed, 12 insertions(+), 17 deletions(-)

diff --git a/math_functions.hpp b/math_functions.hpp
index 05f9a34b..9add8696 100644
--- a/math_functions.hpp
+++ b/math_functions.hpp
@@ -125,7 +125,7 @@ T signum(T t)
 //
 // Implementation note: greater accuracy and speed are obtained by
 // applying the transformation
-//   (1+i)^n - 1 <-> std::expm1(std::log1p(i) * n)
+//   (1+i)^n - 1 <-> expm1(log1p(i) * n)
 // to naive power-based formulas.
 
 template<typename T, int n>
@@ -146,7 +146,6 @@ struct i_upper_n_over_n_from_i
             }
 
         // naively:    (1+i)^(1/n) - 1
-        // substitute: (1+i)^n - 1 <-> std::expm1(std::log1p(i) * n)
         return std::expm1(std::log1p(i) / n);
         }
 };
@@ -171,7 +170,6 @@ struct i_from_i_upper_n_over_n
     T operator()(T i) const
         {
         // naively:    (1+i)^n - 1
-        // substitute: (1+i)^n - 1 <-> std::expm1(std::log1p(i) * n)
         return std::expm1(std::log1p(i) * n);
         }
 };
@@ -204,7 +202,6 @@ struct d_upper_n_from_i
             }
 
         // naively:    n * (1 - (1+i)^(-1/n))
-        // substitute: (1+i)^n - 1 <-> std::expm1(std::log1p(i) * n)
         return -n * std::expm1(std::log1p(i) / -n);
         }
 };
@@ -238,7 +235,6 @@ struct net_i_from_gross
         //   -   (1+spread)^(1/n)
         //   -         fee *(1/n)
         //   )^n - 1
-        // substitute: (1+i)^n - 1 <-> std::expm1(std::log1p(i) * n)
         return std::expm1
             (
             n * std::log1p
@@ -303,7 +299,6 @@ struct coi_rate_from_q
         else
             {
             // naively:    1 - (1-q)^(1/12)
-            // substitute: (1+i)^n - 1 <-> std::expm1(std::log1p(i) * n)
             T monthly_q = -std::expm1(std::log1p(-q) / 12);
             if(T(1) == monthly_q)
                 {
diff --git a/math_functions_test.cpp b/math_functions_test.cpp
index 354c60d0..00854a3b 100644
--- a/math_functions_test.cpp
+++ b/math_functions_test.cpp
@@ -43,7 +43,7 @@
 
 namespace
 {
-// These naive implementations in terms of std::pow() are slower and
+// These naive implementations in terms of pow() are slower and
 // less accurate than those in the header tested here.
 
 template<typename T>
@@ -148,11 +148,11 @@ struct i_upper_n_over_n_from_i_T
 };
 } // Unnamed namespace.
 
-// These 'mete[01]' functions perform the same sets of operations using
-// different implementations.
+// These 'mete[01]' functions perform the same sets of operations
+// using different implementations.
 
-// This implementation naively uses std::pow(); it is both slower and
-// less inaccurate than an alternative using std::expm1() and std::log1p().
+// This implementation naively uses pow(); it is both slower and
+// less accurate than an alternative using expm1() and log1p().
 void mete0()
 {
     double volatile x;
@@ -700,9 +700,9 @@ void sample_results()
 #endif // defined LMI_X87
     std::cout
         << "  " << i_upper_n_over_n_from_i_T    <long double,12>()(intrate)
-        << "  long double prec, std::expm1 and std::log1p\n"
+        << "  long double prec, expm1 and log1p\n"
         << "  " << i_upper_n_over_n_from_i_naive<long double,12>()(intrate)
-        << "  long double prec, std::pow\n"
+        << "  long double prec, pow\n"
         ;
 #if defined LMI_X87
     fenv_initialize();
@@ -712,9 +712,9 @@ void sample_results()
         << "  " << i_upper_n_over_n_from_i      <double,12>()(intrate)
         << "  double prec, production template\n"
         << "  " << i_upper_n_over_n_from_i_T    <double,12>()(intrate)
-        << "  double prec, std::expm1 and std::log1p\n"
+        << "  double prec, expm1 and log1p\n"
         << "  " << i_upper_n_over_n_from_i_naive<double,12>()(intrate)
-        << "  double prec, std::pow\n"
+        << "  double prec, pow\n"
         << std::endl;
         ;
 
@@ -724,8 +724,8 @@ void sample_results()
 void assay_speed()
 {
     std::cout << "Speed tests:\n";
-    std::cout << "  std::pow         " << TimeAnAliquot(mete0) << '\n';
-    std::cout << "  std::expm1       " << TimeAnAliquot(mete1) << '\n';
+    std::cout << "  pow              " << TimeAnAliquot(mete0) << '\n';
+    std::cout << "  expm1 and log1p  " << TimeAnAliquot(mete1) << '\n';
     std::cout << "  double      i365 " << TimeAnAliquot(mete2) << '\n';
     std::cout << "  long double i365 " << TimeAnAliquot(mete3) << '\n';
     std::cout << "  10^-9 nonstd     " << TimeAnAliquot(mete4) << '\n';