# source:stable/5.1/SYMPHONY/Doc/man-cp.tex@759

Last change on this file since 759 was 759, checked in by tkr, 7 years ago

• Property svn:eol-style set to native
• Property svn:keywords set to Author Date Id Revision
File size: 9.1 KB
Line
1%===========================================================================%
2%                                                                           %
3% This file is part of the documentation for the SYMPHONY MILP Solver.      %
4%                                                                           %
5% SYMPHONY was jointly developed by Ted Ralphs (tkralphs@lehigh.edu) and    %
7%                                                                           %
9%                                                                           %
11% accompanying file for terms.                                              %
12%                                                                           %
13%===========================================================================%
14
15%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16\subsection{Cut pool module callbacks}
17
18Due to the relative simplicity of the cut pool, there are no wrapper
19functions implemented for CP. Consequently, there are no default
20options and no post-processing.
21
22%begin{latexonly}
23\bd
24%end{latexonly}
25
26%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
29
32\begin{verbatim}
34\end{verbatim}
35
36\bd
37
38\item[Description:] \hfill
39
40The user has to receive here all problem-specific information sent
41from \hyperref{{\tt user\_send\_cp\_data()}}{{\tt user\_send\_cp\_data()}
42(see Section }{)}{user_send_cp_data} function in the master module.
43The user has to allocate space for all the data structures, including
44{\tt user} itself. Note that this function is only called if the
45either the Tree Manager, LP, or CP are running as a separate process
46(i.e.~either {\tt COMPILE\_IN\_TM}, {\tt COMPILE\_IN\_LP}, or {\tt
47COMPILE\_IN\_CP} are set to {\tt FALSE} in the {\tt make} file).
48Otherwise, this is done in {\tt \htmlref{user\_send\_cp\_data()}
49{user_send_cp_data}}. See the
50description of that function for more details.
51
52\item[Arguments:] \hfill
53
54\bt{llp{280pt}}
55{\tt void **user} & INOUT & Pointer to the user-defined data structure. \\
56\et
57
58\returns
59
60\bt{lp{300pt}}
61{\tt USER\_ERROR} & Error. Cut pool module exits. \\
62{\tt USER\_SUCCESS} & The user received data successfully. \\
63{\tt USER\_DEFAULT} & The user did not send any data to be received. \\
64\et
65
66\item[Invoked from:] {\tt cp\_initialize} at module start-up.
67
68\ed
69
70\vspace{1ex}
71
72%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
74%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
75
77\begin{verbatim}
79\end{verbatim}
80
81\bd
82
83\item[Description:] \hfill
84
85This function is invoked only in the case parallel computation and only if in
86the {\tt \htmlref{user\_send\_lp\_solution()}{user_send_lp_solution}} function
87of the LP module, the user opted for packing the current LP solution in a
88custom format. Here she must receive the data she sent there.
89
90\item[Arguments:] \hfill
91
92\bt{llp{250pt}}
93{\tt void *user} & IN & Pointer to the user-defined data structure. \\
94\et
95
96\returns
97
98\bt{lp{300pt}}
99{\tt USER\_ERROR} & Cuts are not checked for this LP solution. \\
100{\tt USER\_SUCCESS} & The user function executed properly. \\
101{\tt USER\_DEFAULT} & SYMPHONY's default format should be used. \\
102\et
103
104\item[Invoked from:] Whenever an LP solution is received.
105
106\item[Note:] \hfill
107
108\BB\ automatically unpacks the level, index and iteration number
109corresponding to the current LP solution within the current search
110tree node.
111
112\ed
113
114\vspace{1ex}
115
116%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
117% user_prepare_to_check_cuts
118%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
119
120\functiondef{user\_prepare\_to\_check\_cuts}
121\label{user_prepare_to_check_cuts}
122\begin{verbatim}
123int user_prepare_to_check_cuts(void *user, int varnum, int *indices,
124                               double *values)
125\end{verbatim}
126
127\bd
128
129\item[Description:] \hfill
130
131This function is invoked after an LP solution is received but before any cuts
132are tested. Here the user can build up data structures
133(e.g., a graph representation of the solution) that can make the testing of
134cuts easier in the {\tt \htmlref{user\_check\_cuts}{user_check_cuts}} function.
135
136\item[Arguments:] \hfill
137
138\bt{llp{285pt}}
139{\tt void *user} & IN & Pointer to the user-defined data structure. \\
140{\tt int varnum} & IN & The number of nonzero/fractional variables described
141in {\tt indices} and {\tt values}. \\
142{\tt int *indices} & IN & The user indices of the nonzero/fractional
143variables. \\
144{\tt double *values} & IN & The nonzero/fractional values. \\
145\et
146
147\returns
148
149\bt{lp{300pt}}
150{\tt USER\_ERROR} & Cuts are not checked for this LP solution. \\
151{\tt USER\_SUCCESS} & The user is prepared to check cuts. \\
152{\tt USER\_DEFAULT} & There are no user-defined cuts in the pool. \\
153\et
154
155\item[Invoked from:] Whenever an LP solution is received.
156
157\ed
158
159%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
160% user_check_cut
161%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
162
163\functiondef{user\_check\_cut}
164\label{user_check_cuts}
165\begin{verbatim}
166int user_check_cut(void *user, double lpetol, int varnum,
167                   int *indices, double *values, cut_data *cut,
168                   int *is_violated, double *quality)
169\end{verbatim}
170
171\bd
172
173\item[Description:] \hfill
174
175The user has to determine whether a given cut is violated by the given
176LP solution (see Section \ref{user-written-lp} for a description of
177the {\tt \htmlref{cut\_data data}{cut_data}} data structure). Also,
178the user can assign a number to the cut called the {\em quality}. This
179number is used in deciding which cuts to check and purge. See the
180section on \htmlref{Cut Pool Parameters}{cut_pool_params} for more
181information.
182
183\item[Arguments:] \hfill
184
185\bt{llp{255pt}}
186{\tt void *user} & INOUT & The user defined part of p. \\
187{\tt double lpetol} & IN & The $\epsilon$ tolerance in the LP module. \\
188{\tt int varnum} & IN & Same as the previous function. \\
189{\tt int *indices} & IN & Same as the previous function. \\
190{\tt double *values} & IN & Same as the previous function. \\
191{\tt cut\_data *cut} & IN & Pointer to the cut to be tested. \\
192{\tt int *is\_violated} & OUT & TRUE/FALSE based on whether the cut is violated
193or not. \\
194{\tt double *quality} & OUT & a number representing the relative
195strength of the cut.
196\et
197
198\returns
199
200\bt{lp{300pt}}
201{\tt USER\_ERROR} & Cut is not sent to the LP, regardless of the value of
202{\tt *is\_violated}. \\
203{\tt USER\_SUCCESS} & The user function exited properly. \\
204{\tt USER\_DEFAULT} & Same as error. \\
205\et
206
207\item[Invoked from:] Whenever a cut needs to be checked.
208
209\item[Note:] \hfill
210
211The same note applies to {\tt number}, {\tt indices} and {\tt values} as in
212the previous function.
213
214\ed
215
216\vspace{1ex}
217
218%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
219% user_finished_to_check_cuts
220%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
221
222\functiondef{user\_finished\_checking\_cuts}
223\begin{verbatim}
224int user_finished_checking_cuts(void *user)
225\end{verbatim}
226
227\bd
228
229\item[Description:] \hfill
230
231When this function is invoked there are no more cuts to be checked, so the
232user can dismantle data structures he created in {\tt
233\htmlref{user\_prepare\_to\_check\_cuts}{user_prepare_to_check_cuts}}. Also,
234if he received and stored the LP solution himself he can delete it now.
235
236\item[Arguments:] \hfill
237
238\bt{llp{250pt}}
239{\tt void *user} & IN & Pointer to the user-defined data structure. \\
240\et
241
242\returns
243
244\bt{lp{300pt}}
245{\tt USER\_ERROR} & Ignored. \\
246{\tt USER\_SUCCESS} & The user function exited properly. \\
247{\tt USER\_DEFAULT} & There are no user-defined cuts in the pool. \\
248\et
249
250\item[Invoked from:] After all cuts have been checked.
251
252\ed
253
254\vspace{1ex}
255
256%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
257% user_free_cp
258%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
259
260\functiondef{user\_free\_cp}
261\begin{verbatim}
262int user_free_cp(void **user)
263\end{verbatim}
264
265\bd
266
267\item[Description:] \hfill
268
269The user has to free all the data structures within {\tt user}, and also free
270{\tt user} itself. The user can use the built-in macro {\tt FREE} that checks
271the existence of a pointer before freeing it.
272
273\item[Arguments:] \hfill
274
275\bt{llp{280pt}}
276{\tt void **user} & INOUT & Pointer to the user-defined data structure
277(should be {\tt NULL} on exit). \\
278\et
279
280\returns
281
282\bt{lp{300pt}}
283{\tt USER\_ERROR} & Ignored. \\
284{\tt USER\_SUCCESS} & The user freed all data structures. \\
285{\tt USER\_DEFAULT} & There is nothing to be freed. \\
286\et
287
288\item[Invoked from:] cp\_close() at module shutdown.
289
290\ed
291
292\vspace{1ex}
293
294%begin{latexonly}
295\ed
296%end{latexonly}
Note: See TracBrowser for help on using the repository browser.