Fixed typos in the document. Added some options.

docs/source/download.rst

@@ -1,11 +1,14 @@
 Download
 ========
 
+.. highlight:: bash
+
+
 You can download the latest and previous versions of ALAMODE at http://sourceforge.net/projects/alamode .
 
 You can also download the package from the git repository as
 
     $ git clone http://github.com/ttadano/alamode.git
 
-    
+If you choose the GitHub version, please use the 'master' branch.
 

docs/source/formalism/formalism_anphon.rst

@@ -199,6 +199,21 @@ where :math:`m` is the number of phonon branches and
 
     P_{3} = \frac{1}{N_{q}}\sum_{\boldsymbol{q}} P_{3}(\boldsymbol{q}j).
 
+When ``SPS = 2``, the three-phonon scattering phase space with the occupation factor :math:`W_{3}^{(\pm)}` will be calculated and saved to the file ``PREFIX``.sps_Bose. :math:`W_{3}^{(\pm)}` is defined as
+
+.. math::
+
+    W_{3}^{(\pm)}(\boldsymbol{q}j) = \frac{1}{N_{q}}{\sum_{\boldsymbol{q}_{1},\boldsymbol{q}_{2}, j_{1}, j_{2}}}
+    \left\{
+      \begin{array}{c}
+      n_{2} - n_{1} \\
+      n_{1} + n_{2} + 1
+      \end{array}
+    \right\}
+    \delta(\omega_{\boldsymbol{q}j}\pm\omega_{\boldsymbol{q}_{1}j_{1}}-\omega_{\boldsymbol{q}_{2}j_{2}})\delta_{\boldsymbol{q}\pm\boldsymbol{q}_{1},\boldsymbol{q}_{2}+\boldsymbol{G}}.
+
+Here, :math:`n_{1}=n(\omega_{\boldsymbol{q}_{1}j_{1}})` and :math:`n_{2}=n(\omega_{\boldsymbol{q}_{2}j_{2}})` where :math:`n(\omega) = \frac{1}{e^{\hbar\omega/k_B T}-1}` is the Bose-Einstein distribution function. Since :math:`n(\omega)` is temperature dependent, :math:`W_{3}^{(\pm)}` is also temperature dependent. The file ``PREFIX``.sps_Bose contains :math:`W_{3}^{(\pm)}` for all phonon modes at various temperatures specified with ``TMIN``, ``TMAX``, and ``DT`` tags.
+
 Gr\ |umulaut_u|\ neisen parameter
 ---------------------------------
 

docs/source/index.rst

@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Project ALAMODE
-===============
+ALAMODE
+========
 
 
 Users Guide

docs/source/input/inputalm.rst

@@ -25,7 +25,7 @@ For example, &general entry field of program *alm* should be given like
     MODE = fitting
   /
 
