ForceField Engine Options
*************************

Details of the ForceField engine can be set via its input block. Some
option are specific to UFF and others to other force fields.


Common options
==============

These options apply to any force field.


Type
----

There are a few predefined force field types, that, if used, require
no other input.

   Type [UFF | Amber95 | GAFF | Tripos5.2 | APPLE&P | UserDefined]

"Type"
   Type:
      Multiple Choice

   Default value:
      UFF

   Options:
      [UFF, Amber95, GAFF, Tripos5.2, APPLE&P, UserDefined]

   Description:
      Type of force field to be used


Non-bonded screening
--------------------

The long range interaction (dispersion and Coulomb) are the most
expensive to evaluate. This gives you the option to screen the
interaction more aggressively.

   NonBondedCutoff float

"NonBondedCutoff"
   Type:
      Float

   Default value:
      15.0

   Unit:
      Angstrom

   Description:
      Distance beyond which the non-bonded pair interactions (Coulomb
      and Van der Waals) will be ignored.                   The
      interactions are smoothly damped starting from
      0.9*NonBondedCutoff.                    Has no effect on the
      Coulomb term for 3D-periodic systems, as Ewald summation is
      used.

It is usually a good idea to add some "skin" to the cutoff above when
it's used for computing a neighbor list for changing geometries (e.g.
during molecular dynamics or geometry optimization). This way, the
neighbor list will not need to be re-computed when atoms move a
little. This may save some time because generating a neighbor list can
be quite costly. The following option sets the thickness of the
"skin":

   NeighborListSkin float

"NeighborListSkin"
   Type:
      Float

   Default value:
      2.5

   Unit:
      Angstrom

   Description:
      Thickness of the buffer region added to the NonBondedCutoff when
      building a neighbor list.

Note:

  This option also affects the cutoff used when generating a neighbor
  list in the real-space part of the Ewald summation but then it is
  added to the cutoff radius is used there.


Feedback
--------

If you want to know more about the details of the force field you
should crank up the verbosity.

   Verbosity [Silent | Normal | Verbose | VeryVerbose]

"Verbosity"
   Type:
      Multiple Choice

   Default value:
      Silent

   Options:
      [Silent, Normal, Verbose, VeryVerbose]

   Description:
      Controls the verbosity of the engine.


Bonds usage
-----------

Bonds can be specified in the input, still you may not want to use
those. Here are some options to control this.

   BondsUsage [Input | None | Guess | Auto]

"BondsUsage"
   Type:
      Multiple Choice

   Default value:
      Auto

   Options:
      [Input, None, Guess, Auto]

   Description:
      Controls what bonds are used by the engine. The choice auto
      means: guess in case there are no bonds. Guessing only happens
      at the first MD step, or first geometry optimization step.


Ewald summation
---------------

For periodic systems the Ewald summation is performed for the Coulomb
interaction. It has a couple of options:

   EwaldSummation
      Alpha float
      Enabled Yes/No
      GridSpacing float
      RealSpaceCutoff float
      Tolerance float
   End

"EwaldSummation"
   Type:
      Block

   Description:
      Configures the details of the particle mesh Ewald (PME)
      summation of the Coulomb interaction.

   "Alpha"
      Type:
         Float

      Default value:
         -1.0

      Unit:
         1/Angstrom

      Description:
         This parameter shifts the workload from real space (smaller
         alpha) to reciprocal space (larger alpha). Using a larger
         [Alpha] without decreasing [GridSpacing] may increase the
         error in the reciprocal-space contribution. Set to zero to
         disable the reciprocal-space Ewald part. Negative value means
         the [Alpha] will be determined automatically from the
         [Tolerance] and [RealSpaceCutoff] values.

   "Enabled"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Set to false to use real-space pair summation instead of the
         Ewald, which is the default and the only option for
         molecules, 1D and 2D periodic systems.

   "GridSpacing"
      Type:
         Float

      Default value:
         0.5

      Unit:
         Angstrom

      Description:
         Grid spacing in the particle mesh Ewald method. Smaller grid
         spacing will make the reciprocal energy calculation more
         accurate but slower. Using a larger [Alpha] value may require
         a smaller GridSpacing to be accurate.

   "RealSpaceCutoff"
      Type:
         Float

      Default value:
         0.0

      Unit:
         Angstrom

      Description:
         Set the cutoff value for the real-space summation. Zero means
         the internal defaults will be used depending on the [Alpha]
         (if Alpha=0 then the cutoff will be set to 50 Bohr, otherwise
         to 20 Bohr).

   "Tolerance"
      Type:
         Float

      Default value:
         1e-10

      Description:
         Value of the error function that should be used to determine
         the cutoff radius for real-space Ewald summation if [Alpha]
         is set on input. Alternatively, if the [RealSpaceCutoff] is
         set but [Alpha] is not then the [Tolerance] value affects the
         [Alpha]. Larger values will make the real-space summation
         faster but less accurate.


