Merge branch 'develop' into rc

.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/changelog.md

@@ -2,6 +2,10 @@
 
 # Change Log
 
+## Jan-10-2025: Version 0.8.2
+
+- Collection of small updates of velph command
+
 ## Jan-8-2025: Version 0.8.1
 
 - Fix minor bugs in velph command

doc/conf.py

@@ -11,7 +11,7 @@
 author = "Atsushi Togo"
 
 version = "0.8"
-release = "0.8.1"
+release = "0.8.2"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -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/index.md

@@ -31,6 +31,7 @@ install
 workflow
 phelel-command
 velph-command
+velph-toml
 velph-init
 velph-init-template
 velph-subcommands

doc/velph-command.md

@@ -20,6 +20,21 @@ and calculate derivatives of the local potential and PAW strengths with respect
 to atomic displacement, resulting in the `phelel_params.hdf5` file. Most of the
 `velph` subcommands are explained in {ref}`velph_subcommands`.
 
+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]
+```
+
 A list of supported subcommands is displayed by typing:
 
 ```bash
@@ -46,6 +61,57 @@ Commands:
   transport   Choose transport options.
 ```
 
+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
+structure, carries out additional calculations required for electron-phonon
+interactions in the `calc` directory. Details about `velph-tmpl.toml` are
+described in {ref}`velph_init_template`.
+
+```bash
+% ls
+POSCAR-unitcell  POTCAR  velph-tmpl.toml
+% velph init --template-toml velph-tmpl.toml POSCAR-unitcell relax
+...
+% cd relax
+% velph relax generate
+...
+# Run VASP relaxation calculation
+...
+% cd ..
+% ls
+POSCAR-unitcell  POTCAR  relax/  velph-tmpl.toml
+% velph init --template-toml velph-tmpl.toml `ls relax/relax/iter*/CONTCAR|tail -n 1` calc
+...
+% cd calc
+% ls
+POTCAR  velph.toml
+% velph nac generate
+VASP input files were made in "nac".
+% ls
+POTCAR  nac/  velph.toml
+...
+# Run NAC calculation
+...
+% velph phelel init
+Found "nac" directory. Read NAC params.
+"phelel/phelel_disp.yaml" was generated.
+VASP input files will be generated by "velph phelel generate".
+% velph phelel generate
+VASP input files were generated in "phelel/disp-000".
+VASP input files were generated in "phelel/disp-001".
+VASP input files were generated in "phelel/disp-002".
+VASP input files were generated in "phelel/disp-003".
+VASP input files were generated in "phelel/disp-004".
+% ls
+POTCAR  nac/  phelel/  velph.toml
+% velph phelel init
+Found "nac" directory. Read NAC params.
+"phelel/phelel_disp.yaml" was generated.
+VASP input files will be generated by "velph phelel generate".
+...
+```
+
 (velph_hints)=
 ## `velph hints`
 

doc/velph-init-template.md

@@ -1,19 +1,23 @@
 (velph_init_template)=
 # `velph init` template
 
-`velph init` is the command to prepare `velph.toml`. Without specifying a
-velph-toml-template, the default template is used. Custom template can be
-specified as follows:
+The `velph init` command is used to prepare the `velph.toml` file. If no custom
+template is specified, a default template is applied. To specify a custom
+template, use the following command:
 
+```bash
+% velph init CELL_FILENAME PROJECT_FOLDER --template-toml velph-tmpl.toml [OPTIONS]
 ```
-% velph init [OPTIONS] CELL_FILENAME PROJECT_FOLDER --template-toml velph-tmpl.toml
-```
 
-The `velph-tmpl.toml` (arbitrary file name) is almost like the `velph.toml`
-file. It means that the `velph-tmpl.toml` may be created modifying
-`velph.toml`. The sections that exist only in the `velph-tmpl.toml` but not in
-`velph.toml` is `[init.options]`. This can be used as alternatives of command
-options of `velph-init`, e.g.,
+The `velph-tmpl.toml` file (which can have any file name) is similar to the
+`velph.toml` file. It can be created by modifying an existing `velph.toml`.
+However, a key difference is that `velph-tmpl.toml` may include an
+`[init.options]` section that is not present in `velph.toml`. This section
+allows you to define default values as substitutes for command-line options used
+with `velph init`, as described in the next section.
+
+(velph_init_template_init_options)=
+## `[init.options]`
 
 ```toml
 [init.options]
@@ -22,83 +26,30 @@ kspacing_dense = 0.1
 max_num_atoms = 120
 ```
 
