def run(self, niterations=None, mpicomm=None, options=None):
"""
Run a free energy calculation.
Parameters
----------
niterations : int, optional, default=None
If specified, only this many iterations will be run for each phase.
This is useful for running simulation incrementally, but may incur a good deal of overhead.
mpicomm : MPI communicator, optional, default=None
If an MPI communicator is passed, an MPI simulation will be attempted.
options : dict of str, optional, default=None
If specified, these options will override any other options.
"""
# Make sure we've been properly initialized first.
if not self._initialized:
raise Exception(
"Yank must first be initialized by either resume() or create()."
)
# Handle some logistics necessary for MPI.
if mpicomm:
# Turn off output from non-root nodes:
if not (mpicomm.rank == 0):
self.verbose = False
# Make sure each thread's random number generators have unique seeds.
# TODO: Do we need to store seed in repex object?
seed = np.random.randint(sys.maxint - mpicomm.size) + mpicomm.rank
np.random.seed(seed)
# Run all phases sequentially.
# TODO: Divide up MPI resources among the phases so they can run simultaneously?
for phase in self._phases:
store_filename = self._store_filenames[phase]
# Resume simulation from store file.
simulation = ModifiedHamiltonianExchange(
store_filename=store_filename, mpicomm=mpicomm)
simulation.resume(options=options)
# TODO: We may need to manually update run options here if options=options above does not behave as expected.
simulation.run(niterations_to_run=niterations)
# Clean up to ensure we close files, contexts, etc.
del simulation
return
def run(self, niterations_to_run=None, mpicomm=None, options=None):
"""
Run a free energy calculation.
Parameters
----------
niterations_to_run : int, optional, default=None
If specified, only this many iterations will be run for each phase.
This is useful for running simulation incrementally, but may incur a good deal of overhead.
mpicomm : MPI communicator, optional, default=None
If an MPI communicator is passed, an MPI simulation will be attempted.
options : dict of str, optional, default=None
If specified, these options will override any other options.
"""
# Make sure we've been properly initialized first.
if not self._initialized:
raise Exception("Yank must first be initialized by either resume() or create().")
# Handle some logistics necessary for MPI.
if mpicomm:
# Turn off output from non-root nodes:
if not (mpicomm.rank==0):
self.verbose = False
# Make sure each thread's random number generators have unique seeds.
# TODO: Do we need to store seed in repex object?
seed = np.random.randint(sys.maxint - mpicomm.size) + mpicomm.rank
np.random.seed(seed)
# Run all phases sequentially.
# TODO: Divide up MPI resources among the phases so they can run simultaneously?
for phase in self._phases:
store_filename = self._store_filenames[phase]
# Resume simulation from store file.
simulation = ModifiedHamiltonianExchange(store_filename=store_filename, mpicomm=mpicomm)
simulation.resume(options=options)
# TODO: We may need to manually update run options here if options=options above does not behave as expected.
simulation.run(niterations_to_run=niterations_to_run)
# Clean up to ensure we close files, contexts, etc.
del simulation
return
def run(self, niterations_to_run=None):
"""
Run a free energy calculation.
Parameters
----------
niterations_to_run : int, optional, default=None
If specified, only this many iterations will be run for each phase.
This is useful for running simulation incrementally, but may incur a good deal of overhead.
"""
# Make sure we've been properly initialized first.
if not self._initialized:
raise Exception(
"Yank must first be initialized by either resume() or create()."
)
# Handle some logistics necessary for MPI.
if self._mpicomm is not None:
logger.debug("yank.run starting for MPI...")
# Make sure each thread's random number generators have unique seeds.
# TODO: Do we need to store seed in repex object?
seed = np.random.randint(4294967295 -
self._mpicomm.size) + self._mpicomm.rank
np.random.seed(seed)
# Run all phases sequentially.
# TODO: Divide up MPI resources among the phases so they can run simultaneously?
for phase in self._phases:
store_filename = self._store_filenames[phase]
# Resume simulation from store file.
simulation = ModifiedHamiltonianExchange(
store_filename=store_filename, mpicomm=self._mpicomm)
simulation.resume(options=self._repex_parameters)
# TODO: We may need to manually update run options here if options=options above does not behave as expected.
simulation.run(niterations_to_run=niterations_to_run)
# Clean up to ensure we close files, contexts, etc.
del simulation
return
def run(self, niterations_to_run=None):
"""
Run a free energy calculation.
Parameters
----------
niterations_to_run : int, optional, default=None
If specified, only this many iterations will be run for each phase.
This is useful for running simulation incrementally, but may incur a good deal of overhead.
"""
# Make sure we've been properly initialized first.
if not self._initialized:
raise Exception("Yank must first be initialized by either resume() or create().")
# Handle some logistics necessary for MPI.
if self._mpicomm is not None:
logger.debug("yank.run starting for MPI...")
# Make sure each thread's random number generators have unique seeds.
# TODO: Do we need to store seed in repex object?
seed = np.random.randint(4294967295 - self._mpicomm.size) + self._mpicomm.rank
np.random.seed(seed)
# Run all phases sequentially.
# TODO: Divide up MPI resources among the phases so they can run simultaneously?
for phase in self._phases:
store_filename = self._store_filenames[phase]
# Resume simulation from store file.
simulation = ModifiedHamiltonianExchange(store_filename=store_filename, mpicomm=self._mpicomm)
simulation.resume(options=self._repex_parameters)
# TODO: We may need to manually update run options here if options=options above does not behave as expected.
simulation.run(niterations_to_run=niterations_to_run)
# Clean up to ensure we close files, contexts, etc.
del simulation
return
def _create_phase(self, phase, reference_system, positions, atom_indices, thermodynamic_state, protocols=None, options=None, mpicomm=None):
"""
Create a repex object for a specified phase.
Parameters
----------
phase : str
The phase being initialized (one of ['complex', 'solvent', 'vacuum'])
reference_system : simtk.openmm.System
The reference system object from which alchemical intermediates are to be construcfted.
positions : list of simtk.unit.Qunatity objects containing (natoms x 3) positions (as numpy or lists)
The list of positions to be used to seed replicas in a round-robin way.
atom_indices : dict
atom_indices[phase][component] is the set of atom indices associated with component, where component is ['ligand', 'receptor']
thermodynamic_state : ThermodynamicState
Thermodynamic state from which reference temperature and pressure are to be taken.
protocols : dict of list of AlchemicalState, optional, default=None
If specified, the alchemical protocol protocols[phase] will be used for phase 'phase' instead of the default.
options : dict of str, optional, default=None
If specified, these options will override default repex simulation options.
"""
# Make sure positions argument is a list of coordinate snapshots.
if hasattr(positions, 'unit'):
# Wrap in list.
positions = [positions]
# Check the dimensions of positions.
for index in range(len(positions)):
# Make sure it is recast as a numpy array.
positions[index] = unit.Quantity(numpy.array(positions[index] / positions[index].unit), positions[index].unit)
[natoms, ndim] = (positions[index] / positions[index].unit).shape
if natoms != reference_system.getNumParticles():
raise Exception("positions argument must be a list of simtk.unit.Quantity of (natoms,3) lists or numpy array with units compatible with nanometers.")
# Create metadata storage.
metadata = dict()
# Make a deep copy of the reference system so we don't accidentally modify it.
reference_system = copy.deepcopy(reference_system)
# TODO: Use more general approach to determine whether system is periodic.
is_periodic = self._is_periodic(reference_system)
# Make sure pressure is None if not periodic.
if not is_periodic: thermodynamic_state.pressure = None
# Compute standard state corrections for complex phase.
metadata['standard_state_correction'] = 0.0
# TODO: Do we need to include a standard state correction for other phases in periodic boxes?
if phase == 'complex-implicit':
# Impose restraints for complex system in implicit solvent to keep ligand from drifting too far away from receptor.
if self.verbose: print "Creating receptor-ligand restraints..."
reference_positions = positions[0]
if self.restraint_type == 'harmonic':
restraints = HarmonicReceptorLigandRestraint(thermodynamic_state, reference_system, reference_positions, atom_indices['receptor'], atom_indices['ligand'])
elif self.restraint_type == 'flat-bottom':
restraints = FlatBottomReceptorLigandRestraint(thermodynamic_state, reference_system, reference_positions, atom_indices['receptor'], atom_indices['ligand'])
else:
raise Exception("restraint_type of '%s' is not supported." % self.restraint_type)
force = restraints.getRestraintForce() # Get Force object incorporating restraints
reference_system.addForce(force)
metadata['standard_state_correction'] = restraints.getStandardStateCorrection() # standard state correction in kT
elif phase == 'complex-explicit':
# For periodic systems, we do not use a restraint, but must add a standard state correction for the box volume.
# TODO: What if the box volume fluctuates during the simulation?
box_vectors = reference_system.getDefaultPeriodicBoxVectors()
box_volume = thermodynamic_state._volume(box_vectors)
STANDARD_STATE_VOLUME = 1660.53928 * unit.angstrom**3
metadata['standard_state_correction'] = numpy.log(STANDARD_STATE_VOLUME / box_volume) # TODO: Check sign.
# Use default alchemical protocols if not specified.
if not protocols:
protocols = self.default_protocols
# Create alchemically-modified states using alchemical factory.
if self.verbose: print "Creating alchemically-modified states..."
factory = AbsoluteAlchemicalFactory(reference_system, ligand_atoms=atom_indices['ligand'])
systems = factory.createPerturbedSystems(protocols[phase])
# Randomize ligand position if requested, but only for implicit solvent systems.
if self.randomize_ligand and (phase == 'complex-implicit'):
if self.verbose: print "Randomizing ligand positions and excluding overlapping configurations..."
randomized_positions = list()
nstates = len(systems)
for state_index in range(nstates):
positions_index = numpy.random.randint(0, len(positions))
current_positions = positions[positions_index]
new_positions = ModifiedHamiltonianExchange.randomize_ligand_position(current_positions,
atom_indices['receptor'], atom_indices['ligand'],
self.randomize_ligand_sigma_multiplier * restraints.getReceptorRadiusOfGyration(),
self.randomize_ligand_close_cutoff)
randomized_positions.append(new_positions)
positions = randomized_positions
# Identify whether any atoms will be displaced via MC.
mc_atoms = list()
if 'ligand' in atom_indices:
mc_atoms = atom_indices['ligand']
# Combine simulation options with defaults.
options = dict(self.default_options.items() + options.items())
# Set up simulation.
# TODO: Support MPI initialization?
if self.verbose: print "Creating replica exchange object..."
store_filename = os.path.join(self._store_directory, phase + '.nc')
self._store_filenames[phase] = store_filename
simulation = ModifiedHamiltonianExchange(store_filename, mpicomm=mpicomm)
simulation.create(thermodynamic_state, systems, positions,
displacement_sigma=self.mc_displacement_sigma, mc_atoms=mc_atoms,
protocol=options, metadata=metadata)
simulation.verbose = self.verbose
# Initialize simulation.
# TODO: Use the right scheme for initializing the simulation without running.
if self.verbose: print "Initializing simulation..."
simulation.run(0)
# Clean up simulation.
del simulation
return
