1.. _output_files:
2
3Output files
4============
5
6.. contents::
7   :depth: 2
8   :local:
9
10The output data are stored in the following files on the current
11directory.
12
13List of files
14--------------
15
16``band.yaml``
17^^^^^^^^^^^^^^
18
19Sets of phonon frequencies on band paths calculated by the
20:ref:`band-structure mode <band_structure_related_tags>`
21(e.g. ``BAND`` tag) are stored in the YAML format.
22
23``band.yaml`` is viewed using the tool ``phonopy-bandplot``
24(:ref:`bandplot_tool`). ``phonopy-bandplot`` can convert the data in the YAML
25format to that in the gnuplot-style format using the ``--gnuplot`` option.
26
27``mesh.yaml``
28^^^^^^^^^^^^^^
29
30A set of frequencies on irreducible q-points of a q-point mesh by the
31:ref:`mesh-sampling mode <dos_related_tags>` (``MESH`` tag) is stored in
32the YAML format.
33
34``qpoints.yaml``
35^^^^^^^^^^^^^^^^^
36
37A set of frequencies calculated by the
38:ref:`q-points mode <qpoints_tag>`
39(``QPOINTS`` tag) is stored in the YAML format.
40
41``thermal_properties.yaml``
42^^^^^^^^^^^^^^^^^^^^^^^^^^^^
43
44:ref:`Thermal properties <thermal_properties_tag>` calculated
45are stored in the YAML format.
46
47The auxiliary tool ``phonopy-propplot`` (:ref:`propplot_tool`) can be used to
48plot the content of ``thermal_properties.yaml``.
49
50``thermal_displacements.yaml``
51^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
52
53:ref:`Mean square displcements of atoms <thermal_displacements_tag>`
54are stored in the YAML format. Without projecting eigenvectors along a
55specific direction, the results projected along Cartesianl
56coordinates, therefore three values for each atom at a temperature,
57are written into the file.
58
59``thermal_displacement_matrices.yaml``
60^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
61
62:ref:`Mean square displacement matricies of atoms
63<thermal_displacement_matrices_tag>` are stored in the YAML
64format. Since the matrix for each atom at a temperature is symmetric,
65only six elements of it, xx, yy, zz, yz, xz, xy, are written in this
66order.
67
68``total_dos.dat`` and ``projected_dos.dat``
69^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
70
71:ref:`Total and projected DOS <dos_related_tags>` are stored in the
72simple format, respectively.
73
74``total_dos.dat`` and ``projected_dos.dat`` are viewed using the
75auxiliary tool ``phonopy-pdosplot`` (:ref:`pdosplot_tool`).
76
77File format of ``projected_dos.dat``
78~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79
80The first column is the phonon frequency. The following colums are the
81projected density of states for atoms in the primitive cell. In the
82:ref:`NaCl example <example_pdos>`, there are two atoms in the
83primitive cell, which are one Na and one Cl atoms. The order of atoms
84in the primitive cell is confirmed running phonopy with the ``-v``
85option. The ``projected_dos.dat`` of this example is starting with the
86following lines::
87
88   # Sigma = 0.063253
89          -0.6695362607        0.0000000000        0.0000000000
90          -0.6379098952        0.0000000000        0.0000000000
91          -0.6062835296        0.0000000000        0.0000000000
92          -0.5746571641        0.0000000000        0.0000000000
93          -0.5430307986        0.0000000000        0.0000000000
94          -0.5114044331        0.0000000000        0.0000000000
95          -0.4797780675        0.0000000000        0.0000000000
96          -0.4481517020        0.0000000000        0.0000000000
97          -0.4165253365        0.0000000000        0.0000000000
98          -0.3848989710        0.0000000000        0.0000000000
99          -0.3532726054        0.0000000004        0.0000000006
100          -0.3216462399        0.0000000044        0.0000000066
101          -0.2900198744        0.0000000370        0.0000000551
102          -0.2583935089        0.0000002410        0.0000003596
103          -0.2267671433        0.0000012239        0.0000018260
104   ...
105
106where from the left to right in each line, frequency, PDOS of Na and
107PDOS of Cl. The first line is just a comment to remember the sigma
108value used.
109
110With :ref:`xyz_projection_tag` tag specified, the format changes to
111represent x, y, and z components::
112
113   # Sigma = 0.063253
114          -0.6695362607        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000
115          -0.6315846221        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000
116          -0.5936329834        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000
117          -0.5556813448        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000
118          -0.5177297062        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000
119          -0.4797780675        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000
120          -0.4418264289        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000
121          -0.4038747903        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000        0.0000000000
122          -0.3659231516        0.0000000000        0.0000000000        0.0000000000        0.0000000001        0.0000000001        0.0000000001
123          -0.3279715130        0.0000000009        0.0000000009        0.0000000009        0.0000000014        0.0000000014        0.0000000014
124          -0.2900198744        0.0000000123        0.0000000123        0.0000000123        0.0000000184        0.0000000184        0.0000000184
125   ...
126
127``phonopy.yaml`` and ``phonopy_disp.yaml``
128^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
129
130Phonopy configurations and crystal structures are stored in these
131files when running pre-process (``phonopy_disp.yaml``) or post-process
132(``phonopy.yaml``).
133
134``phonopy_disp.yaml`` contains information used to create supercells
135with displacements. The format is hopefully understood just looking
136into it. ``displacement`` is written in Cartesian coordinates.
137
138``.hdf5`` files
139^^^^^^^^^^^^^^^^^
140
141See :ref:`hdf5_tag`.
142
143
144How to read phonopy YAML files
145-------------------------------
146
147Most phonopy results are written in the YAML format. YAML files are
148easily translated to the combination of lists and dictionaries in the
149python case. For each computer language, e.g., Ruby, each YAML parser
150is prepared and you can use those libraries to parse YAML files and
151analyze the data easily in conjunction with your favorite
152language. See http://www.yaml.org/. The basic of the YAML format is
153found easily on the web. In python, it is very easy to parse phonopy's
154yaml files, e.g.,
155
156::
157
158   import yaml
159   with open("band.yaml") as f:
160       data = yaml.load(f)
161
162``mesh.yaml``, ``band.yaml``, ``qpoints.yaml``
163^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
164
165
166General
167~~~~~~~~~~~
168
169============== =======================================================
170============== =======================================================
171nqpoint        Number of q-points calculated.
172natom          Number of atoms in the primitive cell.
173phonon         Key name of list for q-points.
174q-position     Position of q-vector in reduced coordinates.
175band           Key name of list for bands.
176frequency      Phonon frequency in a specified unit at each phonon
177               mode
178eigenvector    Eigenvector at each phonon mode.
179               Each eigenvector :math:`\mathbf{e}` of
180               :ref:`dynamical matrix <dynacmial_matrix_theory>`
181               is shown as sets of three
182               complex values of each atom along the Cartesian axes in
183               the primitive cell. The real and imaginary values
184               correspond to the left and right, respectively.
185               A set of eigenvectors comprising all bands at a q-point
186               forms a unitary matrix obtained as the result of
187               numpy.linalg.eigh, i.e., LAPACK of routine _heevd.
188               Therefore eigenvectors correspond to the column vectors
189               of the unitary matrix.
190group_velocity Group velocity at each phonon mode in the
191               Cartesian coordinates defined in the unit cell.
192============== =======================================================
193
194Mesh sampling mode
195~~~~~~~~~~~~~~~~~~~
196
197============== =======================================================
198============== =======================================================
199mesh           Numbers of mesh sampling points along axes of the
200               primitive cell.
201weight         In the mesh sampling mode, only phonons at irreducible
202               q-points are calculated in the default behavior. This
203               value means the multiplicity of a q-point in the
204               reciprocal space of the primitive cell.
205============== =======================================================
206
207Band structure mode
208~~~~~~~~~~~~~~~~~~~
209
210============== =======================================================
211============== =======================================================
212distance       In the band structure mode, this value means the
213               distance from the origin in the reciprocal space of the
214               primitive cell. The unit is the reciprocal of length
215               unit used in the real space.
216============== =======================================================
217
218
219``thermal_properties.yaml``
220^^^^^^^^^^^^^^^^^^^^^^^^^^^
221
222The physical units of the thermal properties are given in the unit
223section of this YAML file. However the physical units are only correct
224when phonopy ran with proper physical units. See
225:ref:`thermal_properties_tag`.
226