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

Update version number (v2.1.0) and changelog.

This commit is contained in:
Atsushi Togo 2021-11-03 09:56:21 +09:00
parent 5fea85e0c6
commit 28dc6efe47
5 changed files with 358 additions and 392 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/Si-coleigplot.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 21 KiB

390
doc/changelog.md
View File

@ -1,21 +1,34 @@
(changelog)=
# Change Log
## Nov-3-2021: Version 2.1.0
- Fix of a critical bung in the direct solution. See the detail as commit log of
[54d4ddab](https://github.com/phonopy/phono3py/commit/54d4ddab6f3fbf9435bdfe8b27757be1d5c4ebf6).
- Aiming modernizing phono3py code, required python version and package versions
were changed to
- Python >= 3.6
- numpy >= 1.11
- matplotlib >= 2.0
- For developers, flake8, black, pydocstyle, and isort were introduced. See
`REAEME.md` and `.pre-commit-config.yaml`.
## Jul-22-2021: Version 2.0.0
This is a major version release. There are some backword-incompatible changes.
1. Grid point indexing system to address grid points of q-points
is changed.
2. Array data types of most of the integer arrays are changed to
`dtype='int_'` from `dtype='intc'`.
1. Grid point indexing system to address grid points of q-points is changed.
2. Array data types of most of the integer arrays are changed to `dtype='int_'`
from `dtype='intc'`.
3. Python 3.5 or later is required.
To emulate the version 1.x behaviour in `phono3py` command,
try `--v1` option. To emurate the version 1.x behaviour in API,
specify `store_dense_gp_map=False`
and `store_dense_svecs=False` in instatiation of `Phono3py` class
or phon3py loader.
To emulate the version 1.x behaviour in `phono3py` command, try `--v1` option.
To emurate the version 1.x behaviour in API, specify `store_dense_gp_map=False`
and `store_dense_svecs=False` in instatiation of `Phono3py` class or phon3py
loader.
## Mar-17-2021: Version 1.22.3
@ -37,21 +50,19 @@ or phon3py loader.
## Sep-30-2020: Version 1.21.0
- Maintenance release to follow the change of phonopy at v2.8.1
- Improvements of phono3py loader (`phono3py.load`), `phono3py-load`
command, API, and `phono3py_disp.yaml`.
- Harmonic phonon calculation on mesh was multithreaded. This is
effective when using very dense mesh with non-analytical term
correction (probably rare case).
- Real and imaginary parts of self energy and spectral function of
bubble diagram at API level
- Improvements of phono3py loader (`phono3py.load`), `phono3py-load` command,
API, and `phono3py_disp.yaml`.
- Harmonic phonon calculation on mesh was multithreaded. This is effective when
using very dense mesh with non-analytical term correction (probably rare
case).
- Real and imaginary parts of self energy and spectral function of bubble
diagram at API level
## Mar-3-2020: Version 1.20.0
- `phono3py_disp.yaml` is made when creating displacements in
addition to `disp_fc3.yaml` and
`disp_fc2.yaml`. `phono3py_disp.yaml` will be used instead of
`disp_fc3.yaml` and `disp_fc2.yaml` in the future major release
(v2.0).
- `phono3py_disp.yaml` is made when creating displacements in addition to
`disp_fc3.yaml` and `disp_fc2.yaml`. `phono3py_disp.yaml` will be used instead
of `disp_fc3.yaml` and `disp_fc2.yaml` in the future major release (v2.0).
## Mar-3-2020: Version 1.19.1
@ -60,15 +71,14 @@ or phon3py loader.
## Mar-2-2020: Version 1.19.0
- Improvements of phono3py loader and API.
- Improvement of interfaces to calculators. Now it is expected to be
much easier to implement calculator interface if it exists in
phonopy.
- Improvement of interfaces to calculators. Now it is expected to be much easier
to implement calculator interface if it exists in phonopy.
- Fixed dependency to phonopy v2.6.0.
## Dec-22-2019: Version 1.18.2
- Initial version of phono3py loader (`phono3py.load`) was
implemented. See docstring of `phono3py.load`.
- Initial version of phono3py loader (`phono3py.load`) was implemented. See
docstring of `phono3py.load`.
## Oct-17-2019: Version 1.18.1
@ -80,59 +90,51 @@ or phon3py loader.
## Apr-18-2019: Version 1.17.0
- `--cfz` option was made to subtract residual forces. See
{ref}`cfz_option`.
- `--cutoff-pair` was made to override the cutoff pair distance
written in `disp_fc3.yaml` when using on calculating force
constants. This is useful when checking cutoff distance
dependency. So the use case of having fully computed `FORCES_FC3`
is assumed.
- TURBOMOLE interface is provided by Antti Karttunen
(`--turbomole`).
- Compatibility of `fc2.hdf5` and `force_constants.hdf5` was
improved for all calculators to store physical unit information in
the hdf5 file. See {ref}`file_format_compatibility`.
- `--cfz` option was made to subtract residual forces. See {ref}`cfz_option`.
- `--cutoff-pair` was made to override the cutoff pair distance written in
`disp_fc3.yaml` when using on calculating force constants. This is useful when
checking cutoff distance dependency. So the use case of having fully computed
`FORCES_FC3` is assumed.
- TURBOMOLE interface is provided by Antti Karttunen (`--turbomole`).
- Compatibility of `fc2.hdf5` and `force_constants.hdf5` was improved for all
calculators to store physical unit information in the hdf5 file. See
{ref}`file_format_compatibility`.
## Mar-24-2019: Version 1.16.0
- Bug fixes and catching up the updates of phonopy.
- Most of hdf5 output files are compressed by `gzip` as
default. This compression can be set off, see
{ref}`hdf5_compression_option`.
- (Experimental) `phono3py` command accepts `phono3py.yaml` type
file as an input crystal structure by `-c` option. When `DIM`
and any structure file are not given, `phono3py_disp.yaml`
(primary) or `phono3py.yaml` (secondary) is searched in the current
directory. Then `phono3py.yaml` type file is used as the input.
By this, semi-automatic phono3py mode is invocked, which acts as
- Most of hdf5 output files are compressed by `gzip` as default. This
compression can be set off, see {ref}`hdf5_compression_option`.
- (Experimental) `phono3py` command accepts `phono3py.yaml` type file as an
input crystal structure by `-c` option. When `DIM` and any structure file are
not given, `phono3py_disp.yaml` (primary) or `phono3py.yaml` (secondary) is
searched in the current directory. Then `phono3py.yaml` type file is used as
the input. By this, semi-automatic phono3py mode is invocked, which acts as
1. `supercell_matrix` corresponding to `DIM` in the
`phono3py.yaml` type file is used if it exists.
2. `phonon_supercell_matrix` corresponding to `DIM_FC2` in the
`phono3py.yaml` type file is used if it exists.
3. `primitive_matrix` in the `phono3py.yaml` type file
is used if it exists. Otherwise, set `PRIMITIVE_AXES = AUTO`
when `PRIMITIVE_AXES` is not given.
4. NAC params are read (`NAC = .TRUE.`) if NAC params are
contained (primary) in the `phono3py.yaml` type file or if
`BORN` file exists in the current directory (secondary).
1. `supercell_matrix` corresponding to `DIM` in the `phono3py.yaml` type file
is used if it exists.
2. `phonon_supercell_matrix` corresponding to `DIM_FC2` in the `phono3py.yaml`
type file is used if it exists.
3. `primitive_matrix` in the `phono3py.yaml` type file is used if it exists.
Otherwise, set `PRIMITIVE_AXES = AUTO` when `PRIMITIVE_AXES` is not given.
4. NAC params are read (`NAC = .TRUE.`) if NAC params are contained (primary)
in the `phono3py.yaml` type file or if `BORN` file exists in the current
directory (secondary).
## Nov-22-2018: version 1.14.3
- Update to work with phonopy v1.14.2.
- Ph-ph interaction can be read (`--read-pp`) and write
(`--write-pp`) in RTA thermal conductivity calculation, too. Mind
that the data stored are different with and without
`--full-pp`. Wihtout `--full-pp` the data are stored in
complicated way to save data side, so it is not considered readable
by usual users.
- Ph-ph interaction can be read (`--read-pp`) and write (`--write-pp`) in RTA
thermal conductivity calculation, too. Mind that the data stored are different
with and without `--full-pp`. Wihtout `--full-pp` the data are stored in
complicated way to save data side, so it is not considered readable by usual
users.
## June-20-2018: version 1.13.3
- `--lw` (linewidth) option was removed. Use `--br` option and
find 2*gamma values as linewidths in `kappa-xxx.hdf5` file.
- Documentation of `--lbte` option is available at
{ref}`direct_solution`.
- `--lw` (linewidth) option was removed. Use `--br` option and find 2\*gamma
values as linewidths in `kappa-xxx.hdf5` file.
- Documentation of `--lbte` option is available at {ref}`direct_solution`.
- This version is dependent on phonopy>=1.13.2.
## May-17-2018: version 1.13.1
@ -141,58 +143,50 @@ or phon3py loader.
## Mar-16-2018: version 1.12.9
- Definition of `mode_kappa` values in output hdf5 file is
changed. Previously they were divided by number of grid points, but
now not. Therefore users who compute `kappa` from `mode_kappa`
need to be careful about this change. This does not affect to
`phono3py-kaccum` results.
- Definition of `mode_kappa` values in output hdf5 file is changed. Previously
they were divided by number of grid points, but now not. Therefore users who
compute `kappa` from `mode_kappa` need to be careful about this change. This
does not affect to `phono3py-kaccum` results.
## Feb-1-2018: version 1.12.7
- `--tsym` option is removed. Now with `--sym-fc3r` and
`--sym-fc2` options,
- `--tsym` option is removed. Now with `--sym-fc3r` and `--sym-fc2` options,
translational invariance symmetry is also applied.
- `--sym-fc` option is added. This is just an alias to specify both
`--sym-fc3r` and `--sym-fc2` together.
- Documentation on `--write-phonon` and `--read-phonon` options is
written. These options are used to save harmonic phonon infromation
on strage.
- `--sym-fc` option is added. This is just an alias to specify both `--sym-fc3r`
and `--sym-fc2` together.
- Documentation on `--write-phonon` and `--read-phonon` options is written.
These options are used to save harmonic phonon infromation on strage.
## Nov-22-2017: version 1.12.5
- Bug fix of RTA thermal conductivity. This bug exists from version
1.10.11.18 (git e40cd059). This bug exhibits when all the following
conditions are met:
- Bug fix of RTA thermal conductivity. This bug exists from version 1.10.11.18
(git e40cd059). This bug exhibits when all the following conditions are met:
1. RTA thermal conductivity calculation.
2. Tetrahedron method for Brillouin zone integration is used.
3. Number of triplets is smaller than number of bands at each grid point.
4. Without using `--full-pp`.
(3) happens when the primitive cell is relatively large. Number of triplets
can be shown using `--stp` option. A race condition of OpenMP multithreading
is the source of the bug. Therefore, if it occurs, the same calculation comes
up with the different thermal conductivity value in every run time, for whcih
it behaves like randomly.
(3) happens when the primitive cell is relatively large. Number of
triplets can be shown using `--stp` option. A race condition of
OpenMP multithreading is the source of the bug. Therefore, if it
occurs, the same calculation comes up with the different thermal
conductivity value in every run time, for whcih it behaves like
randomly.
- RTA thermal conductivity with smearing method (`--sigma`) is made
to run with smaller memory consumption as similar as tetrahedron
method (`--thm`).
- RTA thermal conductivity with smearing method (`--sigma`) is made to run with
smaller memory consumption as similar as tetrahedron method (`--thm`).
## Nov-17-2017: version 1.12.3
- Command option parser of the phonopy tools is replaced from
`optparse` to `argparse`.
- Command option parser of the phonopy tools is replaced from `optparse` to
`argparse`.
- The filenames used with these options were the positional arguments
previously. Now they are the command-line arguments, i.e., filenames
have to be put just after the option name like `-f vasprun.xml-001
vasprun.xml-002 ...`.
- The names of auxiliary tools (`kdeplot` and `kaccum`) are
changed, for which the prefix phono3py- is added to the old names to
avoid accidental conflict with other script names already existing
under bin directory.
previously. Now they are the command-line arguments, i.e., filenames have to
be put just after the option name like
`-f vasprun.xml-001 vasprun.xml-002 ...`.
- The names of auxiliary tools (`kdeplot` and `kaccum`) are changed, for which
the prefix phono3py- is added to the old names to avoid accidental conflict
with other script names already existing under bin directory.
- {ref}`sigma_cutoff_option` option was created.
## Jun-18-2017: version 1.11.13
@ -204,12 +198,11 @@ or phon3py loader.
## Mar-31-2017: version 1.11.11
- Abinit code interface is implemented and now under the testing.
- Reduction of memory usage in RTA thermal conductivity
calculation. This is especially effective for larger unit cell
case. Currently combinations with --full_pp, --write_gamma_detail,
and --simga(smearing method) are not supported for this. Performance
tuning is under going. In some case, computation can be slower than
the previous versions.
- Reduction of memory usage in RTA thermal conductivity calculation. This is
especially effective for larger unit cell case. Currently combinations with
--full_pp, --write_gamma_detail, and --simga(smearing method) are not
supported for this. Performance tuning is under going. In some case,
computation can be slower than the previous versions.
## Feb-9-2017: version 1.11.9
@ -218,8 +211,8 @@ or phon3py loader.
## Dec-14-2016: version 1.11.7
- This is a maintenance release. This version must be used with
phonopy-1.11.6 or later.
- This is a maintenance release. This version must be used with phonopy-1.11.6
or later.
## Nov-27-2016: version 1.11.5
@ -233,45 +226,42 @@ or phon3py loader.
## Apr-16-2016: version 1.10.7
- API example is prepared and it is found in `Si` example. No
doucment yet.
- API example is prepared and it is found in `Si` example. No doucment yet.
- Si pwscf example was placed in `example-phono3py` directory.
- User interface bug fix.
## Mar-15-2016: version 1.10.5
- Numbering way of phono3py version was just changed (No big updates
were made against previous version.) The number is given based on
the phonopy version. For example, the harmonic part of
phono3py-1.10.5 is based on the code close to phonopy-1.10.4.
- Numbering way of phono3py version was just changed (No big updates were made
against previous version.) The number is given based on the phonopy version.
For example, the harmonic part of phono3py-1.10.5 is based on the code close
to phonopy-1.10.4.
- Python3 support
- For the RTA thermal conductivity calculation mode with using the
linear tetrahedron method, only necessary part of phonon-phonon
interaction strengh among phonons. This improves lifetime
calculation performance, but as the drawback, averaged ph-ph
interaction strength can not be given. See {ref}`full_pp_option`.
- For the RTA thermal conductivity calculation mode with using the linear
tetrahedron method, only necessary part of phonon-phonon interaction strengh
among phonons. This improves lifetime calculation performance, but as the
drawback, averaged ph-ph interaction strength can not be given. See
{ref}`full_pp_option`.
- Pwscf interface ({ref}`calculator_interfaces`)
## 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.
- 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`.
- 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.
- 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
@ -285,47 +275,44 @@ or phon3py loader.
## 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 $\Gamma_\lambda(\omega_\lambda)$.
- 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
$\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 $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 $P_{\mathbf{q}j}$ is set
to $\text{eV}^2$.
- The definition of MSPP is modified so as to be averaged ph-ph interaction
defined as $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
$P_{\mathbf{q}j}$ is set to $\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.
- 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
- 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`.
- 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.
- 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.
@ -333,77 +320,68 @@ or phon3py loader.
## 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.
- 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`.
- 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`.
- 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.
- 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.
- 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.
- 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.
- `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.

4
doc/conf.py
View File

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

354
doc/direct-solution.md
View File

@ -1,8 +1,10 @@
(direct_solution)=
# Direct solution of linearized phonon Boltzmann equation
This page explains how to use the direct solution of LBTE by
[L. Chaput, Phys. Rev. Lett. 110, 265506 (2013)](https://doi.org/10.1103/PhysRevLett.110.265506) ({ref}`citation <citation_direct_solution_lbte>`).
[L. Chaput, Phys. Rev. Lett. 110, 265506 (2013)](https://doi.org/10.1103/PhysRevLett.110.265506)
({ref}`citation <citation_direct_solution_lbte>`).
```{contents}
:depth: 2
@ -11,44 +13,40 @@ This page explains how to use the direct solution of LBTE by
## How to use
As written in the following sections, this calculation requires large
memory space. When running multiple temperature points, simply the
memory space needed is multiplied by the number of the temperature
points. Therefore it is normally recommended to specify {ref}`--ts
option <ts_option>`. An example to run with the direct solution of
LBTE for `example/Si-PBEsol` is as follows:
As written in the following sections, this calculation requires large memory
space. When running multiple temperature points, simply the memory space needed
is multiplied by the number of the temperature points. Therefore it is normally
recommended to specify {ref}`--ts option <ts_option>`. An example to run with
the direct solution of LBTE for `example/Si-PBEsol` is as follows:
```bash
% phono3py --dim="2 2 2" --sym-fc -c POSCAR-unitcell
...
% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="11 11 11" --fc3 --fc2 --lbte --ts=300
% phono3py-load --mesh 11 11 11 --lbte --ts 300
...
=================== End of collection of collisions ===================
- Averaging collision matrix elements by phonon degeneracy [0.031s]
- Making collision matrix symmetric (built-in) [0.000s]
- Averaging collision matrix elements by phonon degeneracy [0.036s]
- Making collision matrix symmetric (built-in) [0.001s]
----------- Thermal conductivity (W/m-k) with tetrahedron method -----------
Diagonalizing by lapacke dsyev... [0.111s]
Diagonalizing by lapacke dsyev... [0.141s]
Calculating pseudo-inv with cutoff=1.0e-08 (np.dot) [0.001s]
# T(K) xx yy zz yz xz xy
300.0 111.588 111.588 111.588 0.000 0.000 -0.000
(RTA) 109.009 109.009 109.009 0.000 0.000 -0.000
300.0 113.140 113.140 113.140 0.000 0.000 -0.000
(RTA) 108.982 108.982 108.982 0.000 0.000 -0.000
----------------------------------------------------------------------------
Thermal conductivity and related properties were written into
"kappa-m111111.hdf5".
Eigenvalues of collision matrix were written into "coleigs-m111111.hdf5"
...
```
## Memory usage
The direct solution of LBTE needs diagonalization of a large collision
matrix, which requires large memory space. This is the largest
limitation of using this method. The memory size needed for one
collision matrix at a temperature point is $(\text{number of
The direct solution of LBTE needs diagonalization of a large collision matrix,
which requires large memory space. This is the largest limitation of using this
method. The memory size needed for one collision matrix at a temperature point
is
$(\text{number of
irreducible grid points} \times \text{number of bands} \times 3)^2$
for the symmetrized collision matrix.
@ -58,17 +56,16 @@ for the symmetrized collision matrix.
collision matrix.
--->
These collision matrices contain real values and are supposed to be
64bit float symmetric matrices. During the diagonalization of each
collision matrix with LAPACK `dsyev` solver, around 1.2 times more
memory space is consumed in total.
These collision matrices contain real values and are supposed to be 64bit float
symmetric matrices. During the diagonalization of each collision matrix with
LAPACK `dsyev` solver, around 1.2 times more memory space is consumed in total.
When phono3py runs with {ref}`--wgp option <wgp_option>` together with
`--lbte` option, estimated memory space needed for storing collision
matrix is presented. An example for `example/Si-PBEsol` is as follows:
When phono3py runs with {ref}`--wgp option <wgp_option>` together with `--lbte`
option, estimated memory space needed for storing collision matrix is presented.
An example for `example/Si-PBEsol` is as follows:
```
% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="40 40 40" --wgp --lbte
```bash
% phono3py-load --mesh 40 40 40 --lbte --wgp
...
Memory requirements:
@ -81,170 +78,166 @@ Memory requirements:
...
```
With {ref}`--stp option <stp_option>`, estimated
memory space needed for ph-ph interaction strengths is shown.
With {ref}`--stp option <stp_option>`, estimated memory space needed for ph-ph
interaction strengths is shown such as
```bash
% phono3py-load --mesh 40 40 40 --lbte --stp
```
## Work load distribution
The other difficulty compared with RTA is the workload
distribution. Currently there are two ways to distribute the
calculation: (1) Collision matrix is divided and the pieces are
distributed into computing nodes. (2) Ph-ph interaction strengths at
grid points are distributed into computing nodes. These two can not be
mixed, so one of them has to be chosen. In either case, the
distribution is done simply running a set of phono3py calculations
over grid points and optionally band indices. The data computed on
each computing node are stored in an hdf5 file. Increasing the
calculation size, e.g., larger mesh numbers or larger number of atoms
in the primitive cell, large files are created.
The other difficulty compared with RTA is the workload distribution. Currently
there are two ways to distribute the calculation: (1) Collision matrix is
divided and the pieces are distributed into computing nodes. (2) Ph-ph
interaction strengths at grid points are distributed into computing nodes. These
two can not be mixed, so one of them has to be chosen. In either case, the
distribution is done simply running a set of phono3py calculations over grid
points and optionally band indices. The data computed on each computing node are
stored in an hdf5 file. Increasing the calculation size, e.g., larger mesh
numbers or larger number of atoms in the primitive cell, large files are
created.
(distribution_colmat)=
### Distribution of collision matrix
A full collision matrix is divided into pieces at grid points of
irreducible part of Brillouin zone. Each piece is calculated
independently from the other pieces. After finishing the calculations
of these pieces, the full collision matrix is diagonzalized to obtain
the thermal conductivity.
A full collision matrix is divided into pieces at grid points of irreducible
part of Brillouin zone. Each piece is calculated independently from the other
pieces. After finishing the calculations of these pieces, the full collision
matrix is diagonzalized to obtain the thermal conductivity.
File size of Each piece of the collision matrix can be
large. Therefore it is recommended to use {ref}`--ts option
<ts_option>` to limit the number of temperature points, e.g.,
`--ts="100 200 300 400 500`, depending on the memory size installed
on each computing node. To write them into files,
`--write-collision` option must be specified, and to read them from
files, `--read-collision` option is used. These are similarly used
as {ref}`--write-gamma <write_gamma_option>` and {ref}`--read-gamma <read_gamma_option>` options for RTA calculation as shown in
{ref}`workload_distribution`.
`--read-collision` option collects the pieces and make one full
collision matrix, then starts to diagonalize it. This option requires
one argument to specify an index to read the collision matrix at one
File size of Each piece of the collision matrix can be large. Therefore it is
recommended to use {ref}`--ts option <ts_option>` to limit the number of
temperature points, e.g., `--ts "100 200 300 400 500"`, depending on the memory
size installed on each computing node. To write them into files,
`--write-collision` option must be specified, and to read them from files,
`--read-collision` option is used. These are similarly used as
{ref}`--write-gamma <write_gamma_option>` and
{ref}`--read-gamma <read_gamma_option>` options for RTA calculation as shown in
{ref}`workload_distribution`. `--read-collision` option collects the pieces and
make one full collision matrix, then starts to diagonalize it. This option
requires one argument to specify an index to read the collision matrix at one
temperature point, e.g., the collision matrix at 200K is read with
`--read-collision=1` for the (pieces of) collision matrices created
with `--ts="100 200 300 400 500"` (corresponding to 0, 1, 2, 3,
4). The temperature (e.g. 200K) is also read from the file, so it is
unnecessary to specify {ref}`--ts option <ts_option>` when reading.
`--read-collision 1` for the (pieces of) collision matrices created with
`--ts "100 200 300 400 500"` (corresponding to 0, 1, 2, 3, 4). The temperature
(e.g. 200K) is also read from the file, so it is unnecessary to specify
{ref}`--ts option <ts_option>` when reading.
The summary of the procedure is as follows:
1. Running at each grid point with {ref}`--gp <gp_option>` (or
{ref}`--ga <ga_option>`) option and
saving the piece of the collision matrix to an hdf5 file with
`--write-collision` option. It is probably OK to calculate and
store the pieces of the collision matrices at multiple temperatures
though it depends on memory size of the computer node. This
{ref}`--ga <ga_option>`) option and saving the piece of the collision matrix
to an hdf5 file with `--write-collision` option. It is probably OK to
calculate and store the pieces of the collision matrices at multiple
temperatures though it depends on memory size of the computer node. This
calculation has to be done at all irreducible grid points.
2. Collecting and creating all necessary pieces of the collision
matrix with `--read-collision=num` (`num`: index of
temperature). By this one full collision matrix at the selected
temperature is created and then diagonalized. An option `-o num`
may be used together with `--read-collision` to distinguish the
file names of the results at different temperatures.
2. Collecting and creating all necessary pieces of the collision matrix with
`--read-collision=num` (`num`: index of temperature). By this one full
collision matrix at the selected temperature is created and then
diagonalized. An option `-o num` may be used together with `--read-collision`
to distinguish the file names of the results at different temperatures.
Examples of command options are shown below using `Si-PBE` example.
Irreducible grid point indices are obtained by {ref}`--wgp option<wgp_option>`:
Examples of command options are shown below using `Si-PBE` example. Irreducible
grid point indices are obtained by {ref}`--wgp option<wgp_option>`:
```bash
% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --lbte --wgp
% phono3py-load --mesh 19 19 19 --lbte --wgp
```
and the information is given in `ir_grid_points.yaml`. For
distribution of collision matrix calculation
(see also {ref}`workload_distribution`):
and the information is given in `ir_grid_points.yaml`. For distribution of
collision matrix calculation (see also {ref}`workload_distribution`):
```
% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc3 --fc2 --lbte --ts=300 --write-collision --gp="grid_point_numbers..."
```bash
% phono3py-load --mesh 19 19 19 --lbte --ts 300 --write-collision --gp="grid_point_numbers..."
```
To collect distributed pieces of the collision matrix:
```bash
% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc3 --fc2 --lbte --ts=300 --read-collision=0
% phono3py-load --mesh 19 19 19 --lbte --read-collision 0
```
where `--read-collision 0` indicates to read the first result in the list of
temperatures by `--ts` option, i.e., 300K in this case.
### Distribution of phonon-phonon interaction strengths
The distribution of pieces of collision matrix is straightforward and
is recommended to use if the number of temperature points is
small. However increasing data file size, network communication
becomes to require long time to send the files from a master node to
computation nodes. In this case, the distribution over ph-ph
interaction strengths can be another choice. Since, without using
{ref}`--full-pp option <full_pp_option>`, the tetrahedron method or
smearing approach with {ref}`--sigma-cutoff option <sigma_cutoff_option>`
results in the sparse ph-ph interaction
strength data array, i.e., most of the elements are zero, the data
size can be reduced by only storing non-zero elements. Not like the
collision matrix, the ph-ph interaction strengths in phono3py are
independent from temperature though it is not the case if the force
constants provided are temperature dependent. Once
stored, they are used to create the collision matrices at
temperatures. Using `--write-pp` and `--read-pp`, they are written
into and read from hdf5 files at grid points.
The distribution of pieces of collision matrix is straightforward and is
recommended to use if the number of temperature points is small. However
increasing data file size, network communication becomes to require long time to
send the files from a master node to computation nodes. In this case, the
distribution over ph-ph interaction strengths can be another choice. Since,
without using {ref}`--full-pp option <full_pp_option>`, the tetrahedron method
or smearing approach with {ref}`--sigma-cutoff option <sigma_cutoff_option>`
results in the sparse ph-ph interaction strength data array, i.e., most of the
elements are zero, the data size can be reduced by only storing non-zero
elements. Not like the collision matrix, the ph-ph interaction strengths in
phono3py are independent from temperature though it is not the case if the force
constants provided are temperature dependent. Once stored, they are used to
create the collision matrices at temperatures. Using `--write-pp` and
`--read-pp`, they are written into and read from hdf5 files at grid points.
It is also recommended to use {ref}`--write-phonon option <write_phonon_option>` and {ref}`--read-phonon option <read_phonon_option>` to use identical phonon eigenvectors among the
distributed nodes.
It is also recommended to use {ref}`--write-phonon option <write_phonon_option>`
and {ref}`--read-phonon option <read_phonon_option>` to use identical phonon
eigenvectors among the distributed nodes.
The summary of the procedure is as follows:
1. Running at each grid point with {ref}`--gp <gp_option>` (or
{ref}`--ga <ga_option>`) option and storing the ph-ph interaction
strengths to an hdf5 file with `--write-pp` option. This calculation
has to be done at all irreducible grid points.
{ref}`--ga <ga_option>`) option and storing the ph-ph interaction strengths
to an hdf5 file with `--write-pp` option. This calculation has to be done at
all irreducible grid points.
2. Running with `--read-pp` option and without {ref}`--gp <gp_option>` (or
{ref}`--ga <ga_option>`) option. By this one full collision matrix at the
selected temperature is created and then diagonalized. An option
`-o num` may be used together with `--read-collision` to
distinguish the file names of the results at different
temperatures.
selected temperature is created and then diagonalized. An option `-o num` may
be used together with `--read-collision` to distinguish the file names of the
results at different temperatures.
Examples of command options are shown below using `Si-PBE` example.
Irreducible grid point indices are obtained by {ref}`--wgp option<wgp_option>`
Examples of command options are shown below using `Si-PBE` example. Irreducible
grid point indices are obtained by {ref}`--wgp option<wgp_option>`
```bash
% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --lbte --wgp
% phono3py-load --mesh "19 19 19" --lbte --wgp
```
and the grid point information is provided in
`ir_grid_points.yaml`. All phonons on mesh grid points are saved
by
and the grid point information is provided in `ir_grid_points.yaml`. All phonons
on mesh grid points are saved by
```bash
% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc2 --write-phonon
% phono3py-load --mesh "19 19 19" --write-phonon
```
For distribution of ph-ph interaction strength calculation (see also
{ref}`workload_distribution`)
```bash
% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc3 --fc2 --lbte --ts=300 --write-pp --gp="grid_point_numbers..." --read-phonon
% phono3py-load --mesh "19 19 19" --lbte --ts 300 --write-pp --gp "grid_point_numbers..." --read-phonon
```
Here one temperature has to be specified but any one of temperatures
is OK since ph-ph interaction strength computed here is assumed to be
temperature independent. Then the computed ph-ph interaction strengths
are read and used to compute collision matrix and lattice thermal
conductivity at a temperature by
Here one temperature has to be specified but any one of temperatures is OK since
ph-ph interaction strength computed here is assumed to be temperature
independent. Then the computed ph-ph interaction strengths are read and used to
compute collision matrix and lattice thermal conductivity at a temperature by
```bash
% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc3 --fc2 --lbte --ts=300 --read-pp --read-phonon
% phono3py-load --mesh "19 19 19" --lbte --ts 300 --read-pp --read-phonon
```
This last command is repeated at different temperatures to obtain the
properties at multiple temperatures.
This last command is repeated at different temperatures to obtain the properties
at multiple temperatures.
(diagonzalization_solver)=
## Cutoff parameter of pseudo inversion
To achieve a pseudo inversion, a cutoff parameter is used to find null
space, i.e., to select the nearly zero eigenvalues. The default cutoff
value is `1e-8`, and this hopefully works in many cases. But if a
collision matrix is numerically not very accurate, we may have to
carefully choose the value by `--pinv-cutoff` option. It is safer to
plot the absolute values of eigenvalues in log scale to see if there
is clear gap between non-zero eigenvalue and nearly-zero eigenvalues.
After running the direct solution of LBTE, `coleigs-mxxx.hdf5` is
To achieve a pseudo inversion, a cutoff parameter is used to find null space,
i.e., to select the nearly zero eigenvalues. The default cutoff value is `1e-8`,
and this hopefully works in many cases. But if a collision matrix is numerically
not very accurate, we may have to carefully choose the value by `--pinv-cutoff`
option. It is safer to plot the absolute values of eigenvalues in log scale to
see if there is clear gap between non-zero eigenvalue and nearly-zero
eigenvalues. After running the direct solution of LBTE, `coleigs-mxxx.hdf5` is
created. This contains the eigenvalues of the collision matrix (either
symmetrized or non-symmetrized). The eigenvalues are plotted using
`phono3py-coleigplot` in the phono3py package:
@ -253,8 +246,8 @@ symmetrized or non-symmetrized). The eigenvalues are plotted using
% phono3py-coleigplot coleigs-mxxx.hdf5
```
It is assumed that only one set of eigenvalues at a temperature point
is contained.
It is assumed that only one set of eigenvalues at a temperature point is
contained.
```{figure} Si-coleigplot.png
:width: 50%
@ -274,72 +267,67 @@ as null spaces.
## Installation of diagonalization solvers with multithreaded BLAS
Multithreaded BLAS is recommended to use for the calculation of the
direct solution of LBTE since the diagonalization of the collision
matrix is computationally demanding. A few examples of how to install
multithreded BLAS libraries are presented below.
Multithreaded BLAS is recommended to use for the calculation of the direct
solution of LBTE since the diagonalization of the collision matrix is
computationally demanding. A few examples of how to install multithreded BLAS
libraries are presented below.
### MKL linked scipy
Scipy (also numpy) has an interface to LAPACK dsyev
(`scipy.linalg.lapack.dsyev`). An MKL LAPACK linked scipy (also
numpy) gives very good computing performance and is easily obtained
using the anaconda package manager. In this choice, usual installation
of LAPACKE is necessary for running `dgesvd` and `zheev`. When
using anaconda, installing OpenBLAS is the easiest way to do. See
{ref}`install_openblas_lapacke`
(`scipy.linalg.lapack.dsyev`). An MKL LAPACK linked scipy (also numpy) gives
very good computing performance and is easily obtained using the anaconda
package manager. In this choice, usual installation of LAPACKE is necessary for
running `dgesvd` and `zheev`. When using anaconda, installing OpenBLAS is the
easiest way to do. See {ref}`install_openblas_lapacke`
### OpenBLAS or MKL via LAPACKE
Using LAPACKE via python C-API is implemented. By this, phono3py can
use LAPACK dsyev. This uses smaller memory space than using MKL linked
scipy. Practically there are two choices, OpenBLAS and MKL. For MKL,
proper installatin of the MKL package is necessary. The MKL
library installed obtained from anaconda can not be used.
Using LAPACKE via python C-API is implemented. By this, phono3py can use LAPACK
dsyev. This uses smaller memory space than using MKL linked scipy. Practically
there are two choices, OpenBLAS and MKL. For MKL, proper installatin of the MKL
package is necessary. The MKL library installed obtained from anaconda can not
be used.
#### OpenBLAS
Use of OpenBLAS is an easy choice if the anaconda package is used.
See {ref}`install_openblas_lapacke`.
Use of OpenBLAS is an easy choice if the anaconda package is used. See
{ref}`install_openblas_lapacke`.
#### MKL
The BLAS multithread performance may be better in that in MKL. Using
MKL-LAPACK via MKL-LAPACKE via python C-API is also implemented if the
link is succeeded. See {ref}`install_mkl_lapacke`.
The BLAS multithread performance may be better in that in MKL. Using MKL-LAPACK
via MKL-LAPACKE via python C-API is also implemented if the link is succeeded.
See {ref}`install_mkl_lapacke`.
## Solver choice for diagonalization
For larger systems, diagonalization of collision matrix takes longest
time and requires large memory space. Phono3py relies on LAPACK for
the diagonalization and so the performance is dependent on the choice
of the diagonalization solver.
For larger systems, diagonalization of collision matrix takes longest time and
requires large memory space. Phono3py relies on LAPACK for the diagonalization
and so the performance is dependent on the choice of the diagonalization solver.
Using multithreaded BLAS with many-core computing node, computing time
may be well reduced and the calculation can finish in a realistic
time. Currently scipy, numpy and LAPACKE can be used as the LAPACK
wrapper in phono3py. Scipy and numpy distributed by anaconda are MKL
linked, therefore MKL multithread BLAS is used through
them. Multithreaded OpenBLAS is installed by conda and can be used via
LAPACKE in phono3py. MKL LAPACK and BLAS are also able to be used via
Using multithreaded BLAS with many-core computing node, computing time may be
well reduced and the calculation can finish in a realistic time. Currently
scipy, numpy and LAPACKE can be used as the LAPACK wrapper in phono3py. Scipy
and numpy distributed by anaconda are MKL linked, therefore MKL multithread BLAS
is used through them. Multithreaded OpenBLAS is installed by conda and can be
used via LAPACKE in phono3py. MKL LAPACK and BLAS are also able to be used via
LAPACKE in phono3py with appropriate setting in `setup.py`.
Using `--pinv-solver=[number]`, one of the following solver is
chosen:
Using `--pinv-solver=[number]`, one of the following solver is chosen:
1. Lapacke `dsyev`: Smaller memory consumption than `dsyevd`, but
slower. This is the default solver when MKL LAPACKE is integrated or
scipy is not installed.
2. Lapacke `dsyevd`: Larger memory consumption than `dsyev`, but
faster. This is not recommended because sometimes a wrong result is
obtained.
3. Numpy's `dsyevd` (`linalg.eigh`). This is not recommended
because sometimes a wrong result is obtained.
4. Scipy's `dsyev`: This is the default solver when scipy is
installed and MKL LAPACKE is not integrated.
5. Scipy's `dsyevd`. This is not recommended because sometimes a
1. Lapacke `dsyev`: Smaller memory consumption than `dsyevd`, but slower. This
is the default solver when MKL LAPACKE is integrated or scipy is not
installed.
2. Lapacke `dsyevd`: Larger memory consumption than `dsyev`, but faster. This is
not as stable as `dsyev` but is useful for solving collision matrix with
dense mesh sampling. So this solver has to be used carefully.
3. Numpy's `dsyevd` (`linalg.eigh`). This is not recommended because sometimes a
wrong result is obtained.
4. Scipy's `dsyev`: This is the default solver when scipy is installed and MKL
LAPACKE is not integrated.
5. Scipy's `dsyevd`: Similar to solver (2), this solver should be used
carefully.
The solver choices other than `--pinv-solver=1` and
`--pinv-solver=4` are dangerous and not recommend. They exist just
for the tests.
The solver choices other than `--pinv-solver=1` and `--pinv-solver=4` are
dangerous and not recommend. They exist just for the tests.

2
phono3py/version.py
View File

@ -33,4 +33,4 @@
# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
__version__ = "2.0.0"
__version__ = "2.1.0"