File input and output

The module has three basic functions: read(), iread() and write(). The methods are described here:, index=None, format=None, parallel=True, **kwargs)[source]

Read Atoms object(s) from file.

filename: str or file
Name of the file to read from or a file descriptor.
index: int, slice or str

The last configuration will be returned by default. Examples:

  • index=0: first configuration
  • index=-2: second to last
  • index=':' or index=slice(None): all
  • index='-3: or index=slice(-3, None): three last
  • index='::2 or index=slice(0, None, 2): even
  • index='1::2 or index=slice(1, None, 2): odd
format: str
Used to specify the file-format. If not given, the file-format will be guessed by the filetype function.
parallel: bool
Default is to read on master and broadcast to slaves. Use parallel=False to read on all slaves.

Many formats allow on open file-like object to be passed instead of filename. In this case the format cannot be auto-decected, so the format argument should be explicitly given., index=None, format=None, parallel=True, **kwargs)[source]

Iterator for reading Atoms objects from file.

Works as the \(read\) function, but yields one Atoms object at a time instead of all at once., images, format=None, parallel=True, append=False, **kwargs)[source]

Write Atoms object(s) to file.

filename: str or file
Name of the file to write to or a file descriptor. The name ‘-‘ means standard output.
images: Atoms object or list of Atoms objects
A single Atoms object or a list of Atoms objects.
format: str
Used to specify the file-format. If not given, the file-format will be taken from suffix of the filename.
parallel: bool
Default is to write on master only. Use parallel=False to write from all slaves.
append: bool
Default is to open files in ‘w’ or ‘wb’ mode, overwriting existing files. In some cases opening the file in ‘a’ or ‘ab’ mode (appending) is usefull, e.g. writing trajectories or saving multiple Atoms objects in one file. WARNING: If the file format does not support multiple entries without additional keywords/headers, files created using ‘append=True’ might not be readable by any program! They will nevertheless be written without error message.

The use of additional keywords is format specific.

These are the file-formats that are recognized (formats with a + support multiple configurations):

format description capabilities
abinit ABINIT input file RW
aims FHI-aims geometry file RW
aims-output FHI-aims output R+
bundletrajectory ASE bundle trajectory RW+
castep-castep CASTEP output file R+
castep-cell CASTEP geom file RW
castep-geom CASTEP trajectory file R+
castep-md CASTEP molecular dynamics file R+
castep-phonon CASTEP phonon file R
cfg AtomEye configuration RW
cif CIF-file RW+
cmdft CMDFT-file R
crystal Crystal fort.34 format RW
cube CUBE file RW
dacapo Dacapo netCDF output file R
dacapo-text Dacapo text output R
db ASE SQLite database file RW+
dftb DftbPlus input file RW
dlp-history DL_POLY HISTORY file R+
dlp4 DL_POLY_4 CONFIG file RW
dmol-arc DMol3 arc file RW+
dmol-car DMol3 structure file RW
dmol-incoor DMol3 structure file RW
elk ELK atoms definition R
eon EON reactant.con file RW
eps Encapsulated Postscript W
espresso-in Quantum espresso in file RW
espresso-out Quantum espresso out file R+
etsf ETSF format RW
exciting exciting input RW
extxyz Extended XYZ file RW+
findsym FINDSYM-format W+
gaussian Gaussian com (input) file RW
gaussian-out Gaussian output file R
gen DFTBPlus GEN format RW
gif Graphics interchange format W+
gpaw-out GPAW text output R+
gpw GPAW restart-file R
gromacs Gromacs coordinates RW
gromos Gromos96 geometry file RW
iwm ? R
json ASE JSON database file RW+
jsv JSV file format RW
lammps-data LAMMPS data file R
lammps-dump LAMMPS dump file R+
magres MAGRES ab initio NMR data file RW
mol MDL Molfile R
mp4 MP4 animation W+
mustem muSTEM xtl file RW
netcdftrajectory AMBER NetCDF trajectory file RW+
nomad-json JSON from Nomad archive R+
nwchem NWChem input file RW
octopus Octopus input file R
png Portable Network Graphics W
postgresql ASE PostgreSQL database file RW+
pov Persistance of Vision W
proteindatabank Protein Data Bank RW+
py Python file W+
qbox QBOX output file R+
res SHELX format RW
sdf SDF format R
struct WIEN2k structure file RW
struct_out SIESTA STRUCT file R
traj ASE trajectory RW+
trj Old ASE pickle trajectory RW+
turbomole TURBOMOLE coord file RW
turbomole-gradient TURBOMOLE gradient file R+
v-sim V_Sim ascii file RW
vasp-out VASP OUTCAR file R+
vasp-xdatcar VASP XDATCAR file R+
vasp-xml VASP vasprun.xml file R+
vti VTK XML Image Data W
vtu VTK XML Unstructured Grid W
x3d X3D W
xsd Materials Studio file RW
xsf XCrySDen Structure File RW+
xyz XYZ-file RW+


