Merge pull request #259 from phonopy/rd-doc

Better support of random displacements

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,25 @@ created from `FORCES_FC2` and `phono3py_disp.yaml` instead of `FORCES_FC3` and
 % phono3py --cfs --dim-fc2="x x x"
 ```
 
+### `--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 +269,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 +277,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 +296,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 +387,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,36 @@
+(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:
+
+```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.

example/NaCl-rd/README.md

@@ -0,0 +1,80 @@
+# 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 2 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 8.3 W/m-k.
+
+
+## How to use pypolymlp
+
+When supercell energies are included in `phono3py_params.yaml` like file, the
+polynomial machine learning potential (poly-MLP) by pypolymlp can be used to
+calculate fc3 by the following command:
+
+```bash
+% 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 `--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
+   `--rd 400` option. The default displacement distance is 0.001 Angstrom in
+   `--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 `--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
+
+```bash
+% phono3py-load phono3py_params_NaCl.yaml.xz --br --ts 300 --mesh 50
+```
+
+and the LTC value of around 8.2 W/m-k is obtained.
+
+## Generating phono3py_params.yaml from vasprun.xml's
+
+`phono3py_params.yaml` is generated from
+
+```bash
+% phono3py phono3py_disp.yaml --cf3 NaCl-vasprun/vasprun-{00001..00100}.xml --cf2 NaCl-vasprun/vasprun-ph0000{1,2}.xml --sp
+```
+
+This command reads electronic energies of supercells from `vasprun.xml`s and
+writes them into `phono3py_params.yaml`, too. Here, `phono3py_disp.yaml` is not
+included in this example, but `phono3py_params_NaCl.yaml.xz` can be used to run
+this example since corresponding information of displacements is included in
+this file, too.

phono3py/cui/create_supercells.py

@@ -35,8 +35,10 @@
 # POSSIBILITY OF SUCH DAMAGE.
 
 from phonopy.interface.calculator import write_supercells_with_displacements
+from phonopy.structure.cells import print_cell
 
 from phono3py import Phono3py
+from phono3py.cui.show_log import print_supercell_matrix
 from phono3py.interface.calculator import (
     get_additional_info_to_write_fc2_supercells,
     get_additional_info_to_write_supercells,
@@ -92,6 +94,16 @@ def create_phono3py_supercells(
     if log_level:
         print("")
         print('Unit cell was read from "%s".' % optional_structure_info[0])
+        print("-" * 32 + " unit cell " + "-" * 33)  # 32 + 11 + 33 = 76
+        print_cell(phono3py.unitcell)
+        print("-" * 76)
+        print_supercell_matrix(
+            phono3py.supercell_matrix, phono3py.phonon_supercell_matrix
+        )
+        if phono3py.primitive_matrix is not None:
+            print("Primitive matrix:")
+            for v in phono3py.primitive_matrix:
+                print("  %s" % v)
         print("Displacement distance: %s" % distance)
 
     ids = []
@@ -125,6 +137,7 @@ def create_phono3py_supercells(
             print("Number of displacement supercell files created: %d" % num_disp_files)
 
     if phono3py.phonon_supercell_matrix is not None:
+        num_disps = len(phono3py.phonon_supercells_with_displacements)
         additional_info = get_additional_info_to_write_fc2_supercells(
             interface_mode, phono3py.phonon_supercell_matrix
         )

phono3py/cui/load.py

@@ -588,9 +588,9 @@ def _get_dataset_phonon_dataset_or_fc2(
         )
     elif (
         forces_fc2_filename is not None or pathlib.Path("FORCES_FC2").exists()
-    ) and ph3py.phonon_supercell_matrix:
+    ) and ph3py.phonon_supercell_matrix is not None:
         if forces_fc2_filename is None:
-            force_filename = forces_fc2_filename
+            force_filename = "FORCES_FC2"
         else:
             force_filename = forces_fc2_filename
         phonon_dataset = _get_dataset_for_fc2(