.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Algorithm::LBFGS 3pm"
.TH Algorithm::LBFGS 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Algorithm::LBFGS \- Perl extension for L\-BFGS
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Algorithm::LBFGS;
\&
\&  # create an L\-BFGS optimizer
\&  my $o = Algorithm::LBFGS\->new;
\&
\&  # f(x) = (x1 \- 1)^2 + (x2 + 2)^2
\&  # grad f(x) = (2 * (x1 \- 1), 2 * (x2 + 2));
\&  my $eval_cb = sub {
\&      my $x = shift;
\&      my $f = ($x\->[0] \- 1) * ($x\->[0] \- 1) + ($x\->[1] + 2) * ($x\->[1] + 2);
\&      my $g = [ 2 * ($x\->[0] \- 1), 2 * ($x\->[1] + 2) ];
\&      return ($f, $g);
\&  };
\&
\&  my $x0 = [0.0, 0.0]; # initial point
\&  my $x = $o\->fmin($eval_cb, $x0); # $x is supposed to be [ 1, \-2 ];
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
L\-BFGS (Limited-memory Broyden-Fletcher-Goldfarb-Shanno) is a quasi-Newton
method for unconstrained optimization. This method is especially efficient 
on problems involving a large number of variables.
.PP
Generally, it solves a problem described as following:
.PP
.Vb 1
\&  min f(x), x = (x1, x2, ..., xn)
.Ve
.PP
Jorge Nocedal wrote a Fortran 77 version of this algorithm.
.PP
<http://www.ece.northwestern.edu/~nocedal/lbfgs.html>
.PP
And, Naoaki Okazaki rewrote it in pure C (liblbfgs).
.PP
<http://www.chokkan.org/software/liblbfgs/index.html>
.PP
This module is a Perl port of Naoaki Okazaki's C version.
.SS new
.IX Subsection "new"
\&\f(CW\*(C`new\*(C'\fR creates a L\-BFGS optimizer with given parameters.
.PP
.Vb 3
\&  my $o1 = new Algorithm::LBFGS(m => 5);
\&  my $o2 = new Algorithm::LBFGS(m => 3, eps => 1e\-6);
\&  my $o3 = new Algorithm::LBFGS;
.Ve
.PP
If no parameter is specified explicitly, their default values are used.
.PP
The parameter can be changed after the creation of the optimizer by 
"set_param". Also, they can be queryed by "get_param".
.PP
Please refer to the "List of Parameters" for details about parameters.
.SS get_param
.IX Subsection "get_param"
Query the value of a parameter.
.PP
.Vb 2
\&   my $o = Algorithm::LBFGS\->new;
\&   print $o\->get_param(\*(Aqepsilon\*(Aq); # 1e\-5
.Ve
.SS set_param
.IX Subsection "set_param"
Change the values of one or several parameters.
.PP
.Vb 2
\&   my $o = Algorithm::LBFGS\->new;
\&   $o\->set_param(epsilon => 1e\-6, m => 7);
.Ve
.SS fmin
.IX Subsection "fmin"
The prototype of "fmin" is like
.PP
.Vb 1
\&  x = fmin(evaluation_cb, x0, progress_cb, user_data)
.Ve
.PP
As the name says, it finds a vector x which minimize the function f(x).
.PP
"evaluation_cb" is a ref to the evaluation callback subroutine, 
"x0" is the initial point of the optimization algorithm,
"progress_cb" (optional) is a ref to the progress callback subroutine,
and "user_data" (optional) is a piece of extra data that client program
want to pass to both "evaluation_cb" and "progress_cb".
.PP
Client program can use "get_status" to find if any problem occured
during the optimization after their calling "fmin". When the status is 
"LBFGS_OK", the returning value \f(CW\*(C`x\*(C'\fR (array ref) contains the optimized
variables, otherwise, there may be some problems occured and the value in
the returning \f(CW\*(C`x\*(C'\fR is undefined.
.PP
\fIevaluation_cb\fR
.IX Subsection "evaluation_cb"
.PP
The ref to the evaluation callback subroutine.
.PP
The evaluation callback subroutine is supposed to calculate the function
value and gradient vector at a specified point \f(CW\*(C`x\*(C'\fR. It is called
automatically by "fmin" when an evaluation is needed.
.PP
The client program need to make sure their evaluation callback subroutine
has a prototype like
.PP
.Vb 1
\&  (f, g) = evaluation_cb(x, step, user_data)
.Ve
.PP
\&\f(CW\*(C`x\*(C'\fR (array ref) is the current values of variables, \f(CW\*(C`step\*(C'\fR is the
current step of the line search routine, "user_data" is the extra user 
data specified when calling "fmin".
.PP
The evaluation callback subroutine is supposed to return both the function
value \f(CW\*(C`f\*(C'\fR and the gradient vector \f(CW\*(C`g\*(C'\fR (array ref) at current \f(CW\*(C`x\*(C'\fR.
.PP
\fIx0\fR
.IX Subsection "x0"
.PP
The initial point of the optimization algorithm.
The final result may depend on your choice of \f(CW\*(C`x0\*(C'\fR.
.PP
NOTE: The content of \f(CW\*(C`x0\*(C'\fR will be modified after calling "fmin".
When the algorithm terminates successfully, the content of \f(CW\*(C`x0\*(C'\fR will be 
replaced by the optimized variables, otherwise, the content of \f(CW\*(C`x0\*(C'\fR is
undefined.
.PP
\fIprogress_cb\fR
.IX Subsection "progress_cb"
.PP
The ref to the progress callback subroutine.
.PP
The progress callback subroutine is called by "fmin" at the end of each
iteration, with information of current iteration. It is very useful for a
client program to monitor the optimization progress.
.PP
The client program need to make sure their progress callback subroutine
has a prototype like
.PP
.Vb 1
\&  s = progress_cb(x, g, fx, xnorm, gnorm, step, k, ls, user_data)
.Ve
.PP
\&\f(CW\*(C`x\*(C'\fR (array ref) is the current values of variables. \f(CW\*(C`g\*(C'\fR (array ref) is the
current gradient vector. \f(CW\*(C`fx\*(C'\fR is the current function value. \f(CW\*(C`xnorm\*(C'\fR
and \f(CW\*(C`gnorm\*(C'\fR is the L2 norm of \f(CW\*(C`x\*(C'\fR and \f(CW\*(C`g\*(C'\fR. \f(CW\*(C`step\*(C'\fR is the line-search
step used for this iteration. \f(CW\*(C`k\*(C'\fR is the iteration count. \f(CW\*(C`ls\*(C'\fR is the
number of evaluations in this iteration. "user_data" is the extra
user data specified when calling "fmin".
.PP
The progress callback subroutine is supposed to return an indicating value
\&\f(CW\*(C`s\*(C'\fR for "fmin" to decide whether the optimization should continue or
stop. \f(CW\*(C`fmin\*(C'\fR continues to the next iteration when \f(CW\*(C`s=0\*(C'\fR, otherwise, it
terminates with status code "LBFGSERR_CANCELED".
.PP
The client program can also pass string values to "progress_cb", which
means it want to use a predefined progress callback subroutine. There are
two predefined progress callback subroutines, 'verbose' and 'logging'.
\&'verbose' just prints out all information of each iteration, while 'logging'
logs the same information in an array ref provided by "user_data".
.PP
.Vb 1
\&  ...
\&
\&  # print out the iterations
\&  fmin($eval_cb, $x0, \*(Aqverbose\*(Aq); 
\&
\&  # log iterations information in the array ref $log
\&  my $log = [];
\&
\&  fmin($eval_cb, $x0, \*(Aqlogging\*(Aq, $log);
\&  
\&  use Data::Dumper;
\&  print Dumper $log;
.Ve
.PP
\fIuser_data\fR
.IX Subsection "user_data"
.PP
The extra user data. It will be sent to both "evaluation_cb" and
"progress_cb".
.SS get_status
.IX Subsection "get_status"
Get the status of previous call of "fmin".
.PP
.Vb 2
\&  ...
\&  $o\->fmin(...);
\&
\&  # check the status
\&  if ($o\->get_status eq \*(AqLBFGS_OK\*(Aq) {
\&     ...
\&  }
\&
\&  # print the status out
\&  print $o\->get_status;
.Ve
.PP
The status code is a string, which could be one of those in the
"List of Status Codes".
.SS status_ok
.IX Subsection "status_ok"
This is a shortcut of saying "get_status" eq "LBFGS_OK".
.PP
.Vb 1
\&  ...
\&
\&  if ($o\->fmin(...), $o\->status_ok) {
\&      ...
\&  }
.Ve
.SS "List of Parameters"
.IX Subsection "List of Parameters"
\fIm\fR
.IX Subsection "m"
.PP
The number of corrections to approximate the inverse hessian matrix.
.PP
The L\-BFGS algorithm stores the computation results of previous "m"
iterations to approximate the inverse hessian matrix of the current
iteration. This parameter controls the size of the limited memories
(corrections). The default value is 6. Values less than 3 are not
recommended. Large values will result in excessive computing time.
.PP
\fIepsilon\fR
.IX Subsection "epsilon"
.PP
Epsilon for convergence test.
.PP
This parameter determines the accuracy with which the solution is to be
found. A minimization terminates when
.PP
.Vb 1
\&  ||grad f(x)|| < epsilon * max(1, ||x||)
.Ve
.PP
where ||.|| denotes the Euclidean (L2) norm. The default value is 1e\-5.
.PP
\fImax_iterations\fR
.IX Subsection "max_iterations"
.PP
The maximum number of iterations.
.PP
The L\-BFGS algorithm terminates an optimization process with
"LBFGSERR_MAXIMUMITERATION" status code when the iteration count
exceedes this parameter. Setting this parameter to zero continues an
optimization process until a convergence or error. The default value is 0.
.PP
\fImax_linesearch\fR
.IX Subsection "max_linesearch"
.PP
The maximum number of trials for the line search.
.PP
This parameter controls the number of function and gradients evaluations
per iteration for the line search routine. The default value is 20.
.PP
\fImin_step\fR
.IX Subsection "min_step"
.PP
The minimum step of the line search routine.
.PP
The default value is 1e\-20. This value need not be modified unless the
exponents are too large for the machine being used, or unless the problem
is extremely badly scaled (in which case the exponents should be increased).
.PP
\fImax_step\fR
.IX Subsection "max_step"
.PP
The maximum step of the line search.
.PP
The default value is 1e+20. This value need not be modified unless the
exponents are too large for the machine being used, or unless the problem
is extremely badly scaled (in which case the exponents should be increased).
.PP
\fIftol\fR
.IX Subsection "ftol"
.PP
A parameter to control the accuracy of the line search routine.
.PP
The default value is 1e\-4. This parameter should be greater than zero and
smaller than 0.5.
.PP
\fIgtol\fR
.IX Subsection "gtol"
.PP
A parameter to control the accuracy of the line search routine.
.PP
The default value is 0.9. If the function and gradient evaluations are
inexpensive with respect to the cost of the iteration (which is sometimes
the case when solving very large problems) it may be advantageous to set
this parameter to a small value. A typical small value is 0.1. This
parameter shuold be greater than the ftol parameter (1e\-4) and smaller than
1.0.
.PP
\fIxtol\fR
.IX Subsection "xtol"
.PP
The machine precision for floating-point values.
.PP
This parameter must be a positive value set by a client program to estimate
the machine precision. The line search routine will terminate with the
status code ("LBFGSERR_ROUNDING_ERROR") if the relative width of the
interval of uncertainty is less than this parameter.
.PP
\fIorthantwise_c\fR
.IX Subsection "orthantwise_c"
.PP
Coeefficient for the L1 norm of variables.
.PP
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 module 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 grad f(x) as
usual. The default value is zero.
.SS "List of Status Codes"
.IX Subsection "List of Status Codes"
\fILBFGS_OK\fR
.IX Subsection "LBFGS_OK"
.PP
No error occured.
.PP
\fILBFGSERR_UNKNOWNERROR\fR
.IX Subsection "LBFGSERR_UNKNOWNERROR"
.PP
Unknown error.
.PP
\fILBFGSERR_LOGICERROR\fR
.IX Subsection "LBFGSERR_LOGICERROR"
.PP
Logic error.
.PP
\fILBFGSERR_OUTOFMEMORY\fR
.IX Subsection "LBFGSERR_OUTOFMEMORY"
.PP
Insufficient memory.
.PP
\fILBFGSERR_CANCELED\fR
.IX Subsection "LBFGSERR_CANCELED"
.PP
The minimization process has been canceled.
.PP
\fILBFGSERR_INVALID_N\fR
.IX Subsection "LBFGSERR_INVALID_N"
.PP
Invalid number of variables specified.
.PP
\fILBFGSERR_INVALID_N_SSE\fR
.IX Subsection "LBFGSERR_INVALID_N_SSE"
.PP
Invalid number of variables (for SSE) specified.
.PP
\fILBFGSERR_INVALID_MINSTEP\fR
.IX Subsection "LBFGSERR_INVALID_MINSTEP"
.PP
Invalid parameter "max_step" specified.
.PP
\fILBFGSERR_INVALID_MAXSTEP\fR
.IX Subsection "LBFGSERR_INVALID_MAXSTEP"
.PP
Invalid parameter "max_step" specified.
.PP
\fILBFGSERR_INVALID_FTOL\fR
.IX Subsection "LBFGSERR_INVALID_FTOL"
.PP
Invalid parameter "ftol" specified.
.PP
\fILBFGSERR_INVALID_GTOL\fR
.IX Subsection "LBFGSERR_INVALID_GTOL"
.PP
Invalid parameter "gtol" specified.
.PP
\fILBFGSERR_INVALID_XTOL\fR
.IX Subsection "LBFGSERR_INVALID_XTOL"
.PP
Invalid parameter "xtol" specified.
.PP
\fILBFGSERR_INVALID_MAXLINESEARCH\fR
.IX Subsection "LBFGSERR_INVALID_MAXLINESEARCH"
.PP
Invalid parameter "max_linesearch" specified.
.PP
\fILBFGSERR_INVALID_ORTHANTWISE\fR
.IX Subsection "LBFGSERR_INVALID_ORTHANTWISE"
.PP
Invalid parameter "orthantwise_c" specified.
.PP
\fILBFGSERR_OUTOFINTERVAL\fR
.IX Subsection "LBFGSERR_OUTOFINTERVAL"
.PP
The line-search step went out of the interval of uncertainty.
.PP
\fILBFGSERR_INCORRECT_TMINMAX\fR
.IX Subsection "LBFGSERR_INCORRECT_TMINMAX"
.PP
A logic error occurred; alternatively, the interval of uncertainty became
too small.
.PP
\fILBFGSERR_ROUNDING_ERROR\fR
.IX Subsection "LBFGSERR_ROUNDING_ERROR"
.PP
A rounding error occurred; alternatively, no line-search step satisfies
the sufficient decrease and curvature conditions.
.PP
\fILBFGSERR_MINIMUMSTEP\fR
.IX Subsection "LBFGSERR_MINIMUMSTEP"
.PP
The line-search step became smaller than "min_step".
.PP
\fILBFGSERR_MAXIMUMSTEP\fR
.IX Subsection "LBFGSERR_MAXIMUMSTEP"
.PP
The line-search step became larger than "max_step".
.PP
\fILBFGSERR_MAXIMUMLINESEARCH\fR
.IX Subsection "LBFGSERR_MAXIMUMLINESEARCH"
.PP
The line-search routine reaches the maximum number of evaluations.
.PP
\fILBFGSERR_MAXIMUMITERATION\fR
.IX Subsection "LBFGSERR_MAXIMUMITERATION"
.PP
The algorithm routine reaches the maximum number of iterations.
.PP
\fILBFGSERR_WIDTHTOOSMALL\fR
.IX Subsection "LBFGSERR_WIDTHTOOSMALL"
.PP
Relative width of the interval of uncertainty is at most "xtol".
.PP
\fILBFGSERR_INVALIDPARAMETERS\fR
.IX Subsection "LBFGSERR_INVALIDPARAMETERS"
.PP
A logic error (negative line-search step) occurred.
.PP
\fILBFGSERR_INCREASEGRADIENT\fR
.IX Subsection "LBFGSERR_INCREASEGRADIENT"
.PP
The current search direction increases the objective function value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
PDL, PDL::Opt::NonLinear
.SH AUTHOR
.IX Header "AUTHOR"
Laye Suen, <laye@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 1990, Jorge Nocedal
.PP
Copyright (C) 2007, Naoaki Okazaki
.PP
Copyright (C) 2008, Laye Suen
.PP
This library is distributed under the term of the MIT license.
.PP
<http://opensource.org/licenses/mit\-license.php>
.SH REFERENCE
.IX Header "REFERENCE"
.IP " J. Nocedal. Updating Quasi-Newton Matrices with Limited Storage (1980) , Mathematics of Computation 35, pp. 773\-782." 4
.IX Item " J. Nocedal. Updating Quasi-Newton Matrices with Limited Storage (1980) , Mathematics of Computation 35, pp. 773-782."
.PD 0
.IP " D.C. Liu and J. Nocedal. On the Limited Memory Method for Large Scale Optimization (1989), Mathematical Programming B, 45, 3, pp. 503\-528." 4
.IX Item " D.C. Liu and J. Nocedal. On the Limited Memory Method for Large Scale Optimization (1989), Mathematical Programming B, 45, 3, pp. 503-528."
.IP " Jorge Nocedal's Fortran 77 implementation, <http://www.ece.northwestern.edu/~nocedal/lbfgs.html>" 4
.IX Item " Jorge Nocedal's Fortran 77 implementation, <http://www.ece.northwestern.edu/~nocedal/lbfgs.html>"
.IP " Naoaki Okazaki's C implementation (liblbfgs), <http://www.chokkan.org/software/liblbfgs/index.html>" 4
.IX Item " Naoaki Okazaki's C implementation (liblbfgs), <http://www.chokkan.org/software/liblbfgs/index.html>"