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.
One can read or write frames <type-Frame>
from a trajectory. In order to do so, more information is needed : namely an unit cell <type-UnitCell>
and a topology <type-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 , the format of a trajectory file is automatically determined based on the file extension.
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.
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 <trajectory-formats>
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 <type-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 arguments kwargs
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 arguments kwargs
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 like for frame in eachframe(reader)
.
read_next_frame!(::Reader, frame)
Reads the next frame from Reader
, and stores it into frame
. Raises an error in case of failure, and returns true
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 the Reader
, and stores it into frame
. Raises an error in the case of failure and returns true
if there is a frame after the step step
, false
otherwise.
write(::Writer, frame)
Writes the Frame <type-Frame>
frame
to the file associated with the Writer
.
close(trajectory_file)
Closes the file associated with a Reader
or a Writer
.
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 <type-UnitCell>
.
traj_reader = Reader("filename.xyz", cell=[10., 10., 10.])
for frame in eachframe(traj_reader)
# Do stuff here
end
close(traj_reader)
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 <type-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)
The following table summarizes the formats supported by , giving the reading and writing capacities of , 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 |
|
||||
Amber NetCDF | .nc |
|
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.
Topology reading supports the formats in the following table.
Format | Reading ? | Writing ? |
---|---|---|
XYZ | ||
LAMMPS data file |
If you want to write a toplogy to a file, the best way for now is to create a frame with this topology, and write this frame to an XYZ file.