%===========================================================================%
%                                                                           %
% 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-2011 Ted Ralphs. All Rights Reserved.                  %
%                                                                           %
% SYMPHONY is licensed under the Eclipse Public License. Please see         %
% accompanying file for terms.                                              %
%                                                                           %
%===========================================================================%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Cut generator module callbacks}

Due to the relative simplicity of the cut generator, there are no wrapper
functions implemented for CG. Consequently, there are no default
options and no post-processing.

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_receive_cg_data
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\firstfuncdef{user\_receive\_cg\_data}
\sindex[cf]{user\_receive\_cg\_data}
\label{user_receive_cg_data}
\begin{verbatim}
int user_receive_cg_data (void **user)
\end{verbatim}

\bd

\describe

This function only has to be filled out for parallel execution and only if the
TM, LP, and CG modules are all compiled as separate modules. This would not be
typical. If needed, the user can use this function to receive problem-specific
data needed for computation in the CG module. The same data must be received
here that was sent in the \hyperref{{\tt user\_send\_cg\_data()}}
{\ptt{user\_send\_cg\_data()} (see Section }{)}{user_send_cg_data} 
function in the
master module. The user has to allocate space for all the data structures,
including {\tt user} itself. Note that some or all of this may be done in the
function {\tt \htmlref{user\_send\_cg\_data()}{user_send_cg_data}} if the Tree
Manager, LP, and CG are all compiled together. See that function for more
information.

\args

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

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. CG exits. \\
{\tt USER\_SUCCESS} & The user received the data properly. \\
{\tt USER\_DEFAULT} & User did not send any data. \\
\et

\item[Invoked from:] {\tt cg\_initialize()} at process start.

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_unpack_lp_solution_cg
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_receive\_lp\_solution\_cg}
\sindex[cf]{user\_receive\_lp\_solution\_cg}
\begin{verbatim}
int user_receive_lp_solution_cg(void *user)
\end{verbatim}

\bd

\describe

This function is invoked only in the case of parallel computation and only if
in the {\tt \htmlref{user\_send\_lp\_solution()}{user_send_lp_solution}}
function of the LP module the user opted for packing the current LP solution
herself. Here she must receive the data sent from there.

\args

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

\item[Invoked from:] Whenever an LP solution is received.

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Error. The LP solution was not received and will not be
processed. \\ 
{\tt USER\_SUCCESS} & The user received the LP solution. \\
{\tt USER\_DEFAULT} & The solution was sent by SYMPHONY and will be received
automatically. \\
\et

\item[Note:] \hfill

\BB\ automatically unpacks the level, index and iteration number
corresponding to the current LP solution within the current search tree node
as well as the objective value and upper bound.

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_find_cuts
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_find\_cuts}
\sindex[cf]{user\_find\_cuts}
\label{user_find_cuts}
\begin{verbatim}
int user_find_cuts(void *user, int varnum, int iter_num, int level,
		    int index, double objval, int *indices, double *values,
		    double ub, double lpetol, int *cutnum)
\end{verbatim}

\bd

\describe

In this function, the user can generate cuts based on the current LP solution
stored in {\tt soln}. Cuts found are added to the LP by calling the {\tt
cg\_add\_user\_cut(\htmlref{cut\_data}{cut_data} *new\_cut)} function, which
then transfers the cut to the LP module, either through message passing or
shared memory.  The argument of this function is a pointer to the cut to be
sent. See Section \ref{user-written-lp} for a description of this data
structure. Each user-defined cut assigned a type and a designated packed
form. Each user-defined type must be recognized by the user's \hyperref{{\tt
user\_unpack\_cuts()}}{\ptt{user\_unpack\_cuts()}}{}{user_unpack_cuts}
function in the master module. If the user wants a user-defined cut to be
added to the cut pool in case it proves to be effective in the LP, then {\tt
new\_cut->name} should be set to {\tt CUT\_\_SEND\_TO\_CP}. In this case, the
cut must be globally valid. Otherwise, it should be set to {\tt
CUT\_\_DO\_NOT\_SEND\_TO\_CP}. \\
\\
Alternatively, SYMPHONY provides automated support for the generation of cuts
represented explicitly as matrix rows. These cuts are passed as sparse vectors
and can be added by calling the routine \texttt{cg\_add\_explicit\_cut()},
which has the following interface.
\begin{verbatim}
int cg_add_explicit_cut(int nzcnt, int *indices, double *values,
                        double rhs, double range, char sense, 
                        char send_to_cp)
