6. Running ALAMODE#

ALAMODE consists of two programs. alm extracts the interatomic force constants (IFCs) from forces calculated by DFT, and anphon uses these force constants to calculate phonon properties. The chart below shows how the two programs, the DFT code, and the helper scripts in the tools/ directory work together.

The Input file builder writes a starting input file for either program from a POSCAR.

Overall workflow: DFT, alm, anphon and the analysis tools

Overall workflow. Blue: alm; green: anphon; grey: DFT calculations; yellow: helper scripts in tools/.#

Overall workflow: DFT, alm, anphon and the analysis tools

Overall workflow. Blue: alm; green: anphon; grey: DFT calculations; yellow: helper scripts in tools/.#

6.1. Step 1: Force constants with alm#

Flowchart for calculating force constants with alm

How to obtain the force constants. The harmonic force constants are calculated first; they are needed to generate the random displacements for the anharmonic force constants.#

Flowchart for calculating force constants with alm

How to obtain the force constants. The harmonic force constants are calculated first; they are needed to generate the random displacements for the anharmonic force constants.#

  1. Prepare the DFT reference. Converge the cutoff energy and the \(k\)-point density, then relax the primitive cell until the forces are negligible. Phonons are sensitive to the lattice constant, especially in polar materials such as perovskites.

  2. Choose a supercell. The suitable size depends on the material and the properties of interest. Give the primitive cell to alm and let it generate the supercell with SUPERCELL (recommended), or build the supercell with an external tool such as pymatgen or ASE and give it to alm as it is.

  3. Harmonic force constants (FC2). Run alm with MODE = suggest and NORDER = 1 to obtain the displacement patterns (PREFIX.pattern_HARMONIC), and create the displaced structures with displace.py:

    $ alm alm.in > alm.log
    $ displace.py --VASP POSCAR --mag 0.01 --prefix disp --pattern_file PREFIX.pattern_HARMONIC
    

    With SUPERCELL, the VASP, Quantum ESPRESSO, OpenMX, and LAMMPS interfaces take the supercell from the pattern file, so an input file of the unit cell given to alm is enough. They write the displaced supercells and the undisplaced supercell (SPOSCAR0 for VASP, supercell0.pw.in for QE, supercell0.dat for OpenMX, supercell0.lammps for LAMMPS). The QE and OpenMX files keep the \(k\)-point mesh of the unit-cell input, so reduce it for the supercell. For LAMMPS, the supercell must fit a LAMMPS box without rotation (a along x, b in the xy plane), as it does for a diagonal SUPERCELL of the cell in the LAMMPS data file. The xTAPP interface does not build the supercell: give it an input file of the supercell with the same atom order as the supercell built by alm (listed in the header of the pattern file).

    Calculate the forces of all structures with DFT, and collect the displacements and forces into one file (DFSET), using the undisplaced supercell as the reference (one of the files above, or your own supercell file if you built it externally):

    $ extract.py --VASP SPOSCAR0 vasprun*.xml > DFSET
    $ extract.py --QE supercell0.pw.in disp*.pw.out > DFSET
    

    Then set MODE = optimize, give the DFSET file in the &optimize field, and run alm again with LMODEL = ols. The harmonic force constants are written to PREFIX.h5.

  4. Anharmonic force constants (FC3, FC4, …) — needed for kappa, SCPH, QHA, and more. The recommended way is to fit them to random displacements:

    • Calculate the harmonic phonons of the supercell with anphon (MODE = phonons, KPMODE = 0) using the harmonic force constants, with PRINTEVEC = 1. This writes the phonon eigenvectors to PREFIX.evec.h5.

    • displace.py --VASP SPOSCAR0 --prim POSCAR --random_normalcoord --evec PREFIX.evec.h5 --temp T generates structures sampled at the temperature T (--VASP SPOSCAR0 gives the supercell, --prim the primitive cell). Alternatively, --random adds random displacements to snapshots of a molecular-dynamics run.

    • Calculate the forces with DFT and make a DFSET file as in step 3.

    • Run alm with MODE = optimize, NORDER = 2 or larger, and LMODEL = enet or adaptive-lasso. Give the harmonic force constants with FC2FIX so that only the anharmonic terms are fitted.

    The result, PREFIX.h5, contains everything anphon needs.

