Optional callback routines

Functions
int COI_CALLCONV	COIDEF_Optfile (coiHandle_t cntvect, const char *optfile)
	define callback routine for defining an options file.
int COI_CALLCONV	COIDEF_FDEvalIni (coiHandle_t cntvect, COI_FDEVALINI_t coi_fdevalini)
	define callback routine to perform initialization tasks for the function and derivative evaluation.
int COI_CALLCONV	COIDEF_FDEvalEnd (coiHandle_t cntvect, COI_FDEVALEND_t coi_fdevalend)
	define callback routine for the termination of the function and derivative evaluation.
int COI_CALLCONV	COIDEF_Progress (coiHandle_t cntvect, COI_PROGRESS_t coi_progress)
	define callback routine for monitoring the algorithmic progress.
int COI_CALLCONV	COIDEF_Option (coiHandle_t cntvect, COI_OPTION_t coi_option)
	define callback routine for defining runtime options.
int COI_CALLCONV	COIDEF_TriOrd (coiHandle_t cntvect, COI_TRIORD_t coi_triord)
	define callback routine for providing the triangular order information.
int COI_CALLCONV	COIDEF_FDInterval (coiHandle_t cntvect, COI_FDINTERVAL_t coi_fdinterval)
	define callback routine for performing function and derivative evaluations on intervals.
int COI_CALLCONV	COIDEF_2DDir (coiHandle_t cntvect, COI_2DDIR_t coi_2ddir)
	define callback routine for computing the second derivative for a constraint in a direction.
int COI_CALLCONV	COIDEF_2DDirIni (coiHandle_t cntvect, COI_2DDIRINI_t coi_2ddirini)
	define callback routine for initializing the computation of second derivatives for a constraint in a direction.
int COI_CALLCONV	COIDEF_2DDirEnd (coiHandle_t cntvect, COI_2DDIREND_t coi_2ddirend)
	define callback routine for termination the computation of second derivatives for a constraint in a direction.
int COI_CALLCONV	COIDEF_2DDirLagr (coiHandle_t cntvect, COI_2DDIRLAGR_t coi_2ddirlagr)
	define callback routine for computing the second derivative of the Lagrangian in a direction.
int COI_CALLCONV	COIDEF_2DLagrStr (coiHandle_t cntvect, COI_2DLAGRSTR_t coi_2dlagrstr)
	define callback routine for providing the structure of the second derivatives of the Lagrangian.
int COI_CALLCONV	COIDEF_2DLagrVal (coiHandle_t cntvect, COI_2DLAGRVAL_t coi_2dlagrval)
	define callback routine for computing the values of the second derivatives of the Lagrangian.
int COI_CALLCONV	COIDEF_UsrMem (coiHandle_t cntvect, void *usrmem)
	provides a pointer to user memory that is available in all callback functions. NOTE: this is not a callback function, but a pointer to a data structure.

Detailed Description

The callback routines that can be used to enhance the solution algorithm.

The optional callbacks are available for the user to have more control over the solution algorithm. For example, the initialisation (see FDEvalIni – Function and Derivative Evaluator Initialization) and termination (see FDEvalEnd – Function and Derivative Evaluator Termination) callbacks for the first derivative evaluations can be used to improve efficiency. Further, it is also possible to provide callbacks that evaluate the second derivative.

Function Documentation

COIDEF_Optfile()

int COI_CALLCONV COIDEF_Optfile	(	coiHandle_t	cntvect,
		const char *	optfile )

define callback routine for defining an options file.

It is possible to define an options file with user defined values for certain options. To define an options file you must write a callback routine that gives CONOPT the file name (see OptFile) and register this optional routine with a call to COIDEF_Optfile() before CONOPT is started. The name of your version of OptFile must be declared as external and given to COIDEF_Optfile() as its second argument.

Note

By default the options defined via an option file are processed before the options defined via the callback routine (see COIDEF_Option()). The order can be changed with a call to coidef_optorder().

For the definition of the Optfile callback function, see Optfile

Parameters

cntvect	the control vector
optfile	the pointer to the OptFile routine for providing the options file name

COIDEF_FDEvalIni()

int COI_CALLCONV COIDEF_FDEvalIni	(	coiHandle_t	cntvect,
		COI_FDEVALINI_t	coi_fdevalini )

define callback routine to perform initialization tasks for the function and derivative evaluation.

The nonlinear FDEval routine is usually called for several constraints in one point before being called for constraints in another point. An optional user provided FDEvalIni routine can be used to perform common tasks that are needed in preparation for a new point. You must register this routine with a call to this method before CONOPT is started. The name of your version of FDEvalIni must be declared as external.

