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. Default False.

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.

field remove_com: bool = False#

Whether or not to remove the center of mass motion. Default False.

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’.

field equil_npt_structure: str | None = 'equil_npt.pdb'#

Path to the pdb file of the system after NPT equilibration. Only the specified atom subset is saved. Default ‘equil_npt.pdb’.

field log_output: str | None = 'simulation.log'#

Filename for writing the log of the MD simulation, including timesteps, energies, density, etc.

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. Default None.

field gpu_device_index: list[int] | None = None#

List of integer indices for the GPU device to select when compute_platform is either set to CUDA or OpenCL.

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 to ambertools`, or using the OpenEye Toolkit (via Quacpac) if ``off_toolkit_backend is set to openeye. 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 to openeye. We recommend setting number_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 and rdkit 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 the partial_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 or espaloma 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 through am1bccelf10. See partial_charge_method’s Description of options documentation.

field nagl_model: str | None = None#

The NAGL model to use for partial charge assignment.

If None (default) and partial_charge_method is set to nagl, the latest available production am1bcc charge model will be used.

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:
  1. defining a solvent padding (solvent_padding) in combination with a box shape

  2. defining the number of solvent molecules (number_of_solvent_molecules) alongside the box shape (box_shape)

  3. defining the box directly either through the box vectors (box_vectors) or rectangular box lengths (box_size)

When using solvent_padding, box_vectors, or box_size, the exact number of waters added is determined automatically by OpenMM through openmm.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 with box_shape,

  • number_of_solvent_molecules in combination with box_shape,

  • box_vectors,

  • box_size

When using number_of_solvent_molecules, the size of the cell is defined by openmm.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, or box_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 or box_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, or box_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, or box_size.

See also

openff.interchange.components.interchange, openff.interchange.components._packmol

field box_size: ArrayQuantity | None = None#

X, Y, and Z lengths of the unit cell for a rectangular box.

Notes

  • Cannot be defined alongside solvent_padding, number_of_solvent_molecules, or box_vectors.

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 rigid_water: bool = True#

Whether to use a rigid water model. Default True

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)

field ph: PositiveFloat | None = None#

Simulation pH

Constraints:
  • exclusiveMinimum = 0

field redox_potential: float | None = None#

Simulation redox potential

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 by MultiStateSimulationSettings.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 by MultiStateSimulationSettings.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 below MultiStateSimulationSettings.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.