diff --git a/doc/command-options.md b/doc/command-options.md index 9851d73e..10331d46 100644 --- a/doc/command-options.md +++ b/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,8 +258,8 @@ 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 @@ -268,6 +267,7 @@ Random directional displacements are generated for fc3 and fc2 supercells by 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 diff --git a/doc/index.md b/doc/index.md index 961ad249..1e077455 100644 --- a/doc/index.md +++ b/doc/index.md @@ -58,6 +58,7 @@ auxiliary-tools direct-solution wigner-solution workload-distribution +random-displacements cutoff-pair external-tools phono3py-api diff --git a/doc/random-displacements.md b/doc/random-displacements.md new file mode 100644 index 00000000..a1582def --- /dev/null +++ b/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. diff --git a/example/NaCl-rd/README.md b/example/NaCl-rd/README.md new file mode 100644 index 00000000..debebe12 --- /dev/null +++ b/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. diff --git a/example/NaCl-rd/phono3py_params_NaCl.yaml.xz b/example/NaCl-rd/phono3py_params_NaCl.yaml.xz new file mode 100644 index 00000000..02e8869f Binary files /dev/null and b/example/NaCl-rd/phono3py_params_NaCl.yaml.xz differ