Update document for v1.10.4

This commit is contained in:
Atsushi Togo 2016-02-05 13:43:50 +09:00
parent e75f29ff5d
commit 10cde4ef34
7 changed files with 282 additions and 46 deletions

View File

@ -3,33 +3,38 @@
Command options
===============
.. _create_displacements_option:
``-d``
~~~~~~
Supercell with displacements are created. Using with ``--amplitude``
option, atomic displacement distances are controlled.
option, atomic displacement distances are controlled. With this
option, files for supercells with displacements and ``disp_fc3.yaml``
file are created.
``--amplitude``
~~~~~~~~~~~~~~~
Displacement distance. The default value is 0.03.
Displacement distance. The default value depends on calculator. See
:ref:`default_displacement_distance_for_calculator`.
``--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
http://atztogo.github.io/phonopy/setting-tags.html#primitive-axis
``--fc2``
~~~~~~~~~
Read ``fc2.hdf5``.
Read 2nd order force constants from ``fc2.hdf5``.
``--fc3``
~~~~~~~~~
Read ``fc3.hdf5``.
Read 3rd order force constants from ``fc3.hdf5``.
``--sym_fc2``, ``--sym_fc3r``, ``--tsym``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -51,7 +56,9 @@ files.
~~~~~~~~~
Supercell size is specified. See the
detail at http://phonopy.sourceforge.net/setting-tags.html#dim .
detail at http://atztogo.github.io/phonopy/setting-tags.html#dim .
.. _dim_fc2_option:
``--dim_fc2``
~~~~~~~~~~~~~
@ -107,7 +114,9 @@ numerical values. This is used when we want to test several
~~~~~~~~~
Tetrahedron method is used for calculation of imaginary part of self
energy.
energy. This is the default option. Therefore it is not necessary to
specify this unless both results by tetrahedron method and
smearing method in one time execution are expected.
``--tmax``, ``--tmin``, ``--tstep``, ``--ts``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -115,7 +124,7 @@ energy.
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 .
http://atztogo.github.io/phonopy/setting-tags.html#tprop-tmin-tmax-tstep .
::
@ -177,14 +186,16 @@ points are shown by using with ``--gp`` or ``--ga`` option.
~~~~~~~~~
Non-analytical term correction for harmonic phonons. Like as phonopy,
``BORN`` file has to be put on the same directory.
``BORN`` file has to be put on the same directory. Always the default
value of unit conversion factor is used even if it is written in the
first line of ``BORN`` file.
``--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 .
http://atztogo.github.io/phonopy/setting-tags.html#q-direction .
``--isotope``
~~~~~~~~~~~~~
@ -230,6 +241,8 @@ 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_option:
``--cf3``
~~~~~~~~~
@ -240,6 +253,8 @@ located at the current directory.
% phono3py --cf3 disp-{00001..00755}/vasprun.xml
.. _cf2_option:
``--cf2``
~~~~~~~~~
@ -288,6 +303,8 @@ After running VASP calculations,
``disp_fc3.yaml`` may be readable and helpful to understand this procedure.
.. _write_gamma_option:
``--write_gamma``
~~~~~~~~~~~~~~~~~
@ -310,6 +327,8 @@ found, it tries to read ``kappa`` file for each grid point,
``kappa-mxxx-dx-gx(-sx).hdf5`` not found,
``kappa-mxxx-dx-gx-bx(-sx).hdf5`` files for band indices are searched.
.. _write_detailed_gamma_option:
``--write_detailed_gamma``
~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -368,35 +387,43 @@ following script::
format. This file can be huge and usually it is not recommended to
write it out.
.. _ise_option:
``--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``.
calculated with respect to :math:`\omega`. The output is written to
``gammas-mxxxx-gx-sx-tx-bx.dat`` in THz (without :math:`2\pi`).
::
% 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_option:
``--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``.
``linewidth-mxxxx-gx-sx-bx.dat`` in THz (without :math:`2\pi`).
::
% 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_option:
``--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,
result is written into ``jdos-mxxxxxx-gx.dat`` in THz (without
:math:`2\pi`). The first column is the frequency, and the second and
third columns are the values given as follows, respectively,
.. math::

View File

@ -49,9 +49,9 @@ copyright = u'2015, Atsushi Togo'
# built documents.
#
# The short X.Y version.
version = '0.9.14'
version = '1.10.3'
# The full version, including alpha/beta/rc tags.
release = '0.9.14'
release = '1.10.3'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

