There are two classes for reading trajectories: AtomsReader and AtomsList. Use an AtomsReader for quick read-only access to a trajectory or if you only want to access some of the frames. If you want to load the entire file into memory and manipulate it use an AtomsList.
An AtomsReader reads a series of Atoms objects from the trajectory source which should be one of the following:
- a filename - in this case format is inferred from the file extension – see Supported File Formats
- a shell-style glob pattern e.g. “*.xyz”
- a list of filenames or glob patterns e.g. [“foo*.xyz”, “bar*.xyz”]
- an open file or file-like object (e.g. a CInOutput object)
- any Python iterator which yields a sequence of Atoms objects
start, stop and step can be used to restrict the range of frames read from source. The first frame in the file has index zero.
cache_limit determines how many configurations will be stored in memory. If more than cache_limit configurations are read in, the least recently accessed configurations are thrown away. To store everything, use an AtomsList instead.
Some sources understand additional keyword arguments from **kwargs. For example the CASTEP file reader can take an atoms_ref argument which is a reference Atoms object which is used to fill in information which is missing from the input file.
All AtomsReaders support iteration, so you can loop over the contents using a for loop:
al = AtomsReader('input-file.xyz')
for at in al:
# process Atoms object `at`
print at.energy
or using list comprehension:
print [at.energy for at in al]
In addition to iteration, some sources allow random access. To find out if an AtomsReader supports random access, either try to get it’s length with len(), or check if the random_access property is true. If cache_limit is large enough to store all the frames in the file, all AtomsReaders will allow random access once the entire trajectory has been loaded.
If randomaccess is true, you can access individual frames by indexing and slicing, e.g. al[i] is the ith Atoms object within al and al[i:j] returns objects from i upto but not including j. Like ordinary Python lists, indices start from 0 and run up to len(al)-1.
Methods and attributes:
True if this source supports random access, False if it does not.
Return an interator over all the frames in this trajectory. This is the default iterator for an AtomsReader instance al, and can be accessed with iter(al).
If reverse=True then the iteration starts with the last frame and goes backwards through the file. This is only possible if random_access is true.
Visualise using atomeye.show(). The optional arguments property, frame and arrows control the atom colouring, initial frame and vector arrows respectively.
Write all frames in this AtomsList to dest. If format is not given it is inferred from the file extension of dest (see Supported File Formats). If properties is present, it should be a list of property names to include in the output file, e.g. [‘species’, ‘pos’].
progress, progress_width, update_interval and show_value are used to control a textual progress bar. The extra arguments in *args and **kwargs are passed along to the underlying writer routine constructed for writing to dest.
See Supported File Formats for a list of supported file formats.
An AtomsList is just like an AtomsReader except that all frames are read in on initialiased and then stored in memory. This is equivalent to an AtomsReader with a cache_limit of None so an AtomsList always supports random access.
The AtomsList allows configurations to be added, removed or reordered using the standard Python methods for mutable sequence types (e.g. append(), extend(), index(), etc).
The attributes of the component Atoms can be accessed as a single array, using the frame number as the first array index. Note that the first index runs from 0 to len(al)-1, unlike the other indices which are one-based since the Atoms attributes are stored in a FortranArray.
For example the following statements are all true:
al.energy == [at.energy for at in al] # energies of all atoms
al.energy[0] == al[0].energy # energy of first frame
all(al.velo[0] == al[0].velo) # velocities of all atoms in first frame
al.velo[0,-1] == al[0].velo[-1] # velocity of last atom in first frame
In addition to the standard Python list methods and those of AtomsReader, AtomsList defined a couple of extras methods.
Sort the AtomsList in place. This is the same as the standard list.sort() method, except for the additional attr argument. If this is present then the sorted list will be ordered by the Atoms attribute attr, e.g.:
al.sort(attr='energy')
will order the configurations by their energy (assuming that Atoms.params contains an entry named energy for each configuration; otherwise an AttributError will be raised).
Returns a file-like object for writing Atoms to dest which should be either a filename or an initiliased output object. If format is not given it is inferred from the file extension of dest. Example usage:
out = AtomsWriter('out_file.xyz')
for at in seq:
out.write(at)
out.close()