gretl_bfgs

gretl_bfgs

Functions

Types and Values

Object Hierarchy


Description

Functions

BFGS_CRIT_FUNC ()

double
(*BFGS_CRIT_FUNC) (const double *Param1,
                   void *Param2);

Returns


BFGS_GRAD_FUNC ()

int
(*BFGS_GRAD_FUNC) (double *Param1,
                   double *Param2,
                   int Param3,
                   BFGS_CRIT_FUNC Param4,
                   void *Param5);

Returns


BFGS_LLT_FUNC ()

const double *
(*BFGS_LLT_FUNC) (const double *Param1,
                  int Param2,
                  void *Param3);

Returns


HESS_FUNC ()

int
(*HESS_FUNC) (double *Param1,
              gretl_matrix *Param2,
              void *Param3);

Returns


BFGS_max ()

int
BFGS_max (double *b,
          int n,
          int maxit,
          double reltol,
          int *fncount,
          int *grcount,
          BFGS_CRIT_FUNC cfunc,
          int crittype,
          BFGS_GRAD_FUNC gradfunc,
          void *data,
          gretl_matrix *A0,
          gretlopt opt,
          PRN *prn);

Obtains the set of values for b which jointly maximize the criterion value as calculated by cfunc . Uses the BFGS variable-metric method. Based on Pascal code in J. C. Nash, "Compact Numerical Methods for Computers," 2nd edition, converted by p2c then re-crafted by B. D. Ripley for gnu R. Revised for gretl by Allin Cottrell.

Parameters

b

array of adjustable coefficients.

 

n

number elements in array b .

 

maxit

the maximum number of iterations to allow.

 

reltol

relative tolerance for terminating iteration.

 

fncount

location to receive count of function evaluations.

 

grcount

location to receive count of gradient evaluations.

 

cfunc

pointer to function used to calculate maximand.

 

crittype

code for type of the maximand/minimand: should be C_LOGLIK, C_GMM or C_OTHER. Used only in printing iteration info.

 

gradfunc

pointer to function used to calculate the gradient, or NULL for default numerical calculation.

 

data

pointer that will be passed as the last parameter to the callback functions cfunc and gradfunc .

 

A0

initial approximation to the inverse of the Hessian (or NULL to use identity matrix)

 

opt

may contain OPT_V for verbose operation, OPT_L to force use of L-BFGS-B.

 

prn

printing struct (or NULL). Only used if opt includes OPT_V.

 

Returns

0 on successful completion, non-zero error code on error.


LBFGS_max ()

int
LBFGS_max (double *b,
           int n,
           int maxit,
           double reltol,
           int *fncount,
           int *grcount,
           BFGS_CRIT_FUNC cfunc,
           int crittype,
           BFGS_GRAD_FUNC gradfunc,
           void *data,
           gretlopt opt,
           PRN *prn);

Returns


newton_raphson_max ()

int
newton_raphson_max (double *b,
                    int n,
                    int maxit,
                    double crittol,
                    double gradtol,
                    int *itercount,
                    int crittype,
                    BFGS_CRIT_FUNC cfunc,
                    BFGS_GRAD_FUNC gradfunc,
                    HESS_FUNC hessfunc,
                    void *data,
                    gretlopt opt,
                    PRN *prn);

The functions cfunc (computes the criterion, usually a loglikelihood) and gradfunc (score, provides an updated estimate of the gradient in its second argument) are just as in BFGS_max above.

The hessfunc callback should compute the negative Hessian, _not_ inverted; newton_raphson_max takes care of the inversion, with a routine for fixing up the matrix if it's not positive definite. If hessfunc is NULL we fall back on a numerical approximation to the Hessian.

Parameters

b

array of adjustable coefficients.

 

n

number elements in array b .

 

maxit

the maximum number of iterations to allow.

 

crittol

tolerance for terminating iteration, in terms of the change in the criterion.

 

gradtol

tolerance for terminating iteration, in terms of the gradient.

 

itercount

location to receive count of iterations.

 

crittype

code for type of the maximand/minimand: should be C_LOGLIK, C_GMM or C_OTHER. Used only in printing iteration info.

 

cfunc

pointer to function used to calculate maximand.

 

gradfunc

pointer to function used to calculate the gradient, or NULL for default numerical calculation.

 

hessfunc

pointer to function used to calculate the Hessian.

 

data

pointer that will be passed as the last parameter to the callback functions cfunc , gradfunc and hessfunc .

 

opt

may contain OPT_V for verbose operation.

 

prn

printing struct (or NULL). Only used if opt includes OPT_V.

 

