Fixed spec

dlib/global_optimization/find_global_maximum_abstract.h

@@ -3,17 +3,21 @@
 #undef DLIB_FiND_GLOBAL_MAXIMUM_ABSTRACT_hH_
 #ifdef DLIB_FiND_GLOBAL_MAXIMUM_ABSTRACT_hH_
 
-
+#include "upper_bound_function_abstract.h"
 #include "global_function_search_abstract.h"
 #include "../metaprogramming.h"
+#include "../matrix.h"
 #include <utility>
 #include <chrono>
 
 namespace dlib
 {
+
 // ----------------------------------------------------------------------------------------
 
-    template <typename T> 
+    template <
+        typename T
+        > 
     auto call_function_and_expand_args(
         T&& f, 
         const matrix<double,0,1>& args
@@ -34,7 +38,7 @@ namespace dlib
               However, the signature of f() is allowed to vary.  In particular, if f()
               takes a matrix<double,0,1> as a single argument then this function simply
               calls f(args).  However, if f() takes double arguments then args is expanded
-              appropriately, e.g it calls one of the following as appropriate: 
+              appropriately, i.e. it calls one of the following as appropriate: 
                 f(args(0))
                 f(args(0),args(1))
                 ...
@@ -48,10 +52,13 @@ namespace dlib
     {
         /*!
             WHAT THIS OBJECT REPRESENTS
+                This is a simple typed integer class used to strongly type the "max number
+                of function calls" argument to find_global_maximum().
 
         !*/
 
         max_function_calls() = default;
+
         explicit max_function_calls(size_t max_calls) : max_calls(max_calls) {}
 
         size_t max_calls = std::numeric_limits<size_t>::max();
@@ -59,7 +66,7 @@ namespace dlib
 
 // ----------------------------------------------------------------------------------------
 
-    const auto FOREVER = std::chrono::hours(24*356*290); // 290 years
+    const auto FOREVER = std::chrono::hours(24*356*290); // 290 years, basically forever
 
 // ----------------------------------------------------------------------------------------
 
@@ -92,23 +99,23 @@ namespace dlib
         ensures
             - This function performs global optimization on the set of given functions.
               The goal is to maximize the following objective function:
-                 functions[i](x)
-                 subject to the constraints on x defined by specs[i].
+                 max_{i,x_i}: functions[i](x_i)
+                 subject to the constraints on x_i defined by specs[i].
               Once found, the return value of find_global_maximum() is:
-                make_pair(i, function_evaluation(x,functions[i](x))). 
+                make_pair(i, function_evaluation(x_i,functions[i](x_i))). 
               That is, we search for the settings of i and x that return the largest output
               and return those settings.
             - The search is performed using the global_function_search object.  See its
               documentation for details of the algorithm.
             - We set the global_function_search::get_solver_epsilon() parameter to
               solver_epsilon.  Therefore, the search will only attempt to find a global
-              maximizer to at most solver_epsilon accuracy.  Once a local minimizer is
-              found to that accuracy the search will focus entirely on finding another
-              minimizers elsewhere rather than on further improving the current local
-              optima found so far.  That is, once a local minima is identified to about
-              solver_epsilon accuracy, the algorithm will spend all its time exploring the
-              function to find other local minima to investigate.
-            - find_global_maximum runs until one of the following is true:
+              maximizer to at most solver_epsilon accuracy.  Once a local maximizer is
+              found to that accuracy the search will focus entirely on finding other maxima
+              elsewhere rather than on further improving the current local optima found so
+              far.  That is, once a local maxima is identified to about solver_epsilon
+              accuracy, the algorithm will spend all its time exploring the functions to
+              find other local maxima to investigate.
+            - find_global_maximum() runs until one of the following is true:
                 - The total number of calls to the provided functions is == num.max_calls
                 - More than max_runtime time has elapsed since the start of this function.
     !*/
@@ -148,19 +155,19 @@ namespace dlib
                  subject to the constraints on x defined by function_spec(bound1,bound2,is_integer_variable).
               Once found, the return value of find_global_maximum() is:
                 function_evaluation(x,f(x))). 
-              That is, we search for the setting of x that return the largest output and
-              return those settings.
+              That is, we search for the setting of x that returns the largest output and
+              return that setting.
             - The search is performed using the global_function_search object.  See its
               documentation for details of the algorithm.
             - We set the global_function_search::get_solver_epsilon() parameter to
               solver_epsilon.  Therefore, the search will only attempt to find a global
-              maximizer to at most solver_epsilon accuracy.  Once a local minimizer is
-              found to that accuracy the search will focus entirely on finding another
-              minimizers elsewhere rather than on further improving the current local
-              optima found so far.  That is, once a local minima is identified to about
-              solver_epsilon accuracy, the algorithm will spend all its time exploring the
-              function to find other local minima to investigate.
-            - find_global_maximum runs until one of the following is true:
+              maximizer to at most solver_epsilon accuracy.  Once a local maximizer is
+              found to that accuracy the search will focus entirely on finding other maxima
+              elsewhere rather than on further improving the current local optima found so
+              far.  That is, once a local maxima is identified to about solver_epsilon
+              accuracy, the algorithm will spend all its time exploring the function to
+              find other local maxima to investigate.
+            - find_global_maximum() runs until one of the following is true:
                 - The total number of calls to f() is == num.max_calls
                 - More than max_runtime time has elapsed since the start of this function.
     !*/