Merge branch 'develop' into rc

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
   - id: check-added-large-files
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.8.4
+  rev: v0.8.6
   hooks:
   - id: ruff
     args: [ "--fix", "--show-fixes" ]

doc/changelog.md

@@ -2,7 +2,11 @@
 
 # Change Log
 
-## Jan-5-2024: Version 0.8.0
+## Jan-8-2025: Version 0.8.1
+
+- Fix minor bugs in velph command
+
+## Jan-5-2025: Version 0.8.0
 
 - Refactoring of `Phelel` class
 - Major update of documentation

doc/conf.py

@@ -11,7 +11,7 @@
 author = "Atsushi Togo"
 
 version = "0.8"
-release = "0.8.0"
+release = "0.8.1"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

doc/index.md

@@ -31,5 +31,10 @@ install
 workflow
 phelel-command
 velph-command
+velph-init
+velph-init-template
+velph-subcommands
+velph-example
+reference
 changelog
 ```

doc/install.md

@@ -5,7 +5,7 @@
 * phonopy
 * phono3py
 * spglib
-* finufft
+* {ref}`reference_finufft`
 * click
 * tomli
 * tomli-w
@@ -32,3 +32,47 @@ From source code of phelel,
 ```
 
 The pypi package is also available.
+
+## `phelel` and `velph` commands
+
+Installing the phelel package makes the `phelel` and `velph` commands available.
+Their usage is described in {ref}`phelel_command` and {ref}`velph_command`,
+respectively. Additionally, the `velph` command supports shell completion, which
+requires further configuration as described in the next section.
+
+### Shell completion of `velph` command
+
+Velph relies on [click](https://click.palletsprojects.com), and shell completion
+is provided for popular shell implementations, see
+[shell-completion](https://click.palletsprojects.com/en/stable/shell-completion/).
+
+For example using bash (zsh) in conda environment, write the following line
+
+```
+eval "$(_VELPH_COMPLETE=bash_source velph)"  # BASH
+```
+
+```
+eval "$(_VELPH_COMPLETE=zsh_source velph)"  # ZSH
+```
+
+in `~/.bashrc` (`~/.zshrc`), or in a conda environment in
+`$CONDA_PREFIX/etc/conda/activate.d/env_vars.sh`.
+
+After setting and reloading the configuration file (e.g., `~/.bashrc`),
+sub-commands are listed by pushing tab key:
+
+```bash
+% velph [PUSH-TAB-KEY]
+el_bands    -- Choose electronic band structure options.
+generate    -- Write POSCAR-unitcell and POSCAR-primitive.
+hints       -- Show velph command hints.
+init        -- Initialize an electron phonon calculation...
+nac         -- Choose nac options.
+ph_bands    -- Choose phonon band structure options.
+phelel      -- Choose supercell options.
+phono3py    -- Choose phono3py options.
+relax       -- Choose relax options.
+selfenergy  -- Choose selfenergy options.
+transport   -- Choose transport options.
+```

doc/phelel-command.md

@@ -1,5 +1,5 @@
 (phelel_command)=
-# 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`
@@ -8,7 +8,7 @@ phonon calculations.
 
 The following example demonstrates operations using the `phelel` command:
 
-```
+```bash
 % phelel -d --dim 2 2 2 -c POSCAR-unitcell --pa auto --pm
 
 # After running VASP calculations in directories corresponding to displacements:
@@ -21,7 +21,7 @@ The following example demonstrates operations using the `phelel` command:
 Supercells with displacements can be generated by combining the following
 command options. For example:
 
-```
+```bash
 % phelel -d --dim 2 2 2 -c POSCAR-unitcell --pa auto --pm
 ```
 
@@ -46,11 +46,11 @@ 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.
 
-```
+```bash
 % phelel --dim 2 2 2 [OPTIONS]
 ```
 
-```
+```bash
 % phelel --dim 0 1 1 1 0 1 1 1 0 [OPTIONS]
 ```
 
@@ -59,7 +59,7 @@ corresponding integer factor.
 
 Unit cell structure is specified.
 
-```
+```bash
 % phelel -c POSCAR-unitcell [OPTIONS]
 ```
 
@@ -70,7 +70,7 @@ 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.
 
-```
+```bash
 % phelel --pm [OPTIONS]
 ```
 
@@ -81,7 +81,7 @@ 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.,
 
-```
+```bash
 % phelel --cd disp-000 disp-001 disp-002 disp-003 disp-004
 ```
 

doc/reference.md

@@ -0,0 +1,12 @@
+(references)=
+# References
+
+This page presents the methodologies and software packages that the phelel code relies on.
+
+(reference_finufft)=
+## finufft
+
+The local potentials from VASP calculation results are interpolated using
+[finufft](https://finufft.readthedocs.io/). For more information and references
+on finufft, visit
+[https://finufft.readthedocs.io/en/latest/refs.html](https://finufft.readthedocs.io/en/latest/refs.html).