gretl_bfgs

gretl_bfgs

Synopsis

enum                OptimizerCode;
double              (*BFGS_CRIT_FUNC)                   (const double *Param1,
                                                         void *Param2);
int                 (*BFGS_GRAD_FUNC)                   (double *Param1,
                                                         double *Param2,
                                                         int Param3,
                                                         BFGS_CRIT_FUNC Param4,
                                                         void *Param5);
const double *      (*BFGS_LLT_FUNC)                    (const double *Param1,
                                                         int Param2,
                                                         void *Param3);
int                 (*HESS_FUNC)                        (double *Param1,
                                                         gretl_matrix *Param2,
                                                         void *Param3);
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);
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);
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);
int                 BFGS_numeric_gradient               (double *b,
                                                         double *g,
                                                         int n,
                                                         BFGS_CRIT_FUNC func,
                                                         void *data);
gretl_matrix *      numerical_score_matrix              (double *b,
                                                         int T,
                                                         int k,
                                                         BFGS_LLT_FUNC lltfun,
                                                         void *data,
                                                         int *err);
int                 hessian_from_score                  (double *b,
                                                         gretl_matrix *H,
                                                         BFGS_GRAD_FUNC gradfunc,
                                                         BFGS_CRIT_FUNC cfunc,
                                                         void *data);
gretl_matrix *      hessian_inverse_from_score          (double *b,
                                                         int n,
                                                         BFGS_GRAD_FUNC gradfunc,
                                                         BFGS_CRIT_FUNC cfunc,
                                                         void *data,
                                                         int *err);
gretl_matrix *      numerical_hessian_inverse           (const double *b,
                                                         int n,
                                                         BFGS_CRIT_FUNC func,
                                                         void *data,
                                                         int *err);
double              user_BFGS                           (gretl_matrix *b,
                                                         const char *fncall,
                                                         const char *gradcall,
                                                         DATASET *dset,
                                                         PRN *prn,
                                                         int *err);
double              user_NR                             (gretl_matrix *b,
                                                         const char *fncall,
                                                         const char *gradcall,
                                                         const char *hesscall,
                                                         DATASET *dset,
                                                         PRN *prn,
                                                         int *err);
double              user_simann                         (gretl_matrix *b,
                                                         const char *fncall,
                                                         int maxit,
                                                         DATASET *dset,
                                                         PRN *prn,
                                                         int *err);
gretl_matrix *      fdjac                               (gretl_matrix *theta,
                                                         const char *fncall,
                                                         DATASET *dset,
                                                         int *err);
int                 gretl_simann                        (double *theta,
                                                         int n,
                                                         int maxit,
                                                         BFGS_CRIT_FUNC cfunc,
                                                         void *data,
                                                         gretlopt opt,
                                                         PRN *prn);
void                BFGS_defaults                       (int *maxit,
                                                         double *tol,
                                                         int ci);
int                 optimizer_get_matrix_name           (const char *fncall,
                                                         char *name);

Description

Details

enum OptimizerCode

typedef enum {
    BHHH_MAX,
    BFGS_MAX,
    LBFGS_MAX,
    LM_MAX
} OptimizerCode;

BHHH_MAX

BFGS_MAX

LBFGS_MAX

LM_MAX


BFGS_CRIT_FUNC ()

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


BFGS_GRAD_FUNC ()

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


BFGS_LLT_FUNC ()

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


HESS_FUNC ()

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


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.

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);


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.

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);


numerical_score_matrix ()

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


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.

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.

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.

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);


user_NR ()

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


user_simann ()

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


fdjac ()

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


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.

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);