view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    the initial point of the optimization algorithm, "progress_cb"
    (optional) is a ref to the progress callback subroutine, and "user_data"
    (optional) is a piece of extra data that client program want to pass to
    both "evaluation_cb" and "progress_cb".

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

   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 "x". It is called
    automatically by "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)

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

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

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

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

   progress_cb
    The ref to the progress callback subroutine.

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

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

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

    The client program can also pass string values to "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
    "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;

   user_data
    The extra user data. It will be sent to both "evaluation_cb" and
    "progress_cb".

  get_status
    Get the status of previous call of "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 "List of
    Status Codes".

  status_ok
    This is a shortcut of saying "get_status" eq "LBFGS_OK".

      ...

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

  List of Parameters
   m
    The number of corrections to approximate the inverse hessian matrix.

    The L-BFGS algorithm stores the computation results of previous "m"
    iterations to approximate the inverse hessian matrix of the current
    iteration. This parameter controls the size of the limited memories