Merge branch 'develop' into publish-gh-pages

.github/workflows/publish-gh-pages.yml

@@ -26,7 +26,7 @@ jobs:
       run: |
         conda activate test
         conda install --yes -c conda-forge python=${{ matrix.python-version }}
-        conda install --yes -c conda-forge sphinx-book-theme linkify-it-py myst-parser sphinxcontrib-bibtex ipython
+        conda install --yes -c conda-forge sphinx-book-theme linkify-it-py myst-parser sphinxcontrib-bibtex sphinxcontrib-mermaid ipython
     - name: Build
       run: |
         conda activate test

doc/conf.py

@@ -21,6 +21,7 @@
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
     "sphinx.ext.extlinks",
+    "sphinxcontrib.mermaid",
 ]
 myst_enable_extensions = ["linkify", "dollarmath", "amsmath"]
 

doc/velph-subcommands.md

@@ -9,6 +9,20 @@ The following subcommands must be executed in the directory containing the
 properly organized relative to the current directory where `velph.toml` is
 located.
 
+A typical workflow of velph subcommands for transport property calculation is illustrated below.
+
+```{mermaid}
+graph LR
+A[velph-init] --> B[velph-relax]
+B --> C[velph-init]
+C --> D[velph-nac]
+C --> E[velph-el_bands]
+F[velph-phelel]
+D --> F
+E --> F
+F --> G[velph-transport]
+```
+
 In the following example, two `velph init` command operations generate two
 different directories. The first operation performs crystal structure relaxation
 in the `relax` directory. The second operation, using the relaxed crystal
@@ -60,6 +74,105 @@ VASP input files will be generated by "velph phelel generate".
 ...
 ```
 
+## `velph init`
+
+See {ref}`velph_init`.
+
+## `velph hints`
+
+See {ref}`velph_hints`.
+
+## `velph relax`
+
+It is recommended to create a project directory secific for relaxation
+calculation, e.g., as
+
+```bash
+% ls
+POSCAR-unitcell  POTCAR  velph-tmpl.toml
+% velph init --template-toml velph-tmpl.toml POSCAR-unitcell relax
+...
+% cd relax
+% ls
+POTCAR  velph.toml
+% velph relax generate
+...
+```
+### `velph relax generate`
+
+This subcommand generates VASP input files and a job script for crystal
+structure relaxation. Initially, these files are created in the `iter1`
+directory. The process supports multiple relaxation steps, where the `CONTCAR`
+file from the previous iteration is used as the `POSCAR` for the next step once
+the preceding VASP calculation is complete. Each subsequent set of input files
+is generated in directories named `iter2`, `iter3`, and so on.
+
+```bash
+% ls
+POTCAR  velph.toml
+% velph relax generate
+VASP input files were made in "relax/iter1".
+...
+# Run VASP calculation in relax/iter1
+...
+% ls
+POTCAR  relax/  velph.toml
+% velph relax generate
+"relax/iter1" exists.
+"relax/iter1/CONTCAR" will be as new "POSCAR".
+VASP input files were made in "relax/iter2".
+...
+```
+
+(velph_nac_subcommand)=
+## `velph nac`
+
+This subcommand is used to prepare VASP input files for calculating the
+dielectric constant and Born effective charges. These quantities are required
+for the non-analytical term correction in phonon calculations and for handling
+the long-range terms in electron-phonon interaction calculations.
+
+### `velph nac generate`
+
+After the VASP calculation is complete, the dielectric constant and Born
+effective charges are extracted from the `vasprun.xml` file during the execution
+of `velph phelel init`, `velph phono3py init`, or `velph phonopy init`. The
+extracted values are then written to `phelel_disp.yaml`, `phono3py_disp.yaml`,
+or `phonopy_disp.yaml`, respectively.
+
+```bash
+% velph nac generate
+VASP input files were made in "nac".
+```
+
+## `velph el_bands`
+
+This subcommand is used to prepare VASP input files for electronic band
+structure and density of states calculations, and to plot the resulting data.
+
+### `velph el_bands generate`
+
+The VASP input files have been prepared so that the calculation results will be
+stored in `vaspout.h5`.
+
+```bash
+% velph el_bands generate
+VASP input files were made in "el_bands/bands".
+VASP input files were made in "el_bands/dos".
+```
+
+### `velph el_bands plot`
+
+The electronic band structure and density of states are plotted and saved in the
+`el_bands.pdf` file. The energy range must be specified using the `--windows`
+option, with the first and second arguments representing the range below and
+above the Fermi energy in eV, respectively.
+
+```bash
+% velph el_bands plot --window -5 9
+Electronic band structure plot was saved in "el_bands/el_bands.pdf".
+```
+
 ## `velph phelel`
 
 This subcommand calculates the derivatives of local potentials and PAW strengths
@@ -121,6 +234,14 @@ Running finufft (eps=1.000e-06)...
 (velph_phelel_phonopy_subcommand)=
 ### `velph phelel phonopy`
 
+```{note}
+This subcommand is similar to `velph ph_bands`, but the phonon band structure is
+calculated using the phonopy code. While the phonon calculation routines of VASP
+and phonopy are expected to yield similar results, they are not entirely
+equivalent. However, for electron-phonon calculations, the VASP routine is
+utilized.
+```
+
 `phonopy_params.yaml` that contains information necessary for phonon calculation
 by the phonopy code is generated from `phelel_disp.yaml` and the results of the
 VASP inputs generated by `velph phelel generate`.
@@ -133,82 +254,76 @@ VASP inputs generated by `velph phelel generate`.
 
 ## `velph transport`
 
+This subcommand is used to prepare VASP input files for calculating transport
+properties based on electron-phonon interactions.
+
 ### `velph transport generate`
 
+The VASP input files are prepared for transport property calculations. Users
+should review the generated `INCAR` tags and modify them as necessary for the
+target material. If results from `el_bands/dos` calculations are available, the
+maximum band index for the self-energy calculation is estimated and written into
+the `INCAR` file.
+
+```bash
+% velph transport generate
+Found "el_bands/dos" directory. Estimate elph_selfen_band_stop.
+  "elph_selfen_band_stop=5" in INCAR is set.
+VASP input files were generated in "transport".
+```
+
 ### `velph transport plot`
 
-## `velph relax`
+The following command opens a graphical window that contains plots of transport
+properties in `vaspout.h5`.
 
-It is recommended to create a project directory secific for relaxation
-calculation, e.g., as
+```bash
+% velph transport plot transport
+```
+
+The following command opens a graphical window that displays eigenvalues in the
+Brillouin zone with non-zero and non-one occupations. The eigenvalues are
+obtained from `vaspout.h5`, and their occupations are calculated based on the
+temperature and Fermi level specified through the command options.
 
 ```bash
