TASC modular Version 1 First release: Aug 31, 2001 Wolfgang Quapp Mathematisches Institut, Unversität Leipzig Augustusplatz, 04109 Leipzig, Germany E-Mail: quapp@rz.uni-leipzig.de References W.Quapp, M.Hirsch, D. Heidrich: Theor Chem Acc (2000) 105: 145-155, DOI 10.1007/s002140000192, W.Quapp: Computers and Mathem with Applic (2001) 41,No.3/4: 407-414 This program is based on the RGF program by Michael Hirsch and Wolfgang Quapp Mathematisches Institut, Unversität Leipzig Augustusplatz, 04109 Leipzig, Germany E-Mail: hirsch@mathematik.uni-leipzig.de quapp@rz.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 mTASC Package includes the following files: TASCman.txt - this manual Makefile - the Makefile TASC.f - the Fortran 77 source file of TASC utils.f - the Fortran 77 source file of utilities param.rgf - the parameter file for RGF / TASC 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 TASC-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 TASC/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 TASC: #!/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 grep -a 'total energy ' output |tail -1 > energy tr -s ' ' < energy > pp cut -d' ' -f5 pp > energy # the energy is grasped from the output of Gamess TASC fi cd mRGF rgf export status=$? if test $status -eq 1 then echo "TASC reported Error" exit fi toang < points > pp paste -d' ' varname pp > mitte cat oben mitte unten > input cd .. done Return values The TASC/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 directory and read by TASC-program. The 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 TASC. The first is any stationary point of index 0 or 1, where the GE-equation is fullfiled. In this case, a search direction must be specified in the param.rgf-file. The best choice is the smallest eigenvector of the hessian. (Other directions are possible - they are corrected by the corrector steps.) The 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 (mainly for a minimum-search). In this case, the gradient at this point gives the first search direction. To apply this, the variable "o_free" must be set "T" in the »param.rgf«-file. Then, TASC first searches for the valley, and then follows the valley- curve to find a stationary point of even index (minimum). The variable »o_even« must be set "T". 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« in case of H_2CO path min-->sp .02d0 .05d0 .0d0 -0.3005d0 0.003005d0 .0000d0 ¶m job_id=4 nn=6 z_FoP='punkt' z_FoG='gradient' z_FoH='hessian' z_FoB='bmatrix' z_FoR='results.rgf' z_FoE='energy' o_flat=F o_free=T o_msg=T o_no_up=T o_const_sgn=F o_even=F o_recorr=F o_nn=F crit_stop=0.09d0 crit_pc= 0.01d0 pstepl= 0.20d0 itmin=5 itmax=200 / Description of the items Direction of search The first entry in »param.rgf« is the search direction. 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 TASC-program first follows. At stationary points it should coincide with the eigenvector direction. Possible Entries: Any vector, except the zero-vector. job_id=N (integer) An internal identifier for the Job. The TASC/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, TASC/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. 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 TASC-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 TASC/RGF-program calculate an update and save it in the store.rgf-file. If »o_no_up« is .true. (see there), the 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_FoE=FILENAME (string) The name of the file containing the actual energy (function value). This file must be written external from data of the quantum chemical program at each point. The file is new in TASC, it was not used in the previous versions of RGF up to Revision 2: Jul 05, 2001! z_FoR=FILENAME (string) The file of the regular TASC output. The 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 an RGF curve the "reduced gradient", that is the part of the gradient which not points in the search direction, 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. TASC usually starts in stationary points. This entry prevents of the instant abort of the algorithm and ensure that the 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 TASC/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 TASC-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 TASC-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_no_up=T is recommended for TASC. o_msg=T|F (logical) If set, the TASC-program writes some information for evaluation purposes in the file message.rgf. If an error occurs - the 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 TASC-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 TASC-program return values. o_free=T|F (logical) If set, the TASC-program start at any point. The direction of search is given by the -gradient at this point. Otherwise, the TASC-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 TASC-program search for stationary points with index 0. that means minima. Otherwise the program search for stationary points with index 1, that means first order saddle points. 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-Raphson step perpendicular to the tangent. In TASC, the steplength of the corrector is restricted, at all. o_nn=T|F (logical) not implemented Other file formats Point, gradient, Hessian, B-matrix, energy 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) z_FoE 1 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" where Predictor step are counted "twice" for step length search * Messages if criterion for turning points or bifurcation points of the corresponding RGF definition are satisfied * The length of the actual step. If the step is a predictor the "second" real length should be less or equal to the value of »pstepl«. If the step is a corrector, the length is restricted to be less than the maximal length of predictor step »pstepl«. Reasons for misfits: 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. See the references to the TASC method. * 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. Note, the last step in TASC is done by the Newton-Raphson step. * The eigenvalues of the hessian. End of Manual