<!-- iframe showing the search results (closed by default) -->
<divid="MSearchResultsWindow">
<iframesrc="javascript:void(0)"frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<divclass="header">
<divclass="headertitle">
<divclass="title">lu_factorization.h</div></div>
</div><!--header-->
<divclass="contents">
<ahref="lu__factorization_8h.html">Go to the documentation of this file.</a><divclass="fragment"><divclass="line"><aname="l00001"></a><spanclass="lineno"> 1</span> <spanclass="comment">// Copyright 2010-2018 Google LLC</span></div>
<divclass="line"><aname="l00002"></a><spanclass="lineno"> 2</span> <spanclass="comment">// Licensed under the Apache License, Version 2.0 (the "License");</span></div>
<divclass="line"><aname="l00003"></a><spanclass="lineno"> 3</span> <spanclass="comment">// you may not use this file except in compliance with the License.</span></div>
<divclass="line"><aname="l00004"></a><spanclass="lineno"> 4</span> <spanclass="comment">// You may obtain a copy of the License at</span></div>
<divclass="line"><aname="l00008"></a><spanclass="lineno"> 8</span> <spanclass="comment">// Unless required by applicable law or agreed to in writing, software</span></div>
<divclass="line"><aname="l00009"></a><spanclass="lineno"> 9</span> <spanclass="comment">// distributed under the License is distributed on an "AS IS" BASIS,</span></div>
<divclass="line"><aname="l00010"></a><spanclass="lineno"> 10</span> <spanclass="comment">// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span></div>
<divclass="line"><aname="l00011"></a><spanclass="lineno"> 11</span> <spanclass="comment">// See the License for the specific language governing permissions and</span></div>
<divclass="line"><aname="l00012"></a><spanclass="lineno"> 12</span> <spanclass="comment">// limitations under the License.</span></div>
<divclass="line"><aname="l00030"></a><spanclass="lineno"> 30</span> <spanclass="comment">// An LU-Factorization class encapsulating the LU factorization data and</span></div>
<divclass="line"><aname="l00031"></a><spanclass="lineno"> 31</span> <spanclass="comment">// algorithms. The actual algorithm is in markowitz.h and .cc. This class holds</span></div>
<divclass="line"><aname="l00032"></a><spanclass="lineno"> 32</span> <spanclass="comment">// all the Solve() functions that deal with the permutations and the L and U</span></div>
<divclass="line"><aname="l00033"></a><spanclass="lineno"> 33</span> <spanclass="comment">// factors once they are computed.</span></div>
<divclass="line"><aname="l00038"></a><spanclass="lineno"> 38</span> <spanclass="comment">// Returns true if the LuFactorization is a factorization of the identity</span></div>
<divclass="line"><aname="l00039"></a><spanclass="lineno"> 39</span> <spanclass="comment">// matrix. In this state, all the Solve() functions will work for any</span></div>
<divclass="line"><aname="l00043"></a><spanclass="lineno"> 43</span> <spanclass="comment">// Clears internal data structure and reset this class to the factorization</span></div>
<divclass="line"><aname="l00044"></a><spanclass="lineno"> 44</span> <spanclass="comment">// of an identity matrix.</span></div>
<divclass="line"><aname="l00047"></a><spanclass="lineno"> 47</span> <spanclass="comment">// Computes an LU-decomposition for a given matrix B. If for some reason,</span></div>
<divclass="line"><aname="l00048"></a><spanclass="lineno"> 48</span> <spanclass="comment">// there was an error, then the factorization is reset to the one of the</span></div>
<divclass="line"><aname="l00049"></a><spanclass="lineno"> 49</span> <spanclass="comment">// identity matrix, and an error is reported.</span></div>
<divclass="line"><aname="l00051"></a><spanclass="lineno"> 51</span> <spanclass="comment">// Note(user): Since a client must use the result, there is little chance of</span></div>
<divclass="line"><aname="l00052"></a><spanclass="lineno"> 52</span> <spanclass="comment">// it being confused by this revert to identity factorization behavior. The</span></div>
<divclass="line"><aname="l00053"></a><spanclass="lineno"> 53</span> <spanclass="comment">// reason behind it is that this way, calling any public function of this</span></div>
<divclass="line"><aname="l00054"></a><spanclass="lineno"> 54</span> <spanclass="comment">// class will never cause a crash of the program.</span></div>
<divclass="line"><aname="l00058"></a><spanclass="lineno"> 58</span> <spanclass="comment">// Returns the column permutation used by the LU factorization.</span></div>
<divclass="line"><aname="l00061"></a><spanclass="lineno"> 61</span> <spanclass="comment">// Sets the column permutation to the identity permutation. The idea is that</span></div>
<divclass="line"><aname="l00062"></a><spanclass="lineno"> 62</span> <spanclass="comment">// the column permutation can be incorporated in the basis RowToColMapping,</span></div>
<divclass="line"><aname="l00063"></a><spanclass="lineno"> 63</span> <spanclass="comment">// and once this is done, then a client can call this and effectively remove</span></div>
<divclass="line"><aname="l00064"></a><spanclass="lineno"> 64</span> <spanclass="comment">// the need for a column permutation on each solve.</span></div>
<divclass="line"><aname="l00070"></a><spanclass="lineno"> 70</span> <spanclass="comment">// Solves 'B.x = b', x initially contains b, and is replaced by 'B^{-1}.b'.</span></div>
<divclass="line"><aname="l00071"></a><spanclass="lineno"> 71</span> <spanclass="comment">// Since P.B.Q^{-1} = L.U, we have B = P^{-1}.L.U.Q.</span></div>
<divclass="line"><aname="l00072"></a><spanclass="lineno"> 72</span> <spanclass="comment">// 1/ Solve P^{-1}.y = b for y by computing y = P.b,</span></div>
<divclass="line"><aname="l00073"></a><spanclass="lineno"> 73</span> <spanclass="comment">// 2/ solve L.z = y for z,</span></div>
<divclass="line"><aname="l00074"></a><spanclass="lineno"> 74</span> <spanclass="comment">// 3/ solve U.t = z for t,</span></div>
<divclass="line"><aname="l00075"></a><spanclass="lineno"> 75</span> <spanclass="comment">// 4/ finally solve Q.x = t, by computing x = Q^{-1}.t.</span></div>
<divclass="line"><aname="l00078"></a><spanclass="lineno"> 78</span> <spanclass="comment">// Solves 'y.B = r', y initially contains r, and is replaced by r.B^{-1}.</span></div>
<divclass="line"><aname="l00079"></a><spanclass="lineno"> 79</span> <spanclass="comment">// Internally, it takes x = y^T, b = r^T and solves B^T.x = b.</span></div>
<divclass="line"><aname="l00080"></a><spanclass="lineno"> 80</span> <spanclass="comment">// We have P.B.Q^{-1} = P.B.Q^T = L.U, thus (L.U)^T = Q.B^T.P^T.</span></div>
<divclass="line"><aname="l00082"></a><spanclass="lineno"> 82</span> <spanclass="comment">// The procedure is thus:</span></div>
<divclass="line"><aname="l00083"></a><spanclass="lineno"> 83</span> <spanclass="comment">// 1/ Solve Q^{-1}.y = b for y, by computing y = Q.b,</span></div>
<divclass="line"><aname="l00084"></a><spanclass="lineno"> 84</span> <spanclass="comment">// 2/ solve U^T.z = y for z,</span></div>
<divclass="line"><aname="l00085"></a><spanclass="lineno"> 85</span> <spanclass="comment">// 3/ solve L^T.t = z for t,</span></div>
<divclass="line"><aname="l00086"></a><spanclass="lineno"> 86</span> <spanclass="comment">// 4/ finally, solve P.x = t for x by computing x = P^{-1}.t.</span></div>
<divclass="line"><aname="l00089"></a><spanclass="lineno"> 89</span> <spanclass="comment">// More fine-grained right/left solve functions that may exploit the initial</span></div>
<divclass="line"><aname="l00090"></a><spanclass="lineno"> 90</span> <spanclass="comment">// non-zeros of the input vector if non-empty. Note that a solve involving L</span></div>
<divclass="line"><aname="l00091"></a><spanclass="lineno"> 91</span> <spanclass="comment">// actually solves P^{-1}.L and a solve involving U actually solves U.Q. To</span></div>
<divclass="line"><aname="l00092"></a><spanclass="lineno"> 92</span> <spanclass="comment">// solve a system with the initial matrix B, one needs to call:</span></div>
<divclass="line"><aname="l00093"></a><spanclass="lineno"> 93</span> <spanclass="comment">// - RightSolveL() and then RightSolveU() for a right solve (B.x = initial x).</span></div>
<divclass="line"><aname="l00094"></a><spanclass="lineno"> 94</span> <spanclass="comment">// - LeftSolveU() and then LeftSolveL() for a left solve (y.B = initial y).</span></div>
<divclass="line"><aname="l00099"></a><spanclass="lineno"> 99</span> <spanclass="comment">// Specialized version of LeftSolveL() that may exploit the initial non_zeros</span></div>
<divclass="line"><aname="l00100"></a><spanclass="lineno"> 100</span> <spanclass="comment">// of y if it is non empty. Moreover, if result_before_permutation is not</span></div>
<divclass="line"><aname="l00101"></a><spanclass="lineno"> 101</span> <spanclass="comment">// NULL, it might be filled with the result just before row_perm_ is applied</span></div>
<divclass="line"><aname="l00102"></a><spanclass="lineno"> 102</span> <spanclass="comment">// to it and true is returned. If result_before_permutation is not filled,</span></div>
<divclass="line"><aname="l00103"></a><spanclass="lineno"> 103</span> <spanclass="comment">// then false is returned.</span></div>
<divclass="line"><aname="l00108"></a><spanclass="lineno"> 108</span> <spanclass="comment">// Specialized version of RightSolveLWithNonZeros() that takes a SparseColumn</span></div>
<divclass="line"><aname="l00109"></a><spanclass="lineno"> 109</span> <spanclass="comment">// or a ScatteredColumn as input. non_zeros will either be cleared or set to</span></div>
<divclass="line"><aname="l00110"></a><spanclass="lineno"> 110</span> <spanclass="comment">// the non zeros of the result. Important: the output x must be of the correct</span></div>
<divclass="line"><aname="l00111"></a><spanclass="lineno"> 111</span> <spanclass="comment">// size and all zero.</span></div>
<divclass="line"><aname="l00116"></a><spanclass="lineno"> 116</span> <spanclass="comment">// Specialized version of RightSolveLWithNonZeros() where x is originaly equal</span></div>
<divclass="line"><aname="l00117"></a><spanclass="lineno"> 117</span> <spanclass="comment">// to 'a' permuted by row_perm_. Note that 'a' is only used for DCHECK.</span></div>
<divclass="line"><aname="l00121"></a><spanclass="lineno"> 121</span> <spanclass="comment">// Specialized version of LeftSolveU() for an unit right-hand side.</span></div>
<divclass="line"><aname="l00122"></a><spanclass="lineno"> 122</span> <spanclass="comment">// non_zeros will either be cleared or set to the non zeros of the results.</span></div>
<divclass="line"><aname="l00123"></a><spanclass="lineno"> 123</span> <spanclass="comment">// It also returns the value of col permuted by Q (which is the position</span></div>
<divclass="line"><aname="l00124"></a><spanclass="lineno"> 124</span> <spanclass="comment">// of the unit-vector rhs in the solve system: y.U = rhs).</span></div>
<divclass="line"><aname="l00125"></a><spanclass="lineno"> 125</span> <spanclass="comment">// Important: the output y must be of the correct size and all zero.</span></div>
<divclass="line"><aname="l00128"></a><spanclass="lineno"> 128</span> <spanclass="comment">// Returns the given column of U.</span></div>
<divclass="line"><aname="l00129"></a><spanclass="lineno"> 129</span> <spanclass="comment">// It will only be valid until the next call to GetColumnOfU().</span></div>
<divclass="line"><aname="l00135"></a><spanclass="lineno"> 135</span> <spanclass="comment">// Returns the norm of (B^T)^{-1}.e_row where e is an unit vector.</span></div>
<divclass="line"><aname="l00138"></a><spanclass="lineno"> 138</span> <spanclass="comment">// The fill-in of the LU-factorization is defined as the sum of the number</span></div>
<divclass="line"><aname="l00139"></a><spanclass="lineno"> 139</span> <spanclass="comment">// of entries of both the lower- and upper-triangular matrices L and U minus</span></div>
<divclass="line"><aname="l00140"></a><spanclass="lineno"> 140</span> <spanclass="comment">// the number of entries in the initial matrix B.</span></div>
<divclass="line"><aname="l00142"></a><spanclass="lineno"> 142</span> <spanclass="comment">// This returns the number of entries in lower + upper as the percentage of</span></div>
<divclass="line"><aname="l00143"></a><spanclass="lineno"> 143</span> <spanclass="comment">// the number of entries in B.</span></div>
<divclass="line"><aname="l00146"></a><spanclass="lineno"> 146</span> <spanclass="comment">// Returns the number of entries in L + U.</span></div>
<divclass="line"><aname="l00147"></a><spanclass="lineno"> 147</span> <spanclass="comment">// If the factorization is the identity, this returns 0.</span></div>
<divclass="line"><aname="l00150"></a><spanclass="lineno"> 150</span> <spanclass="comment">// Computes the determinant of the input matrix B.</span></div>
<divclass="line"><aname="l00152"></a><spanclass="lineno"> 152</span> <spanclass="comment">// det(L) = 1 since L is a lower-triangular matrix with 1 on the diagonal.</span></div>
<divclass="line"><aname="l00153"></a><spanclass="lineno"> 153</span> <spanclass="comment">// det(P) = +1 or -1 (by definition it is the sign of the permutation P)</span></div>
<divclass="line"><aname="l00154"></a><spanclass="lineno"> 154</span> <spanclass="comment">// det(Q^{-1}) = +1 or -1 (the sign of the permutation Q^{-1})</span></div>
<divclass="line"><aname="l00155"></a><spanclass="lineno"> 155</span> <spanclass="comment">// Finally det(U) = product of the diagonal elements of U, since U is an</span></div>
<divclass="line"><aname="l00161"></a><spanclass="lineno"> 161</span> <spanclass="comment">// Computes the 1-norm of the inverse of the input matrix B.</span></div>
<divclass="line"><aname="l00162"></a><spanclass="lineno"> 162</span> <spanclass="comment">// For this we iteratively solve B.x = e_j, where e_j is the jth unit vector.</span></div>
<divclass="line"><aname="l00163"></a><spanclass="lineno"> 163</span> <spanclass="comment">// The result of this computation is the jth column of B^-1.</span></div>
<divclass="line"><aname="l00164"></a><spanclass="lineno"> 164</span> <spanclass="comment">// The 1-norm |B| is defined as max_j sum_i |a_ij|</span></div>
<divclass="line"><aname="l00168"></a><spanclass="lineno"> 168</span> <spanclass="comment">// Computes the infinity-norm of the inverse of the input matrix B.</span></div>
<divclass="line"><aname="l00169"></a><spanclass="lineno"> 169</span> <spanclass="comment">// The infinity-norm |B| is defined as max_i sum_j |a_ij|</span></div>
<divclass="line"><aname="l00173"></a><spanclass="lineno"> 173</span> <spanclass="comment">// Computes the condition number of the input matrix B.</span></div>
<divclass="line"><aname="l00174"></a><spanclass="lineno"> 174</span> <spanclass="comment">// For a given norm, this is the matrix norm times the norm of its inverse.</span></div>
<divclass="line"><aname="l00176"></a><spanclass="lineno"> 176</span> <spanclass="comment">// Note that because the LuFactorization class does not keep the</span></div>
<divclass="line"><aname="l00177"></a><spanclass="lineno"> 177</span> <spanclass="comment">// non-factorized matrix in memory, it needs to be passed to these functions.</span></div>
<divclass="line"><aname="l00178"></a><spanclass="lineno"> 178</span> <spanclass="comment">// It is up to the client to pass exactly the same matrix as the one used</span></div>
<divclass="line"><aname="l00179"></a><spanclass="lineno"> 179</span> <spanclass="comment">// for ComputeFactorization().</span></div>
<divclass="line"><aname="l00181"></a><spanclass="lineno"> 181</span> <spanclass="comment">// TODO(user): separate this from LuFactorization.</span></div>
<divclass="line"><aname="l00194"></a><spanclass="lineno"> 194</span> <spanclass="comment">// Returns a string containing the statistics for this class.</span></div>
<divclass="line"><aname="l00199"></a><spanclass="lineno"> 199</span> <spanclass="comment">// This is only used for testing and in debug mode.</span></div>
<divclass="line"><aname="l00200"></a><spanclass="lineno"> 200</span> <spanclass="comment">// TODO(user): avoid the matrix conversion by multiplying TriangularMatrix</span></div>
<divclass="line"><aname="l00226"></a><spanclass="lineno"> 226</span> <spanclass="comment">// Internal function used in the left solve functions.</span></div>
<divclass="line"><aname="l00229"></a><spanclass="lineno"> 229</span> <spanclass="comment">// Internal function used in the right solve functions</span></div>
<divclass="line"><aname="l00236"></a><spanclass="lineno"> 236</span> <spanclass="comment">// transpose_lower_ is only needed when we compute dual norms.</span></div>
<divclass="line"><aname="l00239"></a><spanclass="lineno"> 239</span> <spanclass="comment">// Computes R = P.B.Q^{-1} - L.U and returns false if the largest magnitude of</span></div>
<divclass="line"><aname="l00240"></a><spanclass="lineno"> 240</span> <spanclass="comment">// the coefficients of P.B.Q^{-1} - L.U is greater than tolerance.</span></div>
<divclass="line"><aname="l00244"></a><spanclass="lineno"> 244</span> <spanclass="comment">// Special case where we have nothing to do. This happens at the beginning</span></div>
<divclass="line"><aname="l00245"></a><spanclass="lineno"> 245</span> <spanclass="comment">// when we start the problem with an all-slack basis and gives a good speedup</span></div>
<divclass="line"><aname="l00246"></a><spanclass="lineno"> 246</span> <spanclass="comment">// on really easy problems. It is initially true and set to true each time we</span></div>
<divclass="line"><aname="l00247"></a><spanclass="lineno"> 247</span> <spanclass="comment">// call Clear(). We set it to false if a call to ComputeFactorization()</span></div>
<divclass="line"><aname="l00251"></a><spanclass="lineno"> 251</span> <spanclass="comment">// The triangular factor L and U (and its transpose).</span></div>
<divclass="line"><aname="l00256"></a><spanclass="lineno"> 256</span> <spanclass="comment">// The transpose of lower_. It is just used by DualEdgeSquaredNorm()</span></div>
<divclass="line"><aname="l00257"></a><spanclass="lineno"> 257</span> <spanclass="comment">// and mutable so it can be lazily initialized.</span></div>
<divclass="line"><aname="l00260"></a><spanclass="lineno"> 260</span> <spanclass="comment">// The column permutation Q and its inverse Q^{-1} in P.B.Q^{-1} = L.U.</span></div>
<divclass="line"><aname="l00264"></a><spanclass="lineno"> 264</span> <spanclass="comment">// The row permutation P and its inverse P^{-1} in P.B.Q^{-1} = L.U.</span></div>
<divclass="line"><aname="l00268"></a><spanclass="lineno"> 268</span> <spanclass="comment">// Temporary storage used by LeftSolve()/RightSolve().</span></div>
<divclass="line"><aname="l00271"></a><spanclass="lineno"> 271</span> <spanclass="comment">// Temporary storage used by GetColumnOfU().</span></div>
<divclass="line"><aname="l00274"></a><spanclass="lineno"> 274</span> <spanclass="comment">// Same as dense_column_scratchpad_ but this vector is always reset to zero by</span></div>
<divclass="line"><aname="l00275"></a><spanclass="lineno"> 275</span> <spanclass="comment">// the functions that use it. non_zero_rows_ is used to track the</span></div>
<divclass="line"><aname="l00276"></a><spanclass="lineno"> 276</span> <spanclass="comment">// non_zero_rows_ position of dense_column_scratchpad_.</span></div>
<divclass="line"><aname="l00280"></a><spanclass="lineno"> 280</span> <spanclass="comment">// Statistics, mutable so const functions can still update it.</span></div>
<divclass="line"><aname="l00283"></a><spanclass="lineno"> 283</span> <spanclass="comment">// Proto holding all the parameters of this algorithm.</span></div>
<divclass="line"><aname="l00286"></a><spanclass="lineno"> 286</span> <spanclass="comment">// The class doing the Markowitz LU factorization.</span></div>
<divclass="ttc"id="aclassoperations__research_1_1glop_1_1_lu_factorization_html_a56d08f5289eea3f018dca5b93b6fca6b"><divclass="ttname"><ahref="classoperations__research_1_1glop_1_1_lu_factorization.html#a56d08f5289eea3f018dca5b93b6fca6b">operations_research::glop::LuFactorization::GetColumnPermutation</a></div><divclass="ttdeci">const ColumnPermutation & GetColumnPermutation() const</div><divclass="ttdef"><b>Definition:</b><ahref="lu__factorization_8h_source.html#l00059">lu_factorization.h:59</a></div></div>
<divclass="ttc"id="aclassoperations__research_1_1glop_1_1_lu_factorization_html_a5a3f1ad730713e296dcbbed8b1123130"><divclass="ttname"><ahref="classoperations__research_1_1glop_1_1_lu_factorization.html#a5a3f1ad730713e296dcbbed8b1123130">operations_research::glop::LuFactorization::row_perm</a></div><divclass="ttdeci">const RowPermutation & row_perm() const</div><divclass="ttdef"><b>Definition:</b><ahref="lu__factorization_8h_source.html#l00210">lu_factorization.h:210</a></div></div>
<divclass="ttc"id="aclassoperations__research_1_1glop_1_1_lu_factorization_html_a864ad5596d017729a4ca349fed8949a8"><divclass="ttname"><ahref="classoperations__research_1_1glop_1_1_lu_factorization.html#a864ad5596d017729a4ca349fed8949a8">operations_research::glop::LuFactorization::inverse_col_perm</a></div><divclass="ttdeci">const ColumnPermutation & inverse_col_perm() const</div><divclass="ttdef"><b>Definition:</b><ahref="lu__factorization_8h_source.html#l00211">lu_factorization.h:211</a></div></div>
<divclass="ttc"id="aclassoperations__research_1_1glop_1_1_lu_factorization_html_ace58a4f9d6a147c3455ff8dc029537c4"><divclass="ttname"><ahref="classoperations__research_1_1glop_1_1_lu_factorization.html#ace58a4f9d6a147c3455ff8dc029537c4">operations_research::glop::LuFactorization::ComputeFactorization</a></div><divclass="ttdeci">ABSL_MUST_USE_RESULT Status ComputeFactorization(const CompactSparseMatrixView &compact_matrix)</div><divclass="ttdef"><b>Definition:</b><ahref="lu__factorization_8cc_source.html#l00044">lu_factorization.cc:44</a></div></div>
<divclass="ttc"id="anamespaceoperations__research_html"><divclass="ttname"><ahref="namespaceoperations__research.html">operations_research</a></div><divclass="ttdoc">The vehicle routing library lets one model and solve generic vehicle routing problems ranging from th...</div><divclass="ttdef"><b>Definition:</b><ahref="dense__doubly__linked__list_8h_source.html#l00021">dense_doubly_linked_list.h:21</a></div></div>