-% ls
-POSCAR-unitcell  POTCAR  velph-tmpl.toml
-% velph init --template-toml velph-tmpl.toml POSCAR-unitcell relax
-...
-% cd relax
-% ls
-POTCAR  velph.toml
-% velph relax generate
-...
+% velph transport plot eigenvalues
+mu: 4.837002 eV
+temperature: 300.000000 K
+No eigenvalues to plot.
+% velph transport plot eigenvalues --mu 4
 ```
-### `velph relax generate`
 
-This subcommand generates VASP input files and a job script for crystal
-structure relaxation. Initially, these files are created in the `iter1`
-directory. The process supports multiple relaxation steps, where the `CONTCAR`
-file from the previous iteration is used as the `POSCAR` for the next step once
-the preceding VASP calculation is complete. Each subsequent set of input files
-is generated in directories named `iter2`, `iter3`, and so on.
+The following command opens a graphical window that displays Fan self-energies.
 
 ```bash
-% ls
-POTCAR  velph.toml
-% velph relax generate
-VASP input files were made in "relax/iter1".
-...
-# Run VASP calculation in relax/iter1
-...
-% ls
-POTCAR  relax/  velph.toml
-% velph relax generate
-"relax/iter1" exists.
-"relax/iter1/CONTCAR" will be as new "POSCAR".
-VASP input files were made in "relax/iter2".
-...
+% velph transport plot selfenergy
 ```
 
-(velph_nac_subcommand)=
-## `velph nac`
+## `velph ph_bands`
 
-This subcommand is used to calculate dielectric constant and Born effective
-charges that are used for non-analytical term correction of phonon calculation
-and treatment of long range term of electron-phonon interaction calculation.
+This subcommand is used to prepare VASP input files for phonon band structure
+calculation using the supercell force constants stored in `phelel_params.hdf5`,
+and to plot the resulting data.
 
-### `velph nac generate`
+### `velph ph_bands generate`
 
-After the VASP calculation is complete, the dielectric constant and Born
-effective charges are extracted from the `vasprun.xml` file during the execution
-of `velph phelel init`, `velph phono3py init`, or `velph phonopy init`. The
-extracted values are then written to `phelel_disp.yaml`, `phono3py_disp.yaml`,
-or `phonopy_disp.yaml`, respectively.
+The VASP input files including `QPOINTS` are prepared so that the
+calculation results will be stored in `vaspout.h5`.
 
 ```bash
