[lmi-commits] [lmi] master 0b44a84 07/11: Reenumerate root-finding activities

[Greg Chicares]

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

    Reenumerate root-finding activities
    
    Single-character codes tersely elucidate traces. Options considered:
    
      W X Y
      -----
      i 0 E_valuate  evaluate_bounds
      j 1 C_onstrain force_b_and_c_to_bracket_root
      k 2 B_est      force_b_to_be_best_approximation
      L L S_ecant    interpolate_linear
      Q Q I_QI       interpolate_inverse_quadratic
      0 d D_ither    dithering_near_root
      1 o O_OB       secant_out_of_bounds
      2 p P_arabola  parabola_not_single_valued
      3 g G_uarantee guarantee_linear_convergence
      4 z Z [last]   pis_aller
    
    Y: Letters alone could be chosen to suggest mnemonics--too precious.
    X: Lowercase mnemonics for bisection remain obscure.
    W: Lowercase=initialization; capital=higher-order; digit=bisection
    
    Option W seems best. Symbols such as "-\|/_+" or unicode exotica
    were considered, but found ambiguous (which of "/\" is a secant?).
---
 zero.hpp      | 43 ++++++++++++++++++++++++++++++-------------
 zero_test.cpp |  2 +-
 2 files changed, 31 insertions(+), 14 deletions(-)

diff --git a/zero.hpp b/zero.hpp
index 895d2c9..84bb473 100644
--- a/zero.hpp
+++ b/zero.hpp
@@ -54,11 +54,16 @@ enum root_bias
 ///      yes         no       implicitly converts to char
 
 enum root_impetus : char
-    {interpolate_initialization    = 'I'
-    ,interpolate_bisection0        = 'B'
-    ,interpolate_linear            = 'L'
-    ,interpolate_inverse_quadratic = 'Q'
-    ,interpolate_bisection1        = 'b' // bisection when quadratic rejected
+    {evaluate_bounds                  = 'i'
+    ,force_b_and_c_to_bracket_root    = 'j'
+    ,force_b_to_be_best_approximation = 'k'
+    ,interpolate_linear               = 'L'
+    ,interpolate_inverse_quadratic    = 'Q'
+    ,dithering_near_root              = '0'
+    ,secant_out_of_bounds             = '1'
+    ,parabola_not_single_valued       = '2'
+    ,guarantee_linear_convergence     = '3'
+    ,pis_aller                        = '4'
     };
 
 enum root_validity
@@ -275,7 +280,7 @@ root_type lmi_root
     constexpr double epsilon {std::numeric_limits<double>::epsilon()};
 
     int              n_iter  {0};
-    root_impetus     impetus {interpolate_initialization};
+    root_impetus     impetus {evaluate_bounds};
 
     os_trace
         << "#eval"
@@ -348,6 +353,7 @@ root_type lmi_root
             c = a;
             fc = fa;
             d = e = b - a;
+            impetus = force_b_and_c_to_bracket_root;
             }
         // If 'c' is a closer approximant than 'b', then swap them,
         // discarding the old value of 'a'.
@@ -355,6 +361,7 @@ root_type lmi_root
             {
              a =  b;  b =  c;  c =  a;
             fa = fb; fb = fc; fc = fa;
+            impetus = force_b_to_be_best_approximation;
             }
         double tol = 2.0 * epsilon * std::fabs(b) + t;
         double m = 0.5 * (c - b);
@@ -379,12 +386,12 @@ root_type lmi_root
             }
         if(std::fabs(e) < tol)
             {
-            impetus = interpolate_bisection0;
+            impetus = dithering_near_root;
             d = e = m;
             }
         else if(std::fabs(fa) <= std::fabs(fb))
             {
-            impetus = interpolate_bisection0;
+            impetus = secant_out_of_bounds;
             d = e = m;
             }
         else
@@ -440,7 +447,11 @@ root_type lmi_root
                 }
             else
                 {
-                impetus = interpolate_bisection1;
+                impetus =
+                      k0 ? parabola_not_single_valued
+                    : k1 ? guarantee_linear_convergence
+                    :      pis_aller
+                    ;
                 d = e = m;
                 }
             }
@@ -532,7 +543,7 @@ double brent_zero
     // that f(a) and f(b) have different signs.
 
     int          n_iter  {0};
-    root_impetus impetus {interpolate_initialization};
+    root_impetus impetus {evaluate_bounds};
 
     os_trace
         << "#eval"
@@ -564,11 +575,13 @@ double brent_zero
     expatiate();
   interpolate:
     c = a; fc = fa; d = e = b - a;
+    impetus = force_b_and_c_to_bracket_root;
   extrapolate:
     if(std::fabs(fc) < std::fabs(fb))
         {
          a =  b;  b =  c;  c =  a;
         fa = fb; fb = fc; fc = fa;
+        impetus = force_b_to_be_best_approximation;
         }
     tol = 2.0 * DBL_EPSILON * std::fabs(b) + t;
     m = 0.5 * (c - b);
@@ -577,12 +590,12 @@ double brent_zero
         // See if a bisection is forced.
         if(std::fabs(e) < tol)
             {
-            impetus = interpolate_bisection0;
+            impetus = dithering_near_root;
             d = e = m;
             }
         else if(std::fabs(fa) <= std::fabs(fb))
             {
-            impetus = interpolate_bisection0;
+            impetus = secant_out_of_bounds;
             d = e = m;
             }
         else
@@ -622,7 +635,11 @@ double brent_zero
                 }
             else
                 {
-                impetus = interpolate_bisection1;
+                impetus =
+                      k0 ? parabola_not_single_valued
+                    : k1 ? guarantee_linear_convergence
+                    :      pis_aller
+                    ;
                 d = e = m;
                 }
             }
diff --git a/zero_test.cpp b/zero_test.cpp
index 1110438..dbc03a4 100644
--- a/zero_test.cpp
+++ b/zero_test.cpp
@@ -488,7 +488,7 @@ void test_celebrated_equation()
     // "1 + " skips the newline:
     std::string const verified = 1 + R"--cut-here--(
 #eval            a           fa            b           fb            c         
  fc
-  2 I -2.5600000000000001 -16.657216000000002 2.5600000000000001 
6.6572160000000018            0            0
+  2 i -2.5600000000000001 -16.657216000000002 2.5600000000000001 
6.6572160000000018            0            0
   3 L 2.5600000000000001 6.6572160000000018 1.0980323260716793 
-5.8721945393772152 -2.5600000000000001 -16.657216000000002
   4 L 1.0980323260716793 -5.8721945393772152 1.783216881610604 
-2.8960493667789873 2.5600000000000001 6.6572160000000018
   5 Q 1.783216881610604 -2.8960493667789873 2.2478393639958036 
1.8621631139566732 2.5600000000000001 6.6572160000000018