14 April 1992 Purpose: This document describes the contents of the "mm2_params" distribution. Description of the program: "mm2_params" is a C language program which attempts to remedy missing parameter messages from either MM2(87) or MM3. Often, MM2/MM3 will be unable to process a structure because required parameters are missing. One method of supplying crude parameters is for the researcher to manually select them from known parameters based on their knowledge of the similarity of atom types, using atom number, hybridization, electronegativity, etc. "mm2_params" attempts to replicate this similarity matching in an automated, consistent fashion. "mm2_params" does NOT produce optimized parameters - it produces a first guess based solely on similarities, which is intended to be used as an adequate starting point for optimization by the researcher. For method details, see The Journal of Computational Chemistry (1991) 12(7), 844, "Development of an Internal Searching Algorithm for Parameterization of the MM2/MM3 Force Fields". Contact: Dr. Dora Schnur Mail Stop U3E Monsanto Agricultural Group 800 North Lindbergh Boulevard St. Louis Missouri 63167 USA Phone: (314) 694-1563 (Timezone is GMT+6) Email: dmschn@bb1t.monsanto.com Conditions: This program is copyright 1992 by Monsanto Company. It is provided without support of any kind. No warranty as to suitability of use for any purpose is extended. Please notify Dora Schnur at the above contact address if you obtain a copy of this program. We would also appreciate bug reports and any enhancements you may make to the code. Files included in distribution: readme.mm2_params - This file. mm2_params.c - mm2_params program C source code. utility.c - Utility library routines C source code. utility.h - Utility library header file. mm2_params.make - Make file to build mm2_params. mm2.site_parameters - Sample "local site" additional parameters for MM2. thiophene.mm2 - Sample MM2 input file (will generate errors). thiophene_mm2.out - Sample MM2 output file (contains errors). thiophene.para - Sample output from mm2_params. Environment variables used: The environment variable LOCAL_DATA is used to determine the location of the known MM2/MM3 parameter files. See "External files used" section for details. External files used: mm2_params requires either $LOCAL_DATA/mm2.builtin_parameters or $LOCAL_DATA/KONST89.MM3, depending on whether it is working on MM2 or MM3 output files. The environment variable LOCAL_DATA must be defined to be the directory containing these files. The MM2 built in parameter file is obtained by feeding MM2 an input file containing one blank line, and renaming the produced "TAPE4.MM2" file as "mm2.builtin_parameters". The MM3 built in parameter file ("KONST89.MM3") is shipped with the MM3 program distribution. Additionally, if either optional file $LOCAL_DATA/mm2.site_parameters or $LOCAL_DATA/mm3.site_parameters is present, the "site specific" parameters contained therein are read to augument or supercede the basic parameters obtained from the required built in parameter file (described above). The formats of both optional site parameter files are identical, and are described in detail in the sample mm2.site_parameters file which is included in this distribution. Making the mm2_params program: The command "make -f mm2_params.make" will compile and link the program, leaving the executable in the current directory. Using the mm2_params program: mm2_params [-a] [-d] {single output file with errors} -a option: Automatically accept all synthesized parameters without querying user for acceptability. -d option: Print additional debug information detailing similarity comparisons and source of matched parameters. The single output file specified must have a file name with the form "xxx_mm2.out" or "xxx_mm3.out", where "xxx" represents any arbitrary string, not limited in length, usually descriptive of the structure. mm2_params will automatically determine whether it is working on a MM2 or MM3 output file based on the name of the file. NOTE: neither MM2 nor MM3, as shipped, produce output files with names of this form. We use a script which automatically takes care of all renaming. You will have to either rename the output files manually from the normally produced TAPE4.MM2 or TAPE4.MM3 files, or write a script to do it. From this file name, mm2_params will automatically construct the name of the corresponding structure file used as original input to MM2/MM3 as "xxx.mm2" or "xxx.mm3" and attempt to read this file, which must be present in the current working directory. The synthesized parameters will be written to a file called "xxx.para", where "xxx" is derived from the original output file name. This file is an additional parameter file in MM2/MM3 format. It is meant to be supplied to MM2/MM3 in a subsequent rerun of the original input file (setting the "additional parameters" flag in the input file). If the "-a" parameter is not used, mm2_params will query the user for each and every missing parameter, using the "best guess" parameter as the default answer. The researcher may either accept the proffered value (it is the most similar match found), or enter in their own, overriding value at that point. mm2_params will not modify an existing file in any way. It will create only the "xxx.para" file upon completion. Caveats: mm2_params dissects the original output file ("xxx_mm2.out" or "xxx_mm3.out" - remember, MM2/MM3 will produce the files with the names TAPE4.MM2 or TAPE4.MM3, but they *must* be renamed) looking for error messages. It navigates through the output files (which were never *intended* to be readable by a program) by looking for critical phrases. It is thus sensitive to the exact wording used by MM2/MM3 to report errors. Changes to MM2/MM3 that affect the critical wording used to report errors will break this program. The exact same constraints hold for reading the built in parameter files. In both cases (MM2/MM3), the exact wording and format of the file is critical, and changes will adversely affect the ability of mm2_params to understand the basic parameter definitions. Notes on the symbolic constants: All symbolic constants are defined at the top of the mm2_params.c source code. Both constant names and comments should be descriptive. Note that maximum numbers of each *kind* of error and parameter are defined here. If your site has unusually large numbers of errors or locally defined parameters, these may require changing.