Writing the Callbacks

For each module, all callback functions are invoked from so-called wrapper functions that provide the interface and also performs a default action if the user chooses not to override it. Although SYMPHONY is written in C, the wrapper functions provide a C++-style interface in which the user can either accept the default action or override it. Each wrapper function is named *_u() , where * is the name of the corresponding callback function, and is defined in a file called *_wrapper.c. The wrapper function first collects the necessary data and hands it to the user by calling the user function. Based on the return value from the user, the wrapper then performs any necessary post-processing. All callback functions have default options, so that SYMPHONY now acts as a generic MILP solver out of the box.

In Section 6.3, the callback functions are described in detail. The name of every callback function starts with user_. There are three kinds of arguments:

IN:
An argument containing information that the user might need to perform the function.
OUT:
A pointer to an argument in which the user should return a result (requested data, decision, etc.) of the function.
INOUT:
An argument which contains information the user might need, but also for which the user can change the value.
The return values for most function are as follows:
Return values:

USER_ERROR Error in the user function. Printing an error message is the user's responsibility. Depending on the work the user function was supposed to do, the error might be ignored (and some default option used), or the process aborts.
USER_SUCCESS The user function was implemented and executed correctly.
USER_DEFAULT This option means that the user function was not implemented and that SYMPHONY should either execute a default subroutine (the default is one of the built-in options--SYMPHONY decides which one to use based on initial parameter settings and the execution of the algorithm) or else do nothing, if execution of the subroutine is optional.
built_in_option1  
built_in_option2 ... The specified built-in option will be used.

Notes:

Ted Ralphs
2007-12-21