<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 Solve() and IncrementalSolver.</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 Callback as an optional argument to Solve() and</span></div>
<divclass="line"><aid="l00019"name="l00019"></a><spanclass="lineno"> 19</span><spanclass="comment">// IncrementalSolver::Solve(). This function is called periodically throughout</span></div>
<divclass="line"><aid="l00020"name="l00020"></a><spanclass="lineno"> 20</span><spanclass="comment">// the solve process. This file defines the data types needed to use this</span></div>
<divclass="line"><aid="l00023"name="l00023"></a><spanclass="lineno"> 23</span><spanclass="comment">// The example below registers a callback that listens for feasible solutions</span></div>
<divclass="line"><aid="l00024"name="l00024"></a><spanclass="lineno"> 24</span><spanclass="comment">// the solvers finds along the way and accumulates them in a list for analysis</span></div>
<divclass="line"><aid="l00025"name="l00025"></a><spanclass="lineno"> 25</span><spanclass="comment">// after the solve.</span></div>
<divclass="line"><aid="l00027"name="l00027"></a><spanclass="lineno"> 27</span><spanclass="comment">// using ::operations_research::math_opt::CallbackData;</span></div>
<divclass="line"><aid="l00028"name="l00028"></a><spanclass="lineno"> 28</span><spanclass="comment">// using ::operations_research::math_opt::CallbackRegistration;</span></div>
<divclass="line"><aid="l00029"name="l00029"></a><spanclass="lineno"> 29</span><spanclass="comment">// using ::operations_research::math_opt::CallbackResult;</span></div>
<divclass="line"><aid="l00030"name="l00030"></a><spanclass="lineno"> 30</span><spanclass="comment">// using ::operations_research::math_opt::Model;</span></div>
<divclass="line"><aid="l00031"name="l00031"></a><spanclass="lineno"> 31</span><spanclass="comment">// using ::operations_research::math_opt::SolveResult;</span></div>
<divclass="line"><aid="l00032"name="l00032"></a><spanclass="lineno"> 32</span><spanclass="comment">// using ::operations_research::math_opt::Solve;</span></div>
<divclass="line"><aid="l00033"name="l00033"></a><spanclass="lineno"> 33</span><spanclass="comment">// using ::operations_research::math_opt::Variable;</span></div>
<divclass="line"><aid="l00034"name="l00034"></a><spanclass="lineno"> 34</span><spanclass="comment">// using ::operations_research::math_opt::VariableMap;</span></div>
<divclass="line"><aid="l00043"name="l00043"></a><spanclass="lineno"> 43</span><spanclass="comment">// auto cb = [&solutions](const CallbackData& cb_data) {</span></div>
<divclass="line"><aid="l00044"name="l00044"></a><spanclass="lineno"> 44</span><spanclass="comment">// // NOTE: this assumes the callback is always called from the same thread.</span></div>
<divclass="line"><aid="l00045"name="l00045"></a><spanclass="lineno"> 45</span><spanclass="comment">// // Gurobi always does this, multi-threaded SCIP does not.</span></div>
<divclass="line"><aid="l00053"name="l00053"></a><spanclass="lineno"> 53</span><spanclass="comment">// At the termination of the example, solutions will have {{x, 1.0}}, and</span></div>
<divclass="line"><aid="l00054"name="l00054"></a><spanclass="lineno"> 54</span><spanclass="comment">// possibly {{x, 0.0}} as well.</span></div>
<divclass="line"><aid="l00056"name="l00056"></a><spanclass="lineno"> 56</span><spanclass="comment">// If the callback argument to Solve() is not null, it will be invoked on the</span></div>
<divclass="line"><aid="l00057"name="l00057"></a><spanclass="lineno"> 57</span><spanclass="comment">// events specified by the callback_registration argument (and when the</span></div>
<divclass="line"><aid="l00058"name="l00058"></a><spanclass="lineno"> 58</span><spanclass="comment">// callback is null, callback_registration must not request any events or will</span></div>
<divclass="line"><aid="l00059"name="l00059"></a><spanclass="lineno"> 59</span><spanclass="comment">// CHECK fail). Some solvers do not support callbacks or certain events, in this</span></div>
<divclass="line"><aid="l00060"name="l00060"></a><spanclass="lineno"> 60</span><spanclass="comment">// case the callback is ignored. TODO(b/180617976): change this behavior.</span></div>
<divclass="line"><aid="l00062"name="l00062"></a><spanclass="lineno"> 62</span><spanclass="comment">// Some solvers may call callback from multiple threads (SCIP will, Gurobi will</span></div>
<divclass="line"><aid="l00063"name="l00063"></a><spanclass="lineno"> 63</span><spanclass="comment">// not). You should either solve with one thread (see</span></div>
<divclass="line"><aid="l00064"name="l00064"></a><spanclass="lineno"> 64</span><spanclass="comment">// solver_parameters.threads), write a threadsafe callback, or consult</span></div>
<divclass="line"><aid="l00065"name="l00065"></a><spanclass="lineno"> 65</span><spanclass="comment">// the documentation of your underlying solver.</span></div>
<divclass="line"><aid="l00091"name="l00091"></a><spanclass="lineno"> 91</span><spanclass="comment">// The supported events for LP/MIP callbacks.</span></div>
<divclass="line"><aid="l00093"name="l00093"></a><spanclass="lineno"> 93</span><spanclass="comment">// The solver is currently running presolve.</span></div>
<divclass="line"><aid="l00095"name="l00095"></a><spanclass="lineno"> 95</span><spanclass="comment">// This event is supported for MIP & LP models by SolverType::kGurobi. Other</span></div>
<divclass="line"><aid="l00096"name="l00096"></a><spanclass="lineno"> 96</span><spanclass="comment">// solvers don't support this event.</span></div>
<divclass="line"><aid="l00099"name="l00099"></a><spanclass="lineno"> 99</span><spanclass="comment">// The solver is currently running the simplex method.</span></div>
<divclass="line"><aid="l00101"name="l00101"></a><spanclass="lineno"> 101</span><spanclass="comment">// This event is supported for MIP & LP models by SolverType::kGurobi. Other</span></div>
<divclass="line"><aid="l00102"name="l00102"></a><spanclass="lineno"> 102</span><spanclass="comment">// solvers don't support this event.</span></div>
<divclass="line"><aid="l00105"name="l00105"></a><spanclass="lineno"> 105</span><spanclass="comment">// The solver is in the MIP loop (called periodically before starting a new</span></div>
<divclass="line"><aid="l00106"name="l00106"></a><spanclass="lineno"> 106</span><spanclass="comment">// node). Useful for early termination. Note that this event does not provide</span></div>
<divclass="line"><aid="l00107"name="l00107"></a><spanclass="lineno"> 107</span><spanclass="comment">// information on LP relaxations nor about new incumbent solutions.</span></div>
<divclass="line"><aid="l00109"name="l00109"></a><spanclass="lineno"> 109</span><spanclass="comment">// This event is supported for MIP models only by SolverType::kGurobi. Other</span></div>
<divclass="line"><aid="l00110"name="l00110"></a><spanclass="lineno"> 110</span><spanclass="comment">// solvers don't support this event.</span></div>
<divclass="line"><aid="l00113"name="l00113"></a><spanclass="lineno"> 113</span><spanclass="comment">// Called every time a new MIP incumbent is found.</span></div>
<divclass="line"><aid="l00115"name="l00115"></a><spanclass="lineno"> 115</span><spanclass="comment">// This event is fully supported for MIP models by SolverType::kGurobi. CP-SAT</span></div>
<divclass="line"><aid="l00116"name="l00116"></a><spanclass="lineno"> 116</span><spanclass="comment">// has partial support: you can view the solutions and request termination,</span></div>
<divclass="line"><aid="l00117"name="l00117"></a><spanclass="lineno"> 117</span><spanclass="comment">// but you cannot add lazy constraints. Other solvers don't support this</span></div>
<divclass="line"><aid="l00121"name="l00121"></a><spanclass="lineno"> 121</span><spanclass="comment">// Called inside a MIP node. Note that there is no guarantee that the</span></div>
<divclass="line"><aid="l00122"name="l00122"></a><spanclass="lineno"> 122</span><spanclass="comment">// callback function will be called on every node. That behavior is</span></div>
<divclass="line"><aid="l00125"name="l00125"></a><spanclass="lineno"> 125</span><spanclass="comment">// Disabling cuts using CommonSolveParameters may interfere with this event</span></div>
<divclass="line"><aid="l00126"name="l00126"></a><spanclass="lineno"> 126</span><spanclass="comment">// being called and/or adding cuts at this event, the behavior is solver</span></div>
<divclass="line"><aid="l00129"name="l00129"></a><spanclass="lineno"> 129</span><spanclass="comment">// This event is supported for MIP models only by SolverType::kGurobi. Other</span></div>
<divclass="line"><aid="l00130"name="l00130"></a><spanclass="lineno"> 130</span><spanclass="comment">// solvers don't support this event.</span></div>
<divclass="line"><aid="l00133"name="l00133"></a><spanclass="lineno"> 133</span><spanclass="comment">// Called in each iterate of an interior point/barrier method.</span></div>
<divclass="line"><aid="l00135"name="l00135"></a><spanclass="lineno"> 135</span><spanclass="comment">// This event is supported for LP models only by SolverType::kGurobi. Other</span></div>
<divclass="line"><aid="l00136"name="l00136"></a><spanclass="lineno"> 136</span><spanclass="comment">// solvers don't support this event.</span></div>
<divclass="line"><aid="l00142"name="l00142"></a><spanclass="lineno"> 142</span><spanclass="comment">// Provided with a callback at the start of a Solve() to inform the solver:</span></div>
<divclass="line"><aid="l00143"name="l00143"></a><spanclass="lineno"> 143</span><spanclass="comment">// * what information the callback needs,</span></div>
<divclass="line"><aid="l00144"name="l00144"></a><spanclass="lineno"> 144</span><spanclass="comment">// * how the callback might alter the solve process.</span></div>
<divclass="line"><aid="l00146"name="l00146"></a><spanclass="lineno"> 146</span><spanclass="comment">// Will CHECK fail if referenced variables are not from the same model.</span></div>
<divclass="line"><aid="l00149"name="l00149"></a><spanclass="lineno"> 149</span><spanclass="comment">// Returns the model referenced variables, or null if no variables are</span></div>
<divclass="line"><aid="l00150"name="l00150"></a><spanclass="lineno"> 150</span><spanclass="comment">// referenced. Will CHECK fail if variables are not from the same model.</span></div>
<divclass="line"><aid="l00153"name="l00153"></a><spanclass="lineno"> 153</span><spanclass="comment">// The events the solver should invoke the callback at.</span></div>
<divclass="line"><aid="l00155"name="l00155"></a><spanclass="lineno"> 155</span><spanclass="comment">// A solver will return an InvalidArgument status when called with registered</span></div>
<divclass="line"><aid="l00156"name="l00156"></a><spanclass="lineno"> 156</span><spanclass="comment">// events that are not supported for the selected solver and the type of</span></div>
<divclass="line"><aid="l00157"name="l00157"></a><spanclass="lineno"> 157</span><spanclass="comment">// model. For example registring for CallbackEvent::kMip with a model that</span></div>
<divclass="line"><aid="l00158"name="l00158"></a><spanclass="lineno"> 158</span><spanclass="comment">// only contains continuous variables will fail for most solvers (see the</span></div>
<divclass="line"><aid="l00159"name="l00159"></a><spanclass="lineno"> 159</span><spanclass="comment">// documentation of each event to see which solvers support them and in which</span></div>
<divclass="line"><aid="l00163"name="l00163"></a><spanclass="lineno"> 163</span><spanclass="comment">// Restricts the variable returned in CallbackData.solution for event</span></div>
<divclass="line"><aid="l00164"name="l00164"></a><spanclass="lineno"> 164</span><spanclass="comment">// CallbackEvent::kMipSolution. This can improve performance.</span></div>
<divclass="line"><aid="l00167"name="l00167"></a><spanclass="lineno"> 167</span><spanclass="comment">// Restricts the variable returned in CallbackData.solution for event</span></div>
<divclass="line"><aid="l00168"name="l00168"></a><spanclass="lineno"> 168</span><spanclass="comment">// CallbackEvent::kMipNode. This can improve performance.</span></div>
<divclass="line"><aid="l00171"name="l00171"></a><spanclass="lineno"> 171</span><spanclass="comment">// If the callback will ever add "user cuts" at event CallbackEvent::kMipNode</span></div>
<divclass="line"><aid="l00172"name="l00172"></a><spanclass="lineno"> 172</span><spanclass="comment">// during the solve process (a linear constraint that excludes the current LP</span></div>
<divclass="line"><aid="l00173"name="l00173"></a><spanclass="lineno"> 173</span><spanclass="comment">// solution but does not cut off any integer points).</span></div>
<divclass="line"><aid="l00176"name="l00176"></a><spanclass="lineno"> 176</span><spanclass="comment">// If the callback will ever add "lazy constraints" at event</span></div>
<divclass="line"><aid="l00177"name="l00177"></a><spanclass="lineno"> 177</span><spanclass="comment">// CallbackEvent::kMipNode or CallbackEvent::kMipSolution during the solve</span></div>
<divclass="line"><aid="l00178"name="l00178"></a><spanclass="lineno"> 178</span><spanclass="comment">// process (a linear constraint that excludes integer points).</span></div>
<divclass="line"><aid="l00182"name="l00182"></a><spanclass="lineno"> 182</span><spanclass="comment">// The input to the Callback function.</span></div>
<divclass="line"><aid="l00184"name="l00184"></a><spanclass="lineno"> 184</span><spanclass="comment">// The information available depends on the current event.</span></div>
<divclass="line"><aid="l00186"name="l00186"></a><spanclass="lineno"> 186</span><spanclass="comment">// Users will typically not need this function.</span></div>
<divclass="line"><aid="l00187"name="l00187"></a><spanclass="lineno"> 187</span><spanclass="comment">// Will CHECK fail if proto is not valid.</span></div>
<divclass="line"><aid="l00190"name="l00190"></a><spanclass="lineno"> 190</span><spanclass="comment">// The current state of the underlying solver.</span></div>
<divclass="line"><aid="l00193"name="l00193"></a><spanclass="lineno"> 193</span><spanclass="comment">// If event == CallbackEvent::kMipNode, the primal_solution contains the</span></div>
<divclass="line"><aid="l00194"name="l00194"></a><spanclass="lineno"> 194</span><spanclass="comment">// primal solution to the current LP-node relaxation. In some cases, no</span></div>
<divclass="line"><aid="l00195"name="l00195"></a><spanclass="lineno"> 195</span><spanclass="comment">// solution will be available (e.g. because LP was infeasible or the solve</span></div>
<divclass="line"><aid="l00196"name="l00196"></a><spanclass="lineno"> 196</span><spanclass="comment">// was imprecise).</span></div>
<divclass="line"><aid="l00197"name="l00197"></a><spanclass="lineno"> 197</span><spanclass="comment">// If event == CallbackEvent::kMipSolution, the primal_solution contains the</span></div>
<divclass="line"><aid="l00198"name="l00198"></a><spanclass="lineno"> 198</span><spanclass="comment">// newly found primal (integer) feasible solution. The solution is always</span></div>
<divclass="line"><aid="l00200"name="l00200"></a><spanclass="lineno"> 200</span><spanclass="comment">// Otherwise, the primal_solution is not available.</span></div>
<divclass="line"><aid="l00203"name="l00203"></a><spanclass="lineno"> 203</span><spanclass="comment">// Time since `Solve()` was called. Available for all events except</span></div>
<divclass="line"><aid="l00207"name="l00207"></a><spanclass="lineno"> 207</span><spanclass="comment">// Only available for event == CallbackEvent::kPresolve.</span></div>
<divclass="line"><aid="l00210"name="l00210"></a><spanclass="lineno"> 210</span><spanclass="comment">// Only available for event == CallbackEvent::kSimplex.</span></div>
<divclass="line"><aid="l00213"name="l00213"></a><spanclass="lineno"> 213</span><spanclass="comment">// Only available for event == CallbackEvent::kBarrier.</span></div>
<divclass="line"><aid="l00216"name="l00216"></a><spanclass="lineno"> 216</span><spanclass="comment">// Only available for event of CallbackEvent::kMip, CallbackEvent::kMipNode,</span></div>
<divclass="line"><aid="l00217"name="l00217"></a><spanclass="lineno"> 217</span><spanclass="comment">// or CallbackEvent::kMipSolution.</span></div>
<divclass="line"><aid="l00221"name="l00221"></a><spanclass="lineno"> 221</span><spanclass="comment">// The value returned by the Callback function.</span></div>
<divclass="line"><aid="l00223"name="l00223"></a><spanclass="lineno"> 223</span><spanclass="comment">// Prefer AddUserCut and AddLazyConstraint below instead of using this</span></div>
<divclass="line"><aid="l00234"name="l00234"></a><spanclass="lineno"> 234</span><spanclass="comment">// Adds a "user cut," a linear constraint that excludes the current LP</span></div>
<divclass="line"><aid="l00235"name="l00235"></a><spanclass="lineno"> 235</span><spanclass="comment">// solution but does not cut off any integer points. Use only for</span></div>
<divclass="line"><aid="l00241"name="l00241"></a><spanclass="lineno"> 241</span><spanclass="comment">// Adds a "lazy constraint," a linear constraint that excludes integer points.</span></div>
<divclass="line"><aid="l00242"name="l00242"></a><spanclass="lineno"> 242</span><spanclass="comment">// Use only for CallbackEvent::kMipNode and CallbackEvent::kMipSolution.</span></div>
<divclass="line"><aid="l00247"name="l00247"></a><spanclass="lineno"> 247</span><spanclass="comment">// Will CHECK fail if referenced variables are not from the same model.</span></div>
<divclass="line"><aid="l00250"name="l00250"></a><spanclass="lineno"> 250</span><spanclass="comment">// Returns the model referenced variables, or null if no variables are</span></div>
<divclass="line"><aid="l00251"name="l00251"></a><spanclass="lineno"> 251</span><spanclass="comment">// referenced. Will CHECK fail if variables are not from the same model.</span></div>
<divclass="line"><aid="l00253"name="l00253"></a><spanclass="lineno"> 253</span><spanclass="comment">// Runs in O(num constraints + num suggested solutions).</span></div>
<divclass="line"><aid="l00256"name="l00256"></a><spanclass="lineno"> 256</span><spanclass="comment">// Stop the solve process and return early. Can be called from any event.</span></div>
<divclass="line"><aid="l00259"name="l00259"></a><spanclass="lineno"> 259</span><spanclass="comment">// The user cuts and lazy constraints added. Prefer AddUserCut() and</span></div>
<divclass="line"><aid="l00260"name="l00260"></a><spanclass="lineno"> 260</span><spanclass="comment">// AddLazyConstraint() to modifying this directly.</span></div>
<divclass="line"><aid="l00263"name="l00263"></a><spanclass="lineno"> 263</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>
