OpenMM Relative Free Energy Protocol#

This section provides details about the OpenMM Relative Free Energy Protocol implemented in OpenFE.

Protocol Settings#

Below are the settings which can be tweaked in the protocol. The default settings (accessed using RelativeHybridTopologyProtocol.default_settings will automatically populate a settings which we have found to be useful for running relative binding free energies using explicit solvent. There will however be some cases (such as when doing gas phase calculations) where you will need to tweak some of the following settings.

pydantic settings openfe.protocols.openmm_rfe.equil_rfe_settings.RelativeHybridTopologyProtocolSettings#

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.

Fields:
field alchemical_sampler_settings: AlchemicalSamplerSettings [Required]#
field alchemical_settings: AlchemicalSettings [Required]#
field engine_settings: OpenMMEngineSettings [Required]#
field integrator_settings: IntegratorSettings [Required]#
field simulation_settings: SimulationSettings [Required]#
field solvation_settings: SolvationSettings [Required]#
field system_settings: SystemSettings [Required]#
pydantic settings openfe.protocols.openmm_rfe.equil_rfe_settings.AlchemicalSamplerSettings#

Settings for the Equilibrium Alchemical sampler, currently supporting either MultistateSampler, SAMSSampler or ReplicaExchangeSampler.

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.

Fields:
field 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 gamma0 = 1.0#

SAMS only. Initial weight adaptation rate. Default 1.0.

field n_repeats: int = 3#

Number of independent repeats to run. Default 3

field n_replicas = 11#

Number of replicas to use. Default 11.

field online_analysis_interval: int | None = 250#

MCMC steps (i.e. IntegratorSettings.n_steps) 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 <SimulationSettings.output_name>_real_time_analysis.yaml. The current error in the estimate will also be assed and if it drops below AlchemicalSamplerSettings.online_analysis_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 SimulationSettings.checkpoint_interval

Default 250.

field online_analysis_minimum_iterations = 500#

Number of iterations which must pass before online analysis is carried out. Default 500.

field online_analysis_target_error = <Quantity(0.0, 'boltzmann_constant * kelvin')>#

Target error for the online analysis measured in kT. Once the free energy is at or below this value, the simulation will be considered complete. A suggested value of 0.2 * unit.boltzmann_constant * unit.kelvin has shown to be effective in both hydration and binding free energy benchmarks. Default 0.0 * unit.boltzmann_constant * unit.kelvin, i.e. no early termination will occur.

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.

pydantic settings openfe.protocols.openmm_rfe.equil_rfe_settings.AlchemicalSettings#

Settings for the alchemical protocol

This describes the lambda schedule and the creation of the hybrid system.

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.

Fields:
field flatten_torsions = False#

Whether to scale torsion terms involving unique atoms, such that at the endstate the torsion term is turned off/on depending on the state the unique atoms belong to. Default False.

field interpolate_old_and_new_14s = False#

Whether to turn off interactions for new exceptions (not just 1,4s) at lambda 0 and old exceptions at lambda 1. If False they are present in the nonbonded force. Default False.

field lambda_functions = 'default'#

Key of which switching functions to use for alchemical mutation. Default ‘default’.

field lambda_windows = 11#

Number of lambda windows to calculate. Default 11.

field softcore_LJ_v2 = True#

Whether to use the LJ softcore function as defined by Gapsys et al. JCTC 2012 Default True.

field softcore_alpha = 0.85#

Softcore alpha parameter. Default 0.85

field softcore_electrostatics = True#

Whether to use softcore electrostatics. Default True.

field softcore_electrostatics_alpha = 0.3#

Softcore alpha parameter for electrostatics. Default 0.3

field softcore_sigma_Q = 1.0#

Softcore sigma parameter for softcore electrostatics. Default 1.0.

field unsampled_endstates = False#

Whether to have extra unsampled endstate windows for long range correction. Default False.

field use_dispersion_correction = False#

Whether to use dispersion correction in the hybrid topology state. Default False.

pydantic settings openfe.protocols.openmm_rfe.equil_rfe_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.

Fields:
field compute_platform: str | None = None#

OpenMM compute platform to perform MD integration with. If None, will choose fastest available platform. Default None.

pydantic settings openfe.protocols.openmm_rfe.equil_rfe_settings.IntegratorSettings#

Settings for the LangevinSplittingDynamicsMove integrator

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.

Fields:
field barostat_frequency = <Quantity(25, 'timestep')>#

Frequency at which volume scaling changes should be attempted. Default 25 * unit.timestep.

field collision_rate = <Quantity(1.0, '1 / picosecond')>#

Collision frequency. Default 1.0 / unit.pisecond.

field constraint_tolerance = 1e-06#

Tolerance for the constraint solver. Default 1e-6.

field n_restart_attempts = 20#

Number of attempts to restart from Context if there are NaNs in the energies after integration. Default 20.

field n_steps = <Quantity(250, 'timestep')>#

Number of integration timesteps between each time the MCMC move is applied. Default 250 * unit.timestep.

field reassign_velocities = False#

If True, velocities are reassigned from the Maxwell-Boltzmann distribution at the beginning of move. Default False.

field timestep = <Quantity(4, 'femtosecond')>#

Size of the simulation timestep. Default 4 * unit.femtosecond.

pydantic settings openfe.protocols.openmm_rfe.equil_rfe_settings.SimulationSettings#

Settings for simulation control, including lengths, 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.

Fields:
field checkpoint_interval = <Quantity(250, 'timestep')>#

Frequency to write the checkpoint file. Default 250 * unit.timestep.

field checkpoint_storage = 'checkpoint.nc'#

Separate filename for the checkpoint file. Note, this should not be a full path, just a filename. Default ‘checkpoint.nc’.

field equilibration_length: Quantity [Required]#

Length of the equilibration phase in units of time. The total number of steps from this equilibration length (i.e. equilibration_length / IntegratorSettings.timestep) must be a multiple of the value defined for IntegratorSettings.n_steps.

field forcefield_cache: str | None = 'db.json'#

Filename for caching small molecule residue templates so they can be later reused.

field minimization_steps = 5000#

Number of minimization steps to perform. Default 5000.

field output_filename = 'simulation.nc'#

Path to the storage file for analysis. Default ‘simulation.nc’.

field output_indices = 'not water'#

Selection string for which part of the system to write coordinates for. Default ‘not water’.

field production_length: Quantity [Required]#

Length of the production phase in units of time. The total number of steps from this production length (i.e. production_length / IntegratorSettings.timestep) must be a multiple of the value defined for IntegratorSettings.nsteps.

pydantic settings openfe.protocols.openmm_rfe.equil_rfe_settings.SolvationSettings#

Settings for solvating the system

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.

Fields:
field solvent_model = 'tip3p'#

Force field water model to use. Allowed values are; tip3p, spce, tip4pew, and tip5p.

field solvent_padding = <Quantity(1.2, 'nanometer')>#

Minimum distance from any solute atoms to the solvent box edge.

pydantic settings openfe.protocols.openmm_rfe.equil_rfe_settings.SystemSettings#

Settings describing the simulation system 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.

Fields:
field nonbonded_cutoff = <Quantity(1.0, 'nanometer')>#

Cutoff value for short range nonbonded interactions. Default 1.0 * unit.nanometer.

field nonbonded_method = 'PME'#

Method for treating nonbonded interactions, currently only PME and NoCutoff are allowed. Default PME.

pydantic settings openfe.protocols.openmm_rfe.equil_rfe_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.

Fields:
field ph: PositiveFloat | None = None#

Simulation pH

Constraints:

  • exclusiveMinimum = 0

field pressure = <Quantity(1.0, 'bar')>#

Simulation pressure, default units standard atmosphere (atm)

field redox_potential: float | None = None#

Simulation redox potential

field temperature = <Quantity(298.15, 'kelvin')>#

Simulation temperature, default units kelvin

pydantic settings openfe.protocols.openmm_rfe.equil_rfe_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.

Fields:
field constraints: str | None = 'hbonds'#

Constraints to be applied to system. One of ‘hbonds’, ‘allbonds’, ‘hangles’ or None, default ‘hbonds’

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 hydrogen_mass: float = 3.0#

Mass to be repartitioned to hydrogens from neighbouring heavy atoms (in amu), default 3.0

field remove_com: bool = False#
field rigid_water: bool = True#
field small_molecule_forcefield: str = 'openff-2.0.0'#

Name of the force field to be used for SmallMoleculeComponent

Protocol API specification#

class openfe.protocols.openmm_rfe.RelativeHybridTopologyProtocol(*args, **kwargs)#

Create a new Protocol instance.

Parameters:

settings (Settings) – The full settings for this Protocol instance.

result_cls#

alias of RelativeHybridTopologyProtocolResult