Update doc

doc/auxiliary-tools.md

@@ -39,7 +39,7 @@ Let's compute lattice thermal conductivity of Si using the `Si-PBEsol` example
 found in the example directory.
 
 ```bash
-% phono3py --mesh="11 11 11" --sym-fc --br
+% phono3py --mesh="11 11 11" --fc-symmetry --br
 ```
 
 Then using the output file, `kappa-m111111.hdf5`, run `phono3py-kaccum` as

doc/command-options.md

@@ -2,6 +2,10 @@
 
 # Command options / Setting tags
 
+(use_config_with_option)=
+
+## Use of configuration file
+
 Phono3py is operated with command options or with a configuration file that
 contains setting tags. In this page, the command options are explained. Most of
 command options have their respective setting tags.
@@ -27,13 +31,19 @@ CELL_FILENAME = POSCAR-unitcell
 where the setting tag names are case insensitive. This is run by
 
 ```bash
-% phono3py setting.conf [command options]
+% phono3py setting.conf [OPTIONS]
 ```
 
 or
 
 ```bash
-% phono3py [command options] -- setting.conf
+% phono3py [OPTIONS] -- setting.conf
+```
+
+When using `phono3py-load` (see also {ref}`phono3py_load_command`)
+
+```bash
+% phono3py-load --config setting.conf [OPTIONS]
 ```
 
 ```{contents}
@@ -201,15 +211,32 @@ When using with `--cf2`, `--cf3` has to be specified simultaneously as below,
 
 ### `--dim` (`DIM`)
 
+**`phono3py-load` doesn't have this option.**
+
 Supercell dimension is specified. See the detail at
-<http://phonopy.github.io/phonopy/setting-tags.html#dim>. When a proper
+<http://phonopy.github.io/phonopy/setting-tags.html#dim>. When
-`phono3py_disp.yaml` exists in the current directory, this is unnecessary to be
+`phono3py_disp.yaml` is found in the current directory, it is read
-specified.
+automatically. Since supercell dimension is written in this file, `--dim` is
+unnecessary to specify. For example, just
+
+```bash
+% phono3py --fc-symmetry
+```
+
+or
+
+```bash
+% phono3py --symfc
+```
+
+can be used to calculate force constants.
 
 (dim_fc2_option)=
 
 ### `--dim-fc2` (`DIM_FC2`)
 
+**`phono3py-load` doesn't have this option.**
+
 Supercell dimension for 2nd order force constants (for harmonic phonons) is
 specified. This is optional. When a proper `phono3py_disp.yaml` exists in the
 current directory, this is unnecessary to be specified.
@@ -228,7 +255,7 @@ supercell size and these force calculations have to be done in addition to the
 usual force calculations for 3rd order force constants.
 
 ```bash
