Atom typing behavior
********************

To use a classical forcefield each atom should be given a type, and a
partial charge. The power of the UFF forcefield is that this
atomtyping is done automatically. For other force fields the
atomtyping for most systems still has to be done by hand, possibly
with the help of an external program. Unlike UFF parameters, the
available parameters for the other available force fields typically
cover only a fraction of all chemical elements. Nonetheless,
experimental atomtyping options are available for small organic
molecules (GAFF), and for biological systems (AMBER).


UFF
===

Atom typing is the process of matching MM atom types to elements. For
example, a Carbon atom becomes a C_1, C_2, C_3 or C_R, depending on
the number (and type) of bonds it has to neighboring atoms. UFF is
capable of finding a matching MM atom type on its own, but might not
always succeed in doing so. When doing calculations with UFF, it is
important to check the beginning of the output file, as the program
will print the detected MM atom types there. You can also take matters
into your own hands, and tell UFF what MM atom types you want it to
use (see the section on Input and examples).

It may be desirable to reuse the atom types and charges from a
previous UFF calculation on the same system. This can be done in two
ways.

1. By referring to an RKF file

2. By explicitly adding the atom typing information to the input file

For the first option, use the keyword "ReuseTypeInfo" referencing the
engine RKF file from the previous UFF calculation (usually named
forcefield.rkf).

   ReuseTypeInfo string

"ReuseTypeInfo"
   Type:
      String

   Default value:
   Description:
      Path to RKF file with atom typing information (atom types,
      charges, and - in case of GAFF or APPLE&P - possibly a
      forcefield (patch) file for the system).

To add the information explicitly to the inputfile one can copy the
atomtyping information from the output file. For the addition of atom
types and charges to input, see Adding atom types and charges.

The atom typing in UFF is mostly controlled by the elements and
mmatomtypes parameter files, however, some part of it is hidden in the
code itself and is (at the moment) not accessible to users. This is
done by UFF to differentiate between:

* Carbon: double-bonded sp2 carbon (C_2) vs aromatic carbon (C_R), if
  any of the orders are close to 2, it's C_2.

* Oxygen: having a bond to silicon gives O_3_z; otherwise, having bond
  order of 1.44 or higher gives O_R, provided that the partner is not
  a hydrogen. Otherwise, it's just an O_3.

* Sulfur: having a bond order greater than 1.3 gives aromatic S_R.

By default, zero charges are used, unless a water molecule is
detected. Note that if some charges are pre-defined by the user, no
auto-detection of the water molecules is performed.


GAFF
====

Automatic atomtyping via an experimental integration of the
Antechamber toolkit is available for the Generalized AMBER Force Field
(GAFF) for small organic molecules. This option was introduced in the
2020 release of AMS, and is still considered experimental and disabled
by default.

See also: Antechamber integration for GAFF forcefields

Using the GAFF forcefield with automatic atomtyping can be done with
the "AntechamberIntegration" keyword.

   GAFF
      AtomTyping
         AntechamberIntegration Yes/No
         AntechamberTask [GeometryOptimization | SinglePoint]
         KeepAntechamberFolder Yes/No
         MolecularCharge
            Charge float
            Region string
         End
      End
   End

"GAFF"
   Type:
      Block

   Description:
      Specific keywords for the GAFF force field type

   "AtomTyping"
      Type:
         Block

      Description:
         Specific keywords for automatic atom typing for the GAFF
         force field type

      "AntechamberIntegration"
         Type:
            Bool

         Default value:
            No

         GUI name:
            Automatic atom typing

         Description:
            EXPERIMENTAL: Use the Antechamber program to automatically
            determine atom types for the GAFF force field. This may
            run a geometry optimization with MOPAC under the hood in
            order to determine the charges (see keyword
            AntechamberTask), which might not work for very large
            systems.

      "AntechamberTask"
         Type:
            Multiple Choice

         Default value:
            GeometryOptimization

         Options:
            [GeometryOptimization, SinglePoint]

         Description:
            If antechamber is invoked to guess atomtypes and charges
            (GAFF force field), select the task for charge guessing
            with MOPAC

      "KeepAntechamberFolder"
         Type:
            Bool

         Default value:
            No

         Description:
            If atom-typing is performed with antechamber, keep the
            folder after the call to antechamber

      "MolecularCharge"
         Type:
            Block

         Recurring:
            True

         Description:
            Defines a (set of) submolecule(s) with their charge, to be
            Used in GAFF atomtyping.

         "Charge"
            Type:
               Float

            Description:
               Molecular charge of submolecule(s) defined in Region.

         "Region"
            Type:
               String

            Description:
               Region name that defines a (set of) submolecule(s).


