schrodinger.application.desmond.packages.traj module

Molecular dynamics trajectory handling module Define common APIs for various trajectory formats. Basic trajectory handling algorithms are also implemented here.

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.desmond.packages.traj.Fmt

Bases: enum.Enum

Trajectory format enum

AUTO = 0
DTR = 1
XTC = 2
__class__

alias of enum.EnumMeta

__members__ = mappingproxy(OrderedDict([('AUTO', <Fmt.AUTO: 0>), ('DTR', <Fmt.DTR: 1>), ('XTC', <Fmt.XTC: 2>)]))
__module__ = 'schrodinger.application.desmond.packages.traj'
schrodinger.application.desmond.packages.traj.get_fmt(fname, format=<Fmt.AUTO: 0>)

Returns the format based on the given trajectory file name (fname) and the format specification (format). If the format specification is definite (i.e., not Fmt.AUTO), this function will trivially return the value of format, otherwise it will check the fname’s value, determining the format, and return the result.

Parameters:
  • fname (str) – Trajectory file name
  • format (Fmt) – Trajectory format specification

:rtype : Fmt :return: The format of the given trajectory fname

schrodinger.application.desmond.packages.traj.get_trajectory_extname(format=<Fmt.AUTO: 0>, ref_fname=None)
class schrodinger.application.desmond.packages.traj.Source(reader, name='sometraj')

Bases: object

Pool = {}
CACHE_LIMIT_BYTES = 1000000000.0
__init__(reader, name='sometraj')

reader specifies where to retrieve a trajectory frame when it’s needed but currently NOT in the memory (in other words, it’s not cached by this source). A reader could potentially be a file reader, a string reader, a socket reader, a database dealer, etc., as long as it satisfies the duck-typing requirements (see below). And interestingly, the probably simplest reader is another ``trajectory’’ (i.e., a list of Frame objects) in memory.

Duck typing for ``readers’‘. - Random access

reader[index] should return the index-th frame. Here index is zero-based, of Python style (i.e., -1 means the last frame, etc.).
  • len support len(reader) should return the total number of frames.

If a reader doesn’t support the duck typing as specified above, a subclass can be created to bypass the typing issue. See DtrSource below as an example.

__str__()

Return str(self).

name
id
retrieve_frame(index)

Retrieves the index-th frame from the source. index is zero-based. This method assumes the source allows random access to frames.

:raise IndexError, if index is out of range.

clear_cache()
used_space()
nframes()

Returns the total number of frames in this trajectory source.

__class__

alias of builtins.type

__delattr__

Implement delattr(self, name).

__dict__ = mappingproxy({'__module__': 'schrodinger.application.desmond.packages.traj', 'Pool': {}, 'CACHE_LIMIT_BYTES': 1000000000.0, '__init__': <function Source.__init__>, '__str__': <function Source.__str__>, 'name': <property object>, 'id': <property object>, '_retrieve_frame': <function Source._retrieve_frame>, 'retrieve_frame': <function Source.retrieve_frame>, '_limit_cache': <function Source._limit_cache>, 'clear_cache': <function Source.clear_cache>, 'used_space': <function Source.used_space>, 'nframes': <function Source.nframes>, '__dict__': <attribute '__dict__' of 'Source' objects>, '__weakref__': <attribute '__weakref__' of 'Source' objects>, '__doc__': None})
__dir__() → list

default dir() implementation

__eq__

Return self==value.

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__

Return hash(self).

__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__

Return self<=value.

__lt__

Return self<value.

__module__ = 'schrodinger.application.desmond.packages.traj'
__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__

Return repr(self).

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object (if defined)

class schrodinger.application.desmond.packages.traj.DtrSource(reader, name='sometraj')

Bases: schrodinger.application.desmond.packages.traj.Source

nframes()

Returns the total number of frames in this trajectory source.

CACHE_LIMIT_BYTES = 1000000000.0
Pool = {}
__class__

alias of builtins.type

__delattr__

Implement delattr(self, name).

__dict__ = mappingproxy({'__module__': 'schrodinger.application.desmond.packages.traj', '_retrieve_frame': <function DtrSource._retrieve_frame>, 'nframes': <function DtrSource.nframes>, '__doc__': None})
__dir__() → list

default dir() implementation

__eq__

Return self==value.

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__

Return hash(self).

__init__(reader, name='sometraj')