-% phono3py -d --dim="2 2 2" --dim-fc2="4 4 4" -c POSCAR-unitcell
+% phono3py -d --dim 2 2 2 --dim-fc2 4 4 4 --pa auto -c POSCAR-unitcell
 ```
 
 After the force calculations, `--cf2` option is used to create `FORCES_FC2`.
@@ -253,10 +280,11 @@ that created in the usual phono3py run without `--dim-fc2` option.
 ### `--pa`, `--primitive-axes` (`PRIMITIVE_AXES`)
 
 Transformation matrix from a non-primitive cell to the primitive cell. See
-phonopy `PRIMITIVE_AXES` tag (`--pa` option) at
+phonopy `PRIMITIVE_AXES` tag (`--pa` option) at [primitive-axis
-<http://phonopy.github.io/phonopy/setting-tags.html#primitive-axis>. When a proper
+(phonopy)](https://phonopy.github.io/phonopy/setting-tags.html#primitive-axes-or-primitive-axis).
-`phono3py_disp.yaml` exists in the current directory, this is unnecessary to be
+When `phono3py_disp.yaml` contains this information and `phono3py_disp.yaml` is
-specified.
+read when running `phono3py` or `phono3py-load` command, this is unnecessary to
+be specified.
 
 ### `--mass` (`MASS`)
 
@@ -273,24 +301,45 @@ web page](https://phonopy.github.io/phonopy/setting-tags.html#magmom).
 (create_displacements_option)=
 ### `-d` (`CREATE_DISPLACEMENTS = .TRUE.`)
 
-Supercell with displacements are created. Using with `--amplitude` option,
+**`phono3py-load` doesn't have this option.**
-atomic displacement distances are controlled. With this option, files for
-supercells with displacements and `phono3py_disp.yaml` file are created. `--pa`
-should be specified if the input unit cell structure is not a primitive cell,
-e.g., `--pa="F"` if the input unit cell has F-centring.
 
+Supercells with displacements and `phono3py_disp.yaml` are created. Using with
+`--amplitude` option, atomic displacement distances are controlled. With this
+option, files for supercells with displacements and `phono3py_disp.yaml` file
+are created.
+
+It is recommended to use this option with `--pa auto` option to store
+information about primitive cell (`primitive_matrix` key) in
+`phono3py_disp.yaml`, e.g.,
+
+```bash
+% phono3py -c POSCAR-unitcell -d --dim 2 2 2 --dim-fc2 4 4 4 --pa auto
+```
 
 (random_displacements_option)=
 ### `--rd` (`RANDOM_DISPLACEMENTS`), `--rd-fc2` (`RANDOM_DISPLACEMENTS_FC2`) and `--random-seed` (`RANDOM_SEED`)
 
+**`phono3py-load` doesn't have this option.**
+
+See also {ref}`random-displacements`.
+
 Random directional displacements are generated for fc3 and fc2 supercells by
 `--rd` and `--rd-fc2`, respectively. `--amplitude` and `--random-seed` options
 may be used together. These are used in the equivalent way to [`--rd` of
 phonopy](https://phonopy.github.io/phonopy/setting-tags.html#random-displacements).
 
+Like `-d` option, it is recommended to specify `--pa auto` together with `--rd`
+and/or `--rd-fc2`,
+
+```bash
+% phono3py -c POSCAR-unitcell --dim 2 2 2 --dim-fc2 4 4 4 --rd 100 --rd-fc2 2 --pa auto
+```
+
 (amplitude_option)=
 ### `--amplitude` (`DISPLACEMENT_DISTANCE`)
 
+**`phono3py-load` doesn't have this option.**
+
 Atomic displacement distance is specified. This value may be increased for the
 weak interaction systems and decreased when the force calculator is numerically
 very accurate.
@@ -303,13 +352,13 @@ The default value depends on calculator. See
 
 Choice of force constants calculator.
 
-```
+```bash
-% phono3py --fc-calc symfc ...
+% phono3py-load --fc-calc symfc ...
 ```
 
 To use different force constants calculators for fc2 and fc3
-```
+```bash
-% phono3py --fc-calc "symfc|" ...
+% phono3py-load --fc-calc "symfc|" ...
 ```
 Those for fc2 and fc3 are seprated by `|` such as `symfc|` . Blank means to
 employ the finite difference method for systematic displacements generated by
@@ -320,8 +369,8 @@ the option `-d`.
 
 Special options for force constants calculators.
 
-```
+```bash
-% phono3py --fc-calc-opt "cutoff=8" ...
+% phono3py-load --fc-calc-opt "cutoff=8" ...
 ```
 
 Similarly to `--fc-calc`, `|` can be used to separated those for fc2 and fc3.
@@ -336,6 +385,9 @@ Similarly to `--fc-calc`, `|` can be used to separated those for fc2 and fc3.
 
 These are shortcuts of `--fc-calc symfc` and `--fc-calc alm`, respectively.
 
+Please be careful that `--symfc` and `--sym-fc` (deprecated) are similar, but
+different.
+
 ## Force constants
 
 (compact_fc_option)=
@@ -352,16 +404,16 @@ data size becomes large. If the input crystal structure has centring
 {ref}`--pa <pa_option>` is necessary to have smallest data size. In this case,
 `--pa` option has to be specified on reading. Otherwise phono3py can recognize
 if `fc2.hdf5` and `fc3.hdf5` are compact or full automatically. When using with
-`--sym-fc`, the calculated results will become slightly different due to
+`--fc-symmetry`, the calculated results will become slightly different due to
 imperfect symmetrization scheme that phono3py employs.
 
 ```bash
-% phono3py --dim="2 2 2" --cfc --pa="F" -c POSCAR-unitcell
+% phono3py-load --compact-fc
 ```
 
 (symmetrization_option)=
 
-### `--sym-fc` (`FC_SYMMETRY = .TRUE.`)
+### `--fc-symmetry` (`FC_SYMMETRY = .TRUE.`)
 
 Second- and third-order force constants are symmetrized. The index exchange of
 real space force constants and translational invariance symmetry are applied in a
@@ -390,15 +442,16 @@ supercell size and the second choice is using `--cutoff-pair` option.
 
 ### `--cutoff-pair` or `--cutoff-pair-distance` (`CUTOFF_PAIR_DISTANCE`)
 
-This option works differently for the `-d` and `--rd` options.
+This option works in two ways.
 
