Added descriptions of anharmonic free energy in documentation

docs/source/conf.py

@@ -107,7 +107,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/formalism/formalism_anphon.rst

@@ -105,6 +105,19 @@ given as follows:
 
 Here, :math:`k` is the Boltzmann constant. These quantities will be saved in the ``PREFIX``.thermo file.
 
+When the self-consistent phonon mode (``MODE = SCPH``) is selected, the anharmonic free-energy 
+defined by the following equation will be calculated and saved in the ``PREFIX``.scph_thermo file:
+
+.. math::
+    :nowrap:
+    
+    \begin{align*}
+     F^{\mathrm{SCP}} &= \frac{1}{N_{q}}\sum_{\boldsymbol{q},j}\left[ \frac{\hbar\Omega_{\boldsymbol{q}j}}{2} + kT\log{\left( 1 - e^{-\hbar\Omega_{\boldsymbol{q}j}/kT}\right)} \right] \\
+     & - \frac{1}{N_{q}}\sum_{\boldsymbol{q},j}\left[ \Omega_{\boldsymbol{q}j}^{2} - (C_{\boldsymbol{q}}^{\dagger}\Lambda_{\boldsymbol{q}}^{(\mathrm{HA})}C_{\boldsymbol{q}})_{jj} \right]
+     \times \frac{\hbar [1 + 2n_{\boldsymbol{q}j} ]}{2\Omega_{\boldsymbol{q}j}}.
+    \end{align*}
+
+Details of the derivation of the above expression can be found in Ref. [7]_.
 
 
 Mean square displacement
@@ -445,3 +458,5 @@ When ``SELF_OFFDIAG = 1``, the off-diagonal elements are also calculated, and th
 .. [5] P\. E. Bl\ |umulaut_o|\ chl, O. Jepsen, and O. K. Andersen, Phys. Rev. B **49**, 1450555 (1994).
 
 .. [6] T\. Tadano and S. Tsuneyuki, Phys. Rev. B **92**, 054301 (2015).
+
+.. [7] Y.\ Oba, T. Tadano, R. Akashi, and S. Tsuneyuki, Phys. Rev. Materials **3**, 033601 (2019).

docs/source/input/inputanphon.rst

@@ -551,8 +551,8 @@ The first entry **KPMODE** specifies the types of calculation which is followed
 
  === ====================================================================================
   0   Do not compute scattering phase space
-  1   Total and mode-decomposed scattering phase space involving three-phonon processes 
-      will be stored in ``PREFIX``.sps
+  1   | Total and mode-decomposed scattering phase space involving 
+      | the 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
  === ====================================================================================
@@ -568,8 +568,8 @@ The first entry **KPMODE** specifies the types of calculation which is followed
 
  === ====================================================================================
   0   Do not compute the (atomic) participation ratio
-  1   Compute participation ratio and atomic participation ratio, which will be 
-      stored in  ``PREFIX``.pr and ``PREFIX``.apr respectively.
+  1   | Compute participation ratio and atomic participation ratio, which will be 
+      | stored in  ``PREFIX``.pr and ``PREFIX``.apr respectively.
  === ====================================================================================
 
  :Default: 0
@@ -599,8 +599,8 @@ The first entry **KPMODE** specifies the types of calculation which is followed
  === =========================================================================
   0   Do not consider phonon-isotope scatterings
   1   Consider phonon-isotope scatterings
-  2   Consider phonon-isotope scatterings as in ``ISOTOPE = 1`` and 
-      the corresponding selfenergy will be stored in ``PREFIX``.gamma_isotope
+  2   | Consider phonon-isotope scatterings as in ``ISOTOPE = 1`` and 
+      | the calculated selfenergy is stored in ``PREFIX``.gamma_isotope
  === =========================================================================
 
  :Default: 0
@@ -619,6 +619,21 @@ The first entry **KPMODE** specifies the types of calculation which is followed
                This quantity is equivalent to :math:`g_{2}` appearing in the original paper by S. Tamura [Phys. Rev. B, 27, 858.].
 
 