View File

@ -10,7 +10,8 @@ This software calculates phonon-phonon interaction related properties:
- 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 .
http://dx.doi.org/10.1103/PhysRevB.91.094306 or the draft in arxiv at
http://arxiv.org/abs/1501.00691 .
Examples are found in ``example-phono3py`` directory.
@ -24,6 +25,7 @@ Documentation
install
output-files
command-options
interfaces
auxiliary-tools
citation
changelog

View File

@ -20,14 +20,15 @@ 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
In the versions of Ubuntu-12.10 or later, 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.
package manager (``liblapacke`` and ``liblapacke-dev``). But in the
older versions of Ubuntu or in the other environments, e.g., Mac, 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.
::
@ -40,10 +41,11 @@ 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.
otherwise the calculation may take long time. The library options used
for GCC, ``-lgomp`` and ``-fopenmp``, are written in ``setup3.py``,
but for the other compilers, you may have to change them. If you need
to compile without the OpenMP support, you can remove these options in
``setup3.py``.
Installation procedure
------------------------
@ -70,10 +72,10 @@ 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
export PYTHONPATH=~/phonopy-1.10.3/lib/python
or::
export PYTHONPATH=$PYTHONPATH:~/phonopy-0.9.9/lib/python
export PYTHONPATH=$PYTHONPATH:~/phonopy-1.10.3/lib/python

120
doc/interfaces.rst Normal file
View File

@ -0,0 +1,120 @@
Interfaces to calculators
==========================
Currently the built-in interfaces for VASP and Pwscf are
prepared. VASP is the default interface and no special option is
necessary to invoke it, but for the other interfaces, each special
option has to be specified, e.g. ``--pwscf``.
.. _calculator_interfaces:
Calculator specific behaviors
------------------------------
Physical unit
^^^^^^^^^^^^^^
The interfaces for VASP and Pwscf are built in to the phono3py command.
For each calculator, each physical unit system is used. The physical
unit systems used for the calculators are summarized below.
::
| unit-cell FORCES_FC3 disp_fc3.yaml
-----------------------------------------------
VASP | Angstrom eV/Angstrom Angstrom
Pwscf | au (bohr) Ry/au au
``FORCES_FC2`` and ``disp_fc2.yaml`` have the same physical units as
``FORCES_FC3`` and ``disp_fc3.yaml``, respectively.
.. _default_unit_cell_file_name_for_calculator:
Default unit cell file name
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Default unit cell file names are also changed according to the calculators::
VASP | POSCAR
Pwscf | unitcell.in
.. _default_displacement_distance_for_calculator:
Default displacement distance created
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Default displacement distances created by ``-d`` option without
``--amplitude`` option are respectively as follows::
VASP | 0.03 Angstrom
Pwscf | 0.06 au (bohr)
Usage of VASP interface
-------------------------
The VASP interface is the default one. Therefore how to use is found
in :ref:`workflow`.
Usage of Pwscf interface
-------------------------
To invoke the Pwscf interface, ``--pwscf`` option has to be always
specified::
% phono3py --pwscf [options] [arguments]
The usage of the Pwscf interface is almost the same as that of the
default case shown in :ref:`workflow`.
When the file name of the unit cell is different from the default one
(see :ref:`default_unit_cell_file_name_for_calculator`), ``-c`` option
is used to specify the file name. Pwscf unit cell file parser used in
phono3py is the same as that in phonopy. It can read
only limited number of keywords that are shown in the phonopy web site
(http://atztogo.github.io/phonopy/pwscf.html#pwscf-interface).
1. Create supercells with displacements
::
% phono3py --pwscf -d --dim="2 2 2" -c Si.in
In this example, probably 111 different supercells with
displacements are created. Supercell files (``supercell-xxx.in``)
are created but they contain only the crystal
structures. Calculation setting has to be added before running the
calculation.
2. Run Pwscf for supercell force calculations
Let's assume that the calculations have been made in ``disp-xxx``
directories with the file names of ``Si-supercell.in``. Then after
finishing those calculations, ``Si-supercell.out`` may be created
in each directory.
3. Collect forces
``FORCES_FC3`` is obtained with ``--cf3`` options collecting the
forces on atoms in Pwscf calculation results::
% phono3py --pwscf --cf3 disp-00001/Si-supercell.out disp-00002/Si-supercell.out ...
or in recent bash or zsh::
% phono3py --pwscf --cf3 disp-{00001..00111}/Si-supercell.out
``disp_fc3.yaml`` is used to create ``FORCES_FC3``, therefore it
must exist in current directory.
4) Calculate 3rd and 2nd order force constants
``fc3.hdf5`` and ``fc2.hdf5`` files are created by::
% phono3py --pwscf --dim="2 2 2" -c Si.in --sym_fc3r --sym_fc2 --tsym
5) Calculate lattice thermal conductivity, e.g., by::
% phono3py --pwscf --dim="2 2 2" -c Si.in --pa="0 1/2 1/2 1/2 0 1/2 1/2 1/2 0" \
--mesh="11 11 11" --fc3 --fc2 --br

