Merge branch 'develop' into publish-gh-pages

doc/phelel-command.md

@@ -1,7 +1,100 @@
 (phelel_command)=
 # phelel command
 
-These command-line tools are used to perform the steps 1 and 3 in {ref}`the
-el-ph calculation workflow <workflow>`. Usage of `phelel` and `phelel-load`
-commands are similar to `phonopy` and `phonopy-load` commands in
-[phonopy](https://phonopy.github.io/phonopy/) code for phonon calculation.
+Command-line tools perform steps 1 and 3 in {ref}`the el-ph calculation
+workflow <workflow>`. 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:
+
+```bash
+% 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:
+
+```bash
+% 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.
+
+```bash
+% phelel --dim 2 2 2 [OPTIONS]
+```
+
+```bash
+% phelel --dim 0 1 1 1 0 1 1 1 0 [OPTIONS]
+```
+
+
+### `-c`, `--cell`
+
+Unit cell structure is specified.
+
+```bash
+% 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.
+
+```bash
+% 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.,
+
+```bash
+% 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`.