<ahref="matrix__scaler_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">// The SparseMatrixScaler class provides tools to scale a SparseMatrix, i.e.</span></div>
<divclass="line"><aid="l00015"name="l00015"></a><spanclass="lineno"> 15</span><spanclass="comment">// reduce the range of its coefficients and make for each column and each row</span></div>
<divclass="line"><aid="l00016"name="l00016"></a><spanclass="lineno"> 16</span><spanclass="comment">// the maximum magnitude of its coefficients equal to 1.</span></div>
<divclass="line"><aid="l00018"name="l00018"></a><spanclass="lineno"> 18</span><spanclass="comment">// In the case there are bounds or costs on the columns or a right-hand side</span></div>
<divclass="line"><aid="l00019"name="l00019"></a><spanclass="lineno"> 19</span><spanclass="comment">// related to each row, SparseMatrixScaler provides the tools to scale those</span></div>
<divclass="line"><aid="l00022"name="l00022"></a><spanclass="lineno"> 22</span><spanclass="comment">// More precisely, suppose we have the Linear Program:</span></div>
<divclass="line"><aid="l00023"name="l00023"></a><spanclass="lineno"> 23</span><spanclass="comment">// min c.x</span></div>
<divclass="line"><aid="l00027"name="l00027"></a><spanclass="lineno"> 27</span><spanclass="comment">// The rows of A are scaled by left-multiplying it by a diagonal matrix R</span></div>
<divclass="line"><aid="l00028"name="l00028"></a><spanclass="lineno"> 28</span><spanclass="comment">// whose elements R_ii correspond to the scaling factor of row i.</span></div>
<divclass="line"><aid="l00029"name="l00029"></a><spanclass="lineno"> 29</span><spanclass="comment">// The columns of A are scaled by right-multiplying it by a diagonal matrix C</span></div>
<divclass="line"><aid="l00030"name="l00030"></a><spanclass="lineno"> 30</span><spanclass="comment">// whose elements C_jj correspond to the scaling factor of column j.</span></div>
<divclass="line"><aid="l00034"name="l00034"></a><spanclass="lineno"> 34</span><spanclass="comment">// We wish to scale x, c, b, l, u so as to work on the scaled problem:</span></div>
<divclass="line"><aid="l00035"name="l00035"></a><spanclass="lineno"> 35</span><spanclass="comment">// min c'.x'</span></div>
<divclass="line"><aid="l00039"name="l00039"></a><spanclass="lineno"> 39</span><spanclass="comment">// The right-hand side b needs to be left-multiplied by R, the cost function c</span></div>
<divclass="line"><aid="l00040"name="l00040"></a><spanclass="lineno"> 40</span><spanclass="comment">// needs to be right-multiplied by C. Finally, x, and its lower- and upper-bound</span></div>
<divclass="line"><aid="l00041"name="l00041"></a><spanclass="lineno"> 41</span><spanclass="comment">// vectors l and u need to be left-multiplied by C^-1.</span></div>
<divclass="line"><aid="l00043"name="l00043"></a><spanclass="lineno"> 43</span><spanclass="comment">// Note also that the dual vector y is scaled as follows:</span></div>
<divclass="line"><aid="l00044"name="l00044"></a><spanclass="lineno"> 44</span><spanclass="comment">// y'.R = y, thus y' = y.R^-1.</span></div>
<divclass="line"><aid="l00046"name="l00046"></a><spanclass="lineno"> 46</span><spanclass="comment">// The complete transformation is thus:</span></div>
<divclass="line"><aid="l00055"name="l00055"></a><spanclass="lineno"> 55</span><spanclass="comment">// The validity of the above transformation can be checked by computing:</span></div>
<divclass="line"><aid="l00082"name="l00082"></a><spanclass="lineno"> 82</span><spanclass="comment">// Initializes the object with the SparseMatrix passed as argument.</span></div>
<divclass="line"><aid="l00083"name="l00083"></a><spanclass="lineno"> 83</span><spanclass="comment">// The row and column scaling factors are all set to 1.0 (i.e. no scaling.)</span></div>
<divclass="line"><aid="l00084"name="l00084"></a><spanclass="lineno"> 84</span><spanclass="comment">// In terms of matrices, R and C are set to identity matrices.</span></div>
<divclass="line"><aid="l00087"name="l00087"></a><spanclass="lineno"> 87</span><spanclass="comment">// Clears the object, and puts it back into the same state as after being</span></div>
<divclass="line"><aid="l00091"name="l00091"></a><spanclass="lineno"> 91</span><spanclass="comment">// The column col of the matrix was multiplied by ColScalingFactor(col). The</span></div>
<divclass="line"><aid="l00092"name="l00092"></a><spanclass="lineno"> 92</span><spanclass="comment">// variable bounds and objective coefficient at the same columsn where DIVIDED</span></div>
<divclass="line"><aid="l00093"name="l00093"></a><spanclass="lineno"> 93</span><spanclass="comment">// by that same factor. If col is outside the matrix size, this returns 1.0.</span></div>
<divclass="line"><aid="l00096"name="l00096"></a><spanclass="lineno"> 96</span><spanclass="comment">// The constraint row of the matrix was multiplied by RowScalingFactor(row),</span></div>
<divclass="line"><aid="l00097"name="l00097"></a><spanclass="lineno"> 97</span><spanclass="comment">// same for the constraint bounds (which is not the same as for the variable</span></div>
<divclass="line"><aid="l00098"name="l00098"></a><spanclass="lineno"> 98</span><spanclass="comment">// bounds for a column!). If row is outside the matrix size, this returns 1.0.</span></div>
<divclass="line"><aid="l00101"name="l00101"></a><spanclass="lineno"> 101</span><spanclass="comment">// The inverse of both factor above (this is how we keep them) so this</span></div>
<divclass="line"><aid="l00102"name="l00102"></a><spanclass="lineno"> 102</span><spanclass="comment">// direction should be faster to query (no 1.0 / factor).</span></div>
<divclass="line"><aid="l00106"name="l00106"></a><spanclass="lineno"> 106</span><spanclass="comment">// TODO(user): rename function and field to col_scales (and row_scales)</span></div>
<divclass="line"><aid="l00112"name="l00112"></a><spanclass="lineno"> 112</span><spanclass="comment">// Solves the scaling problem as a linear program.</span></div>
<divclass="line"><aid="l00118"name="l00118"></a><spanclass="lineno"> 118</span><spanclass="comment">// Scales a row vector up or down (depending whether parameter up is true or</span></div>
<divclass="line"><aid="l00119"name="l00119"></a><spanclass="lineno"> 119</span><spanclass="comment">// false) using the scaling factors determined by Scale().</span></div>
<divclass="line"><aid="l00120"name="l00120"></a><spanclass="lineno"> 120</span><spanclass="comment">// Scaling up means multiplying by the scaling factors, while scaling down</span></div>
<divclass="line"><aid="l00121"name="l00121"></a><spanclass="lineno"> 121</span><spanclass="comment">// means dividing by the scaling factors.</span></div>
<divclass="line"><aid="l00124"name="l00124"></a><spanclass="lineno"> 124</span><spanclass="comment">// Scales a column vector up or down (depending whether parameter up is true</span></div>
<divclass="line"><aid="l00125"name="l00125"></a><spanclass="lineno"> 125</span><spanclass="comment">// or false) using the scaling factors determined by Scale().</span></div>
<divclass="line"><aid="l00126"name="l00126"></a><spanclass="lineno"> 126</span><spanclass="comment">// Scaling up means multiplying by the scaling factors, while scaling down</span></div>
<divclass="line"><aid="l00127"name="l00127"></a><spanclass="lineno"> 127</span><spanclass="comment">// means dividing by the scaling factors.</span></div>
<divclass="line"><aid="l00130"name="l00130"></a><spanclass="lineno"> 130</span><spanclass="comment">// Computes the variance of the non-zero coefficients of the matrix.</span></div>
<divclass="line"><aid="l00131"name="l00131"></a><spanclass="lineno"> 131</span><spanclass="comment">// Used by Scale() do decide when to stop.</span></div>
<divclass="line"><aid="l00134"name="l00134"></a><spanclass="lineno"> 134</span><spanclass="comment">// Scales the rows. Returns the number of rows that have been scaled.</span></div>
<divclass="line"><aid="l00135"name="l00135"></a><spanclass="lineno"> 135</span><spanclass="comment">// Helper function to Scale().</span></div>
<divclass="line"><aid="l00138"name="l00138"></a><spanclass="lineno"> 138</span><spanclass="comment">// Scales the columns. Returns the number of columns that have been scaled.</span></div>
<divclass="line"><aid="l00139"name="l00139"></a><spanclass="lineno"> 139</span><spanclass="comment">// Helper function to Scale().</span></div>
<divclass="line"><aid="l00142"name="l00142"></a><spanclass="lineno"> 142</span><spanclass="comment">// Equilibrates the rows. Returns the number of rows that have been scaled.</span></div>
<divclass="line"><aid="l00143"name="l00143"></a><spanclass="lineno"> 143</span><spanclass="comment">// Helper function to Scale().</span></div>
<divclass="line"><aid="l00146"name="l00146"></a><spanclass="lineno"> 146</span><spanclass="comment">// Equilibrates the Columns. Returns the number of columns that have been</span></div>
<divclass="line"><aid="l00147"name="l00147"></a><spanclass="lineno"> 147</span><spanclass="comment">// scaled. Helper function to Scale().</span></div>
<divclass="line"><aid="l00151"name="l00151"></a><spanclass="lineno"> 151</span><spanclass="comment">// Convert the matrix to be scaled into a linear program.</span></div>
<divclass="line"><aid="l00154"name="l00154"></a><spanclass="lineno"> 154</span><spanclass="comment">// Scales the row indexed by row by 1/factor.</span></div>
<divclass="line"><aid="l00155"name="l00155"></a><spanclass="lineno"> 155</span><spanclass="comment">// Used by ScaleMatrixRowsGeometrically and EquilibrateRows.</span></div>
<divclass="line"><aid="l00158"name="l00158"></a><spanclass="lineno"> 158</span><spanclass="comment">// Scales the column index by col by 1/factor.</span></div>
<divclass="line"><aid="l00159"name="l00159"></a><spanclass="lineno"> 159</span><spanclass="comment">// Used by ScaleColumnsGeometrically and EquilibrateColumns.</span></div>
<divclass="line"><aid="l00162"name="l00162"></a><spanclass="lineno"> 162</span><spanclass="comment">// Looks up the index to the scale factor variable for this matrix row, in the</span></div>
<divclass="line"><aid="l00163"name="l00163"></a><spanclass="lineno"> 163</span><spanclass="comment">// LinearProgram, or creates it. Note lp_ must be initialized first.</span></div>
<divclass="line"><aid="l00166"name="l00166"></a><spanclass="lineno"> 166</span><spanclass="comment">// As above, but for the columns of the matrix.</span></div>
<divclass="line"><aid="l00169"name="l00169"></a><spanclass="lineno"> 169</span><spanclass="comment">// Returns a string containing information on the progress of the scaling</span></div>
<divclass="line"><aid="l00170"name="l00170"></a><spanclass="lineno"> 170</span><spanclass="comment">// algorithm. This is not meant to be called in an optimized mode as it takes</span></div>
<divclass="line"><aid="l00171"name="l00171"></a><spanclass="lineno"> 171</span><spanclass="comment">// some time to compute the displayed quantities.</span></div>
<divclass="line"><aid="l00174"name="l00174"></a><spanclass="lineno"> 174</span><spanclass="comment">// Pointer to the matrix to be scaled.</span></div>
<divclass="line"><aid="l00177"name="l00177"></a><spanclass="lineno"> 177</span><spanclass="comment">// Member pointer for convenience, in particular for GetRowScaleIndex and</span></div>
<divclass="line"><aid="l00181"name="l00181"></a><spanclass="lineno"> 181</span><spanclass="comment">// Array of scaling factors for each row. Indexed by row number.</span></div>
<divclass="line"><aid="l00184"name="l00184"></a><spanclass="lineno"> 184</span><spanclass="comment">// Array of scaling factors for each column. Indexed by column number.</span></div>
<divclass="ttc"id="aclassoperations__research_1_1glop_1_1_sparse_matrix_scaler_html_ab666962593c98de3b63fc31c49343645"><divclass="ttname"><ahref="classoperations__research_1_1glop_1_1_sparse_matrix_scaler.html#ab666962593c98de3b63fc31c49343645">operations_research::glop::SparseMatrixScaler::col_scale</a></div><divclass="ttdeci">const DenseRow & col_scale() const</div><divclass="ttdef"><b>Definition:</b><ahref="matrix__scaler_8h_source.html#l00107">matrix_scaler.h:107</a></div></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>
