view release on metacpan or  search on metacpan

README  view on Meta::CPAN

      (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
    (corrections). The default value is 6. Values less than 3 are not
    recommended. Large values will result in excessive computing time.

   epsilon
    Epsilon for convergence test.

    This parameter determines the accuracy with which the solution is to be
    found. A minimization terminates when

      ||grad f(x)|| < epsilon * max(1, ||x||)

    where ||.|| denotes the Euclidean (L2) norm. The default value is 1e-5.

   max_iterations
    The maximum number of iterations.

    The L-BFGS algorithm terminates an optimization process with
    "LBFGSERR_MAXIMUMITERATION" status code when the iteration count
    exceedes this parameter. Setting this parameter to zero continues an
    optimization process until a convergence or error. The default value is
    0.