\end{verbatim}
Here, \texttt{nzcnt} is the number of nonzero coefficients in the cut,
\texttt{indices} is an array containing the indices of the columns with
nonzero entries, and \texttt{values} is an array of the corresponding
values. The right hand side value is passed in through the variable
\texttt{rhs}, the range is passed in through the variable \texttt{range}, and
the sense of the inequality is passed through the variable
\texttt{sense}. Finally, the variable \texttt{send\_to\_cp} indicates to
SYMPHONY whether the cut is globally valid and should be sent to the cut pool,
or whether it is only to be used locally.\\
\\
The only output of the \texttt{user\_find\_cuts()} function is the number of
cuts generated and this value is returned in the last argument. For options to
generate generic cuts automatically using the COIN Cut Generation Library, see
the function \hyperref{\ptt{user\_generate\_cuts\_in\_lp()}}{{\tt
user\_generate\_cuts\_in\_lp()}}{}{user_generate_cuts_in_lp}\\
\\

\newpage
\args

\bt{llp{280pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure.
\\
{\tt int iter\_num} & IN & The iteration number of the current LP solution. \\
{\tt int level} & IN & The level in the tree on which the current LP
solution was generated. \\
{\tt index} & IN & The index of the node in which LP solution was generated.
\\
{\tt objval} & IN & The objective function value of the current LP solution.
\\
{\tt int varnum} & IN & The number of nonzeros in the current LP solution. \\
{\tt indices} & IN & The column indices of the nonzero variables in the current
LP solution. \\
{\tt values} & IN & The values of the nonzero variables listed in 
{\tt indices}.
\\
{\tt double ub} & IN & The current global upper bound. \\
{\tt double lpetol} & IN & The current error tolerance in the LP. \\
{\tt int *cutnum} & OUT & Pointer to the number of cuts generated
and sent to the LP. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Ignored. \\
{\tt USER\_SUCCESS} & The user function exited properly. \\
{\tt USER\_DEFAULT} & No cuts were generated. \\
\et

\item[Invoked from:] Whenever an LP solution is received.

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_check_validity_of_cut
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{user_check_validity_of_cut}
\functiondef{user\_check\_validity\_of\_cut}
\sindex[cf]{user\_check\_validity\_of\_cut}
\begin{verbatim}
int user_check_validity_of_cut(void *user, cut_data *new_cut)
\end{verbatim}

\bd

\describe

This function is provided as a debugging tool. Every cut that is to be
sent to the LP solver is first passed to this function where the user
can independently verify that the cut is valid by testing it against a
known feasible solution (usually an optimal one). This is useful for
determining why a particular known feasible (optimal) solution was
never found. Usually, this is due to an invalid cut being added. See
Section \ref{debugging} for more on this feature.

\args

\bt{llp{280pt}}
{\tt void *user} & IN & Pointer to the user-defined data structure. \\
{\tt cut\_data *new\_cut} & IN & Pointer to the cut that must be
checked. \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Ignored. \\
{\tt USER\_SUCCESS} & The user is done checking the cut. \\
{\tt USER\_DEFAULT} & The cut is ignored.
\et

\item[Invoked from:] Whenever a cut is being sent to the LP.

\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% user_free_cg
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{user\_free\_cg}
\sindex[cf]{user\_free\_cg}
\begin{verbatim}
int user_free_cg(void **user)
\end{verbatim}

\bd

\describe

The user has to free all the data structures within {\tt user}, and also free
{\tt user} itself. The user can use 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 exit from this function). \\
\et

\returns

\bt{lp{300pt}}
{\tt USER\_ERROR} & Ignored. \\
{\tt USER\_SUCCESS} & The user freed all data structures. \\
{\tt USER\_DEFAULT} & The user has no memory to free. \\
\et

\item[Invoked from:] {\tt cg\_close()} at module shutdown. 

\ed

\vspace{1ex}

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