-These `[init.options]` keywords can be found along with the list of the command
-options by
+The `[init.options]` keywords correspond to command-line options for `velph
+init`. To view a complete list of available options, use:
 
-```
+```bash
 % velph init --help
 ```
 
-## Settings in sections of `velph.toml`
-
-Note that the same can be applied to `velph-tmpl.toml`.
-
-### Default INCAR settings
-
-The default INCAR settins are written in `[vasp.incar]`. These settings are
-overwritten by `[vasp.CALC_TYPE.incar]` (`CALC_TYPE` can be `phelel`, `relax`,
-`nac`, `transport`, `phono3py`, `phono3py.phonon`, etc).
-
-### Scheduler settings
+(velph_init_template_incar)=
+## `[vasp.incar]`
 
-The parameters used for generating the job submission script are specified as
-strings in `[scheduler]`. If `[vasp.CALC_TYPE.scheduler]` is
-specified, `[scheduler]` settings are overwritten by the settings for
-`[vasp.CALC_TYPE]`. The content in this section operates through [Python string
-formatting](https://docs.python.org/3/library/stdtypes.html#str.format), using
-replacement fields named after keyword arguments. Each parameter line in the
-`[scheduler]` section is treated as a keyword argument, which is then inserted
-into the string format.
-
-In the `[scheduler]` section, the parameters `scheduler_name` and
-`scheduler_template` have special roles:
-
-- `scheduler_name`: Specifies the template type, with options `slurm`, `sge`, or
-  `custom`. For `slurm` and `sge`, the template string (i.e.,
-  `scheduler_template`) is
-  [hard-coded](https://github.com/phonopy/phelel/blob/develop/src/phelel/velph/utils/scheduler.py).
-  If `custom` is selected, the string provided by `scheduler_template` is used,
-  into which the parameters are inserted.
-- `scheduler_template`: The string template where parameters defined in this
-  section are inserted.
-
-An example is shown below.
+The base INCAR settings are defined in the `[vasp.incar]` section. These
+settings can be overridden by the `[vasp.CALC_TYPE.incar]` section if existed,
+where `CALC_TYPE` could be `phelel`, `relax`, `nac`, `transport`, `phono3py`,
+`phono3py.phonon`, etc. For example, consider the following configuration:
 
 ```toml
-[scheduler]
-scheduler_name = "sge"
-job_name = "PbTe"
-mpirun_command = "mpirun"
-vasp_binary = "/usr/local/cluster-1/bin/vasp_std"
-pe = "vienna 32"
-prepend_text = '''
-source /opt/intel/oneapi/setvars.sh --config="/home/togo/.oneapi-config"
-'''
-
-...
-[vasp.phelel.scheduler]
-pe = "paris 24"
-
-...
-[vasp.phonopy.scheduler]
-scheduler_template = '''#!/bin/bash
-#QSUB2 core 192
-#QSUB2 mpi 192
-#QSUB2 smp 1
-#QSUB2 wtime 48:00:00
-#PBS -N {job_name}
-cd $PBS_O_WORKDIR
-
-{prepend_text}
-{mpirun_command} {vasp_binary} | tee vasp_output
-{append_text}
-'''
-job_name = "PbTe"
-mpirun_command = "mpijob"
-vasp_binary = "/usr/local/cluster-2/bin/vasp_std"
-prepend_text = '''
-. /etc/profile.d/modules.sh
-module load inteloneapi22u3
-'''
-append_text = ""
+[vasp.incar]
+encut = 400
+ncore = 4
+gga = "PS"
 ```
+
+In this case, the `[vasp.phelel.incar]` section in `velph.toml` is initially
+populated with these base settings. And then, the default parameters specific to
+the `phelel` calculation, as well as any settings defined in the
+`[vasp.phelel.incar]` section of the template, will override these
+configurations as needed.