view release on metacpan or  search on metacpan

lib/Algorithm/LBFGS.pm  view on Meta::CPAN

L<"progress_cb">.

=head2 get_status

Get the status of previous call of L</"fmin">.

  ...
  $o->fmin(...);

  # check the status
  if ($o->get_status eq 'LBFGS_OK') {
     ...
  }

  # print the status out
  print $o->get_status;

The status code is a string, which could be one of those in the
L</"List of Status Codes">.

=head2 status_ok

This is a shortcut of saying L</"get_status"> eq L</"LBFGS_OK">.

  ...

  if ($o->fmin(...), $o->status_ok) {
      ...
  }

=head2 List of Parameters

=head3 m

The number of corrections to approximate the inverse hessian matrix.

The L-BFGS algorithm stores the computation results of previous L</"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. 

=head3 epsilon

Epsilon for convergence test.

This parameter determines the accuracy with which the solution is to be
found. A minimization terminates when
  
  ||grad f(x)|| < epsilon * max(1, ||x||)

where ||.|| denotes the Euclidean (L2) norm. The default value is 1e-5. 

=head3 max_iterations

The maximum number of iterations.

The L-BFGS algorithm terminates an optimization process with
L</"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. 

=head3 max_linesearch

The maximum number of trials for the line search.

This parameter controls the number of function and gradients evaluations
per iteration for the line search routine. The default value is 20. 

=head3 min_step

The minimum step of the line search routine.

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).

=head3 max_step

The maximum step of the line search.

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).

=head3 ftol

A parameter to control the accuracy of the line search routine.

The default value is 1e-4. This parameter should be greater than zero and
smaller than 0.5. 

=head3 gtol

A parameter to control the accuracy of the line search routine.

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. 

=head3 xtol

The machine precision for floating-point values.

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 (L</"LBFGSERR_ROUNDING_ERROR">) if the relative width of the
interval of uncertainty is less than this parameter. 

=head3 orthantwise_c

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 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. 

=head2 List of Status Codes

=head3 LBFGS_OK

No error occured.

=head3 LBFGSERR_UNKNOWNERROR

Unknown error.

=head3 LBFGSERR_LOGICERROR

Logic error.

=head3 LBFGSERR_OUTOFMEMORY

Insufficient memory.

=head3 LBFGSERR_CANCELED

The minimization process has been canceled.

=head3 LBFGSERR_INVALID_N

Invalid number of variables specified.

=head3 LBFGSERR_INVALID_N_SSE

Invalid number of variables (for SSE) specified.

=head3 LBFGSERR_INVALID_MINSTEP

Invalid parameter L</"max_step"> specified.

=head3 LBFGSERR_INVALID_MAXSTEP

Invalid parameter L</"max_step"> specified.

=head3 LBFGSERR_INVALID_FTOL

Invalid parameter L</"ftol"> specified.

=head3 LBFGSERR_INVALID_GTOL

Invalid parameter L</"gtol"> specified.

=head3 LBFGSERR_INVALID_XTOL

Invalid parameter L</"xtol"> specified.

=head3 LBFGSERR_INVALID_MAXLINESEARCH

Invalid parameter L</"max_linesearch"> specified.

=head3 LBFGSERR_INVALID_ORTHANTWISE

Invalid parameter L</"orthantwise_c"> specified.

=head3 LBFGSERR_OUTOFINTERVAL

The line-search step went out of the interval of uncertainty.

=head3 LBFGSERR_INCORRECT_TMINMAX

A logic error occurred; alternatively, the interval of uncertainty became
too small.

=head3 LBFGSERR_ROUNDING_ERROR

A rounding error occurred; alternatively, no line-search step satisfies
the sufficient decrease and curvature conditions.

=head3 LBFGSERR_MINIMUMSTEP

The line-search step became smaller than L</"min_step">.

=head3 LBFGSERR_MAXIMUMSTEP

The line-search step became larger than L</"max_step">.

=head3 LBFGSERR_MAXIMUMLINESEARCH

The line-search routine reaches the maximum number of evaluations.

=head3 LBFGSERR_MAXIMUMITERATION

The algorithm routine reaches the maximum number of iterations.

=head3 LBFGSERR_WIDTHTOOSMALL

Relative width of the interval of uncertainty is at most L</"xtol">.

=head3 LBFGSERR_INVALIDPARAMETERS

A logic error (negative line-search step) occurred.

=head3 LBFGSERR_INCREASEGRADIENT

The current search direction increases the objective function value. 

=head1 SEE ALSO

L<PDL>, L<PDL::Opt::NonLinear>

=head1 AUTHOR

Laye Suen, E<lt>laye@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 1990, Jorge Nocedal

Copyright (C) 2007, Naoaki Okazaki

Copyright (C) 2008, Laye Suen

This library is distributed under the term of the MIT license.

L<http://opensource.org/licenses/mit-license.php>

=head1 REFERENCE

=over

=item
J. Nocedal. Updating Quasi-Newton Matrices with Limited Storage (1980)
, Mathematics of Computation 35, pp. 773-782.

=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.

=item
Jorge Nocedal's Fortran 77 implementation,
L<http://www.ece.northwestern.edu/~nocedal/lbfgs.html>

=item
Naoaki Okazaki's C implementation (liblbfgs),
L<http://www.chokkan.org/software/liblbfgs/index.html>

=back

=cut