Skip to content

config #

Configure free energy calculations.

Classes:

  • System –

    Define the two solvents that solutes will be transferred between (a -> b),

  • MinimizationProtocol –

    Configure how a system should be energy minimized.

  • SimulationProtocol –

    Configure how a system should be evolved by molecular simulation.

  • HREMDProtocol –

    Configure how a system should be evolved by Hamiltonian replica exchange.

  • EquilibriumProtocol –

    Configure how an equilibrium (e.g. TI, MBAR) alchemical free energy

  • SwitchingProtocol –

    Configure non-reversibly driving a system between to alchemical states.

  • NonEquilibriumProtocol –

    Configure a non-equilibrium alchemical free energy calculation [1, 2].

  • Config –

    Configure a transfer free energy calculation.

  • Result –

    The result of a free energy calculation.

System pydantic-model #

Bases: BaseModel

Define the two solvents that solutes will be transferred between (a -> b), as well as the solutes themselves.

Fields:

Validators:

solutes pydantic-field #

solutes: dict[str, PositiveInt]

A dictionary containing the SMILES patterns of each solute in the system as well as how many instances of each there should be.

solvent_a pydantic-field #

solvent_a: dict[str, PositiveInt] | None

A dictionary containing the SMILES patterns of each component in the first solvent as well as how many instances of each there should be.A value of None should be used to indicate vacuum.

solvent_b pydantic-field #

solvent_b: dict[str, PositiveInt] | None

A dictionary containing the SMILES patterns of each component in the second solvent as well as how many instances of each there should be. A value of None should be used to indicate vacuum.

n_solute_molecules pydantic-field #

n_solute_molecules: int

Returns the total number of solute molecules that will be present.

n_solvent_molecules_a pydantic-field #

n_solvent_molecules_a: int

Returns the total number of solvent molecules that will be present in the first solution.

n_solvent_molecules_b pydantic-field #

n_solvent_molecules_b: int

Returns the total number of solvent molecules that will be present in the second solution.

components_a pydantic-field #

components_a: list[tuple[str, int]]

Returns the identities and counts of the molecules present in the first system.

Returns:

  • list[tuple[str, int]] –

    The SMILES representation and count of each component.

components_b pydantic-field #

components_b: list[tuple[str, int]]

Returns the identities and counts of the molecules present in the second system.

Returns:

  • list[tuple[str, int]] –

    The SMILES representation and count of each component.

MinimizationProtocol pydantic-model #

Bases: BaseModel

Configure how a system should be energy minimized.

Fields:

tolerance pydantic-field #

tolerance: OpenMMQuantity[
    kilojoule_per_mole / nanometers
] = (10.0 * kilojoule_per_mole / nanometers)

How precisely the energy minimum must be located [kj / mol / nm]

max_iterations pydantic-field #

max_iterations: NonNegativeInt = 0

The maximum number of iterations to perform. If this is 0, minimization is continued until the results converge.

SimulationProtocol pydantic-model #

Bases: BaseModel

Configure how a system should be evolved by molecular simulation.

Fields:

integrator pydantic-field #

integrator: LangevinIntegrator = LangevinIntegrator(
    timestep=2.0 * femtosecond, friction=1.0 / picosecond
)

The integrator to use for the simulation.

n_steps pydantic-field #

n_steps: PositiveInt

The number of steps to evolve the system by.

HREMDProtocol pydantic-model #

Bases: BaseModel

Configure how a system should be evolved by Hamiltonian replica exchange.

Fields:

integrator pydantic-field #

integrator: LangevinIntegrator = LangevinIntegrator(
    timestep=2.0 * femtosecond, friction=1.0 / picosecond
)

The integrator to use for the simulation.

n_warmup_steps pydantic-field #

n_warmup_steps: int = 50000

The number of steps to run each replica for before starting hremd trials. All energies gathered during this period will be discarded.

n_steps_per_cycle pydantic-field #

n_steps_per_cycle: int = 1000

The number of steps to propagate the system by before attempting an exchange.

n_cycles pydantic-field #

n_cycles: int = 2500

The number of cycles of 'propagate the system' -> 'exchange replicas' to run.

trajectory_interval pydantic-field #

trajectory_interval: int | None = None

The number of cycles to run before saving the current replica states to DCD trajectory files. If None, no trajectories will be saved.

trajectory_enforce_pbc pydantic-field #

trajectory_enforce_pbc: bool = False

Whether to apply periodic boundary conditions when retrieving coordinates for writing to trajectory files.

EquilibriumProtocol pydantic-model #

Bases: BaseModel

Configure how an equilibrium (e.g. TI, MBAR) alchemical free energy calculation.

Fields:

Validators:

  • _validate_lambda_lengths

minimization_protocol pydantic-field #

minimization_protocol: MinimizationProtocol = (
    MinimizationProtocol()
)

Whether to minimize the energy of the system prior to any simulations.

equilibration_protocol pydantic-field #

equilibration_protocol: SimulationProtocol = (
    SimulationProtocol(n_steps=100000)
)

The (optional) protocol that describes the equilibration simulation to run prior to the production one.

production_protocol pydantic-field #

production_protocol: HREMDProtocol = HREMDProtocol(
    n_steps_per_cycle=6250, n_cycles=160
)

The protocol that describes the production to run.

lambda_sterics pydantic-field #

