Improved documentations

git-svn-id: file:///home/svnrepos/software/liblbfgs/trunk@59 ecf4c44f-38d1-4fa4-9757-a0b4dd0349fc

include/lbfgs.h

@@ -107,6 +107,8 @@ enum {
     LBFGSERR_INVALID_MAXSTEP,
     /** Invalid parameter lbfgs_parameter_t::ftol specified. */
     LBFGSERR_INVALID_FTOL,
+    /** Invalid parameter lbfgs_parameter_t::wolfe specified. */
+    LBFGSERR_INVALID_WOLFE,
     /** Invalid parameter lbfgs_parameter_t::gtol specified. */
     LBFGSERR_INVALID_GTOL,
     /** Invalid parameter lbfgs_parameter_t::xtol specified. */
@@ -152,13 +154,36 @@ enum {
     LBFGS_LINESEARCH_DEFAULT = 0,
     /** MoreThuente method proposd by More and Thuente. */
     LBFGS_LINESEARCH_MORETHUENTE = 0,
-    /** Backtracking method with strong Wolfe condition. */
+    /**
-    LBFGS_LINESEARCH_BACKTRACKING_STRONG_WOLFE = 1,
+     * Backtracking method with the Armijo condition:
-    /** Backtracking method with regular Wolfe condition. */
+     *  The backtracking method finds the step length such that it satisfies
-    LBFGS_LINESEARCH_BACKTRACKING = 2,
+     *  the sufficient decrease (Armijo) condition,
+     *      f(x + a * d) <= f(x) + lbfgs_parameter_t::ftol * a * g(x) \cdot d,
+     *  where x is the current point, d is the current search direction, and
+     *  a is the step length.
+     */
+    LBFGS_LINESEARCH_BACKTRACKING_ARMIJO = 1,
+    LBFGS_LINESEARCH_BACKTRACKING = 1,
+    /**
+     * Backtracking method with regular Wolfe condition.
+     *  The backtracking method finds the step length such that it satisfies
+     *  both the Armijo condition (LBFGS_LINESEARCH_BACKTRACKING_ARMIJO)
+     *  and the curvature condition,
+     *      g(x + a * d) \cdot d >= lbfgs_parameter_t::wolfe * g(x) \cdot d,
+     *  where x is the current point, d is the current search direction, and
+     *  a is the step length.
+     */
     LBFGS_LINESEARCH_BACKTRACKING_WOLFE = 2,
-    /** Backtracking method with Armijo condition. */
+    /**
-    LBFGS_LINESEARCH_BACKTRACKING_ARMIJO = 3,
+     * Backtracking method with strong Wolfe condition.
+     *  The backtracking method finds the step length such that it satisfies
+     *  both the Armijo condition (LBFGS_LINESEARCH_BACKTRACKING_ARMIJO)
+     *  and the following condition,
+     *      |g(x + a * d) \cdot d| <= lbfgs_parameter_t::wolfe * |g(x) \cdot d|,
+     *  where x is the current point, d is the current search direction, and
+     *  a is the step length.
+     */
+    LBFGS_LINESEARCH_BACKTRACKING_STRONG_WOLFE = 3,
 };
 
 /**
@@ -257,6 +282,17 @@ typedef struct {
      */
     lbfgsfloatval_t ftol;
 
+    /**
+     * A coefficient for the Wolfe condition.
+     *  This parameter is valid only when the backtracking line-search
+     *  algorithm is used with the Wolfe condition,
+     *  ::LBFGS_LINESEARCH_BACKTRACKING_STRONG_WOLFE or
+     *  ::LBFGS_LINESEARCH_BACKTRACKING_WOLFE .
+     *  The default value is \c 0.9. This parameter should be greater
+     *  the \ref ftol parameter and smaller than \c 1.0.
+     */
+    lbfgsfloatval_t wolfe;
+
     /**
      * A parameter to control the accuracy of the line search routine.
      *  The default value is \c 0.9. If the function and gradient
@@ -557,6 +593,15 @@ libLBFGS is distributed under the term of the
 <a href="http://opensource.org/licenses/mit-license.php">MIT license</a>.
 
 @section changelog History
+- Version 1.8 (2009-07-13):
+    - The backtracking method now has three criteria for choosing the step
+      length:
+        - ::LBFGS_LINESEARCH_BACKTRACKING_ARMIJO: sufficient decrease condition
+          (Armijo condition)
+        - ::LBFGS_LINESEARCH_BACKTRACKING_WOLFE: regular Wolfe condition
+          (sufficient decrease condition + curvature condition)
+        - ::LBFGS_LINESEARCH_BACKTRACKING_STRONG_WOLFE: strong Wolfe condition
+      This is based on the patch submitted by Takashi Imamichi.
 - Version 1.7 (2009-02-28):
     - Improved OWL-QN routines for stability.
     - Removed the support of OWL-QN method in MoreThuente algorithm because

lib/lbfgs.c

@@ -113,7 +113,7 @@ typedef struct tag_iteration_data iteration_data_t;
 static const lbfgs_parameter_t _defparam = {
     6, 1e-5, 0, 1e-5,
     0, LBFGS_LINESEARCH_DEFAULT, 40,
-    1e-20, 1e20, 1e-4, 0.9, 1.0e-16,
+    1e-20, 1e20, 1e-4, 0.9, 0.9, 1.0e-16,
     0.0, 0, -1,
 };
 
@@ -312,6 +312,12 @@ int lbfgs(
     if (param.ftol < 0.) {
         return LBFGSERR_INVALID_FTOL;
     }
+    if (param.linesearch == LBFGS_LINESEARCH_BACKTRACKING_WOLFE &&
+        param.linesearch == LBFGS_LINESEARCH_BACKTRACKING_STRONG_WOLFE) {
+        if (param.wolfe <= param.ftol || 1. <= param.wolfe) {
+            return LBFGSERR_INVALID_WOLFE;
+        }
+    }
     if (param.gtol < 0.) {
         return LBFGSERR_INVALID_GTOL;
     }
@@ -653,7 +659,7 @@ static int line_search_backtracking(
     int ret = 0, count = 0;
     lbfgsfloatval_t width, dg, norm = 0.;
     lbfgsfloatval_t finit, dginit = 0., dgtest;
-    const lbfgsfloatval_t wolfe = 0.9, dec = 0.5, inc = 2.1;
+    const lbfgsfloatval_t dec = 0.5, inc = 2.1;
 
     /* Check the input parameters for errors. */
     if (*stp <= 0.) {
@@ -692,7 +698,7 @@ static int line_search_backtracking(
 
 	        /* Check the Wolfe condition. */
 	        vecdot(&dg, g, s, n);
-	        if (dg < wolfe * dginit) {
+	        if (dg < param->wolfe * dginit) {
     		    width = inc;
 	        } else {
 		        if(param->linesearch == LBFGS_LINESEARCH_BACKTRACKING_WOLFE) {
@@ -701,7 +707,7 @@ static int line_search_backtracking(
 		        }
 
 		        /* Check the strong Wolfe condition. */
-		        if(dg > -wolfe * dginit) {
+		        if(dg > -param->wolfe * dginit) {
 		            width = dec;
 		        } else {
 		            /* Exit with the strong Wolfe condition. */