File input and output

The ase.io module has two basic functions: read() and write(). The two methods are described here:

ase.io.read(filename, index=None, format=None)[source]

Read Atoms object(s) from file.

filename: str
Name of the file to read from.
index: int or slice
If the file contains several configurations, the last configuration will be returned by default. Use index=n to get configuration number n (counting from zero).
format: str
Used to specify the file-format. If not given, the file-format will be guessed by the filetype function.

Known formats:

format short name
GPAW restart-file gpw
Dacapo netCDF output file dacapo
Old ASE netCDF trajectory nc
Virtual Nano Lab file vnl
ASE pickle trajectory traj
ASE bundle trajectory bundle
GPAW text output gpaw-text
CUBE file cube
XCrySDen Structure File xsf
Dacapo text output dacapo-text
XYZ-file xyz
VASP POSCAR/CONTCAR file vasp
VASP OUTCAR file vasp_out
VASP XDATCAR file vasp_xdatcar
SIESTA STRUCT file struct_out
ABINIT input file abinit
V_Sim ascii file v_sim
Protein Data Bank pdb
CIF-file cif
FHI-aims geometry file aims
FHI-aims output file aims_out
VTK XML Image Data vti
VTK XML Structured Grid vts
VTK XML Unstructured Grid vtu
TURBOMOLE coord file tmol
TURBOMOLE gradient file tmol-gradient
exciting input exi
AtomEye configuration cfg
WIEN2k structure file struct
DftbPlus input file dftb
CASTEP geom file cell
CASTEP output file castep
CASTEP trajectory file geom
ETSF format etsf.nc
DFTBPlus GEN format gen
CMR db/cmr-file db
CMR db/cmr-file cmr
LAMMPS dump file lammps
EON reactant.con file eon
Gromacs coordinates gro
Gaussian com (input) file gaussian
Gaussian output file gaussian_out
Quantum espresso in file esp_in
Quantum espresso out file esp_out
Extended XYZ file extxyz
NWChem input file nw
Materials Studio file xsd

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.

ase.io.write(filename, images, format=None, **kwargs)[source]

Write Atoms object(s) to file.

filename: str
Name of the file to write to.
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.

The accepted output formats:

format short name
ASE pickle trajectory traj
ASE bundle trajectory bundle
CUBE file cube
XYZ-file xyz
VASP POSCAR/CONTCAR file vasp
ABINIT input file abinit
Protein Data Bank pdb
CIF-file cif
XCrySDen Structure File xsf
FHI-aims geometry file aims
gOpenMol .plt file plt
Python script py
Encapsulated Postscript eps
Portable Network Graphics png
Persistance of Vision pov
VTK XML Image Data vti
VTK XML Structured Grid vts
VTK XML Unstructured Grid vtu
TURBOMOLE coord file tmol
exciting exi
AtomEye configuration cfg
WIEN2k structure file struct
CASTEP cell file cell
DftbPlus input file dftb
ETSF etsf.nc
DFTBPlus GEN format gen
CMR db/cmr-file db
CMR db/cmr-file cmr
EON reactant.con file eon
Gromacs coordinates gro
GROMOS96 (only positions) g96
X3D x3d
X3DOM HTML html
Extended XYZ file extxyz

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.

The use of additional keywords is format specific.

The cube and plt formats accept (plt requires it) a data keyword, which can be used to write a 3D array to the file along with the nuclei coordinates.

The vti, vts and vtu formats are all specifically directed for use with MayaVi, and the latter is designated for visualization of the atoms whereas the two others are intended for volume data. Further, it should be noted that the vti format is intended for orthogonal unit cells as only the grid-spacing is stored, whereas the vts format additionally stores the coordinates of each grid point, thus making it useful for volume date in more general unit cells.

The eps, png, and pov formats are all graphics formats, and accept the additional keywords:

rotation: str (default ‘’)
The rotation angles, e.g. ‘45x,70y,90z’.
show_unit_cell: int (default 0)
Can be 0, 1, 2 to either not show, show, or show all of the unit cell.
radii: array or float (default 1.0)
An array of same length as the list of atoms indicating the sphere radii. A single float specifies a uniform scaling of the default covalent radii.
bbox: 4 floats (default None)
Set the bounding box to (xll, yll, xur, yur) (lower left, upper right).
colors: array (default None)
An array of same length as the list of atoms, indicating the rgb color code for each atom. Default is the jmol_colors of ase/data/colors.
scale: int (default 20)
Number of pixels per Angstrom.

For the pov graphics format, scale should not be specified. The elements of the color array can additionally be strings, or 4 and 5 vectors for named colors, rgb + filter, and rgb + filter + transmit specification. This format accepts the additional keywords:

run_povray, display, pause, transparent, canvas_width, canvas_height, camera_dist, image_plane, camera_type, point_lights, area_light, background, textures, celllinewidth, bondlinewidth, bondatoms

The xyz format accepts a comment string using the comment keyword:

comment: str (default ‘’)
Optional comment written on the second line of the file.

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

ase.io.read_cube_data()

which will return a (data, atoms) tuple:

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

Examples

from ase.lattice.surface import *
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')
../_images/io1.png

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:

../_images/io2.png

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))
../_images/io3.png

Note that the XYZ-format does not contain information about the unic cell:

>>> write('slab.xyz', slab)
>>> a = read('slab.xyz')
>>> a.get_cell()
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> a.get_pbc()
array([False, False, False], dtype=bool)

Use ASE’s native format for writing all information:

>>> write('slab.traj', slab)
>>> b = read('slab.traj')
>>> b.get_cell()
array([[  5.10531096e+00,  -4.11836034e-16,   1.99569088e-16],
       [  2.55265548e+00,   4.42132899e+00,   7.11236625e-17],
       [  8.11559027e+00,   4.68553823e+00,   1.32527034e+01]])
>>> b.get_pbc()
array([ True,  True,  True], dtype=bool)

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

../_images/NaCl_C6H6.png

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