File input and output — ASE documentation

### Navigation

- index
- modules |
- Documentation for modules in ASE »

# 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)

  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)

  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')

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 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`

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

### Navigation

- index
- modules |
- Documentation for modules in ASE »