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. Selections are stored separately for each defined universe, since the same selection may require a different selection string for different universes.

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:
  • depth (int) – Maximum directory depth to display. None indicates no limit.
  • hidden (bool) – If False, do not show hidden files; hidden directories are still shown if they contain non-hidden files or directories.
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

hidden

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.

tags

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 to None 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.

remove(*handle)

Remove an atom selection for the universe.

If named selection doesn’t exist, KeyError raised.

Parameters:handle (str) – Name of selection(s) to remove.