OpenMM Absolute Solvation Free Energy Protocol#

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

Protocol API specification#

AbsoluteSolvationProtocol

Absolute solvation free energy calculations using OpenMM and OpenMMTools.

AbsoluteSolvationProtocolResult

Dict-like container for the output of a AbsoluteSolvationProtocol

Protocol Settings#

Below are the settings which can be tweaked in the protocol. The default settings (accessed using AbsoluteSolvationProtocol.default_settings()) will automatically populate settings which we have found to be useful for running solvation free energy calculations. There will however be some cases (such as when calculating difficult to converge systems) where you will need to tweak some of the following settings.

pydantic model openfe.protocols.openmm_afe.equil_solvation_afe_method.AbsoluteSolvationSettings

Configuration object for AbsoluteSolvationProtocol.

See also

openfe.protocols.openmm_afe.AbsoluteSolvationProtocol

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 forcefield_settings: OpenMMSystemGeneratorFFSettings [Required]

Parameters to set up the force field with OpenMM Force Fields

field thermo_settings: ThermoSettings [Required]

Settings for thermodynamic parameters

field vacuum_system_settings: SystemSettings [Required]

Simulation system settings including the long-range non-bonded methods for the vacuum transformation.

field solvent_system_settings: SystemSettings [Required]

Simulation system settings including the long-range non-bonded methods for the solvent transformation.

field solvation_settings: SolvationSettings [Required]

Settings for solvating the system.

field alchemical_settings: AlchemicalSettings [Required]

Alchemical protocol settings including lambda windows.

field alchemsampler_settings: AlchemicalSamplerSettings [Required]

Settings for controling how we sample alchemical space, including the number of repeats.

field vacuum_engine_settings: OpenMMEngineSettings [Required]

Settings specific to the OpenMM engine, such as the compute platform for the vacuum transformation.

field solvent_engine_settings: OpenMMEngineSettings [Required]

Settings specific to the OpenMM engine, such as the compute platform for the solvent transformation.

field integrator_settings: IntegratorSettings [Required]

Settings for controlling the integrator, such as the timestep and barostat settings.

field vacuum_simulation_settings: SimulationSettings [Required]

Simulation control settings, including simulation lengths and record-keeping for the vacuum transformation.

field solvent_simulation_settings: SimulationSettings [Required]

Simulation control settings, including simulation lengths and record-keeping for the solvent transformation.

pydantic model openfe.protocols.openmm_afe.equil_afe_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
field remove_com: bool = False
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.0.0'

Name of the force field to be used for SmallMoleculeComponent

pydantic model openfe.protocols.openmm_afe.equil_afe_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

pydantic model openfe.protocols.openmm_afe.equil_afe_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.

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 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_target_error: FloatQuantity = <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 online_analysis_minimum_iterations = 500

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

field n_repeats: int = 3

Number of independent repeats to run. Default 3

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_replicas = 11

Number of replicas to use. Default 11.

pydantic model openfe.protocols.openmm_afe.equil_afe_settings.AlchemicalSettings

Settings for the alchemical protocol

These settings describe 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.

field lambda_elec_windows = 12

Number of lambda electrostatic alchemical steps, default 12

field lambda_vdw_windows = 12

Number of lambda vdw alchemical steps, default 12

pydantic model openfe.protocols.openmm_afe.equil_afe_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_afe.equil_afe_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.

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

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

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

Collision frequency. Default 1.0 / unit.pisecond.

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 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 = <Quantity(25, 'timestep')>

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

pydantic model openfe.protocols.openmm_afe.equil_afe_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.

field minimization_steps = 5000

Number of minimization steps to perform. Default 5000.

field equilibration_length: FloatQuantity [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 production_length: FloatQuantity [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.

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 output_indices = 'not water'

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

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 forcefield_cache: str | None = 'db.json'

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

pydantic model openfe.protocols.openmm_afe.equil_afe_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.

field solvent_model = '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_afe.equil_afe_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.

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.