reader specifies where to retrieve a trajectory frame when it’s needed but currently NOT in the memory (in other words, it’s not cached by this source). A reader could potentially be a file reader, a string reader, a socket reader, a database dealer, etc., as long as it satisfies the duck-typing requirements (see below). And interestingly, the probably simplest reader is another ``trajectory’’ (i.e., a list of Frame objects) in memory.

Duck typing for ``readers’‘. - Random access

reader[index] should return the index-th frame. Here index is zero-based, of Python style (i.e., -1 means the last frame, etc.).
  • len support len(reader) should return the total number of frames.

If a reader doesn’t support the duck typing as specified above, a subclass can be created to bypass the typing issue. See DtrSource below as an example.

__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__

Return self<=value.

__lt__

Return self<value.

__module__ = 'schrodinger.application.desmond.packages.traj'
__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__

Return repr(self).

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__()

Return str(self).

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object (if defined)

clear_cache()
id
name
retrieve_frame(index)

Retrieves the index-th frame from the source. index is zero-based. This method assumes the source allows random access to frames.

:raise IndexError, if index is out of range.

used_space()
class schrodinger.application.desmond.packages.traj.XtcSource(reader, name='sometraj')

Bases: schrodinger.application.desmond.packages.traj.Source

nframes()

Returns the total number of frames in this trajectory source.

used_space()
CACHE_LIMIT_BYTES = 1000000000.0
Pool = {}
__class__

alias of builtins.type

__delattr__

Implement delattr(self, name).

__dict__ = mappingproxy({'__module__': 'schrodinger.application.desmond.packages.traj', '_recache': <function XtcSource._recache>, '_retrieve_frame': <function XtcSource._retrieve_frame>, 'nframes': <function XtcSource.nframes>, '_limit_cache': <function XtcSource._limit_cache>, 'used_space': <function XtcSource.used_space>, '__doc__': None})
__dir__() → list

default dir() implementation

__eq__

Return self==value.

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__

Return hash(self).

__init__(reader, name='sometraj')

reader specifies where to retrieve a trajectory frame when it’s needed but currently NOT in the memory (in other words, it’s not cached by this source). A reader could potentially be a file reader, a string reader, a socket reader, a database dealer, etc., as long as it satisfies the duck-typing requirements (see below). And interestingly, the probably simplest reader is another ``trajectory’’ (i.e., a list of Frame objects) in memory.

Duck typing for ``readers’‘. - Random access

reader[index] should return the index-th frame. Here index is zero-based, of Python style (i.e., -1 means the last frame, etc.).
  • len support len(reader) should return the total number of frames.

If a reader doesn’t support the duck typing as specified above, a subclass can be created to bypass the typing issue. See DtrSource below as an example.

__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__

Return self<=value.

__lt__

Return self<value.

__module__ = 'schrodinger.application.desmond.packages.traj'
__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__

Return repr(self).

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__()

Return str(self).

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object (if defined)

clear_cache()
id
name
retrieve_frame(index)

Retrieves the index-th frame from the source. index is zero-based. This method assumes the source allows random access to frames.

:raise IndexError, if index is out of range.

class schrodinger.application.desmond.packages.traj.Frame(source, index)

Bases: object

This class, as its name suggests, represents a single trajectory frame. So far, we allow a frame to be mutated in the following ways: - Assign a new chemical time - Reduce to a subset of particles - Coordinates of all particles are translated

We call changes generally as ``decorations’‘. They might not make into the frame data, or at least not immediately. Why? This avoids making multiple expensive copies of the data.

__init__(source, index)

Initialize self. See help(type(self)) for accurate signature.

__str__()

Return str(self).

__deepcopy__(memo={})
source()
copy()

Return a copy of this Frame object. The position and velocity arrays will be copied.

natoms
nactive
pos(i=None)

Return the position vector(s).

vel(i=None)

Return the velocity vector(s). This method may throw if this frame doesn’t have velocity data.

hijackPos(impos)

Tentatively replace the internal position array of this Frame object with an external numpy array impos. We can call the external array “imposter”. After calling this method, the pos method will return values from the imposter until the imposter is removed (by calling hijackPos(None)). The imposter should be a Nx3 numpy array, where N can be of any size. Note the impacts on other methods of this class: - pos Use impos. - copy The entire impos array will be copied into the copy of

