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.