Disabling energy terms
----------------------

By default all force field energy terms are calculated, however, you
can disable each one of them individually.

   EnergyTerms
      Angle Yes/No
      Coulomb Yes/No
      Dispersion Yes/No
      Inversion Yes/No
      Stretch Yes/No
      Torsion Yes/No
   End

"EnergyTerms"
   Type:
      Block

   Description:
      expert key, that allows you to disable specific energy terms.

   "Angle"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Whether to use angle (bend) energy.

   "Coulomb"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Whether to use coulomb energy.

   "Dispersion"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Whether to use dispersion energy.

   "Inversion"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Whether to use inversion energy.

   "Stretch"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Whether to use stretch energy.

   "Torsion"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Whether to use torsion energy.


Guessing or loading partial charges
-----------------------------------

The UFF forcefield has some very rudimentary partial charges guessing,
only setting charges for atoms in water molecules. By default the
partial charges in a force field calculation are zero. Essentially you
will always need to specify atomic charges in the input to make the
results more realistic.

See also example ChargedMolecules.


GuessCharges
~~~~~~~~~~~~

The simplest way is the use the GuessCharges key, that uses an engine
that can calculate atomic charges. By default DFTB is used. DFTB is of
course much more expensive than a forcefield, but if you run a MD
calculation you can maybe afford a single DFTB calculation on the
system.

   GuessCharges Yes/No

"GuessCharges"
   Type:
      Bool

   Default value:
      No

   Description:
      Use another engine to calculate/guess the charges to be used by
      the force field.

If you want to control the engine use the GuessChargesConfig key.

   GuessChargesConfig
      EngineType string
   End

"GuessChargesConfig"
   Type:
      Block

   Description:
      Guess charges to be used by the forcefield

   "EngineType"
      Type:
         String

      Default value:
         dftb

      Description:
         Engine that can calculate or guess charges


LoadCharges
~~~~~~~~~~~

You have more control over the charge guessing, by loading the charges
of another calculation. This way you can set any engine specific
detail, such as the basis set, or functional.

You can load charges form a previous calculation to be used as force
field charges.

   LoadCharges
      File string
      Section string
      Variable string
   End

"LoadCharges"
   Type:
      Block

   Description:
      Load charges from a file to be used as forcefield charges

   "File"
      Type:
         String

      Description:
         Name of the (kf) file

   "Section"
      Type:
         String

      Default value:
         AMSResults

      Description:
         Section name of the kf file

   "Variable"
      Type:
         String

      Default value:
         Charges

      Description:
         variable name of the kf file


Amber force field options
=========================

These options are relevant for the Amber and GAFF force fields:

   AllowMissingParameters Yes/No

"AllowMissingParameters"
   Type:
      Bool

   Default value:
      No

   Description:
      When parameters are not found for bonds, angles, dihedrals, or
      inversions, the first entry in the database will be used.

   CheckDuplicateRules Yes/No

"CheckDuplicateRules"
   Type:
      Bool

   Default value:
      Yes

   Description:
      The database could contain duplicate entries. For torsions this
      is a feature, and the potentials will be added. For all other
      terms this is no allowed, and if detected the program stops. One
      should fix the database or set the checking to false. As always
      the last entry will be used.

   ForceFieldFile string

"ForceFieldFile"
   Type:
      String

   Default value:
   GUI name:
      Force field library

   Description:
      Path to the force field parameter file


UFF options
===========

The following options are only relevant for the UFF force field:

   UFF
      AtomTypesFile string
      Database string
      ElementsFile string
      Library [UFF | UFF4MOF | UFF4MOF-II]
   End

"UFF"
   Type:
      Block

   Description:
      Option for the UFF force filed.

   "AtomTypesFile"
      Type:
         String

      Default value:
         mmatomtypes_db

      Description:
         Expert option: Select the file that defines how UFF
         determines the atom types

   "Database"
      Type:
         String

      Default value:
         general_db

      Description:
         Expert option: Select the file that defines the UFF
         parameters per atom type

   "ElementsFile"
      Type:
         String

      Default value:
         elements_db

      Description:
         Expert option: Select the file that defines the elements
         known to UFF

   "Library"
      Type:
         Multiple Choice

      Default value:
         UFF

      Options:
         [UFF, UFF4MOF, UFF4MOF-II]

      GUI name:
         Force field library

      Description:
         Selects the used parameter library.