this Frame object.
  • reduce Still function in the same way, but note that the impos
    array will not be changed by these methods.
  • moveby The same as reduce
  • write Still function in the same way, note that it’s the internal
    position array, not impos, that will be written out.
Parameters:impos (None, or numpy.ndarray of size Nx3, where N is arbitray number) – The position array to tentatively replac the internal position array in this Frame object. If the value is None, we remove the “imposter” and recover the internal position array.
time
box
transpose_box()

Transpose the simulation box.

orig_index
reduce(indices, copy=True)

Keep only the atoms specified by indices, the other atoms will be deleted from this frame. The caller needs to ensure the indices order matches with the msys model of the reduced system.

Parameters:copy – If true, this function will make a copy of this frame and reduce atoms in this copy, and finally return the copy.
moveby(x, y, z)

Translate all positions by the given x, y, and z.

write(writer)

Write out this frame using the given writer.

__class__

alias of builtins.type

__delattr__

Implement delattr(self, name).

__dict__ = mappingproxy({'__module__': 'schrodinger.application.desmond.packages.traj', '__doc__': "\n This class, as its name suggests, represents a single trajectory frame.\n So far, we allow a frame to be mutated in the following ways:\n - Assign a new chemical time\n - Reduce to a subset of particles\n - Coordinates of all particles are translated\n\n We call changes generally as ``decorations''. They might not make into\n the frame data, or at least not immediately. Why? This avoids making\n multiple expensive copies of the data.\n ", '__init__': <function Frame.__init__>, '__str__': <function Frame.__str__>, '__deepcopy__': <function Frame.__deepcopy__>, '_frame': <function Frame._frame>, '_mapped_index': <function Frame._mapped_index>, '_copy_and_decorate': <function Frame._copy_and_decorate>, '_get_native_object': <function Frame._get_native_object>, '_make': <function Frame._make>, 'source': <function Frame.source>, 'copy': <function Frame.copy>, 'natoms': <property object>, 'nactive': <property object>, 'pos': <function Frame.pos>, 'vel': <function Frame.vel>, 'hijackPos': <function Frame.hijackPos>, '_getTime': <function Frame._getTime>, '_setTime': <function Frame._setTime>, 'time': <property object>, 'box': <property object>, 'transpose_box': <function Frame.transpose_box>, 'orig_index': <property object>, 'reduce': <function Frame.reduce>, 'moveby': <function Frame.moveby>, 'write': <function Frame.write>, '__dict__': <attribute '__dict__' of 'Frame' objects>, '__weakref__': <attribute '__weakref__' of 'Frame' objects>})
__dir__() → list

default dir() implementation

__eq__

Return self==value.

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__

Return hash(self).

__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__

Return self<=value.

__lt__

Return self<value.

__module__ = 'schrodinger.application.desmond.packages.traj'
__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__

Return repr(self).

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object (if defined)

schrodinger.application.desmond.packages.traj.read_traj(inp, format=<Fmt.AUTO: 0>, return_iter=False)

Lazy load trajectory.

Parameters:
  • inp (str) – Input trajectory’s file name
  • format (Fmt) – Trajectory file format
  • return_iter – If True, return an iterator, otherwise return a list of `Frame`s.
schrodinger.application.desmond.packages.traj.write_traj(tr, fname, format=<Fmt.AUTO: 0>)
Parameters:
  • fname (str) – Output file name
  • format (Fmt) – Trajectory file format
schrodinger.application.desmond.packages.traj.merge(*arg)

Merge a list of trajectories. If there is any overlapped frames among these trajectories, the ones from the latter trajectory (higher index in the arg list) will be kept.

schrodinger.application.desmond.packages.traj.concat(first_time, delta_time, *args)

Concatenate a list of trajectories or iterators and reassign the chemical time for each frame. Results are yielded.

Parameters:
  • first_time (float) – Chemical time of the first frame.
  • delta_time (float) – The chemical time interval between two successive frames.
  • args – trajectories as iterables
schrodinger.application.desmond.packages.traj.extract_subsystem(tr, gids)

Extract the subsystem as specified by the gids for each frame in the given trajectory tr, and return a new trajectory for the subsystem. The original trajectory is not mutated in any way by this function.

Parameters:
  • tr (list of Frame) – Original trajectory
  • gids (list of `int`s) – A list of gids that specifies the subsystem.
Return type:

list
Returns:

A new trajectory for the subsystem