view release on metacpan or  search on metacpan

lbfgs.h  view on Meta::CPAN

 */
typedef lbfgsfloatval_t (*lbfgs_evaluate_t)(
	void *instance,
	const lbfgsfloatval_t *x,
	lbfgsfloatval_t *g,
	const int n,
	const lbfgsfloatval_t step
	);

/**
 * Callback interface to receive the progress of the optimization process.
 *
 *	The lbfgs() function call this function for each iteration. Implementing
 *	this function, a client program can store or display the current progress
 *	of the optimization process.
 *
 *	@param	instance	The user data sent for lbfgs() function by the client.
 *	@param	x			The current values of variables.
 *	@param	g			The current gradient values of variables.
 *	@param	fx			The current value of the objective function.
 *	@param	xnorm		The Euclidean norm of the variables.
 *	@param	gnorm		The Euclidean norm of the gradients.
 *	@param	step		The line-search step used for this iteration.
 *	@param	n			The number of variables.
 *	@param	k			The iteration count.
 *	@param	ls			The number of evaluations called for this iteration.
 *	@retval	int			Zero to continue the optimization process. Returning a
 *						non-zero value will cancel the optimization process.
 */
typedef int (*lbfgs_progress_t)(
	void *instance,
	const lbfgsfloatval_t *x,
	const lbfgsfloatval_t *g,
	const lbfgsfloatval_t fx,
	const lbfgsfloatval_t xnorm,
	const lbfgsfloatval_t gnorm,
	const lbfgsfloatval_t step,
	int n,
	int k,
	int ls
	);

/*
A user must implement a function compatible with ::lbfgs_evaluate_t (evaluation
callback) and pass the pointer to the callback function to lbfgs() arguments.
Similarly, a user can implement a function compatible with ::lbfgs_progress_t
(progress callback) to obtain the current progress (e.g., variables, function
value, ||G||, etc) and to cancel the iteration process if necessary.
Implementation of a progress callback is optional: a user can pass \c NULL if
progress notification is not necessary.

In addition, a user must preserve two requirements:
	- The number of variables must be multiples of 16 (this is not 4).
	- The memory block of variable array ::x must be aligned to 16.

This algorithm terminates an optimization
when:

	||G|| < \epsilon \cdot \max(1, ||x||) .

In this formula, ||.|| denotes the Euclidean norm.
*/

/**
 * Start a L-BFGS optimization.
 *
 *	@param	n			The number of variables.
 *	@param	x			The array of variables. A client program can set
 *						default values for the optimization and receive the
 *						optimization result through this array.
 *	@param	ptr_fx		The pointer to the variable that receives the final
 *						value of the objective function for the variables.
 *						This argument can be set to \c NULL if the final
 *						value of the objective function is unnecessary.
 *	@param	proc_evaluate	The callback function to provide function and
 *							gradient evaluations given a current values of
 *							variables. A client program must implement a
 *							callback function compatible with \ref
 *							lbfgs_evaluate_t and pass the pointer to the
 *							callback function.
 *	@param	proc_progress	The callback function to receive the progress
 *							(the number of iterations, the current value of
 *							the objective function) of the minimization
 *							process. This argument can be set to \c NULL if
 *							a progress report is unnecessary.
 *	@param	instance	A user data for the client program. The callback
 *						functions will receive the value of this argument.
 *	@param	param		The pointer to a structure representing parameters for
 *						L-BFGS optimization. A client program can set this
 *						parameter to \c NULL to use the default parameters.
 *						Call lbfgs_parameter_init() function to fill a
 *						structure with the default values.
 *	@retval	int			The status code. This function returns zero if the
 *						minimization process terminates without an error. A
 *						non-zero value indicates an error.
 */
int lbfgs(
	const int n,
	lbfgsfloatval_t *x,
	lbfgsfloatval_t *ptr_fx,
	lbfgs_evaluate_t proc_evaluate,
	lbfgs_progress_t proc_progress,
	void *instance,
	lbfgs_parameter_t *param
	);

/**
 * Initialize L-BFGS parameters to the default values.
 *
 *	Call this function to fill a parameter structure with the default values
 *	and overwrite parameter values if necessary.
 *
 *	@param	param		The pointer to the parameter structure.
 */
void lbfgs_parameter_init(lbfgs_parameter_t *param);

/** @} */

#ifdef	__cplusplus
}
#endif/*__cplusplus*/