APPLE&P force field options
===========================

The ForceFieldFile key is mandatory and it should contain path to the
APPLE&P forcefield file. This file is usually tailored for each system
specifically.

Additionally, the following options are relevant for the APPLE&P force
field.

   DipoleConvergenceThreshold float

"DipoleConvergenceThreshold"
   Type:
      Float

   Default value:
      1e-06

   Unit:
      eBohr

   Description:
      Convergence criterion for induced point dipoles, in atomic
      units. When the length of every atomic delta_mu vector between
      two iterations becomes below the tolerance, the procedure is
      considered converged.

The repulsion/dispersion and Coulomb interaction between atoms
connected by a bond or by a valence angle are excluded in APPLE&P.
Those between atoms connected by a dihedral (the so called 1-4
neighbors) may be scaled down and the scaling factors can be changed
using the following options:

   APPLE&P
      ForceFieldParameters
      LongRangeCorrection Yes/No
      MuMu14Scaling float
      QMu14Scaling float
      QQ14Scaling float
      RD14Scaling float
   End

"APPLE&P"
   Type:
      Block

   Description:
      Options for the APPLE&P force field.

   "ForceFieldParameters"
      Type:
         Block

      Recurring:
         True

      GUI name:
      Description:
         Forcefield parameter text block, provided as alternative to
         the general ForceFieldFile keyword. Will be ignored if
         ForceFieldFile keyword is also present.

   "LongRangeCorrection"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         Add long-range correction

      Description:
         Add a long-range dispersion correction to the energy and
         pressure for 3D-periodic systems.                       This
         correction should be enabled only for a homogeneous liquid.

   "MuMu14Scaling"
      Type:
         Float

      Default value:
         1.0

      GUI name:
         Mu-Mu 3rd-neighbor scaling

      Description:
         Scaling factor for dipole-dipole interactions between atoms
         connected to 3rd order (via a dihedral).

   "QMu14Scaling"
      Type:
         Float

      Default value:
         0.2

      GUI name:
         Q-Mu 3rd-neighbor scaling

      Description:
         Scaling factor for charge-dipole interactions between atoms
         connected to 3rd order (via a dihedral).

   "QQ14Scaling"
      Type:
         Float

      Default value:
         1.0

      GUI name:
         Q-Q 3rd-neighbor scaling

      Description:
         Scaling factor for charge-charge interactions between atoms
         connected to 3rd order (via a dihedral).

   "RD14Scaling"
      Type:
         Float

      Default value:
         1.0

      GUI name:
         RD 3rd-neighbor scaling

      Description:
         Scaling factor for repulsion/dispersion interactions between
         atoms connected to 3rd order (via a dihedral).


Offloading calculations to LAMMPS
=================================

The ForceField engine can optionally offload the evaluation of
energies and forces to LAMMPS to accelerate the calculation, possibly
leveraging a GPU. In this mode, the engine will still set up all force
field parameters as usual, but instead of evaluating the potential
directly in AMS, the engine converts the parameters into a a LAMMPS
data file and then invokes LAMMPS as an external pipe worker. As of
AMS2025, this option is fully supported only for "Type UFF".


Setting up LAMMPS
-----------------

The interface between AMS and LAMMPS relies on a modified LAMMPS
version that integrates the amspipe library for communication via the
AMSPipe protocol. We intend to make our modification available in
upstream LAMMPS, but for now the modified version can be obtained from
SCM's GitHub page:

https://github.com/SCM-NV/lammps/tree/amspipe

We currently do not distribute binaries for the modified LAMMPS
version, but it should be quite easy to build from source. Consult the
LAMMPS documentation for a detailed description on building LAMMPS.
For example, the following commands can be used to build LAMMPS
including the necessary packages:

   #!/bin/sh

   # 1. build the amspipe library
   git clone https://github.com/SCM-NV/amspipe.git
   mkdir amspipe/build
   cd amspipe/build
   cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON -DAMSPIPE_BUILD_DEMOS=OFF ..
   cmake --build .
   cmake --install . --prefix=../install
   cd ../..

   # 2. build modified LAMMPS
   git clone https://github.com/SCM-NV/lammps.git -b amspipe
   mkdir lammps/build
   cd lammps/build
   cmake ../cmake -DPKG_AMSPIPE=yes -Damspipe_ROOT=../../amspipe/install -DBUILD_MPI=no -DBUILD_OMP=yes -DPKG_OPENMP=yes -DPKG_GPU=yes -DPKG_MOLECULE=yes -DPKG_EXTRA-MOLECULE=yes -DPKG_KSPACE=yes
   cmake --build .

