Merge branch 'develop' into rc

README.md

@@ -10,7 +10,7 @@ Note that this code couples with VASP code, and the electron-phonon interaction
 properties can not be computed only using this code.
 
 Phelel user documentation is found at
-http://phonopy.github.io/phelel/
+https://phonopy.github.io/phelel/
 
 ## Installation
 

doc/changelog.md

@@ -2,6 +2,11 @@
 
 # Change Log
 
+## Jan-5-2024: Version 0.8.0
+
+- Refactoring of `Phelel` class
+- Major update of documentation
+
 ## Dec-31-2024: Version 0.7.0
 
 - Maintenance release to follow the change of phonopy.

doc/conf.py

@@ -10,8 +10,8 @@
 copyright = "2024, Atsushi Togo"
 author = "Atsushi Togo"
 
-version = "0.7"
-release = "0.7.0"
+version = "0.8"
+release = "0.8.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

doc/index.md

@@ -3,11 +3,19 @@
 A code that provides a few computations related to electron-phonon interaction
 calculation in finite-displacement method reported by
 
-Laurent Chaput, Atsushi Togo, and Isao Tanaka, Phys. Rev. B **100**, 174304
+- Laurent Chaput, Atsushi Togo, and Isao Tanaka, Phys. Rev. B **100**, 174304
 (2019).
+- Manuel Engel, Henrique Miranda, Laurent Chaput, Atsushi Togo, Carla Verdi,
+  Martijn Marsman, and Georg Kresse, Phys. Rev. B **106**, 094316 (2022)
+
+This code couples with VASP code, and the electron-phonon interaction properties
+cannot be computed only using this code.
+
+Properties calculated using phelel and VASP codes:
+
+- Thermoelectric properties
+- Bandgap renormalization
 
-Note that this code couples with VASP code, and the electron-phonon interaction
-properties can not be computed only using this code.
 
 ## License
 
@@ -20,6 +28,8 @@ BSD-3-Clause.
 ```{toctree}
 :hidden:
 install
-velph
+workflow
+phelel-command
+velph-command
 changelog
 ```

doc/phelel-command.md