-For `-d`, A cutoff pair-distance in a supercell is used to reduce the number of
+When using with `-d` options, a cutoff pair-distance in a supercell is used to
-necessary supercells with displacements to obtain third order force constants.
+reduce the number of necessary supercells with displacements to obtain third
-As the drawback, a certain number of third-order-force-constants elements are
+order force constants. As the drawback, a certain number of
-abandoned or computed with less numerical accuracy. More details are found at
+third-order-force-constants elements are abandoned or computed with less
-{ref}`command_cutoff_pair`.
+numerical accuracy. More details are found at {ref}`command_cutoff_pair`.
 
-For `--rd`, `--cutoff-pair VAL` is equivalent to `--fc-calc-opt "cutoff=VAL"`.
+When using with an external force constants calculator, `--cutoff-pair VAL` works
+equivalent to `--fc-calc-opt "cutoff=VAL"`.
 
 ### `--alm`
 
@@ -436,10 +489,10 @@ The mapping table between grid points to its indices is obtained by running with
 `--loglevel=2` option.
 
 ```bash
-% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc3 --fc2 --br --write-gamma --gp="0 1 2 3 4 5"
+% phono3py-load --mesh 19 19 19 --br --write-gamma --gp 0 1 2 3 4 5
 ```
 
-where `--gp="0 1 2 3 4 5"` can be also written `--gp="0,1,2,3,4,5"`. `--ga`
+where `--gp 0 1 2 3 4 5` can be also written `--gp="0,1,2,3,4,5"`. `--ga`
 option below can be used similarly for the same purpose.
 
 (ga_option)=
@@ -447,10 +500,10 @@ option below can be used similarly for the same purpose.
 ### `--ga` (`GRID_ADDRESSES`)
 
 This is used to specify grid points like `--gp` option but in their addresses
-represented by integer numbers. For example with `--mesh="16 16 16"`, a q-point
+represented by integer numbers. For example with `--mesh 16 16 16`, a q-point
-of (0.5, 0.5, 0.5) is given by `--ga="8 8 8"`. The values have to be integers.
+of (0.5, 0.5, 0.5) is given by `--ga 8 8 8`. The values have to be integers.
 If you want to specify the point on a path,
-`--ga="0 0 0 1 1 1 2 2 2 3 3 3 ..."`, where each three values are recognized as
+`--ga 0 0 0 1 1 1 2 2 2 3 3 3 ...`, where each three values are recognized as
 a grid point. The grid points given by `--ga` option are translated to grid
 point indices as given by `--gp` option, and the values given by `--ga` option
 will not be shown in log files.
@@ -466,7 +519,7 @@ band indices where the values are calculated and summed and averaged over those
 bands.
 
 ```bash
-% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="16 16 16" -c POSCAR-unitcell --nac --gp="34" --bi="4 5, 6"
+% phono3py-load --mesh 16 16 16 --nac --gp 34 --bi "4 5, 6"
 ```
 
 This option may be also useful to distribute the computational demand such like
@@ -489,7 +542,7 @@ calculated divided these integers by sampling mesh numbers for respective
 reciprocal axes.
 
 ```bash
-% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --wgp
+% phono3py-load --mesh 19 19 19 --wgp
 ```
 
 (stp_option)=
@@ -502,7 +555,7 @@ large a calculation is. Only those for specific grid points are shown by using
 with `--gp` or `--ga` option.
 
 ```bash
-% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --stp --gp 20
+% phono3py-load --mesh 19 19 19 --stp --gp 20
 ```
 
 ## Brillouin zone integration
@@ -533,7 +586,7 @@ This is used when we want to test several $\sigma$ values simultaneously.
 The tails of the Gaussian functions that are used to replace delta functions in
 the equation shown at {ref}`--full-pp <full_pp_option>` are cut with this
 option. The value is specified in number of standard deviation.
-`--sigma-cutoff=5` gives the Gaussian functions to be cut at $5\sigma$. Using
+`--sigma-cutoff 5` gives the Gaussian functions to be cut at $5\sigma$. Using
 this option scarifies the numerical accuracy. So the number has to be carefully
 tested. But computation of phonon-phonon interaction strength becomes much
 faster in exchange for it.
@@ -614,27 +667,27 @@ database of the natural abundance data for elements, which refers Laeter _et
 al._, Pure Appl. Chem., **75**, 683 (2003).
 
 ```bash
-% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br --isotope
+% phono3py-load -v --mesh 32 32 20 --br --isotope
 ```
 
 ### `--mass-variances` or `--mv` (`MASS_VARIANCES`)
 
 Mass variance parameters are specified by this option to include phonon-isotope
 scattering effect in the same way as `--isotope` option. For example of GaN,