* "-DBUILD_MPI=no -DBUILD_OMP=yes -DPKG_OPENMP=yes" are strongly
  recommended to enable OpenMP parallelization of the CPU code of
  LAMMPS. AMS currently cannot use the MPI framework to parallelize
  LAMMPS and linking to a MPI-enabled library can cause issues.

* "-DPKG_GPU=yes" builds LAMMPS with GPU support. By default this
  builds the OpenCL version of the GPU package, which runs on both AMD
  and Nvidia cards. If you are targeting Nvidia cards only, we may
  consider switching to the Cuda version by adding "-DGPU_API=cuda"
  (and optionally specifying also "-DGPU_ARCH=sm_XX"). See the
  instructions for building the LAMMPS GPU package.

* "-DPKG_MOLECULE=yes -DPKG_EXTRA-MOLECULE=yes -DPKG_KSPACE=yes"
  enable the potential terms required by UFF.

By default the ForceField engine will look for the modified LAMMPS
binary simply as "lmp" on "$PATH". It is therefore easiest just to
extend "$PATH" with the "lammps/build" directory we made above:

   export PATH="/path/to/modified/lammps/build:$PATH"

You may want to put this line into your "$HOME/.profile" file to make
this permanent. You can use the "which" command to check that the
correct "lmp" binary is picked up:

   $ which lmp
   /path/to/modified/lammps/build/lmp

An alternative is to specify the path to the modified "lmp" binary in
the input of your job.

   Engine ForceField
      LAMMPSOffload
         WorkerCommand exec /path/to/modified/lammps/build/lmp
      End
   End

Note:

  Prior to AMS2025, the LAMMPS interface in AMS was based on the
  lammps Python module. This proved to be a performance bottleneck and
  is no longer supported in AMS2025 in favor of the direct
  communication with the modified "lmp" binary.


Input options
-------------

   LAMMPSOffload
      Enabled Yes/No
      Input
      UseGPU Yes/No
      UseGPUForKSpace Yes/No
      UseGPUForNeighbor Yes/No
      UseOpenMP Yes/No
      WorkerCommand string
   End

"LAMMPSOffload"
   Type:
      Block

   Description:
      Offload the calculation to LAMMPS via AMSPipe.

   "Enabled"
      Type:
         Bool

      Default value:
         No

      Description:
         Enable offloading the force field evaluation to LAMMPS
         instead of handling it internally in AMS. This is currently
         only supported for Type=UFF.

   "Input"
      Type:
         Block

      Description:
         Commands to be passed to LAMMPS to set up the calculation. If
         this is left empty, AMS will generate a set of commands to
         set LAMMPS up according to the settings of the ForceField
         engine. Any LAMMPS commands entered in this input block will
         be used to set LAMMPS up instead of those generated by AMS.
         To merge the AMS-generated lines with your customizations,
         include lines like 'AMS somelammpskeyword' anywhere in this
         block. Any such line will be replaced by the AMS-generated
         line for 'somelammpskeyword'. Any text after
         'somelammpskeyword' will be appended to the generated line
         verbatim, which can be used to modify the generated command
         by additional options. A special line 'AMS everything' will
         be replaced by the entire block of AMS-generated commands,
         except those overridden anywhere in this input block (defined
         manually or inserted using 'AMS somelammpskeyword'. Any
         customized Input block should probably include 'AMS
         read_data' near or at the end to load the AMS-generated data
         file defining the system.

   "UseGPU"
      Type:
         Bool

      Default value:
         No

      Description:
         Accelerate LAMMPS calculations using a GPU. Requires a LAMMPS
         library built with the GPU package.

   "UseGPUForKSpace"
      Type:
         Bool

      Default value:
         Yes

      Description:
         When UseGPU is enabled, also use the GPU to accelerate
         reciprocal space electrostatic interactions. Disabling this
         can improve performance on less powerful GPUs.

   "UseGPUForNeighbor"
      Type:
         Bool

      Default value:
         Yes

      Description:
         When UseGPU is enabled, also use the GPU to accelerate
         neighbor searches. Disabling this can improve performance on
         less powerful GPUs.

   "UseOpenMP"
      Type:
         Bool

      Default value:
         No

      Description:
         Parallelize LAMMPS calculations using OpenMP threading.
         Requires a LAMMPS library built with the OMP package.

   "WorkerCommand"
      Type:
         String

      Default value:
         exec lmp

      Description:
         The command to execute to run the external worker. The
         command is executed in a subdirectory of the results
         directory. The LAMMPS input commands will be passed to the
         worker on standard input.