displace.py and extract.py support VASP, Quantum ESPRESSO, OpenMX, xTAPP, and LAMMPS. Other codes, such as ASE calculators, WIEN2k, and CRYSTAL, can be used as described in Using other codes (ASE calculators, WIEN2k, CRYSTAL, …). The DFSET format is described here, and a complete example is given in Si : Anharmonic interatomic force constants (IFCs).

The input variables of alm are listed here.

6.2. Step 2: Phonon properties with anphon#

Flowchart for choosing the MODE of anphon

Choosing MODE. Each box lists the force constants (FC2: harmonic, FC3: cubic, FC4: quartic) that PREFIX.h5 must contain.#

Flowchart for choosing the MODE of anphon

Choosing MODE. Each box lists the force constants (FC2: harmonic, FC3: cubic, FC4: quartic) that PREFIX.h5 must contain.#

Set MODE and FCSFILE = PREFIX.h5 in the &general field of the anphon input, and run:

$ anphon anphon.in > anphon.log
$ mpirun -np 8 anphon anphon.in > anphon.log     # with MPI

OpenMP threads are set by OMP_NUM_THREADS and can be combined with MPI. The main output files are:

MODE

Main output files

phonons

PREFIX.bands (dispersion), .dos, .thermo (thermodynamic functions), .msd (mean-square displacements)

kappa

PREFIX.kappa.h5 (all results), .kl (thermal conductivity)

selfenergy

PREFIX.selfenergy.h5

SCPH

PREFIX.scph.h5, .scph_bands, .scph_dos, .scph_thermo

QHA

PREFIX.qha.h5, .qha_thermo

The input variables of anphon are listed here, and all output files here.

6.3. Finite-temperature calculations (SCPH and QHA)#

Flowchart for the structural optimization at finite temperatures

Options of the finite-temperature calculations, and how to use their results in later calculations.#

Flowchart for the structural optimization at finite temperatures

Options of the finite-temperature calculations, and how to use their results in later calculations.#

  • RELAX_STR selects what is relaxed at each temperature: nothing, the atomic positions, or the atomic positions and the cell.

  • Relaxing the cell also needs the elastic constants and the coupling between strain and forces. They come from DFT calculations of strained cells, prepared with the strain tools and given as STRAINFILE. If the coupling between strain and forces is zero by symmetry, STRAIN_COUPLING = 0 skips these DFT calculations and estimates the rest from the force constants.

  • The results at every temperature are stored in PREFIX.scph.h5 or PREFIX.qha.h5. To use them in a later MODE = kappa or phonons calculation, keep FCSFILE pointing to the original IFCs, set DFC2FILE to the SCPH/QHA result file, and set FC2_TEMPERATURE to a stored temperature. If the structure was relaxed, also set RELAXED_STRUCTURE = 1; FCSFILE must then contain the same FC4 (and, after a STRAIN_FC5 = 1 relaxation, the same FC5) as used in the SCPH/QHA run. For kappa, set TMIN = TMAX = FC2_TEMPERATURE for each run.

6.4. Step 3: Analyze the results#

Script

Reads

Shows

plotband.py

PREFIX.bands

Phonon dispersion

plotdos.py

PREFIX.dos

Phonon density of states

analyzer.py

PREFIX.kappa.h5

Phonon lifetimes, mean free paths, cumulative thermal conductivity

For example:

$ plotband.py PREFIX.bands
$ analyzer.py --calc tau --temp 300 --h5 PREFIX.kappa.h5
$ analyzer.py --calc cumulative --temp 300 --h5 PREFIX.kappa.h5

Each script prints its options with -h. Complete examples are given in the Tutorial.