-this may be set like `--mv="1.97e-4 1.97e-4 0 0"`. The number of elements has to
+this may be set like `--mv 1.97e-4 1.97e-4 0 0`. The number of elements has to
 correspond to the number of atoms in the primitive cell.
 
 Isotope effect to thermal conductivity may be checked first running without
 isotope calculation:
 
 ```bash
-% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br
+% phono3py-load -v --mesh 32 32 20 --br
 ```
 
 Then running with isotope calculation:
 
 ```bash
-% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br --read-gamma --mv="1.97e-4 1.97e-4 0 0"
+% phono3py -v --mesh 32 32 20 --br --read-gamma --mv 1.97e-4 1.97e-4 0 0
 ```
 
 In the result hdf5 file, currently isotope scattering strength is not written
@@ -648,7 +701,7 @@ A most simple phonon boundary scattering treatment is included. $v_g/L$ is just
 used as the scattering rate, where $v_g$ is the group velocity and $L$ is the
 boundary mean free path. The value is given in micrometre. The default value, 1
 metre, is just used to avoid divergence of phonon lifetime and the contribution
-to the thermal conducitivity is considered negligible.
+to the thermal conductivity is considered negligible.
 
 (ave_pp_option)=
 
@@ -691,13 +744,13 @@ option is strongly recommended.
 First, run full conductivity calculation,
 
 ```bash
-% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br
+% phono3py-load -v --mesh 32 32 20 --br
 ```
 
 Then
 
 ```bash
-% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br --read-gamma --ave-pp -o ave_pp
+% phono3py-load -v --mesh 32 32 20 --br --read-gamma --ave-pp -o ave_pp
 ```
 
 ### `--const-ave-pp` (`CONST_AVE_PP = .TRUE.`)
@@ -715,7 +768,7 @@ $\text{eV}^2$.
 See also {ref}`reference papers <ave_pp_reference>`.
 
 ```bash
-% phono3py --dim="3 3 2" -v --mesh="32 32 20" -c POSCAR-unitcell --br --const-ave-pp=1e-10
+% phono3py-load -v --mesh 32 32 20 --br --const-ave-pp 1e-10
 ```
 
 (normal_umklapp_option)=
@@ -739,7 +792,7 @@ The data are stored in `kappa-mxxx(-gx-sx-sdx).hdf5` file and accessed by
 below:
 
 ```bash
-% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="11 11 11" --fc3 --fc2 --br --nu
+% phono3py-load --mesh 11 11 11 --fc3 --fc2 --br --nu
 ...
 % ipython
 
@@ -820,7 +873,7 @@ $$
 Specific temperatures are specified by `--ts`.
 
 ```bash
-% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="11 11 11" -c POSCAR-unitcell --br --ts="200 300 400"
+% phono3py-load -v --mesh 11 11 11 -c POSCAR-unitcell --br --ts 200 300 400
 ```
 
 ### `--tmax`, `--tmin`, `--tstep` (`TMAX`, `TMIN`, `TSTEP`)
@@ -830,7 +883,7 @@ See phonopy's document for the same tags at
 <http://phonopy.github.io/phonopy/setting-tags.html#tprop-tmin-tmax-tstep>.
 
 ```bash
-% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="11 11 11" -c POSCAR-unitcell --br --tmin=100 --tmax=1000 --tstep=50
+% phono3py-load -v --mesh 11 11 11 --br --tmin 100 --tmax 1000 --tstep 50
 ```
 
 ## Non-analytical term correction
@@ -918,7 +971,7 @@ to `gammas-mxxx-gx(-sx)-tx-bx.dat` in THz (without $2\pi$) with respect to
 samplied frequency points of $\omega$ in THz (without $2\pi$).
 
 ```bash
-% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="16 16 16" -c POSCAR-unitcell --nac --q-direction="1 0 0" --gp=0 --ise --bi="4 5, 6"
+% phono3py-load --mesh 16 16 16 --nac --q-direction 1 0 0 --gp 0 --ise --bi "4 5, 6"
 ```
 
 (rse_option)=
@@ -945,7 +998,7 @@ $\Delta_\lambda(\omega)$ is written to `deltas-mxxx-gx-sx-tx-bx.dat` in THz
 (without $2\pi$).
 
 ```bash
-% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="16 16 16" -c POSCAR-unitcell --nac --q-direction="1 0 0" --gp=0 --rse --sigma="0.1" --bi="4 5, 6"
+% phono3py-load --mesh 16 16 16 --nac --q-direction 1 0 0 --gp 0 --rse --sigma 0.1 --bi "4 5, 6"
 ```
 
 (spectral_function_option)=
@@ -982,7 +1035,7 @@ THz (without $2\pi$) with respect to samplied frequency points of $\omega$ in
 THz (without $2\pi$), and `spectral-mxxx-gx.hdf5`.
 
 ```bash
-% phono3py --fc3 --fc2 --dim="2 2 2" --mesh="16 16 16" -c POSCAR-unitcell --nac --q-direction="1 0 0" --gp=0 --spf
+% phono3py-load --mesh 16 16 16 --nac --q-direction 1 0 0 --gp 0 --spf
 ```
 
 ```{note}
@@ -1026,7 +1079,7 @@ $$
 See also {ref}`reference papers <spectral_function_reference>`.
 
 ```bash
-% phono3py --fc2 --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="16 16 16" --jdos --ga="0 0 0  8 8 8"
+% phono3py-load --mesh 16 16 16 --jdos --ga 0 0 0 8 8 8
 ```
 
 When temperatures are specified, two classes of weighted JDOS are calculated.
@@ -1052,7 +1105,7 @@ $$
 See also {ref}`reference papers <spectral_function_reference>`.
 
 ```bash
-% phono3py --fc2 --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="16 16 16" --jdos --ga="0 0 0  8 8 8" --ts=300
+% phono3py-load --mesh 16 16 16 --jdos --ga 0 0 0 8 8 8 --ts 300
 ```
 
 This is an example of `Si-PBEsol`.
@@ -1081,13 +1134,13 @@ Mode-Gruneisen-parameters are calculated from fc3.
 Mesh sampling mode:
 
 ```bash
-% phono3py --fc3 --fc2 --dim="2 2 2" -v --mesh="16 16 16" -c POSCAR-unitcell --nac --gruneisen
+% phono3py-load -v --mesh 16 16 16 --nac --gruneisen
 ```
 
 Band path mode:
 
 ```bash
-% phono3py --fc3 --fc2 --dim="2 2 2" -v -c POSCAR-unitcell --nac --gruneisen --band="0 0 0  0 0 1/2"
+% phono3py-load -v --nac --gruneisen --band "0 0 0  0 0 1/2"
 ```
 
 ## File I/O
@@ -1199,7 +1252,7 @@ Phonon frequencies, eigenvectors, and grid point addresses are stored in
 may be required depending on calculation setting.
 
 ```bash
-% phono3py --fc2 --dim="2 2 2" --pa="F" --mesh="11 11 11" -c POSCAR-unitcell --nac --write-phoonon
+% phono3py-load --mesh 11 11 11 --nac --write-phoonon
 ```
 
 Contents of `phonon-mxxx.hdf5` are watched by:
@@ -1248,7 +1301,7 @@ different CPU architectures. {ref}`--pa <pa_option>` and
 {ref}`--nac <nac_option>` may be required depending on calculation setting.
 
 ```bash
-% phono3py --fc2 --fc3 --dim="2 2  2" --pa="F" --mesh="11 11 11" -c POSCAR-unitcell --nac --read-phoonon --br
+% phono3py-load --mesh 11 11 11 --nac --read-phoonon --br
 ```
 
 (write_read_pp_option)=
@@ -1266,11 +1319,11 @@ calculation, in writing and reading, ph-ph interaction strength has to be stored
 in memory, so there is overhead in memory than usual RTA calculation.
 
 ```bash
-% phono3py --fc2 --fc3 --dim="2 2 2" --pa="F" --mesh="11 11 11" -c POSCAR-unitcell --nac --write-pp --br --gp=1
+% phono3py-load --mesh 11 11 11 --nac --write-pp --br --gp 1
 ```
 
 ```bash
-% phono3py --fc2 --dim="2 2 2" --pa="F" --mesh="11 11 11" -c POSCAR-unitcell --nac --read-pp --br --gp=1
+% phono3py-load --mesh 11 11 11 --nac --read-pp --br --gp 1
 ```
 
 (hdf5_compression_option)=

doc/crystal.md

@@ -78,10 +78,10 @@ so the -c crystal.o parameter is not needed.
 4) Calculate 3rd and 2nd order force constants in files `fc3.hdf5` and `fc2.hdf5`:
 
    ```bash
-   % phono3py --crystal --dim="2 2 2" --dim-fc2="4 4 4" --sym-fc
+   % phono3py --crystal --dim="2 2 2" --dim-fc2="4 4 4" --fc-symmetry
    ```
 
