RGF modular Version First release: Apr 19, 2000 Revision 1: Nov 11, 2000 Revision 2: Jul 05, 2001 Michael Hirsch, Wolfgang Quapp Mathematisches Institut, Unversität Leipzig Augustusplatz, 04109 Leipzig, Germany E-Mail: hirsch@mathematik.uni-leipzig.de quapp@mathematik.uni-leipzig.de References W.Quapp, M.Hirsch, D. Heidrich: Theor Chem Acc (1998) 100:285-299 W.Quapp, M.Hirsch, O.Imig, D.Heidrich: J Comput Chem 19 (1998) 1087-1100 Contents Installation Command line arguments Script file Return values Starting point The paramter file Example for the file »param.rgf« Description of the items Other file formats Point, gradient, Hessian, B-Matrix File result.rgf Installation The mRGF Package includes the following files: rgfman.txt - this manual Makefile - the Makefile rgf.f - the Fortran 77 source file of RGF utils.f - the Fortran 77 source file of utilities param.rgf - the parameter file for RGF Installation steps: * Copy all files in a new directory * Adjust the compiler settings in the Makefile for your system. The Makefile is configured for Linux on PC. * execute "make" Command line arguments The RGF-program accept some command line arguments. These are: -ver Print version informations to Standart Out and exit with Code 0 -ret Print description of return values to Standart Out and exit with Code 0 -para Print a short format description of "param.rgf" to Standart Out and exit with Code 0 -exact force the use of the exact hessian by this program call -update force the use of the updated hessian by this program call -reinit reread PSTEPL,CRIT_STOP,CRIT_PC,ITMIN,ITMAX from the "param.rgf". The file "param.rgf" will be opened by each call to read the job ID but the full parameterlist is only read by the first call. If some of the parameters mentioned above should be changed between two steps, this option can be used. any other argument: Print the list of command line arguments to Standart Out and exit with Code 0 RGF uses the DFP-Update by Davidon, Fletcher and Powell as it is descibed in: Heidrich, Kliesch, Quapp: "Properties...", Lecture Notes in Chemstry 56, Springer, Berlin, 1991 Script file This is an example for a bash script to apply modular RGF: #!/usr/bin/bash export status=0 while (test $status -ne 10) do gamess < mRGF/input > mRGF/output # gamess has created the gradient, hessian and b-matrix file if test $? -ne 0 then echo "Gamess Error occurred" exit fi cd mRGF rgf export status=$? if test $status -eq 1 then echo "RGF reported Error" exit fi toang < points > pp paste -d' ' varname pp > mitte cat oben mitte unten > input cd .. done Return values The RGF-program alternately return these values: "0" Occurs after printing info or help messages invoked by command line arguments "1" Error occurred (e.g. missing or wrong »param.rgf«) "4" Predictor executed, next hessian will be updated "5" Predictor executed, request for exact hessian next step "6" Corrector executed, next hessian will be updated "7" Corrector executed, request for exact hessian next step "10" Step executed. Stopping criterion satisfied The return value can read out of a shell environment variable (In this example: $?). Gamess is the quantum chemical program which calculate the gradient, the Hessian (at least once), and the Wilson B-matrix. These will be written in separate files in the mRGF directory and read by RGF-program. The RGF-program writes the new point in a file (Here: mRGF/points). The lines 5 to 3 from the bottom of the script build the new input file for Gamess and surely they must be different for any other application. If the Gamess-program returns not "0" or the RGF-program returns "1" the processing of the script stops. In the regular case, the script loop will be repeated until the RGF-program returns "10". Starting point There are two opportunities for the starting point of the RGF-method. The first is any stationary point, where the RGF-equation is fullfiled. In this case, a search direction must be specified in the param.rgf-file. The RGF-program starts in this direction with respect to the sign of the search vector. Hence, to start in the opposite direction, the sign of each component of the search direction must be changed. The second opportunity for a starting point is any point outside of stationary points. In this case, the gradient at this point gives the search direction. To apply this, the variable "o_free" must be set "T" in the »param.rgf«-file. Then, the RGF-program follows the curve to find stationary points of odd index, that means first order saddle points, third order saddle points and so on. To find a stationary point of even index (minima, second order saddle points) the variable »o_even« must be set "T". Now the RGF-program will follow the curve in opposite direction. The parameter file »param.rgf« The parameter file contains a sequence of Fortran form real numbers, double precision, followed by a namelist, with the parameters. Example for the file »param.rgf« 0.0d0 -0.2d0 -1.0d0 ¶m job_id=4 nn=3 z_FoP='point' z_FoG='gradient' z_FoH='hessian' z_FoB='bmatrix' z_FoR='results.rgf' o_flat=F o_free=F o_msg=F o_no_up=F o_const_sgn=F o_even=F o_recorr=F o_nn=F crit_stop=0.06 crit_pc=0.001 pstepl=0.1 itmin=5 itmax=100 / Description of the items Direction of search The first entry in »param.rgf« is the searchdirection. It is given by a sequence of N Fortran double precision real numbers (real*8), separated by space or newline characters, whereby N is the dimension, given by the variable »nn« in the »param«-namelist. It is the direction which the RGF-program follows. Along the RGF curve, the gradient points in this direction. At stationary points it coincides with the tangent direction. That means the RGF curve will leave stationary points with this direction. Possible Entries: Any vector, except the zero-vector. job_id=N (integer) An internal identifier for the Job. The RGF-program saves data from the current step in the file store.rgf in the mRGF directory. To be sure that the store.rgf is the right one for this Job the RGF-program compares the »job_id« variable from the parameter file with an entry in »store.rgf«. If they are different or if the »store.rgf« does not exist, RGF assumes a new Job, (re-)creates a new »store.rgf« file, writes »job_id« to it and starts with step 1. For equal entries RGF assumes a proceeding job, reads the stored values of the former step from »store.rgf« and calculates the next step. This entry is changed from string-type to integer-type since Revision 1. nn=N (integer) Dimension of the configuration space. The dimension is usually the number of the non-redundant internal coordinates: 3 x (Number of Atoms)-6. z_FoP=FILENAME (string) The name of the file containing the current point. The first point must be given, then the RGF-program write each new point in this file. z_FoG=FILENAME (string) The name of the file containing the current gradient. This file must be written external from data of the quantum chemical program at each point. z_FoH=FILENAME (string) The name of the file containing the Hessian. The first Hessian must be given, then the RGF-program calculate an update and save it in the store.rgf-file. If »o_no_up« is .true. (see there), the RGF-program reads the Hessian from the file given by FILENAME at each point. z_FoB=FILENAME (string) The name of the file containing the actual Wilson B-matrix. This file must be written externally from data of the quantum chemical program at each point. If »o_flat« is .true. (see there), then this file is not used and obsolete. z_FoR=FILENAME (string) The file of the regular RGF output. The RGF-program appends the output data to this file at each point. crit_stop=R (real*8) The Newton-Raphson step is calculated for the equation G(x)=0, where G is the gradient and x a point of the configuration space. This step will not be executed. It will be calculated to estimate the distance to the next stationary point. If the length of the Newton-Raphson step is less than R (double precison real number) the algorithm stops and return "10". Close to a stationary points, the length of the Newton-Raphson step is nearly equal to the distance to the stationary points. The stopping criterion should not be less then a half of the length of predictor steps (see »pstepl«) pstepl=R (real*8) The length of predictor step R (double precison real number) usually spreads along the curve at all components of the configuration space. Therefore it can be chosen larger for higher dimensions. For 3- and 4-atomic systems (dimension of the configuration space: N=3 resp. N=6) R=0.1 (bohr/radian) is a probed choice. crit_pc=R (real*8) Along a RGF curve the "reduced gradient", that is the part of the gradient which not points in the searchdirection, should be zero. R (double precison real number) is the maximal acceptable deviation of the length of the reduced gradient from zero. If the deviation is greater than R a corrector step will be executed, a predictor step otherwise. The predictor-corrector-criterion should be one order of magnitude less than the predictor step length, at least. The smaller the predictor-corrector-criterion, the better the algorithm works but the higher is the number of steps, necessarily. Probed values: 0.01 down to 0.0001 (bohr/radian). For the search of stationary points only, large values for R are often sufficient. itmin=N (integer) The minimal number N of predictor steps before the stopping criterion will be tested. RGF usually starts in stationary points. This entry prevents of the instant abort of the algorithm and ensure that the RGF curve can leave the stationary point. itmax=N (integer) The maximal number N of predictor and corrector steps. If this number is reached the algorithm aborts and returns 10. o_flat=T|F (logical) If set, the RGF-program uses the Euclidian scalar product: =v^1*w^1+..v^N*w^N, else the scalar product induced by the Wilson B-Matrix: =Sum v^i*g_(ij)*w^j, whereby g_(ij) is the metric tensor calculated from the B-matrix. If the dimension should be NOT 3 x (number of atoms)-6, the switch MUST be set. If it is set, the file with the Wilson B-matrix is not used by the RGF-program and obsolete, but usually, the program works more rawish and the number of steps increases. o_no_up=T|F (logical) If set, the RGF-program reads the Hessian from the file given by »z_FoH« at each point, else this file only will read at the first step and the Hessian will be updated in the next calculations. o_msg=T|F (logical) If set, the RGF-program writes some information for evaluation purposes in the file message.rgf. If an error occurs - the RGF-program returns "1" - also some error messages can be find there. o_const_sgn=T|F (logical) If set, after a change of the signature of the Hessian, the RGF-program requires a new external Hessian, otherwise not. Setting the switch makes the Update method more robust. The requirement of a new Hessian is indicated by the RGF-program return values. o_free=T|F (logical) If set, the RGF-program start at any point. The direction of search is given by the gradient at this point. Otherwise, the RGF-program has to start in a stationary point. The direction of search is read from the »param.rgf«-file. o_even=T|F (logical) If set together with »o_free«, the RGF-program search for stationary points with index 0,2,4,.., that means minima, second order saddle points and so on. Otherwise the program search for stationary points with index 1,3,.. , that means first order saddle points, third order saddle points and so on. The switch influences the direction of the first step, not the components of the direction of the search. o_recorr=T|F (logical) If set, the RGF-program prevents the corrector from alternating and increasing steplength. Often it may better the convergence of the corrector step, but this is not guaranteed. The correctorstep is a Newton-Raphsonstep perpendicular to the tangent. o_nn=T|F (logical) not implemented Other file formats Point, gradient, Hessian, B-matrix The files given by the »z_Fo?« variables must only contain sequences of Fortran form real numbers (double precision) separated by space or newline characters. If N is the dimension given by »nn«, the files must contain the following number of entries: variable expected entries z_FoP N z_FoG N z_FoH N x N z_FoB N x (N+6) Matricies must be written column by column into the files. File given by »z_FoR« At the begining, the result-file contains some informations of the switches set. Then follows one record for each point calculated. These records contains: * the number of the actual step and the maximal number of steps separated by "/" * "Predictor step" with number or "corrector step" * Messages if criterion for turning points or bifurcation points are satisfied * The length of the actual step. If the step is a predictor the length should be equal to the value of »pstepl«. If the step is a corrector, the length should be less than the length of predictor step. If the length of corrector is greater then the length of predictor it is really worse. Two "regular" reasons: The corrector step is a Newton-Raphson step perpendicular to the tangent. This method does not converge under all conditions. There may exist regions of the configuration space which not fulfill the convergence conditions. Try a shorter predictor step, other search directions or parameters. Especially close to bifurcation points it may happen that the corrector does not converge. Worse luck. Generally the RGF method crosses bifurcation points without trouble. Slightly modified parameters (step length, predictor-corrector-criterion) should solve the problem. * The actual point and the step which will be executed now in the input coordinates. * The signature of the Hessian, i.e. the number of positive, negative and (exact) zero eigenvalues * A table of actual values and criteria for comparison: Length of the gradient vector. At stationary points this length is zero. This criterion has no influence to the program processing. Length of the "reduced gradient". If the value is less than the criterion the actual step is a predictor step, a corrector step otherwise. (see »crit_pc«) Length of the Newton-Raphson step (see »crit_stop«). Not worry, this length can be really large. If the value is less than the criterion and the minimal number of predictor steps is done (»itmin«) the program stops successfully. End of Manual