Added a spec for the least squares stuff

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%403934

dlib/optimization/optimization_least_squares.h

@@ -5,6 +5,7 @@
 
 #include "../matrix.h"
 #include "optimization_trust_region.h"
+#include "optimization_least_squares_abstract.h"
 
 namespace dlib
 {
@@ -15,7 +16,7 @@ namespace dlib
         typename column_vector_type,
         typename funct_type,
         typename funct_der_type,
-        typename list_type
+        typename vector_type
         >
     class least_squares_function_model 
     {
@@ -23,7 +24,7 @@ namespace dlib
         least_squares_function_model (
             const funct_type& f_,
             const funct_der_type& der_,
-            const list_type& list_
+            const vector_type& list_
         ) : f(f_), der(der_), list(list_) 
         {
             S = 0;
@@ -33,7 +34,7 @@ namespace dlib
 
         const funct_type& f;
         const funct_der_type& der;
-        const list_type& list;
+        const vector_type& list;
 
         typedef typename column_vector_type::type type;
         typedef typename column_vector_type::mem_manager_type mem_manager_type;
@@ -139,15 +140,15 @@ namespace dlib
         typename column_vector_type,
         typename funct_type,
         typename funct_der_type,
-        typename list_type
+        typename vector_type
         >
-    least_squares_function_model<column_vector_type,funct_type,funct_der_type,list_type> least_squares_model (
+    least_squares_function_model<column_vector_type,funct_type,funct_der_type,vector_type> least_squares_model (
         const funct_type& f,
         const funct_der_type& der,
-        const list_type& list
+        const vector_type& list
     )
     {
-        return least_squares_function_model<column_vector_type,funct_type,funct_der_type,list_type>(f,der,list);
+        return least_squares_function_model<column_vector_type,funct_type,funct_der_type,vector_type>(f,der,list);
     }
 
 // ----------------------------------------------------------------------------------------
@@ -156,18 +157,29 @@ namespace dlib
         typename stop_strategy_type,
         typename funct_type,
         typename funct_der_type,
-        typename list_type,
+        typename vector_type,
         typename T
         >
     double solve_least_squares (
         stop_strategy_type stop_strategy,
         const funct_type& f,
         const funct_der_type& der,
-        const list_type& list,
+        const vector_type& list,
         T& x, 
         double radius = 1
     )
     {
+        // make sure requires clause is not broken
+        DLIB_ASSERT(is_vector(vector_to_matrix(list)) && list.size() > 0 && 
+                    is_col_vector(x) && radius > 0,
+            "\t double solve_least_squares()"
+            << "\n\t invalid arguments were given to this function"
+            << "\n\t is_vector(list):  " << is_vector(vector_to_matrix(list)) 
+            << "\n\t list.size():      " << list.size() 
+            << "\n\t is_col_vector(x): " << is_col_vector(x) 
+            << "\n\t radius:           " << radius
+            );
+
         return find_min_trust_region(stop_strategy,
                                      least_squares_model<T>(f, der, vector_to_matrix(list)), 
                                      x, 
@@ -182,7 +194,7 @@ namespace dlib
         typename column_vector_type,
         typename funct_type,
         typename funct_der_type,
-        typename list_type
+        typename vector_type
         >
     class least_squares_lm_function_model 
     {
@@ -190,12 +202,12 @@ namespace dlib
         least_squares_lm_function_model (
             const funct_type& f_,
             const funct_der_type& der_,
-            const list_type& list_
+            const vector_type& list_
         ) : f(f_), der(der_), list(list_) {}
 
         const funct_type& f;
         const funct_der_type& der;
-        const list_type& list;
+        const vector_type& list;
 
         typedef typename column_vector_type::type type;
         typedef typename column_vector_type::mem_manager_type mem_manager_type;
@@ -245,15 +257,15 @@ namespace dlib
         typename column_vector_type,
         typename funct_type,
         typename funct_der_type,
-        typename list_type
+        typename vector_type
         >
-    least_squares_lm_function_model<column_vector_type,funct_type,funct_der_type,list_type> least_squares_lm_model (
+    least_squares_lm_function_model<column_vector_type,funct_type,funct_der_type,vector_type> least_squares_lm_model (
         const funct_type& f,
         const funct_der_type& der,
-        const list_type& list
+        const vector_type& list
     )
     {
-        return least_squares_lm_function_model<column_vector_type,funct_type,funct_der_type,list_type>(f,der,list);
+        return least_squares_lm_function_model<column_vector_type,funct_type,funct_der_type,vector_type>(f,der,list);
     }
 
 // ----------------------------------------------------------------------------------------
@@ -262,18 +274,29 @@ namespace dlib
         typename stop_strategy_type,
         typename funct_type,
         typename funct_der_type,
-        typename list_type,
+        typename vector_type,
         typename T
         >
     double solve_least_squares_lm (
         stop_strategy_type stop_strategy,
         const funct_type& f,
         const funct_der_type& der,
-        const list_type& list,
+        const vector_type& list,
         T& x, 
         double radius = 1
     )
     {
+        // make sure requires clause is not broken
+        DLIB_ASSERT(is_vector(vector_to_matrix(list)) && list.size() > 0 && 
+                    is_col_vector(x) && radius > 0,
+            "\t double solve_least_squares_lm()"
+            << "\n\t invalid arguments were given to this function"
+            << "\n\t is_vector(list):  " << is_vector(vector_to_matrix(list)) 
+            << "\n\t list.size():      " << list.size() 
+            << "\n\t is_col_vector(x): " << is_col_vector(x) 
+            << "\n\t radius:           " << radius
+            );
+
         return find_min_trust_region(stop_strategy,
                                      least_squares_lm_model<T>(f, der, vector_to_matrix(list)), 
                                      x, 

dlib/optimization/optimization_least_squares_abstract.h

+// Copyright (C) 2010  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_OPTIMIZATIOn_LEAST_SQUARES_ABSTRACT_
+#ifdef DLIB_OPTIMIZATIOn_LEAST_SQUARES_ABSTRACT_
+
+#include "../matrix/matrix_abstract.h"
+#include "optimization_trust_region_abstract.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename stop_strategy_type,
+        typename funct_type,
+        typename funct_der_type,
+        typename vector_type,
+        typename T
+        >
+    double solve_least_squares (
+        stop_strategy_type stop_strategy,
+        const funct_type& f,
+        const funct_der_type& der,
+        const vector_type& list,
+        T& x, 
+        double radius = 1
+    );
+    /*!
+        requires
+            - stop_strategy == an object that defines a stop strategy such as one of 
+              the objects from dlib/optimization/optimization_stop_strategies_abstract.h
+            - list == a matrix or something convertible to a matrix via vector_to_matrix()
+              such as a std::vector.
+            - is_vector(list) == true
+            - list.size() > 0
+            - is_col_vector(x) == true
+            - radius > 0
+            - for all valid i:
+                - f(list(i),x) must be a valid expression that evaluates to a floating point value.
+                - der(list(i),x) must be a valid expression that evaluates to the derivative of f(list(i),x) 
+                  with respect to x. This derivative must take the form of a column vector.
+        ensures
+            - This function performs an unconstrained minimization of the least squares
+              function g(x) defined by:
+                - g(x) = sum over all i: 0.5*pow( f(list(i),x), 2 )
+            - This method combines the Levenberg–Marquardt method with a quasi-newton method
+              for approximating the second order terms of the hessian and is appropriate for
+              large residual problems (i.e. problems where the f() function isn't driven to 0).  
+              In particular, it uses the method of Dennis, Gay, and Welsch as described in 
+              Numerical Optimization by Nocedal and Wright (second edition).
+            - Since this is a trust region algorithm, the radius parameter defines the initial 
+              size of the trust region.  
+            - The function is optimized until stop_strategy decides that an acceptable 
+              point has been found or the trust region subproblem fails to make progress.
+            - #x == the value of x that was found to minimize g()
+            - returns g(#x). 
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename stop_strategy_type,
+        typename funct_type,
+        typename funct_der_type,
+        typename vector_type,
+        typename T
+        >
+    double solve_least_squares_lm (
+        stop_strategy_type stop_strategy,
+        const funct_type& f,
+        const funct_der_type& der,
+        const vector_type& list,
+        T& x, 
+        double radius = 1
+    );
+    /*!
+        requires
+            - stop_strategy == an object that defines a stop strategy such as one of 
+              the objects from dlib/optimization/optimization_stop_strategies_abstract.h
+            - list == a matrix or something convertible to a matrix via vector_to_matrix()
+              such as a std::vector.
+            - is_vector(list) == true
+            - list.size() > 0
+            - is_col_vector(x) == true
+            - radius > 0
+            - for all valid i:
+                - f(list(i),x) must be a valid expression that evaluates to a floating point value.
+                - der(list(i),x) must be a valid expression that evaluates to the derivative of f(list(i),x) 
+                  with respect to x.  This derivative must take the form of a column vector.
+        ensures
+            - This function performs an unconstrained minimization of the least squares
+              function g(x) defined by:
+                - g(x) = sum over all i: 0.5*pow( f(list(i),x), 2 )
+            - This method implements a plain Levenberg–Marquardt approach for approximating
+              the hessian of g().  Therefore, it is most appropriate for small residual problems
+              (i.e. problems where f() goes to 0 at the solution).
+            - Since this is a trust region algorithm, the radius parameter defines the initial 
+              size of the trust region.  
+            - The function is optimized until stop_strategy decides that an acceptable 
+              point has been found or the trust region subproblem fails to make progress.
+            - #x == the value of x that was found to minimize g()
+            - returns g(#x). 
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_OPTIMIZATIOn_LEAST_SQUARES_ABSTRACT_
+
+