@@ -0,0 +1,100 @@
+(phelel_command)=
+# phelel command
+
+Command-line tools perform steps 1 and 3 in {ref}`the el-ph calculation
+workflow <workflow_minimal>`. Their usage parallels that of the `phonopy`
+command in [phonopy](https://phonopy.github.io/phonopy/) for
+phonon calculations.
+
+The following example demonstrates operations using the `phelel` command:
+
+```
+% phelel -d --dim 2 2 2 -c POSCAR-unitcell --pa auto --pm
+
+# After running VASP calculations in directories corresponding to displacements:
+
+% phelel --cd disp-000 disp-001 disp-002 disp-003 disp-004
+```
+
+## Generation of displacements in supercell
+
+Supercells with displacements can be generated by combining the following
+command options. For example:
+
+```
+% phelel -d --dim 2 2 2 -c POSCAR-unitcell --pa auto --pm
+```
+
+Here, `POSCAR-unitcell` is the unit cell structure in VASP POSCAR format. After
+this operation, a file named `phelel_disp.yaml`, containing information about
+the displacements, is created. Additionally, the supercell structures `SPOSCAR`,
+`POSCAR-001`, and so on are generated.
+
+### `-d`
+
+This triggers an execution mode that generates supercells with systematically
+introduced displacements. The displacements are determined by crystal symmetry,
+with exactly one displacement applied in each supercell.
+
+### `--dim`
+
+Three or nine integer values specify the supercell shape with respect to the
+unit cell structure indicated by the `-c` option. If nine values are provided,
+they correspond to the supercell matrix as defined in the [phonopy
+documentation](https://phonopy.github.io/phonopy/setting-tags.html#dim). If
+three values are given, they represent the diagonal elements of the supercell
+matrix, meaning each axis of the input unit cell is simply extended by the
+corresponding integer factor.
+
+```
+% phelel --dim 2 2 2 [OPTIONS]
+```
+
+```
+% phelel --dim 0 1 1 1 0 1 1 1 0 [OPTIONS]
+```
+
+
+### `-c`, `--cell`
+
+Unit cell structure is specified.
+
+```
+% phelel -c POSCAR-unitcell [OPTIONS]
+```
+
+### `--pm`
+
+Unless specified, only one directional displacement is selected among
+symmetrically equivalent displacements in the opposite direction. With this
+option specified, both directions are included in the generated supercells with
+dispacements. Use of this option is recommended.
+
+```
+% phelel --pm [OPTIONS]
+```
+
+## Calculation of derivatives of potentials
+
+After running VASP calculations to calculate local potentials and PAW strenghts
+under the configurations of displacements in supercells, those data are stored
+in cetain files. Those are read and then the derivatives are computed by the
+following command option, e.g.,
+
+```
+% phelel --cd disp-000 disp-001 disp-002 disp-003 disp-004
+```
+
+Here `disp-000`, `disp-001`, ..., indicate the directories in which VASP
+calculations were performed for respective supercells with displacements, i.e.,
+`SPOSCAR`, `POSCAR-001`, ..., as generated in the first step. It is necessary to
+have `phelel_disp.yaml` in the current directory to perform this operation.
+
+### `--cd`, `--create-derivatives`
+
+This triggers two sequential operations. First, VASP calculation results are
+collected from the specified directories in the order given by the command
+options. Displacement information is obtained from the `phelel_disp.yaml` file
+in the current directory. Next, using these collected data, the derivatives of
+local potentials and PAW strengths with respect to displacement are calculated
+and stored in `phelel_params.hdf5`.

doc/velph.md → doc/velph-command.md

@@ -1,10 +1,24 @@
+(velph_command)=
 # velph command
 
 The `velph` command is a convenient tool to systematically perform
 electron-phonon interaction calculations with VASP code and analyze the results.
 Velph works in combination of command options. The `velph` command is installed
 along with the installation of phelel.
 
+The `velph` command orchestrates el-ph calculation {ref}`workflow <workflow>` by
+running its sub-commands in a specific sequence. These `velph` sub-commands can
+perform the following operations:
+
+- Execute `phelel`.
+- Generate VASP input files for the following calculations (required for the
+  subsequent electron-phonon interaction calculation):
+  - Dielectric constant
+  - Born effective charges
+  - Electronic band structure and density of states
+- Generate VASP input files for phonon and lattice thermal conductivity
+  calculations using phonopy and phono3py.
+
 ## Shell completion
 
 Velph relies on [click](https://click.palletsprojects.com), and shell completion

doc/workflow.md

@@ -0,0 +1,36 @@
+(workflow)=
+# Workflow of el-ph calculation
+
+```{note}
+To perform the workflow for electron-phonon related properties (including
+thermoelectric properties), {ref}`velph_command` can be particularly helpful in
+managing the required calculations. For instance, it can generate VASP inputs
+for supercells with displacements as well as the parameters needed to
+incorporate the long-range dipole contribution in electron-phonon interactions.
+Additionally, it enables monitoring of both electronic and phonon band
+structures.
+```
+
+(workflow_minimal)=
+## Minimal calculation steps
+
+1. **(Phelel)** Generate supercell structures with atomic displacements based on the initial unit cell.
+2. **(VASP)** Perform calculations on these supercell structures to obtain local potentials and PAW strengths under the applied atomic displacements.
+3. **(Phelel)** Gather VASP results and compute derivatives of the local potentials and PAW strengths with respect to the atomic displacements.
+4. **(VASP)** Use these derived quantities to calculate electron–phonon interaction strengths and related properties, such as:
+   - Electrical conductivity
+   - Seebeck coefficient
+   - Electrical thermal conductivity
+
+## Additional steps (Optional)
+
+**Before step 4**
+
+- Electronic band structure and density of states calculations
+- Dielectric constant and Born effective charge calculations
+- Phonon band structure calculations
+
+**After step 4**
+
+- Lattice thermal conductivity calculations needed to compute the thermoelectric
+  figure of merit

example/PbTe/POSCAR-unitcell

@@ -0,0 +1,25 @@
+generated by phonopy
+   1.00000000000000
+     6.4405958992591392    0.0000000000000000    0.0000000000000000
+     0.0000000000000000    6.4405958992591392    0.0000000000000000
+     0.0000000000000000    0.0000000000000000    6.4405958992591392
+  Pb              Te
+     4     4
+Direct
+     0.0000000000000000    0.0000000000000000    0.0000000000000000
+     0.0000000000000000    0.5000000000000000    0.5000000000000000
+     0.5000000000000000    0.0000000000000000    0.5000000000000000
+     0.5000000000000000    0.5000000000000000    0.0000000000000000
+     0.5000000000000000    0.5000000000000000    0.5000000000000000
+     0.5000000000000000    0.0000000000000000    0.0000000000000000
+     0.0000000000000000    0.5000000000000000    0.0000000000000000
+     0.0000000000000000    0.0000000000000000    0.5000000000000000
+
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00

example/PbTe/README.md

@@ -0,0 +1,30 @@
+# PbTe example
+
+Conventional unit cell of rocksalt-type PbTe crystal structure is stored in
+`POSCAR-unitcell`. This structure is relaxed with 400 eV cutoff energy and
+PBEsol XC functional. More detail of the relaxation calculation is found in
+`velph-tmpl.toml`.
+
+2x2x2 supercell of the unit cell and the supercells with displacements are
+generated by
+
+```
+% phelel -d --dim 2 2 2 -c POSCAR-unitcell --pa auto --pm
+```
+
+By this command, following files are created. `phelel_disp.yaml` contains
+crystal structure information and `SPOSCAR`, `POSCAR-001`, `POSCAR-002`,
+`POSCAR-003`, `POSCAR-004` files are the perfect supercell and supercells with
+four different displacements, respectively.
+
+Let's assume that these supercell calculations are executed in `disp-000`,
+`disp-001`, `disp-002`, `disp-003`, and `disp-004`. After the VASP calculations
+(`LWAP=.TRUE.` or `ELPH_PREPARE=.TRUE.` in `INCAR` is necessary), phelel
+computes derivatives of local potential and PAW strengths with respect to
+displacements by
+
+```
+% phelel --cd disp-{000..004}
+```
+
+The result is stored in `phelel_params.hdf5`.