src/mmdb_math_bfgsmin.h
Go to the documentation of this file.
00001 // $Id: mmdb_math_bfgsmin.h $ 00002 // ================================================================= 00003 // 00004 // CCP4 Coordinate Library: support of coordinate-related 00005 // functionality in protein crystallography applications. 00006 // 00007 // Copyright (C) Eugene Krissinel 2000-2013. 00008 // 00009 // This library is free software: you can redistribute it and/or 00010 // modify it under the terms of the GNU Lesser General Public 00011 // License version 3, modified in accordance with the provisions 00012 // of the license to address the requirements of UK law. 00013 // 00014 // You should have received a copy of the modified GNU Lesser 00015 // General Public License along with this library. If not, copies 00016 // may be downloaded from http://www.ccp4.ac.uk/ccp4license.php 00017 // 00018 // This program is distributed in the hope that it will be useful, 00019 // but WITHOUT ANY WARRANTY; without even the implied warranty of 00020 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00021 // GNU Lesser General Public License for more details. 00022 // 00023 // ================================================================= 00024 // 00025 // 12.09.13 <-- Date of Last Modification. 00026 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 00027 // ----------------------------------------------------------------- 00028 // 00029 // **** Module : BFGSMin <interface> 00030 // ~~~~~~~~~ 00031 // **** Classes : mmdb::math::BFGSMin ( minimization driver ) 00032 // ~~~~~~~~~ 00033 // 00034 // (C) E. Krissinel 2000-2013 00035 // 00036 // ================================================================= 00037 // 00038 00039 #ifndef __MMDB_MATH_BFGSMin__ 00040 #define __MMDB_MATH_BFGSMin__ 00041 00042 #include <stdlib.h> 00043 00044 #include "mmdb_mattype.h" 00045 #include "mmdb_math_linalg.h" 00046 00047 00048 namespace mmdb { 00049 00050 namespace math { 00051 00052 // ============================================================== 00053 00054 enum BFGS_RC { 00055 BFGS_TooFewDigits = -2, 00056 BFGS_WrongSpaceDim = -1, 00057 BFGS_NoTermination = 0, 00058 BFGS_SmallGradient = 1, 00059 BFGS_SmallStep = 2, 00060 BFGS_LineSearchComplete = 3, 00061 BFGS_IterationLimit = 4, 00062 BFGS_LargeSteps = 5, 00063 BFGS_Stopped = 6 00064 }; 00065 00066 typedef void BFGSMinFunc ( void * UserData, int N, rvector X, 00067 realtype & F ); 00068 typedef BFGSMinFunc * PBFGSMinFunc; 00069 00070 typedef void BFGSPrintFunc ( void * UserData, int N, int Itn, 00071 rvector X, rvector G, realtype F ); 00072 typedef BFGSPrintFunc * PBFGSPrintFunc; 00073 00074 DefineClass(BFGSMin); 00075 00076 class BFGSMin { 00077 00078 public : 00079 00080 BFGSMin (); 00081 virtual ~BFGSMin(); 00082 00083 virtual void MinFunc ( rvector X, realtype & F ); 00084 virtual void Print ( int Itn, rvector X, rvector G, 00085 realtype F ); 00086 00087 void SetMinFunction ( void * UserData, PBFGSMinFunc Fnc ); 00088 void SetPrintFunction ( void * UserData, PBFGSPrintFunc Fnc ); 00089 00090 00091 // ====================================================== 00092 // 00093 // .--------------------------------------------. 00094 // | | 00095 // | UNCONSTRAINED MINIMIZATION DRIVER | 00096 // | | 00097 // `--------------------------------------------' 00098 // 00099 // Finds a minimum of function F(X), X is vector [1..N], 00100 // defined by virtual MinFunc. Virtual Print provides 00101 // information on every iteration step. 00102 // 00103 // 00104 // Input parameters : 00105 // ----------------------- 00106 // 00107 // N is the dimension the minimization space 00108 // 00109 // x0 [1..N] is the initial point for minimization 00110 // 00111 // TypX [1..N] is the array of the typical ranges of 00112 // X - components, which are used for the scaling. 00113 // If TypX<=0.0 then 1.0 will be substituted 00114 // 00115 // Digits is the number of valid decimal digits in 00116 // the calculated value of minimizing function ( F ). 00117 // If Digits<=0 then the Driver will consider 00118 // that the F is computed with usual machine's 00119 // noise 00120 // 00121 // ItnLmt is the maximum available number of iterations. 00122 // If ItnLmt=0 then 100 will be substituted 00123 // 00124 // TypF is the expected absolute value of F in the 00125 // minimum, which is used in the stop criterion. 00126 // If TypF<=0.0 then 1.0 will be substituted 00127 // 00128 // GrdTol is the desired absolute value of the gradient 00129 // vector in the minimum of F . If GrdTol<=0.0 00130 // then the some value correlated with machine's 00131 // noise will be substituted 00132 // 00133 // StpTol is the minimum available step for the minimi- 00134 // zation. The execution stops if the distance 00135 // between two consequential approximation will be 00136 // less then StpTol . If StpTol<=0.0 then the 00137 // some value correlated with machine's noise 00138 // will be substituted 00139 // 00140 // MaxStp is the maximum available step for then minimi- 00141 // zation. This parameter only prevents the appea- 00142 // rance of the too large steps, but the execution 00143 // stops if more than 5 steps with length of MaxStep 00144 // will consequently appear. 00145 // 00146 // 00147 // 00148 // Outpute parameters : 00149 // -------------------------- 00150 // 00151 // x0 will be the point at which the minimisation 00152 // had stopped 00153 // 00154 // Func will be the function's value at x0 00155 // 00156 // TermCode will be the reason of stopping : 00157 // 00158 // 1 <=> the norm of gradient vector at x0 is 00159 // less than GrdTol ; the x0 is probable 00160 // point of the minimum 00161 // 2 <=> the distance between two last approxima- 00162 // tions was less than StpTol ; the x0 00163 // may be the point of minimum 00164 // 3 <=> the gradient length is greater than 00165 // GrdTol , but future minimization fails ; 00166 // it may be the consequence of the errors 00167 // at the computing of gradient, but also 00168 // x0 could be the point of minimum 00169 // 4 <=> the iteration limit had been exchausted 00170 // 5 <=> more than 5 steps with length of 00171 // MaxStp had been made 00172 // 6 <=> the termination key ( Esc or End ) 00173 // had been pressed. 00174 // 00175 // 00176 // ======================================================== 00177 00178 void BFGS_Driver ( int MinN, 00179 rvector x0, 00180 rvector TypX, 00181 realtype & FuncValue, 00182 int & TerminationCode, 00183 int Digits = 0, 00184 int ItnLmt = 0, 00185 realtype TypF = 0.0, 00186 realtype GrdTol = 0.0, 00187 realtype StpTol = 0.0, 00188 realtype MaxStp = MaxReal, 00189 bool Hess = false, 00190 rvector LowLimit = NULL, 00191 rvector TopLimit = NULL ); 00192 00193 void Stop(); // generates stop signal to stop optimization 00194 00195 00196 protected : 00197 00198 PBFGSMinFunc MFunc; 00199 void * MFuncData; 00200 PBFGSPrintFunc PFunc; 00201 void * PFuncData; 00202 00203 int N,NAlloc; 00204 rmatrix Hsn; 00205 rvector TL,LL,XOpt,XPlus,Sx,SN,HDiag,GradX,GPlus; 00206 rvector StepSize,FNeighbor; 00207 rvector us,uy,ut; 00208 bvector Freese; 00209 realtype Func,FPlus,FOpt; 00210 realtype TakenLambda; 00211 bool ForDiff; // if True then forward differences are 00212 // used for the 1st estimation of the 00213 // Hessian (which is less expensive), 00214 // otherwise central differences will 00215 // be employed (which is more expensive). 00216 bool CalcHess; 00217 00218 realtype Etha,SqrtEtha,CubertEtha,TpF,GrdEps,StpEps,MxStep; 00219 realtype SqrtEps; 00220 int CnsMax,MaxItn,TermCode; 00221 bool ModF; 00222 00223 void MinFunc1 ( rvector X, realtype & F ); 00224 void UMInCk ( rvector x0, rvector TypX, 00225 int Digits, realtype TypF, 00226 realtype GrdTol, realtype StpTol, 00227 realtype MaxStp, int ItnLmt ); 00228 void UMStop0 ( rvector x0, rvector Grad ); 00229 void UMStop ( rvector x0, rvector Grad, int RetCode, 00230 int ItnCnt, bool MaxTkn ); 00231 00232 virtual void Gradient ( rvector X, rvector G, realtype Fc ); 00233 virtual void FDHessF ( realtype Fc, rvector X ); 00234 00235 void FDGrad ( rvector X, rvector G, realtype Fc ); 00236 void CDGrad ( rvector X, rvector G ); 00237 void MdHess ( rmatrix H, rvector HDg ); 00238 void InitHessUnFac ( realtype F, rmatrix H ); 00239 void BFGSUnFac ( rvector Xc, rvector Xp, 00240 rvector Gc, rvector Gp, 00241 bool AnalGrad, rvector HDg, 00242 rmatrix H ); 00243 void Choose_Lambda ( rvector X, rvector S, realtype & Lambda0 ); 00244 void LineSearch ( rvector px0, rvector G, 00245 rvector P, realtype pFunc, 00246 int & RetCode, bool & MaxTkn ); 00247 void GetMemory (); 00248 void FreeMemory (); 00249 void Relax (); 00250 void CopyPlus ( rvector x0 ); 00251 00252 }; 00253 00254 } 00255 00256 } 00257 00258 #endif 00259 00260
