Update document for workload distribution

doc/command-options.rst

@@ -800,3 +800,39 @@ Band path mode::
    % phono3py --fc3 --fc2 --dim="2 2 2" -v \
      -c POSCAR-unitcell --nac --gruneisen --band="0 0 0  0 0 1/2"
 
+Input and output file names
+----------------------------
+
+.. _output_filename_option:
+
+``-o``: Arranging output file names
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using this option, output file names are slightly modified. For example,
+specifying ``-o iso``, a file name ``kappa-m191919.hdf5`` is changed
+to ``kappa-m191919.iso.hdf5``.
+
+This rule is applied to
+
+- ``fc3.hdf5``
+- ``fc2.hdf5``
+- ``kappa-xxx.hdf5``
+- ``disp_fc3.yaml``
+- ``disp_fc2.yaml``
+
+.. _input_filename_option:
+
+``-i``: Arranging input file names
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using this option, input file names are slightly modified. For example,
+specifying ``-i iso --fc3``, a file name ``fc3.iso.hdf5`` is read
+instead of ``fc3.hdf5``.
+
+This rule is applied to
+
+- ``fc3.hdf5``
+- ``fc2.hdf5``
+- ``kappa-xxx.hdf5``
+- ``disp_fc3.yaml``
+- ``disp_fc2.yaml``

doc/workload-distribution.rst

@@ -5,16 +5,20 @@ Workload distribution
 
 Workload of thermal conductivity calculation can be distributed into
 computer nodes. The distribution over q-point grid points (:ref:`--gp
-option <gp_option>`) and phonon bands (:ref:`--bi option <bi_option>`)
-are supported. Distribution over bands has some overhead in
-calculation of Fourier transformation of force constants. Below
-distribution over only grid points is explained. For each computer
-node, selected irreducible grid points needed for completing thermal
-conductivity are calculated. The resulting data for each grid point are
+option <gp_option>`), over phonon bands (:ref:`--bi option
+<bi_option>`), and over both of them are supported. Unless necessary,
+the distribution over bands is not recommended since it has some
+amount of overhead in the part of Fourier transformation of force
+constants. Therefore the distribution over grid-points is explained
+below. However since the distribution over bands works quite similarly as
+that over q-points, the usage can be easily guessed.
+
+On each computer node, pieces of lattice thermal conductivity
+calculation are executed. The resulting data for each grid point are
 stored in its ``kappa-mxxx-gx.hdf5`` file on each node by setting
 :ref:`--write_gamma option <write_gamma_option>`. Once all data are
 obtained, those data are collected by :ref:`--read_gamma option
-<read_gamma_option>`.
+<read_gamma_option>` and the lattice thermal conductivity is obtained.
 
 .. contents::
    :depth: 2
@@ -30,8 +34,8 @@ created on a single node::
 
    % phono3py --dim="2 2 2" --sym_fc3r --sym_fc2 --tsym -c POSCAR-unitcell
 
-The indices of the irreducible grid points neccesarry for ``--ga``
-option are found by :ref:`--wgp option <wgp_option>`
+The indices of the irreducible grid-points neccesarry to specify
+``--ga`` option are found by :ref:`--wgp option <wgp_option>`
 
 ::
 
@@ -44,12 +48,21 @@ and they are stored in ``ir_grid_points.yaml``.
    % egrep '^- grid_point:' ir_grid_points.yaml|awk '{printf("%d,",$3)}'
    0,1,2,3,4,5,6,7,8,9,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,60,61,62,63,64,65,66,67,68,69,70,71,72,73,80,81,82,83,84,85,86,87,88,89,90,91,100,101,102,103,104,105,106,107,108,109,120,121,122,123,124,125,126,127,140,141,142,143,144,145,160,161,162,163,180,181,402,403,404,405,406,407,408,409,422,423,424,425,426,427,428,429,430,431,432,433,434,435,442,443,444,445,446,447,448,449,450,451,452,453,462,463,464,465,466,467,468,469,470,471,482,483,484,485,486,487,488,489,502,503,504,505,506,507,522,523,524,525,542,543,804,805,806,807,808,809,824,825,826,827,828,829,830,831,832,833,844,845,846,847,848,849,850,851,864,865,866,867,868,869,884,885,886,887,904,905,1206,1207,1208,1209,1226,1227,1228,1229,1230,1231,1246,1247,1248,1249,1266,1267,1608,1609,1628,1629,
 
-Some of all the indices are specified and executed as follows::
+The calculated data on all the grid points shown above as indices are
+necessary to obtain lattice thermal conductivity. To distribute
+computational demands into computer nodes, a set of the grid-point
+indices are chosen and executed as follows::
 
    % phono3py --dim="2 2 2" --pa="0 1/2 1/2 1/2 0 1/2 1/2 1/2 0" -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
 
-After finishing calculations on all nodes, the RTA thermal
-conductivity is computed in a short time from the stored data by
+Then many ``kappa-m191919-gx.hdf5`` files are generated. These file
+names should not be altered because in reading the data by phono3py,
+those file names are supposed to be so, though there is a little
+freedom to arrange those file names, for which see :ref:`-o
+<output_filename_option>` and :ref:`-i <input_filename_option>`
+options. After completing calculations for all irreducible grid-point
+indices, the RTA thermal conductivity is computed by another run in a
+short time from the stored data:
 
 ::
 
@@ -58,9 +71,9 @@ conductivity is computed in a short time from the stored data by
 A convenient script
 --------------------
 
-The following short script may be used to splitting all irreducible
-grid point indices into some number (first argument) of sets of grid
-point indices for workload distribution.
+The following short script may be useful to splitting all irreducible
+grid-point indices into of reasonable number of sets of grid-point
+indices for workload distribution.
 
 .. code-block:: python
 
@@ -87,6 +100,8 @@ Supposed that this script is saved as ``divide_gps.py``,
 
 ::
 
+   % phono3py --dim="2 2 2" --pa="0 1/2 1/2 1/2 0 1/2 1/2 1/2 0" -c POSCAR-unitcell --mesh="19 19 19" --wgp
+   ...
    % python divide_gps.py 20
    0,30,52,82,120,402,434,468,524,844,1206
    1,31,53,83,121,403,435,469,525,845,1207