Documentation for random displacement

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
@@ -250,7 +250,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 +258,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 +277,43 @@ very accurate.
 The default value depends on calculator. See
 {ref}`default_displacement_distance_for_calculator`.
 
+(fc_calculator_options_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-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 +368,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/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,27 @@
+(random-displacements)=
+# Randan displacements
+
+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:
+
+```
+% 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.

example/NaCl-rd/README.md

@@ -0,0 +1,66 @@
+# Example of using random directional displacements
+
+## How to use symfc
+
+This example utilizes an NaCl calculation result from A. Togo and A. Seko, J.
+Chem. Phys. 160, 211001 (2024). Supercells of 2x2x2 and 4x4x4 conventional unit
+cells are chosen for the third-order force constants (fc3) and second-order
+force constants (fc2), respectively. Displacement-force datasets consisting of
+100 supercells for fc3 and 4 supercells for fc2 are extracted and stored in
+`phono3py_params_NaCl.yaml.xz`. Random directional displacements of a constant
+0.03 Angstrom are used.
+
+To calculate force constants, an external force constants calculator is
+necessary. Here, the symfc tool (available at https://github.com/symfc/symfc) is
+used, which can be easily installed via pip or conda.
+
+The `fc3.hdf5` and `fc2.hdf5` are computed using the command:
+
+```
+% phono3py-load phono3py_params_NaCl.yaml.xz --symfc -v
+```
+
+Lattice thermal conductivity (LTC) is calculated with the following command:
+
+```
+% phono3py-load phono3py_params_NaCl.yaml.xz --br --ts 300 --mesh 50
+```
+
+By this, LTC is obtained around 7.8 W/m-k.
+
+
+## How to use pypolymlp
+
+The polynomial machine learning potential (poly-MLP) by pypolymlp can be used to
+calculate fc3 by the following command:
+
+```
+% phono3py-load phono3py_params_NaCl.yaml.xz --pypolymlp --symfc --rd 400 -v
+```
+
+the procedure below is performed:
+
+1. Poly-MLPs are computed from the displacement-force dataset for fc3. This is
+   activated by the `--pypolymlp` option.
+2. 800=400+400 supercells for random directional displacements are generated,
+   where 400+400 means 400 supercells with random displacements (u) and 400
+   supercells with opposite displacement vectors (-u). This is activated by the
+   `--rd 400` option. The default displacement distance is 0.001 Angstrom in the
+   `--pypolymlp` mode. Since random displacements are generated `--symfc` has to
+   be specified for fc3. In this example, random displacements are used for fc2,
+   too, `--symfc` is applied to both of fc3 and fc2. Without the `--rd` option,
+   systematic displacements are generated, for which the option `--fc-calc "symfc|"`
+   has to be specified instead of `--symfc` (equivalent to `--fc-calc "symfc|symfc")`).
+3. Forces on atoms in these 800 supercells are calculated using poly-MLP.
+4. Force constants are calculated.
+
+
+The `fc3.hdf5` and `fc2.hdf5` are obtained. Using these force constants, LTC is
+calculated by
+
+```
+% phono3py-load phono3py_params_NaCl.yaml.xz --br --ts 300 --mesh 50
+```
+
+and the LTC value of around 7.8 W/m-k is obtained. This LTC value is equivalent
+to above, but of course, it can be different.