1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
.. module:: ase.io
:synopsis: File input-output module
=====================
File input and output
=====================
.. seealso::
* :mod:`ase.io.trajectory`
.. toctree::
:hidden:
formatoptions
trajectory
ulm
opls
The :mod:`ase.io` module has three basic functions: :func:`read`,
:func:`iread` and :func:`write`. The methods are described here:
.. autofunction:: read
.. autofunction:: iread
.. autofunction:: write
Use ``ase info --formats`` to see a list of formats. This information
is programmatically accessible as ``ase.io.formats.ioformats``, a
dictionary which maps format names to :class:`ase.io.formats.IOFormat`
objects.
These are the file-formats that are recognized (formats with a ``+`` support
multiple configurations):
.. csv-table::
:file: io.csv
:header-rows: 1
.. note::
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.
.. note::
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
:mod:`ase.parallel`.
.. note::
ASE can read and write directly to compressed files. Simply add ``.gz``,
``.bz2`` or ``.xz`` to your filename.
The :func:`read` function is only designed to retrieve the atomic configuration
from a file, but for the CUBE format you can import the function:
.. function:: 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 import Atoms
>>> from ase.build import fcc111, add_adsorbate, bulk
>>> from ase.io 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')
.. image:: io1.png
Write animation with 500 ms duration per frame
>>> write('movie.gif', [bulk(s) for s in ['Cu', 'Ag', 'Au']], interval=500)
Write POVRAY file (the projection settings and povray specific settings are separated)
>>> write('slab.pov', slab * (3, 3, 1),
... generic_projection_settings = dict(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
``.render`` method on the returned object:
.. image:: io2.png
Here is an example using ``bbox``
>>> d = a / 2**0.5
>>> write('slab.pov', slab * (2, 2, 1),
... generic_projection_settings = dict(
... bbox=(d, 0, 3 * d, d * 3**0.5))).render()
.. image:: io3.png
This is an example of displaying bond order for a molecule
.. literalinclude:: save_C2H4.py
.. image:: C2H4.png
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 ase.io import read, write
>>> write('slab.xyz', slab)
>>> a = read('slab.xyz')
>>> 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('slab.xyz', 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: :download:`save_pov.py`
.. image:: NaCl_C6H6.png
An other example showing how to change colors and textures in pov can
be found here: :download:`../../tutorials/saving_graphics.py`.
Adding a new file-format to ASE
===============================
Try to model the read/write functions after the *xyz* format as implemented
in :git:`ase/io/xyz.py` and also read, understand and update
:git:`ase/io/formats.py`.
Adding a new file-format in a plugin package
============================================
IO formats can also be implemented in external packages. For this the read
write functions of the IO format are implemented as normal. To define the
format the parameters are entered into a :class:`ase.utils.plugins.ExternalIOFormat`
object.
.. note::
The module name of the external IO format has to be absolute and cannot
be omitted.
In the configuration of the package an entry point is added under the group
``ase.ioformats`` which points to the defined :class:`ase.utils.plugins.ExternalIOFormat`
object. The format of this entry point looks like ``format-name=ase_plugin.io::ioformat``.
|
