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 Limitedmemory BroydenFletcherGoldfarbShanno (LBFGS) method written by Jorge Nocedal.
The LBFGS 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 linesearch 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 linesearch 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 deltabased 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 ofLBFGS_LINESEARCH_DEFAULT
,LBFGS_LINESEARCH_MORETHUENTE
,LBFGS_LINESEARCH_BACKTRACKING_ARMIJO
,LBFGS_LINESEARCH_BACKTRACKING
,LBFGS_LINESEARCH_BACKTRACKING_WOLFE
andLBFGS_LINESEARCH_BACKTRACKING_STRONG_WOLFE
. The default value isLBFGS_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 floatingpoint 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
Copyright 2016 titsuki
Copyright 1990 Jorge Nocedal
Copyright 20072010 Naoki Okazaki
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.