Solvents Header for YAML Files

The solvents header lets users specify what solvents are available to the systems they will create. “Solvents” in this case is a very general term and includes the ability to specify vacuum (i.e. no solvent). Just like in molecules, the solvents can have arbitrary, user defined names. In the examples, these user defined names are marked as {UserDefinedSolvent}.

You can define as many {UserDefinedSolvent} as you like. These solvents will be used in other YAML headers.

Most of the solvent options are tied directly to OpenMM options of the same name in the primary function simtk.openmm.app.amberprmtopfile.AmberPrmtopFile.createSystem(), however, there are other options tied to LEaP preparation instructions. Similarly, the solvents section is where you specify Periodic Boundary Conditions (PBC) and long range electrostatic treatments. Each of the arguments in this category is optional and the default option will be assumed if not specified.

OpenMM System Creation Options

nonbonded_method

solvents:
  {UserDefinedSolvent}:
    nonbonded_method: NoCutoff

Specify the nonbonded scheme that the solvent is put in. This argument defines the type of solvent (none, implicit, explicit). Although technically optional, this is the most important setting in this header. Because each option has very different behavior, we list each of them here and subsequent options will note which mode they apply to.

  • NoCutoff: Default. Specifies a non-periodic system with no cutoff. This is the de facto choice for vacuum and implicit solvent.
  • CutoffNonPeriodic: Specify a non-periodic system which uses a cutoff scheme to reduce the computational overhead of computing long range interactions. This scheme is helpful for vacuum and implicit solvent systems with large number of molecules where computing the pairwise interaction at long range between all atoms is inefficient.
  • CutoffPeriodic: Specifies a periodic system with a cutoff scheme and Reaction Field electrostatics for long range interactions. There is some cutoff based error associated with using this option and is not currently recommended.
  • Ewald: Specifies a periodic system with a cutoff scheme and Ewald decomposed electrostatics. This is typically not used over PME
  • PME: Specifies a periodic system with a cutoff scheme and Particle Mesh Ewald (PME) decomposed electrostatics. Currently support by YANK, however, there is a small error introduced by YANK due to the inability efficiently treat long range alchemical PME electrostatics during simulation. We partially correct for this error by computing it at run-time at the cost of a bit of computational overhead. This is YANK’s currently preferred mode for explicit solvent.

nonbonded_cutoff

solvents:
  {UserDefinedSolvent}:
    nonbonded_cutoff: 1 * nanometer

Specify the cutoff radius for the nonbonded_method‘s which rely on it. What happens beyond this cutoff depends both on the nonbonded_method and the switch_distance.

Nonbonded Methods: CutoffPeriodic, Ewald, PME

Valid Options (1 * nanometer): <Quantity Length> [1]

switch_distance

solvents:
   {UserDefinedSolvent}:
      switch_distance: 0.9 * nanometer

The distance at which the potential energy switching function is turned on for Lennard-Jones interactions. If the switch_distance is 0 (or not specified), no switching function will be used. Values greater than nonbonded_cutoff or less than 0 raise errors.

Nonbonded Methods: CutoffPeriodic, Ewald, PME

Valid Options (0 * nanometer) <Quantity Length> [1]

solvent_model

solvents:
  {UserDefinedSolvent}:
    solvent_model: tip4pew

Specify the water model used to solvate the box.

Nonbonded Methods: CuttoffNonPeriodic, CuttoffPeriodic, Ewald, PME

Valid Options: [tip4pew] / tip3p / tip3pfb / tip5p / spce

rigid_water

solvents:
  {UserDefinedSolvent}:
    rigid_water: True

If True, the water molecules will be fully rigid, regardless of the settings in constraints.

Nonbonded Methods: All

Valid Options: [True] / False

implicit_solvent

solvents:
  {UserDefinedSolvent}:
    implicit_solvent: OBC2

Specify an implicit solvent model. Please check the OpenMM documentation on each option to see the differences in the models.

When not specified, no implicit solvent is set.

Nonbonded Methods: NoCutoff, CutoffNonPeriodic

Valid Options: HCT / OBC1 / OBC2 / GBn / GBn2

implicit_solvent_salt_concentration

solvents:
  {UserDefinedSolvent}:
    implicit_solvent_salt_concentration: 1.0 * moles / liter

Specify the salt concentration of the implicit model. Requires an implicit_solvent.

You may also specify a Debye length temperature parameter which accepts <Quantity Temperature> [1] as an argument, default 300 * kelvin. Note: This is NOT the temperature for the system as a whole.

Nonbonded Methods: NoCutoff, CutoffNonPeriodic

Valid Options (0.0 * moles / liter): <Quantity Moles / Volume> OR <Quantity Temperature> [1]

solute_dielectric

solvents:
  {UserDefinedSolvent}:
    solute_dielectric: 1.5

Specify the dielectric of the solute molecules.

Nonbonded Methods: NoCutoff, CutoffNonPeriodic

Valid Options (1.0): <Float>

solvent_dielectric

solvents:
  {UserDefinedSolvent}:
    solvent_dielectric: 78.5

Specify the dielectric of the implcit solvent models

Nonbonded Methods: NoCutoff, CutoffNonPeriodic

Valid Options (78.5): <Float>

ewald_error_tolerance

solvents:
  {UserDefinedSolvent}:
    ewald_error_tolerance: 0.0005

The relative error tolerance to use for Ewald summations. There are very few times this will need to be explicitly set.

Nonbonded Methods: Ewald, PME

Valid Options (0.0005): <Float>


LEaP Solvation Options

clearance

solvents:
  {UserDefinedSolvent}:
    clearance: 10 * angstrom

The edge of the solvation box will be at clearance distance away from any atom of the receptor and ligand. This method is a way to solvate without explicitly defining solvent atoms. We highly recommend having a number of equilibration iterations when this option is invoked.

This option is mandatory only for systems that need to go through the automatic preparation pipeline, and it is ignored for systems defined by Amber, GROMACS, or OpenMM files.

Nonbonded Methods: CuttoffNonPeriodic, CuttoffPeriodic, Ewald, PME

Valid Options: <Quantity Length> [1]

positive_ion

solvents:
  {UserDefinedSolvent}:
    positive_ion: Na+

Specifies the positive counter ions that will be added as needed.

No positive counter ions will be added if this option is not specified. Note that the name must match a known atom type in LEaP based on the parameter files you specified to load.

Nonbonded Methods: CuttoffPeriodic, Ewald, PME

Valid Options: <Ion Symbol and charge>

negative_ion

solvents:
  {UserDefinedSolvent}:
    negative_ion: Cl-

Specifies the negative counter ions that will be added as needed.

No negative counter ions will be added if this option is not specified. Note that the name must match a known atom type in LEaP based on the parameter files you specified to load.

Nonbonded Methods: CuttoffPeriodic, Ewald, PME

Valid Options: <Ion Symbol and charge>

[1](1, 2, 3, 4, 5) Quantity strings are of the format: <float> * <unit> where <unit> is any valid unit specified in the “Valid Options” for an option. e.g. “<Quantity Length>” indicates any measure of length may be used for <unit> such as nanometer or angstrom. Compound units are also parsed such as kilogram / meter**3 for density. Only full unit names as they appear in the simtk.unit package (part of OpenMM) are allowed; so “nm” and “A” will be rejected.