Updated documentation for 1.5 release.

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

include/lbfgs.h

@@ -68,13 +68,13 @@ typedef double lbfgsfloatval_t;
 
 /**
  * Return values of lbfgs().
+ * 
+ *  Roughly speaking, a negative value indicates an error.
  */
 enum {
-    /** False value. */
+    /** L-BFGS reaches convergence. */
-    LBFGSFALSE = 0,
+    LBFGS_SUCCESS = 0,
-    /** True value. */
+    /** The initial variables already minimize the objective function. */
-    LBFGSTRUE,
-    /** */
     LBFGS_ALREADY_MINIMIZED,
 
     /** Unknown error. */
@@ -245,16 +245,30 @@ typedef struct {
     /**
      * Coeefficient for the L1 norm of variables.
      *  This parameter should be set to zero for standard minimization
-     *  problems. Setting this parameter to a positive value minimizes the
+     *  problems. Setting this parameter to a positive value activates
-     *  objective function F(x) combined with the L1 norm |x| of the variables,
+     *  Orthant-Wise Limited-memory Quasi-Newton (OWL-QN) method, which
-     *  {F(x) + C |x|}. This parameter is the coeefficient for the |x|, i.e.,
+     *  minimizes the objective function F(x) combined with the L1 norm |x|
-     *  C. As the L1 norm |x| is not differentiable at zero, the library
+     *  of the variables, {F(x) + C |x|}. This parameter is the coeefficient
-     *  modify function and gradient evaluations from a client program
+     *  for the |x|, i.e., C. As the L1 norm |x| is not differentiable at
-     *  suitably; a client program thus have only to return the function value
+     *  zero, the library modifies function and gradient evaluations from
-     *  F(x) and gradients G(x) as usual. The default value is zero.
+     *  a client program suitably; a client program thus have only to return
+     *  the function value F(x) and gradients G(x) as usual. The default value
+     *  is zero.
      */
     lbfgsfloatval_t orthantwise_c;
 
+    /**
+     * Start index for computing L1 norm of the variables.
+     *  This parameter is valid only for OWL-QN method
+     *  (i.e., \ref orthantwise_c != 0). This parameter b (0 <= b < N)
+     *  specifies the index number from which the library computes the
+     *  L1 norm of the variables x,
+     *      |x| := |x_{b} + x_{b+1} + ... + x_{N}|
+     *  In other words, variables x_1, ..., x_{b-1} are not used for
+     *  computing the L1 norm. Setting b (0 < b < N), one can protect
+     *  variables, x_1, ..., x_{b-1} (e.g., a bias term of logistic
+     *  regression) from being regularized. The default value is zero.
+     */
     int             orthantwise_start;
 } lbfgs_parameter_t;
 
@@ -486,15 +500,29 @@ Among the various ports of L-BFGS, this library provides several features:
 This library is used by:
 - <a href="http://www.chokkan.org/software/crfsuite/">CRFsuite: A fast implementation of Conditional Random Fields (CRFs)</a>
 - <a href="http://www.public.iastate.edu/~gdancik/mlegp/">mlegp: an R package for maximum likelihood estimates for Gaussian processes</a>
+- <a href="http://infmath.uibk.ac.at/~matthiasf/imaging2/">imaging2: the imaging2 class library</a>
+- <a href="http://search.cpan.org/~laye/Algorithm-LBFGS-0.16/">Algorithm::LBFGS - Perl extension for L-BFGS</a>
 
 @section download Download
 
-- <a href="http://www.chokkan.org/software/dist/liblbfgs-1.4.tar.gz">Source code</a>
+- <a href="http://www.chokkan.org/software/dist/liblbfgs-1.5.tar.gz">Source code</a>
 
 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.5 (2008-07-09):
+    - Configurable starting index for L1-norm computation. A member variable
+      ::lbfgs_parameter_t::orthantwise_start was added to specify the index
+      number from which the library computes the L1 norm of the variables.
+      This is useful to prevent some variables from being regularized by the
+      OW-LQN method.
+    - Fixed a zero-division error when the initial variables have already
+      been a minimizer (reported by Takashi Imamichi). In this case, the
+      library returns ::LBFGS_ALREADY_MINIMIZED status code.
+    - Defined ::LBFGS_SUCCESS status code as zero; removed unused constants,
+      LBFGSFALSE and LBFGSTRUE.
+    - Fixed a compile error in an implicit down-cast.
 - Version 1.4 (2008-04-25):
     - Configurable line search algorithms. A member variable
       ::lbfgs_parameter_t::linesearch was added to choose either MoreThuente

lib/lbfgs.c

@@ -401,7 +401,7 @@ int lbfgs(
         if (xnorm < 1.0) xnorm = 1.0;
         if (gnorm / xnorm <= param->epsilon) {
             /* Convergence. */
-            ret = 0;
+            ret = LBFGS_SUCCESS;
             break;
         }