<ahref="solve_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">// Functions and classes used to solve a Model.</span></div>
<divclass="line"><aid="l00016"name="l00016"></a><spanclass="lineno"> 16</span><spanclass="comment">// The main entry point is the Solve() function.</span></div>
<divclass="line"><aid="l00018"name="l00018"></a><spanclass="lineno"> 18</span><spanclass="comment">// For users that need incremental solving, there is the IncrementalSolver</span></div>
<divclass="line"><aid="l00042"name="l00042"></a><spanclass="lineno"> 42</span><spanclass="comment">// A Status error will be returned if there is an unexpected failure in an</span></div>
<divclass="line"><aid="l00043"name="l00043"></a><spanclass="lineno"> 43</span><spanclass="comment">// underlying solver or for some internal math_opt errors. Otherwise, check</span></div>
<divclass="line"><aid="l00044"name="l00044"></a><spanclass="lineno"> 44</span><spanclass="comment">// SolveResult::termination.reason to see if an optimal solution was found.</span></div>
<divclass="line"><aid="l00046"name="l00046"></a><spanclass="lineno"> 46</span><spanclass="comment">// Memory model: the returned SolveResult owns its own memory (for solutions,</span></div>
<divclass="line"><aid="l00047"name="l00047"></a><spanclass="lineno"> 47</span><spanclass="comment">// solve stats, etc.), EXPECT for a pointer back to the model. As a result:</span></div>
<divclass="line"><aid="l00048"name="l00048"></a><spanclass="lineno"> 48</span><spanclass="comment">// * Keep the model alive to access SolveResult,</span></div>
<divclass="line"><aid="l00050"name="l00050"></a><spanclass="lineno"> 50</span><spanclass="comment">// * The result is generally accessible after mutating the model, but some care</span></div>
<divclass="line"><aid="l00051"name="l00051"></a><spanclass="lineno"> 51</span><spanclass="comment">// is needed if variables or linear constraints are added or deleted.</span></div>
<divclass="line"><aid="l00053"name="l00053"></a><spanclass="lineno"> 53</span><spanclass="comment">// Asserts (using CHECK) that the inputs solve_args.model_parameters and</span></div>
<divclass="line"><aid="l00054"name="l00054"></a><spanclass="lineno"> 54</span><spanclass="comment">// solve_args.callback_registration only contain variables and constraints from</span></div>
<divclass="line"><aid="l00055"name="l00055"></a><spanclass="lineno"> 55</span><spanclass="comment">// the input model.</span></div>
<divclass="line"><aid="l00057"name="l00057"></a><spanclass="lineno"> 57</span><spanclass="comment">// Thread-safety: this method is safe to call concurrently on the same Model.</span></div>
<divclass="line"><aid="l00059"name="l00059"></a><spanclass="lineno"> 59</span><spanclass="comment">// Some solvers may add more restrictions regarding threading. Please see</span></div>
<divclass="line"><aid="l00060"name="l00060"></a><spanclass="lineno"> 60</span><spanclass="comment">// SolverType::kXxx documentation for details.</span></div>
<divclass="line"><aid="l00067"name="l00067"></a><spanclass="lineno"> 67</span><spanclass="comment">// This is a feature for advance users. Most users should only use the Solve()</span></div>
<divclass="line"><aid="l00068"name="l00068"></a><spanclass="lineno"> 68</span><spanclass="comment">// function above.</span></div>
<divclass="line"><aid="l00070"name="l00070"></a><spanclass="lineno"> 70</span><spanclass="comment">// Here incremental means that the we try to reuse the existing underlying</span></div>
<divclass="line"><aid="l00071"name="l00071"></a><spanclass="lineno"> 71</span><spanclass="comment">// solver internals between each solve. There is no guarantee though that the</span></div>
<divclass="line"><aid="l00072"name="l00072"></a><spanclass="lineno"> 72</span><spanclass="comment">// solver supports all possible model changes. Hence there is not guarantee that</span></div>
<divclass="line"><aid="l00073"name="l00073"></a><spanclass="lineno"> 73</span><spanclass="comment">// performances will be improved when using this class; this is solver</span></div>
<divclass="line"><aid="l00074"name="l00074"></a><spanclass="lineno"> 74</span><spanclass="comment">// dependent. Typically LPs have more to gain from incremental solve than</span></div>
<divclass="line"><aid="l00075"name="l00075"></a><spanclass="lineno"> 75</span><spanclass="comment">// MIPs. In both cases, even if the solver supports the model changes,</span></div>
<divclass="line"><aid="l00076"name="l00076"></a><spanclass="lineno"> 76</span><spanclass="comment">// incremental solve may actually be slower.</span></div>
<divclass="line"><aid="l00078"name="l00078"></a><spanclass="lineno"> 78</span><spanclass="comment">// The New() function instantiates the solver, setup it from the current state</span></div>
<divclass="line"><aid="l00079"name="l00079"></a><spanclass="lineno"> 79</span><spanclass="comment">// of the Model and register on it to listen to changes. Calling Solve() will</span></div>
<divclass="line"><aid="l00080"name="l00080"></a><spanclass="lineno"> 80</span><spanclass="comment">// update the underlying solver with latest model changes and solve this model.</span></div>
<divclass="line"><aid="l00097"name="l00097"></a><spanclass="lineno"> 97</span><spanclass="comment">// Lifecycle: The IncrementalSolver is only keeping a std::weak_ref on Model's</span></div>
<divclass="line"><aid="l00098"name="l00098"></a><spanclass="lineno"> 98</span><spanclass="comment">// internal data and thus it returns an error if Update() or Solve() are called</span></div>
<divclass="line"><aid="l00099"name="l00099"></a><spanclass="lineno"> 99</span><spanclass="comment">// after the Model has been destroyed. It is fine to destroy the</span></div>
<divclass="line"><aid="l00100"name="l00100"></a><spanclass="lineno"> 100</span><spanclass="comment">// IncrementalSolver after the associated Model though.</span></div>
<divclass="line"><aid="l00102"name="l00102"></a><spanclass="lineno"> 102</span><spanclass="comment">// Thread-safety: The New(), Solve() and Update() methods must not be called</span></div>
<divclass="line"><aid="l00103"name="l00103"></a><spanclass="lineno"> 103</span><spanclass="comment">// while modifying the Model() (adding variables...). The user is expected to</span></div>
<divclass="line"><aid="l00104"name="l00104"></a><spanclass="lineno"> 104</span><spanclass="comment">// use proper synchronization primitives to serialize changes to the model and</span></div>
<divclass="line"><aid="l00105"name="l00105"></a><spanclass="lineno"> 105</span><spanclass="comment">// the use of this object. Note though that it is safe to call methods from</span></div>
<divclass="line"><aid="l00106"name="l00106"></a><spanclass="lineno"> 106</span><spanclass="comment">// different IncrementalSolver instances on the same Model concurrently.</span></div>
<divclass="line"><aid="l00108"name="l00108"></a><spanclass="lineno"> 108</span><spanclass="comment">// There is no problem calling SolveWithoutUpdate() concurrently on different</span></div>
<divclass="line"><aid="l00109"name="l00109"></a><spanclass="lineno"> 109</span><spanclass="comment">// instances of IncrementalSolver or while the model is being modified (unless</span></div>
<divclass="line"><aid="l00110"name="l00110"></a><spanclass="lineno"> 110</span><spanclass="comment">// of course the underlying solver itself is not thread-safe and can only be</span></div>
<divclass="line"><aid="l00111"name="l00111"></a><spanclass="lineno"> 111</span><spanclass="comment">// called from a single-thread).</span></div>
<divclass="line"><aid="l00113"name="l00113"></a><spanclass="lineno"> 113</span><spanclass="comment">// Note that Solve(), Update() and SolveWithoutUpdate() are not reentrant so</span></div>
<divclass="line"><aid="l00114"name="l00114"></a><spanclass="lineno"> 114</span><spanclass="comment">// they should not be called concurrently on the same instance of</span></div>
<divclass="line"><aid="l00117"name="l00117"></a><spanclass="lineno"> 117</span><spanclass="comment">// Some solvers may add more restrictions regarding threading. Please see</span></div>
<divclass="line"><aid="l00118"name="l00118"></a><spanclass="lineno"> 118</span><spanclass="comment">// SolverType::kXxx documentation for details.</span></div>
<divclass="line"><aid="l00125"name="l00125"></a><spanclass="lineno"> 125</span><spanclass="comment">// True if the solver has been successfully updated or if no update was</span></div>
<divclass="line"><aid="l00126"name="l00126"></a><spanclass="lineno"> 126</span><spanclass="comment">// necessary (in which case `update` will be nullopt). False if the solver</span></div>
<divclass="line"><aid="l00127"name="l00127"></a><spanclass="lineno"> 127</span><spanclass="comment">// had to be recreated.</span></div>
<divclass="line"><aid="l00130"name="l00130"></a><spanclass="lineno"> 130</span><spanclass="comment">// The update that was attempted on the solver. Can be nullopt when no</span></div>
<divclass="line"><aid="l00131"name="l00131"></a><spanclass="lineno"> 131</span><spanclass="comment">// update was needed (the model was not changed).</span></div>
<divclass="line"><aid="l00135"name="l00135"></a><spanclass="lineno"> 135</span><spanclass="comment">// Creates a new incremental solve for the given model. It may returns an</span></div>
<divclass="line"><aid="l00136"name="l00136"></a><spanclass="lineno"> 136</span><spanclass="comment">// error if the parameters are invalid (for example if the selected solver is</span></div>
<divclass="line"><aid="l00137"name="l00137"></a><spanclass="lineno"> 137</span><spanclass="comment">// not linked in the binary).</span></div>
<divclass="line"><aid="l00139"name="l00139"></a><spanclass="lineno"> 139</span><spanclass="comment">// The returned IncrementalSolver keeps a copy of `arguments`. Thus the</span></div>
<divclass="line"><aid="l00140"name="l00140"></a><spanclass="lineno"> 140</span><spanclass="comment">// content of arguments.non_streamable (for example pointers to solver</span></div>
<divclass="line"><aid="l00141"name="l00141"></a><spanclass="lineno"> 141</span><spanclass="comment">// specific struct) must be valid until the destruction of the</span></div>
<divclass="line"><aid="l00142"name="l00142"></a><spanclass="lineno"> 142</span><spanclass="comment">// IncrementalSolver. It also registers on the Model to keep track of updates</span></div>
<divclass="line"><aid="l00143"name="l00143"></a><spanclass="lineno"> 143</span><spanclass="comment">// (see class documentation for details).</span></div>
<divclass="line"><aid="l00147"name="l00147"></a><spanclass="lineno"> 147</span><spanclass="comment">// Updates the underlying solver with latest model changes and runs the solve.</span></div>
<divclass="line"><aid="l00149"name="l00149"></a><spanclass="lineno"> 149</span><spanclass="comment">// A Status error will be returned if there is an unexpected failure in an</span></div>
<divclass="line"><aid="l00150"name="l00150"></a><spanclass="lineno"> 150</span><spanclass="comment">// underlying solver or for some internal math_opt errors. Otherwise, check</span></div>
<divclass="line"><aid="l00151"name="l00151"></a><spanclass="lineno"> 151</span><spanclass="comment">// SolveResult::termination.reason to see if an optimal solution was found.</span></div>
<divclass="line"><aid="l00153"name="l00153"></a><spanclass="lineno"> 153</span><spanclass="comment">// Memory model: the returned SolveResult owns its own memory (for solutions,</span></div>
<divclass="line"><aid="l00154"name="l00154"></a><spanclass="lineno"> 154</span><spanclass="comment">// solve stats, etc.), EXPECT for a pointer back to the model. As a result:</span></div>
<divclass="line"><aid="l00155"name="l00155"></a><spanclass="lineno"> 155</span><spanclass="comment">// * Keep the model alive to access SolveResult,</span></div>
<divclass="line"><aid="l00157"name="l00157"></a><spanclass="lineno"> 157</span><spanclass="comment">// * The result is generally accessible after mutating this, but some care</span></div>
<divclass="line"><aid="l00158"name="l00158"></a><spanclass="lineno"> 158</span><spanclass="comment">// is needed if variables or linear constraints are added or deleted.</span></div>
<divclass="line"><aid="l00160"name="l00160"></a><spanclass="lineno"> 160</span><spanclass="comment">// Asserts (using CHECK) that the inputs arguments.model_parameters and</span></div>
<divclass="line"><aid="l00161"name="l00161"></a><spanclass="lineno"> 161</span><spanclass="comment">// arguments.callback_registration only contain variables and constraints from</span></div>
<divclass="line"><aid="l00162"name="l00162"></a><spanclass="lineno"> 162</span><spanclass="comment">// the input model.</span></div>
<divclass="line"><aid="l00164"name="l00164"></a><spanclass="lineno"> 164</span><spanclass="comment">// See callback.h for documentation on arguments.callback and</span></div>
<divclass="line"><aid="l00170"name="l00170"></a><spanclass="lineno"> 170</span><spanclass="comment">// This is an advanced API, most users should use Solve() above that does the</span></div>
<divclass="line"><aid="l00171"name="l00171"></a><spanclass="lineno"> 171</span><spanclass="comment">// update and before calling the solver. Calling this function is only useful</span></div>
<divclass="line"><aid="l00172"name="l00172"></a><spanclass="lineno"> 172</span><spanclass="comment">// for users that want to access to update data or users that need to use</span></div>
<divclass="line"><aid="l00173"name="l00173"></a><spanclass="lineno"> 173</span><spanclass="comment">// SolveWithoutUpdate() (which should not be common).</span></div>
<divclass="line"><aid="l00175"name="l00175"></a><spanclass="lineno"> 175</span><spanclass="comment">// The returned value indicates if the update was possible or if the solver</span></div>
<divclass="line"><aid="l00176"name="l00176"></a><spanclass="lineno"> 176</span><spanclass="comment">// had to be recreated from scratch (which may happen when the solver does not</span></div>
<divclass="line"><aid="l00177"name="l00177"></a><spanclass="lineno"> 177</span><spanclass="comment">// support this specific update or any update at all). It also contains the</span></div>
<divclass="line"><aid="l00180"name="l00180"></a><spanclass="lineno"> 180</span><spanclass="comment">// A status error will be returned if the underlying solver has an internal</span></div>
<divclass="line"><aid="l00184"name="l00184"></a><spanclass="lineno"> 184</span><spanclass="comment">// Same as Solve() but does not update the underlying solver with the latest</span></div>
<divclass="line"><aid="l00185"name="l00185"></a><spanclass="lineno"> 185</span><spanclass="comment">// changes to the model.</span></div>
<divclass="line"><aid="l00187"name="l00187"></a><spanclass="lineno"> 187</span><spanclass="comment">// This is an advanced API, most users should use Solve().</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>
