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 = '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 = 'system.pdb'#: Path to the pdb file of the full pre-minimized system. Default ‘system.pdb’.

field minimized_structure = '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 = '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.

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

Note

No solvation will happen if a SolventComponent is not passed.

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. Allowed values are; tip3p, spce, tip4pew, and tip5p.

field solvent_padding: FloatQuantity = <Quantity(1.2, 'nanometer')>#: Minimum distance from any solute atoms to the solvent box edge.

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