%===========================================================================%
%                                                                           %
% This file is part of the documentation for the SYMPHONY MILP Solver.      %
%                                                                           %
% SYMPHONY was jointly developed by Ted Ralphs (ted@lehigh.edu) and         %
% Laci Ladanyi (ladanyi@us.ibm.com).                                        %
%                                                                           %
% (c) Copyright 2000-2015 Ted Ralphs. All Rights Reserved.                  %
%                                                                           %
% SYMPHONY is licensed under the Eclipse Public License. Please see         %
% accompanying file for terms.                                              %
%                                                                           %
%===========================================================================%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Master module callbacks}

%begin{latexonly}
\bd
%end{latexonly}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_usage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\firstfuncdef{user\_usage}
\label{user_usage}
\mysindex{cf}{user\_usage}
\begin{verbatim}
void user_usage()
\end{verbatim}

\bd

\describe

SYMPHONY's command-line switches are all lower case letters. The user can use
any upper case letter (except 'H' and as specified below) for command line
switches to control user-defined parameter settings without the use of a
parameter file. The function \ptt{user\_usage()} can optionally print out
usage information for the user-defined command line switches. The command line
switch {\tt -H} automatically calls the user's usage subroutine. The switch
{\tt -h} prints \BB's own usage information. In its default configuration, the
command-line switch \texttt{-F} is used to specify the file in which the
instance data is contained (either an MPS file or an GMPL/AMPL file). The
\texttt{-D} switch is used to specify the data file if an GMPL/AMPL file is
being read in (see the README file). The \texttt{-L} switch is used to specify
the data file if a file in LP format is being read in

\ed

\vspace{1ex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_initialize
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_initialize}
\label{user_initialize}
\mysindex{cf}{user\_initialize}
\begin{verbatim}
int user_initialize(void **user)
\end{verbatim}

\bd

\describe

The user allocates space for and initializes the user-defined
data structures for the master module.

\args

\bt{llp{250pt}}
{\tt void **user} & OUT & Pointer to the user-defined data structure. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. \BB\ exits. \\
{\tt USER\_SUCCESS} & Initialization is done. \\
{\tt USER\_DEFAULT} & There is no user-defined data structure (this can be the
case if the default parser is being used to read in either an MPS or GMPL/AMPL
file. \\
\et

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_readparams
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_readparams}
\label{user_readparams}
\mysindex{cf}{user\_readparams}
\begin{verbatim}
int user_readparams(void *user, char *filename, int argc, char **argv)
\end{verbatim}

\bd

\describe

