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¶
-
-
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., notFmt.AUTO
), this function will trivially return the value offormat
, otherwise it will check thefname
’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 trajectoryfname
- 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
-
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 ofFrame
objects) in memory.Duck typing for ``readers’‘. - Random access
reader[index]
should return theindex
-th frame. Hereindex
is zero-based, of Python style (i.e., -1 means the last frame, etc.).len
supportlen(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 requirements. See
DtrSource
below as an example.
-
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
ifindex
is out of range, orIOError
if the trajectory reader is closed.
-
clear_cache
()¶
-
used_space
()¶
-
nframes
()¶ Returns the total number of frames in this trajectory source.
-
close
()¶ Closes down the trajectory reader. A couple of points to note: 1. Once this method is called, this
Source
object can only retrieveframes that are internally cached. Attempting to retrieve uncached frames will incur anIOError
. Normally we do NOT know which frames are cached, so to be safe this method should be called only when we are done with the trajectory.
-
-
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¶
-
__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 ofFrame
objects) in memory.Duck typing for ``readers’‘. - Random access
reader[index]
should return theindex
-th frame. Hereindex
is zero-based, of Python style (i.e., -1 means the last frame, etc.).len
supportlen(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 requirements. See
DtrSource
below as an example.
-
clear_cache
()¶
-
close
()¶ Closes down the trajectory reader. A couple of points to note: 1. Once this method is called, this
Source
object can only retrieveframes that are internally cached. Attempting to retrieve uncached frames will incur anIOError
. Normally we do NOT know which frames are cached, so to be safe this method should be called only when we are done with the trajectory.
-
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
ifindex
is out of range, orIOError
if the trajectory reader is closed.
-
used_space
()¶
-
-
class
schrodinger.application.desmond.packages.traj.
XtcSource
(*args, **kwargs)¶ Bases:
schrodinger.application.desmond.packages.traj.Source
-
__init__
(*args, **kwargs)¶ 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 ofFrame
objects) in memory.Duck typing for ``readers’‘. - Random access
reader[index]
should return theindex
-th frame. Hereindex
is zero-based, of Python style (i.e., -1 means the last frame, etc.).len
supportlen(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 requirements. See
DtrSource
below as an example.
-
nframes
()¶ Returns the total number of frames in this trajectory source.
-
CACHE_LIMIT_BYTES
= 1000000000.0¶
-
clear_cache
()¶
-
close
()¶ Closes down the trajectory reader. A couple of points to note: 1. Once this method is called, this
Source
object can only retrieveframes that are internally cached. Attempting to retrieve uncached frames will incur anIOError
. Normally we do NOT know which frames are cached, so to be safe this method should be called only when we are done with the trajectory.
-
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
ifindex
is out of range, orIOError
if the trajectory reader is closed.
-
used_space
()¶
-
-
class
schrodinger.application.desmond.packages.traj.
Frame
(source: Optional[schrodinger.application.desmond.packages.traj.Source], index: Optional[int])¶ 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: Optional[schrodinger.application.desmond.packages.traj.Source], index: Optional[int])¶ Parameters:
-
source
()¶
-
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 arrayimpos
. We can call the external array “imposter”. After calling this method, thepos
method will return values from the imposter until the imposter is removed (by callinghijackPos(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 Useimpos
. - copy The entireimpos
array will be copied into the copy ofthisFrame
object.- reduce Still function in the same way, but note that the
impos
- array will not be changed by these methods.
- reduce Still function in the same way, but note that the
- 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
, ornumpy.ndarray
of size Nx3, where N is arbitray number) – The position array to tentatively replac the internal position array in thisFrame
object. If the value isNone
, 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 theindices
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
, andz
.
-
write
(writer)¶ Write out this frame using the given
writer
.
-
-
schrodinger.application.desmond.packages.traj.
read_traj
(inp, format=<Fmt.AUTO: 0>, return_iter=False)¶ Lazy load trajectory.
Parameters:
-
schrodinger.application.desmond.packages.traj.
write_traj
(tr, fname, format=<Fmt.AUTO: 0>)¶ Parameters: - fname (
str
) – Output file name - format (
Fmt
) – Trajectory file format
- fname (
-
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
- first_time (
-
schrodinger.application.desmond.packages.traj.
extract_subsystem
(tr, gids)¶ Extract the subsystem as specified by the
gids
for each frame in the given trajectorytr
, and return a new trajectory for the subsystem. The original trajectory is not mutated in any way by this function.Parameters: Return type: list
Returns: A new trajectory for the subsystem