OpenMM Protocol Settings#
This page documents the Settings classes used by OpenMM-based Protocols.
Details on which of these Settings classes are used by a given Protocol can be found on the individual Protocol API reference documentation pages:
Shared OpenMM Protocol Settings#
The following are Settings clases which are shared between multiple OpenMM-based Protocols. Please note that not all Protocols use these Settings classes.
- pydantic model openfe.protocols.openmm_utils.omm_settings.IntegratorSettings#
Settings for the LangevinDynamicsMove integrator
Note
For some Protocols, an MC “move” (e.g. replica exchange swap) is applied at a given frequency. In most Protocols the move frequency is defined in MultiStateSimulationSettings.time_per_iteration.
Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field timestep: FloatQuantity = <Quantity(4, 'femtosecond')>#
Size of the simulation timestep. Default 4 * unit.femtosecond.
- field langevin_collision_rate: FloatQuantity = <Quantity(1.0, '1 / picosecond')>#
Collision frequency. Default 1.0 / unit.pisecond.
- field reassign_velocities = False#
If
True
, velocities are reassigned from the Maxwell-Boltzmann distribution at the beginning of each MC move. DefaultFalse
.
- field n_restart_attempts = 20#
Number of attempts to restart from Context if there are NaNs in the energies after integration. Default 20.
- field constraint_tolerance = 1e-06#
Tolerance for the constraint solver. Default 1e-6.
- field barostat_frequency: FloatQuantity = <Quantity(25, 'timestep')>#
Frequency at which volume scaling changes should be attempted. Note: The barostat frequency is ignored for gas-phase simulations. Default 25 * unit.timestep.
- pydantic model openfe.protocols.openmm_utils.omm_settings.MDOutputSettings#
Settings for simulation output settings for plain MD simulations.
Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field checkpoint_interval: FloatQuantity = <Quantity(250, 'picosecond')>#
Frequency to write the checkpoint file. Default 1 * unit.picosecond.
- field forcefield_cache: str | None = 'db.json'#
Filename for caching small molecule residue templates so they can be later reused.
- field output_indices = 'not water'#
Selection string for which part of the system to write coordinates for. Default ‘not water’.
- field checkpoint_storage_filename = 'checkpoint.chk'#
Separate filename for the checkpoint file. Note, this should not be a full path, just a filename. Default ‘checkpoint.chk’.
- field production_trajectory_filename: str | None = 'simulation.xtc'#
Path to the storage file for analysis. Default ‘simulation.xtc’.
- field trajectory_write_interval: FloatQuantity = <Quantity(20, 'picosecond')>#
Frequency to write the xtc file. Default 5000 * unit.timestep.
- field preminimized_structure: str | None = 'system.pdb'#
Path to the pdb file of the full pre-minimized system. Default ‘system.pdb’.
- field minimized_structure: str | None = 'minimized.pdb'#
Path to the pdb file of the system after minimization. Only the specified atom subset is saved. Default ‘minimized.pdb’.
- field equil_nvt_structure: str | None = 'equil_nvt.pdb'#
Path to the pdb file of the system after NVT equilibration. Only the specified atom subset is saved. Default ‘equil_nvt.pdb’.
- pydantic model openfe.protocols.openmm_utils.omm_settings.MDSimulationSettings#
Settings for simulation control for plain MD simulations
Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field equilibration_length: FloatQuantity [Required]#
Length of the equilibration phase in units of time. Must be divisible by the
IntegratorSettings.timestep
.
- field production_length: FloatQuantity [Required]#
Length of the production phase in units of time. Must be divisible by the
IntegratorSettings.timestep
.
- field minimization_steps = 5000#
Number of minimization steps to perform. Default 5000.
- field equilibration_length_nvt: FloatQuantity | None = None#
Length of the equilibration phase in the NVT ensemble in units of time. The total number of steps from this equilibration length (i.e.
equilibration_length_nvt
/IntegratorSettings.timestep
). If None, no NVT equilibration will be performed.
- pydantic model openfe.protocols.openmm_utils.omm_settings.OpenMMEngineSettings#
OpenMM MD engine settings
Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field compute_platform: str | None = None#
OpenMM compute platform to perform MD integration with. If
None
, will choose fastest available platform. DefaultNone
.
- field gpu_device_index: list[int] | None = None#
List of integer indices for the GPU device to select when
compute_platform
is either set toCUDA
orOpenCL
.If
None
, the default OpenMM GPU selection behaviour is used.See the OpenMM platform properties documentation for more details.
Default
None
.
- pydantic model openfe.protocols.openmm_utils.omm_settings.OpenFFPartialChargeSettings#
Settings for controlling partial charge assignment using the OpenFF tooling
Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field partial_charge_method: Literal['am1bcc', 'am1bccelf10', 'nagl', 'espaloma'] = 'am1bcc'#
Selection of method for partial charge generation.
Description of options#
am1bcc
:Generate partial charges using the AM1-BCC approach, as detailed by Araz Jalkalian et al. J. Comp. Chem. 2000. AM1-BCC charges are either assigned using AmberTools (via SQM) if
off_toolkit_backend
is set toambertools`, or using the OpenEye Toolkit (via Quacpac) if ``off_toolkit_backend
is set toopeneye
. A maximum of one conformer is allowed.am1bccelf10
:Assign AM1-BCC partialk charges using the ELF10 method This is only currently possible via the OpenEye toolkit if setting
off_toolkit_backend
toopeneye
. We recommend settingnumber_of_conformers
to at least 500.nagl
:Assign partial charges using the OpenFF NAGL ML method All
off_toolkit_backend
options are supported. A maximum of one conformer is allowed.espaloma
:Assign partial charges using the Espaloma Charge method Only
ambertools
andrdkit
off_toolkit_backend` options are supported. A maximum of one conformer is allowed.
- field off_toolkit_backend: Literal['ambertools', 'openeye', 'rdkit'] = 'ambertools'#
The OpenFF toolkit registry backend to use for partial charge generation.
OpenFF backend selection options#
ambertools
:This limits partial charge generation to using a mixture of AmberTools and RDKit.
openeye
:This limits partial charge generation to using the OpenEye toolkit. This cannot be used with
espaloma
as thepartial_charge_method
rdkit
:This limits partial charge generation to using the RDKit toolkit. Note that this alone cannot be used for conventional am1bcc partial charge generation, but is usually used in combination with the
nagl
orespaloma
partial_charge_method
selections.
- field number_of_conformers: int | None = None#
Number of conformers to generate as part of the partial charge assignment.
If
None
(default), the existing conformer of the input SmallMoleculeComponent will be used.Values greater than 1 or
None
are only allowed when calculating partial charges througham1bccelf10
. Seepartial_charge_method
’sDescription of options
documentation.
- pydantic model openfe.protocols.openmm_utils.omm_settings.OpenMMSolvationSettings#
Settings for controlling how a system is solvated using OpenMM tooling.
Defining the number of waters#
- The number of waters is controlled by either:
defining a solvent padding (
solvent_padding
) in combination with a box shapedefining the number of solvent molecules (
number_of_solvent_molecules
) alongside the box shape (box_shape
)defining the box directly either through the box vectors (
box_vectors
) or rectangular box lengths (box_size
)
When using
solvent_padding
,box_vectors
, orbox_size
, the exact number of waters added is determined automatically by OpenMM throughopenmm.app.Modeller.addSolvent()
internal heuristics. Briefly, the necessary volume required by a single water is estimated and then the defined target cell is packed with waters avoiding clashes with existing solutes and box edges.Defining the periodic cell size#
- The periodic cell size is defined by one, and only one, of the following:
solvent_padding
in combination withbox_shape
,number_of_solvent_molecules
in combination withbox_shape
,box_vectors
,box_size
When using
number_of_solvent_molecules
, the size of the cell is defined byopenmm.app.Modeller.addSolvent()
internal heuristics, automatically selecting a padding value that is large enough to contain the number of waters based on a geometric estimate of the volume required by each water molecule.Defining the periodic cell shape#
- The periodic cell shape is defined by one, and only one, of the following:
box_shape
,box_vectors
,box_size
Default settings will create a cubic box, although more space efficient shapes (e.g.
dodecahedrons
) are recommended to improve simulation performance.Notes
The number of water molecules added will be affected by the number of ions defined in SolventComponent. For example, the value of
number_of_solvent_molecules
is the sum of the number of counterions added and the number of water molecules added.Solvent addition does not account for any pre-existing waters explicitly defined in the
openfe.ChemicalSystem
. Any waters will be added in addition to those pre-existing waters.No solvation will happen if a SolventComponent is not passed.
See also
openmm.app.Modeller
,Base
Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field solvent_model: Literal['tip3p', 'spce', 'tip4pew', 'tip5p'] = 'tip3p'#
Force field water model to use when solvating and defining the model properties (e.g. adding virtual site particles).
Allowed values are; tip3p, spce, tip4pew, and tip5p.
- field solvent_padding: FloatQuantity | None = <Quantity(1.2, 'nanometer')>#
Minimum distance from any solute bounding sphere to the edge of the box.
Note
Cannot be defined alongside
number_of_solvent_molecules
,box_size
, orbox_vectors
.
- field box_shape: Literal['cube', 'dodecahedron', 'octahedron'] | None = 'cube'#
The shape of the periodic box to create.
Notes
Must be one of cube, dodecahedron, or octahedron.
Cannot be defined alongside
box_vectors
orbox_size
.
- field number_of_solvent_molecules: int | None = None#
The number of solvent molecules (water + ions) to add.
Note
Cannot be defined alongside
solvent_padding
,box_size
, orbox_vectors
.
- field box_vectors: ArrayQuantity | None = None#
OpenMM reduced form box vectors <http://docs.openmm.org/latest/userguide/theory/05_other_features.html#periodic-boundary-conditions>.
Notes
Cannot be defined alongside
solvent_padding
,number_of_solvent_molecules
, orbox_size
.
See also
openff.interchange.components.interchange
,openff.interchange.components._packmol
- pydantic model openfe.protocols.openmm_utils.omm_settings.OpenMMSystemGeneratorFFSettings#
Parameters to set up the force field with OpenMM ForceFields
Note
Right now we just basically just grab what we need for the
openmmforcefields.system_generators.SystemGenerator
signature. See the OpenMMForceField SystemGenerator documentation for more details.Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field constraints: str | None = 'hbonds'#
Constraints to be applied to system. One of ‘hbonds’, ‘allbonds’, ‘hangles’ or None, default ‘hbonds’
- field hydrogen_mass: float = 3.0#
Mass to be repartitioned to hydrogens from neighbouring heavy atoms (in amu), default 3.0
- field forcefields: list[str] = ['amber/ff14SB.xml', 'amber/tip3p_standard.xml', 'amber/tip3p_HFE_multivalent.xml', 'amber/phosaa10.xml']#
List of force field paths for all components except
SmallMoleculeComponent
- field small_molecule_forcefield: str = 'openff-2.1.1'#
Name of the force field to be used for
SmallMoleculeComponent
- field nonbonded_method = 'PME'#
Method for treating nonbonded interactions, currently only PME and NoCutoff are allowed. Default PME.
- field nonbonded_cutoff: FloatQuantity = <Quantity(1.0, 'nanometer')>#
Cutoff value for short range nonbonded interactions. Default 1.0 * unit.nanometer.
- pydantic model openfe.protocols.openmm_utils.omm_settings.ThermoSettings#
Settings for thermodynamic parameters.
Note
No checking is done to ensure a valid thermodynamic ensemble is possible.
Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field temperature: FloatQuantity = None#
Simulation temperature, default units kelvin
- field pressure: FloatQuantity = None#
Simulation pressure, default units standard atmosphere (atm)
Shared MultiState OpenMM Protocol Settings#
Protocol Settings shared between MultiState simulation protocols.
These currently include the following Protocols:
- pydantic model openfe.protocols.openmm_utils.omm_settings.MultiStateOutputSettings#
Settings for MultiState simulation output settings, writing to disk, etc…
Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field output_filename = 'simulation.nc'#
Path to the trajectory storage file. Default ‘simulation.nc’.
- field output_structure = 'hybrid_system.pdb'#
Path of the output hybrid topology structure file. This is used to visualise and further manipulate the system. Default ‘hybrid_system.pdb’.
- field positions_write_frequency: FloatQuantity | None = <Quantity(100, 'picosecond')>#
Frequency at which positions are written to the simulation trajectory storage file (defined by
output_filename
).If
None
, no positions will be written to the trajectory.Unless set to
None
, must be divisible byMultiStateSimulationSettings.time_per_iteration
.
- field velocities_write_frequency: FloatQuantity | None = None#
Frequency at which velocities are written to the simulation trajectory storage file (defined by
output_filename
).If
None
(default), no velocities will be written to the trajectory.Unless set to
None
, must be divisible byMultiStateSimulationSettings.time_per_iteration
.
- field checkpoint_interval: FloatQuantity = <Quantity(250, 'picosecond')>#
Frequency to write the checkpoint file. Default 1 * unit.picosecond.
- field forcefield_cache: str | None = 'db.json'#
Filename for caching small molecule residue templates so they can be later reused.
- field output_indices = 'not water'#
Selection string for which part of the system to write coordinates for. Default ‘not water’.
- field checkpoint_storage_filename = 'checkpoint.chk'#
Separate filename for the checkpoint file. Note, this should not be a full path, just a filename. Default ‘checkpoint.chk’.
- pydantic model openfe.protocols.openmm_utils.omm_settings.MultiStateSimulationSettings#
Settings for simulation control for multistate simulations, including simulation length and details of the alchemical sampler.
Create a new model by parsing and validating input data from keyword arguments.
Raises ValidationError if the input data cannot be parsed to form a valid model.
- field equilibration_length: FloatQuantity [Required]#
Length of the equilibration phase in units of time. Must be divisible by the
IntegratorSettings.timestep
.
- field production_length: FloatQuantity [Required]#
Length of the production phase in units of time. Must be divisible by the
IntegratorSettings.timestep
.
- field minimization_steps = 5000#
Number of minimization steps to perform. Default 5000.
- field sampler_method = 'repex'#
Alchemical sampling method, must be one of; repex (Hamiltonian Replica Exchange), sams (Self-Adjusted Mixture Sampling), or independent (independently sampled lambda windows). Default repex.
- field time_per_iteration: FloatQuantity = <Quantity(1, 'picosecond')>#
Simulation time between each MCMC move attempt. Default 1 * unit.picosecond.
- field real_time_analysis_interval: FloatQuantity | None = <Quantity(250, 'picosecond')>#
Time interval at which to perform an analysis of the free energies.
At each interval, real time analysis data (e.g. current free energy estimate and timing data) will be written to a yaml file named
<OutputSettings.output_filename>_real_time_analysis.yaml
. The current error in the estimate will also be assessed and if it drops belowMultiStateSimulationSettings.early_termination_target_error
the simulation will be terminated.If
None
, no real time analysis will be performed and the yaml file will not be written.Must be a multiple of
OutputSettings.checkpoint_interval
Default 250.
- field early_termination_target_error: FloatQuantity | None = <Quantity(0.0, 'kilocalorie_per_mole')>#
Target error for the real time analysis measured in kcal/mol. Once the MBAR error of the free energy is at or below this value, the simulation will be considered complete. A suggested value of 0.12 * unit.kilocalorie_per_mole has shown to be effective in both hydration and binding free energy benchmarks. Default
None
, i.e. no early termination will occur.
- field real_time_analysis_minimum_time: FloatQuantity = <Quantity(500, 'picosecond')>#
Simulation time which must pass before real time analysis is carried out.
Default 500 * unit.picosecond.
- field sams_flatness_criteria = 'logZ-flatness'#
SAMS only. Method for assessing when to switch to asymptomatically optimal scheme. One of [‘logZ-flatness’, ‘minimum-visits’, ‘histogram-flatness’]. Default ‘logZ-flatness’.
- field sams_gamma0 = 1.0#
SAMS only. Initial weight adaptation rate. Default 1.0.
- field n_replicas = 11#
Number of replicas to use. Default 11.