Individual simulations¶
The Sim is the core unit of functionality of mdsynthesis
. They function as
markers for simulation data, giving an interface to raw topologies and
trajectories by way of MDAnalysis.
The components documented here are those included within mdsynthesis
.
However, the API elements of :mod:datreant.core and :mod:datreant.data
are also available for use with Sims.
Sim¶
The class mdsynthesis.Sim
is the central object of mdsynthesis
.
-
class
mdsynthesis.
Sim
(sim, new=False, categories=None, tags=None)¶ The Sim object is an interface to data for a single simulation.
sim should be a base directory of a new or existing Sim. An existing Sim will be regenerated if a state file is found. If no state file is found, a new Sim will be created.
A Tree object may also be used in the same way as a directory string.
If multiple Treant state files are in the given directory, a
MultipleTreantsError
will be raised; specify the full path to the desired state file to regenerate the desired Treant in this case. It is generally better to avoid having multiple state files in the same directory.Use the new keyword to force generation of a new Sim at the given path.
Parameters: - sim (str or Tree) – Base directory of a new or existing Sim; will regenerate a Sim if a state file is found, but will genereate a new one otherwise; may also be a Tree object
- new (bool) – Generate a new Sim even if one already exists at the given location
- categories (dict) – dictionary with user-defined keys and values; used to give Sims distinguishing characteristics
- tags (list) – list with user-defined values; like categories, but useful for adding many distinguishing descriptors
-
abspath
¶ Absolute path of
self.path
.
-
atomselections
¶ Stored atom selections for the universe.
Useful atom selections can be stored for the universe and recalled later.
-
attach
(*limbname)¶ Attach limbs by name to this Treant.
-
categories
¶ Interface to categories.
-
children
¶ A View of all files and directories in this Tree.
Includes hidden files and directories.
-
data
¶ Interface to stored data.
-
discover
(dirpath='.', depth=None, treantdepth=None)¶ Find all Treants within given directory, recursively.
Parameters: - dirpath (string, Tree) – Directory within which to search for Treants. May also be an existing Tree.
- depth (int) – Maximum directory depth to tolerate while traversing in search of
Treants.
None
indicates no depth limit. - treantdepth (int) – Maximum depth of Treants to tolerate while traversing in search
of Treants.
None
indicates no Treant depth limit.
Returns: found – Bundle of found Treants.
Return type: Bundle
-
draw
(depth=None, hidden=False)¶ Print an ASCII-fied visual of the tree.
Parameters:
-
exists
¶ Check existence of this path in filesystem.
-
filepath
¶ Absolute path to the Treant’s state file.
-
glob
(pattern)¶ Return a View of all child Leaves and Trees matching given globbing pattern.
Arguments: - pattern
globbing pattern to match files and directories with
A View of the hidden files and directories in this Tree.
-
leaves
¶ A View of the files in this Tree.
Hidden files are not included.
-
limbs
¶ A set giving the names of this Tree’s attached limbs.
-
location
¶ The location of the Treant.
Setting the location to a new path physically moves the Treant to the given location. This only works if the new location is an empty or nonexistent directory.
-
make
()¶ Make the directory if it doesn’t exist. Equivalent to
makedirs()
.Returns: This Tree. Return type: Tree
-
makedirs
()¶ Make all directories along path that do not currently exist.
Returns: - tree
this tree
-
name
¶ The name of the Treant.
The name of a Treant need not be unique with respect to other Treants, but is used as part of Treant’s displayed representation.
-
parent
¶ Parent directory for this path.
-
path
¶ Treant directory as a
pathlib.Path
.
-
relpath
¶ Relative path of
self.path
from current working directory.
Interface to tags.
-
treants
¶ Bundle of all Treants found within this Tree.
This does not return a Treant for a bare state file found within this Tree. In effect this gives the same result as
Bundle(self.trees)
.
-
treanttype
¶ The type of the Treant.
-
tree
¶ This Treant’s directory as a Tree.
-
trees
¶ A View of the directories in this Tree.
Hidden directories are not included.
-
universe
¶ The universe of the Sim.
Universes are interfaces to raw simulation data, with stored selections for this universe directly available via
Sim.selections
.Setting this to a
MDAnalysis.Universe
will set that as the universe definition for this Sim. Setting toNone
will remove the universe definition entirely.
-
universedef
¶ The universe definition for this Sim.
-
uuid
¶ Get Treant uuid.
A Treant’s uuid is used by other Treants to identify it. The uuid is given in the Treant’s state file name for fast filesystem searching. For example, a Treant with state file:
'Treant.7dd9305a-d7d9-4a7b-b513-adf5f4205e09.h5'
has uuid:
'7dd9305a-d7d9-4a7b-b513-adf5f4205e09'
Changing this string will alter the Treant’s uuid. This is not generally recommended.
Returns: - uuid
unique identifier string for this Treant
UniverseDefinition¶
The class mdsynthesis.limbs.UniverseDefinition
is the interface used by a Sim to
define its MDAnalysis.Universe
.
-
class
mdsynthesis.limbs.
UniverseDefinition
(treant)¶ The defined universe of the Sim.
Universes are interfaces to raw simulation data, with stored selections for this universe directly available via
Sim.atomselections
.-
kwargs
¶ The keyword arguments applied to the Sim’s universe when building it.
Set these with a dictionary of keywords and values to change them. Keywords must be strings and values must be strings, ints, floats, bools, or
None
.
-
reload
()¶ Re-load the universe from its stored definition.
-
topology
¶ The topology file for this Sim’s universe.
To change the topology file for this Sim’s universe, set the path to the file. Setting to
None
will disable the Sim’s universe, but the trajectory paths will be retained.
-
trajectory
¶ The trajectory file for this Sim’s universe.
To change the trajectory file(s) for this Sim’s Universe, set the path to the file. A single path will use a single trajectory file, while a list or tuple of paths will use each trajectory file in order for building the universe.
None
indicates that the Universe will not load a trajectory file at all (but the topology may have coordinates).
-
AtomSelections¶
The class mdsynthesis.limbs.AtomSelections
is the interface used by Sims to
get MDAnalysis.AtomGroup
objects from stored selection definitions.
-
class
mdsynthesis.limbs.
AtomSelections
(treant)¶ Stored atom selections for the universe.
Useful atom selections can be stored for the universe and recalled later.
-
add
(handle, *selection)¶ Add an atom selection for the attached universe.
AtomGroups are needed to obtain useful information from raw coordinate data. It is useful to store AtomGroup selections for later use, since they can be complex and atom order may matter.
If a selection with the given handle already exists, it is replaced.
Parameters: - handle (str) – Name to use for the selection.
- selection (str, AtomGroup) – Selection string or AtomGroup indices; multiple selections may be given and their order will be preserved, which is useful for e.g. structural alignments.
-
create
(handle)¶ Generate AtomGroup from universe from the given named selection.
If named selection doesn’t exist,
KeyError
raised.Parameters: handle (str) – Name of selection to return as an AtomGroup. Returns: The named selection as an AtomGroup of the universe. Return type: AtomGroup
-
get
(handle)¶ Get selection definition for given handle.
If named selection doesn’t exist,
KeyError
raised.Parameters: handle (str) – Name of selection to get definition of. Returns: definition – list of strings defining the atom selection Return type: list
-
keys
()¶ Return a list of all selection handles.
-