Merge branch 'develop' into publish-gh-pages

.pre-commit-config.yaml

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

doc/changelog.md

@@ -2,6 +2,14 @@
 
 # Change Log
 
+## Jul-22-2024: Version 3.3.3
+
+- Provide functionality by `--cf3` and `--cf2` command options to create force
+  constants from displacement-force dataset of random displacements when
+  an external force constants calculator is specified.
+- New command line options `--rd`, `--rd-fc2`, `--fc-calc`, `--fc-calc-opt` and
+  `--sp` to support random displacements.
+
 ## Jul-22-2024: Version 3.3.2
 
 - Minor fix of `phono3py.load` function for reading displacements from

doc/command-options.md

@@ -27,13 +27,13 @@ CELL_FILENAME = POSCAR-unitcell
 where the setting tag names are case insensitive. This is run by
 
 ```bash
-% phono3py setting.conf [comannd options]
+% phono3py setting.conf [command options]
 ```
 
 or
 
 ```bash
-% phono3py [comannd options] -- setting.conf
+% phono3py [command options] -- setting.conf
 ```
 
 ```{contents}
@@ -48,7 +48,7 @@ or
 This specifies input unit cell filename.
 
 ```bash
-% phono3py -c POSCAR-unitcell ... (many options)
+% phono3py -c POSCAR-unitcell ... (options)
 ```
 
 ## Calculator interface
@@ -174,6 +174,27 @@ created from `FORCES_FC2` and `phono3py_disp.yaml` instead of `FORCES_FC3` and
 % phono3py --cfs --dim-fc2="x x x"
 ```
 
+(sp_option)=
+
+### `--sp` or `--save-params`
+
+Instead of `FORCES_FC3`, `phono3py_params.yaml` is generated. This option must
+be used with `--cf3`, and optionally with `--cf2`. If the force calculator
+supports reading energy of supercell, those are written into
+`phono3y_params.yaml`. These energies are necessary for using `--pypolymlp`
+option.
+
+```bash
+% phono3py --cf3 disp-{00001..00755}/vasprun.xml --sp
+```
+
+When using with `--cf2`, `--cf3` has to be specified simultaneously as below,
+
+```bash
+% phono3py --cf3 disp-{00001..00755}/vasprun.xml --cf2 disp_fc2-{00001..00002}/vasprun.xml --sp
+```
+
+
 ## Supercell, primitive cell, masses, magnetic moments
 
 (dim_option)=
@@ -250,7 +271,6 @@ web page](https://phonopy.github.io/phonopy/setting-tags.html#magmom).
 ## Displacement creation
 
 (create_displacements_option)=
-
 ### `-d` (`CREATE_DISPLACEMENTS = .TRUE.`)
 
 Supercell with displacements are created. Using with `--amplitude` option,
@@ -259,15 +279,16 @@ 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.
 
-(amplitude_option)=
 
+(random_displacements_option)=
 ### `--rd` (`RANDOM_DISPLACEMENTS`), `--rd-fc2` (`RANDOM_DISPLACEMENTS_FC2`) and `--random-seed` (`RANDOM_SEED`)
 
 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).
 
+(amplitude_option)=
 ### `--amplitude` (`DISPLACEMENT_DISTANCE`)
 
 Atomic displacement distance is specified. This value may be increased for the
@@ -277,6 +298,44 @@ very accurate.
 The default value depends on calculator. See
 {ref}`default_displacement_distance_for_calculator`.
 