-   `--sym-fc` is used to symmetrize second- and third-order force constants.
+   `--fc-symmetry` is used to symmetrize second- and third-order force constants.
 
 5) Thermal conductivity calculation:
 

doc/cutoff-pair.md

@@ -1,17 +1,14 @@
 (command_cutoff_pair)=
 
 # Force constants calculation with cutoff pair-distance
-
+```{note}
-Since this calculation is a little bit tricky. It may be recommended to try
+Since usage of this calculation is complicated. It is recommended to try
 {ref}`random-displacements` with `--fc-calc-opt "cutoff = VAL"` before trying
 this option.
+```
 
 Here the detail of the command option {ref}`--cutoff-pair <cutoff_pair_option>`
-is explained.
+is explained. See also {ref}`a reference paper <cutoff_pair_reference>`.
-
-<!-- See also reference {cite}`Mizokami-PRB-2018`. -->
-
-See also {ref}`a reference paper <cutoff_pair_reference>`.
 
 ```{contents}
 :depth: 2
@@ -329,7 +326,7 @@ number_of_pairs_in_cutoff: 110
   300.0     119.501    119.501    119.501     -0.000     -0.000      0.000
   300.0     119.483    119.483    119.483     -0.000     -0.000      0.000
   300.0     119.481    119.481    119.481     -0.000     -0.000      0.000
-% for i in {2..10};do cp phono3py_disp.$i.yaml phono3py_disp.yaml; phono3py --sym-fc --mesh="11 11 11" --br|tee std.sym-$i.out;done
+% for i in {2..10};do cp phono3py_disp.$i.yaml phono3py_disp.yaml; phono3py --fc-symmetry --mesh="11 11 11" --br|tee std.sym-$i.out;done
 % for i in {2..10};do egrep '^\s+300' std.sym-$i.out;done
   300.0     124.650    124.650    124.650     -0.000     -0.000      0.000
   300.0     119.765    119.765    119.765     -0.000     -0.000      0.000

doc/index.md

@@ -20,28 +20,16 @@ the Wigner transport equation <LTC_options>`
 Papers that may introduce phono3py:
 
 - Theoretical background is summarized in this paper:
