NAME

Algorithm::LBFGS - A Raku bindings for libLBFGS

SYNOPSIS

use Algorithm::LBFGS;
use Algorithm::LBFGS::Parameter;

my Algorithm::LBFGS $lbfgs .= new;
my &evaluate = sub ($instance, $x, $g, $n, $step --> Num) {
   my Num $fx = ($x[0] - 2.0) ** 2 + ($x[1] - 5.0) ** 2;
   $g[0] = 2.0 * $x[0] - 4.0;
   $g[1] = 2.0 * $x[1] - 10.0;
   return $fx;
};
my Algorithm::LBFGS::Parameter $parameter .= new;
my Num @x0 = [0e0, 0e0];
my @x = $lbfgs.minimize(:@x0, :&evaluate, :$parameter);
@x.say; # [2e0, 5e0]

DESCRIPTION

Algorithm::LBFGS is a Raku bindings for libLBFGS. libLBFGS is a C port of the implementation of Limited-memory Broyden-Fletcher-Goldfarb-Shanno (L-BFGS) method written by Jorge Nocedal.

The L-BFGS method solves the unconstrainted minimization problem,

minimize F(x), x = (x1, x2, ..., xN),

only if the objective function F(x) and its gradient G(x) are computable.

CONSTRUCTOR

my $lbfgs = Algorithm::LBFGS.new;
my Algorithm::LBFGS $lbfgs .= new; # with type restrictions

METHODS

minimize(:@x0!, :&evaluate!, :&progress, Algorithm::LBFGS::Parameter :$parameter!) returns Array

my @x = $lbfgs.minimize(:@x0!, :&evaluate, :&progress, :$parameter); # use &progress callback
my @x = $lbfgs.minimize(:@x0!, :&evaluate, :$parameter);

Runs the optimization and returns the resulting variables.

:@x0 is the initial value of the variables.

:&evaluate is the callback function. This requires the definition of the objective function F(x) and its gradient G(x).

:&progress is the callback function. This gets called on every iteration and can output the internal state of the current iteration.

:$parameter is the instance of the Algorithm::LBFGS::Parameter class.

:&evaluate

The one of the simplest &evaluate callback function would be like the following:

my &evaluate = sub ($instance, $x, $g, $n, $step --> Num) {
   my Num $fx = ($x[0] - 2.0) ** 2 + ($x[1] - 5.0) ** 2; # F(x) = (x0 - 2.0)^2 + (x1 - 5.0)^2

   # G(x) = [∂F(x)/∂x0, ∂F(x)/∂x1]
   $g[0] = 2.0 * $x[0] - 4.0; # ∂F(x)/∂x0 = 2.0 * x0 - 4.0
   $g[1] = 2.0 * $x[1] - 10.0; # ∂F(x)/∂x1 = 2.0 * x1 - 10.0
   return $fx;
};

$instance is the user data. (NOTE: NYI in this binder. You must set it as a first argument, but you can't use it in the callback.)
$x is the current values of variables.
$g is the current gradient values of variables.
$n is the number of variables.
$step is the line-search step used for this iteration.

&evaluate requires all of these five arguments in this order.

After writing the definition of the objective function F(x) and its gradient G(x), it requires returning the value of the F(x).

:&progress

The one of the simplest &progress callback function would be like the following:

my &progress = sub ($instance, $x, $g, $fx, $xnorm, $gnorm, $step, $n, $k, $ls --> Int) {
    "Iteration $k".say;
    "fx = $fx, x[0] = $x[0], x[1] = $x[1]".say;
    return 0;
}

$instance is the user data. (NOTE: NYI in this binder. You must set it as a first argument, but you can't use it in the callback.)
$x is the current values of variables.
$g is the current gradient values of variables.
$fx is the current value of the objective function.
$xnorm is the Euclidean norm of the variables.
$gnorm is the Euclidean norm of the gradients.
$step is the line-search step used for this iteration.
$n is the number of variables.
$k is the iteration count.
$ls the number of evaluations called for this iteration.

&progress requires all of these ten arguments in this order.

Algorithm::LBFGS::Parameter :$parameter

Below is the examples of creating a Algorithm::LBFGS::Parameter instance:

my Algorithm::LBFGS::Parameter $parameter .= new; # sets default parameter
my Algorithm::LBFGS::Parameter $parameter .= new(max_iterations => 100); # sets max_iterations => 100

OPTIONS

Int m is the number of corrections to approximate the inverse hessian matrix.
Num epsilon is epsilon for convergence test.
Int past is the distance for delta-based convergence test.
Num delta is delta for convergence test.
Int max_iterations is the maximum number of iterations.
Int linesearch is the line search algorithm. This requires one of LBFGS_LINESEARCH_DEFAULT, LBFGS_LINESEARCH_MORETHUENTE, LBFGS_LINESEARCH_BACKTRACKING_ARMIJO, LBFGS_LINESEARCH_BACKTRACKING, LBFGS_LINESEARCH_BACKTRACKING_WOLFE and LBFGS_LINESEARCH_BACKTRACKING_STRONG_WOLFE. The default value is LBFGS_LINESEARCH_MORETHUENTE.
Int max_linesearch is the maximum number of trials for the line search.
Num min_step is the minimum step of the line search routine.
Num max_step is the maximum step of the line search.
Num ftol is a parameter to control the accuracy of the line search routine.
Num wolfe is a coefficient for the Wolfe condition.
Num gtol is a parameter to control the accuracy of the line search routine.
Num xtol is the machine precision for floating-point values.
Num orthantwise_c is a coeefficient for the L1 norm of variables.
Int orthantwise_start is the start index for computing L1 norm of the variables.
Int orthantwise_end is the end index for computing L1 norm of the variables.

STATUS CODES

TBD

AUTHOR

titsuki titsuki@cpan.org

COPYRIGHT AND LICENSE

libLBFGS by Naoki Okazaki is licensed under the MIT License.

This library is free software; you can redistribute it and/or modify it under the terms of the MIT License.