Even though that ASE does a good job reading the above listed formats, it may not read some unusual features or strangely formatted files.

For the CIF format, STAR extensions as save frames, global blocks, nested loops and multi-data values are not supported.


ASE read and write functions are automatically parallelized if a suitable MPI library is found. This requires to call read and write with same input on all cores. For more information, see ase.parallel.


ASE can read and write directly to compressed files. Simply add .gz, .bz2 or .xz to your filename (.xz requires the backports.lzma module on Python 2).

The read() function is only designed to retrieve the atomic configuration from a file, but for the CUBE format you can import the function:

which will return a (data, atoms) tuple:

from import read_cube_data
data, atoms = read_cube_data('abc.cube')


>>> from ase import Atoms
>>> from import fcc111, add_adsorbate, bulk
>>> from import read, write
>>> adsorbate = Atoms('CO')
>>> adsorbate[1].z = 1.1
>>> a = 3.61
>>> slab = fcc111('Cu', (2, 2, 3), a=a, vacuum=7.0)
>>> add_adsorbate(slab, adsorbate, 1.8, 'ontop')

Write PNG image

>>> write('slab.png', slab * (3, 3, 1), rotation='10z,-80x')

Write animation with 500 ms duration per frame

>>> write('movie.gif', [bulk(s) for s in ['Cu', 'Ag', 'Au']], interval=500)

Write POVRAY file

>>> write('slab.pov', slab * (3, 3, 1), rotation='10z,-80x')

This will write both a slab.pov and a slab.ini file. Convert to PNG with the command povray slab.ini or use the run_povray=True option:


Here is an example using bbox

>>> d = a / 2**0.5
>>> write('slab.pov', slab * (2, 2, 1),
...       bbox=(d, 0, 3 * d, d * 3**0.5))

Note that in general the XYZ-format does not contain information about the unit cell, however, ASE uses the extended XYZ-format which stores the unitcell:

>>> from import read, write
>>> write('', slab)
>>> a = read('')
>>> cell = a.get_cell()
>>> cell.round(3)
array([[  5.105,   0.   ,   0.   ],
       [  2.553,   4.421,   0.   ],
       [  0.   ,   0.   ,  18.168]])
>>> a.get_pbc()
array([ True,  True, False], dtype=bool)

Another way to include the unit cell is to write the cell vectors at the end of the file as VEC<N> <x> <y> <z> (used for example in the ADF software).

>>> write('', vec_cell=True)

Use ASE’s native format for writing all information:

>>> write('slab.traj', slab)
>>> b = read('slab.traj')
>>> b.cell.round(3)
array([[  5.105,   0.   ,   0.   ],
       [  2.553,   4.421,   0.   ],
       [  0.   ,   0.   ,  18.168]])
>>> b.pbc
array([ True,  True, False], dtype=bool)

A script showing all of the povray parameters, and generating the image below, can be found here:


An other example showing how to change colors and textures in pov can be found here: ../../tutorials/

Adding a new file-format to ASE

Try to model the read/write functions after the xyz format as implemented in ase/io/ and also read, understand and update ase/io/