-% velph nac generate
-VASP input files were made in "nac".
+% velph ph_bands generate
+VASP input files were made in "ph_bands/bands".
 ```
 
-## `velph el_bands`
-
-### `velph el_bands generate`
-### `velph el_bands plot`
+### `velph ph_bands plot`
 
-## `velph ph_bands`
+The phonon band structure is plotted and saved in the `ph_bands.pdf` file.
 
-### `velph ph_bands generate`
-
-### `velph ph_bands plot`
+```bash
+% velph ph_bands plot
+Phonon band structure plot was saved in "ph_bands/ph_bands.pdf".
+```
 
 ## `velph phono3py`
 

src/phelel/velph/cli/ph_bands/generate.py

@@ -17,7 +17,10 @@
 )
 
 
-def write_input_files(toml_filename: pathlib.Path) -> None:
+def write_input_files(
+    toml_filename: pathlib.Path,
+    dir_name: str = "phelel",
+) -> None:
     """Generate VASP inputs to generate phonon band structure."""
     with open(toml_filename, "rb") as f:
         toml_dict = tomli.load(f)
@@ -58,12 +61,12 @@ def write_input_files(toml_filename: pathlib.Path) -> None:
     )
 
     # phelel_params.hdf5
-    if pathlib.Path("supercell/phelel_params.hdf5").exists():
+    if pathlib.Path(f"{dir_name}/phelel_params.hdf5").exists():
         shutil.copy2(
-            "supercell/phelel_params.hdf5", "ph_bands/bands/phelel_params.hdf5"
+            f"{dir_name}/phelel_params.hdf5", "ph_bands/bands/phelel_params.hdf5"
         )
     else:
-        click.echo('"supercell/bands/phelel_params.hdf5" not found.', err=True)
+        click.echo(f'"{dir_name}/bands/phelel_params.hdf5" not found.', err=True)
         return None
 
     # POTCAR

src/phelel/velph/cli/selfenergy/generate.py

@@ -173,7 +173,7 @@ def _estimate_elph_selfen_band_stop(
         is 0.5 eV.
     occupation_condition : float
         Condition to determine either if bands are occupied or not. This value
-        is used as occupation_number > occupation_condition. Default is 1e-5.
+        is used as occupation_number > occupation_condition. Default is 1e-10.
 
     Returns
     -------

src/phelel/velph/cli/transport/plot/__init__.py

@@ -138,7 +138,6 @@ def cmd_plot_eigenvalues(
         plot_eigenvalues(
             args[0],
             tid=tid,
-            nid=nid,
             temperature=temperature,
             cutoff_occupancy=cutoff_occupancy,
             mu=mu,

src/phelel/velph/cli/transport/plot/plot_selfenergy.py

@@ -22,11 +22,14 @@ def plot_selfenergy(f_h5py: h5py.File, plot_filename: str, save_plot: bool = Fal
     import matplotlib.pyplot as plt
 
     selfens = {}
-    for key in f_h5py["results"]["electron_phonon"]["electrons"]:
+    f_elph = f_h5py["results/electron_phonon/electrons"]
+    for key in f_elph:
         if "self_energy_" in key:
-            selfens[int(key.split("_")[2])] = f_h5py["results"]["electron_phonon"][
-                "electrons"
-            ][key]
+            index = key.split("_")[-1]
+            if index.isdigit():
+                selfens[int(index)] = f_elph[key]
+
+    assert len(selfens) == int(f_elph["self_energy_meta/ncalculators"][()])
 
     if len(selfens) == 1:
         fig, axs = plt.subplots(1, 1, figsize=(4, 4))

src/phelel/velph/cli/transport/plot/plot_transport.py

@@ -35,13 +35,12 @@ def plot_transport(f_h5py: h5py.File, plot_filename: str, save_plot: bool = Fals
         "seebeck",
     )
 
+    f_elph = f_h5py["results/electron_phonon/electrons"]
+
     n_transport = len(
-        [
-            key
-            for key in f_h5py["results/electron_phonon/electrons"]
-            if "transport_" in key
-        ]
+        [key for key in f_elph if "transport_" in key and key.split("_")[1].isdigit()]
     )
+    assert n_transport == int(f_elph["transport_meta/ncalculators"][()])
     transports = [
         f_h5py[f"results/electron_phonon/electrons/transport_{n + 1}"]
         for n in range(n_transport)