<ahref="callback_8h.html">Go to the documentation of this file.</a><divclass="fragment"><divclass="line"><aid="l00001"name="l00001"></a><spanclass="lineno"> 1</span><spanclass="comment">// Copyright 2010-2021 Google LLC</span></div>
<divclass="line"><aid="l00002"name="l00002"></a><spanclass="lineno"> 2</span><spanclass="comment">// Licensed under the Apache License, Version 2.0 (the "License");</span></div>
<divclass="line"><aid="l00003"name="l00003"></a><spanclass="lineno"> 3</span><spanclass="comment">// you may not use this file except in compliance with the License.</span></div>
<divclass="line"><aid="l00004"name="l00004"></a><spanclass="lineno"> 4</span><spanclass="comment">// You may obtain a copy of the License at</span></div>
<divclass="line"><aid="l00008"name="l00008"></a><spanclass="lineno"> 8</span><spanclass="comment">// Unless required by applicable law or agreed to in writing, software</span></div>
<divclass="line"><aid="l00009"name="l00009"></a><spanclass="lineno"> 9</span><spanclass="comment">// distributed under the License is distributed on an "AS IS" BASIS,</span></div>
<divclass="line"><aid="l00010"name="l00010"></a><spanclass="lineno"> 10</span><spanclass="comment">// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span></div>
<divclass="line"><aid="l00011"name="l00011"></a><spanclass="lineno"> 11</span><spanclass="comment">// See the License for the specific language governing permissions and</span></div>
<divclass="line"><aid="l00012"name="l00012"></a><spanclass="lineno"> 12</span><spanclass="comment">// limitations under the License.</span></div>
<divclass="line"><aid="l00014"name="l00014"></a><spanclass="lineno"> 14</span><spanclass="comment">// Data types for using callbacks with MathOpt.</span></div>
<divclass="line"><aid="l00016"name="l00016"></a><spanclass="lineno"> 16</span><spanclass="comment">// Callbacks allow to user to observe the progress of a solver and modify its</span></div>
<divclass="line"><aid="l00017"name="l00017"></a><spanclass="lineno"> 17</span><spanclass="comment">// behavior mid solve. This is supported by allowing the user to a function of</span></div>
<divclass="line"><aid="l00018"name="l00018"></a><spanclass="lineno"> 18</span><spanclass="comment">// type MathOpt::Callback as an optional argument to MathOpt::Solve(). This</span></div>
<divclass="line"><aid="l00019"name="l00019"></a><spanclass="lineno"> 19</span><spanclass="comment">// function is called periodically throughout the solve process. This file</span></div>
<divclass="line"><aid="l00020"name="l00020"></a><spanclass="lineno"> 20</span><spanclass="comment">// defines the data types needed to use this callback.</span></div>
<divclass="line"><aid="l00022"name="l00022"></a><spanclass="lineno"> 22</span><spanclass="comment">// The example below registers a callback that listens for feasible solutions</span></div>
<divclass="line"><aid="l00023"name="l00023"></a><spanclass="lineno"> 23</span><spanclass="comment">// the solvers finds along the way and accumulates them in a list for analysis</span></div>
<divclass="line"><aid="l00024"name="l00024"></a><spanclass="lineno"> 24</span><spanclass="comment">// after the solve.</span></div>
<divclass="line"><aid="l00026"name="l00026"></a><spanclass="lineno"> 26</span><spanclass="comment">// using ::operations_research::math_opt::CallbackData;</span></div>
<divclass="line"><aid="l00027"name="l00027"></a><spanclass="lineno"> 27</span><spanclass="comment">// using ::operations_research::math_opt::CallbackRegistration;</span></div>
<divclass="line"><aid="l00028"name="l00028"></a><spanclass="lineno"> 28</span><spanclass="comment">// using ::operations_research::math_opt::CallbackResult;</span></div>
<divclass="line"><aid="l00029"name="l00029"></a><spanclass="lineno"> 29</span><spanclass="comment">// using ::operations_research::math_opt::MathOpt;</span></div>
<divclass="line"><aid="l00030"name="l00030"></a><spanclass="lineno"> 30</span><spanclass="comment">// using ::operations_research::math_opt::Result;</span></div>
<divclass="line"><aid="l00031"name="l00031"></a><spanclass="lineno"> 31</span><spanclass="comment">// using ::operations_research::math_opt::Variable;</span></div>
<divclass="line"><aid="l00032"name="l00032"></a><spanclass="lineno"> 32</span><spanclass="comment">// using ::operations_research::math_opt::VariableMap;</span></div>
<divclass="line"><aid="l00041"name="l00041"></a><spanclass="lineno"> 41</span><spanclass="comment">// auto cb = [&solutions](const CallbackData& cb_data) {</span></div>
<divclass="line"><aid="l00042"name="l00042"></a><spanclass="lineno"> 42</span><spanclass="comment">// // NOTE: this assumes the callback is always called from the same thread.</span></div>
<divclass="line"><aid="l00043"name="l00043"></a><spanclass="lineno"> 43</span><spanclass="comment">// // Gurobi always does this, multi-threaded SCIP does not.</span></div>
<divclass="line"><aid="l00049"name="l00049"></a><spanclass="lineno"> 49</span><spanclass="comment">// At the termination of the example, solutions will have {{x, 1.0}}, and</span></div>
<divclass="line"><aid="l00050"name="l00050"></a><spanclass="lineno"> 50</span><spanclass="comment">// possibly {{x, 0.0}} as well.</span></div>
<divclass="line"><aid="l00052"name="l00052"></a><spanclass="lineno"> 52</span><spanclass="comment">// If the callback argument to MathOpt::Solve() is not null, it will be invoked</span></div>
<divclass="line"><aid="l00053"name="l00053"></a><spanclass="lineno"> 53</span><spanclass="comment">// on the events specified by the callback_registration argument (and when the</span></div>
<divclass="line"><aid="l00054"name="l00054"></a><spanclass="lineno"> 54</span><spanclass="comment">// callback is null, callback_registration must not request any events or will</span></div>
<divclass="line"><aid="l00055"name="l00055"></a><spanclass="lineno"> 55</span><spanclass="comment">// CHECK fail). Some solvers do not support callbacks or certain events, in this</span></div>
<divclass="line"><aid="l00056"name="l00056"></a><spanclass="lineno"> 56</span><spanclass="comment">// case the callback is ignored. TODO(b/180617976): change this behavior.</span></div>
<divclass="line"><aid="l00058"name="l00058"></a><spanclass="lineno"> 58</span><spanclass="comment">// Some solvers may call callback from multiple threads (SCIP will, Gurobi</span></div>
<divclass="line"><aid="l00059"name="l00059"></a><spanclass="lineno"> 59</span><spanclass="comment">// will not). You should either solve with one thread (see</span></div>
<divclass="line"><aid="l00060"name="l00060"></a><spanclass="lineno"> 60</span><spanclass="comment">// solver_parameters.common_parameters.threads), write a threadsafe callback,</span></div>
<divclass="line"><aid="l00061"name="l00061"></a><spanclass="lineno"> 61</span><spanclass="comment">// or consult the documentation of your underlying solver.</span></div>
<divclass="line"><aid="l00080"name="l00080"></a><spanclass="lineno"> 80</span><spanclass="comment">// The input to the MathOpt::Callback function.</span></div>
<divclass="line"><aid="l00082"name="l00082"></a><spanclass="lineno"> 82</span><spanclass="comment">// The information available depends on the current event.</span></div>
<divclass="line"><aid="l00084"name="l00084"></a><spanclass="lineno"> 84</span><spanclass="comment">// Users will typically not need this function.</span></div>
<divclass="line"><aid="l00085"name="l00085"></a><spanclass="lineno"> 85</span><spanclass="comment">// Will CHECK fail if proto is not valid.</span></div>
<divclass="line"><aid="l00089"name="l00089"></a><spanclass="lineno"> 89</span><spanclass="comment">// The current state of the underlying solver.</span></div>
<divclass="line"><aid="l00092"name="l00092"></a><spanclass="lineno"> 92</span><spanclass="comment">// If event == CALLBACK_EVENT_MIP_NODE, the primal_solution contains the</span></div>
<divclass="line"><aid="l00093"name="l00093"></a><spanclass="lineno"> 93</span><spanclass="comment">// primal solution to the current LP-node relaxation. In some cases, no</span></div>
<divclass="line"><aid="l00094"name="l00094"></a><spanclass="lineno"> 94</span><spanclass="comment">// solution will be available (e.g. because LP was infeasible or the solve</span></div>
<divclass="line"><aid="l00095"name="l00095"></a><spanclass="lineno"> 95</span><spanclass="comment">// was imprecise).</span></div>
<divclass="line"><aid="l00096"name="l00096"></a><spanclass="lineno"> 96</span><spanclass="comment">// If event == CALLBACK_EVENT_MIP_SOLUTION, the primal_solution contains the</span></div>
<divclass="line"><aid="l00097"name="l00097"></a><spanclass="lineno"> 97</span><spanclass="comment">// newly found primal (integer) feasible solution. The solution is always</span></div>
<divclass="line"><aid="l00099"name="l00099"></a><spanclass="lineno"> 99</span><spanclass="comment">// Otherwise, the primal_solution is not available.</span></div>
<divclass="line"><aid="l00102"name="l00102"></a><spanclass="lineno"> 102</span><spanclass="comment">// If event == CALLBACK_EVENT_MESSAGE, contains the messages from the solver.</span></div>
<divclass="line"><aid="l00103"name="l00103"></a><spanclass="lineno"> 103</span><spanclass="comment">// Each message represents a single output line from the solver, and each</span></div>
<divclass="line"><aid="l00104"name="l00104"></a><spanclass="lineno"> 104</span><spanclass="comment">// message does not contain any '\n' characters.</span></div>
<divclass="line"><aid="l00105"name="l00105"></a><spanclass="lineno"> 105</span><spanclass="comment">// Otherwise, messages is empty.</span></div>
<divclass="line"><aid="l00108"name="l00108"></a><spanclass="lineno"> 108</span><spanclass="comment">// Time since `Solve()` was called. Available for all events except</span></div>
<divclass="line"><aid="l00112"name="l00112"></a><spanclass="lineno"> 112</span><spanclass="comment">// Only available for event == CALLBACK_EVENT_PRESOLVE.</span></div>
<divclass="line"><aid="l00115"name="l00115"></a><spanclass="lineno"> 115</span><spanclass="comment">// Only available for event == CALLBACK_EVENT_SIMPLEX.</span></div>
<divclass="line"><aid="l00118"name="l00118"></a><spanclass="lineno"> 118</span><spanclass="comment">// Only available for event == CALLBACK_EVENT_BARRIER.</span></div>
<divclass="line"><aid="l00121"name="l00121"></a><spanclass="lineno"> 121</span><spanclass="comment">// Only available for event of CALLBACK_EVENT_MIP, CALLBACK_EVENT_MIP_NODE, or</span></div>
<divclass="line"><aid="l00126"name="l00126"></a><spanclass="lineno"> 126</span><spanclass="comment">// Provided with a callback at the start of a Solve() to inform the solver:</span></div>
<divclass="line"><aid="l00127"name="l00127"></a><spanclass="lineno"> 127</span><spanclass="comment">// * what information the callback needs,</span></div>
<divclass="line"><aid="l00128"name="l00128"></a><spanclass="lineno"> 128</span><spanclass="comment">// * how the callback might alter the solve process.</span></div>
<divclass="line"><aid="l00130"name="l00130"></a><spanclass="lineno"> 130</span><spanclass="comment">// Will CHECK fail if referenced variables are not from the same model.</span></div>
<divclass="line"><aid="l00133"name="l00133"></a><spanclass="lineno"> 133</span><spanclass="comment">// Returns the model referenced variables, or null if no variables are</span></div>
<divclass="line"><aid="l00134"name="l00134"></a><spanclass="lineno"> 134</span><spanclass="comment">// referenced. Will CHECK fail if variables are not from the same model.</span></div>
<divclass="line"><aid="l00137"name="l00137"></a><spanclass="lineno"> 137</span><spanclass="comment">// The events the solver should invoke the callback at.</span></div>
<divclass="line"><aid="l00140"name="l00140"></a><spanclass="lineno"> 140</span><spanclass="comment">// Restricts the variable returned in CallbackData.solution for event</span></div>
<divclass="line"><aid="l00141"name="l00141"></a><spanclass="lineno"> 141</span><spanclass="comment">// CALLBACK_EVENT_MIP_SOLUTION. This can improve performance.</span></div>
<divclass="line"><aid="l00144"name="l00144"></a><spanclass="lineno"> 144</span><spanclass="comment">// Restricts the variable returned in CallbackData.solution for event</span></div>
<divclass="line"><aid="l00145"name="l00145"></a><spanclass="lineno"> 145</span><spanclass="comment">// CALLBACK_EVENT_MIP_NODE. This can improve performance.</span></div>
<divclass="line"><aid="l00148"name="l00148"></a><spanclass="lineno"> 148</span><spanclass="comment">// If the callback will ever add "user cuts" at event CALLBACK_EVENT_MIP_NODE</span></div>
<divclass="line"><aid="l00149"name="l00149"></a><spanclass="lineno"> 149</span><spanclass="comment">// during the solve process (a linear constraint that excludes the current LP</span></div>
<divclass="line"><aid="l00150"name="l00150"></a><spanclass="lineno"> 150</span><spanclass="comment">// solution but does not cut off any integer points).</span></div>
<divclass="line"><aid="l00153"name="l00153"></a><spanclass="lineno"> 153</span><spanclass="comment">// If the callback will ever add "lazy constraints" at event</span></div>
<divclass="line"><aid="l00154"name="l00154"></a><spanclass="lineno"> 154</span><spanclass="comment">// CALLBACK_EVENT_MIP_NODE or CALLBACK_EVENT_MIP_SOLUTION during the solve</span></div>
<divclass="line"><aid="l00155"name="l00155"></a><spanclass="lineno"> 155</span><spanclass="comment">// process (a linear constraint that excludes integer points).</span></div>
<divclass="line"><aid="l00159"name="l00159"></a><spanclass="lineno"> 159</span><spanclass="comment">// The value returned by the MathOpt::Callback function.</span></div>
<divclass="line"><aid="l00161"name="l00161"></a><spanclass="lineno"> 161</span><spanclass="comment">// Prefer AddUserCut and AddLazyConstraint below instead of using this</span></div>
<divclass="line"><aid="l00170"name="l00170"></a><spanclass="lineno"> 170</span><spanclass="comment">// Adds a "user cut," a linear constraint that excludes the current LP</span></div>
<divclass="line"><aid="l00171"name="l00171"></a><spanclass="lineno"> 171</span><spanclass="comment">// solution but does not cut off any integer points. Use only for</span></div>
<divclass="line"><aid="l00177"name="l00177"></a><spanclass="lineno"> 177</span><spanclass="comment">// Adds a "lazy constraint," a linear constraint that excludes integer points.</span></div>
<divclass="line"><aid="l00178"name="l00178"></a><spanclass="lineno"> 178</span><spanclass="comment">// Use only for CALLBACK_EVENT_MIP_NODE and CALLBACK_EVENT_MIP_SOLUTION.</span></div>
<divclass="line"><aid="l00183"name="l00183"></a><spanclass="lineno"> 183</span><spanclass="comment">// Will CHECK fail if referenced variables are not from the same model.</span></div>
<divclass="line"><aid="l00186"name="l00186"></a><spanclass="lineno"> 186</span><spanclass="comment">// Returns the model referenced variables, or null if no variables are</span></div>
<divclass="line"><aid="l00187"name="l00187"></a><spanclass="lineno"> 187</span><spanclass="comment">// referenced. Will CHECK fail if variables are not from the same model.</span></div>
<divclass="line"><aid="l00189"name="l00189"></a><spanclass="lineno"> 189</span><spanclass="comment">// Runs in O(num constraints + num suggested solutions).</span></div>
<divclass="line"><aid="l00192"name="l00192"></a><spanclass="lineno"> 192</span><spanclass="comment">// Stop the solve process and return early. Can be called from any event.</span></div>
<divclass="line"><aid="l00195"name="l00195"></a><spanclass="lineno"> 195</span><spanclass="comment">// The user cuts and lazy constraints added. Prefer AddUserCut() and</span></div>
<divclass="line"><aid="l00196"name="l00196"></a><spanclass="lineno"> 196</span><spanclass="comment">// AddLazyConstraint() to modifying this directly.</span></div>
<divclass="line"><aid="l00199"name="l00199"></a><spanclass="lineno"> 199</span><spanclass="comment">// A solution or partially defined solution to give to the solver.</span></div>
<divclass="ttc"id="anamespaceoperations__research_html"><divclass="ttname"><ahref="namespaceoperations__research.html">operations_research</a></div><divclass="ttdoc">Collection of objects used to extend the Constraint Solver library.</div><divclass="ttdef"><b>Definition:</b><ahref="dense__doubly__linked__list_8h_source.html#l00021">dense_doubly_linked_list.h:21</a></div></div>
