mirror of https://github.com/phonopy/phono3py.git
Update phono3py document
This commit is contained in:
Atsushi Togo
parent
0f4ba0b3b1
commit
3c89b37d1f
|
|
@ -51,9 +51,17 @@ calculate 2nd order force constants for the larger supercell size and
|
|||
these force calculations have to be done in addition to the usual
|
||||
force calculations for 3rd order force constants.
|
||||
|
||||
::
|
||||
|
||||
phono3py -d --dim="2 2 2" --dim_fc2="4 4 4" -c POSCAR-unitcell
|
||||
|
||||
After the force calculations, ``--cf2`` option is used to create
|
||||
``FORCES_FC2``.
|
||||
|
||||
::
|
||||
|
||||
phono3py --cf2 disp-{001,002}/vasprun.xml
|
||||
|
||||
To calculate 2nd order force constants for the larger supercell size,
|
||||
``FORCES_FC2`` and ``disp_fc2.yaml`` are necessary. Whenever running
|
||||
phono3py for the larger 2nd order force constants, ``--dim_fc2``
|
||||
|
|
@ -62,6 +70,10 @@ running phono3py contains the 2nd order force constants with
|
|||
larger supercell size. The filename is the same as that created in the
|
||||
usual phono3py run without ``--dim_fc2`` option.
|
||||
|
||||
::
|
||||
|
||||
phono3py --dim="2 2 2" --dim_fc2="4 4 4" -c POSCAR-unitcell ... (many options)
|
||||
|
||||
``--pa``, ``--primitive_axis``: Transformation matrix to primitive cell
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
|
|||
|
|
@ -29,11 +29,13 @@ Documentation
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
workflow
|
||||
install
|
||||
output-files
|
||||
command-options
|
||||
interfaces
|
||||
vasp
|
||||
pwscf
|
||||
command-options
|
||||
output-files
|
||||
tips
|
||||
auxiliary-tools
|
||||
citation
|
||||
changelog
|
||||
|
|
|
|||
|
|
@ -64,22 +64,36 @@ 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)::
|
||||
set the location of it. Before running ``setup3.py``, if you install
|
||||
phonopy (not phono3py), you need to uninstall phonopy since
|
||||
``setup3.py`` installs phonopy, too. Then
|
||||
|
||||
::
|
||||
|
||||
% python setup3.py install --user
|
||||
|
||||
Or you can install phono3py on the current directory by
|
||||
|
||||
::
|
||||
|
||||
% 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::
|
||||
already a user of phonopy, ``PYTHONPATH`` for the original phonopy
|
||||
version has to be removed. The ``PYTHONPATH`` setting depends on
|
||||
shells that you use. For example in bash or zsh::
|
||||
|
||||
export PYTHONPATH=~/phonopy-1.10.3/lib/python
|
||||
export PYTHONPATH=~/phonopy-1.11.1/lib/python
|
||||
|
||||
or::
|
||||
|
||||
export PYTHONPATH=$PYTHONPATH:~/phonopy-1.10.3/lib/python
|
||||
|
||||
export PYTHONPATH=$PYTHONPATH:~/phonopy-1.11.1/lib/python
|
||||
|
||||
Phono3py command is installed under ``bin`` directory. The location of
|
||||
``bin`` directory is depending on ``--user`` or ``--home`` scheme when
|
||||
running ``setup3.py``. In the former case, it depends on your
|
||||
operation system, e.g., ``~/.local/bin`` for Ubuntu linux and
|
||||
``~/Library/Python/2.7`` for Mac (& python2.7). In the latter case,
|
||||
``bin`` directory is found on the current directory if it was
|
||||
``--home=.``.
|
||||
|
|
|
|||
|
|
@ -8,6 +8,12 @@ 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``.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
vasp
|
||||
pwscf
|
||||
|
||||
Calculator specific behaviors
|
||||
------------------------------
|
||||
|
||||
|
|
@ -51,77 +57,4 @@ Default displacement distances created by ``-d`` option without
|
|||
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
|
||||
-------------------------
|
||||
|
||||
Quantum espresso package itself has a set of the force constants
|
||||
calculation environment based on DFPT. But the document here explains how
|
||||
to calculate phonon-phonon interaction and related properties using
|
||||
phono3py, i.e., using the finite displacement and supercell approach.
|
||||
|
||||
An example for pwscf is found in the ``example-phono3py/Si-pwscf`` directory.
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,72 @@
|
|||
.. _pwscf_interface:
|
||||
|
||||
Pwscf & phono3py calculation
|
||||
=============================
|
||||
|
||||
Quantum espresso package itself has a set of the force constants
|
||||
calculation environment based on DFPT. But the document here explains how
|
||||
to calculate phonon-phonon interaction and related properties using
|
||||
phono3py, i.e., using the finite displacement and supercell approach.
|
||||
|
||||
An example for pwscf is found in the ``example-phono3py/Si-pwscf`` directory.
|
||||
|
||||
To invoke the Pwscf interface, ``--pwscf`` option has to be always
|
||||
specified::
|
||||
|
||||
% phono3py --pwscf [options] [arguments]
|
||||
|
||||
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).
|
||||
|
||||
.. _pwscf_workflow:
|
||||
|
||||
Workflow
|
||||
---------
|
||||
|
||||
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
|
||||
|
|
@ -0,0 +1,77 @@
|
|||
.. _tips:
|
||||
|
||||
Tips
|
||||
=====
|
||||
|
||||
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``, 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.
|
||||
|
||||
..
|
||||
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.
|
||||
|
||||
|
|
@ -1,10 +1,12 @@
|
|||
.. _workflow:
|
||||
.. _vasp_interface:
|
||||
|
||||
Work flow
|
||||
==========
|
||||
VASP & phono3py calculation
|
||||
=============================
|
||||
|
||||
Calculation procedure
|
||||
----------------------
|
||||
.. _vasp_workflow:
|
||||
|
||||
Workflow
|
||||
---------
|
||||
|
||||
1. Create POSCARs with displacements
|
||||
|
||||
|
|
@ -114,76 +116,3 @@ Calculation procedure
|
|||
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``, 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.
|
||||
|
||||
..
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue