updated docs

docs/docs/optimization.xml

@@ -92,6 +92,7 @@
          <item>parse_tree_to_string</item> 
          <item>find_trees_not_rooted_with_tag</item> 
          <item>upper_bound_function</item> 
+         <item>call_function_and_expand_args</item> 
       </section>
 
     </top>  
@@ -1281,6 +1282,32 @@ Or it can use the elastic net regularizer:
                                  
       </component>
 
+   <!-- ************************************************************************* -->
+
+      <component>
+         <name>call_function_and_expand_args</name>
+         <file>dlib/global_optimization.h</file>
+         <spec_file link="true">dlib/global_optimization/find_max_global_abstract.h</spec_file>
+         <description>
+            This routine allows you to pass a <tt>dlib::matrix&lt;double,0,1&gt;</tt> object to
+            a function that takes simple <tt>double</tt> arguments.  It does this by automatically
+            expanding the matrix elements and invoking the function.  For example, suppose you had
+            a function like this:
+            <code_box>
+double f(double x, double y, double z); </code_box>
+            You could then call f() like this:
+            <code_box>
+matrix&lt;double,0,1&gt; args = {3,4,5};
+call_function_and_expand_args(f, args); // calls: f(3,4,5) </code_box>
+
+            This kind of thing is convenient when writing optimizers like <a
+            href="#find_max_global">find_max_global</a> since it allows a wide range of
+            input functions to be given to the optimizer, including functions with
+            explicitly named arguments like x,y,z as shown above.
+         </description>
+                                 
+      </component>
+
    <!-- ************************************************************************* -->
 
 

docs/docs/release_notes.xml

@@ -19,6 +19,7 @@ New Features and Improvements:
       - Added solve_trust_region_subproblem_bounded()
       - Added tools for doing global optimization. The main new tools here are find_max_global() and global_function_search.
       - Updated model_selection_ex.cpp and optimization_ex.cpp to use these new tools.
+      - added call_function_and_expand_args()
    - Added loss_ranking_ layer 
    - Added loss_epsilon_insensitive_ layer
    - Added softmax_all layer.

docs/docs/term_index.xml

@@ -264,8 +264,11 @@
          <term file="optimization.html" name="find_max_box_constrained"    include="dlib/optimization.h"/>
          <term file="optimization.html" name="find_max_global"             include="dlib/global_optimization.h"/>
          <term file="optimization.html" name="find_min_global"             include="dlib/global_optimization.h"/>
-         <term file="optimization.html" name="global_function_search"             include="dlib/global_optimization.h"/>
+         <term file="optimization.html" name="global_function_search"           include="dlib/global_optimization.h"/>
          <term file="optimization.html" name="upper_bound_function"             include="dlib/global_optimization.h"/>
+         <term file="optimization.html" name="call_function_and_expand_args"    include="dlib/global_optimization.h"/>
+         <term file="dlib/global_optimization/find_max_global_abstract.h.html" name="FOREVER"   include="dlib/global_optimization.h"/>
+         <term file="dlib/global_optimization/find_max_global_abstract.h.html" name="max_function_calls"   include="dlib/global_optimization.h"/>
          <term file="optimization.html" name="max_cost_assignment"         include="dlib/optimization.h"/>
          <term link="optimization.html#max_cost_assignment" name="Hungarian Algorithm"         include="dlib/optimization.h"/>
          <term file="optimization.html" name="max_sum_submatrix"           include="dlib/optimization.h"/>