================================================== Copyright And License Agreement ================================================== MMSQ Version 1.1, 13th of april 1992. You may copy and distribute copies of the complete MMSQ source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each file a valid copyright notice "Copyright (C) 1991 Rob Hooft, Utrecht University"; keep intact the notices on all files that refer to this License Agreement and give other recipients of MMSQ a copy of this license agreement along with the program. You may charge a distribution fee for the physical act of transferring a copy. You may copy and distribute MMSQ in object code or executable form under the terms mentioned above provided that you also accompany it with the complete corresponding machine-readable source code, which must also be distributed under the terms mentioned above. You may not copy, sublicense, distribute or transfer MMSQ except as expressly provided under this license agreement. (This license agreement has been modelled after the GNU GENERAL PUBLIC LICENSE) ================================================== FILES IN THE PACKAGE ================================================== The distribution of MMSQ consists of the following files: BUILD_SQUARE.FOR MMSQ initiator: creates binary and history file CLEANHIS.FOR Clean up a history file (makes every point occur once) MMFINISH.FOR Summarize MM2 output-files to history and binary file MMINS.FOR MM2 front-end program MMSTART.FOR the main `prudent ascent' program SQUARE_NONEBUSY.FOR Tell MMSTART that calculations have crashed SUBROUTINES.FOR Some VAX-fortran subroutines that occur frequently SQUARE.INC included part of some programs. CLPROP.DAT Test-deck part 1 CLPROP.RES Test-deck part 2 SQUARE.DAT Test-deck part 3 CLPROP.HIS Test-deck resulting square.his MAKEFILE. Makefile for all the programs. COMPILE.COM Builds MMSQ on systems that lack VMS MAKE MANUAL.TXT This manual MMINS.TXT MMINS documentation MMRUN.COM procedure used to call MM2 from MMSQ MMSQ.COM MMSQ main procedure. SYMBOLS.COM Definition of symbols needed for MMSQ For unix implementations: SUBROUTINES.UNIX Unix version of SUBROUTINES.FOR MAKEFILE.UNIX Unix version of MAKEFILE MMSQ.CSH Unix version of MMSQ.COM MMRUN.CSH Unix version of MMRUN.COM ALIASES.CSH Unix version of SYMBOLS.COM RENAME.CSH Unix rename procedure The distribution requires a version of MM2 or MM3, which however is not included. The program-package was designed on a VAX/VMS system, and ported to UNIX machines on which the FORTRAN compiler can handle 'STRUCTURE' statements, such as the Silicon Graphics Workstations. ================================================== What is MMSQ, the `prudent ascent' method ================================================== The prudent ascent method is described in: Rob W.W. Hooft, Jan A. Kanters & Jan Kroon, Implementation and use of the `method of prudent ascent'. Journal of Computational Chemistry (August 1991). In principle it is a method to calculate a potential energy map of a molecule, as a function of two torsion angles in the molecule. The main differences with the MM2 DRIVER option are: 1) The order in which the calculations are carried out is not pre-determined. 2) A recalculation is carried out if a conformational change occurs in the unrestrained part of the molecule. Implementation of the algorithm is by repeatedly calling MM2/3 for a single DRIVER step. Which step is to be calculated is decided by "MMSTART". After the calculation "MMFINISH" summarizes the output. The authors of the article can be reached via E-Mail: hooft@hutruu54.bitnet OR hooft@chem.ruu.nl kanters@hutruu54.bitnet kroon@hutruu54.bitnet Postal Address: Bijvoet Center for Biomolecular Research Lab. for Crystal and Structural Chemistry Rijksuniversiteit Utrecht Padualaan 8 NL-3584 CH Utrecht The Netherlands ================================================== What is MMINS ================================================== MMINS is a front-end program for MM2, programmed by Dr. Huub Kooijman at our laboratory. Documentation can be found in MMINS.TXT. The author of the program can be reached via E-Mail: huub@hutruu54.bitnet OR huub@chem.ruu.nl or at the postal-address mentioned above. ================================================== Installation of MMSQ on VMS systems ================================================== 1) Copy all the files of the distribution to a separate directory. 2) edit the SYMBOLS.COM file. Put the names of the MM2/3 executables and directories and the MM3 parameter file in the right place. 3) Look at MMRUN.COM. MMRUN.COM will be called with 2 parameters: p1: the name of the input file (without extension) p2: the name of the MM2 program to be executed. Make sure that a call of MMRUN.COM will result in MM2/3 reading NAME.INS and writing resulting coordinates to NAME.RESN and list output to NAME.OUT. Also take care to delete scratch-files that are produced. The MMRUN.COM file that is distributed with the program works with our versions of MM2/3. 3) Check an OUT file produced by your version of MM2/3, it should be readable by MMFINISH. MMFINISH looks for a line in which the words 'FINAL STERIC ENERGY' are at columns 7 to 25 or at columns 6 to 24. Then it skips the empty lines present and reads the energies present at the next lines. The only energies that are really needed are the FINAL STERIC ENERGY and the COMPRESSION ENERGY. The program as it is now works with our versions of MM2/3. Change MMFINISH.FOR if necessary. 4) Check a RES file produced by your version of MM2/3, it should be readable to MMSTART. Because we think MMSTART will be able to read most RES files, you can delay this step until something is wrong. remedy: change MMSTART.FOR to handle the RES file properly. 4) Call MAKE, if you have MAKE installed, or type @COMPILE otherwise. 5) Edit the LOGIN.COM file in your home directory to call SYMBOLS.COM See also "RUNNING THE TEST DECK" below. ================================================== Installation of MMSQ on UNIX systems ================================================== Since the unix operating system is very diverse, not all systems will install as smoothly as is stated here. Installation at our lab was performed on an SGI 4D/20 system running IRIX 3.2 1) Copy all the files of the distribution to a separate directory. Then execute the rename.csh cshell script by typing "source rename.csh" while in the distribution directory. If this script does not work for you, the steps that have to be performed are: a) All files should be named with lowercase names. b) All ".csh" files should have their extensions removed. c) All ".for" files should be renamed to ".f". d) All ".com" files can be removed. e) 'subroutines.for' can be moved to 'subroutines.vms', and 'subroutines.unix' should be named as 'subroutines.f'. f) 'makefile.unix' should be named 'Makefile', and the vms 'makefile' should be removed. g) The files mmrun, mmsq and aliases should be made executable. 2) edit the 'aliases' file. Put the names of the MM2/3 executables and directories in the right place. For mm3 the location of the parameter file should probably be defined also. 3) Look at 'mmrun' 'mmrun' will be called with 2 parameters: $1: the name of the input file (without extension) $2: the name of the MM2 program to be executed. Make sure that a call of 'mmrun' will result in MM2/3 reading $1.ins and writing resulting coordinates to $1.resn and list output to $1.out Also take care to delete scratch-files that are produced. The 'mmrun' file that is distributed with the program works with our versions of MMP85 and MM2HB 3) Check an OUT file produced by your version of MM2/3, it should be readable to MMFINISH. MMFINISH looks for a line in which the words 'FINAL STERIC ENERGY' are at columns 7 to 25 or at columns 6 to 24. Then it skips the empty lines present and reads the energies present at the next lines. The only energies that are really needed are the FINAL STERIC ENERGY and COMPRESSION ENERGY. The program as it is now works with our versions of MM2/3. Change 'mmfinish.f' if necessary. 4) Check a RES file produced by your version of MM2/3, it should be readable to MMSTART. Because we think MMSTART will be able to read most RES files, you can delay this step until something is wrong. remedy: change 'mmstart.f' to handle the RES file properly. 4) Call 'make'. 5) Edit your '.cshrc' file in your home directory to call 'source aliases' See also "RUNNING THE TEST DECK" below. ================================================== Running MMSQ ================================================== To start an MMSQ run, three files have to be created: 1) square.dat contains information to MMSQ about the run that is performed. 2) xxxxx.yyy (as specified RESFILE in SQUARE.DAT) contains the starting coordinate set. 3) xxxxx.yyy (as specified DATFILE in SQUARE.DAT) contains any MMINS commands that have to be passed on to MMINS for each run. SQUARE.DAT ========== The possible commands in SQUARE.DAT are: DRIVE at1 at2 at3 at4 start end step driver_mode Essentially the same command as in MMINS. Instructs MMSQ to use driver 'driver_mode' (1 or -1) on atoms at1--at4. Calculations are performed using stepsize 'step' between 'start' and 'end'. All values in degrees. Atoms must be given as numbers, because labels are not conserved during the MMSQ run. If END-START+STEP=360 degrees periodicity is taken into account for the `prudent ascent' algorithm. Please note that standard DRIVER 1 is not able to cross 0 or 180. This is not noted by MMSQ and will result in faulty symmetric maps. A patch is available to correct this problem in MM2. One or two drive commands MUST be present in SQUARE.DAT NOW xx.x [yy.y] Specifies the value of the one or two torsion angles specified with DRIVE as they are in the starting coordinate set. If no NOW command is present the conformation in the RESFILE is checked. RESFILE fffffff.ttt Specifies the name of the file containing the input coordinates. DATFILE fffffff.ttt Specifies the name of the file containing the MMINS commands to use in every run. ENERMAX xxxx.y Specifies the limit of the TOTAL STERIC ENERGY at which the MMSQ procedure is to be aborted. This is the absolute energy that MM2/3 reports. During the run of MMSQ this value can be lowered, but it must not be raised once BUILD_SQUARE has been run. Default value is 1000.0 JUMP xxxx.y Specifies the minimum difference in energy from point X to point Y which must be present for a calculation of Y to be redone starting from X. Default value is 0.1, which is normally ok. If e.g. two neighboring points have energies of 1.0 and 1.05 kcal/mol respectively at a certain moment, with the default value of 0.1 for JUMP the calculation from 1.0 -> 1.05 will not be performed. Usually sufficient recalculations are performed with this value of JUMP. If an improvement in the convergence is needed, it can be of use to set JUMP to a lower value, or even a large negative value. This last option will insure that all connections in the map will be calculated in both directions: The average number of calculations per point will thus rise dramatically. This option has thus far only been used to give better results with one-dimensional DRIVER's. Lines in SQUARE.DAT starting with ! or MESS are ignored. Lines other than ENERMAX should not change once the procedure has been started. The RESFILE: ============ This is supposed to be the result-file of a MM2/3 run on an unrestrained molecule. The DATFILE: ============ This is an MMINS command file containing all commands that should be given at each run. No DRIVE commands are allowed in this file: those will be generated by MMSTART. It is suggested to use an 'IPRINT 4' command to reduce the I/O load. If charges must be present on the atoms during each run, all atoms should be present in the DATFILE. Coordinates will be ignored, but the charges will be used in each run. The order of appearance in the DATFILE should be the same as in the RESFILE. This is not checked. If no charges are to be used, it is necessary to explicitly tell MMINS using the command 'NDC 0 OVERRULE', otherwise zero charges will be added to the MM2/3 inputfile. An 'ADD' card should not be present in this file: instead all atoms including lone-pairs should already be present in the RESFILE. PI atoms should be specified using a separate PI card for MMINS in the DATFILE, and not using a 'P' character on each PI atom line. 'P' characters will be ignored. The same holds for X,Y,Z restraining. It is also necessary to put in a line that specifies the version of MM2/3 that is being used. (OUTPUT xxx) ======================= BUILD_SQUARE ======================= If the three files described above have been created, use the command 'BUILD_SQUARE' to create the binary file and the history file used during the MMSQ procedure. If two driver angles are present in SQUARE.DAT, BUILD_SQUARE will also create a file MKDIR.COM (on a unix system mkdir.csh) which can be used to create the directory structure needed for the actual run. Execute it by typing '@MKDIR' (on a unix system 'source mkdir.csh'). ======================= RUNNING ======================= Start MMSQ on a vax system using the command: mmsq queuename mm_version or on a unix system by submitting the command 'mmsq mm_version' to your batch system. If no queuename is given the procedure will submit itself to SYS$BATCH If no mm_version is given MM3 is used. For MM2HB, MMP85 and MM3 runs it is possible to create multiple runs on different nodes in a VAX-cluster, that are working on the same problem in parallel. For MM287 this would result in filename conflicts, because this program uses standard filenames like CPD.MM2 for each job. No parallelisation is supported for unix systems. There is a theoretical possibility that parallel runs result in a history- or binary-file timeout for one of the processes, but only if one of the others is suspended for a long time. ============================ RUNNING THE TEST-DECK ============================ To run the test-deck copy the three files square.dat, clprop.dat and clprop.res to a separate directory, run build_square, execute the mkdir script generated and start MMSQ with mm_version MM3. If MM3 is not available or another MM version is to be checked, change the `OUTPUT' line in the CLPROP.DAT file, and run using the appropriate mm_version. If the calculation completes succesfully, compare the SQUARE.HIS file generated with the CLPROP.HIS file supplied with the distribution. Small changes in the total energy reflecting the change in MM program and forcefield and the computer accuracy are possible. WARNINGS: 1) The test deck is a set of example inputfiles. It is not meant as a complete test of the installation of the MMSQ package. 2) Generally a grid-size of 10 degrees (or smaller for dihedrals in rings) is to be preferred instead of the 20 degrees step used in the test deck. ============================ A WARNING FOR RING DRIVING ============================ An attempt has been made to prevent "exploded molecules" to corrupt the result of subsequent calculations. This is done by a check on the COMPRESSION ENERGY. Computations that result in a negative compression energy will be discarded. However: since the connectivity is redetermined by MMINS at every step, it is possible for a bond to break slowly, and unnoticed by this mechanism. ======================== STOPPING ======================== To stop the procedure create the file 'please.stop' in the problem directory. The procedure will not start any new steps. ================================================== What to do if the computer crashed ================================================== MMSQ will restart if the computer reboots. This can result in a hole in the potential-energy map, because the point that was being calculated at the moment of the crash is marked as 'being calculated now', but will never be finished. The best way to solve this problem is stopping all jobs working on the problem by creating the file 'please.stop', and if they have all stopped running SQUARE_NONEBUSY. This program will clear all busy-flags. Then restart the batch-jobs. ============================ Cleanup of the history file ============================ In the history file, the first two columns are the two driver angles, the third column is the 'FINAL STERIC ENERGY', and the remaining columns are the remaining values from the ENERGY table in the MM2 output listing. The CLEANHIS program is able to build a copy of the SQUARE.HIS file in which each configuration is only mentioned once. Only the lowest potential energy result for each point is copied. The resulting file is CLEAN.HIS The cleanhis program can be run at any time during the MMSQ calculation to produce an intermediate result.