Help language development. Donate to The Perl Foundation

## Algorithm::LBFGS cpan:TITSUKI last updated on 2020-11-07

Algorithm-LBFGS-0.0.6/

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

TBD

# AUTHOR

titsuki [email protected]

Copyright 1990 Jorge Nocedal

Copyright 2007-2010 Naoki Okazaki

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