Returns

0 on successful completion, non-zero error code on error.


BFGS_numeric_gradient ()

int
BFGS_numeric_gradient (double *b,
                       double *g,
                       int n,
                       BFGS_CRIT_FUNC func,
                       void *data);

Returns


numerical_score_matrix ()

gretl_matrix *
numerical_score_matrix (double *b,
                        int T,
                        int k,
                        BFGS_LLT_FUNC lltfun,
                        void *data,
                        int *err);

Returns


hessian_from_score ()

int
hessian_from_score (double *b,
                    gretl_matrix *H,
                    BFGS_GRAD_FUNC gradfunc,
                    BFGS_CRIT_FUNC cfunc,
                    void *data);

Uses the score function (gradfunc ) is to construct a numerical approximation to the Hessian. This is primarily intended for building a covariance matrix at convergence; note that it may not work well at an arbitrary point in the parameter space.

Note that the only use of cfunc within this function is as an argument to be passed to gradfunc . It is therefore OK to pass NULL for cfunc provided that gradfunc does not use its 4th argument, which corresponds to the BFGS_CRIT_FUNC parameter.

Parameters

b

array of k parameter estimates.

 

H

k x k matrix to receive the (negative) Hessian.

 

gradfunc

function to compute gradient.

 

cfunc

function to compute criterion (or NULL, see below).

 

data

data to be passed to the gradfunc callback.

 

Returns

0 on successful completion, non-zero error code on error.


hessian_inverse_from_score ()

gretl_matrix *
hessian_inverse_from_score (double *b,
                            int n,
                            BFGS_GRAD_FUNC gradfunc,
                            BFGS_CRIT_FUNC cfunc,
                            void *data,
                            int *err);

A wrapper for hessian_from_score() which takes care of (a) allocation of the Hessian and (b) inversion.

Parameters

b

array of parameter estimates.

 

n

the number of elements in b .

 

gradfunc

function to compute gradient.

 

cfunc

function to compute criterion.

 

data

data to be passed to the gradfunc callback.

 

err

location to receive error code.

 

Returns

the inverse of the (negative) Hessian on successful completion, NULL on error.


numerical_hessian_inverse ()

gretl_matrix *
numerical_hessian_inverse (const double *b,
                           int n,
                           BFGS_CRIT_FUNC func,
                           void *data,
                           int *err);

A wrapper for numerical_hessian() which takes care of (a) allocation of the Hessian and (b) inversion.

Parameters

b

array of parameter estimates.

 

n

the number of elements in b .

 

func

function to compute criterion.

 

data

data to be passed to the gradfunc callback.

 

err

location to receive error code.

 

Returns

the inverse of the (negative) Hessian on successful completion, NULL on error.


user_BFGS ()

double
user_BFGS (gretl_matrix *b,
           const char *fncall,
           const char *gradcall,
           DATASET *dset,
           PRN *prn,
           int *err);

Returns


user_NR ()

double
user_NR (gretl_matrix *b,
         const char *fncall,
         const char *gradcall,
         const char *hesscall,
         DATASET *dset,
         PRN *prn,
         int *err);

Returns


user_simann ()

double
user_simann (gretl_matrix *b,
             const char *fncall,
             int maxit,
             DATASET *dset,
             PRN *prn,
             int *err);

Returns


fdjac ()

gretl_matrix *
fdjac (gretl_matrix *theta,
       const char *fncall,
       DATASET *dset,
       int *err);

Returns


gretl_simann ()

int
gretl_simann (double *theta,
              int n,
              int maxit,
              BFGS_CRIT_FUNC cfunc,
              void *data,
              gretlopt opt,
              PRN *prn);

Simulated annealing: can help to improve the initialization of theta for numerical optimization. On exit the value of theta is set to the func-best point in case of improvement, otherwise to the last point visited.

Parameters

theta

parameter array.

 

n

length of theta .

 

maxit

the maximum number of iterations to perform.

 

cfunc

the function to be maximized.

 

data

pointer to be passed to the cfunc callback.

 

opt

may include OPT_V for verbose operation.

 

prn

printing struct, or NULL.

 

Returns

0 on success, non-zero code on error.


BFGS_defaults ()

void
BFGS_defaults (int *maxit,
               double *tol,
               int ci);


optimizer_get_matrix_name ()

int
optimizer_get_matrix_name (const char *fncall,
                           char *name);

Returns

Types and Values

enum OptimizerCode

Members

BHHH_MAX

   

BFGS_MAX

   

LBFGS_MAX

   

LM_MAX