1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
.. module:: ase.io.trajectory
:synopsis: Trajectory input-output module
================
Trajectory files
================
.. contents::
The :mod:`ase.io.trajectory` module defines Trajectory objects, that is
objects storing the temporal evolution of a simulation or the path
taken during an optimization. A Trajectory file
contains one or more :class:`~ase.Atoms` objects, usually to be
interpreted as a time series, although that is not a requirement.
The main Trajectory object writes in a file format, which is compatible
across Python version.
The :mod:`ase.io.trajectory` additionally defines two specialized kinds of
Trajectory files, the PickleTrajectory and the BundleTrajectory.
PickleTrajectory is the old (pre 2015) Trajectory format, its use is no
longer recommended as compatibility between Python versions (and to a
lesser degree between ASE vesions) cannot be guaranteed. You *must*
:ref:`convert your old PickleTrajectory files <convert>` as soon
as possible.
BundleTrajectory is only intended for large molecular dynamics
simulations (large meaning millions of atoms).
Typically, trajectories are used to store different configurations of
the same system (i.e. the same atoms). If you need to store
configurations of different systems, the :mod:`ASE Database module
<ase.db>` may be more appropriate.
Trajectory
==========
The Trajectory function returns a Trajectory reading or writing
object, depending on the mode.
.. autofunction:: ase.io.Trajectory
The function returns a TrajectoryReader or a TrajectoryWriter object.
Reading a trajectory file is done by indexing the TrajectoryReader
object, i.e. traj[0] reads the first configuration, traj[-1] reads the
last, traj[3:8] returns a list of the third through seventh, etc.
Writing a trajectory file is done by calling the ``write`` method. If no
atoms object was given when creating the object, it must be given as
an argument to the ``write`` method.
Examples
--------
Reading a configuration::
from ase.io.trajectory import Trajectory
traj = Trajectory('example.traj')
atoms = traj[-1]
Reading all configurations::
traj = Trajectory('example.traj')
for atoms in traj:
# Analyze atoms
Writing every 100th time step in a molecular dynamics simulation::
# dyn is the dynamics (e.g. VelocityVerlet, Langevin or similar)
traj = Trajectory('example.traj', 'w', atoms)
dyn.attach(traj.write, interval=100)
dyn.run(10000)
traj.close()
.. _new trajectory:
The TrajectoryReader and TrajectoryWriter objects
-------------------------------------------------
Usually, you only need the interface given above, but the reader and
writer have a few additional methods, that can be useful.
.. autoclass:: ase.io.trajectory.TrajectoryReader
:members:
Note that there is apparently no methods for reading the trajectory.
Reading is instead done by indexing the trajectory, or by iterating
over the trajectory: ``traj[0]`` and ``traj[-1]`` return the first and
last :class:`~ase.Atoms` object in the trajectory.
.. autoclass:: ase.io.trajectory.TrajectoryWriter
:members:
.. _old trajectory:
PickleTrajectory
================
The *obsolete* PickleTrajectory uses the same object for reading and writing.
**WARNING 1:** If your Atoms objects contains constraints, the
constraint object is pickled and stored in the file. Unfortunately,
this means that if the object definition in ASE changes, you cannot
read the trajectory file. In the new
Trajectory format the contraint is stored in an
implementation-independent format.
**WARNING 2:** It is possible to write a malicious pickle file (and
thus a malicious PickleTrajectory) that executes arbitrary code when
reading the file. The new Trajectory format cannot contain code.
For the reasons above, version 3.10 of ASE will not be able to read and write
PickleTrajectory files, and you need to :ref:`convert existing files <convert>`
to the new format.
.. _convert:
Converting old PickleTrajectory files to new Trajectory files
-------------------------------------------------------------
Please convert your old PickleTrajectory files before it is too late::
$ python -m ase.io.trajectory file1.traj [file2.traj ...]
this will convert one or more files. The original files are kept with
extension ``.traj.old``
You can identify old trajectory files like this::
$ python -m ase.io.formats hmmm.traj
hmmm.traj: Old ASE pickle trajectory (trj+)
$ python -m ase.io.trajectory hmmm.traj # convert
$ python -m ase.io.formats hmmm.traj hmmm.traj.old
hmmm.traj: ASE trajectory (traj+)
hmmm.traj.old: Old ASE pickle trajectory (trj+)
BundleTrajectory
================
The BundleTrajectory has the interface
.. autoclass:: ase.io.bundletrajectory.BundleTrajectory
:members:
See also
========
* The function :func:`ase.io.write` can write a single
:class:`~ase.Atoms` object to a Trajectory file.
* The function :func:`ase.io.read` can read an :class:`~ase.Atoms`
object from a Trajectory file, per default it reads the last one.
* The database modue :mod:`ase.db`.
|