+(fc_calculator_option)=
+### `--fc-calc`, `--fc-calculator` (`FC_CALCULATOR`)
+
+Choice of force constants calculator.
+
+```
+% phono3py --fc-calc symfc ...
+```
+
+To use different force constants calculators for fc2 and fc3
+```
+% phono3py --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
+the option `-d`.
+
+(fc_calculator_options_option)=
+### `--fc-calc-opt`, `--fc-calculator-options` (`FC_CALCULATOR_OPTIONS`)
+
+Special options for force constants calculators.
+
+```
+% phono3py --fc-calc-opt "cutoff=8" ...
+```
+
+Similarly to `--fc-calc`, `|` can be used to separated those for fc2 and fc3.
+
+#### Options for symfc
+
+* cutoff : cutoff pair distance beyond that third-order force constants are zero
+  (fc3 only).
+* use_mkl : sparse_dot_mkl is employed when it is available.
+
+### `--symfc` and `--alm`
+
+These are shortcuts of `--fc-calc symfc` and `--fc-calc alm`, respectively.
+
 ## Force constants
 
 (compact_fc_option)=
@@ -331,14 +390,16 @@ supercell size and the second choice is using `--cutoff-pair` option.
 
 ### `--cutoff-pair` or `--cutoff-pair-distance` (`CUTOFF_PAIR_DISTANCE`)
 
-This option is only used together with `-d` option.
+This option works differently for the `-d` and `--rd` options.
 
-A cutoff pair-distance in a supercell is used to reduce the number of necessary
-supercells with displacements to obtain third order force constants. As the
-drawback, a certain number of third-order-force-constants elements are abandoned
-or computed with less numerical accuracy. More details are found at
+For `-d`, A cutoff pair-distance in a supercell is used to reduce the number of
+necessary supercells with displacements to obtain third order force constants.
+As the drawback, a certain number of third-order-force-constants elements are
+abandoned or computed with less numerical accuracy. More details are found at
 {ref}`command_cutoff_pair`.
 
+For `--rd`, `--cutoff-pair VAL` is equivalent to `--fc-calc-opt "cutoff=VAL"`.
+
 ### `--alm`
 
 This invokes ALM as the force constants calculator for fc2 and fc3. See the

doc/conf.py

@@ -60,7 +60,7 @@
 # The short X.Y version.
 version = "3.3"
 # The full version, including alpha/beta/rc tags.
-release = "3.3.2"
+release = "3.3.3"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/cutoff-pair.md

@@ -2,7 +2,11 @@
 
 # Force constants calculation with cutoff pair-distance
 
-Here the detail of the command option {ref}`--cutoff_pair <cutoff_pair_option>`
+Since this calculation is a little bit tricky. It may be 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.
 
 <!-- See also reference {cite}`Mizokami-PRB-2018`. -->

doc/index.md

@@ -58,6 +58,7 @@ auxiliary-tools
 direct-solution
 wigner-solution
 workload-distribution
+random-displacements
 cutoff-pair
 external-tools
 phono3py-api

doc/random-displacements.md

@@ -0,0 +1,125 @@
+(random-displacements)=
+# Force constants calculation with randan displacements of atoms
+
+Random displacements and corresponding forces in supercells can be employed as a
+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
+
+- {ref}`random_displacements_option` (`--rd`, `--random-seed`)
+- {ref}`fc_calculator_option` (`--fc-calc`)
+- {ref}`fc_calculator_options_option` (`--fc-calc-opt`)
+
+## Generation of random directional displacements
+
+The option `--rd NUM` is used instead of `-d` in generating displacements as follows:
+
+```bash
+% phono3py --rd 100 --dim 2 2 2 --pa auto -c POSCAR-unitcell
+```
+
+`NUM` means the number of supercells with random directional displacements. This
+must be specified, and the initial guess may be from around the number of
+supecells generated for the systematic displacements by `-d`. In the case of the
+`NaCl-rd` example, 146 supercells are generated with `-d`, so similar
+number `--rd 100` was chosen here.
+
+If random directional displacements for fc2 are expected, `--rd-fc2` and
+`--dim-fc2` have to be specified:
+
+```bash
+% phono3py --rd 100 --dim 2 2 2 --rd-fc2 2 --dim-fc2 4 4 4 --pa auto -c POSCAR-unitcell
+```
+
+where `--dim` is necessary but `--rd` is not.
+
+## Create `FORCES_FC3` and `FORCES_FC2`
+
+`FORCES_FC3` and optionally `FORCES_FC2`, which contains forces corresponding to
+displacements, can be created by
+
+```bash
+% phono3py --cf3 vasprun_xmls/vasprun-00{001..100}.xml
+```
+
+Here it is assumed that the forces were calculated by VASP, and the output files
+(`vasprun.xml`) are stored in `vasprun_xmls` directory after renaming. When
+running this command, `phono3py_disp.yaml` is automatically read. For the
+different file name, e.g. `phono3py_disp_rd.yaml`, it is specified with `-c`
+option:
+
+```bash
+% phono3py -c phono3py_disp_rd.yaml --cf3 vasprun_xmls/vasprun-00{001..100}.xml
+```
+
+`FORCES_FC2` is created similarly, e.g., from the VASP output stored as
+`vasprun_xmls/vasprun-ph000{1,2}.xml`,
+
+```bash
+% phono3py --cf2 vasprun_xmls/vasprun-ph000{1,2}.xml
+```
+
+## Create `phono3py_params.yaml`
+
+Instead of creating `FORCES_FC3` and `FORCES_FC2`, more convenient data file to
+store displacement-force dataset is created by `--sp` option:
+
+```bash
+% phono3py --cf3 vasprun_xmls/vasprun-00{001..100}.xml --cf2 vasprun_xmls/vasprun-ph0000{1,2}.xml --sp
+```
+
+The advantage to employ `phono3py_params.yaml` is that this file can contain all
+the information required to run phono3py such as crystal structure, supercell
+information, displacements, forces, and parameters for non-analytical term
+correction. This file is immediately usable for `phono3py-load` command ({ref}`phono3py_load_command`).
+
+## Calculation of force constants
+
+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 --symfc -v
+```
+
+or with `phono3py_params.yaml`
+
+```bash
+% 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
+
+The number of supercells required for calculating fc3 depends on crystal
+structure, crystal symmetry, and supercell size. For larger supercells, the
+number can be very large. In addition, the required computational time and
+memory space can also become large. In such case, it may be good to consider
+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"
+```
+
+The shortcut of `--fc-calc-opt "cutoff=8"` is `--cutoff-pair 8`.
+
+The convergence of fc3 has to be checked. With the same input of
+displacement-force dataset, calculated force constants gradually converge by
+increasing cutoff pair-distance. The convergence may be checked by lattice
+thermal conductivity, but it may depend on quantity that is expected to be
+calculated.