The user can optionally read in parameter settings from the file named 
\texttt{filename}, specified on the command line using the \texttt{-f} switch. 
The parameter file \texttt{filename} can contain both SYMPHONY's built-in
parameters and user-defined parameters. If desired, the user can open this
file for reading, scan the file for lines that contain user parameter settings
and then read the parameter settings. A shell for doing this is set up in the
in the file \texttt{SYMPHONY-5.0/USER/user\_master.c}. Also, see the file
\texttt{Master/master\_io.c} to see how \BB\ does this. \\
\\
The user can also parse the command line arguments for user
settings. A shell for doing this is also set up in the file
\texttt{SYMPHONY-5.0/USER/user\_master.c}. Upper case letters are reserved for
user-defined command line switches. The switch {\tt -H} is reserved for help
and calls the user's usage subroutine (see \hyperref{\texttt{user_usage}}
{\texttt{user\_usage()}}{}{user_usage}). If the user returns 
`\texttt{USER\_DEFAULT}', then \BB\ will look for the command-line switches 
\texttt{-F} to specify the file name for reading in the model from either an 
MPS or a GMPL/AMPL file or \texttt{-L} to specify the file name for reading in
the model from an LP format file. The \texttt{-D} command-line switch is used
to specify an additional data file for GMPL/AMPL models. If the \texttt{-D}
option is not present, SYMPHONY assumes the file is an MPS file.

\args

\bt{llp{280pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt char *filename} & IN & The name of the parameter file. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. \BB\ stops. \\ {\tt USER\_SUCCESS} & User
parameters were read successfully. \\ {\tt USER\_DEFAULT} & SYMPHONY will read
in the problem instance from either an MPS, LP, or GMPL/AMPL file. The
command-line switches \texttt{-F}, \texttt{-L}, and \texttt{-D} (as
appropriate) will be used to specify the model file. \\
\et

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_io
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_io}
\label{user_io}
\mysindex{cf}{user\_io}
\begin{verbatim}
int user_io(void *user)
\end{verbatim}

\bd

\describe

Here, the user can read in an instance in a custom format and set up
appropriate data structures. If the user wants to use the default parsers to
read either an MPS file or a GMPL/AMPL file, then the return value
\texttt{USER\_DEFAULT} should be specified (see
\hyperref{\texttt{user_readparams}} 
{\texttt{user\_readparams()}}{}{user_readparams} for the
command-line switches to use to specify this behavior).

\args

\bt{llp{280pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. \BB\ stops. \\
{\tt USER\_SUCCESS} & User I/O was completed successfully. \\
{\tt USER\_DEFAULT} & Input will be read in from an MPS or GMPL/AMPL file. \\
\et

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_init_draw_graph
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_init\_draw\_graph}
\mysindex{cf}{user\_init\_draw\_graph}
\begin{verbatim}
int user_init_draw_graph(void *user, int dg_id)
\end{verbatim}

\bd

\describe

This function is invoked only if the {\tt do\_draw\_graph} parameter is set.
The user can initialize the graph drawing module by sending
some initial information (e.g., the location of the nodes of a
graph, like in the TSP.)

\args

\bt{llp{280pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt int dg\_id} & IN & The process id of the graph drawing module. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. \BB\ stops. \\
{\tt USER\_SUCCESS} & The user completed initialization successfully. \\
{\tt USER\_DEFAULT} & No action. \\
\et

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_start_heurs
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_start\_heurs}
\label{user_start_heurs}
\mysindex{cf}{user\_start\_heurs}
\begin{verbatim}
int user_start_heurs(void *user, double *ub, double *ub_estimate)
\end{verbatim}

\bd

\describe

The user invokes heuristics and generates the initial global upper
bound and also perhaps an upper bound estimate. This is the last place 
where the user can do things before the
branch and cut algorithm starts. She might do some preprocessing,
in addition to generating the upper bound.

\args

\bt{llp{300pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt double *ub} & OUT & Pointer to the global upper bound. Initially,
the upper bound is set to either {\tt -MAXDOUBLE} or the bound read in
from the parameter file, and should be changed by the user only if
a better valid upper bound is found. \\
{\tt double *ub\_estimate} & OUT & Pointer to an estimate of the global
upper bound. This is useful if the {\tt BEST\_ESTIMATE} diving
strategy is used (see the treemanager parameter
\hyperref{\tt diving\_strategy}{{\tt diving\_strategy} (Section } {)}
{diving_strategy}) \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. This error is probably not fatal. \\
{\tt USER\_SUCCESS} & User executed function successfully. \\
{\tt USER\_DEFAULT} & No action (someday, there may be a
default MIP heuristic here). \\
\et

\ed

\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_initialize_root_node
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\functiondef{user\_initialize\_root\_node}
\label{user_initialize_root_node}
\mysindex{cf}{user\_initialize\_root\_node}
\begin{verbatim}
int user_initialize_root_node(void *user, int *basevarnum, int **basevars,
                              int *basecutnum, int *extravarnum,  int **extravars,
                              char *obj_sense, double *obj_offset,
                              char ***colnames, int *colgen_strat)
\end{verbatim}

\bd

\describe

In this function, the user must specify the list of indices for the base and
extra variables. The option to specify a variable as base is provided simply
for efficiency reasons. If there is no reasonable way to come up with a set of
base variables, then all variables should be specified as extra (see Section
\ref{variables} for a discussion of base and extra variables). If the function
returns \texttt{USER\_DEFAULT} and sets \texttt{extravarnum}, then SYMPHONY
will put all variables indexed from 0 to \texttt{extravarnum} in the set of
extra variables by default. If an MPS or GMPL/AMPL file was read in using
SYMPHONY's built-in parser, i.e., the default behavior of
\hyperref{\texttt{user\_io}}{\texttt{user\_io()}}{}{user_io} was not modified,
then \texttt{extravarnum} need not be set. \\
\\
In this function, the user may also specify column names for display
purposes. If the \texttt{colnames} array is allocated, then SYMPHONY will use
for displaying solutions. If the data was read in from either an MPS or
GMPL/AMPL file, then the column names will be set automatically.

\args

\bt{llp{265pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt int *basevarnum} & OUT & Pointer to the number of base variables. \\
{\tt int **basevars} & OUT & Pointer to an array containing a list of
user indices of the base variables to be active in the root. \\
{\tt int *basecutnum} & OUT & The number of base constraints. \\
{\tt int *extravarnum} & OUT & Pointer to the number of extra active
variables in the root. \\
{\tt int **extravars} & OUT & Pointer to an array containing a list of
user indices of the extra variables to be active in the root. \\
{\tt char *obj\_sense} & INOUT & Whether to negate the objective function value
when printing the solution, set to either \texttt{MAXIMIZE} or
\texttt{MINIMIZE}. Note that SYMPHONY always minimizes---\textbf{this only
effects the printing of the solution}. The default is \texttt{MINIMIZE}. \\
{\tt double *obj\_offset} & INOUT & A specified constant to be added to the
objective function value when printing out the solution. \\
{\tt int ***colnames} & OUT & Pointer to an array containing a list of
column names to be used for display purposes. \\
{\tt int *colgen\_strat} & INOUT & The default strategy or one that has
been read in from the parameter file is passed in, but the user is free
to change it. See {\tt colgen\_strat} in the description of
parameters for details on how to set it.
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. \BB\ stops. \\
{\tt USER\_SUCCESS} & The required data are filled in. \\
{\tt USER\_DEFAULT} & All variables indexed 0 to \texttt{extravarnum} are put 
in the extra set (The user must set \texttt{extravarnum} unless an MPS or
GMPL/AMPL file was read in by SYMPHONY. \\
\et

\postp

The array of base and extra indices are sorted.

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_receive_feasible_solution
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_receive\_feasible\_solution}
\label{user_receive_feasible_solution}
\mysindex{cf}{user\_receive\_feasible\_solution}
\begin{verbatim}
int user_receive_feasible_solution(void *user, int msgtag, double cost, 
                                   int numvars, int *indices, double *values)
\end{verbatim}

\bd

\describe

This function is only used for parallel execution. Feasible solutions can be
sent and/or stored in a user-defined packed form if desired. For instance, the
TSP, a tour can be specified simply as a permutation, rather than as a list of
variable indices. In the LP module, a feasible solution is packed either by
the user or by a default packing routine. If the default packing routine was
used, the {\tt msgtag} will be {\tt FEASIBLE\_SOLUTION\_NONZEROS}. In this
case, {\tt cost}, {\tt numvars}, {\tt indices} and {\tt values} will contain
the solution value, the number of nonzeros in the feasible solution, and their
user indices and values. The user has only to interpret and store the
solution. Otherwise, when {\tt msgtag} is {\tt FEASIBLE\_SOLUTION\_USER}, \BB\
will send and receive the solution value only and the user has to unpack
exactly what she has packed in the LP module. In this case the contents of
the last three arguments are undefined. \\
\\
In most cases, SYMPHONY's default routines for sending and receiving feasible
solutions, as well as displaying them, will suffice. These routines simply
display all nonzeros by either index or name, depending on whether the user
set the column names. See
\hyperref{{\tt user_send_feasible_solution()}} 
{\ptt{user\_receive\_lp\_data()} in Section }{}{user_send_feasible_solution} for
more discussion.

\args

\bt{llp{290pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt int msgtag} &    IN & {\tt FEASIBLE\_SOLUTION\_NONZEROS} or {\tt
FEASIBLE\_SOLUTION\_USER} \\
{\tt double cost}  &    IN & The cost of the feasible solution.\\
{\tt int numvars} &  IN & The number of variables whose user indices and
values were sent (length of {\tt indices} and {\tt values}). \\
{\tt int *indices} &  IN & The user indices of the nonzero variables. \\
{\tt double *values} & IN & The corresponding values. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Ignored. This is probably not a fatal error.\\
{\tt USER\_SUCCESS} & The solution has been unpacked and stored. \\
{\tt USER\_DEFAULT} & Store the nonzeros in the solutions for later display. \\
\et

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_send_lp_data
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_send\_lp\_data}
\label{user_send_lp_data}
\mysindex{cf}{user\_send\_lp\_data}
\begin{verbatim}
int user_send_lp_data(void *user, void **user_lp)
\end{verbatim}

\bd

\describe

If the user wishes to employ parallelism, she has to send all problem-specific
data that will be needed to implement user functions in the LP module in order
to set up the initial LP relaxation and perform later computations. This could
include instance data, as well as user parameter settings (see Section
\ref{communication} for a discussion of this). This is one of the few places
where the user may need to worry about the configuration of the modules. If
either the tree manager or the LP are running as a separate process (either
{\tt COMPILE\_IN\_LP} or {\tt COMPILE\_IN\_TM} are {\tt FALSE} in the make
file), then the data will be sent and received through message-passing. See
\hyperref{{\tt user_receive_lp_data}} {\ptt{user\_receive\_lp\_data()} in
Section }{}{user_receive_lp_data} for more discussion. Otherwise, it can be
copied through shared memory. The easiest solution, which is set up by default
is to simply copy over a pointer to a single user data structure where
instance data is stored. The code for the two cases is put in the same source
file by use of {\tt \#ifdef} statements. See the comments in the code stub for
this function for more details.

\args

\bt{llp{275pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt void **user\_lp} & OUT & Pointer to the user-defined data
structure for the LP module. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. \BB\ stops. \\
{\tt USER\_SUCCESS} & Packing is done. \\
{\tt USER\_DEFAULT} & User has no data to send. This would be used when
SYMPHONY has read in an MPS or GMPL/AMPL model file. 
\et

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_send_cg_data
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_send\_cg\_data}
\label{user_send_cg_data}
\mysindex{cf}{user\_send\_cg\_data}
\begin{verbatim}
int user_pack_cg_data(void *user, void **user_cg)
\end{verbatim}

\bd

\describe

If the user wishes to employ parallelism and wants a separate cut generator
module, this function can be used to send all problem-specific data that will
be needed by the cut generator module to perform separation. This could
include instance data, as well as user parameter settings (see Section
\ref{communication} for a discussion of this). This is one of the few places
where the user may need to worry about the configuration of the modules. If
either the tree manager or the LP are running as a separate process (either
{\tt COMPILE\_IN\_LP} or {\tt COMPILE\_IN\_TM} are {\tt FALSE} in the {\tt
make} file), then the data will be sent and received through message-passing.
See \hyperref{{\tt user_receive_cg_data}} {\ptt{user\_receive\_cg\_data()} in
Section }{}{user_receive_cg_data} for more discussion. Otherwise, it can be
copied through shared memory. The easiest solution, which is set up by default
is to simply copy over a pointer to a single user data structure where
instance data is stored. The code for the two cases is put in the same source
file by use of {\tt \#ifdef} statements. See the comments in the code stub for
this function for more details.

\args

\bt{llp{275pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt void **user\_cg} & OUT & Pointer to the user-defined data
structure for the cut generator module. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. \BB\ stops. \\
{\tt USER\_SUCCESS} & Packing is done. \\
{\tt USER\_DEFAULT} & No data to send to the cut generator (no separation
performed). \\
\et

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_send_cp_data
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_send\_cp\_data}
\label{user_send_cp_data}
\mysindex{cf}{user\_send\_cp\_data}
\begin{verbatim}
int user_pack_cp_data(void *user, void **user_cp)
\end{verbatim}

\bd

\describe

If the user wishes to employ parallelism and wants to use the cut pool to
store user-defined cuts, this function can be used to send all
problem-specific data that will be needed by the cut pool module. This could
include instance data, as well as user parameter settings (see Section
\ref{communication} for a discussion of this). This is one of the few places
where the user may need to worry about the configuration of the modules. If
either the tree manager or the LP are running as a separate process (either
{\tt COMPILE\_IN\_LP} or {\tt COMPILE\_IN\_TM} are {\tt FALSE} in the {\tt
make} file), then the data will be sent and received through message-passing.
See \hyperref{{\tt user_receive_cp_data}} {\ptt{user\_receive\_cp\_data()} in
Section }{}{user_receive_cp_data} for more discussion. Otherwise, it can be
copied through shared memory. The easiest solution, which is set up by default
is to simply copy over a pointer to a single user data structure where
instance data is stored. The code for the two cases is put in the same source
file by use of {\tt \#ifdef} statements. See the comments in the code stub for
this function for more details. \\
\\
Note that there is support for cuts generated and stored as explicit matrix
rows. The cut pool module is already configured to deal with such cuts, so no
user implementation is required. Only the use of user-defined cuts requires
customization of the Cut Pool module. 

\args

\bt{llp{275pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt void **user\_cp} & OUT & Pointer to the user-defined data
structure for the cut pool module. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. \BB\ stops. \\
{\tt USER\_SUCCESS} & Packing is done. \\
{\tt USER\_DEFAULT} & No data to send to the cut pool (no user-defined cut
classes or cut pool not used). \\
\et

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_display_solution
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_display\_solution}
\label{user_display_solution}
\mysindex{cf}{user\_display\_solution}
\begin{verbatim}
int user_display_solution(void *user, double lpetol, int varnum, int *indices, 
                          double *values, double objval)
\end{verbatim}

\bd

\describe

This function is invoked when a best solution found so far is to be displayed
(after heuristics, after the end of the first phase, or the end of the whole
algorithm). This can be done using either a text-based format or using the
{\tt drawgraph} module. By default, SYMPHONY displays the indices (or column
names, if specified) and values for each nonzero variable in the solution. The
user may wish to display a custom version of the solution by interpreting the
variables. 

\args

\bt{llp{280pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. For
sequential computation, a pointer to the user's LP data structure is passed
in. For parallel computation, a pointer to the user's Master data structure is
passed in. \\
{\tt double lpetol} & IN & The LP zero tolerance used.\\
{\tt int varnum} & IN & The number of nonzeros in the solution. \\
{\tt int *indices} & IN & The indices of the nonzeros. \\
{\tt double *values} & IN & The values of the nonzeros. \\
{\tt double objval} &  IN & The objective function value of the solution. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Ignored. \\
{\tt USER\_SUCCESS} & User displayed the solution. SYMPHONY should do nothing. 
\\
{\tt USER\_DEFAULT} & SYMPHONY should display the solution in default format. 
\\
\et

\postp

If requested, SYMPHONY will display a best solution found so far in the
default format. 

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_send_feas_sol
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_send\_feas\_sol}
\label{user_send_feas_sol}
\mysindex{cf}{user\_send\_feas\_sol}
\begin{verbatim}
int user_send_feas_sol(void *user, int *feas_sol_size, int **feas_sol)
\end{verbatim}

\bd

\describe

This function is useful for debugging purposes. It passes a known
feasible solution to the tree manager. The tree manager then tracks
which current subproblem admits this feasible solution and notifies
the user when it gets pruned. It is useful for finding out why a known
optimal solution never gets discovered. Usually, this is due to either
an invalid cut of an invalid branching. Note that this feature only
works when branching on binary variables. See Section \ref{debugging}
for more on how to use this feature.

\args

\bt{llp{245pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt int *feas\_sol\_size} & INOUT & Pointer to size of the feasible
solution passed by the user. \\
{\tt int **feas\_sol} & INOUT & Pointer to the array of user indices
containing the feasible solution. This array is simply copied by the tree
manager and must be freed by the user. \\
\et

\returns

\args\bt{lp{260pt}}
{\tt USER\_ERROR} & Solution tracing is not enabled. \\
{\tt USER\_SUCCESS} & Tracing of the given solution is enabled. \\
{\tt USER\_DEFAULT} & No feasible solution given. \\
\et

\ed

\vspace{1ex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_process_own_messages
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_process\_own\_messages}
\mysindex{cf}{user\_process\_own\_messages}
\begin{verbatim}
int user_process_own_messages(void *user, int msgtag)
\end{verbatim}

\bd

\describe

The user must receive any message he sends to the master module
(independently of \BB's own messages). An example for such a message is
sending feasible solutions from separate heuristics processes fired up
in \htmlref{\tt user\_start\_heurs()}{user_start_heurs}. 

\args

\bt{llp{280pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt int msgtag} & IN & The message tag of the message. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Ignored. \\
{\tt USER\_SUCCESS} & Message is processed. \\
{\tt USER\_DEFAULT} & No user message types defined. \\
\et

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_free_master
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_free\_master}
\mysindex{cf}{user\_free\_master}
\begin{verbatim}
int user_free_master(void **user)
\end{verbatim}

\bd

\describe

The user frees all the data structures within {\tt *user}, and
also free {\tt *user} itself. This can be done using the built-in macro
{\tt FREE} that checks the existence of a pointer before freeing it.

\args

\bt{llp{280pt}}
{\tt void **user} & INOUT & Pointer to the user-defined data structure
(should be {\tt NULL} on return). \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Ignored. This is probably not a fatal error.\\
{\tt USER\_SUCCESS} & Everything was freed successfully. \\
{\tt USER\_DEFAULT} & There is no user memory to free. \\
\et

\ed

\vspace{1ex}

%begin{latexonly}
\ed
%end{latexonly}
