Skip to content

Commit

Permalink
Merge pull request #55 from datreant/feature-ukwargs
Browse files Browse the repository at this point in the history
Sim stores universe kwargs if possible; refactored atomselections to address confusing API
  • Loading branch information
orbeckst committed Apr 5, 2016
2 parents 7bd6b76 + 89b3ca0 commit 7946d1b
Show file tree
Hide file tree
Showing 5 changed files with 302 additions and 178 deletions.
77 changes: 49 additions & 28 deletions docs/sims.rst
Original file line number Diff line number Diff line change
Expand Up @@ -46,38 +46,53 @@ access the Sim's Universe directly with::

>>> s.universe

At this point, we get back ``None``. However, if we define a topology for the
Universe with
At this point, we get back ``None``. However, we can define the Sim's Universe
by giving it one direclty::

>>> s.udef.topology = 'path/to/topology.psf'
>>> import MDAnalysis as mda
>>> s.universe = mda.Universe('path/to/topology.psf',
'path/to/trajectory.dcd')
>>> s.universe
<Universe with 3341 atoms and 3365 bonds>

then we get back a Universe built with this topology instead::
The Universe definition is persistent, so we can get back an identical Universe
later from another Python session with our Sim::

>>> import mdsynthesis as mds
>>> s = mds.Sim('adk')
>>> s.universe
<Universe with 3341 atoms and 3365 bonds>

We can also add a trajectory::

>>> s.udef.trajectory = 'path/to/trajectory.dcd'
Changing the Universe definition
--------------------------------
.. warning:: This interface may be removed in a future release, but remains for
now due to limitations in MDAnalysis. It is encouraged to set the
Universe definition directly as shown above.

We can directly change the topology used for the Sim's Universe with ::

>>> s.universedef.topology = 'path/to/another/topology.psf'

then we get back a Universe built with this topology instead::

>>> s.universe.filename
'/home/bob/research/path/to/another/topology.psf'

We can also change the trajectory::

>>> s.universedef.trajectory = 'path/to/another/trajectory.dcd'

which re-initializes the Universe with both the defined topology and trajectory::

>>> s.universe.trajectory
<DCDReader /home/bob/research/path/to/trajectory.dcd with 98 frames of 3341 atoms>
<DCDReader /home/bob/research/path/to/another/trajectory.dcd with 98 frames of 3341 atoms>

We can also define our Universe as having multiple trajectories by giving a
list of filepaths instead. Internally, the Universe generated will use the
MDAnalysis :class:`~MDAnalysis.coordinates.base.ChainReader` for treating the
trajectories as a contiguous whole.

The Universe definition is persistent, so we can get back an identical Universe
later from another Python session with our Sim::

>>> import mdsynthesis as mds
>>> s = mds.Sim('adk')
>>> s.universe
<Universe with 3341 atoms and 3365 bonds>

.. note:: Changing the topology or trajectory definition will reload the
Universe automatically. This means that any AtomGroups you are
working with will not point to the new Universe, but perhaps the old
Expand All @@ -89,14 +104,14 @@ If the Universe needed requires keyword arguments on initialization, these can
be stored as well. For example, if our topology was a PDB file and we wanted
bonds to be guessed upfront, we could make this happen every time::

>>> s.udef.kwargs = {'guess_bonds': True}
>>> s.universedef.kwargs = {'guess_bonds': True}

Reinitializing the Universe
---------------------------
If you make modifications to the Universe but you want to restore the original
from its definition, you can force it to reload with::

>>> s.udef.reload()
>>> s.universedef.reload()

API Reference: UniverseDefinition
---------------------------------
Expand All @@ -120,14 +135,15 @@ kinase, the protein we simulated. We can store these immediately::

>>> s.atomselections['lid'] = 'resid 122:159'
>>> s.atomselections['nmp'] = 'resid 30:59'
>>> s.atomselections['core'] = ['resid 1:29', 'resid 60:121', 'resid 160:214']
>>> s.atomselections['core'] = ('resid 1:29', 'resid 60:121', 'resid 160:214')

We can now get new AtomGroups back for each selection at any time ::
We can now get new AtomGroups back for each selection at any time with the
:meth:`~mdsynthesis.limbs.AtomSelections.create` method::

>>> s.atomselections['lid']
>>> s.atomselections.create('lid')
<AtomGroup with 598 atoms>
>>> s.atomselections['core']
>>> s.atomselections.create('core')
<AtomGroup with 2306 atoms>

and we don't have to remember or know how 'lid' or 'core' are defined for this
Expand All @@ -145,24 +161,29 @@ work with many variants of a simulation system without having to micromanage.
alignments.

Want just the selection strings back? We can use
:meth:`~mdsynthesis.limbs.AtomSelections.define`::
:meth:`~mdsynthesis.limbs.AtomSelections.get`::

>>> s.atomselections.define('lid')
['resid 122:159']
>>> s.atomselections.get('lid')
'resid 122:159'

Note that selections are always stored as lists, even if only a single
selection string was given.
# or using getitem syntax
>>> s.atomselections['lid']
'resid 122:159'

Atom selections from atom indices
---------------------------------
Do you already have an AtomGroup and prefer to define it according to its atom
indices instead of as a selection string? That can be done, too::

>>> lid = s.universe.select_atoms('resid 122:159')
>>> s.atomselections['lid'] = lid
>>> s.atomselections['lid']
>>> s.atomselections['lid'] = lid.indices
>>> s.atomselections.create('lid')
<AtomGroup with 598 atoms>

Lists/tuples of selection strings or atom indices can be stored in any combination
as a selection. These are applied in order to yield the AtomGroup when calling the
:meth:`~mdsynthesis.limbs.AtomSelections.create` method.

API Reference: AtomSelections
-----------------------------
See the :ref:`AtomSelections_api` API reference for more details.
Expand Down
Loading

0 comments on commit 7946d1b

Please sign in to comment.