scnc
/
phono3py
mirror of https://github.com/phonopy/phono3py.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add documents

This commit is contained in:
Atsushi Togo 2015-12-30 18:35:32 +09:00
parent c2bfd7244c
commit e75f29ff5d
10 changed files with 1604 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/Si-kaccum.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

54
doc/auxiliary-tools.rst Normal file
View File

@ -0,0 +1,54 @@
.. _auxiliary_tools:
Auxiliary tools
===============
``kaccum``
-----------
**This command is under the development. The usage and file format of
the output may change in the future.**
Accumulated lattice thermal conductivity with respect to frequency is
calculated. The frequency derivative like density of states is also
calculated.
::
% kaccum --mesh="11 11 11" --pa="0 1/2 1/2 1/2 0 1/2 1/2 1/2 0" \
POSCAR-unitcell kappa-m111111.hdf5 |tee kaccum.dat
``--mesh`` option is mandatory and ``--pa`` option is optional. The
first and second arguments are the unit cell and ``kappa-***.hdf5`` files,
respectively.
The format of the output is as follows: The first column gives
frequency, and the second to seventh columns give the accumulated
lattice thermal conductivity of 6 elements, xx, yy, zz, yz, xz,
xy. The eighth to 13th columns give the derivatives. There are sets of
frequencies, which are separated by blank lines. Each set is for a
temperature. There are the groups corresponding to the number of
temperatures calculated.
To plot the output by gnuplot at temperature index 30 that may
correspond to 300 K,
::
% echo 'p "kaccum.dat" i 30 u 1:2 w l, "kaccum.dat" i 30 u 1:8 w l'|gnuplot -persist
This is the result of silicon.
.. |i0| image:: Si-kaccum.png
:width: 50%
|i0|
``gaccum``
-----------
``gaccum`` is very similar to ``kaccum``, but for
:math:`\Gamma_\lambda(\omega_\lambda)`. The intensity is normalized by
the number of grid points.

179
doc/changelog.rst Normal file
View File

@ -0,0 +1,179 @@
.. _changelog:
Change Log
==========
Oct-10-2015: version 0.9.14
------------------------------
- Computational performance tuning for phonon-phonon interaction
strength calculation was made by Jonathan Skelton. Depending on
systems, but 10-20% performance improvement may be possible.
- ``--stp`` option is created to show numbers of q-point triplets to
be calculated. See :ref:`command_options`.
- ``--write_gamma`` and ``--read_gamma`` support using with ``--bi``
option. Therefore a thermal conductivity calculation can be
distributed over band index, too. This may be useful for the system
whose unit cell is large.
Sep-26-2015: version 0.9.13
------------------------------
- Changed so that ``--wgp`` option writes ``grid_address-mxxx.hdf5``
instead of ``grid_address-mxxx.dat``.
- ``--write_detailed_gamma`` is implemented. See :ref:`command_options`.
- When running without setting ``--thm`` and ``--sigma`` options,
linear tetrahedron method corresponding to ``--thm`` is used as the
default behavior.
- ``--ise`` options is created.
Aug-12-2015: version 0.9.12
------------------------------
- Spglib update to version 1.8.2.1.
- Improve computational performance of ``kaccum`` and ``gaccum``.
Jun-18-2015: version 0.9.10.1
------------------------------
- Bug fix of ``gcaccum``
Jun-17-2015: version 0.9.10
----------------------------
- Fix bug in ``kaccum``. When using with ``--pa`` option, irreducible
q-points were incorrectly indexed.
- ``gaccum`` is implemented. ``gaccum`` is very similar to ``kaccum``,
but for :math:`\Gamma_\lambda(\omega_\lambda)`.
- spglib update.
Changes in version 0.9.7
-------------------------
- The definition of MSPP is modified so as to be averaged ph-ph
interaction defined as :math:`P_{\mathbf{q}j}` in the arXiv
manuscript. The key in the kappa hdf5 file is changed from ``mspp``
to ``ave_pp``. The physical unit of :math:`P_{\mathbf{q}j}` is set
to :math:`\text{eV}^2`.
Changes in version 0.9.6
------------------------
- Silicon example is put in ``example-phono3py`` directory.
- Accumulated lattice thermal conductivity is calculated by ``kaccum``
script.
- JDOS output format was changed.
Changes in version 0.9.5
-------------------------
- In ``kappa-xxx.hdf5`` file, ``heat_capacity`` format was changed
from ``(irreducible q-point, temperature, phonon band)`` to
``(temperature, irreducible q-point, phonon band)``. For ``gamma``,
previous document was wrong in the array shape. It is
``(temperature, irreducible q-point, phonon band)``
Changes in version 0.9.4
------------------------
- The option of ``--cutoff_mfp`` is renamed to ``--boundary_mfp`` and
now it's on the document.
- Detailed contribution of ``kappa`` at each **q**-point and phonon
mode is output to .hdf5 with the keyword ``mode_kappa``.
Changes in version 0.8.11
-------------------------
- A new option of ``--cutoff_mfp`` for including effective boundary
mean free path.
- The option name ``--cutfc3`` is changed to ``--cutoff_fc3``.
- The option name ``--cutpair`` is changed to ``--cutoff_pair``.
- A new option ``--ga`` is created.
- Fix spectrum plot of joint dos and imaginary part of self energy
Changes in version 0.8.10
-------------------------
- Different supercell size of fc2 from fc3 can be specified using
``--dim_fc2`` option.
- ``--isotope`` option is implemented. This is used instead of
``--mass_variances`` option without specifying the values. Mass
variance parameters are read from database.
Changes in version 0.8.2
------------------------
- Phono3py python interface is rewritten and a lot of changes are
introduced.
- ``FORCES_SECOND`` and ``FORCES_THIRD`` are no more used. Instead just
one file of ``FORCES_FC3`` is used. Now ``FORCES_FC3`` is generated
by ``--cf3`` option and the backward compatibility is simple: ``cat
FORCES_SECOND FORCES_THIRD > FORCES_FC3``.
- ``--multiple_sigmas`` is removed. The same behavior is achieved by
``--sigma``.
Changes in version 0.8.0
------------------------
- ``--q_direction`` didn't work. Fix it.
- Implementation of tetrahedron method whcih is activated by
``--thm``.
- Grid addresses are written out by ``--wgp`` option.
Changes in version 0.7.6
------------------------
- Cut-off distance for fc3 is implemented. This is activated by
``--cutfc3`` option. FC3 elements where any atomic pair has larger
distance than cut-off distance are set zero.
- ``--cutpair`` works only when creating displacements. The cut-off
pair distance is written into ``disp_fc3.yaml`` and FC3 is created
from ``FORCES_THIRD`` with this information. Usually sets of pair
displacements are more redundant than that needed for creating fc3
if index permutation symmetry is considered. Therefore using index
permutation symmetry, some elements of fc3 can be recovered even if
some of supercell force calculations are missing. In paticular, all
pair distances among triplet atoms are larger than cutoff pair
distance, any fc3 elements are not recovered, i.e., the element will
be zero.
Changes in version 0.7.2
------------------------
- Default displacement distance is changed to 0.03.
- Files names of displacement supercells now have 5 digits numbering,
``POSCAR-xxxxx``.
- Cutoff distance between pair displacements is implemented. This is
triggered by ``--cutpair`` option. This option works only for
calculating atomic forces in supercells with configurations of pairs
of displacements.
Changes in version 0.7.1
------------------------
- It is changed to sampling q-points in Brillouin zone. Previously
q-points are sampled in reciprocal primitive lattice. Usually this
change affects very little to the result.
- q-points of phonon triplets are more carefully sampled when a
q-point is on Brillouin zone boundary. Usually this
change affects very little to the result.
- Isotope effect to thermal conductivity is included.
Changes in version 0.6.0
------------------------
- ``disp.yaml`` is renamed to ``disp_fc3.yaml``. Old calculations with
``disp.yaml`` can be used without any problem just by changing the
file name.
- Group velocity is calculated from analytical derivative of dynamical
matrix.
- Group velocities at degenerate phonon modes are better handled.
This improves the accuracy of group velocity and thus for thermal
conductivity.
- Re-implementation of third-order force constants calculation from
supercell forces, which makes the calculation much faster
- When any phonon of triplets can be on the Brillouin zone boundary, i.e.,
when a mesh number is an even number, it is more carefully treated.

