Contents
The 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 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 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. We strongly recommend to convert your old PickleTrajectory files 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 ASE Database module may be more appropriate.
The Trajectory function returns a Trajectory reading or writing object, depending on the mode.
A Trajectory can be created in read, write or append mode.
Parameters:
The atoms, properties and master arguments are ignores in read mode.
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, 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.
Reading a configuration:
from ase.io.trajectory import Trajectory
traj = PickleTrajectory("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()
Usually, you only need the interface given above, but the reader and writer have a few additional methods, that can be useful.
Reads Atoms objects from a .traj file.
A Trajectory in read mode.
The filename traditionally ends in .traj.
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 Atoms object in the trajectory.
Writes Atoms objects to a .traj file.
A Trajectory writer, in write or append mode.
Parameters:
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, we recommend not to use the PickleTrajectory format, and to convert existing files to the new format.
Reads/writes Atoms objects into a .traj file.
A PickleTrajectory can be created in read, write or append mode.
Parameters:
The mode.
‘r’ is read mode, the file should already exist, and no atoms argument should be specified.
‘w’ is write mode. If the file already exists, it is renamed by appending .bak to the file name. The atoms argument specifies the Atoms object to be written to the file, if not given it must instead be given as an argument to the write() method.
‘a’ is append mode. It acts a write mode, except that data is appended to a preexisting file.
Close the trajectory file.
Opens the file.
For internal use only.
Attach a function to be called after writing ends.
function: The function or callable object to be called.
interval: How often the function is called. Default: every time (1).
All other arguments are stored, and passed to the function.
Attach a function to be called before writing begins.
function: The function or callable object to be called.
interval: How often the function is called. Default: every time (1).
All other arguments are stored, and passed to the function.
Associate an Atoms object with the trajectory.
Mostly for internal use.
Write the atoms to the file.
If the atoms argument is not given, the atoms object specified when creating the trajectory object is used.
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 Atoms object in the trajectory.
Please convert you 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
The BundleTrajectory has the interface
Reads and writes atoms into a .bundle directory.
The BundleTrajectory is an alternative way of storing trajectories, intended for large-scale molecular dynamics simulations, where a single flat file becomes unwieldy. Instead, the data is stored in directory, a ‘bundle’ (the name bundle is inspired from bundles in Mac OS, which are really just directories the user is supposed to think of as a single file-like unit).
Parameters:
Check if a filename is an empty bundle. Assumes that it is a bundle.
Write to the log file in the bundle.
Logging is only possible in write/append mode.
This function is mainly for internal use, but can also be called by the user.
Attach a function to be called after writing ends.
function: The function or callable object to be called.
interval: How often the function is called. Default: every time (1).
All other arguments are stored, and passed to the function.
Attach a function to be called before writing begins.
function: The function or callable object to be called.
interval: How often the function is called. Default: every time (1).
All other arguments are stored, and passed to the function.
Read extra data stored alongside the atoms.
Currently only used to read data stored by an NPT dynamics object. The data is not associated with individual atoms.
Selects if a given data type should be written.
Data can be written in every frame (specify True), in the first frame only (specify ‘only’) or not at all (specify False). Not all data types support the ‘only’ keyword, if not supported it is interpreted as True.
The following data types are supported, the letter in parenthesis indicates the default:
positions (T), numbers (O), tags (O), masses (O), momenta (T), forces (T), energy (T), energies (F), stress (F), magmoms (T)
If a given property is not present during the first write, it will be not be saved at all.
Adds extra data to be written.
Parameters: name: The name of the data.
source (optional): If specified, a callable object returning the data to be written. If not specified it is instead assumed that the atoms contains the data as an array of the same name.
once (optional): If specified and True, the data will only be written to the first frame.