Trajectories¶
When running molecular simulations, the trajectory of the system is commonly saved to the disk in prevision of future analysis or new simulations run. The Trajectories module offers facilities to read and write this files.
Reading and writing trajectories¶
One can read or write frames from a trajectory. In order to do so, more information is needed : namely an unit cell and a topology. Both are optional, but allow for better computations. Some file formats already contain this kind of informations so there is no need to provide it.
Trajectories can exist in differents formats: text formats like the XYZ format, or binary formats. In Jumos, the format of a trajectory file is automatically determined based on the file extension.
Base types¶
The two basic types for reading and writing trajectories in files are respectively
the Reader
and the Writer
parametrised types. For each specific format,
there is a FormatWriter
and/or FormatReader
subtype implementing
the basic operations.
Usage¶
The following functions are defined for the interactions with trajectory files.
-
opentraj
(filename[, mode="r", topology="", kwargs...])¶ Opens a trajectory file for reading or writing. The
filename
extension determines the format of the trajectory.The
mode
argument can be"r"
for reading or"w"
for writing.The
topology
argument can be the path to a Topology file, if you want to use atomic names with trajectories files in which there is no topological informations.All the keyword arguments
kwargs
are passed to the specific constructors.
-
Reader
(filename[, kwargs...])¶ Creates a
Reader
object, by passing the keywords argumentskwargs
to the specific constructor. This is equivalent to use the opentraj function with"r"
mode.
-
Writer
(filename[, kwargs...])¶ Creates a
Writer
object, by passing the keywords argumentskwargs
to the specific constructor. This is equivalent to use the opentraj function with"w"
mode.
-
eachframe
(::Reader [range::Range, start=first_step])¶ This function creates an [interator] interface to a
Reader
, allowing for constructions likefor frame in eachframe(reader)
.
-
read_next_frame!
(::Reader, frame)¶ Reads the next frame from
Reader
, and stores it intoframe
. Raises an error in case of failure, and returnstrue
if there are other frames to read,false
otherwise.This function can be used in constructions such as
while read_next_frame!(traj)
.
-
read_frame!
(::Reader, step, frame)¶ Reads a frame at the step
step
from theReader
, and stores it intoframe
. Raises an error in the case of failure and returnstrue
if there is a frame after the stepstep
,false
otherwise.
-
close
(trajectory_file)¶ Closes the file associated with a
Reader
or aWriter
.
Reading frames from a file¶
Here is an example of how you can read frames from a file. In the Reader
constructor, the cell
keyword argument will be used to construct an
UnitCell.
traj_reader = Reader("filename.xyz", cell=[10., 10., 10.])
for frame in eachframe(traj_reader)
# Do stuff here
end
close(traj_reader)
Writing frames in a file¶
Here is an example of how you can write frames to a file. This example converts a
trajectory from a file format to another. The topology
keyword is used to
read a Topology from a file.
traj_reader = Reader("filename-in.nc", topology="topology.xyz")
traj_writer = Writer("filename-out.xyz")
for frame in eachframe(traj_reader)
write(traj_writer, frame)
end
close(traj_writer)
close(traj_reader)
Supported formats¶
The following table summarizes the formats supported by Jumos, giving the reading and writing capacities of Jumos, as well as the presence or absence of the unit cell and the topology information in the files. The last column indicates the accepted keywords.
Format | Extension | Read | Write | Cell | Topology | Keywords |
---|---|---|---|---|---|---|
XYZ | .xyz |
cell | ||||
Amber NetCDF | .nc |
topology |
Readind and writing topologies¶
Topologies can also be represented and stored in files. Some functions allow to read directly these files, but there is usally no need to use them directely.