28
doc/citation.rst Normal file
View File

@ -0,0 +1,28 @@
How to cite phono3py
====================
Citation of phono3py
--------------------
If you have used phono3py, please cite the following article:
- "Distributions of phonon lifetimes in Brillouin zones",
Atsushi Togo, Laurent Chaput, and Isao Tanaka, Phys. Rev. B, **91**, 094306 (2015)
::
@article{phono3py,
title = {Distributions of phonon lifetimes in Brillouin zones},
author = {Togo, Atsushi and Chaput, Laurent and Tanaka, Isao},
journal = {Phys. Rev. B},
volume = {91},
issue = {9},
pages = {094306},
numpages = {31},
year = {2015},
month = {Mar},
publisher = {American Physical Society},
doi = {10.1103/PhysRevB.91.094306},
}

514
doc/command-options.rst Normal file
View File

@ -0,0 +1,514 @@
.. _command_options:
Command options
===============
``-d``
~~~~~~
Supercell with displacements are created. Using with ``--amplitude``
option, atomic displacement distances are controlled.
``--amplitude``
~~~~~~~~~~~~~~~
Displacement distance. The default value is 0.03.
``--pa``, ``--primitive_axis``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Transformation matrix from a non-primitive cell to the primitive
cell. See phonopy ``PRIMITIVE_AXIS`` tag (``--pa`` option) at
http://phonopy.sourceforge.net/setting-tags.html#primitive-axis
``--fc2``
~~~~~~~~~
Read ``fc2.hdf5``.
``--fc3``
~~~~~~~~~
Read ``fc3.hdf5``.
``--sym_fc2``, ``--sym_fc3r``, ``--tsym``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These are used to symmetrize second- and third-order force
constants. ``--sym_fc2`` and ``--sym_fc3r`` symmetrize those in real
space by the index exchange, respectively, and ``--tsym`` symmetrizes
by the translational invariance, respectively.
..
``--sym_fc3q`` symmetrizes third-order force constants in normal
coordinates by the index exchange.
When those force constants are not read from the hdf5 files,
symmetrized force constants in real space are written into those hdf5
files.
``--dim``
~~~~~~~~~
Supercell size is specified. See the
detail at http://phonopy.sourceforge.net/setting-tags.html#dim .
``--dim_fc2``
~~~~~~~~~~~~~
Larger supercell size to calculate harmonic force constants can be
used with these options. The larger supercell size is specified by
``--dim_fc2``. When running with ``--dim_fc2`` option, a pair of
``FORCES_fC2`` and ``disp_fc2.yaml`` or ``fc2.hdf5`` has to be
prepared.
The larger supercells for fc2 in ``POSCAR`` format are created
specifying this option with ``-d`` option as
``POSCAR_FC2-xxxxx``. Simultaneously ``disp_fc2.yaml`` is created,
which is necessary to generate fc2 from ``FORCES_FC2``.
``--mesh``
~~~~~~~~~~
Phonon triples are chosen on the grid points on the sampling mesh
specified by this option. This mesh is made along reciprocal
axes and is always Gamma-centered.
..
``--md``
~~~~~~~~~
Divisors of mesh numbers. Another sampling mesh is used to calculate
phonon lifetimes. :math:`8\times 8\times 8` mesh is used for the
calculation of phonon lifetimes when it is specified, e.g.,
``--mesh="11 11 11" --md="2 2 2"``.
``--br``
~~~~~~~~
Run calculation of lattice thermal conductivity tensor with the single
mode relaxation time approximation and linearized phonon Boltzmann
equation. Without specifying ``--gp`` option, thermal conductivity is
written into ``kappa-mxxx.hdf5``.
``--sigma``
~~~~~~~~~~~
:math:`\sigma` value of Gaussian function for smearing when
calculating imaginary part of self energy. See the detail at
:ref:`brillouinzone_sum`.
Multiple :math:`\sigma` values are also specified by space separated
numerical values. This is used when we want to test several
:math:`\sigma` values simultaneously.
``--thm``
~~~~~~~~~
Tetrahedron method is used for calculation of imaginary part of self
energy.
``--tmax``, ``--tmin``, ``--tstep``, ``--ts``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Temperatures at equal interval are specified by ``--tmax``,
``--tmin``, ``--tstep``. See phonopy ``TMAX``, ``TMIN``, ``TSTEP``
tags (``--tmax``, ``--tmin``, ``--tstep`` options) at
http://phonopy.sourceforge.net/setting-tags.html#tprop-tmin-tmax-tstep .
::
% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="11 11 11" \
-c POSCAR-unitcell --br --tmin=100 --tmax=1000 --tstep=50
Specific temperatures are given by ``--ts``.
::
% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="11 11 11" \
-c POSCAR-unitcell --br --ts="200 300 400"
``--gp``
~~~~~~~~
Grid points where imaginary part of self energy is calculated. Indices
of grid points are specified by space separated numbers. The mapping
table between grid points to its indices is obtained by running with
``--loglevel=2`` option.
``--ga`` option can be used instead of ``--gp`` option. See ``--gp``
section.
``--ga``
~~~~~~~~
This option is used to specify grid points like ``--gp`` option but in
the different way. For example with ``--mesh="16 16 16"``, a q-point
of (0.5, 0.5, 0.5) is given by ``--ga="8 8 8"``. The values have to be
integers. If you want to specify the point on a path, ``--ga="0 0 0 1
1 1 2 2 2 3 3 3 ..."``, where each three values are recogninzed as a
grid point. The grid points given by ``--ga`` option are translated to
grid point indices as given by ``--gp`` option, and the values given
by ``--ga`` option will not be shown in log files.
``--wgp``
~~~~~~~~~
Irreducible grid point indices are written into
``ir_grid_points.yaml``. This information may be used when we want to
calculate imaginary part of self energy at each grid point in
conjunction with ``--gp`` option. ``grid_address-mxxx.hdf5`` is also
written. This file contains all the grid points and their grid
addresses in integers. Q-points corresponding to grid points are
calculated divided these integers by sampling mesh numbers for
respective reciprocal axes.
``--stp``
~~~~~~~~~~
Numbers of q-point triplets to be calculated for irreducible grid
points for specified sampling mesh numbers are shown. This can be used
to estimate how large a calculation is. Only those for specific grid
points are shown by using with ``--gp`` or ``--ga`` option.
``--nac``
~~~~~~~~~
Non-analytical term correction for harmonic phonons. Like as phonopy,
``BORN`` file has to be put on the same directory.
``--q_direction``
~~~~~~~~~~~~~~~~~
This is used with ``--nac`` to specify the direction to polarize in
reciprocal space. See the detail at
http://phonopy.sourceforge.net/setting-tags.html#q-direction .
``--isotope``
~~~~~~~~~~~~~
Phonon-isotope scattering is calculated.. Mass variance parameters are
read from database of the natural abundance data for elements, which
refers Laeter *et al.*, Pure Appl. Chem., **75**, 683
(2003)
::
% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br --isotope
``--mass_variances`` or ``--mv``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This option is used to include isotope effect by reading specified
mass variance parameters. For example of GaN, this may be set like
``--mv="1.97e-4 1.97e-4 0 0"``. The number of elements has to
correspond to the number of atoms in the primitive cell.
Isotope effect to thermal conductivity may be checked first running
without isotope calculation::
% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br
Then running with isotope calculation::
% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br \
--read_gamma --mv="1.97e-4 1.97e-4 0 0"
In the result hdf5 file, currently isotope scattering strength is not
written out, i.e., ``gamma`` is still imaginary part of self energy of
ph-ph scattering.
``--boundary_mfp``, ``--bmfp``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A most simple boundary scattering treatment is
implemented. :math:`v_g/L` is just used as the scattering rate, where
:math:`v_g` is the group velocity and :math:`L` is the boundary mean
free path. The value is given in micrometre. The default value, 1
metre, is just used to avoid divergence of phonon lifetime and the
contribution to the thermal conducitivity is considered negligible.
``--cf3``
~~~~~~~~~
This is used to create ``FORCES_FC3``. ``disp_fc3.yaml`` has to be
located at the current directory.
::
% phono3py --cf3 disp-{00001..00755}/vasprun.xml
``--cf2``
~~~~~~~~~
This is used to create ``FORCES_FC2``. ``disp_fc2.yaml`` has to be
located at the current directory. This is
optional. ``FORCES_FC2`` is necessary to run with ``--dim_fc2``.
::
% phono3py --cf2 disp_fc2-{00001..00002}/vasprun.xml
``--cutoff_fc3`` or ``--cutoff_fc3_distance``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This option is used to set elements of third-order force constants
zero when any pair-distance among triplet of atoms is larger than the
cut-off distance. This option may be useful to check interaction range
of third-order force constants.
``--cutoff_pair`` or ``--cutoff_pair_distance``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This option is only used together with ``-d`` option. Using this
option, number of supercells with displacements is reduced and a
special ``disp_fc3.yaml`` is created.
Cut-off pair distance is used to cut-off configurations of pairs of
displacements. ``POSCAR-xxxxx`` are not created if distance between
pair of atoms to be displaced is larger than the cut-off pair
distance. The indexing of ``POSCAR-xxxxx`` files is same as the usual
case, i.e., without this option. But using this option, a lot of
indices are missing, which are not necessary to be put for creating
``FORCES_THIRD``. Only ``vasprun.xml``'s calculated for these
reduced number of ``POSCAR-xxxxx`` have to be given at ``phono3py --cf3
...``.
::
phono3py -d --cutpair=4
After running VASP calculations,
::
phono3py --cf3 all_calculated_vasprun_xmls
``disp_fc3.yaml`` may be readable and helpful to understand this procedure.
``--write_gamma``
~~~~~~~~~~~~~~~~~
Imaginary part of self energy at harmonic phonon frequency
:math:`\Gamma_\lambda(\omega_\lambda)` (or twice of inverse phonon
lifetime) is written into file in hdf5 format. The result is written
into ``kappa-mxxx-dx-gx.hdf5`` or ``kappa-mxxx-dx-gx-bx.hdf5`` with
``--bi`` option. With ``--sigma`` option, ``-sx`` is inserted in front
of ``.hdf5``.
``--read_gamma``
~~~~~~~~~~~~~~~~
Imaginary part of self energy at harmonic phonon frequency
:math:`\Gamma_\lambda(\omega_\lambda)` (or twice of inverse phonon lifetime)
is read from ``kappa`` file in hdf5 format. Initially the usual
result file of ``kappa-mxxx-dx(-sx).hdf5`` is searched. Unless it is
found, it tries to read ``kappa`` file for each grid point,
``kappa-mxxx-dx-gx(-sx).hdf5``. Then, similarly,
``kappa-mxxx-dx-gx(-sx).hdf5`` not found,
``kappa-mxxx-dx-gx-bx(-sx).hdf5`` files for band indices are searched.
``--write_detailed_gamma``
~~~~~~~~~~~~~~~~~~~~~~~~~~
Q-point triplet contributions to imaginary part of self energy are
written into ``gamma_detail-mxxx-gx-sx.hdf5`` file. This option is
only valid in calculation of imaginary part of self energy (``--ise``)
or linewidth (``--lw``) with ``--gp`` or ``--ga`` options.
In the output file in hdf5, following keys are used to extract the
detailed information.
============================= ===========================================================================================================================
gamma_detail for ``--ise`` (temperature, sampling frequency point, band1, band2, band3, symmetry reduced set of triplets at a grid point) in THz
gamma_detail for ``--lw`` (temperature, band1, band2, band3, symmetry reduced set of triplets at a grid point) in THz
mesh Numbers of sampling mesh along reciprocal axes.
frequency_point for ``--ise`` Sampling frequency points in THz, i.e., :math:`\omega` in :math:`\Gamma_\lambda(\omega)`
temperature Temperatures in K
triplet (symmetry reduced set of triplets at a grid point, 3), Triplets are given by the grid point indices (see below).
weight Weight of each triplet to imaginary part of self energy
============================= ===========================================================================================================================
Q-points corresponding to grid point indices are calculated from
grid addresses and sampling mesh numbers given in
``grid_address-mxxx.hdf5`` that is obtained by ``--wgp`` option. A
python script to obtain q-point triplets is shown below.
::
import h5py
import numpy as np
f = h5py.File("gamma_detail-mxxx-gx-sx.hdf5")
g = h5py.File("grid_address-mxxx.hdf5")
grid_address = f['grid_address'][:]
triplets = g['triplet'][:]
mesh = f['mesh'][:]
q = grid_address[triplets] / np.array(mesh, dtype='double')
Imaginary part of self energy or linewidth/2 is recovered by the
following script::
import h5py
import numpy as np
f = h5py.File("gamma_detail-mxxx-gx-sx.hdf5")
temp = 1 # index of temperature
gamma_detail = f['gamma_detail'][:].sum(axis=-2).sum(axis=-2)
weight = f['weight'][:]
print np.dot(gamma_detail[temp], weight).sum(axis=-1) / gamma_detail.shape[-2]
..
``--write_amplitude``
~~~~~~~~~~~~~~~~~~~~~~
Interaction strengths of triplets are written into file in hdf5
format. This file can be huge and usually it is not recommended to
write it out.
``--ise``
~~~~~~~~~~
Imaginary part of self energy :math:`\Gamma_\lambda(\omega)` is
calculated with respect to :math:`\omega`. The output is written to ``gammas-mxxxx-gx-sx-tx-bx.dat``.
::
% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="16 16 16" -c POSCAR-unitcell \
--nac --q_direction="1 0 0" --gp=0 --ise --bi="4 5, 6"
``--lw``
~~~~~~~~
Linewidth :math:`2\Gamma_\lambda(\omega_\lambda)` is calculated with
respect to temperature. The output is written to
``linewidth-mxxxx-gx-sx-bx.dat``.
::
% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="16 16 16" -c POSCAR-unitcell \
--nac --q_direction="1 0 0" --gp=0 --lw --bi="4 5, 6"
``--jdos``
~~~~~~~~~~
Two classes of joint density of states (JDOS) are calculated. The
result is written into ``jdos-mxxxxxx-gx.dat``. The first column is
the frequency, and the second and third columns are the values given
as follows, respectively,
.. math::
&D_2^{(1)}(\mathbf{q}, \omega) = \frac{1}{N}
\sum_{\lambda_1,\lambda_2}
\left[\delta(\omega+\omega_{\lambda_1}-\omega_{\lambda_2}) +
\delta(\omega-\omega_{\lambda_1}+\omega_{\lambda_2}) \right], \\
&D_2^{(2)}(\mathbf{q}, \omega) = \frac{1}{N}
\sum_{\lambda_1,\lambda_2}\delta(\omega-\omega_{\lambda_1}
-\omega_{\lambda_2}).
::
% phono3py --fc2 --dim="2 2 2" -c POSCAR-unitcell --mesh="16 16 16" \
--nac --jdos --ga="0 0 0 8 8 8"
When temperatures are specified, two classes of weighted JDOS are
calculated. The result is written into ``jdos-mxxxxxx-gx-txxx.dat``,
where ``txxx`` shows the temperature. The first column is the
frequency, and the second and third columns are the values given as
follows, respectively,
.. math::
&N_2^{(1)}(\mathbf{q}, \omega) = \frac{1}{N}
\sum_{\lambda'\lambda''} \Delta(-\mathbf{q}+\mathbf{q}'+\mathbf{q}'')
(n_{\lambda'} - n_{\lambda''}) [ \delta( \omega + \omega_{\lambda'} -
\omega_{\lambda''}) - \delta( \omega - \omega_{\lambda'} +
\omega_{\lambda''})], \\
&N_2^{(2)}(\mathbf{q}, \omega) = \frac{1}{N}
\sum_{\lambda'\lambda''} \Delta(-\mathbf{q}+\mathbf{q}'+\mathbf{q}'')
(n_{\lambda'}+ n_{\lambda''}+1) \delta( \omega - \omega_{\lambda'} -
\omega_{\lambda''}).
::
% phono3py --fc2 --dim="2 2 2" -c POSCAR-unitcell --mesh="16 16 16" \
--nac --jdos --ga="0 0 0 8 8 8" --ts=300
``--num_freq_points``, ``--freq_pitch``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For spectrum like calculations of imaginary part of self energy and
JDOS, number of sampling frequency points is controlled by
``--num_freq_points`` or ``--freq_pitch``.
``--bi``
~~~~~~~~
Specify band indices. Imaginary part of self energy is calculated when
``--lw`` is not specified. The output file name is like
``gammas-mxxxxxx-gxx-bx.dat`` where ``bxbx...`` shows the band indices
used to be averaged. The calculated values at indices separated by
space are averaged, and those separated by comma are separately
calculated.
::
% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="16 16 16" \
-c POSCAR-unitcell --nac --gp="34" --bi="4 5, 6"
``--ave_pp``
~~~~~~~~~~~~
Averaged phonon-phonon interaction strength (:math:`P_{\mathbf{q}j}`)
is used to calculate imaginary part of self energy. This option works
only when ``--read_gamma`` and ``--br`` options are activated where
the averaged phonon-phonon interaction that is read from
``kappa-mxxxxx.hdf5`` file is used. Therefore the averaged
phonon-phonon interaction has to be stored before using this
option. The calculation result **overwrites** ``kappa-mxxxxx.hdf5``
file. Therefore to use this option together with ``-o`` option is
strongly recommended.
First, run full conductivity calculation,
::
% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br
Then
::
% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br \
--read_gamma --ave_pp -o ave_pp
``--const_ave_pp``
~~~~~~~~~~~~~~~~~~
Averaged phonon-phonon interaction (:math:`P_{\mathbf{q}j}`) is
replaced by this constant value. Therefore third-order force constants
are not necessary to input. The physical unit of the value is
:math:`\text{eV}^2`.
::
% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br \
--const_ave_pp=1e-10
``--gruneisen``
~~~~~~~~~~~~~~~
Mode-Gruneisen-parameters are calculated from fc3.
Mesh sampling mode::
% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="16 16 16"
-c POSCAR-unitcell --nac --gruneisen
Band path mode::
% phono3py --fc3 --fc2 --dim="2 2 2" -v \
-c POSCAR-unitcell --nac --gruneisen --band="0 0 0 0 0 1/2"