-  <http://dx.doi.org/10.1103/PhysRevB.91.094306> (arxiv
+  [PRB.91.094306](http://dx.doi.org/10.1103/PhysRevB.91.094306) (arxiv
-  <http://arxiv.org/abs/1501.00691>).
+  [1501.00691](http://arxiv.org/abs/1501.00691>)).
 - Introduction to phono3py application:
-  <https://journals.jps.jp/doi/10.7566/JPSJ.92.012001> (open access),
+  [JPSJ.92.012001](https://journals.jps.jp/doi/10.7566/JPSJ.92.012001) (open access),
   and phono3py inputs for 103 compounds found in Fig.17
   <https://github.com/atztogo/phonondb/blob/main/mdr/phono3py_103compounds_fd/README.md>
 - Implementation of phono3py:
-  <https://iopscience.iop.org/article/10.1088/1361-648X/acd831> (open access)
+  [JPCM.35.353001](https://iopscience.iop.org/article/10.1088/1361-648X/acd831)
+  (open access)
 
-A set of pre-calculated data for phono3py in
-
-```{image} Si-kaccum.png
-:width: 20%
-```
-
-```{image} Si-kaccum-MFP.png
-:width: 20%
-```
-
-```{image} Si-kdeplot.png
-:width: 22%
-```
 
 ## Documentation
 

doc/phono3py-load.md

@@ -8,31 +8,42 @@ module. The main aim of introducing this command is to provide uniform usage
 over many different force calculators. Once `phono3py_disp.yaml` is created, the
 following operations will be the same using this command.
 
-The following default behaviours are different from that of those of `phono3py`
+This is used almost in the same way as `phono3py` command, e.g., but there are
-command:
+some differences. The following default behaviours are different from that of
+those of `phono3py` command:
 
 1. `phono3py_xxx.yaml` type file is always necessary in either of two ways:
 
    - `phono3py_xxx.yaml` type file is given as the first argument of the
-     command.
+     command, e.g.,
-   - `phono3py_xxx.yaml` type file is put in the current directory with one of
+
-     the default filenames of `phono3py_params.yaml`, `phono3py_disp.yaml`,
+     ```bash
-     `phono3py.yaml`. The searching preference order is `phono3py_params.yaml` >
+     % phono3py-load phono3py_xxx.yaml --br --ts 300 --mesh 50
-     `phono3py_disp.yaml` > `phono3py.yaml`.
+     ```
+
+   - With first argument unspecified, `phono3py_disp.yaml` or `phono3py.yaml`
+     file is read if it is found in the current directory. If both found,
+     `phono3py_disp.yaml` is read. For example, having `phono3py_disp.yaml`
+     under the current directory,
+
+     ```bash
+     % phono3py-load --br --ts 300 --mesh 50
+     ```
 
 2. `-c` option (read crystal structure) does not exist.
 
-3. `-d` option (create displacements) does not exist.
+3. `-d` option (create displacements) does not exist. Please use `phono3py`
+   command.
 
-4. Use of command options is recommended, but phono3py configuration file can be
+4. Phono3py configuration file can be read through `--config` option. See
-   read through `--config` option.
+   {ref}`use_config_with_option`.
 
 5. If parameters for non-analytical term correction (NAC) are found, NAC is
    automatically enabled. This can be disabled by `--nonac` option.
 
 6. When force constants are calculated from displacements and forces dataset,
    force constants are automatically symmetrized. To disable this, `--no-sym-fc`
-   option is used.
+   option can be used.
 
 7. `-o` option works differently from `phono3py` command. This option requires
    one argument of string. The string is used as the output yaml filename that

doc/qe.md

@@ -67,10 +67,10 @@ only limited number of keywords that are shown in the phonopy web site
    `fc3.hdf5` and `fc2.hdf5` files are created by:
 
    ```bash
-   % phono3py --sym-fc
+   % phono3py --fc-symmetry
    ```
 
-   where `--sym-fc` symmetrizes fc3 and fc2.
+   where `--fc-symmetry` symmetrizes fc3 and fc2.
 
 5) Calculate lattice thermal conductivity, e.g., by:
 

doc/random-displacements.md

@@ -6,7 +6,7 @@ displacement-force dataset for computing force constants. This requires an
 external force constants calculator, e.g., symfc or ALM. Here, examples are
 presented with using symfc that can be installed via pip or conda easily.
 
-## Related setting tags
+## Related command options
 
 - {ref}`random_displacements_option` (`--rd`, `--random-seed`)
 - {ref}`fc_calculator_option` (`--fc-calc`)
@@ -81,6 +81,18 @@ If `phono3py_disp.yaml` is located in current directory, force constants are
 calculated from `FORCES_FC3` (and optionally `FORCES_FC2`) and
 `phono3py_disp.yaml` by
 
+```bash
+% phono3py-load --symfc -v
+```
+
+or
+
+```bash
+% phono3py-load phono3py_params.yaml --symfc -v
+```
+
+Similarly, it is performed by also using `phono3py` command,
+
 ```bash
 % phono3py --symfc -v
 ```
@@ -91,17 +103,6 @@ or with `phono3py_params.yaml`
 % phono3py -c phono3py_params.yaml --symfc -v
 ```
 
-Similarly, it is performed by also using `phono3py-load` command,
-
-```bash
-% phono3py-load --symfc -v
-```
-
-or
-
-```bash
-% phono3py-load phono3py_params.yaml --symfc -v
-```
 
 ## Cutoff pair-distance for fc3 calculation
 
@@ -113,7 +114,7 @@ introducing cutoff distance for pairs of atoms. It is performed by
 `--fc-calc-opt` option as
 
 ```bash
-% phono3py --symfc -v --fc-calc-opt "cutoff=8"
+% phono3py-load --symfc -v --fc-calc-opt "cutoff=8"
 ```
 
 The shortcut of `--fc-calc-opt "cutoff=8"` is `--cutoff-pair 8`.

doc/turbomole.md

@@ -69,7 +69,7 @@ so the `-c control` parameter is not needed.
 4) Calculate 3rd and 2nd order force constants in files `fc3.hdf5` and `fc2.hdf5`:
 
    ```bash
-   % phono3py --turbomole --dim="2 2 2" --dim-fc2="3 3 3" --sym-fc
+   % phono3py --turbomole --dim="2 2 2" --dim-fc2="3 3 3" --fc-symmetry
    ```
 
    `--sym-fc` is used to symmetrize second- and third-order force constants.

doc/vasp.md

@@ -61,10 +61,10 @@
 4. Create `fc2.hdf` and `fc3.hdf`
 
    ```bash
-   % phono3py --sym-fc
+   % phono3py --fc-symmetry
    ```
 
-   `--sym-fc` symmetrizes fc3 and fc2. `fc2.hdf5` and `fc3.hdf5`
+   `--fc-symmetry` symmetrizes fc3 and fc2. `fc2.hdf5` and `fc3.hdf5`
    are created from `FORCES_FC3` (and
    optionally `FORCES_FC2`) and `phono3py_disp.yaml`. This step is
    not mandatory, but you can avoid calculating fc2 and fc3 at every

doc/wigner-solution.md

@@ -38,7 +38,7 @@ As discussed in the references above, the term $\kappa_{\rm P}^{\alpha \beta}$ c
 To compute the Wigner conductivity with scattering in the RTA approximation, specify `--br` and `--wigner`. For `example/Wigner_La2Zr2O7`, the command is:
 
 ```bash
-phono3py --nac --cell POSCAR --fc2 --dim="2 2 2" --dim-fc2="4 4 4" --mesh="19 19 19" --tmin=300 --tmax=1000 --tstep=700 --sym-fc --isotope --br --wigner --read-gamma > tc_La2Zr2O7.out
+phono3py --nac --cell POSCAR --fc2 --dim="2 2 2" --dim-fc2="4 4 4" --mesh="19 19 19" --tmin=300 --tmax=1000 --tstep=700 --fc-symmetry --isotope --br --wigner --read-gamma > tc_La2Zr2O7.out
 ```
 The example above uses the `--read-gamma` option to read the phonon linewidths stored in the file  `kappa-m191919.hdf5`. The calculation of these linewidths is computationally expensive, more details are reported in the {ref}`paper on the Wigner formulation <citation_wigner_formulation>`, and in this example the linewidths are provided.
 To learn how to compute the linewidths, the reader is referred to the documentation of the `--write-gamma` option.

doc/workload-distribution.md

@@ -28,14 +28,14 @@ To avoid re-calculating fc3 and fc2, `fc3.hdf5` and `fc2.hdf5` are
 created on a single node:
 
 ```bash
-% phono3py --dim="2 2 2" --sym-fc -c POSCAR-unitcell
+% phono3py-load
 ```
 
 The indices of the irreducible grid-points neccesarry to specify
 `--ga` option are found by {ref}`--wgp option <wgp_option>`
 
 ```bash
-% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc3 --fc2 --br --wgp
+% phono3py-load --mesh 19 19 19 --br --wgp
 ```
 
 and they are stored in `ir_grid_points.yaml`.
@@ -51,7 +51,7 @@ computational demands into computer nodes, a set of the grid-point
 indices are chosen and executed as follows:
 
 ```bash
-% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc3 --fc2 --br --gp="0,1,2,3,4,5,6,7,8,9,20,21,22,23,24,25" --write-gamma
+% phono3py-load --mesh 19 19 19 --br --gp "0,1,2,3,4,5,6,7,8,9,20,21,22,23,24,25" --write-gamma
 ```
 
 Then many `kappa-m191919-gx.hdf5` files are generated. These file
@@ -63,7 +63,7 @@ indices, the RTA thermal conductivity is computed by another run in a
 short time from the stored data:
 
 ```bash
-% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc3 --fc2 --br --read-gamma
+% phono3py-load --mesh 19 19 19 --br --read-gamma
 ```
 
 ## A convenient script
@@ -96,7 +96,7 @@ with open("ir_grid_points.yaml") as f:
 Supposed that this script is saved as `divide_gps.py`,
 
 ```bash
-% phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --wgp
+% phono3py-load --mesh 19 19 19 --wgp
 ...
 % python divide_gps.py 20
 0,30,52,82,120,402,434,468,524,844,1206
@@ -138,5 +138,5 @@ with `job.sh` (here for grid-engine):
 #$ -e err-phono3py-num.log
 #$ -o std-phono3py-num.log
 
-phono3py --dim="2 2 2" --pa="F" -c POSCAR-unitcell --mesh="19 19 19" --fc3 --fc2 --br --gp="gps" --write-gamma
+phono3py-load --mesh 19 19 19 --br --gp "gps" --write-gamma
 ```

example/Si-CRYSTAL/README

@@ -23,7 +23,7 @@ for the CRYSTAL interface, so the -c crystal.o parameter is not needed
 
 4) Create force constant files fc2.hdf5 and fc3.hdf5:
 
-   phono3py --crystal --dim="2 2 2" --dim-fc2="4 4 4" --sym-fc
+   phono3py --crystal --dim="2 2 2" --dim-fc2="4 4 4" --fc-symmetry
 
 5) Thermal conductivity calculation:
 

phono3py/cui/phono3py_argparse.py

@@ -59,6 +59,7 @@ def get_parser(fc_symmetry=False, is_nac=False, load_phono3py_yaml=False):
         default=False,
         help=("Use ALM for generating 2nd and 3rd force constants " "in one fitting"),
     )
+    if not load_phono3py_yaml:
         parser.add_argument(
             "--amplitude",
             dest="displacement_distance",