+````
+
+* FE_BUBBLE-tag = 0 | 1
+
+ === ====================================================================================
+  0   Do not compute the vibrational free-energy associated with the bubble diagram
+  1   | Compute the vibrational free-energy associated with the bubble diagram and 
+      | save it in ``PREFIX``.thermo (when ``MODE = phonons``) or ``PREFIX``.scph_thermo (when ``MODE = SCPH``).
+ === ====================================================================================
+
+ :Default: 0
+ :Type: Integer
+ :Description: This tag is used when *KPMODE* = 2.
+
+
 ````
 
 * ANIME-tag = k1, k2, k3

docs/source/intro.rst

@@ -54,7 +54,7 @@ Anharmonic properties
 * Phonon frequency shift due to 3- and 4-phonon interactions
 * Temperature-dependent effective potential method
 * Self-consisitent phonon (SCPH) calculation
-
+* Anharmonic vibrational free-energy
 
 Links
 -----
@@ -88,6 +88,11 @@ If you use the self-consistent phonon (SCPH) method, please cite the following p
   T\. Tadano and S. Tsuneyuki, Phys. Rev. B **92**\ , 054301 (2015). 
   [`Link <https://journals.aps.org/prb/abstract/10.1103/PhysRevB.92.054301>`__]
 
+If you use ALAMODE to compute anharmonic vibrational free-energies in your research paper,
+please cite the following paper as well:
+
+  Y\. Oba, T. Tadano, R. Akashi, and S. Tsuneyuki, Phys. Rev. Materials **3**\, 033601 (2019). 
+  [`Link <https://journals.aps.org/prmaterials/abstract/10.1103/PhysRevMaterials.3.033601>`__]
 
 Acknowledgement
 ---------------

docs/source/output.rst

@@ -9,20 +9,23 @@ Output files of alm
 
 * ``PREFIX``.pattern_HARMONIC, ``PREFIX``.pattern_ANHARM?
 
- In these files, displacement patterns are printed in units of :math:`\boldsymbol{e}_{x,y,z}`.
- These files are created when ``MODE = suggest``. 
+ In these files, displacement patterns are printed in units of
+ :math:`\boldsymbol{e}_{x,y,z}`.
+ These files are created when ``MODE = suggest``.
  Patterns for anharmonic force constants are printed only when ``NORDER > 1``.
 
 * ``PREFIX``.fcs
 
  Harmonic and anharmonic force constants in Rydberg atomic units.
  In the first section, only symmetry-reduced force constants are printed.
- All symmetry-related force constants are shown in the following section with the symmetry prefactor (:math:`\pm 1`).
+ All symmetry-related force constants are shown in the following section
+ with the symmetry prefactor (:math:`\pm 1`).
  Created when ``MODE = fitting``.
 
 * ``PREFIX``.xml
 
- A XML file containing necessary information for performing phonon calculations.
+ A XML file containing necessary information for performing
+ phonon calculations.
  The files can be read by *anphon* using the ``FCSXML``-tag.
  Created when ``MODE = fitting``.
 
@@ -54,6 +57,8 @@ Output files of anphon
 
  Constant volume heat capacity, vibrational entropy, internal energy, and vibrational free energy.
  Created when ``MODE = phonons`` with **KPMODE** = 2.
+ When ``FE_BUBBLE = 1`` is set in the **&analysis** field, an additional bubble correction term 
+ to the vibrational free energy is also calculated.
 
 * ``PREFIX``.msd
 
@@ -149,6 +154,14 @@ Output files of anphon
 
  Anharmonic phonon dispersion curves. The format is same as the ``PREFIX``.bands.
 
+* ``PREFIX``.scph_thermo
+
+ Constant volume heat capacity, vibrational entropy, and vibrational free energy calculated
+ based on the self-consistent phononon calculation. 
+ Created when ``MODE = SCPH`` with **KPMODE** = 2.
+ When ``FE_BUBBLE = 1`` is set in the **&analysis** field, an additional bubble correction term 
+ to the vibrational free energy is also calculated.
+
 * ``PREFIX``.scph_fc2_correction
 
  This file contains :math:`\Delta D(\boldsymbol{q}) = D_{\mathrm{SCPH}}(\boldsymbol{q}) - D_{\mathrm{Harmonic}}(\boldsymbol{q})`.