313
doc/conf.py Normal file
View File

@ -0,0 +1,313 @@
# -*- coding: utf-8 -*-
#
# phono3py documentation build configuration file, created by
# sphinx-quickstart on Wed Jun 26 13:13:14 2013.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
import sphinx_bootstrap_theme
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.pngmath']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'phono3py'
copyright = u'2015, Atsushi Togo'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.9.14'
# The full version, including alpha/beta/rc tags.
release = '0.9.14'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
# html_theme = 'default'
html_theme = 'bootstrap'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
html_theme_options = {
# Navigation bar title. (Default: ``project`` value)
'navbar_title': "Phono3py",
# Tab name for entire site. (Default: "Site")
'navbar_site_name': "Site",
# A list of tuples containing pages or urls to link to.
# Valid tuples should be in the following forms:
# (name, page) # a link to a page
# (name, "/aa/bb", 1) # a link to an arbitrary relative url
# (name, "http://example.com", True) # arbitrary absolute url
# Note the "1" or "True" value above as the third argument to indicate
# an arbitrary url.
# 'navbar_links': [
# ("Examples", "examples"),
# ("Link", "http://example.com", True),
# ],
# 'navbar_links': [
# ("Options", "command-options"),
# ],
# Render the next and previous page links in navbar. (Default: true)
'navbar_sidebarrel': True,
# Render the current pages TOC in the navbar. (Default: true)
'navbar_pagenav': True,
# Global TOC depth for "site" navbar tab. (Default: 1)
# Switching to -1 shows all levels.
'globaltoc_depth': 2,
# Include hidden TOCs in Site navbar?
#
# Note: If this is "false", you cannot have mixed ``:hidden:`` and
# non-hidden ``toctree`` directives in the same page, or else the build
# will break.
#
# Values: "true" (default) or "false"
'globaltoc_includehidden': "true",
# HTML navbar class (Default: "navbar") to attach to <div> element.
# For black navbar, do "navbar navbar-inverse"
# 'navbar_class': "navbar navbar-inverse",
'navbar_class': "navbar",
# Fix navigation bar to top of page?
# Values: "true" (default) or "false"
'navbar_fixed_top': "true",
# Location of link to source.
# Options are "nav" (default), "footer" or anything else to exclude.
# 'source_link_position': "nav",
'source_link_position': "footer",
# Bootswatch (http://bootswatch.com/) theme.
#
# Options are nothing with "" (default) or the name of a valid theme
# such as "amelia" or "cosmo".
# 'bootswatch_theme': "united",
'bootswatch_theme': "cosmo",
# Choose Bootstrap version.
# Values: "3" (default) or "2" (in quotes)
'bootstrap_version': "3",
}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
html_title = 'Phono3py v.%s' % release
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'phono3pydoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'phono3py.tex', u'phono3py manual',
u'Atsushi Togo', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'phono3py', u'phono3py Documentation',
[u'Atsushi Togo'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'phono3py', u'phono3py Documentation',
u'Atsushi Togo', 'phono3py', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'

50
doc/index.rst Normal file
View File

@ -0,0 +1,50 @@
=======================================================
Welcome to phono3py
=======================================================
This software calculates phonon-phonon interaction related properties:
- Lattice thermal conductivity
- Phonon lifetime/linewidth
- Imaginary part of self energy at the lowest order
- Joint density of states (JDOS) and weighted-JDOS
The theoretical background is summarized in the paper found at
http://dx.doi.org/10.1103/PhysRevB.91.094306 .
Examples are found in ``example-phono3py`` directory.
Documentation
=============
.. toctree::
:maxdepth: 1
workflow
install
output-files
command-options
auxiliary-tools
citation
changelog
Mailing list
============
For questions, bug reports, and comments, please visit following
mailing list:
https://lists.sourceforge.net/lists/listinfo/phonopy-users
Message body including attached files has to be smaller than 300 KB.
License
=======
New BSD
Contact
=======
* Author: `Atsushi Togo <http://atztogo.github.io/>`_

79
doc/install.rst Normal file
View File

@ -0,0 +1,79 @@
.. _install:
Installation
=============
System requirement
-------------------
The following python libraries are required.
::
python-dev python-numpy python-yaml python-h5py python-matplotlib
``python-matplotlib`` is optional, but it is strongly recommended to
install it. The OpenMP library is necessary for multithreding
support. The GNU OpenMP library is ``libgomp1``. In the case of
ubuntu linux, these are installed using the package manager::
% sudo apt-get install python-dev python-numpy python-matplotlib \
python-yaml python-h5py libgomp1 liblapacke-dev
After the versions of Ubuntu-12.10, lapacke
(http://www.netlib.org/lapack/lapacke.html) can be installed from the
package manager (``liblapacke`` and ``liblapacke-dev``), but in older
versions of ubuntu, or in other environments, you may have to compile
lapacke by yourself. The compilation procedure is found at the lapacke
web site. After creating the lapacke library, ``liblapacke.a`` (or the
dynamic link library) ``setup3.py`` must be properly modified to link
it. As an example, the procedure of compiling lapacke is shown below.
::
% tar xvfz lapack-3.5.0.tgz
% cd lapack-3.5.0
% cp make.inc.example make.inc
% make lapackelib
Multithreading support
------------------------
Phono3py supports OpenMP multithreading and most users will need it,
otherwise the calculation may take long time. However, without special
OpenMP environment variables (``-lgomp`` and ``-fopenmp`` in
``setup3.py``), phono3py will be compiled without the OpenMP
multithreding support.
Installation procedure
------------------------
Download the latest version from
http://sourceforge.net/projects/phonopy/files/phono3py/ and extract it
somewhere. The version number here is not related to the version
number of harmonic (usual) phonopy. The harmonic phonopy included in
this package is a development version and can be different from that
distributed at sourceforge.net.
In the directory, open ``setup3.py`` and set the location of
lapacke. If you installed lapacke from the package manager, you can
remove the line related to lapacke. If you compiled it by yourself,
set the location of it. Then run ``setup3.py`` (for anharmonic
phonopy)::
% python setup3.py install --home=.
In this way to setup, ``PYTHONPATH`` has to be set so that python can
find harmonic and anharmonic phonopy libraries. If you have been
already a user of phonopy, the original phonopy version distributed at
sourceforge.net will be removed from the list of the ``PYTHONPATH``.
The ``PYTHONPATH`` setting depends on shells that you use. For example
in bash or zsh::
export PYTHONPATH=~/phonopy-0.9.9/lib/python
or::
export PYTHONPATH=$PYTHONPATH:~/phonopy-0.9.9/lib/python

198
doc/output-files.rst Normal file
View File

@ -0,0 +1,198 @@
.. _output_files:
Output files
============
How to read the results stored in hdf5 files
-----------------------------------------------
How to use HDF5 python library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is assumed that ``python-h5py`` is installed on the computer you
interactively use. In the following, how to see the contents of
``.hdf5`` files in the interactive mode of Python. Usually for running
interactive python, ``ipython`` is recommended to use but not the
plain python. In the following example, an MgO result of thermal
conductivity calculation is loaded and thermal conductivity tensor at
300 K is watched.
::
In [1]: import h5py
In [2]: f = h5py.File("kappa-m111111.hdf5")
In [3]: f.keys()
Out[3]:
[u'frequency',
u'gamma',
u'group_velocity',
u'heat_capacity',
u'kappa',
u'mode_kappa',
u'ave_pp',
u'qpoint',
u'temperature',
u'weight']
In [4]: f['kappa'].shape
Out[4]: (101, 6)
In [5]: f['kappa'][:]
Out[5]:
array([[ 0.00000000e+00, 0.00000000e+00, 0.00000000e+00,
0.00000000e+00, 0.00000000e+00, 0.00000000e+00],
[ 5.86834069e+03, 5.86834069e+03, 5.86834069e+03,
1.20936823e-15, 0.00000000e+00, -2.05720313e-15],
[ 1.37552313e+03, 1.37552313e+03, 1.37552313e+03,
2.81132320e-16, 0.00000000e+00, -5.00076366e-16],
...,
[ 6.56974871e+00, 6.56974871e+00, 6.56974871e+00,
1.76632276e-18, 0.00000000e+00, -2.30450472e-18],
[ 6.50316555e+00, 6.50316555e+00, 6.50316555e+00,
1.74843437e-18, 0.00000000e+00, -2.28116103e-18],
[ 6.43792061e+00, 6.43792061e+00, 6.43792061e+00,
1.73090513e-18, 0.00000000e+00, -2.25828616e-18]])
In [6]: f['temperature'][:]
Out[6]:
array([ 0., 10., 20., 30., 40., 50., 60., 70.,
80., 90., 100., 110., 120., 130., 140., 150.,
160., 170., 180., 190., 200., 210., 220., 230.,
240., 250., 260., 270., 280., 290., 300., 310.,
320., 330., 340., 350., 360., 370., 380., 390.,
400., 410., 420., 430., 440., 450., 460., 470.,
480., 490., 500., 510., 520., 530., 540., 550.,
560., 570., 580., 590., 600., 610., 620., 630.,
640., 650., 660., 670., 680., 690., 700., 710.,
720., 730., 740., 750., 760., 770., 780., 790.,
800., 810., 820., 830., 840., 850., 860., 870.,
880., 890., 900., 910., 920., 930., 940., 950.,
960., 970., 980., 990., 1000.])
In [7]: f['kappa'][30]
Out[7]:
array([ 2.18146513e+01, 2.18146513e+01, 2.18146513e+01,
5.84389577e-18, 0.00000000e+00, -7.63278476e-18])
Details of ``kappa-*.hdf5`` file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Files name, e.g. ``kappa-m323220.hdf5``, is determined by some
specific options. ``mxxx``, show the numbers of sampling
mesh. ``sxxx`` and ``gxxx`` appear optionally. ``sxxx`` gives the
smearing width in the smearing method for Brillouin zone integration
for phonon lifetime, and ``gxxx`` denotes the grid number. Using the
command option of ``-o``, the file name can be modified slightly. For
example ``-o nac`` gives ``kappa-m323220.nac.hdf5`` to
memorize the option ``--nac`` was used.
Currently ``kappa-*.hdf5`` file (not for the specific grid points)
contains the properties shown below.
frequency
~~~~~~~~~
Phonon frequencies. The physical unit is THz (without :math:`2\pi`)
The array shape is (irreducible q-point, phonon band).
gamma
~~~~~
Imaginary part of self energy. The physical unit is THz
(without :math:`2\pi`).
The array shape for all grid-points (irreducible q-points) is
(temperature, irreducible q-point, phonon band).
The array shape for a specific grid-point is
(temperature, phonon band).
This is read when ``--read_gamma`` option is specified.
gamma_isotope
~~~~~~~~~~~~~~
Isotope scattering of :math:`1/2\tau^\mathrm{iso}_\lambda`.
The physical unit is same as that of gamma.
The array shape is same as that of frequency.
This is NOT read even when ``--read_gamma`` option is specified.
group_velocity
~~~~~~~~~~~~~~
Phonon group velocity, :math:`\nabla_\mathbf{q}\omega_\lambda`. The
physical unit is :math:`\text{THz}\cdot\text{\AA}` (without
:math:`2\pi`).
The array shape is (irreducible q-point, phonon band, 3 = Cartesian coordinates).
heat_capacity
~~~~~~~~~~~~~
Mode-heat-capacity defined by
.. math::
C_\lambda = k_\mathrm{B}
\left(\frac{\hbar\omega_\lambda}{k_\mathrm{B} T} \right)^2
\frac{\exp(\hbar\omega_\lambda/k_\mathrm{B}
T)}{[\exp(\hbar\omega_\lambda/k_\mathrm{B} T)-1]^2}.
The physical unit is eV/K.
The array shape is (temperature, irreducible q-point, phonon band).
kappa
~~~~~
Thermal conductivity tensor. The physical unit is W/m-K.
The array shape is (temperature, 6 = (xx, yy, zz, yz, xz, xy)).
mode_kappa
~~~~~~~~~~
Thermal conductivity tensor at k-star. The physical unit is
W/m-K. Each tensor element is the sum of tensor elements on the
members of the k-star, i.e., equivalent q-points by crystallographic
point group and time reversal symmetry.
The array shape is (temperature, irreducible q-point, phonon band, 6 =
(xx, yy, zz, yz, xz, xy)).
q-point
~~~~~~~
Irreducible q-points in reduced coordinates.
The array shape is (irreducible q-point, 3 = reduced
coordinates in reciprocal space).
temperature
~~~~~~~~~~~
Temperatures where thermal conductivities are calculated. The physical
unit is K.
weight
~~~~~~
Weights corresponding to irreducible q-points. Sum of weights equals to
the number of (coarse) mesh grid points.
ave_pp
~~~~~~~
Averaged phonon-phonon interaction in :math:`\text{eV}^2`,
:math:`P_{\mathbf{q}j}`:
.. math::
P_{\mathbf{q}j} = \frac{1}{(3n_\mathrm{a})^2} \sum_{\lambda'\lambda''}
|\Phi_{\lambda\lambda'\lambda''}|^2.

189
doc/workflow.rst Normal file
View File

@ -0,0 +1,189 @@
.. _workflow:
Work flow
==========
Calculation procedure
----------------------
1. Create POSCARs with displacements
This is the same way as usual phonopy::
% phono3py -d --dim="2 2 2" -c POSCAR-unitcell
``disp_fc3.yaml`` and ``POSCAR-xxxxx`` files are created.
If you want to use larger supercell size for
second-order force constants (fc2) calculation than that
for third-order force constants (fc3) calculation::
% phono3py -d --dim_fc2="4 4 4" --dim="2 2 2" -c POSCAR-unitcell
In this case, ``disp_fc2.yaml`` and ``POSCAR_FC2-xxxxx`` files are
also created.
2. Run VASP for supercell force calculations
To calculate forces on atoms in supercells, ``POSCAR-xxxxx`` (and
``POSCAR_FC2-xxxxx`` if they exist) are used as VASP (or any force
calculator) calculations.
It is supposed that each force calculation is executed under the
directory named ``disp-xxxxx`` (and ``disp_fc2-xxxxx``), where
``xxxxx`` is sequential number.
3. Collect ``vasprun.xml``'s
When VASP is used as the force calculator, force sets to calculate
fc3 and fc2 are created as follows.
::
% phono3py --cf3 disp-{00001..00755}/vasprun.xml
where 0755 is an example of the index of the last displacement
supercell. To perform this collection, ``disp_fc3.yaml`` created at
step 1 is required. Then ``FORCES_FC3`` is created.
When you use larger supercell for fc2 calculation::
% phono3py --cf2 disp_fc2-{00001..00002}/vasprun.xml
``disp_fc2.yaml`` is necessary in this case and ``FORCES_FC2`` is
created.
4. Create fc2.hdf and fc3.hdf
::
% phono3py --dim="2 2 2" -c POSCAR-unitcell
``fc2.hdf5`` and ``fc3.hdf5`` are created from ``FORCES_FC3`` and
``disp_fc3.yaml``. This step is not mandatory, but you can avoid
calculating fc2 and fc3 at every run time.
When you use larger supercell for fc2 calculation::
% phono3py --dim_fc2="4 4 4" --dim="2 2 2" -c POSCAR-unitcell
Similarly ``fc2.hdf5`` and ``fc3.hdf5`` are created from ``FORCES_FC3``,
``FORCES_FC2``, ``disp_fc3.yaml``, and ``disp_fc2.yaml``.
5. Thermal conductivity calculation
An example of thermal conductivity calculation is::
% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="11 11 11" \
-c POSCAR-unitcell --br --thm
or with larger supercell for fc2::
% phono3py --fc3 --fc2 --dim_fc2="4 4 4" --dim="2 2 2" -v --mesh="11 11 11" \
-c POSCAR-unitcell --br --thm
This calculation may take very long time. ``--thm`` invokes a
tetrahedron method for Brillouin zone integration for phonon
lifetime calculation. Instead, ``--sigma`` option can be used with
the smearing widths.
In this command, phonon lifetimes at many grid points are
calculated in series. The phonon lifetime calculation at each grid
point can be separately calculated since they
are independent and no communication is necessary at the
computation. The procedure is as follows:
First run the same command with the addition option of ``--wgp``::
% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="11 11 11" \
-c POSCAR-unitcell --br --thm --wgp
``ir_grid_points.yaml`` is obtained. In this file, irreducible
q-points are shown. Then distribute calculations of phonon
lifetimes on grid points with ``--write_gamma`` option by::
% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="11 11 11" \
-c POSCAR-unitcell --br --thm --write_gamma --gp="[grid ponit(s)]"
After finishing all distributed calculations, run with
``--read_gamma`` option::
% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="11 11 11" \
-c POSCAR-unitcell --br --thm --read_gamma
Once this calculation runs without problem, separately calculated
hdf5 files on grid points are no more necessary and may be deleted.
Convergence check in calculation
---------------------------------
.. _brillouinzone_sum:
Brillouin zone summation
~~~~~~~~~~~~~~~~~~~~~~~~~
Brillouin zone sums appear at different two points for phonon lifetime
calculation. First it is used for the Fourier transform of force
constans, and then to obtain imaginary part of phonon-self-energy. In
the numerical calculation, uniform sampling meshes are employed for
these summations. To obtain more accurate result, it is always better
to use denser meshes. But the denser mesh requires more
computationally demanding.
The second Brillouin zone sum contains delta functions. In phono3py
calculation, a linear tetrahedron method (``--thm``) and a smearing
method (``--sigma``) can be used for this Brillouin zone
integration. Smearing parameter is used to approximate delta
functions. Small ``sigma`` value is better to describe the detailed
structure of three-phonon-space, but it requires a denser mesh to
converge.
..
The first and second meshes have to be same or the first
mesh is integral multiple of the second mesh, i.e., the first and
second meshes have to overlap and the first mesh is the same as or
denser than the second mesh.
To check the convergence with respect to the ``sigma`` value, multiple
sigma values can be set. This can be computationally efficient, since
it is avoided to re-calculate phonon-phonon interaction strength for
different ``sigma`` values in this case.
Convergence with respect to the sampling mesh and smearing parameter
strongly depends on materials. A :math:`20\times 20\times 20` sampling
mesh (or 8000 reducible sampling points) and 0.1 THz smearing value
for reciprocal of the volume of an atom may be a good starting choice.
The tetrahedron method requires no parameter such as the smearing
width, therefore it is easier to use than the smearing method and
recommended to use. A drawback of using the tetrahedron method is that
it is slower and consumes more memory space.
Numerical quality of force constants
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Third-order force constants are much weaker to numerical noise of a
force calculator than second-order force constants. Therefore
supercell force calculations have to be done by enough high numerical
accuracy.
The phono3py default displacement distance is 0.03
:math:`\text{\AA}`. In some cases, accurate result may not be obtained
due to the numerical noise of the force calculator. Usually increasing
the displacement distance by ``--amplitude`` option reduces
the numerical noise, but increases error from higher order anharmonicity.
It is not easy to check the numerical quality of force constants. It
is suggested firstly to check deviation from the translational
invariance condition by watching output where the output lines start
with ``max drift of ...``. The drift value smaller than 1 may be
acceptable but of course it is dependent on cases. The most practical
way may be to compare thermal conductivities calculated with and
without symmetrizing third-order force constants by ``--sym_fc3r``,
``--sym_fc2``, and ``--tsym`` options.
Mode-Gruneisen-parameters calculated from third-order force constants
look very sensitive to numerical noise near the Gamma point. Therefore
symmetrization is recommended.