diff --git a/include/lbfgs.h b/include/lbfgs.h index eeb6f02..b992ac9 100644 --- a/include/lbfgs.h +++ b/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. */ - LBFGSFALSE = 0, - /** True value. */ - LBFGSTRUE, - /** */ + /** L-BFGS reaches convergence. */ + LBFGS_SUCCESS = 0, + /** The initial variables already minimize the objective function. */ 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 - * objective function F(x) combined with the L1 norm |x| of the variables, - * {F(x) + C |x|}. This parameter is the coeefficient for the |x|, i.e., - * C. As the L1 norm |x| is not differentiable at zero, the library - * modify function and gradient evaluations from 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. + * problems. Setting this parameter to a positive value activates + * Orthant-Wise Limited-memory Quasi-Newton (OWL-QN) method, which + * minimizes the objective function F(x) combined with the L1 norm |x| + * of the variables, {F(x) + C |x|}. This parameter is the coeefficient + * for the |x|, i.e., C. As the L1 norm |x| is not differentiable at + * zero, the library modifies function and gradient evaluations from + * 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: - CRFsuite: A fast implementation of Conditional Random Fields (CRFs) - mlegp: an R package for maximum likelihood estimates for Gaussian processes +- imaging2: the imaging2 class library +- Algorithm::LBFGS - Perl extension for L-BFGS @section download Download -- Source code +- Source code libLBFGS is distributed under the term of the MIT license. @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 diff --git a/lib/lbfgs.c b/lib/lbfgs.c index 27af73c..5524dbf 100644 --- a/lib/lbfgs.c +++ b/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; }