Parameters

cntvect	the control vector
coi_fdevalini	the pointer to the FDEvalIni routine for initializing data before nonlinear evaluations

COIDEF_FDEvalEnd()

int COI_CALLCONV COIDEF_FDEvalEnd	(	coiHandle_t	cntvect,
		COI_FDEVALEND_t	coi_fdevalend )

define callback routine for the termination of the function and derivative evaluation.

After the nonlinear FDEval routine has been called for several constraints in one point an optional user provided FDEvalEnd routine can be used to perform common cleanup tasks. If you want to use this possibility you must register this routine with a call to this method before CONOPT is started. The name of your version of FDEvalEnd must be declared as external.

Parameters

cntvect	the control vector
coi_fdevalend	the pointer to the FDEvalEnd routine for cleanup after nonlinear evaluations

COIDEF_Progress()

int COI_CALLCONV COIDEF_Progress	(	coiHandle_t	cntvect,
		COI_PROGRESS_t	coi_progress )

define callback routine for monitoring the algorithmic progress.

If you would like to write your own iteration log then CONOPT can provide the necessary information to a user written callback routine called Progress. Progress can also be used to communicate a Stop messages back to CONOPT. If you would like CONOPT to call your Progress routine you must register it with a call to this method before CONOPT is started. The name of your version of Progress must be declared as external.

Parameters

cntvect	the control vector
coi_progress	the pointer to the Progress routine for logging iteration progress or sending stop messages

COIDEF_Option()

int COI_CALLCONV COIDEF_Option	(	coiHandle_t	cntvect,
		COI_OPTION_t	coi_option )

define callback routine for defining runtime options.

An alternative or supplement to an options file is an option callback routine that CONOPT calls repeatedly to get non-default option values. To use this method you must write a callback routine that gives CONOPT the names and values of the non default options and you must register this optional routine with a call to this method before CONOPT is started. The name of your version of Option must be declared as external.

Note

By default the options defined via an option file are processed before the options defined via the callback routine.

Parameters

cntvect	the control vector
coi_option	the pointer to the Option routine for setting non-default option values

COIDEF_TriOrd()

int COI_CALLCONV COIDEF_TriOrd	(	coiHandle_t	cntvect,
		COI_TRIORD_t	coi_triord )

define callback routine for providing the triangular order information.

During preprocessing of a model CONOPT can provide information about the solution sequence of triangular parts of a model. This can be useful for analyzing certain types of infeasibilities. If you want to use this feature you must register a TriOrd callback routine with a call to this method before CONOPT is started. The name of your version of TriOrd must be declared as external.

Parameters

cntvect	the control vector
coi_triord	the pointer to the TriOrd routine for analyzing the solution sequence of triangular parts.

COIDEF_FDInterval()

int COI_CALLCONV COIDEF_FDInterval	(	coiHandle_t	cntvect,
		COI_FDINTERVAL_t	coi_fdinterval )

define callback routine for performing function and derivative evaluations on intervals.

During preprocessing CONOPT can take advantage of interval information for function values and derivatives if this is available. If you can provide interval information you can register an optional FDInterval function and derivative evaluation callback routine with a call to this method before CONOPT is started. The name of your version of FDInterval must be declared as external.

Parameters

cntvect	the control vector
coi_fdinterval	the pointer to the FDInterval routine for providing interval data for functions and derivatives

COIDEF_2DDir()

int COI_CALLCONV COIDEF_2DDir	(	coiHandle_t	cntvect,
		COI_2DDIR_t	coi_2ddir )

define callback routine for computing the second derivative for a constraint in a direction.

CONOPT can take advantage of 2^nd derivatives in various forms, as discussed in the Defining Second Order Information section. If you can provide directional 2^nd derivatives of the individual constraints then you can register an optional 2DDir callback routine with a call to this method before CONOPT is started. The name of your version of 2DDir must be declared as external.

Parameters

cntvect	the control vector
coi_2ddir	the pointer to the 2DDir callback routine for supplying directional second derivatives of constraints

COIDEF_2DDirIni()

int COI_CALLCONV COIDEF_2DDirIni	(	coiHandle_t	cntvect,
		COI_2DDIRINI_t	coi_2ddirini )

define callback routine for initializing the computation of second derivatives for a constraint in a direction.