Molecular charges
-----------------

When a molecular system consists of multiple molecules, the charges of
those molecules default to zero. The user can supply molecular charges
by defining regions (see The System block). The regions can then be
linked to molecular charges with the keywords
"GAFF%AtomTyping%MolecularCharge%Region" and
"GAFF%AtomTyping%MolecularCharge%Charge". Multiple instances of this
keyword are allowed. If all the atoms in a single molecule/ion are
included in the region, then the charge is applied to it. If the
region covers multiple molecules/ions, then all the ions in that
region will be assigned the supplied molecular charge.


Reusing type info
-----------------

For complex molecules atomtyping can take some time. Therefore, it may
be desirable to reuse the atom types and charges from a previous GAFF
calculation on the same system. This can be done in two ways.

1. By referring to an RKF file

2. By explicitly adding the atom typing information to the input file

For the first option, use the keyword "ReuseTypeInfo" referencing the
engine RKF file from the previous GAFF calculation (usually named
forcefield.rkf).

   ReuseTypeInfo string

"ReuseTypeInfo"
   Type:
      String

   Default value:
   Description:
      Path to RKF file with atom typing information (atom types,
      charges, and - in case of GAFF or APPLE&P - possibly a
      forcefield (patch) file for the system).

Adding the atomtyping information for reuse explicitly to the
inputfile requires more knowledge of the produced data. Using
automatic atomtyping for GAFF produces atom types and charges, and
often a parameter patch as well. This is a piece of text that contains
additional parameters to the standard GAFF set. All the atomtyping
information can be found in the output file. One can then add the
types, charges, and parameter patch(es) directly into the GAFF input
file. For the addition of atom types and charges to input, see Adding
atom types and charges. For the parameter patch, use the keyword
"GAFF%ForceFieldParameters", and insert the patch text directly into
the input. The force field patch information can also be passed as a
reference to a text file or to the forcefield.rkf file from a previous
GAFF calculation, using the keyword *GAFF%ForceFieldPatchFile*.

   GAFF
      ForceFieldParameters
   End

"GAFF"
   Type:
      Block

   Description:
      Specific keywords for the GAFF force field type

   "ForceFieldParameters"
      Type:
         Block

      Recurring:
         True

      GUI name:
      Description:
         Parameter file text in AMBER format with (additional
         parameters, missing from main file). Alternative option to
         ForceFieldPatchFile. The parameter patches provided by
         antechamber can be used here. Cannot be used when atomtypes
         are guessed.

   GAFF
      ForceFieldPatchFile string
   End

"GAFF"
   Type:
      Block

   Description:
      Specific keywords for the GAFF force field type

   "ForceFieldPatchFile"
      Type:
         String

      Recurring:
         True

      GUI name:
         Force field patch file

      Description:
         Path to the force field patch parameter file (additional
         parameters, missing from main file). Cannot be used when
         atomtypes are guessed.


APPLE&P
=======

Apple&P atomtyping has to be done prior to an AMS calculation using a
separate tool. This tool can be accessed via our graphical user
interface (APPLE&P tutorial) or using our general atom typing tool
(../AMS/Utilities/AtomTyping.html).

The procedure generates atom types and charges, as well as parameters.
After atom typing is complete, an input can be written with the types
and charges in the *System* block (Adding atom types and charges) and
the produced parameter file added with the *ForceFielFile* keyword.
When the atom typing tool was used, the produced data can also be used
in an APPLE&P calculation with the keyword "ReuseTypeInfo", and a
reference to the file *atomtyping.rkf*.

   ReuseTypeInfo string

"ReuseTypeInfo"
   Type:
      String

   Default value:
   Description:
      Path to RKF file with atom typing information (atom types,
      charges, and - in case of GAFF or APPLE&P - possibly a
      forcefield (patch) file for the system).


Other forcefields
=================

Some atomtyping functionality for biological systems can be accessed
via the GUI, using pdb files as input. A pdb file can be loaded into
amsinput and then under the regions the residues can be found. Still,
charges need to be set by hand.

Custom force field parameters can be provided as forcefield files. The
two supported formats are ".ff" (originating from the ADF and QUILD
programs) and the much more widely used amber ".dat" files.
