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.
All of the solvents will be built, even if they are not used in a later system, so ensure your solvents do not have errors or are commented out.
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.
Note: We do not recommend the nonbonded_methods not listed here, even though they may be available in OpenMM;
as such, we do not list them.
NoCutoff: Default. Specifies a non-periodic system with no cutoff. This is the de facto choice for vacuum and implicit solvent.Ewald: Specifies a periodic system with a cutoff scheme and Ewald decomposed electrostatics. This is typically not used over PMEPME: 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: 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: 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
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
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
Valid Options (1.0): <Float>
solvent_dielectric¶
solvents:
{UserDefinedSolvent}:
solvent_dielectric: 78.5
Specify the dielectric of the implcit solvent models
Nonbonded Methods: NoCutoff
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: Ewald, PME
Valid Options: <Ion Symbol and charge>
ionic_strength¶
solvents:
{UserDefinedSolvent}:
ionic_strength: 0.0*molar
The ionic strength of the ions.
Both positive_ion and negative_ion must be specified with this, and only monovalent ions are supported. Note
that this does not include the ions that are used to neutralize the periodic box.
Nonbonded Methods: Ewald, PME
Valid Options (0 * molar): <Quantity Concentration> [1]
| [1] | (1, 2, 3, 4, 5, 6) 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. |
leap¶
solvents:
{UserDefinedSolvent}:
leap:
parameters: [leaprc.water.tip4pew]
Load solvent-specific force field parameters. This is useful if you plan to run a combinatorial experiment over multiple solvent models that require different parameters.
This command has only one mandatory subargument parameters, which can accept both single files as a string or a
comma separated list of files enclosed by [ ]. File paths are relative to either the AmberTools default paths or to
the folder the YAML script is in.
Alternatively, the solvent parameters can be specified also as leap arguments in the system section. There is no difference between the two solutions other than convenience.
OPTIONAL