Collections

The collections submodule provides models that describe series of states.

Trajectory

Description

The Trajectory model describes trajectories in classical molecular dynamics. Model creation occurs with a kwargs constructor as shown by equivalent operations below:

>>> traj = mmelemental.models.Trajectory(
        natoms = 1,
        nframes = 3,
        timestep = 1.0,
        timestep_units = "femtoseconds",
        geometry = [2.0, 2.09, 0.0, 2.82, 2.09, 0.58, 1.18, 2.09, 0.58],
        geometry_units = "angstrom"
    )
>>> traj
 Trajectory(name=None, hash='da39a3e')

In addition, Trajectory provides from_data() and from_file() methods to create a trajectory from data (e.g. MDAnalysis.Universe) or file objects. The methods to_data() and to_file() enable converting a trajectory to data and file objects, respectively. See the API for more details. See the Trajectory tutorials for more in-depth examples.

API

class mmelemental.models.collect.trajectory.Trajectory(**data)[source]

Representation of trajectories in classical mechanics. By default, this model loads a single frame in memory.

Parameters

schema_name (ConstrainedStrValue, Default: mmschema_trajectory) – The MMSchema specification to which this model conforms. Explicitly fixed as mmschema_trajectory.
schema_version (int, Default: 1) – The version number of schema_name to which this model conforms.
name (str, Optional) – Common or human-readable name to assign to this molecule. This field can be arbitrary; see identifiers for well-defined labels.
timestep (Union[Array, float]) – Timestep size. Default unit is femtoseconds.
timestep_units (str, Default: fs) – Timestep size units. Defaults to femtoseconds.
natoms (Union[int, Array]) – Number of atoms. A scalar for closed systems and an array for open (variable N) systems.
nframes (int) – Number of frames.
ndim (int, Default: 3) – Number of spatial dimensions.
top (Union[Topology, Topology], Optional) –

A topological representation of a Molecule in MM. In addition to connectivity, this model contains data for particle
symbols/labels, masses, and net charge. Useful for creating :class:Trajectory objects.
geometry (Array, Optional) – An ordered (natom*ndim*nframes,) array for XYZ atomic coordinates. Default unit is Angstrom. Storage is sequential in each dimension: [ x1o,…,xno, y1o,…,yno, z1o,…,zno, …, x1f,…,xnf, y1f,…,ynf, z1f,…,znf, ]
geometry_units (str, Default: angstrom) – Units for atomic geometry. Defaults to Angstroms.
velocities (Array, Optional) – An ordered (natoms*ndim*nframes,) array for XYZ atomic velocities. Default unit is Angstroms/femtoseconds.Storage is sequential in each dimension: [ x1o,…,xno, y1o,…,yno, z1o,…,zno, …, x1f,…,xnf, y1f,…,ynf, z1f,…,znf, ]
velocities_units (str, Default: angstrom/fs) – Units for atomic velocities. Defaults to Angstroms/femtoseconds.
forces (Array, Optional) – An ordered (natoms*ndim*nframes,) array for XYZ atomic forces. Default unit is kJ/mol*angstrom.Storage is sequential in each dimension: [ x1o,…,xno, y1o,…,yno, z1o,…,zno, …, x1f,…,xnf, y1f,…,ynf, z1f,…,znf, ]
forces_units (str, Default: kJ/(mol*angstrom)) – Units for atomic forces. Defaults to kJ/mol*angstrom.
provenance (Provenance, Default: {‘creator’: ‘MMElemental’, ‘version’: ‘v0.1.1’, ‘routine’: ‘mmelemental.models.collect.trajectory’}) – The provenance information about how this object (and its attributes) were generated, provided, and manipulated.
extras (Dict[Any], Optional) – Additional information to bundle with this object. Use for schema development and scratch space.

Return type

None

classmethod from_data(data, dtype=None, **kwargs)[source]

Constructs a Trajectory object from a data object.

Parameters

data (Any) – Data to construct Molecule from
dtype (str, optional) – How to interpret the data. If not set, mmelemental attempts to discover this based on input type. Possible values: mdanalysis, mdraj, pytraj
**kwargs (Dict[str, Any]) – Additional kwargs to pass to the constructors. kwargs take precedence over data.
kwargs (Dict[str, Any]) –

Returns

A constructed Trajectory class.

Return type

Trajectory

classmethod from_file(traj_filename, top_filename=None, dtype=None, *, translator=None, all_frames=False, **kwargs)[source]

Constructs a Trajectory object from an input file.

Parameters

traj_filename (str) – The atomic positions filename to read
top_filename (str, optional) – The topology i.e. connectivity filename to read
dtype (str, optional) – The type of file to interpret. If not set, mmelemental attempts to discover the file type.
translator (Optional[str], optional) – Translator name e.g. mmic_rdkit. Takes precedence over dtype. If unset, MMElemental attempts to find an appropriate translator if it is registered in the TransComponent class.
all_frames (bool, optional) – Reads all frames in memory.
**kwargs (Dict[str, Any], optional) – Additional kwargs to pass to the constructors.

Returns

A constructed Trajectory class.

Return type

Trajectory

get_geometry(frame)[source]

Returns geometry at a specific snapshot/frame.

Parameters: frame (int) – Frame number ranges from 0 … nframes-1
Returns: Geometry 1D numpy array of length natoms * ndim
Return type: Array[float]

get_hash()[source]: Returns the hash of a single frame in a trajectory.

to_data(dtype=None, *, translator=None, **kwargs)[source]

Converts Molecule to toolkit-specific molecule (e.g. rdkit, MDAnalysis, parmed).

Parameters

dtype (str, optional) – The type of data object to convert to e.g. mdanalysis, rdkit, parmed, etc.
translator (Optional[str], optional) – Translator name e.g. mmic_rdkit. Takes precedence over dtype. If unset, MMElemental attempts to find an appropriate translator if it is registered in the TransComponent class.
**kwargs (Optional[Dict[str, Any]], optional) – Additional kwargs to pass to the constructor.
kwargs (Optional[Dict[str, Any]]) –

Returns

Toolkit-specific molecule model

Return type

ToolkitModel

to_file(filename, dtype=None, *, translator=None, **kwargs)[source]

Writes the Trajectory to a file.

Parameters

filename (str) – The filename to write to
dtype (str, optional) – The type of file to write, attempts to infer dtype from the filename if not provided.
translator (Optional[str], optional) – Translator name e.g. mmic_rdkit. Takes precedence over dtype. If unset, MMElemental attempts to find an appropriate translator if it is registered in the TransComponent class.
**kwargs (Optional[Dict[str, Any]], optional) – Additional kwargs to pass to the constructor.
kwargs (Optional[Dict[str, Any]]) –

Return type

None