mirror of https://github.com/phonopy/phono3py.git
Update document
This commit is contained in:
Atsushi Togo
parent
a0411bd0a7
commit
e42c8e2a15
|
|
@ -4,28 +4,23 @@ digraph phonopy {
|
|||
"Phono3py (FC)" [shape = box, style = filled];
|
||||
"Phono3py (LTC)" [shape = box, style = filled];
|
||||
"Supercell + displacements" [shape = box];
|
||||
"Supercell & displacements generation" [shape = box];
|
||||
"Force calc." [shape = octagon];
|
||||
"Force-constants calc." [shape = octagon];
|
||||
|
||||
subgraph ph3force {
|
||||
"Unit cell" -> "Phono3py (force-sets)";
|
||||
"Supercell matrix" -> "Phono3py (force-sets)";
|
||||
"Phono3py (force-sets)" -> "Supercell & displacements generation";
|
||||
"Supercell & displacements generation" -> "Displacements dataset";
|
||||
"Supercell & displacements generation" -> "Supercell";
|
||||
"Supercell & displacements generation"
|
||||
"Supercell" -> "Supercell + displacements";
|
||||
"Displacements dataset" -> "Supercell + displacements";
|
||||
"Supercell + displacements" -> "Supercells with displacements";
|
||||
"Supercells with displacements" -> "Force calc.";
|
||||
"Phono3py (force-sets)" -> "Supercell";
|
||||
"Phono3py (force-sets)" -> "Displacement dataset";
|
||||
"Supercell" -> "Force calc.";
|
||||
"Displacement dataset" -> "Force calc.";
|
||||
"Force calc." -> "Supercell-force sets";
|
||||
}
|
||||
|
||||
subgraph ph3fc {
|
||||
"Unit cell" -> "Phono3py (FC)";
|
||||
"Supercell matrix" -> "Phono3py (FC)";
|
||||
"Displacements dataset" -> "Phono3py (FC)";
|
||||
"Displacement dataset" -> "Phono3py (FC)";
|
||||
"Supercell-force sets" -> "Phono3py (FC)";
|
||||
"Phono3py (FC)" -> "Force-constants calc.";
|
||||
"Force-constants calc." -> "Force constants (fc2, fc3)";
|
||||
|
|
|
|||
|
|
@ -70,6 +70,8 @@ TURBOMOLE interface is invoked. See the details at {ref}`turbomole_interface`.
|
|||
|
||||
These options have no respective configuration file tags.
|
||||
|
||||
(cf3_option)=
|
||||
|
||||
### `--cf3` (command option only)
|
||||
|
||||
This is used to create `FORCES_FC3` from `phono3py_disp.yaml` and force
|
||||
|
|
@ -297,8 +299,6 @@ The symmetrizations for the second and third orders can be independently applied
|
|||
by `--sym-fc2` (`SYMMETRIZE_FC2 = .TRUE.`) and `--sym-fc3r`
|
||||
(`SYMMETRIZE_FC3 = .TRUE.`), , respectively.
|
||||
|
||||
(cf3_option)=
|
||||
|
||||
### `--cutoff-fc3` or `--cutoff-fc3-distance` (`CUTOFF_FC3_DISTANCE`)
|
||||
|
||||
This option is **not** used to reduce number of supercells with displacements,
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ workflow
|
|||
examples
|
||||
Interfaces to calculators (VASP, QE, CRYSTAL, Abinit, TURBOMOLE) <interfaces>
|
||||
command-options
|
||||
output-files
|
||||
input-output-files
|
||||
hdf5_howto
|
||||
auxiliary-tools
|
||||
direct-solution
|
||||
|
|
|
|||
|
|
@ -0,0 +1,182 @@
|
|||
(input-output_files)=
|
||||
|
||||
# Input / Output files
|
||||
|
||||
```{contents}
|
||||
:depth: 3
|
||||
:local:
|
||||
```
|
||||
|
||||
The calculation results are written into files. Mostly the data are stored in
|
||||
HDF5 format, therefore how to read the data from HDF5 files is also shown.
|
||||
|
||||
## Intermediate text files
|
||||
|
||||
The following files are not compatible with phonopy. But phonopy's `FORCE_SETS`
|
||||
file can be created using phono3py command options from the following files. See
|
||||
the detail at {ref}`file_format_compatibility`.
|
||||
|
||||
### `phono3py_disp.yaml`
|
||||
|
||||
This is created with `-d` option. See {ref}`create_displacements_option`.
|
||||
|
||||
This file contains displacement dataset and crystal structure information.
|
||||
|
||||
(input-output_files_FORCES_FC3)=
|
||||
|
||||
### `FORCES_FC3`
|
||||
|
||||
This is created with `--cf3` option. See {ref}`cf3_option`.
|
||||
|
||||
This file has a simple format like
|
||||
|
||||
```
|
||||
# File: 1
|
||||
# 1 0.0300000000000000 0.0000000000000000 0.0000000000000000
|
||||
-0.6458483000 0.0223064300 -0.0143299700
|
||||
0.0793497000 0.0088413200 -0.0052766800
|
||||
0.0768176500 -0.0095501600 0.0057262300
|
||||
-0.0016552800 -0.0366684600 -0.0059480700
|
||||
-0.0023432300 0.0373490000 0.0059468600
|
||||
0.0143901800 0.0000959800 -0.0001100900
|
||||
-0.0019487200 -0.0553591300 -0.0113649500
|
||||
0.0143732700 -0.0000614400 0.0000502600
|
||||
-0.0020311400 0.0554678300 0.0115355100
|
||||
...
|
||||
# File: 1254
|
||||
# 37 0.0000000000000000 0.0000000000000000 -0.0300000000000000
|
||||
# 68 0.0000000000000000 0.0000000000000000 -0.0300000000000000
|
||||
-0.0008300600 -0.0004792400 0.0515596200
|
||||
-0.0133197900 -0.0078480800 0.0298334900
|
||||
0.0141518600 -0.0105405200 0.0106313000
|
||||
0.0153762500 -0.0072671600 0.0112864200
|
||||
-0.0134565300 -0.0076112400 0.0298334900
|
||||
-0.0019180000 -0.0011073600 0.0272454300
|
||||
0.0013945800 0.0169498000 0.0112864200
|
||||
0.0006578200 0.0003797900 0.0085617600
|
||||
-0.0020524300 0.0175261300 0.0106313000
|
||||
0.0019515200 0.0011267100 -0.2083651200
|
||||
0.0148675800 -0.0516285500 -0.0924200600
|
||||
-0.0168043800 0.0074232400 -0.0122506300
|
||||
-0.0128831200 0.0114004400 -0.0110906700
|
||||
...
|
||||
```
|
||||
|
||||
This file contains supercell forces. Lines starting with `#` is ignored when
|
||||
parsing. Each line gives forces of at atom in Cartesian coordinates. All forces
|
||||
of atoms in each supercell are written in the same order as the atoms in the
|
||||
supercell. All forces of all supercells are concatenated. If force sets are
|
||||
stored in a numpy array (`forces`) of the shape of
|
||||
`(num_supercells, num_atoms_in_supercell, 3)`, this file is generated using
|
||||
numpy as follows:
|
||||
|
||||
```python
|
||||
np.savetxt("FORCES_FC3", forces.reshape(-1, 3))
|
||||
```
|
||||
|
||||
### `FORCES_FC2`
|
||||
|
||||
This is created with `--cf2` option. See {ref}`cf2_option` and
|
||||
{ref}`dim_fc2_option`.
|
||||
|
||||
The file format of this file is similar to that of `FORCES_FC3`.
|
||||
|
||||
## HDF5 files
|
||||
|
||||
### `kappa-*.hdf5`
|
||||
|
||||
See the detail at {ref}`kappa_hdf5_file`.
|
||||
|
||||
(fc3_hdf5_file)=
|
||||
|
||||
### `fc3.hdf5`
|
||||
|
||||
Third order force constants (in real space) are stored in
|
||||
$\mathrm{eV}/\text{Angstrom}^3$.
|
||||
|
||||
In phono3py, this is stored in the numpy array `dtype='double'` and `order='C'`
|
||||
in the shape of:
|
||||
|
||||
```
|
||||
(num_atom, num_atom, num_atom, 3, 3, 3)
|
||||
```
|
||||
|
||||
against $\Phi_{\alpha\beta\gamma}(l\kappa, l'\kappa',
|
||||
l''\kappa'')$. The first
|
||||
three `num_atom` are the atom indices in supercell corresponding to $l\kappa$,
|
||||
$l'\kappa'$, $l''\kappa''$, respectively. The last three elements are the
|
||||
Cartesian coordinates corresponding to $\alpha$, $\beta$, $\gamma$,
|
||||
respectively.
|
||||
|
||||
If you want to import a supercell structure and its fc3, you may suffer from
|
||||
matching its atom index between the supercell and an expected unit cell. This
|
||||
may be easily dealt with by letting phono3py see your supercell as the unit cell
|
||||
(e.g., `POSCAR`, `unitcell.in`, etc) and find the unit (primitive) cell using
|
||||
{ref}`--pa option <pa_option>`. For example, let us assume your supercell is the
|
||||
2x2x2 multiples of your unit cell that has no centring, then your `--pa` setting
|
||||
will be `1/2 0 0 0 1/2 0 0 1/2 0`. If your unit cell is a conventional unit cell
|
||||
and has a centring, e.g., the face centring,
|
||||
|
||||
$$
|
||||
(\mathbf{a}_\text{p}, \mathbf{b}_\text{p}, \mathbf{c}_\text{p}) =
|
||||
(\mathbf{a}_\text{s}, \mathbf{b}_\text{s}, \mathbf{c}_\text{s})
|
||||
\begin{pmatrix}
|
||||
\frac{{1}}{2} & 0 & 0 \\
|
||||
0 & \frac{{1}}{2} & 0 \\
|
||||
0 & 0 & \frac{{1}}{2}
|
||||
\end{pmatrix}
|
||||
\begin{pmatrix}
|
||||
0 & \frac{{1}}{2} & \frac{{1}}{2} \\
|
||||
\frac{{1}}{2} & 0 & \frac{{1}}{2} \\
|
||||
\frac{{1}}{2} & \frac{{1}}{2} & 0
|
||||
\end{pmatrix} =
|
||||
(\mathbf{a}_\text{s}, \mathbf{b}_\text{s}, \mathbf{c}_\text{s})
|
||||
\begin{pmatrix}
|
||||
0 & \frac{{1}}{4} & \frac{{1}}{4} \\
|
||||
\frac{{1}}{4} & 0 & \frac{{1}}{4} \\
|
||||
\frac{{1}}{4} & \frac{{1}}{4} & 0
|
||||
\end{pmatrix}.
|
||||
$$
|
||||
|
||||
So what you have to set is `--pa="0 1/4 1/4 1/4 0 1/4 1/4 1/4 0"`.
|
||||
|
||||
(fc2_hdf5_file)=
|
||||
|
||||
### `fc2.hdf5`
|
||||
|
||||
Second order force constants are stored in $\mathrm{eV}/\text{Angstrom}^2$.
|
||||
|
||||
In phono3py, this is stored in the numpy array `dtype='double'` and `order='C'`
|
||||
in the shape of:
|
||||
|
||||
```
|
||||
(num_atom, num_atom, 3, 3)
|
||||
```
|
||||
|
||||
against $\Phi_{\alpha\beta}(l\kappa, l'\kappa')$. More detail is similar to the
|
||||
case for {ref}`fc3_hdf5_file`.
|
||||
|
||||
### `gamma-*.hdf5`
|
||||
|
||||
Imaginary parts of self energies at harmonic phonon frequencies
|
||||
($\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
|
||||
$\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`
|
||||
|
|
@ -7,6 +7,9 @@
|
|||
:local:
|
||||
```
|
||||
|
||||
How to use phono3py API is described below along with snippets that work with
|
||||
[`AlN-LDA` example](https://github.com/phonopy/phono3py/tree/develop/example/AlN-LDA).
|
||||
|
||||
## `Phono3py` class
|
||||
|
||||
To operate phono3py from python, there is phono3py API. The main class is
|
||||
|
|
@ -16,13 +19,20 @@ To operate phono3py from python, there is phono3py API. The main class is
|
|||
from phono3py import Phono3py
|
||||
```
|
||||
|
||||
The minimum set of inputs are `unitcell` (1st argument), `supercell_matrix` (2nd
|
||||
argument), and `primitive_matrix`, which are used as
|
||||
As written in {ref}`workflow`, phono3py workflow is roughly divided into three
|
||||
steps. `Phono3py` class is used at each step. The minimum set of inputs to
|
||||
instantiate `Phono3py` class are `unitcell` (1st argument), `supercell_matrix`
|
||||
(2nd argument), and `primitive_matrix`, which are used as
|
||||
|
||||
```python
|
||||
ph3 = Phono3py(unitcell,
|
||||
[[2, 0, 0], [0, 2, 0], [0, 0, 2]],
|
||||
primitive_matrix='auto')
|
||||
ph3 = Phono3py(unitcell, supercell_matrix=[3, 3, 2], primitive_matrix='auto')
|
||||
```
|
||||
|
||||
There are many parameters that can be given to `Phono3py` class. The details are
|
||||
written in the docstring, which is shown by
|
||||
|
||||
```python
|
||||
help(Phono3py)
|
||||
```
|
||||
|
||||
The `unitcell` is an instance of the
|
||||
|
|
@ -32,3 +42,127 @@ generate supercell and primitive cell from `unitcell` (see
|
|||
[definitions](https://phonopy.github.io/phonopy/phonopy-module.html#definitions-of-variables)).
|
||||
This step is similar to the
|
||||
[instantiation of `Phonopy` class](https://phonopy.github.io/phonopy/phonopy-module.html#pre-process).
|
||||
|
||||
When we want `unitcell` from a text file of a force-calculator format, the
|
||||
`read_crystal_structure` function in phonopy can be used, e.g., in the AlN-LDA
|
||||
example,
|
||||
|
||||
```python
|
||||
In [1]: from phonopy.interface.calculator import read_crystal_structure
|
||||
|
||||
In [2]: unitcell, _ = read_crystal_structure("POSCAR-unitcell", interface_mode='vasp')
|
||||
|
||||
In [3]: print(unitcell)
|
||||
lattice:
|
||||
- [ 3.110999999491908, 0.000000000000000, 0.000000000000000 ] # a
|
||||
- [ -1.555499999745954, 2.694205030733368, 0.000000000000000 ] # b
|
||||
- [ 0.000000000000000, 0.000000000000000, 4.978000000000000 ] # c
|
||||
points:
|
||||
- symbol: Al # 1
|
||||
coordinates: [ 0.333333333333333, 0.666666666666667, 0.000948820000000 ]
|
||||
mass: 26.981539
|
||||
- symbol: Al # 2
|
||||
coordinates: [ 0.666666666666667, 0.333333333333333, 0.500948820000000 ]
|
||||
mass: 26.981539
|
||||
- symbol: N # 3
|
||||
coordinates: [ 0.333333333333333, 0.666666666666667, 0.619051180000000 ]
|
||||
mass: 14.006700
|
||||
- symbol: N # 4
|
||||
coordinates: [ 0.666666666666667, 0.333333333333333, 0.119051180000000 ]
|
||||
mass: 14.006700
|
||||
```
|
||||
|
||||
In AlN-LDA example, the unit cell structure, supercell matrix, and primitive
|
||||
matrix were recorded in the `phono3py_disp_dimfc2.yamll` file. This is easily
|
||||
read a helper function of `phono3py.load`. Using ipython (or jupyter-notebook):
|
||||
|
||||
```python
|
||||
In [1]: import phono3py
|
||||
|
||||
In [2]: ph3 = phono3py.load("phono3py_disp_dimfc2.yaml", produce_fc=False)
|
||||
|
||||
In [3]: type(ph3)
|
||||
Out[3]: phono3py.api_phono3py.Phono3py
|
||||
|
||||
In [4]: print(ph3.unitcell)
|
||||
lattice:
|
||||
- [ 3.110999999491908, 0.000000000000000, 0.000000000000000 ] # a
|
||||
- [ -1.555499999745954, 2.694205030733368, 0.000000000000000 ] # b
|
||||
- [ 0.000000000000000, 0.000000000000000, 4.978000000000000 ] # c
|
||||
points:
|
||||
- symbol: Al # 1
|
||||
coordinates: [ 0.333333333333333, 0.666666666666667, 0.000948820000000 ]
|
||||
mass: 26.981539
|
||||
- symbol: Al # 2
|
||||
coordinates: [ 0.666666666666667, 0.333333333333333, 0.500948820000000 ]
|
||||
mass: 26.981539
|
||||
- symbol: N # 3
|
||||
coordinates: [ 0.333333333333333, 0.666666666666667, 0.619051180000000 ]
|
||||
mass: 14.006700
|
||||
- symbol: N # 4
|
||||
coordinates: [ 0.666666666666667, 0.333333333333333, 0.119051180000000 ]
|
||||
mass: 14.006700
|
||||
|
||||
In [5]: ph3.supercell_matrix
|
||||
Out[5]:
|
||||
array([[3, 0, 0],
|
||||
[0, 3, 0],
|
||||
[0, 0, 2]])
|
||||
```
|
||||
|
||||
## Displacement dataset generation
|
||||
|
||||
The step (1) in {ref}`workflow` generates sets of displacements in supercell.
|
||||
Supercells with the displacements are used as input crystal structure models of
|
||||
force calculator that is, e.g., first-principles calculation code. Using the
|
||||
force calculator, sets of forces of the supercells with the displacements are
|
||||
obtained out of phono3py environment, i.e., phono3py only provides crystal
|
||||
structures. Here we call the sets of the displacements as
|
||||
`displacement dataset`, the sets of the supercell forces as `force sets`, and
|
||||
the pair of `displacement dataset` and `force sets` as simply `dataset` for
|
||||
computing second and third force constants.
|
||||
|
||||
After instantiating `Phono3py` with `unitcell`, displacements are generated as
|
||||
follows:
|
||||
|
||||
```python
|
||||
In [6]: ph3 = Phono3py(unitcell, supercell_matrix=[3, 3, 2], primitive_matrix='auto')
|
||||
|
||||
In [7]: ph3.generate_displacements()
|
||||
|
||||
In [8]: len(ph3.supercells_with_displacements)
|
||||
Out[8]: 1254
|
||||
|
||||
In [9]: type(ph3.supercells_with_displacements[0])
|
||||
Out[9]: phonopy.structure.atoms.PhonopyAtoms
|
||||
```
|
||||
|
||||
By this, 1254 supercells with displacements were generated.
|
||||
|
||||
The generated displacement dataset is used in the force constants calculation.
|
||||
Therefore, it is recommended to save it into a file if the python process having
|
||||
the `Phono3py` class instance is expected to be terminated. The displacement
|
||||
dataset and crystal structure information are saved to a file by
|
||||
`Phono3py.save()` method:
|
||||
|
||||
```python
|
||||
In [11]: ph3.save("phono3py_disp.yaml")
|
||||
```
|
||||
|
||||
## Supercell force calculation
|
||||
|
||||
Forces of the generated supercells with displacements are calculated by some
|
||||
external force calculator such as first-principles calculation code.
|
||||
|
||||
Calculated supercell forces will be stored in `Phono3py` class instance through
|
||||
`Phono3py.forces` attribute by setting an array_like variable with the shape of
|
||||
`(num_supercells, num_atoms_in_supercell, 3)`. In the above example, the array
|
||||
shape is `(1254, 72, 3)`.
|
||||
|
||||
If calculated force sets are stored in the {ref}`input-output_files_FORCES_FC3`
|
||||
format, the numpy array of `forces` is obtained by
|
||||
|
||||
```python
|
||||
forces = np.loadtxt("FORCES_FC3").reshape(-1, num_atoms_in_supercell, 3)
|
||||
assert len(forces) == num_supercells
|
||||
```
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 92 KiB After Width: | Height: | Size: 78 KiB |
|
|
@ -3,18 +3,36 @@
|
|||
# Workflow
|
||||
|
||||
Phono3py calculate phonon-phonon interaction related properties. Diagram shown
|
||||
below is an example of workflow to calculate lattice thermal conductivity using
|
||||
phono3py. The other properties such as spectral function can be calculated in
|
||||
similar ways.
|
||||
below illustrates workflow of lattice thermal conductivity (LTC) calculation.
|
||||
The other properties such as spectral function can be calculated in similar
|
||||
workflow.
|
||||
|
||||
The calculation is divided into roughly three parts:
|
||||
The LTC calculation is performed by the following three steps:
|
||||
|
||||
1. Calculation of supercell-force sets
|
||||
2. Calculation of force constants
|
||||
3. Calculation of lattice thermal conductivity (or other properties)
|
||||
1. Calculation of supercell-force sets (force-sets)
|
||||
2. Calculation of force constants (FC)
|
||||
3. Calculation of lattice thermal conductivity (LTC)
|
||||
|
||||
Users will call phono3py at each step with at least unit cell and supercell
|
||||
matrix, which define the supercell model, as inputs.
|
||||
|
||||
In the first step, supercell and sets of atomic displacements are generated,
|
||||
where we call the sets of the displacements as "displacement dataset".
|
||||
Supercells with displacements are built from them. Then forces of the supercell
|
||||
models are calculated using a force calculator such as first-principles
|
||||
calculation code, which we call "force sets".
|
||||
|
||||
In the second step, second and third order force constants (fc2 and fc3) are
|
||||
computed from the displacement datasets and force sets obtained in the first
|
||||
step.
|
||||
|
||||
In the third step, the force constants obtained in the second step are used to
|
||||
calculate lattice thermal conductivity. When the input unit cell is not a
|
||||
primitive cell, primitive cell matrix is required to be given. Long-range
|
||||
dipole-dipole interaction can be included when parameters for non-analytical
|
||||
term correction (NAC) are provided.
|
||||
|
||||
```{figure} procedure.png
|
||||
:scale: 80
|
||||
:align: center
|
||||
|
||||
Work flow of lattice thermal conductivity calculation
|
||||
|
|
|
|||
Loading…
Reference in New Issue