View File

@ -3,6 +3,89 @@
Output files
============
The calculation results are written into files. Mostly the data are
stored in HDF5 format. In the following sections, how to read the data
from HDF5 files is shown.
Intermediate text files
------------------------
``disp_fc3.yaml``
^^^^^^^^^^^^^^^^^^
This is created with ``-d`` option. See :ref:`create_displacements_option`.
``disp_fc2.yaml``
^^^^^^^^^^^^^^^^^^
This is created with ``-d`` option with ``--dim_fc2`` option. See
:ref:`dim_fc2_option`.
``FORCES_FC3``
^^^^^^^^^^^^^^^
This is created with ``--cf3`` option. See :ref:`cf3_option`.
``FORCES_FC2``
^^^^^^^^^^^^^^^
This is created with ``--cf2`` option. See :ref:`cf2_option` and
:ref:`dim_fc2_option`.
HDF5 files
-------------
``kappa-*.hdf5``
^^^^^^^^^^^^^^^^^
See the detail at :ref:`kappa_hdf5_file`.
``fc3.hdf5``
^^^^^^^^^^^^^
Third order force constants are stored in :math:`\mathrm{eV}/\mathrm{\AA}^3`.
``fc2.hdf5``
^^^^^^^^^^^^^
Second order force constants are stored in
:math:`\mathrm{eV}/\mathrm{\AA}^3`.
``gamma-*.hdf5``
^^^^^^^^^^^^^^^^^
Imaginary parts of self energies at harmonic phonon frequencies
(:math:`\Gamma_\lambda(\omega_\lambda)` = half linewidths) are stored in
THz. See :ref:`write_gamma_option`.
``gamma_detail-*.hdf5``
^^^^^^^^^^^^^^^^^^^^^^^^
Q-point triplet contributions to imaginary parts of self energies at
phonon frequencies (half linewidths) are stored in THz. See
:ref:`write_detailed_gamma_option`.
Simple text file
-----------------
``gammas-*.dat``
^^^^^^^^^^^^^^^^^
Imaginary parts of self energies with respect to frequency
:math:`\Gamma_\lambda(\omega)` are stored in THz. See :ref:`ise_option`.
``jdos-*.dat``
^^^^^^^^^^^^^^^
Joint densities of states are stored in Thz. See :ref:`jdos_option`.
``linewidth-*.dat``
^^^^^^^^^^^^^^^^^^^^
Linewidths (FWHM) at temperatures are stored in THz. See :ref:`lw_option`.
How to read the results stored in hdf5 files
-----------------------------------------------
@ -78,6 +161,8 @@ conductivity calculation is loaded and thermal conductivity tensor at
5.84389577e-18, 0.00000000e+00, -7.63278476e-18])
.. _kappa_hdf5_file:
Details of ``kappa-*.hdf5`` file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

View File

@ -74,18 +74,18 @@ Calculation procedure
An example of thermal conductivity calculation is::
% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="11 11 11" \
-c POSCAR-unitcell --br --thm
% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="11 11 11" \
-c POSCAR-unitcell --br
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
% phono3py --fc3 --fc2 --dim_fc2="4 4 4" --dim="2 2 2" --mesh="11 11 11" \
-c POSCAR-unitcell --br
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.
lifetime calculation, which is the default option. 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
@ -95,21 +95,21 @@ Calculation procedure
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
% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="11 11 11" \
-c POSCAR-unitcell --br --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)]"
% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="11 11 11" \
-c POSCAR-unitcell --br --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
% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="11 11 11" \
-c POSCAR-unitcell --br --read_gamma
Once this calculation runs without problem, separately calculated
hdf5 files on grid points are no more necessary and may be deleted.
@ -132,9 +132,9 @@ 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
calculation, a linear tetrahedron method (``--thm``, default option)
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.