Running ALAMODE
===============

.. |Angstrom|   unicode:: U+00C5 


Program alm
-----------

Program *alm* estimates harmonic and anharmonic interatomic force constants (IFCs) based on the *supercell approach*. 


1. Perform usual SCF calculations for a *primitive cell*

  Before performing phonon calculations, one needs to perform usual self-consistent field calculations and check the convergence with respect to the cutoff energy and the :math:`k` point density.
  After that, please optimize the internal coordinate so that the atomic forces are negligibly small.
  Optimization of cell parameters may also be necessary, but please note that phonon properties are relatively sensitive to the cell parameters in polar materials such as perovskites.

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 using the primitive cell. 

3. Prepare an input file for *alm*

  Please make an input file for *alm*, say alm.in, which should contain ``&general``, ``&interaction``, ``&cutoff``, and 
  ``&position`` entries. For details of available input variables, please refer to :ref:`here <label_inputvar_alm>`. 
  Once the input file is properly prepared with ``MODE = suggest``, 
  necessary displacement patterns can be generated by executing *alm* as follows::
    
        $ alm alm.in > alm.log

  This produces the following files containing the pattern of atomic displacements.

  * ``PREFIX``.HARMONIC_pattern
  * ``PREFIX``.ANHARM?_pattern (If ``NORDER`` > 1)
  
  In pattern files, all necessary displacement patterns are given in **Cartesian coordinates**.

  .. Note::
    Pattern files just indicate the direction of displacements. 
    The magnitude of displacements should be specified by each user.
    (:math:`\Delta u \sim 0.01` |Angstrom| is usual for calculating harmonic force constants.)

4. Perform SCF calculations to generate displacement-force data set

  Then, please prepare necessary input files for a DFT engine (or a classical force field engine) 
  and calculate atomic forces for each displaced configuration.
  Once the atomic forces are calculated for all configurations, please collect the atomic displacements and atomic forces to separate files, say `disp_all.dat` and `force_all.dat`, in Rydberg atomic units. 
  The detail of the file format is described on :ref:`this page <label_format_DFSET>`.

  .. 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 willing to support other software if necessary.


5. Estimate IFCs by linear regression

  In order to perform a fitting, please change the variable ``MODE`` of the input file `alm.in` to ``MODE = optimize``. 
  In addition please add the ``&optimize`` entry with appropriate ``DFSET``. Then, IFCs can be estimated by executing
  
  ::

  $ alm alm.in > alm.log
  
  which makes the following two files in the working directory.

  * ``PREFIX``.fcs : The list of force constants
  * ``PREFIX``.xml : XML file containing necessary information for subsequent phonon calculations


Program anphon
--------------

1. Prepare an input file for *anphon*
  
  To perform phonon calculations and thermal conductivity calculations, one needs to prepare another input file, say `anphon.in`, for the program *anphon*. 

  If one wants to perform (harmonic) phonon calculations, one should write ``MODE = phonons`` in the ``&general`` entry of anphon.in. Please make sure that ``FCSXML`` variable is set to the XML file generated by *alm*. 

  If one wants to conduct thermal conductivity calculations instead of usual phonon calculations, please switch to ``MODE = RTA`` with appropriate ``FCSXML`` containing cubic IFCs. 

  For details of input variables of anphon, please refer to the :ref:`list of input variables for anphon <label_inputvar_anphon>`.


2. Execute *anphon*

  Phonon properties and lattice thermal conductivity can be calculated via executing
  ::

    $ anphon anphon.in > anphon.log
  
  or ::

    $ mpirun -np NPROCS anphon anphon.in > anphon.log

  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+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.

  * ``PREFIX``.bands : Phonon dispersion along designated Brillouin zone paths
  * ``PREFIX``.dos : (Atom projected) phonon DOS
  * ``PREFIX``.thermo : Thermodynamic functions
  * ``PREFIX``.msd : Mean-square displacement of atoms
  * ...

  The complete list of output files can be found :ref:`here <reference_output>`.


3. Analyze the result

  One can plot the phonon dispersion relation or phonon DOS using gnuplot. 
  Alternatively, one can use a small script in the ``tools/`` directory for visualizing these results.
  For example, 
  ::

    $ plotband.py target.bands

  shows the phonon dispersion relation. Available command line options can be displayed by

  ::

    $ plotband.py -h

  We also provide a similar script for phonon DOS. Another script ``analyze_phonons.py`` may be useful to analyze the result of thermal conductivity calculations. For example, phonon lifetimes and mean-free-path at 300 K can be extracted by

  :: 

    $ analyze_phonons.py --calc tau --temp 300 target.result


  It can also estimate a cumulative thermal conductivity by

  ::

    $ analyze_phonons.py --calc cumulative --temp 300 --direction 1 target.result


  For details, see the tutorial.