Keyword descriptions below obey the following conventions: N – integer constant, R – real constant, C(n) – character constant of the maximum length n, L- logical variable. Curly brackets {} imply optional arguments. Unless otherwise specified, the units are the following: [l]=angstrom, [E]=electronvolts, [T]=K, [P]=GPa,[q]=electron charge, [m]=a.m.u.
Real space cutoff for the calculations of the third derivative matrices in the units of angstrom. If classical potential is used, then potential cutoff will be used as a defult. if the interface to another code is to be used, then this value need to be supplied, as it will be determine the size of the super-cell for finite displacement approach.
Examples:
D3_cutoff 10.0
Default:
Largest interaction cutoff
kpoints
Format:
kpoints N1 N1 N3 N4
Description:
Define the k-point mesh on which phonon properties are to be calculated. First three integers determine resolutions along x,y and z axes in the reciprocal space. For convenience, we employ odd valued grid and have a grid points on opposing edges of the Brillouin Zone, which implies that those are duplicated due to periodic boundary conditions. Proper weighting ensures correct integration over the Brillouin Zone. The convenience is that any two grid vectors are also a grid vector and no special cases arises in the calculations of the three phonon processes. PhonTS will correct itself even-valued grid, if supplied by user and issue a warning. The rule of thumb is to have about cubic volume elements, hence one typically needs fewer k-points in the longer real space dimension. Forth integer specifies the finer grid along z-axis for more accurate determination of the energy conservation surface in thermal conductivity calculations. Such refinement ensures fast convergence with the size of the main k-point grid (but it is desirable to ensure the convergence) Value of 1 corresponds to no refinement. Our experience indicates that refinement of 10 is sufficient for most of the cases. Minimum grid is meaningful for the calculations in PhonTS is 3x3x3. The values of N1=1 and N2=1 are reserved to signify a 2D system (N1=1), or a 1D system (N1=1 and N2=1) which can be used to study things like graphene and/or nanotubes.
Examples:
kpoints 15 15 15 1 kpoints 1 7 7 5
Default:
9 9 9 10
ASR_3der
Format:
ASR_3der
Description:
Enforces the acourstic sum rule for the third derivatives (it is always forced for the 2nd derivatives). It has been shown in the literature, that finitwe cutoff of the third derivatives leads to violations of the requiremements on the force coenstants that appear as a result of the translational and roational symmetries. Subset of those are also known as acoustic sum rules. We enforce them in the simplest manner: by requiring diagonal term to be equal to the sum of the of diagonal terms. See this reference for more details. This is of course the most pronounced for the ab initio calculations, where cut off is forced to be quite short due to computational load. For classical potentials we found the effect to be negligible for a cutoffs of the oprser of 2-3 lattice constants, even if electrostatic interaction is present in the system.
Examples:
ASR_3der T
Default:
False
Isotope
Format:
Isotope R
Description:
Account for the additional contribution to thermal resistivity caused by the isotopic substitution. Supplied real number is the scattering parameterΓ, which user needs to evaluate for a specfic system of interest according to the formula :
Examples:
Isotope 0.134
Default:
0
Sample_size
Format:
Sample_size R
Description:
Account for the boundary scattering in the macroscopic sample. This is the only parameter that has different units: it is in meters. Contribution from the boundary scattering for each individual phonon (τ=L/v) is added by the Mathiessien rule to the intrinsic phonon-phonon scattering time.
Examples:
Sample_size 0.1
Default:
Infinity
cut_optical
Format:
cut_optical N
Description:
Removes upper N phonon branches from the calculations alltogether. Each phonon played double role in the phonons transport: it is a heat carrier, and simulataniously a scatterer for other phonons. While relaxaton time for each phonon gives an account of its heat carrying ability, there is no direct measure for the scattering ability. One possible way is to eliminate the phonons from the calculation and see the change in thermal conductivity: this keyword does this for the upper energy branches.
Examples:
cut_optical 3
Default:
0
shift_optical
Format:
energy_cutoff R
Description:
This keyword attempts to improve efficiency by using observation that optical phonons often contribute little to the thermal conductivity: no phonons above certain energy are considered as a heat carriers. (they are still considered for the scattering). Energy is in THz, negative values imply no cutoff.
Examples:
energy_cutoff 10.0
Default:
-1
Format:
shift_optical R
Description:
In order to investigate the influence of the optical modes on the thermal transport it might be instructive to change their position “by hand” relative to the acoustic branches. This keyword allow for this to happen. Real number provided (in THz) specifies by how much the energy of the upper optical branches is increased. The number of branches affected is specified by cut_optical keyword.
Examples:
shift_optical 1.0
Default:
10e8
energy_cutoff
Format:
energy_cutoff R
Description:
This keyword attempts to improve efficiency by using observation that optical phonons often contribute little to the thermal conductivity: no phonons above certain energy are considered as a heat carriers. (they are still considered for the scattering). Energy is in THz, negative values imply no cutoff.
Examples:
energy_cutoff 10.0
Default:
-1
neglect_3b
Format:
neglect_3b L
Description:
Zeros down the third derivatives of the potential energy that involve differentiation over atomic coordinates of the 3 different atoms. These terms are automatically zero for a two-body potentials, thus this might be useful to elucidate many-body effects.
Examples:
neglect_3b T
Default:
False
do_min_therm_cond
Format:
do_min_therm_cond L
Description:
Attemtps to approximately correct for a breakdown of the phonon theory at high temperature: namely, if a phonon mean free path was found to be below the shortest interatomic distance, its lifetime is corrected to this distance divided by the the group velocity of the phonon. This is quite approximate.
Examples:
do_min_therm_cond T
Default:
False
do_perturbation
Format:
do_perturbation L
Description:
Turns on perturbation theory calculations for a determination of the possible states crossings when one searches for the surface of the energy conservation in the three-phonon scattering. This is described in detail here . This turns out to be very important, if one has only one or two atoms in the cell, and otherwise it does not matter too much. Not implemented for a first principles calculations.
Examples:
do_perturbation T
Default:
True
do_classical
Format:
do_classical L
Description:
Uses high-temperature limit in the expression for the Bose-Einstein distribution, which also corresponds to a classical description. This is usefull when comparing to MD simulations, since the latter is always in the classical regime. Should not matter much above the Debye temperature, but can make large difference below, and the direction of the error is not universal, see here for examples.
Examples:
do_classical T
Default:
False
mixing
Format:
mixing R
Description:
Iterative solution of the BTE can be viewed as a solution of the set of linear equations by the conjugated gradient technique. For a positive-defined matrix, this is always a convergent procedure, thus solution should always exist. In practice, however, numerical errors can lead to instabilities, which can be mitigated by “mixing” in the spirit of the solution of the self-consistency problems in the electronic structure calculations. This also improves convegence speed. Supplied values should be between 0 and 1, 1 corresponds to no mixing, and 0 corresponds to no update. In our expirience alteration of this is very seldom needed.
Examples:
mixing 0.3
Default:
0.5
iter_steps
Format:
iter_steps N
Description:
Specifies the number of steps for the iteration procedure. Very seldom more than 10 are required: expamples of the systems that do include very low temperature, 1D or 2D systems.
Examples:
iter_steps 5
Default:
10
numerical_2der
Format:
numerical_2der L
Description:
Finds second derivatives through the numerical differentiation of the forces by finite displacement method. Can be used in conjuction with any interaction keyword.
Examples:
numerical_2der T
Default:
F
var_finish
Format:
var_finish L
Description:
Finish up the iterative run with the variational calculation using subsequent approximations to the non-equilibrium distribution function as a trial functions. Number of iterations, therefore, automatically sets number of the variational functions.
Examples:
var_finish T
Default:
F
numerical_3der
Format:
numerical_3der L
Description:
Finds third derivatives through the numerical differentiation of the forces by finite displacement method. Can be used in conjuction with any interaction keyword.
Examples:
numerical_3der T
Default:
F
Performance keywords
kspace_parall
Format:
kspace_parall L
Description:
This keyword is to be used for a very large systems, where parallelization across phonons states at each k-point is more reasonable way to go than across k-points. For example, if one has 100 atoms in the cell and considers 5x5x5 k-point mesh, then there are 300 phonon states at each of 125 k-points. Splitting the calculations across phonon states will allow to use 300 processors, while k-points split will permit to use only 125 processors.
Examples:
kspace_parall F
Default:
T
low_mem
Format:
low_mem N
Description:
The main bottleneck for considering larger systems is the memory constraints in the current implementation. One can always substitute memory requirements by time requirements by computing on the fly things that used to be stored. This keyword does just that: shifts different calculations from being precomputed and stored to be computed on the fly during computation of the phonon-phonon scattering probabilities. The larger this number, the more staff is computed on the fly, with the maximum value of 3. Quantities shifted from memory to the calculations on the fly are: Fourier transform of the third derivatives (low_mem=1, automatic for the numerical derivatives or not 2-body potentials, including AbInitio); phonon eigenvectors (low_mem=2); some technical pieces in the computation of the anharmonic matrix elements (low_mem=3).
Examples:
low_mem 2
Default:
0
Ab Initio keywords
AbInitio
Format:
AbInitio L1 L2
Description:
This keyword indicates that first principles would be perfromed via interfacing to one of the first principles codes, such as VASP or QuantumEspresso. Such calculations are to be performed in 3 stages: preparation run, which only creates input structures for those codes, followed by a bunch of first principles calculations, followed by a thermal conductivity run where the output from first principles code is used to compute real-space second and third total energy derivatives and thermal conductivity. First logical variable specifies that preparation run needs to be done, while second controls production run. Strictly speacking, it means that only “F T” or “T F” combinations are allowed. For more detailes please see example in the manual section. Has to be used together with the FP_interface keyword.
Examples:
AbInitio F T
Default:
F F
delta
Format:
delta R
Description:
Specifies the magnitude of the atomic displacements for finite differences calculations in turms of lattice constants. In choosing this number a few factors need to be taken into account: It is an interplay between the accuracy of the quantity being differentiated (in our case interatomic forces) and the accuracy of the approximation for the derivative. Namely, if the accuracy of the differentiated quantity is poor, then small values of δ will return large derivatives error (roughly ~dF/δ). In the opposite extreme of large δ the error due to using central difference is proportional to ~δ 2 . It is especially important in the context of the first principles calculations. The accuracy of the forces in that case is determined by self-consistency accuracy and accuracy of the integrations over the energy density. Optimistic estimates will put this accuracy at 10 -5 , may be 10 -6 at best with maxing out appropriate settings. Therefore for first prionciples calculations this value should be larger than default. In our experience, it should be ~0.005 (lattice constant for many materials is very roughly around ~5 Angstrom), so this corresponds to ~0.001 Angstrom. Note, that this is about an order of magnitude smaller than sugested by the VASP manual for the phonons calculations, but we actually need 3rd derivatives, so we have a tighter requirements. Our tests indicates that we see virtually no change in the phonon structure if we alter this value by an order of magnitude or so. In the case of VASP caulations it is recommended to use ADDGRID=T, tight EDIFF of at least 10 -8 and maybe use finer than default FFT meshes.
Examples:
delta 0.005
Default:
0.0005
FP_interface
Format:
FP_interface C(*)
Description:
Specifies the interface for the external code energy/forces calculations, most notably first principles. Current choices are VASP (will do second and third derivative numerically), QE (can do second derivatives from DFPT, and third numerically, or both second and third numerically) and LAMMPS (both second and third derivatives numerically). The last one is not ab-initio, but allow access to a large number of potentials available in LAMMPS.
Examples:
FP_interface VASP
Default:
VASP
new_filename
Format:
new_filename L
Description:
This keyword Determines whether filenames in the interfaces to other codes will have a lattice constant as a part of it. It needs to be .TRUE. (default) if QHA calculations are to be performed. It was introduced for a backwards compartibility, and therefore rarely needs to be altered.
Examples:
new_filename F
Default:
T
External conditions keywords
Temperature
Format:
temperature R1 {R2} {N}
Description:
Specifies temperature in degrees Kelvin (if only one real constant is supplied) or a range of temperatures (if all three arguments are supplied) for the simulations. In the latter case, N temperature points are obtained by
Thermal conductivity is computed for each temperature (at the same volume). Also accepts abbreviations “temp”, “Temp”
Examples:
temperature 300. temperature 100. 300. 3
Default:
temperature 300 1200 9
Pressure
Format:
Pressure R1 {R2} {N}
Description:
Specifies pressure for the quasiharmonic approximation ( QHA ) calculation in GPa (if only one real constant is supplied) or a range of pressures (if all three arguments are supplied). In the latter case, N pressure points are obtained by
Note, that thermal conductivity in the solid state system is a function of pressure only through the volume of the system. Thus once the equilibrium volume at given temperature and pressure is established via QHA, thermal conductivity calculations itself does not need any pressure specified (unlike temperature). QHA by itself can be used to study phase diagram of the material, assuming it is a valid approximation – in the low temperature region.
Examples:
Pressure 0. 100. 21
Default:
Pressure 0
Service keywords
printout
Format:
printout C(*)
Description:
Specifies the level of output from PhonTS. Currently there are 3 different levels, though its complete implementation is in the works. The levels are ‘basic’ (default), ‘extended’ and ‘debugging’ with progressively more verbose output.
Examples:
printout debugging
Default:
basic
print_vectors
Format:
print_vectors L
Description:
Creates output file that contains eigenvectors of the phonon modes at each k-point. This file is rather large, hence the separate keyword to request it. The format of the file is first column specifies the eigenvector at given k-point, the second specifies the component of the eigenvetor, followed by real and imaginary part of the value. The k-point number is the last number in the line.
Examples:
print_vectors T
Default:
False
Supercell
Format:
supercell N1 N2 N3
Description:
Instract PhonTS to make a larger supercell out of the supplied cell for the thermal transport simulations. This is usefull, if one desires to study large disordered system in conjuctions with randomize keyword.
Examples:
supercell 2 2 2
Default:
1 1 1
randomize
Format:
randomize L
Description:
Grabs input structure and randomly rearranges atoms of the lattice sites. It is usefull for simulating random allows, like SiGe, for example.
Examples:
randomize T
Default:
F
delta_k
Format:
delta_k R
Description:
Specifies the step in the k-space for the numerical differentiation of the frequencies for the group velocities calculatoins in term of the reciproical lattice vector. This parameter rarely needs a change.
Examples:
delta_k 0.001
Default:
0.0001
do_dispersion
For versions after 1.1.2
Format:
do_dispersion N1 N2
R x R y R z R x R y R z … R x R y R z R x R y R z
Description:
Performes sampling of the Brillouin Zone along specified directions for plotting of the phonons dispersion relations. This requares a separate PhonTS calculation from thermal conductivity or phonon density of states. N1 specifies number of lines and N2 specifies number of sampling points along each line. This keyword is to be followed by N1 pairs of k-points coordinates that specify the beginning and the end of each line. This keyword also automatically sets phonons_only keyword to TRUE. Also note that k-points coordinates should be given in reciprocal lattice basis.
do_dispersion 0 0, indicating that no dispersion will be produced.
For versions up to 1.1.2
Format:
do_dispersion N
Description:
Performes sampling of the Brillouin Zone along <001>, <011>, and <111> directions for easier plotting of the phonons dispersion relations. This requares a separate PhonTS calculation from thermal conductivity or phonon density of states. N specifies total number of points used. This keyword also automatically sets phonons_only keyword to TRUE.
Examples:
do_dispersion 180
Default:
do_dispersion 0
pdos
Format:
pdos R1 R2 N R3
Description:
Controls the energy range for the phonon density of states calculations (R1 to R2, in THz), number of intervals (N) and gaussian smoothing factor (R3, in THz -2 ). Upper limit (R2) in the current version of the code will be adjusted to the maximum frequency encountered during the simulations, if the latter is greater than supplied value. PDOS is normalized the number of atoms in the system.
Examples:
pdos 0. 30. 300 5.
Default:
pdos 0. 30. 200 10.
number_proj
Format:
number_proj N
Description:
Specifies the number of atoms (N) for which projected density of states are to be calculated. This is to follow up by the proj_dos_atom_list keyword
Examples:
number_proj 2
Default:
0
proj_dos_atom_list
Format:
proj_dos_atom_list N 1 ,…N number_proj
Description:
Specifies the numbers of atoms in the atoms list for which projected densities of states are to be calculated. Has to be used in conjuction with number_proj keyword.