Merge pull request #432 from choderalab/fix-docs

Set chunksize for iteration dimension to 1 and doc fixes

devtools/conda-envs/test_env.yaml

@@ -25,7 +25,6 @@ dependencies:
   - sphinxcontrib-bibtex
   - mpiplus
   - pymbar
-  - pyyaml
 
     # Testing
   - nose

docs/gettingstarted.rst

@@ -761,7 +761,7 @@ part of a system.
 
 .. doctest::
 
-    >>> # Prepare the T4 Lysozyme + p-xylene system for alchemical modification.
+    >>> # Prepare the host-guest system for alchemical modification.
     >>> guest_atoms = host_guest.mdtraj_topology.select('resname B2')
     >>> alchemical_region = alchemy.AlchemicalRegion(alchemical_atoms=guest_atoms)
     >>> factory = alchemy.AbsoluteAlchemicalFactory()
@@ -786,8 +786,8 @@ Finally, let's mix Monte Carlo and dynamics for propagation.
 .. doctest::
 
     >>> sequence_move = mcmc.SequenceMove(move_list=[
-    ...     mcmc.MCDisplacementMove(atom_subset=pxylene_atoms),
-    ...     mcmc.MCRotationMove(atom_subset=pxylene_atoms),
+    ...     mcmc.MCDisplacementMove(atom_subset=guest_atoms),
+    ...     mcmc.MCRotationMove(atom_subset=guest_atoms),
     ...     mcmc.LangevinSplittingDynamicsMove(timestep=2.0*unit.femtoseconds, n_steps=n_steps,
     ...                                        reassign_velocities=True, n_restart_attempts=6)
     ... ])

docs/releasehistory.rst

@@ -1,12 +1,19 @@
 Release History
 ***************
 
-Current development
-===================
+0.18.3 - Storage enhancements and bugfixes
+==========================================
 
 Bugfixes
 --------
 - Fixed a bug in ``multistateanalyzer.py`` where a function was imported from ``openmmtools.utils`` instead of ``openmmtools.multistate.utils`` (`#430 <https://github.com/choderalab/openmmtools/pull/430>`_).
+- Fixed a few imprecisions in the documentation (`#432 <https://github.com/choderalab/openmmtools/pull/432>`_).
+
+Enhancements
+------------
+- Writing on disk is much faster when the `checkpoint_interval` of multi-state samplers is large. This was due
+  to the dimension of the netcdf chunk size increasing with the checkpoint interval and surpassing the dimension
+  of the netcdf chunk cache. The chunk size of the iteration dimension is now always set to 1 (`#432 <https://github.com/choderalab/openmmtools/pull/432>`_).
 
 0.18.2 - Bugfix release
 =======================

docs/states.rst

@@ -25,3 +25,15 @@ States
     IComposableState
     GlobalParameterFunction
     GlobalParameterState
+
+|
+
+Utility functions
+-----------------
+
+.. currentmodule:: openmmtools.states
+.. autosummary::
+    :nosignatures:
+    :toctree: api/generated/
+
+    create_thermodynamic_state_protocol

openmmtools/cache.py

@@ -650,12 +650,57 @@ class DummyContextCache(object):
         The OpenMM platform to use. If None, OpenMM tries to select
         the fastest one available.
 
+    Examples
+    --------
+    Create a new ``Context`` object for alanine dipeptide in vacuum in NPT.
+
+    >>> from simtk import openmm, unit
+    >>> from openmmtools import states, testsystems
+    >>> system = testsystems.AlanineDipeptideVacuum().system
+    >>> thermo_state = states.ThermodynamicState(system, temperature=300*unit.kelvin)
+
+    >>> context_cache = DummyContextCache()
+    >>> integrator = openmm.VerletIntegrator(1.0*unit.femtosecond)
+    >>> context, context_integrator = context_cache.get_context(thermo_state, integrator)
+
+    Or create a ``Context`` with an arbitrary integrator (when you only
+    need to compute energies, for example).
+
+    >>> context, context_integrator = context_cache.get_context(thermo_state)
+
     """
     def __init__(self, platform=None):
         self.platform = platform
 
-    def get_context(self, thermodynamic_state, integrator):
-        """Create a new context in the given thermodynamic state."""
+    def get_context(self, thermodynamic_state, integrator=None):
+        """Create a new context in the given thermodynamic state.
+
+        Parameters
+        ----------
+        thermodynamic_state : states.ThermodynamicState
+            The thermodynamic state of the system.
+        integrator : simtk.openmm.Integrator, optional
+            The integrator to bind to the new context. If ``None``, an arbitrary
+            integrator is used. Currently, this is a ``LangevinIntegrator`` with
+            "V R O R V" splitting, but this might change in the future. Default
+            is ``None``.
+
+        Returns
+        -------
+        context : simtk.openmm.Context
+            The new context in the given thermodynamic system.
+        context_integrator : simtk.openmm.Integrator
+            The integrator bound to the context that can be used for
+            propagation. This is identical to the ``integrator`` argument
+            if it was passed.
+
+        """
+        if integrator is None:
+            integrator = integrators.LangevinIntegrator(
+                timestep=1.0*unit.femtoseconds,
+                splitting="V R O R V",
+                temperature=thermodynamic_state.temperature
+            )
         context = thermodynamic_state.create_context(integrator, self.platform)
         return context, integrator
 

openmmtools/integrators.py

@@ -2125,22 +2125,29 @@ def __init__(self, *args, **kwargs):
         kwargs['splitting'] = "O { V R V } O"
         super(GHMCIntegrator, self).__init__(*args, **kwargs)
 
+
 class FIREMinimizationIntegrator(mm.CustomIntegrator):
     """Fast Internal Relaxation Engine (FIRE) minimization.
+
     Notes
     -----
     This integrator is taken verbatim from Peter Eastman's example appearing in the CustomIntegrator header file documentation.
+
     References
     ----------
     Erik Bitzek, Pekka Koskinen, Franz Gaehler, Michael Moseler, and Peter Gumbsch.
     Structural Relaxation Made Simple. PRL 97:170201, 2006.
     http://dx.doi.org/10.1103/PhysRevLett.97.170201
+
     Examples
     --------
     >>> from openmmtools import testsystems
     >>> from simtk import openmm
     >>> t = testsystems.AlanineDipeptideVacuum()
     >>> system, positions = t.system, t.positions
+
+    Create a FIRE integrator with default parameters and minimize for 100 steps
+
     >>> integrator = FIREMinimizationIntegrator()
     >>> context = openmm.Context(system, integrator)
     >>> context.setPositions(positions)

openmmtools/mcmc.py

@@ -570,7 +570,7 @@ class BaseIntegratorMove(MCMCMove):
     reassign_velocities : bool, optional
         If True, the velocities will be reassigned from the Maxwell-Boltzmann
         distribution at the beginning of the move (default is False).
-    restart_attempts : int, optional
+    n_restart_attempts : int, optional
         When greater than 0, if after the integration there are NaNs in energies,
         the move will restart. When the integrator has a random component, this
         may help recovering. On the last attempt, the ``Context`` is
@@ -583,7 +583,7 @@ class BaseIntegratorMove(MCMCMove):
     n_steps : int
     context_cache : openmmtools.cache.ContextCache
     reassign_velocities : bool
-    restart_attempts : int or None
+    n_restart_attempts : int or None
 
     Examples
     --------