view release on metacpan or  search on metacpan

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

want to pass to both L</"evaluation_cb"> and L</"progress_cb">.

Client program can use L</"get_status"> to find if any problem occured
during the optimization after their calling L</"fmin">. When the status is 
L</"LBFGS_OK">, the returning value C<x> (array ref) contains the optimized
variables, otherwise, there may be some problems occured and the value in
the returning C<x> is undefined.

=head3 evaluation_cb

The ref to the evaluation callback subroutine. 

The evaluation callback subroutine is supposed to calculate the function
value and gradient vector at a specified point C<x>. It is called
automatically by L</"fmin"> when an evaluation is needed.

The client program need to make sure their evaluation callback subroutine
has a prototype like

  (f, g) = evaluation_cb(x, step, user_data)

C<x> (array ref) is the current values of variables, C<step> is the
current step of the line search routine, L</"user_data"> is the extra user 
data specified when calling L</"fmin">. 

The evaluation callback subroutine is supposed to return both the function
value C<f> and the gradient vector C<g> (array ref) at current C<x>.

=head3 x0

The initial point of the optimization algorithm.
The final result may depend on your choice of C<x0>.

NOTE: The content of C<x0> will be modified after calling L</"fmin">.
When the algorithm terminates successfully, the content of C<x0> will be 
replaced by the optimized variables, otherwise, the content of C<x0> is
undefined.


=head3 progress_cb

The ref to the progress callback subroutine.

The progress callback subroutine is called by L</"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. 

The client program need to make sure their progress callback subroutine
has a prototype like

  s = progress_cb(x, g, fx, xnorm, gnorm, step, k, ls, user_data)

C<x> (array ref) is the current values of variables. C<g> (array ref) is the
current gradient vector. C<fx> is the current function value. C<xnorm>
and C<gnorm> is the L2 norm of C<x> and C<g>. C<step> is the line-search
step used for this iteration. C<k> is the iteration count. C<ls> is the
number of evaluations in this iteration. L</"user_data"> is the extra
user data specified when calling L</"fmin">. 

The progress callback subroutine is supposed to return an indicating value
C<s> for L</"fmin"> to decide whether the optimization should continue or
stop. C<fmin> continues to the next iteration when C<s=0>, otherwise, it
terminates with status code L</"LBFGSERR_CANCELED">.

The client program can also pass string values to L</"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 L</"user_data">.

  ...

  # print out the iterations
  fmin($eval_cb, $x0, 'verbose'); 

  # log iterations information in the array ref $log
  my $log = [];

  fmin($eval_cb, $x0, 'logging', $log);
  
  use Data::Dumper;
  print Dumper $log;


=head3 user_data

The extra user data. It will be sent to both L</"evaluation_cb"> and
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