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 to make the results more realistic, either via the input or using one or the following options.

See also example LoadCharges, and 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
   LongRangeCorrection Yes/No
   MuMu14Scaling float
   QMu14Scaling float
   QQ14Scaling float
   RD14Scaling float
End
APPLE&P
Type:

Block

Description:

Options for the APPLE&P force field.

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.