lambda_sterics: list[confloat(ge=0.0, le=1.0)]

The alchemical pathway to transform the vdW interactions along. A value of 1.0 represents a fully interacting system while a value of 0.0 represents a system with the solute-solute and solute-solvent vdW interactions disabled.

lambda_electrostatics pydantic-field #

lambda_electrostatics: list[confloat(ge=0.0, le=1.0)]

The alchemical pathway to transform the electrostatic interactions along. A value of 1.0 represents a fully interacting system while a value of 0.0 represents a system with the solute-solute and solute-solvent electrostatic interactions disabled.

n_states pydantic-field #

n_states: int

Returns the number of lambda states that will be sampled at.

SwitchingProtocol pydantic-model #

Bases: BaseModel

Configure non-reversibly driving a system between to alchemical states.

Fields:

n_electrostatic_steps pydantic-field #

n_electrostatic_steps: NonNegativeInt

The number of steps to annihilate the electrostatics interactions over. The total time needed to annihilate the electrostatics interactions will be n_electrostatic_steps * n_steps_per_electrostatic_step * timestep

n_steps_per_electrostatic_step pydantic-field #

n_steps_per_electrostatic_step: NonNegativeInt

The number of timesteps to evolve the system by each time the electrostatics interactions are modified. A value of 1 will give a 'smooth' transition between the each discrete lambda value whereas a value greater than 1 will yield a stepwise transition as shown in Figure 3 of doi:10.1063/1.4712028.

n_steric_steps pydantic-field #

n_steric_steps: NonNegativeInt

The number of steps to decouple the sterics interactions over once the electrostatics interactions have been annihilated. The total time needed to annihilate the sterics interactions will be n_steric_steps * n_steps_per_steric_step * timestep

n_steps_per_steric_step pydantic-field #

n_steps_per_steric_step: NonNegativeInt

The number of timesteps to evolve the system by each time the sterics interactions are modified. A value of 1 will give a 'smooth' transition between the each discrete lambda value whereas a value greater than 1 will yield a stepwise transition as shown in Figure 3 of doi:10.1063/1.4712028.

NonEquilibriumProtocol pydantic-model #

Bases: BaseModel

Configure a non-equilibrium alchemical free energy calculation [1, 2].

It is expected that first the electrostatics interactions will be annihilated followed by a decoupling of the sterics interactions.

References

[1] Ballard, Andrew J., and Christopher Jarzynski. "Replica exchange with nonequilibrium switches: Enhancing equilibrium sampling by increasing replica overlap." The Journal of chemical physics 136.19 (2012): 194101.

[2] Gapsys, Vytautas, et al. "Large scale relative protein ligand binding affinities using non-equilibrium alchemy." Chemical Science 11.4 (2020): 1140-1152.

Fields:

minimization_protocol pydantic-field #

minimization_protocol: MinimizationProtocol | None = (
    MinimizationProtocol()
)

The (optional) protocol to follow when minimizing the system in both the end states prior to running the equilibrium simulations.

equilibration_protocol pydantic-field #

equilibration_protocol: SimulationProtocol | None = (
    SimulationProtocol(n_steps=100000)
)

The (optional) protocol to follow when equilibrating the system in both the end states prior to running the production equilibrium simulations.

production_protocol pydantic-field #

production_protocol: SimulationProtocol = (
    SimulationProtocol(n_steps=6250 * 160)
)

The protocol to follow when running the production equilibrium simulation in both the end states. The snapshots generated at the end of each iteration will be used for each non-equilibrium switch.

production_report_interval pydantic-field #

production_report_interval: PositiveInt = 6250

The interval at which to write out the simulation state during the production simulation.

switching_protocol pydantic-field #

switching_protocol: SwitchingProtocol

The protocol that describes how each snapshot generated during the production simulation should be driven from state 0 -> 1 and likewise 1 -> 0 in order to compute the non-equilibrium work distributions.

Config pydantic-model #

Bases: BaseModel

Configure a transfer free energy calculation.

Fields:

temperature pydantic-field #

temperature: OpenMMQuantity[kelvin]

The temperature to calculate at [K].

pressure pydantic-field #

pressure: OpenMMQuantity[atmosphere] | None

The pressure to calculate at [atm].

alchemical_protocol_a pydantic-field #

alchemical_protocol_a: AlchemicalProtocol

The protocol that describes the alchemical pathway to transform the solute along in the first solvent.

alchemical_protocol_b pydantic-field #

alchemical_protocol_b: AlchemicalProtocol

The protocol that describes the alchemical pathway to transform the solute along in the second solvent.

Result pydantic-model #

Bases: BaseModel

The result of a free energy calculation.

Fields:

dg_solvent_a pydantic-field #

dg_solvent_a: OpenMMQuantity[KCAL_MOL]

The change in free energy of alchemically transforming the solute from an interacting to a non-interacting state in the first solvent.

dg_std_solvent_a pydantic-field #

dg_std_solvent_a: OpenMMQuantity[KCAL_MOL]

The standard error in dg_solvent_a.

dg_solvent_b pydantic-field #

dg_solvent_b: OpenMMQuantity[KCAL_MOL]

The change in free energy of alchemically transforming the solute from an interacting to a non-interacting state in the second solvent.

dg_std_solvent_b pydantic-field #

dg_std_solvent_b: OpenMMQuantity[KCAL_MOL]

The standard error in dg_solvent_b.