-Multiple entries can be put in a single line. Also, any characters put on the right of sharp (“#”) character will be neglected. Therefore, the above example is equivalent to the following::
+Multiple entries can be put in a single line. Also, characters put on the right of sharp (“#”) will be neglected. Therefore, the above example is equivalent to the following::
   
   &general
     PREFIX = prefix; MODE = fitting  # Comment line
@@ -196,7 +196,7 @@ which means that all possible harmonic terms between Si-Si atoms will be include
 
   Setting 'None' for anharmonic terms can greatly increase the number of parameters and thereby increase the computational cost.
 
-When there are more than two atomic elements, please specify the cutoff radii between every possible pairs of atomic elements. In the case of MgO (``NKD = 2``), the cutoff entry should be like
+When there are more than two atomic elements, please specify the cutoff radii between every possible pair of atomic elements. In the case of MgO (``NKD = 2``), the cutoff entry should be like
 ::
  
  &cutoff
@@ -325,7 +325,7 @@ This field is necessary when ``MODE = fitting``.
 
  :Default: None
  :Type: String
- :Description: When ``FC2XML``-tag is given, harmonic force constants will be fixed to the values stored in the ``FC2XML`` file. This may be useful for optimizing cubic and higher-order terms without changing the harmonic terms. Please make sure that the number of harmonic terms in the new computational condition be the same as that in the ``FC2XML`` file.
+ :Description: When ``FC2XML``-tag is given, harmonic force constants will be fixed to the values stored in the ``FC2XML`` file. This may be useful for optimizing cubic and higher-order terms without changing the harmonic terms. Please make sure that the number of harmonic terms in the new computational condition is the same as that in the ``FC2XML`` file.
 
 ````
 

docs/source/input/inputanphon.rst

@@ -80,7 +80,7 @@ List of input variables
 
  :Default: None
  :Type: String
- :Description: When ``FC2XML`` is given, the harmonic force constants in this file will be used for calculating dynamical matricies. It is possible to use different size of supercell for harmonic and anharmonic terms, which are specified by ``FC2XML`` and ``FCSXML`` respectively.
+ :Description: When ``FC2XML`` is given, the harmonic force constants in this file will be used for calculating dynamical matrices. It is possible to use different size of supercell for harmonic and anharmonic terms, which are specified by ``FC2XML`` and ``FCSXML`` respectively.
 
 ````
 
@@ -359,7 +359,7 @@ The first entry **KPMODE** specifies the types of calculation which is followed
 
  :Default: 0
  :Type: Integer
- :Description: This flag is available only when ``KPMODE = phonons`` and *KPMODE* = 2.
+ :Description: This flag is available only when ``MODE = phonons`` and *KPMODE* = 2.
 
 ````
 
@@ -372,7 +372,7 @@ The first entry **KPMODE** specifies the types of calculation which is followed
 
  :Default: 0
  :Type: Integer
- :Description: This flag is available only when ``KPMODE = phonons`` and *KPMODE* = 2.
+ :Description: This flag is available only when ``MODE = phonons`` and *KPMODE* = 2.
 
 ````
 
@@ -385,24 +385,27 @@ The first entry **KPMODE** specifies the types of calculation which is followed
 
  :Default: 0
  :Type: Integer
- :Description: This flag is available only when ``KPMODE = phonons`` and *KPMODE* = 2.
+ :Description: This flag is available only when ``MODE = phonons`` and *KPMODE* = 2.
 
  .. Note::
 
   Calculation of two-phonon DOS is computationally expensive.
 
 ````
 
-* SPS-tag = 0 | 1
+* SPS-tag = 0 | 1 | 2
 
  === ====================================================================================
   0   Do not compute scattering phase space
-  1   Total and mode-decomposed scattering phase space will be stored in ``PREFIX``.sps
+  1   Total and mode-decomposed scattering phase space involving three-phonon processes 
+      will be stored in ``PREFIX``.sps
+  2   Three-phonon scattering phase space with the Bose factor will be stored 
+      in ``PREFIX``.sps_Bose
  === ====================================================================================
 
  :Default: 0
  :Type: Integer
- :Description: This flag is available only when ``KPMODE = phonons`` and *KPMODE* = 2.
+ :Description: This flag is available only when ``MODE = phonons`` and *KPMODE* = 2.
 
 
 ````
@@ -417,7 +420,7 @@ The first entry **KPMODE** specifies the types of calculation which is followed
 
  :Default: 0
  :Type: Integer
- :Description: This flag is available when ``KPMODE = phonons``.
+ :Description: This flag is available when ``MODE = phonons``.
 
 
 ````

docs/source/install.rst

@@ -7,7 +7,7 @@ Requirement
 Mandatory requirements
 ~~~~~~~~~~~~~~~~~~~~~~
 
-* C++ compiler (Intel compiler is highly recommended.)
+* C++ compiler (Intel compiler is recommended.)
 * LAPACK library
 * MPI library (Either OpenMPI, MPICH2, or IntelMPI)
 * `Boost C++ library <http://www.boost.org>`_
@@ -50,13 +50,13 @@ How to install
 
   This will create a directory alamode-x.y.z containing the following sub-directories:
   
-  * alm/ : Source files for alm (force constant calculation)
-  * anphon/ : Source files for anphon (phonon calculation)
+  * alm/      : Source files for alm (force constant calculation)
+  * anphon/   : Source files for anphon (phonon calculation)
   * external/ : Third-party include files
-  * include/ : Commonly-used include files
-  * tools/ : Small auxiliary programs and scripts
-  * docs/ : Source files for making documents
-  * example/ : Example files
+  * include/  : Commonly-used include files
+  * tools/    : Small auxiliary programs and scripts
+  * docs/     : Source files for making documents
+  * example/  : Example files
 
 3. Edit the Makefiles
 

docs/source/intro.rst

@@ -13,38 +13,53 @@
 About
 =====
 
-What is ALAMODE ?
+What is ALAMODE?
 -----------------
 
-**ALAMODE** stands for **A**\ nharmonic **LA**\ ttice **MODE**\ l, 
-which is designed for estimating harmonic and anharmonic properties of lattice vibrations (phonons) in solids. 
-The code is written in C++ and MPI/OpenMP parallelization is implemented.
+**ALAMODE** is an open source software designed for analyzing lattice anharmonicity and lattice thermal conductivity of solids. By using an external DFT package such as VASP and Quantum ESPRESSO, you can extract harmonic and anharmonic force constants straightforwardly with ALAMODE. Using the calculated anharmonic force constants, you can also estimate lattice thermal conductivity, phonon linewidth, and other anharmonic phonon properties from first principles.
 
 Features
 --------
 
-ALAMODE consists of two main programs **alm** and **anphon** written in C++, and some subsidiary Python scripts.
-
-The program *alm* can estimate harmonic and anharmonic interatomic force constants (IFCs) based on the supercell approach.
-The program *anphon* can compute phonon properties using the estimated IFCs. Currently, it can compute the following quantities:
-
-* Phonon dispersion, Phonon DOS, Atom-projected phonon DOS
-* Thermodynamic functions (vibrational entropy, free energy, internal energy)
-* Mean square displacement
-* Heat capacity at constant volume
+General
+^^^^^^^
+
+* Extraction of harmonic and anharmonic force constants based on the supercell approach
+* Applicable to any crystal structures and low-dimensional systems
+* Accurate treatment of translational and rotational invariance
+* Interface to VASP, Quantum-ESPRESSO, and xTAPP codes
+* Mainly written in C++, parallelized with MPI+OpenMP
+
+Harmonic properties
+^^^^^^^^^^^^^^^^^^^
+* Phonon dispersion
+* Phonon DOS, atom-projected phonon DOS
+* Two-phonon DOS
+* Vibrational thermodynamic functions (heat capacity, entropy, free energy)
+* Mean-square displacement
+* Animation and visualization of phonon modes (requires VMD or XCrysDen)
+* 3-phonon scattering phase space
+* Phonon-isotope scattering rate
+* Participation ratio for analyzing localization of phonon modes
+
+Anharmonic properties
+^^^^^^^^^^^^^^^^^^^^^
+
+.. |umulaut_u|    unicode:: U+00FC
+
+* Gr\ |umulaut_u|\ neisen parameter via cubic force constants
+* Lattice thermal conductivity by BTE-RTA
+* Cumulative thermal conductivity
 * Phonon linewidth due to 3-phonon interactions
-* Phonon frequency shift
-* Phonon self-energy due to phonon-isotope scatterings
-* Lattice thermal conductivity
-
-In addition, a python script may be used to estimate the cumulative thermal conductivity as a function of phonon mean-free-path.
+* Phonon frequency shift due to 3- and 4-phonon interactions
+* Temperature-dependent effective potential method
 
 
 Links
 -----
 
-* Download page  : http://sourceforge.net/projects/alamode
-* Documentation  : http://alamode.readthedocs.org
+* Download page  : http://sourceforge.net/projects/alamode 
+* Documentation  : http://alamode.readthedocs.org (this page)
 * Git repository : http://github.com/ttadano/alamode
 
 
@@ -53,11 +68,16 @@ License
 
 .. |copy|   unicode:: U+000A9 
 
-Copyright |copy| 2014 Terumasa Tadano. See the LICENSE.txt file for license
-rights and limitations (MIT). 
+Copyright |copy| 2014, 2015, 2016 Terumasa Tadano
+
+This software is distributed under the MIT license.
+See the LICENSE.txt file for license rights and limitations. 
 
 
-If you used ALAMODE, please cite the following article:
+How to Cite ALAMODE
+-------------------
+
+Please cite the following article when you use ALAMODE:
 
   T\. Tadano, Y. Gohda, and S. Tsuneyuki, J. Phys.: Condens. Matter **26**\ , 225402 (2014) [Link_].
 
@@ -72,13 +92,15 @@ This project was supported by a Grant-in-Aid for Scientific Research on Innovati
 (http://computics-material.jp)
 
 
-Author
-------
-
+Author & Contact
+----------------
 
 .. raw:: html
 
     <script>gen_mail_to_link('Terumasa TADANO', 'terumasa.tadano','gmail.com')</script>
 
-Current affiliation: Department of Applied Physics, The University of Tokyo, Japan
+Department of Applied Physics, 
+The University of Tokyo, Japan
+
+If you have any questions, suggestions, and problems regarding ALAMODE, please feel free to contact the author.
 

docs/source/quickstart.rst

@@ -20,7 +20,7 @@ Program *alm* estimates harmonic and anharmonic interatomic force constants (IFC
 2. Decide the size of supercell
 
   Next, please decide the size of a supercell. Here, one may use a conventional cell.
-  When the primitive cell is fairly large (:math:`a \sim 10` |Angstrom|), one may proceed with the primitive cell.
+  When the primitive cell is fairly large (:math:`a \sim 10` |Angstrom|), one may proceed using the primitive cell. 
 
 3. Prepare an input file for *alm*
 
@@ -52,7 +52,8 @@ Program *alm* estimates harmonic and anharmonic interatomic force constants (IFC
 
   .. Note::
     We provide some auxiliary Python scripts to expedite the above procedure for VASP, Quantum ESPRESSO, and xTAPP users.
-    The script files can be found in the tools/ directory. We are planning to support other software. 
+    The script files can be found in the tools/ directory. 
+    We are willing to support other software if necessary.
 
 
 5. Estimate IFCs by a least-squares fitting
@@ -93,20 +94,18 @@ Program anphon
   
   or ::
 
-    $ mpirun -np NP anphon anphon.in > anphon.log
+    $ mpirun -np NPROCS anphon anphon.in > anphon.log
 
-  Here, ``NP`` is the number of MPI threads. 
+  Here, ``NPROCS`` is the number of MPI threads. 
   If the code is compiled with the OpenMP option, the OpenMP parallelization can also be used by setting the ``OMP_NUM_THREADS`` variable as
   ::
 
     $ export OMP_NUM_THREADS=16
 
   The number 16 should be modified appropriately for your environment.
-
 
   .. Note::
-    MPI parallelization can accelerate the calculation when ``MODE = RTA``.
-    In the current implementation of the code, however, OpenMP parallelization is more efficient.
+    MPI+OpenMP hybrid parallelization is available when calculating thermal conductivity with ``MODE = RTA``, in which anharmonic self-energies of all :math:`N_{\boldsymbol{q},irred}\times N_{j}` phonon modes need to be calculated. Here :math:`N_{\boldsymbol{q},irred}` and :math:`N_{j}` are the number of irreducible :math:`q` points and the number of phonon branches, respectively. These phonon modes are distributed across ``NPROCS`` MPI threads, and phonon self-energies are calculated in parallel. OpenMP is used for the double loop over the :math:`N_{j}` branches inside the calculation of each phonon self-energy. Therefore, a good performance is expected when ``OMP_NUM_THREADS`` is a divisor of :math:`N_{j}^{2}`.
 
 
   When the calculation finishes normally, various files are generated in the working directory.
@@ -123,7 +122,7 @@ Program anphon
 3. Analyze the result
 
   One can plot the phonon dispersion relation or phonon DOS using gnuplot. 
-  Alternatively, one can use a small scripts in the ``tools/`` directory for visualizing these results.
+  Alternatively, one can use a small script in the ``tools/`` directory for visualizing these results.
   For example, 
   ::