The 2DDir routine defined above will be called in batches. First it will be called in one point and with a given direction for all nonlinear constraints except pre-triangular constraints and constraints with dual variables equal to zero, then for the same constraints in the same point but with a different direction, and later again in a new point with a new direction and possibly for a different set of constraints (due to changes in the dual variables). If the modeler would like to perform certain common tasks each time the point or the direction changes then this can be done in a callback routine defined with this method. If you would like to provide this initialization routine then you can register an optional 2DDirIni callback routine with a call to this method before CONOPT is started. The name of your version of 2DDirIni must be declared as external.

Parameters

cntvect	the control vector
coi_2ddirini	the pointer to the 2DDirIni callback routine for initializing tasks when the point or direction changes

COIDEF_2DDirEnd()

int COI_CALLCONV COIDEF_2DDirEnd	(	coiHandle_t	cntvect,
		COI_2DDIREND_t	coi_2ddirend )

define callback routine for termination the computation of second derivatives for a constraint in a direction.

After the 2DDir routine defined above has been called for a number of constraints in a particular point and in a particular direction the optional 2DDirEnd routine will be called if it has been defined by the modeler. in batches. If the modeler would like to perform certain common cleanup tasks each time the 2DDir calls for a point or a direction have been finished then this can be done in a callback routine defined with this method as discussed in 2DDirEnd section. If you would like to provide this termination routine then you can register an optional 2DDirEnd callback routine with a call to this method before CONOPT is started. The name of your version of 2DDirEnd must be declared as external.

Parameters

cntvect	the control vector
coi_2ddirend	the pointer to the 2DDirEnd callback routine for cleanup after processing a point or direction

COIDEF_2DDirLagr()

int COI_CALLCONV COIDEF_2DDirLagr	(	coiHandle_t	cntvect,
		COI_2DDIRLAGR_t	coi_2ddirlagr )

define callback routine for computing the second derivative of the Lagrangian in a direction.

CONOPT can take advantage of 2^nd derivatives in various forms as discussed in Defining Second Order Information. If you can provide directional 2^nd derivatives of the Lagrangian then you can register an optional 2DDirLagr callback routine with a call to this method before CONOPT is started. The name of your version of 2DDirLagr must be declared as external.

Parameters

cntvect	the control vector
coi_2ddirlagr	the pointer to the 2DDirLagr callback routine for supplying directional second derivatives of the Lagrangian

COIDEF_2DLagrStr()

int COI_CALLCONV COIDEF_2DLagrStr	(	coiHandle_t	cntvect,
		COI_2DLAGRSTR_t	coi_2dlagrstr )

define callback routine for providing the structure of the second derivatives of the Lagrangian.

CONOPT can take advantage of 2^nd derivatives in various forms, including the Hessian of the Lagrangian and directional 2^nd derivatives. If you can provide the Hessian of the Lagrangian as a sparse matrix, you can register the optional 2DLagrStr callback routine with a call to this method before CONOPT is started. The name of your version of 2DLagrStr must be declared as external.

Parameters

cntvect	the control vector.
coi_2dlagrstr	the pointer to the 2DLagrStr callback routine, which defines the structure of the Hessian of the Lagrangian.

COIDEF_2DLagrVal()

int COI_CALLCONV COIDEF_2DLagrVal	(	coiHandle_t	cntvect,
		COI_2DLAGRVAL_t	coi_2dlagrval )

define callback routine for computing the values of the second derivatives of the Lagrangian.

CONOPT can take advantage of 2^nd derivatives in various forms, including the Hessian of the Lagrangian and directional 2^nd derivatives. If you can provide the Hessian of the Lagrangian as a sparse matrix, you can register the optional 2DLagrVal callback routine with a call to this method before CONOPT is started. The name of your version of 2DLagrVal must be declared as external.

Parameters

cntvect	the control vector.
coi_2dlagrval	the pointer to the 2DLagrVal callback routine, which provides the values of the Hessian of the Lagrangian.

COIDEF_UsrMem()

int COI_CALLCONV COIDEF_UsrMem	(	coiHandle_t	cntvect,
		void *	usrmem )

provides a pointer to user memory that is available in all callback functions. NOTE: this is not a callback function, but a pointer to a data structure.

Communication between the modeler’s main program and the callback routines can take place via common blocks or global variables. For use in a thread safe application CONOPT offers an alternative communication mechanism called User Memory. The modeler can register a memory location (usually the address of the start of a vector) as User Memory and CONOPT will provide this address to all callback routines. You register User Memory by calling this method with the User Memory as the second argument.

Parameters

cntvect	the control vector
usrmem	the user memory location for communication between the main program and callback routines