11.1. ANPHON: Input files#
Format of input files#
Each input file should consist of entry fields. Available entry fields are
&general, &cell, &scph, &qha, &relax, &kpoint, &strain, &displace, &analysis, &kappa, and &selfenergy.
The format of the input file is the same as that of alm which can be found here.
List of supported input variables#
&general |
|||
&cell |
|||
&kpoint |
|||
&kappa |
|||
&selfenergy |
|||
&scph |
|||
&qha |
|||
&relax |
|||
&strain |
|||
&displace |
|||
&analysis |
|||
Description of input variables#
“&general”-field#
PREFIX-tag : Job prefix to be used for names of output files
- Default:
None
- Type:
String
MODE-tag = phonons | kappa | selfenergy | SCPH | QHA
phonons
Calculate phonon dispersion relation, phonon DOS,Grüneisen parameters etc.kappa
Calculate phonon lifetimes and lattice thermal conductivitybased on the Boltzmann transport equation (BTE). The solverlevel (RTA, IBTE, …) is chosen by the SOLVERtag of the &kappa field.MODE = RTAis a deprecated alias.selfenergy
Calculate the anharmonic self-energy (linewidth, frequencyshift, spectral function) of selected phonon modes atarbitrary wave vectors. See theSCPH
Calculate temperature dependent phonon dispersion curvesby the self-consistent phonon method. WithRELAX_STR the crystal structure ateach temperature is optimized as well.QHA
Calculate the crystal structure and phonons at finitetemperatures within the quasi-harmonic approximation.
- Default:
None
- Type:
String
KD-tag : List of the atomic species
- Default:
The element names stored in
FCSFILE(orFC2FILE)- Type:
Array of strings
- Description:
When given, the number of entries must match the number of species in
FCSFILE, and they are assigned to the species in the order stored in that file. TheNKDtag of version 1.x is no longer accepted; remove it from old input files.- Example:
In the case of GaAs, it should be
KD = Ga As.
MASS-tag : List of atomic masses, one value per atomic species (in the order of the
KD-tag)
- Default:
Standard atomic weight of elements given by the
KD-tag- Type:
Array of doubles
- Example:
In the case of Bi2Te3,
MASSshould beMASS = 208.98 127.60.
FCSFILE-tag : File (XML or HDF5) containing force constants generated by the program alm
- Default:
None
- Type:
String
- Description:
Either
FCSFILEorFC2FILEmust be given to start a phonon calculation.Note
FCSFILEandFC2FILEreplace the formerFCSXMLandFC2XMLtags, which are no longer accepted.Note
For HDF5 files, the
unitattributes stored in the file (e.g. by alm withFCS_UNIT_OUTPUT = eV/angstrom) are honored: the lattice vectors, shift vectors, and force constant values are converted to the internal Rydberg atomic units automatically. Files without unit attributes are assumed to be in bohr and Ry/bohrn. XML files are always in Rydberg atomic units.
FC2FILE-tag : File containing harmonic force constants for a different supercell size
- Default:
None
- Type:
String
- Description:
When
FC2FILEis given, the harmonic force constants in this file are used for calculating dynamical matrices. It is possible to use supercells of different sizes for harmonic and anharmonic terms, which are specified byFC2FILEandFCSFILErespectively. Analogously,FC3FILEandFC4FILEcan be used to supply the cubic and quartic force constants from separate files; when they are not given, the corresponding terms are read fromFCSFILE.Each order is thus read from exactly one file:
Order
Source
FC2
FC2FILEif given, otherwiseFCSFILEFC3
FC3FILEif given, otherwiseFCSFILE(only when the mode needs FC3)FC4
FC4FILEif given, otherwiseFCSFILE(only when the mode needs FC4)Note
FC2FILE vs. DFC2FILE.
FC2FILEreplaces the source of the FC2: the FC2 is read from it instead of fromFCSFILE. DFC2FILE replaces nothing: it adds the anharmonic correction \(\Delta\Phi(T)\) of an SCPH/QHA run on top of the FC2 read fromFC2FILE(orFCSFILE).When
FC2FILE(orFCSFILE) is itself an SCPH/QHA state file (PREFIX.scph.h5 /PREFIX.qha.h5), which FC2 is used depends on FC2_TEMPERATURE:
without
FC2_TEMPERATURE, the base (harmonic) FC2 stored in the file is used and the renormalized FC2 is ignored;with
FC2_TEMPERATUREand withoutDFC2FILE, the renormalized FC2 at that temperature is used (withDFC2FILE, the base FC2 is used as above and the correction comes fromDFC2FILE).To use a renormalized FC2, therefore, either give the state file as
FC2FILEtogether withFC2_TEMPERATURE, or keep the original harmonic FC2 asFC2FILE/FCSFILEand give the state file asDFC2FILEtogether withFC2_TEMPERATURE. The latter is needed when the harmonic FC2 comes from a larger supercell than the SCPH/QHA cell. See the table under DFC2FILE for all combinations.The FC2 actually used is printed in the standard output (the
Order 2line of the list of force-constant files) and, inMODE = kappa, stored as/metadata/fc2_sourceand/metadata/fc2_descriptioninPREFIX.kappa.h5.
TOLERANCE-tag : Tolerance for finding symmetry operations
- Default:
1.0e-3
- Type:
Double
PRINTSYM-tag = 0 | 1
0
Symmetry operations won’t be saved in “SYMM_INFO_PRIM”
1
Symmetry operations will be saved in “SYMM_INFO_PRIM”
- Default:
0
- type:
Integer
NONANALYTIC-tag = 0 | 1 | 2 | 3
0
Non-analytic correction is not considered.1
Include the non-analytic correction by the damping method proposed by Parlinski.2
Include the non-analytic correction by the mixed-space approach3
Include the non-analytic correction by the Ewald method
- Default:
0
- Type:
Integer
- Description:
When
NONANALYTIC > 0, appropriateBORNINFOneeds to be given. IfNONANALYTIC = 1, one may need to adjust theNA_SIGMAvalue to obtain reasonably smooth dispersion curves.
NA_SIGMA-tag : Damping factor for the non-analytic term
- Default:
0.1
- Type:
Double
- Description:
Used when
NONANALYTIC = 1. The definition ofNA_SIGMAis described in the formalism section.
BORNINFO-tag : File containing the macroscopic dielectric tensor and Born effective charges for the non-analytic correction
- Default:
None
- Type:
String
- Description:
The details of the file format can be found here.
BORNSYM-tag = 0 | 1
0
Do not symmetrize Born effective charges
1
Symmetrize Born effective charges by using point group symmetry
- Default:
0
- Type:
Integer
PREC_EWALD-tag : Accuracy of the Ewald summation used for
NONANALYTIC = 3
- Default:
1.0e-12
- Type:
Double
- Description:
Read only when
NONANALYTIC = 3. The convergence parameter and the real- and reciprocal-space cutoffs of the Ewald summation of the dipole-dipole interaction are chosen automatically so that the neglected terms are of the order ofPREC_EWALD. The value must satisfy 0 <PREC_EWALD< 1.
TMIN, TMAX, DT-tags : Temperature range and its stride in units of Kelvin
- Default:
TMIN = 0,TMAX = 1000,DT = 10- Type:
Double
EMIN, EMAX, DELTA_E-tags : Energy range and its stride in units of Kayser (cm-1)
- Default:
EMINandEMAXare set automatically from the eigenfrequencies. The default value forDELTA_Eis 10.0.- Type:
Double
ISMEAR-tag = -1 | 0 | 1 | 2
-1
Tetrahedron method
0
Lorentzian smearing with width of
EPSILON1
Gaussian smearing with width of
EPSILON2
Adaptive Gaussian smearing
- Default:
-1
- Type:
Integer
- Description:
ISMEARspecifies the method for Brillouin zone integration (DOS and three-phonon scattering rates). WithISMEAR = 2, the Gaussian width is chosen automatically for each pair of phonon modes from the group-velocity difference and the \(k\)-mesh spacing,\[\sigma_{jj'}(\boldsymbol{q}) = \alpha \sqrt{\frac{1}{12} \sum_{u=1}^{3} \left[ \left( \boldsymbol{v}_{j} - \boldsymbol{v}_{j'} \right) \cdot \frac{\boldsymbol{G}_{u}}{N_{u}} \right]^{2} },\]following the adaptive-broadening scheme of Yates et al. [Phys. Rev. B 75, 195121 (2007)], where \(\boldsymbol{G}_{u}/N_{u}\) are the mesh steps along the three reciprocal lattice vectors and the prefactor \(\alpha\) is set by ADAPTIVE_FACTOR.
EPSILONis not used in this case, and no manual width convergence test is needed.
EPSILON-tag : Smearing width in units of Kayser (cm-1)
- Default:
10.0
- Type:
Double
- Description:
This variable is neglected when
ISMEAR = -1orISMEAR = 2.
BCONNECT-tag = 0 | 1 | 2
0
Phonon band is saved without change (sorted in order of energy)1
Phonon band is connected by using the similarity of eigenvectorsand the continuity of frequencies.2
Same asBCONNECT=1. In addition, information about the connectivity issaved asPREFIX.connection(harmonic bands only).
- Default:
0
- Type:
Integer
- Description:
Between neighboring k points, each band is connected to the partner that combines a large eigenvector overlap (summed over degenerate modes) with a frequency close to the value extrapolated along the band. At a break of the k path (a segment that does not start where the previous one ends), the bands are connected by frequency only. The connection is also applied to the
PREFIX.scph_bandsandPREFIX.qha_bandsfiles. The eigenvector-based approach follows the algorithm described here.
NBANDS-tag : Number of phonon branches to be written in output files
- Default:
\(3N\), where \(N\) is the number of atoms in the primitive cell
- Type:
Integer
- Description:
When
NBANDSis given, only the lowestNBANDSphonon branches are written in the frequency output files, such asPREFIX.bands and the eigenvalue files created with PRINTEVAL.
CLASSICAL-tag = 0 | 1
0
Use quantum statistics (default)
1
Use classical statistics
- Default:
0
- Type:
Integer
- Description:
When
CLASSICAL = 1, all thermodynamic functions including the occupation function, heat capacity, and mean square displacements are calculated using the classical formulae. This option may be useful when comparing the lattice dynamics and molecular dynamics results.
Comparison of quantum and classical values# Function
Quantum (
CLASSICAL = 0)Classical (
CLASSICAL = 1)Occupation number
\(\displaystyle n_\mathrm{B}=\frac{1}{\exp(\beta\hbar\omega) - 1}\)
\(\displaystyle n_\mathrm{C}=\frac{1}{\beta\hbar\omega}\)
Mode specific heat
\(\displaystyle c_{q} = k_{\mathrm{B}}\left[\frac{\beta\hbar\omega_q}{2}\mathrm{csch}\bigg({\frac{\beta\hbar\omega_q}{2}}\bigg)\right]^2\)
\(\displaystyle c_{q} = k_{\mathrm{B}}\)
MSD of normal mode \(\braket{Q^{*}_qQ_q}\)
\(\displaystyle \frac{\hbar (1 + n_{\mathrm{B}})}{2\omega_q}\)
\(\displaystyle \frac{1}{\beta\omega_{q}^{2}}\)
TREVSYM-tag = 0 | 1
- Default:
1
- Type:
Integer
- Description:
Uses time-reversal symmetry (k and -k are equivalent) in addition to the spatial symmetry when reducing the uniform k-point meshes (DOS/transport, four-phonon and SCPH/QHA meshes). It reduces the irreducible k-point count only in non-centrosymmetric crystals, by up to a factor of two. It is ignored for magnetic systems whose force-constant file was generated without time-reversal symmetry (
TREVSYM = 0in alm).TREVSYM = 0restores the behavior of version 1.x, which used the spatial symmetry only.Changing
TREVSYMchanges the irreducible k-point set, so restart files written with the other setting are rejected; use a newPREFIXor setTREVSYM = 0to continue an old run. For non-centrosymmetric crystals the computed linewidths at k and -k are not numerically identical with the adaptive (ISMEAR = 2) and tetrahedron (ISMEAR = -1) methods, so the thermal conductivity can shift slightly (within the k-mesh convergence error); fixed Gaussian smearing (ISMEAR = 1) gives identical results.
TRISYM-tag : Flag to use symmetry operations to reduce the number of triples of \(k\) points for self-energy calculations
0
Symmetry will not be used
1
Use symmetry to reduce triples of \(k\) points
- Default:
1
- Type:
Integer
- Description:
This variable is used only when
MODE = kappa. It applies to the linewidth calculation and to the collision operator of the iterative, variational and direct BTE solvers (SOLVER = IBTE,VBTE,DBTE).Note
TRISYM = 1reduces the computational cost. The linewidths stored inPREFIX.kappa.h5 andPREFIX.result are averaged over degenerate modes, so they do not depend on this choice. With the tetrahedron method (ISMEAR = -1), the weights of the reduced triplets are averaged over each symmetry-equivalent group, so the result agrees with theTRISYM = 0one up to a small residual. With the adaptive smearing (ISMEAR = 2), whose widths depend on mode-resolved group velocities,TRISYMis ignored for the linewidth calculation and the full k mesh is always used.The linear tetrahedron method itself is not invariant under the point-group operations of the crystal: the linewidth computed at an irreducible k point depends slightly on which member of its star represents it. The difference vanishes as the k mesh is refined.
FILE_FORMAT-tag : Format of the restart/state files
h5
Unified crash-safe HDF5 files (
PREFIX.kappa.h5 forMODE = kappa;PREFIX.scph.h5 /PREFIX.qha.h5 forMODE = SCPH/QHA)text
Legacy text files (
PREFIX.result,PREFIX.scph_dymat, etc.)
- Default:
h5
- Type:
String
- Description:
The text format is deprecated. Human-readable outputs (
PREFIX.kl,PREFIX.scph_thermo,PREFIX.scph_dfc2,PREFIX.V0, …) are written in both modes. The eigenvalue/eigenvector outputs of PRINTEVAL and PRINTEVEC also follow this tag:h5writes the schema-stamped *.eval.h5 / *.evec.h5 files,textthe plain-text variants.
FC2_TEMPERATURE-tag : Temperature (K) at which the renormalized FC2 is loaded
- Default:
None
- Type:
Double
- Description:
When
FCSFILEorFC2FILEpoints at aPREFIX.scph.h5 /PREFIX.qha.h5 file produced by an SCPH/QHA run, the effective (temperature-renormalized) harmonic force constants at this temperature are loaded directly — nodfc2round-trip is needed. Note that this self-contained route folds the harmonic FC2 onto theKMESH_INTERPOLATEcell; to combine the correction with a harmonic FC2 of a larger supercell, use DFC2FILE instead. The temperature must be one of the values on the file’s temperature grid. The stored FC2 must be read with theNONANALYTICof the run that wrote it (2 and 3 may read each other’s files, aNONANALYTIC = 0file may be read with a nonanalytic term with a warning; other combinations stop with an error): the nonanalytic term is then added fromBORNINFOas usual, and the frequencies of the SCPH/QHA run are reproduced exactly at the \(q\) points of itsKMESH_INTERPOLATEmesh (see Force constants and corrections with NONANALYTIC > 0). InMODE = kappa, this tag also switchesPREFIX.kappa.h5 to its temperature-resolved layout so that runs at different basis temperatures accumulate into one file (setTMIN = TMAX = FC2_TEMPERATUREper run). Temperatures whose SCPH iteration or structural optimization did not converge are refused unless ALLOW_UNCONVERGED is set.
DFC2FILE-tag : SCPH/QHA state file supplying the anharmonic FC2 correction
- Default:
None
- Type:
String
- Description:
Adds the anharmonic FC2 correction \(\Delta\Phi_{ij}\) stored in a
PREFIX.scph.h5 /PREFIX.qha.h5 file (at FC2_TEMPERATURE, which must be given) onto the harmonic FC2 provided byFCSFILEorFC2FILE. This is the native form of the legacydfc2workflow: the harmonic FC2 may come from a larger supercell than the SCPH cell, which is justified because the anharmonic correction is usually shorter ranged than the harmonic force constants. The two supercells must be commensurate tilings of the same primitive cell. The convergence flags of the state file are enforced as for a directFC2_TEMPERATUREread.The correction may break the translations of the primitive cell of the harmonic FC2 file, as a cell-doubling distortion relaxed with
RELAX_STR > 0in a supercell does; it is kept atom by atom. The&cellof the present run must then be that SCPH cell (or a cell whose copies inside the SCPH cell carry identical corrections); the run stops when it finds copies whose corrections differ.
DFC2FILEnever replaces the harmonic FC2 — it is purely additive. The base FC2 follows the usual precedence (FC2FILEif given, otherwiseFCSFILE), andFC2_TEMPERATURErefers toDFC2FILEwhen it is present. The resulting combinations are:
Input combination
Resulting FC2
FCSFILEonlybase from
FCSFILE
FCSFILE+FC2FILEbase from
FC2FILE(FC3/FC4 fromFCSFILE)either of the above +
DFC2FILE+FC2_TEMPERATUREsame base + \(\Delta\Phi(T)\) from
DFC2FILE
FC2FILE=PREFIX.scph.h5 +FC2_TEMPERATURE, noDFC2FILEtotal (base + \(\Delta\Phi(T)\)) read directly from the state file
FC2FILE=PREFIX.scph.h5, noFC2_TEMPERATURE, noDFC2FILEbase FC2 of the state file only; the renormalized FC2 is not used
The correction is relative to the full harmonic dynamical matrix of the SCPH/QHA run, so the present run must use the same
NONANALYTIC(2 and 3 are interchangeable) and the sameBORNINFO. A file of aNONANALYTIC = 0run may be used withNONANALYTIC > 0with a warning: the correction then lacks the long-range term, which is added to the harmonic part only (an approximation). See Force constants and corrections with NONANALYTIC > 0.Note that the crystal structure is still taken from
FCSFILE/FC2FILE;DFC2FILEcontributes force-constant corrections only. Giving a state file as the harmonic FC2 source together withDFC2FILEuses only its coarse-mesh-folded base FC2 and prints a warning, since that is rarely intended.
RELAXED_STRUCTURE-tag = 0 | 1
- Default:
0
- Type:
Integer
- Description:
Run on the crystal structure that an earlier SCPH or QHA calculation relaxed, instead of the original one.
When
RELAX_STR > 0, an SCPH/QHA run finds a new equilibrium structure at every temperature: the cell is strained and the atoms shift. It stores those structures in itsPREFIX.scph.h5 /PREFIX.qha.h5 file. SettingRELAXED_STRUCTURE = 1makes the present run adopt the one at FC2_TEMPERATURE, which must also be given. The structure is read fromDFC2FILEif present, otherwise fromFC2FILEorFCSFILE.Three things then follow the relaxed structure:
The cell itself — its volume, its reciprocal lattice and its symmetry. This matters because thermal conductivity is inversely proportional to the cell volume, group velocities are Cartesian derivatives with respect to the physical (deformed) wave vector, and a relaxation usually lowers the symmetry, which changes the set of irreducible q points.
The cubic force constants, which the deformation changes just as it changes the harmonic ones. They are corrected using the quartic force constants, so
FC4FILE— or anFCSFILEcontaining the quartic order — must be available even for a three-phonon calculation. This is the same FC4 the SCPH/QHA run itself needed, and the run checks that it is indeed the same one. The quartic force constants themselves are used as they are, as in the SCP calculation.The STRAIN_FC5 setting of the relaxation. A structure relaxed with STRAIN_FC5 = 1 is followed with the same model, taken from the state file without any further input: the quintic force constants are read with the others (the same ones; the run checks their fingerprint), the quartic force constants become \(\Phi_4 + \sum_{\mu\nu} u_{\mu\nu}\, \partial \Phi_4 / \partial u_{\mu\nu}\), and the cubic ones gain the cross term \(\sum_{\mu\nu} u_{\mu\nu}\, (\partial \Phi_4 / \partial u_{\mu\nu}) : u_0\) of that strain and the atomic shifts \(u_0\), in the channels of its STRAIN_FC5_CHANNELS. A calculation without cubic force constants, such as a phonon dispersion, does not read the quintic ones.
STRAIN_FC5andSTRAIN_FC5_CHANNELSneed not be given; if they are (in&relax), they must agree with the state file.The dynamical matrix itself is the one of the SCPH/QHA state. That run never moves its cell: its harmonic part, including the long-range dipole-dipole term, is built on the reference cell and the deformation enters only through the force constants. The present run therefore splits the geometry as follows (
relaxed_cell_convention = 2inPREFIX.kappa.h5):
Reference cell — everything that defines \(D(\boldsymbol{q})\) at a fractional q: the Ewald sums and the long-range force constants (
NONANALYTIC = 3), theNONANALYTIC = 1, 2terms, the direction of the non-analytic limit, and the choice of the uniform-mesh representatives (minimum \(|\boldsymbol{q}+\boldsymbol{G}|\)). The Born effective charges and the dielectric tensor are taken from the state file as the SCPH/QHA run processed them (acoustic sum rule,BORNSYMwith its symmetry operations), instead of processingBORNINFOagain with those of the relaxed cell. The frequencies and eigenvectors are thus those of the state at every q, not only on its coarse mesh.Relaxed cell — the physical geometry: the conversion of group velocities to Cartesian coordinates, the atomic positions entering the velocity operator, the cell volume, the symmetry operations, the band-path lengths and the tangent onto which
PRINTVELprojects, the boundary scattering (LEN_BOUNDARY), and the longitudinal projection of the DOS.Affected when
NONANALYTICis nonzero: thermal conductivity (RTA, IBTE, four-phonon,KAPPA_COHERENT,KAPPA_SPEC), bands, DOS, mean square displacements, thermodynamic functions, Grüneisen parameters,PRINTVEL, the dielectric function, mode effective charges, irreducible representations, normal-mode animations andMODE = selfenergy.PREFIX.kappa.h5 records, per temperature, which convention computed it; a run that would continue a temperature computed with another one stops, whateverRESTARTandRESTART_4PHsay — delete or rename the file. Results with and withoutRELAXED_STRUCTUREdescribe different crystals and are never mixed. (Text.resultfiles are never imported underRELAXED_STRUCTURE = 1.)Without this tag, a follow-up calculation uses the renormalized harmonic force constants of the relaxed structure together with the original cell and the original cubic force constants, which do not describe the same crystal.
A typical two-step use, thermal conductivity at 300 K:
&general MODE = kappa FCSFILE = si_anharm.h5 # original structure, FC2/FC3/FC4 DFC2FILE = si_scph.scph.h5 # from the RELAX_STR run FC2_TEMPERATURE = 300 RELAXED_STRUCTURE = 1 TMIN = 300; TMAX = 300 /The same tag works for
MODE = phonons, giving phonon dispersion, DOS, mean square displacements, thermodynamic functions and Grüneisen parameters on the relaxed structure.Please note:
Use the same TOLERANCE as the SCPH/QHA run. The symmetry of the relaxed structure is detected with it, and a different value may give a different space group. The run prints the space group the relaxation found next to the one it detects itself, so the two can be compared.
Born effective charges and the dielectric tensor are not adjusted to the relaxed structure, in the SCPH/QHA run and here alike, and the long-range term keeps the reference geometry (see above). For polar materials under a sizeable strain this is the largest remaining approximation.
The correction to the cubic force constants assumes force constants that satisfy the acoustic and rotational invariance conditions well (
ICONSTin alm); its accuracy is limited by how well they do.This tag cannot be combined with
RELAX_STR > 0in the same run, nor with NEWFCS.The band structure (
KPMODE = 1) is drawn on the \(k\) axis of the relaxed cell, whereasPREFIX.scph_bands of theRELAX_STR > 0run uses the reference cell’s axis. The frequencies agree; only the abscissa differs.
ALLOW_UNCONVERGED-tag = 0 | 1
- Default:
0
- Type:
Integer
- Description:
SCPH/QHA state files record, per temperature, whether the SCPH iteration and the structural optimization converged (
/convergenceinPREFIX.scph.h5 /PREFIX.qha.h5). By default, later calculations that consume the renormalized IFCs or structure —FC2_TEMPERATUREreads for kappa/DOS/band runs, andRESTART_SCPH/RESTART_QHA(whose postprocess produces DOS, bands, and thermodynamic functions) — refuse unconverged temperatures with an error. SetALLOW_UNCONVERGED = 1to use such data anyway (a warning is printed). When the structural optimization of an SCPH temperature fails, its row holds a copy of the last converged temperature (or the harmonic data if none converged yet), and so do that run’s DOS and band outputs; its thermodynamic functions are evaluated at its own temperature from those fallback frequencies./convergence/data_temperaturerecords the source temperature (NaN for harmonic), and the warning names it.
VERBOSITY-tag : Level of the standard output
- Default:
1
- Type:
Integer
- Description:
VERBOSITY = 0suppresses the echo of the input variables and the per-iteration log of the SCPH solver.VERBOSITY >= 2keeps the per-iteration SCPH log even inside the structural optimization loop (RELAX_STR != 0), where it is compacted by default.
“&scph”-field (Read only when MODE = SCPH)#
KMESH_INTERPOLATE-tag = k1, k2, k3
- Default:
None
- Type:
Array of integers
- Description:
In the iteration process of the SCPH equation, the interpolation is done using the \(k\) mesh defined by
KMESH_INTERPOLATE.
KMESH_SCPH-tag = k1, k2, k3
- Default:
None
- Type:
Array of integers
- Description:
This \(k\) mesh is used for the inner loop of the SCPH equation. Each value of
KMESH_SCPHmust be equal to or a multiple of the number ofKMESH_INTERPOLATEin the same direction.
SELF_OFFDIAG-tag = 0 | 1
0
Neglect the off-diagonal elements of the loop diagram in the SCPH calculation
1
Consider the off-diagonal elements of the loop diagram in the SCPH calculation
- Default:
1
- Type:
Integer
- Description:
SELF_OFFDIAG = 1is more accurate, but expensive.
TOL_SCPH-tag: Stopping criterion of the SCPH iteration
- Default:
1.0e-10
- Type:
Double
- Description:
The SCPH iteration stops when both \([\frac{1}{N_{q}}\sum_{q} (\Omega_{q}^{(i)}-\Omega_{q}^{(i-1)})^{2}]^{1/2}\) <
TOL_SCPHand \((\Omega_{q}^{(i)})^{2} \geq 0 \; (\forall q)\) are satisfied. Here, \(\Omega_{q}^{(i)}\) is the anharmonic phonon frequency in the \(i\)th iteration and \(q\) is the phonon modes at the irreducible momentum grid ofKMESH_INTERPOLATE.
MIXALPHA-tag: Mixing parameter used in the SCPH iteration
- Default:
0.1
- Type:
Double
IMIX-tag = 0 | 1
0
Simple linear mixing with the mixing parameter
MIXALPHA1
DIIS (Pulay) mixing
- Default:
1
- Type:
Integer
- Description:
Mixing algorithm used in the SCPH iteration. With
IMIX = 1, a few simple-mixing steps are performed first and the subsequent iterations are accelerated by the DIIS method; MIXALPHA is used as the underlying mixing parameter and must be in (0, 1] in this case.IMIX = 0restores the plain simple mixing.
MAXITER-tag: Maximum number of the SCPH iteration
- Default:
1000
- Type:
Integer
LOWER_TEMP-tag = 0 | 1
0
The SCPH iteration starts from
TMINand proceeds toTMAX. (Raise the temperature)1
The SCPH iteration starts from
TMAXand proceeds toTMIN. (Lower the temperature)
- Default:
1
- Type:
Integer
WARMSTART-tag = 0 | 1
0
SCPH iteration is initialized by harmonic frequencies and eigenvectors
1
SCPH iteration is initialized by the solution of the previous temperature
- Default:
1
- Type:
Integer
- Description:
WARMSTART = 1usually improves the convergence.
V4_REAL_SPACE-tag = 0 | 1 | 2
0
The quartic couplings are the reciprocal-space tensor V4
1
The quartic couplings are contracted over the real-space fourth-order IFCs
2
Both, compared in the log (the tensor is used); for testing
- Default:
0
- Type:
Integer
- Description:
The SCPH iteration contracts the quartic coupling with the displacement correlation of the dense mesh once per iteration, and the structural optimization contracts it with the displacement once per step. With
V4_REAL_SPACE = 0these use the tensor V4 between the irreducible points ofKMESH_INTERPOLATEand the points ofKMESH_SCPH, whose memory grows as the fourth power of the number of modes and whose construction is usually the most expensive part of the run. WithV4_REAL_SPACE = 1the same contractions are done over the fourth-order IFCs folded onto the cells ofKMESH_SCPH(exact for the loaded IFCs; the memory is that of the folded IFC list plus a few matrices of \(N_k \times n_s^2\) elements), and the tensor is not built. The contractions run on one MPI process with OpenMP threads; the other processes stay idle, so run with one process and many threads.BUBBLE = 4then uses the real-space quartic ladder.
IALGO-tag = 0 | 1
0
MPI parallelization for the \(k\) point
1
MPI parallelization for the phonon branch
- Default:
0
- Type:
Integer
- Description:
Use
IALGO = 1when the primitive cell contains many atoms and the number of \(k\) points is small.
RESTART_SCPH-tag = 0 | 1
0
Perform a SCPH calculation from scratch
1
Skip a SCPH iteration by loading a precalculated result
- Default:
1 if the file
PREFIX.scph.h5(or the legacyPREFIX.scph_dymat) exists in the working directory; 0 otherwise- Type:
Integer
BUBBLE-tag = 0 | 1 | 2 | 3 | 4
0
No bubble correction to the dynamical matrix
1
Static correction: the real part of the bubble self-energy at \(\omega = 0\)
2
On-shell correction: the real part of the bubble self-energy at the SCPH frequency \(\omega = \Omega_{\boldsymbol{q}j}\)
3
Quasiparticle correction: the real part of the bubble self-energy at the solution of \(\omega^{2} = \Omega_{\boldsymbol{q}j}^{2} - 2\Omega_{\boldsymbol{q}j}\,\mathrm{Re}\,\Sigma^{\mathrm{B}}_{\boldsymbol{q}j}(\omega)\)
4
Curvature of the SCP free energy: static bubble with the quartic ladder resummed, at \(\Gamma\) of the cell, along a structural optimization (
RELAX_STR > 0)
- Default:
0
- Type:
Integer
- Description:
Adds the bubble (three-phonon) self-energy correction on top of the converged SCPH dynamical matrix. For every irreducible point of
KMESH_INTERPOLATEand branch \(j\) the real part of the bubble self-energy is evaluated with the SCPH phonons (frequencies \(\Omega_{\boldsymbol{q}j}\) and eigenvectors) and summed over the \(q\) mesh given byKMESH_BUBBLE;EPSILONis the imaginary part added to the frequency. The corrected frequencies \(\omega^{2}_{\boldsymbol{q}j} = \Omega_{\boldsymbol{q}j}^{2} - 2\Omega_{\boldsymbol{q}j}\,\mathrm{Re}\,\Sigma^{\mathrm{B}}_{\boldsymbol{q}j}\) (averaged over degenerate branches) define a new dynamical matrix, which is Fourier interpolated like the SCPH one and written asPREFIX.scph+bubble(0)_dfc2,PREFIX.scph+bubble(w)_dfc2orPREFIX.scph+bubble(wQP)_dfc2forBUBBLE = 1, 2, 3; the DOS, MSD and thermodynamic outputs get the same suffix.With
BUBBLE = 3the equation above is solved for every mode in two steps. The function \(F(\omega) = \omega^{2} - \Omega^{2} + 2\Omega\,\mathrm{Re}\,\Sigma^{\mathrm{B}}(\omega)\) is first scanned on a coarse grid from 0 to \(\Omega + \max(50\ \mathrm{cm}^{-1}, \Omega/2)\), so that strongly softened modes such as soft polar modes, whose root can lie far below \(\Omega\), are found as well as stiffened ones. The coarse step isEPSILON/4, but at most \(\max(0.5\ \mathrm{cm}^{-1}, \text{range}/400)\) and at least 0.1 cm-1: the Lorentzian-broadened self-energy does not vary on scales much shorter thanEPSILON. The coarse intervals with a sign change of \(F\), and the two intervals around a coarse local extremum of \(F\) whose parabolic interpolation crosses zero (a pair of roots within one step), are then rescanned on a 0.1 cm-1 grid. In each fine interval with an upward crossing (\(F' > 0\)) the self-energy is taken as linear and the resulting quadratic equation is solved, so that the root and the frequency of the corrected dynamical matrix coincide. Downward crossings (\(F' < 0\), negative weight) are not used. A root at \(\omega = 0\) (\(F(0) = 0\), \(F > 0\) above it) is accepted. If several roots are found, the one with the largest weight \(Z = 2\omega / F'(\omega) = [1 + (\Omega/\omega)\,\partial_{\omega}\mathrm{Re}\,\Sigma^{\mathrm{B}}]^{-1}\) is used by convention (it is the residue of the pole when \(\mathrm{Im}\,\Sigma\) is neglected), and all roots are listed in a warning. If there is no root in the scanned range (for example when the bubble makes the mode unstable, \(F(0) > 0\)), the on-shell value \(\mathrm{Re}\,\Sigma^{\mathrm{B}}(\Omega)\) ofBUBBLE = 2is used and a warning naming the branch is printed.BUBBLE = 3costs at most two self-energy sums per mode, one at a few hundred frequencies (more for a smallEPSILON) and one at about ten frequencies per refined interval.With
RELAX_STR > 0the correction is evaluated on the structure relaxed at each temperature: the SCPH phonons already belong to it, and the cubic force constants are deformed to it as \(\Phi_3 + \Phi_4 : d\) (as with RELAXED_STRUCTURE). Temperatures whose SCPH iteration or structural optimization did not converge keep the SCPH result. The structure is the one the optimizer accepted, which differs from that of the final SCPH solution withinCOORD_CONV_TOL/CELL_CONV_TOL. A restart (RESTART_SCPH = 1) takes the structures fromPREFIX.scph.h5; the legacy text restart files do not carry them and are refused for this combination. In a phase with large symmetry-breaking displacements the one-loop correction can overshoot and even turn a stable mode imaginary; it is a frequency correction, not a stability test.
BUBBLE = 4answers that stability question instead. At every temperature whose structural optimization converges, it computes the derivative of the SCP force with respect to the \(\Gamma\) displacements: the SCPH curvature plus the response of the phonon occupations, i.e. the static bubble with the quartic ladder resummed (Masuki et al., Phys. Rev. B 106, 224104 (2022), Appendix B). The self-consistent response equation is solved by GMRES to the relative residualBUBBLE_TOL; the response is not symmetrized, so directions that break the symmetry of the structure are included. When this force Jacobian is symmetric, it is the curvature of the SCP free energy, and the frequencies \(\mathrm{sign}(\lambda)\sqrt{|\lambda|}\) of its eigenvalues \(\lambda\) are printed, with the SCPH ones for comparison, and written toPREFIX.scph_hessian; a negative value marks a direction in which the structure is not a minimum of the free energy. Each such direction is also written toPREFIX.scph_hessian_displace as a&displaceand a&strainfield of the structure moved 0.05 bohr along it, labeled with the space group of the displaced structure, as a start for a relaxation in the lower symmetry. A temperature is skipped, with the reason, when its final SCPH iteration repaired an eigenvalue, a frequency vanishes, the translations mix with optical modes, the response equation does not converge, or the Jacobian is not symmetric. With a cell (RELAX_STR = 2, 4) the curvature also covers the six strain components, and the elastic curvature of the free energy plus \(pV\) with respect to the strain of the reference cell (Voigt notation, GPa, with clamped and with relaxed atoms; the phonon occupations respond in both) is printed and written toPREFIX.scph_hessian. The ordinary SCPH outputs are written as usual; the curvature is static, so no DOS or thermodynamic output is derived from it. The present version needsRELAX_STR > 0,KMESH_SCPH = KMESH_INTERPOLATE(a supercell with1 1 1, or a k-mesh, on which the curvature is also computed for the modulations at the other irreducible \(\boldsymbol{Q}\) of the mesh,PREFIX.scph_hessian_q) andNONANALYTIC = 0, and cannot be combined withRESTART_SCPH; an existing state file does not switch such a run to a restart.
BUBBLE_TOL-tag : Relative residual of the response equation of
BUBBLE = 4
- Default:
1.0e-8
- Type:
Double
KMESH_BUBBLE-tag = k1, k2, k3
- Default:
KMESH_SCPH- Type:
Array of integers
- Description:
\(q\) mesh over which the bubble self-energy of
BUBBLE > 0is summed. The SCPH phonons are interpolated onto this mesh, so it can be denser thanKMESH_SCPHto converge the bubble correction without changing the SCPH iteration. Each value must be equal to or a multiple of the number ofKMESH_INTERPOLATEin the same direction.
CV_ANHARM-tag = 0 | 1
0
Report the QHA-like heat capacity only
1
Also report the anharmonic correction to \(C_{v}\)
- Default:
0
- Type:
Integer
- Description:
With
CV_ANHARM = 1the anharmonic correction to the constant-volume heat capacity that originates from the temperature dependence of the SCPH frequencies is computed, i.e. the term containing \(\partial \Omega_{\boldsymbol{q}j} / \partial T\), which is evaluated by a central finite difference of the SCPH frequencies on the temperature grid defined byTMIN,TMAXandDT. Since the central difference needs both neighboring temperatures, the correction is reported as zero atTMINandTMAX; at least three temperature points and a \(k\) mesh (KPMODE = 2) are therefore required. The accuracy of the correction depends onDTbecause only the adjacent temperature points enter the derivative; for a more reliable estimate it is recommended to fit the entropy as a function of temperature by a polynomial and differentiate the fitted curve instead. The value is written toPREFIX.scph_thermoin the extra columnCv (anharm correction) [in kB unit], which follows theCvcolumn.
RELAX_STR-tag = 0 | 1 | 2 | 3 | 4
0
Don’t relax the crystal structure (not supported when
MODE = QHA).1
Relax atomic positions.
2
Relax both atomic positions and the shape of the unit cell.
3
Lowest-order perturbation theory (not supported when
MODE = SCPH).4
Relax atomic positions with the unit cell held at the strain given in the
&strainfield.
RELAX_STR = 4differs fromRELAX_STR = 1only in where the cell sits: both optimize the internal coordinates alone, butRELAX_STR = 1works at the undeformed reference cell, whereasRELAX_STR = 4holds the cell at the prescribed strain and therefore requires the elastic constants and the strain-IFC coupling (STRAINFILEorSTRAIN_IFC_DIR), exactly asRELAX_STR = 2does. The strain given in&strainmust be symmetric.This mode gives the internally relaxed free energy at a prescribed strain, \(\bar{F}(\epsilon, T) = \min_{q} F(\epsilon, q, T)\), which is written to the
.scph_thermo/.qha_thermofile (thePhi0column is already included inF_total). Finite differences of \(\bar{F}\) with respect to the strain give the isothermal elastic constants at finite temperature, \(C_{ij}(T) = V^{-1} \partial^2 \bar{F} / \partial \epsilon_i \partial \epsilon_j\). SetSTAT_PRESSURE = 0for this purpose: a nonzero value adds a \(pV\) term, so the quantity being differentiated is then no longer \(\bar{F}\).The energy is a function of the Green-Lagrange strain \(\eta = \mathrm{sym}\,u + \tfrac{1}{2} u u^{T}\), which is built assuming that the displacement gradient \(u\) given in
&strainis symmetric; an asymmetric \(u\) is rejected. Note that a symmetric \(u\) need not preserve the crystal symmetry, and thatSET_INIT_STR = 3compares against the space group of the undeformed reference cell, so it will not trigger under a symmetry-lowering strain.QHA_SCHEMEmust be 0 in this mode.
- Default:
0
- Type:
Integer
“&qha”-field (Read only when MODE = QHA)#
KMESH_INTERPOLATE-tag = k1, k2, k3
- Default:
None
- Type:
Array of integers
- Description:
In the structural optimization based on quasiharmonic approximation (QHA), the interpolation is done using the \(k\) mesh defined by
KMESH_INTERPOLATE.
KMESH_QHA-tag = k1, k2, k3
- Default:
None
- Type:
Array of integers
- Description:
This \(k\) mesh is used for the QHA-based structural optimization. Each value of
KMESH_QHAmust be equal to or a multiple of the number ofKMESH_INTERPOLATEin the same direction.Imaginary modes on this mesh are excluded from the vibrational free energy but not from the stress and forces. When they appear, a WARNING is printed once per temperature with their number and the most negative frequency: the free energy (absolute values and differences) and the stress/forces at that temperature are then unreliable.
The free energy in
PREFIX.qha_thermo (andPREFIX.scph_thermo) is evaluated on the&kpointmesh, while the structure is optimized for the free energy onKMESH_QHA(KMESH_SCPH). Use the same mesh for both when the reported free energy should be the minimized one; a WARNING is printed when they differ withRELAX_STR> 0.
RELAX_STR-tag = 1 | 2 | 3 | 4
1
Relax atomic positions.
2
Relax both atomic positions and the shape of the unit cell.
3
Lowest-order perturbation theory.
4
Relax atomic positions at the fixed strain of
&strain.
- Default:
1
- Type:
Integer
- Description:
RELAX_STR = 0is not supported whenMODE = QHA.
LOWER_TEMP-tag = 0 | 1
0
The structural optimization starts from
TMINand proceeds toTMAX. (Raise the temperature)1
The structural optimization starts from
TMAXand proceeds toTMIN. (Lower the temperature)
- Default:
1
- Type:
Integer
QHA_SCHEME-tag = 0 | 1 | 2
0
Full optimization within QHA.
1
zero-static internal stress approximation (ZSISA).
2
volumetric ZSISA (v-ZSISA).
- Default:
0
- Type:
Integer
- Description:
This option is used only when
mode = QHAandRELAX_STR = 2. It must be 0 whenRELAX_STR = 4.
RESTART_QHA-tag = 0 | 1
0
Perform a QHA calculation from scratch
1
Skip the QHA optimization by loading a precalculated result
- Default:
1 if the file
PREFIX.qha.h5, or the pair of the legacy filesPREFIX.renorm_harm_dymatandPREFIX.V0, exists in the working directory; 0 otherwise- Type:
Integer
- Description:
With the default
FILE_FORMAT = h5, the restart data are read preferentially from the unified state filePREFIX.qha.h5. When only the legacy text files are found, they are loaded instead and migrated intoPREFIX.qha.h5 once. Temperatures whose structural optimization did not converge are refused unless ALLOW_UNCONVERGED is set.
“&relax”-field (Read only when RELAX_STR != 0)#
RELAX_ALGO-tag = 1 | 2 | 3
1
Steepest descent (not recommended)
2
Newton-like method
3
BFGS + GDIIS
- Default:
2
- Type:
Integer
- Description:
Algorithm to update the crystal structure in structural optimization. This option is used only when
RELAX_STR = 1, 2, 4.RELAX_ALGO = 1works properly only when the unit cell is fixed (RELAX_STR = 1).
ALPHA_STDECENT-tag: Coefficient of steepest descent in structural optimization
- Default:
1.0e4
- Type:
Double
- Description:
\(\alpha\) coefficient in structural optimization with the steepest-descent algorithm. The unit is [\(m_e a_B^2/(2\text{Ry})\)]. This option is used only when
RELAX_ALGO = 1.
GDIIS_PLAIN-tag = 0 | 1
0
Use the controlled GDIIS (with step-acceptance tests)
1
Use the plain GDIIS (without step-acceptance tests)
- Default:
0
- Type:
Integer
- Description:
This option is used only when
RELAX_ALGO = 3. By default, each GDIIS step is subjected to the step-acceptance criteria of the controlled GDIIS method by Farkas and Schlegel (step-length cap, coefficient/extrapolation cap, and near-singularity rejection with error-vector rescaling), which makes the optimization more robust. SetGDIIS_PLAIN = 1to switch back to the regular GDIIS update.
MAX_STR_ITER-tag: Maximum number of structure updates.
- Default:
100
- Type:
Integer
- Description:
This option is used only when
RELAX_STR = 1, 2, 4.
ADD_HESS_DIAG-tag: Correction to the estimated Hessian of free energy in units of Kayser (cm-1)
- Default:
100.0
- Type:
Double
- Description:
The squared
ADD_HESS_DIAGis added to the diagonal components of estimated Hessians, which is used to update crystal structures in structural optimization.ADD_HESS_DIAGmakes the calculation more robust in the presence of soft modes near the structural phase transition, but setting large values will make the convergence slower. This option is used only whenRELAX_ALGO = 2.
BUBBLE_HESS-tag = 0 | 1
- Default:
0
- Type:
Integer
- Description:
BUBBLE_HESS = 1takes the atomic-coordinate block of the Hessian of the structural optimizer from the curvature of the SCP free energy (BUBBLE = 4) at the current structure, instead of the SCP \(\Gamma\) matrix plusADD_HESS_DIAG. Its negative eigenvalues are replaced by their absolute values and all are bounded below by (1 cm-1)2, so that the step leaves a saddle point downhill. The curvature is computed whenever the optimizer reads a Hessian: at every step forRELAX_ALGO = 2, and when the BFGS history is initialized forRELAX_ALGO = 3. When it is not available at a step (seeBUBBLE = 4), the default Hessian is used and the log says why. WithRELAX_STR = 2the cell block and the coupling between coordinates and strain come from the same curvature (RELAX_ALGO = 2then solves the coupled Newton equation, each part scaled by itsMIXBETA); with a fixed cell only the coordinate block is used. The phonon response in this Hessian is restricted to the symmetry the SCPH equation is solved in (that of the initial structure), so that it is the Jacobian of the forces the optimizer sees. RequiresMODE = SCPH,BUBBLE = 4andRELAX_ALGO = 2or3.
COORD_CONV_TOL-tag: Threshold of convergence for atomic positions in structural optimization.
- Default:
1.0e-5
- Type:
Double
- Description:
The value is interpreted in units of Bohr. This option is used only when
RELAX_STR = 1, 2, 4.
GRADIENT_CONV_TOL-tag: Threshold of convergence for the residual force in structural optimization.
- Default:
0.0 (disabled)
- Type:
Double
- Description:
When
GRADIENT_CONV_TOL > 0, the structural optimization at each temperature is declared converged only if the norm of the residual force acting on the internal coordinates is smaller than this value, in addition to the step-size criterion COORD_CONV_TOL. This guards against false convergence at a non-stationary point, where the step can be small although the gradient is not, which may happen with the GDIIS optimizer (RELAX_ALGO = 3).
MIXBETA_COORD-tag: Mixing coefficient for atomic positions in structure updates.
- Default:
0.5
- Type:
Double
- Description:
This option is used only when
RELAX_ALGO = 2(RELAX_STR = 1, 2, 4).
CELL_CONV_TOL-tag: Threshold of convergence for displacement gradient tensor \(u_{\mu \nu}\) in structural optimization.
- Default:
1.0e-5
- Type:
Double
- Description:
This option is used only when
RELAX_STR = 2.
CELL_GRADIENT_CONV_TOL-tag: Threshold of convergence for the residual cell gradient (stress) in structural optimization.
- Default:
0.0 (disabled)
- Type:
Double
- Description:
When
CELL_GRADIENT_CONV_TOL > 0and the cell shape is relaxed (RELAX_STR = 2), convergence additionally requires the norm of the gradient of the free energy with respect to the strain tensor (including the term due to STAT_PRESSURE) to be smaller than this value. Its units differ from those of GRADIENT_CONV_TOL, hence the separate threshold.
MIXBETA_CELL-tag: Mixing coefficient for displacement gradient tensor \(u_{\mu \nu}\) in structure updates.
- Default:
0.5
- Type:
Double
- Description:
This option is used only when
RELAX_ALGO = 2andRELAX_STR = 2.
SET_INIT_STR-tag = 1 | 2 | 3
1
Set initial structure from the input file at each temperature.
2
Start from the crystal structure of the previous temperature.
3
Start from the crystal structure of the previous temperature in low-symmetry phase.
- Default:
1
- Type:
Integer
- Description:
This option specifies how to set the initial structure of structural optimization at different temperatures. This option is used when
RELAX_STR = 1, 2, 4. In all options, the initial structure at the initial temperature is set from the input file. The initial structure of the input file is read from the&strainand&displacefield. WhenSET_INIT_STR = 3, the initial displacement from the input file is used again whenever the crystal structure relaxed back to the high-symmetry phase at the previous temperature. The structure is judged to be in the high-symmetry phase when spglib finds the space group of the undistorted reference cell for it, with the symmetry tolerance of the TOLERANCE tag. This is useful in cooling calculations because a small displacement from the high-symmetry structure is required to induce spontaneous symmetry breaking. (The formerCOOLING_U0_INDEXandCOOLING_U0_THRtags are deprecated and ignored.)
STAT_PRESSURE-tag: Hydrostatic pressure in GPa.
- Default:
0.0
- Type:
Double
STRAIN_COUPLING-tag = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 10 | 11 | 14 | 15 | 20 | 21 | 24 | 25
- Default:
7
- Type:
Integer
- Description:
This option selects where the elastic constants and the strain couplings of the cell relaxation come from. It is used only when
RELAX_STR = 2, 3, 4and replaces the four tagsELASTIC_CONST,RENORM_2TO1ST,RENORM_34TO1STandRENORM_3TO2NDof earlier versions (still accepted, see below). Three ingredients are involved; each is either read from the strain-coupling file (STRAINFILE, or the legacy text files inSTRAIN_IFC_DIR) or obtained without DFT input. The units digit is the sum of the values of the ingredients read from the file:
Value
Ingredient
Read from the file
Not read from the file (bit clear)
1
Elastic constants \(C^{(2)}_{\mu_1 \nu_1, \mu_2 \nu_2}\), \(C^{(3)}_{\mu_1 \nu_1, \mu_2 \nu_2, \mu_3 \nu_3}\)
/Elastic(elastic_constants.in)computed from the harmonic and cubic IFCs (see the notes below)
2
Strain–force coupling \(\partial \Phi_{\mu}(0\alpha) / \partial u_{\mu_1 \nu_1}\)
/StrainForce(strain_force.in)set to zero (valid only when it vanishes by symmetry)
4
Strain–harmonic-IFC coupling \(\partial \Phi_{\mu_1 \mu_2}(0\alpha_1, R \alpha_2) / \partial u_{\mu \nu}\)
/StrainHarmonic(strain_harmonic.in)computed from the cubic IFCs
Every combination therefore has a value:
STRAIN_COUPLING\(C^{(2)}, C^{(3)}\)
strain–force
strain–harmonic
typical situation
0
IFCs
zero
IFCs
high-symmetry crystal, no strained-cell DFT at all
1
file
zero
IFCs
high-symmetry crystal, elastic constants from elsewhere
2
IFCs
file
IFCs
strainifc.py collect --coupling forceonly3
file
file
IFCs
elastic.py fitonly (it writes both groups)4
IFCs
zero
file
high-symmetry crystal,
strainifc.py --coupling harmoniconly5
file
zero
file
high-symmetry crystal,
/Elasticand/StrainHarmoniconly6
IFCs
file
file
strainifc.pyforce + harmonic, elastic constants from the IFCs7 (default)
file
file
file
elastic.py fit+strainifc.py collect10, 11, 14, 15
as 0, 1, 4, 5
harmonic IFCs
as 0, 1, 4, 5
expert, see the note on the tens digit
20, 21, 24, 25
as 0, 1, 4, 5
harmonic IFCs, plus \(\partial^2 \Phi_{\mu}(0\alpha)/\partial u^2\), \(\partial^3 \Phi_{\mu}(0\alpha)/\partial u^3\) from the cubic and quartic IFCs
as 0, 1, 4, 5
expert, see the note on the tens digit
The second strain derivative of the harmonic IFCs and the first strain derivative of the cubic IFCs are always taken from the quartic IFCs. The log echoes the resolved source of every ingredient.
strainfile.py showprints the values a container supports.Projection of the IFC-derived strain–harmonic-IFC couplings. The strain derivatives of the harmonic IFCs computed from the cubic IFCs (bit 4 clear) and from the quartic IFCs take the positions of the other atoms relative to the first atom of each cluster. In a finite supercell with equidistant images, the resulting real-space set is neither symmetric under exchange of its two atoms nor translation-invariant. anphon therefore applies a chosen correction in real space, before the Fourier transform, for every strain component:
The set is averaged with the set anchored on the second atom.
The minimal-norm correction that is symmetric over the set’s own atom pairs is added, so that the acoustic sum rule holds for every atom and Cartesian block, including the shear components.
The correction depends only on the derivative set, not on the phonon spectrum. It keeps the crystal symmetry provided the input IFCs, and hence the set’s atom pairs, are symmetric. The log prints its relative size (
max|delta| / max|dPhi|; about \(10^{-3}\) for SrTiO3 on a 2×2×2 supercell). A warning is printed if the sum rule of the corrected set is violated by more than \(10^{-8}\) relative. Only these strain contributions are corrected. The renormalized dynamical matrix satisfies the sum rule at \(\Gamma\) to round-off only when the other contributions (harmonic IFCs, SCPH correction, displacement terms) do so as well. In the SrTiO3 tests, the acoustic frequencies are then about \(10^{-5}\) cm-1.Strain–force coupling set to zero (bit 2 clear, one-digit values). This is exact only in crystals whose site symmetries forbid a strain–force coupling (every atom on a centrosymmetric site, e.g. rock salt, cubic perovskites; not diamond, whose sites lack inversion). anphon checks this with the harmonic IFCs, which carry the site symmetry, and prints a warning when the symmetry allows a nonzero coupling.
Tens digit (values 10–25). The strain–force coupling is computed from the harmonic IFCs (Appendix C of the original paper); with a tens digit of 2 its second and third strain derivatives are also computed, from the cubic and quartic IFCs. These relations hold only for rotationally invariant IFCs (
ICONST >= 2in alm) and are limited by the cutoff of the fitted model, so this route is not recommended; anphon prints a warning, and the result should be validated against a run with the coupling read from the file. The units digit must not contain 2 (the coupling cannot come from both sources).Strain–harmonic-IFC coupling from the file (bit 4). When the file covers only a subset of the strain components (weight sums 1 for the given components, 0 for the rest), the missing ones are generated from the given ones by the space-group operations; this requires that the entries of the rotation matrices of all operations are 0 or \(\pm 1\) in Cartesian coordinates, and the log says which completion is used.
Elastic constants from the IFCs (bit 1 clear). The clamped-ion second-order elastic constants are computed from the harmonic force constants via the Born long-wave method, and the third-order ones from the cubic force constants following Wallace’s formulation. The clamped-ion (not relaxed-ion) constants are used because the internal coordinates are optimized explicitly. The first-order coefficients (the residual stress of the reference structure) are not contained in the force constants and are still taken from
/Elastic/stressofSTRAINFILEor fromC1_array.inwhen present (set to zero otherwise). The accuracy is limited by the range and the rotational invariance of the fitted force constants; comparing the values printed in the log against DFT elastic constants (elastic.py fit --compare) is recommended. In polar crystals, the real-space sums entering the second-order elastic constants converge slowly with the supercell size because of the long-range dipole-dipole interaction. WhenNONANALYTIC = 3is set (withBORNINFO), the dipole-dipole contribution is separated and resummed analytically (with the macroscopic term excluded, giving the fixed-field response), which largely removes this supercell-size error; usingNONANALYTIC = 3together with the IFC route is therefore strongly recommended for polar materials. The third-order elastic constants remain short-range because the strain derivatives of the Born charges are not contained in the force constants.Elastic constants from the file (bit 1). The constants are generated from DFT calculations of strained cells with the
tools/elastic.pyscript (see this page) and read from the/Elasticgroup of theSTRAINFILEcontainer or, on the legacy route, fromelastic_constants.in(andC1_array.in). The text files hold the constants in GPa when their section labels carry the unit token (SOEC GPa,TOEC GPa,C1 GPa); anphon multiplies them by the volume of its primitive cell, so the same files serve any nested&cellof the same reference structure (the values are not transformed between Cartesian frames). Files without the unit token (the legacy layout) or with an explicitRytoken hold \(V C\) and \(V \sigma\) in Ry for one specific cell, which anphon cannot check: a warning is printed when such a file is used together with a user-defined&cell.
STRAIN_FC5-tag = 0 | 1
- Default:
0
- Type:
Integer
- Description:
STRAIN_FC5 = 1adds the first strain derivative of the quartic IFCs, computed from the quintic ones in the same way as \(\partial \Phi_3 / \partial u_{\mu\nu}\) is computed from the quartic ones (the strain leg on a partner atom, positions relative to the atom in the home cell):\[\Phi_4(u) = \Phi_4 + \sum_{\mu\nu} u_{\mu\nu} \frac{\partial \Phi_4}{\partial u_{\mu\nu}}, \quad \frac{\partial \Phi_4(\ldots)}{\partial u_{\mu\nu}} = \sum_{m} \Phi_5(\ldots, m\mu)\, r_m^{\nu}.\]It enters the SCP equation, the renormalization at the displaced structure \(q_0\) and the stress. This is the only use of the quintic IFCs: the expansion is truncated at the first strain derivative of \(\Phi_4\); higher strain derivatives (\(\partial^2 \Phi_3/\partial u^2\), \(\partial^3 \Phi_2/\partial u^3\)) and the quintic displacement potential \(\Phi_5 u^5\) are not included. At the relaxed structure (strain \(u_{\mu\nu}\), atomic shifts \(u_0\), \(d = u \cdot R + u_0\)) the anharmonic IFCs of the model are therefore
\[\Phi_4' = \Phi_4 + \delta\Phi_4, \quad \Phi_3' = \Phi_3 + \Phi_4 : d + \delta\Phi_4 : u_0, \quad \delta\Phi_4 = \sum_{\mu\nu} u_{\mu\nu} \frac{\partial \Phi_4}{\partial u_{\mu\nu}},\]with no \(\Phi_5 : u_0\) in \(\Phi_4'\) and no \(\Phi_5 : d\, d\) in \(\Phi_3'\). A follow-up run with RELAXED_STRUCTURE = 1 uses exactly these (for
STRAIN_FC5 = 0the same without \(\delta\Phi_4\)), so its three- and four-phonon calculations follow the relaxation’s setting.The quintic IFCs are read from
/ForceConstants/Order5of the HDF5 file of the quartic ones (FC4FILE, elseFCSFILE), which must therefore contain both orders from the same fit (same supercell). They must satisfy the acoustic sum rule, without which the strain derivative depends on the atom the positions are measured from; a warning is printed when the deviation exceeds \(10^{-6}\) of the largest \(|\Phi_5|\). Available forMODE = SCPHwithRELAX_STR = 2or4, not withBUBBLE > 0orBUBBLE_HESS = 1. The correction is evaluated on MPI rank 0 (in aRELAXED_STRUCTURE = 1follow-up, every rank reads the quintic IFCs). The setting and a fingerprint of the quintic IFCs are stored inPREFIX.scph.h5;RESTART_SCPHrefuses a state file written with a differentSTRAIN_FC5,STRAIN_FC5_CHANNELSor quintic IFCs (files without the record count asSTRAIN_FC5 = 0).
STRAIN_FC5_CHANNELS-tag = ALL | DIAG
- Default:
ALL
- Type:
String
- Description:
DIAGkeeps only the normal-strain channels \(u_{xx}, u_{yy}, u_{zz}\) ofSTRAIN_FC5and drops the six shear channels.
ELASTIC_CONST, RENORM_2TO1ST, RENORM_34TO1ST, RENORM_3TO2ND-tags (deprecated)
- Description:
The four tags replaced by
STRAIN_COUPLING. They are still accepted and override the individual switches (a warning names the equivalentSTRAIN_COUPLINGvalue); they will be removed in a later release.ELASTIC_CONST = 1, 2: elastic constants from the IFCs / the file (bit 1).RENORM_2TO1ST = 0, 1, 2: strain–force coupling zero / from the harmonic IFCs (tens digit) / from the file (bit 2).RENORM_34TO1ST = 0, 1: its higher strain derivatives zero / from the cubic and quartic IFCs (tens digit 2).RENORM_3TO2ND = 1, 2, 3: strain–harmonic-IFC coupling from the cubic IFCs / from the file (bit 4; the former distinction between all and a subset of the strain patterns is now detected from the file).
STRAINFILE-tag: The strain-coupling container.
- Default:
None
- Type:
String
- Description:
The HDF5 container (schema
alamode:strain_coupling) holding every input of the cell relaxation that anphon cannot compute from the force constants: the reference stress and the elastic constants (/Elastic, used with bit 1 ofSTRAIN_COUPLING; the stress also with bit 1 clear), the strain–force coupling (/StrainForce, bit 2) and the strain–harmonic-IFC coupling with the force constants of the strained supercells embedded (/StrainHarmonic, bit 4). It is produced with--strain-filebyelastic.py fit(/Elasticand/StrainForce, the latter from the same strained primitive cells) andstrainifc.py collect(/StrainHarmonic;--coupling forcefor runs withoutelastic.py), or from existing text files withstrainfile.py pack; see this page. anphon verifies the schema, the presence of the groups its settings need (a missing one is reported together with the command that adds it), the units, the reference structure against the&cellfield (a nested super- or sub-cell is accepted, the rows of/StrainForcebeing tiled or averaged accordingly), and every strained supercell against the supercell of the harmonic force constants.STRAINFILEandSTRAIN_IFC_DIRare mutually exclusive. The file is read on every MPI rank and must not be modified while anphon runs.
STRAIN_IFC_DIR-tag: Directory name of the inputs of strain-IFC couplings (legacy text files).
- Default:
None
- Type:
String
- Description:
The legacy alternative to
STRAINFILE(anphon prints a note when it is used;strainfile.py packconverts the directory into a container). The input files of the strain-IFC couplings (strain_force.infor bit 2 ofSTRAIN_COUPLING,strain_harmonic.inand the force-constant files it lists for bit 4) must be given in this directory, as well aselastic_constants.infor bit 1. Note thatC1_array.inis read from the working directory of anphon, not from this directory. See this page for the file formats and the tools that generate them. When the&cellfield selects a cell different from the one the strain-force calculations were done for (for instance an enlarged cell chosen to condense a zone-boundary instability),strain_force.inmust either carry the&reference_cellheader, so that its rows can be mapped onto the atoms of that cell, or already contain one row per atom of that cell in its order;elastic_constants.inandC1_array.inin GPa need no change.
“&cell”-field#
This field gives the unit cell used by anphon. It can be omitted when FCSFILE is an HDF5 file
(PREFIX.h5): the primitive cell defined in the alm calculation, which is stored in that file, is then used.
With an XML file (PREFIX.xml), the field is required.
When the field is given, it replaces the cell stored in FCSFILE.
The cell must be either the true primitive cell or a supercell of it, such as the conventional cell,
so that the supercell of the alm calculation consists of whole copies of it.
Otherwise anphon stops with an error.
The cell parameters are given as:
&cell
a
a11 a12 a13
a21 a22 a23
a31 a32 a33
/
The cell parameters are then given by \(\vec{a}_{1} = a \times (a_{11}, a_{12}, a_{13})\), \(\vec{a}_{2} = a \times (a_{21}, a_{22}, a_{23})\), and \(\vec{a}_{3} = a \times (a_{31}, a_{32}, a_{33})\).
Note
The lattice constant \(a\) must be consistent with the value used for the program alm. For example, if one used \(a = 20.4 a_{0}\) for a 2x2x2 supercell of Si, one should use \(a = 10.2 a_{0}\) here for the primitive cell.
“&kpoint”-field#
This entry field is used to specify the list of \(k\) points to be calculated. The first entry KPMODE specifies the types of calculation which is followed by detailed entries.
KPMODE = 0 : Calculate phonon frequencies at given \(k\) points
For example, if one wants to calculate phonon frequencies at Gamma (0, 0, 0) and X (0, 1/2, 1/2) of an FCC crystal, the
&kpointentry should be written as&kpoint 0 0.000 0.000 0.000 0.000 0.500 0.500 /
KPMODE = 1 : Band dispersion calculation
For example, if one wants to calculate phonon dispersion relations along G-K-X-G-L of a FCC crystal, the
&kpointentry should be written as follows:&kpoint 1 G 0.000 0.000 0.000 K 0.375 0.375 0.750 51 K 0.375 0.375 0.750 X 0.500 0.500 1.000 51 X 0.000 0.500 0.500 G 0.000 0.000 0.000 51 G 0.000 0.000 0.000 L 0.500 0.500 0.500 51 /The 1st and 5th columns specify the character of Brillouin zone edges, which are followed by fractional coordinates of each point. The last column indicates the number of sampling points.
KPMODE = 2 : Uniform \(k\) grid for phonon DOS and thermal conductivity
In order to perform a calculation with 20x20x20 \(k\) grid, the entry should be
&kpoint 2 20 20 20 /
“&strain”-field (Read when RELAX_STR = 2, 3, 4; optional when MODE = phonons with NEWFCS = 1)#
Please specify the displacement gradient tensor \(u_{\mu \nu}\) as
&strain
u_xx u_xy u_xz
u_yx u_yy u_yz
u_zx u_zy u_zz
/
Note that the user needs to give a symmetric matrix.
When RELAX_STR = 2, this field gives the initial strain for structural optimization; when RELAX_STR = 4, the fixed strain.
When MODE = phonons with NEWFCS = 1, this field is optional: if given,
the force constants of the systems strained by \(+u\) and \(-u\) are estimated and saved
to PREFIX_+.h5/PREFIX_-.h5 (or the XML pair with FILE_FORMAT = text). This is the
recommended way to specify the deformation for NEWFCS = 1.
“&displace”-field (Read when RELAX_STR is nonzero; optional)#
Please specify the initial atomic displacements \(u^{(0)}_{\alpha \mu}\) [Bohr].
This field is optional: when it is absent (or empty), the structural optimization starts from the undistorted positions.
Note that a zero initial displacement keeps the full symmetry of the reference structure, so a symmetry-breaking distortion never appears spontaneously; give a small displacement along the soft mode (most conveniently with DISPMODE = 2) to allow it.
DISPMODE = 0 : Fractional coordinate representation
The
&displaceentry should be written as follows. The first four lines after DISPMODE (= 0) specifies the unit cell, whose format is the same as the&cellfield. Note that the unit cell in the&displacefield is used only for transforming the input to the real space representation. Thus, the unit cell here does not need to be commensurate with the primitive cell or some supercells.u_ij is the j-th component of the displacement of i-th atom in the primitive cell in fractional coordinate representation.
&displace 0 a a11 a12 a13 a21 a22 a23 a31 a32 a33 u_01, u_02, u_03 ... /
DISPMODE = 1 : Cartesian coordinate representation
Each line after DISPMODE (= 1) specifies the initial atomic displacement in Cartesian representation. u_ij is the j component of the displacement of i-th atom in the primitive cell.
&displace 1 u_0x, u_0y, u_0z ... /
DISPMODE = 2 : Normal-mode representation
Each line after DISPMODE (= 2) displaces the atoms along one \(\Gamma\)-point normal mode of the harmonic force constants. The lines are added up, so a linear combination of modes can be given.
&displace 2 branch amplitude [nx ny nz] ... /
branchis the 1-based branch index at \(\Gamma\) in ascending order of the harmonic frequency (unstable modes come first), as printed in the anphon outputs. Any member of a degenerate set selects the whole set.
amplitude[Bohr] is the largest atomic displacement of the pattern. The pattern is oriented so that its largest Cartesian component is positive; a negative amplitude reverses it.
nx ny nzis required for a degenerate branch and ignored otherwise. It is a symmetry axis of the reference structure (Cartesian coordinates) that the distortion keeps: the pattern is the member of the degenerate set that is invariant under a proper rotation about this axis. The eigenvectors of a degenerate subspace returned by the diagonalization are arbitrary, but this member is not. A polar mode transforms as a vector and an octahedral tilt as an axial vector, so the same axes select the analogous patterns for both.Examples. For cubic BaTiO3, the soft polar triplet with axis
0 0 1,1 1 0, and1 1 1gives the tetragonal, orthorhombic, and rhombohedral distortions; for the folded tilt triplet of SrTiO3 in a 2x2x2 cell, the same axes give the a0a0c-, a0b-b-, and a-a-a- tilt patterns:1 0.03 0 0 1 1 0.03 1 1 0 1 0.03 1 1 1The resolved Cartesian displacements, the degenerate set, and the rotation used are printed at the beginning of the log. anphon stops with an error when the reference structure has no rotation about the axis, when no member of the set is invariant (the axis is incompatible with the mode), or when several members are (choose a higher-order axis). When rotations about the same axis through different points select distinct patterns that are not symmetry-equivalent domains, the candidates are printed as
DISPMODE = 1lines and the run stops so that one of them can be given explicitly.
“&selfenergy”-field (MODE = selfenergy)#
MODE = selfenergy analyzes the anharmonic self-energy of selected phonon modes at arbitrary wave vectors. It shares the setup of MODE = kappa (harmonic and cubic force constants, smearing or tetrahedron integration, temperatures), but the &kpoint field lists the target wave vectors and the integration mesh is given here:
&general
MODE = selfenergy
/
&kpoint
0 # KPMODE 0: list of target q points
0.0 0.0 0.0
0.15 0.2 0.3
/ # or KPMODE 1: a band path, every point of the path is a target
&selfenergy
KMESH = 20 20 20 # integration mesh
BRANCHES = all # or a list such as 1,4-6 (1-based), applied to every target
LINEWIDTH = 1 # Gamma(T), files PREFIX.Gamma.[n] (as SELF_ENERGY)
SHIFT = 0 # frequency shift, PREFIX.Shift.[n] (as REALPART)
SELF_W = 0 # Sigma(omega, T), PREFIX.Self.[n] (tetrahedron only)
FSTATE_W = 0 # frequency-resolved final state, PREFIX.fw.[n]
PRINTV3 = 0; PRINTV4 = 0
INTERPOLATE = 0 # 1: spectral function from the Fourier-interpolated self-energy matrix
KMESH_COARSE = 5 5 5 # coarse mesh for INTERPOLATE (must divide KMESH)
OMEGA_RANGE = 300 600 0.5 # frequency window and step for INTERPOLATE [cm^-1]
/
At least one output must be requested; LINEWIDTH = 0 suppresses the linewidth output, for example when only the frequency shift is needed.
With INTERPOLATE = 1 the full bubble self-energy matrix \(\Sigma_{jj'}(\mathbf{q},\omega)\) (Lorentzian broadening EPSILON) is computed on the coarse mesh, transformed to the displacement basis where it does not depend on the eigenvector gauge, Fourier-interpolated to every target wave vector, and the spectral function \(A(\mathbf{q},\omega) = -\frac{2\omega}{\pi}\,\mathrm{Im}\,\mathrm{Tr}\,[\omega^2 - D(\mathbf{q}) - \Pi(\mathbf{q},\omega)]^{-1}\) and its branch projections are written (PREFIX.spectrum or the spectrum/ group of the HDF5 file). The interpolation is exact on the coarse-mesh points; between them the accuracy is set by the coarse mesh, so compare with the direct linewidths of a few targets. The cost grows with the number of coarse points and frequencies; OMEGA_RANGE restricts the window (default: 0 to twice the highest frequency in steps of DELTA_E).
With the default FILE_FORMAT = h5 the results of all targets are collected in one file PREFIX.selfenergy.h5 (group targets/NNNNN per target in the order of the &kpoint field and BRANCHES, with xk, branch, frequency, kaxis for a path, linewidth, shift_*, self_omega/self_real/self_imag, fstate_*, and units as attributes; the path coordinates are repeated under path/). With FILE_FORMAT = text the per-target text files of the KS_INPUT analysis are written instead. The matrix-element listings (PRINTV3/PRINTV4) are always text files.
Targets that fall on the integration mesh are evaluated as in the KS_INPUT analysis. Targets off the mesh are evaluated exactly on the same mesh by diagonalizing the dynamical matrix on the shifted grid \(\{\mathbf{q}-\mathbf{k}\}\); every mesh point then contributes once and, for the matrix-element listings, the partners are keyed by their fractional coordinates. QUARTIC = 2 is not available off the mesh, and ISMEAR = 2 cannot be used off the mesh. For a degenerate target branch the linewidth, the shifts, and \(\Sigma(\omega)\) are averaged over the degenerate block, which makes them independent of the eigenvector gauge; FSTATE_W and the matrix-element listings remain per branch. Output files are numbered with the on-mesh targets first, then the off-mesh ones, in the order of the &kpoint field and BRANCHES; the header of each file gives the wave vector and branch. KS_INPUT in &analysis remains available with MODE = kappa and accepts off-mesh points under the same restrictions.
“&analysis”-field#
GRUNEISEN-tag = 0 | 1 | 2 | 3
0
Grüneisen parameters will not be calculated
1
Volumetric Grüneisen parameters \(\gamma_{\boldsymbol{q}j} = -\partial \log\omega_{\boldsymbol{q}j}/\partial \log V\) will be stored
2
Generalized Grüneisen parameters for the diagonal strain components (xx, yy, zz) will be stored
3
Generalized Grüneisen parameters for all 6 strain components (xx, yy, zz, yz, xz, xy) will be stored
- Default:
0
- Type:
Integer
- Description:
When
MODE = phononsandGRUNEISEN >= 1, Grüneisen parameters will be stored inPREFIX.gru_kpoints (KPMODE = 0),PREFIX.gruneisen (KPMODE = 1), orPREFIX.gru_all (KPMODE = 2).GRUNEISEN = 1computes the volumetric parameters \(\gamma_{\boldsymbol{q}j} = -\frac{\partial \log{\omega_{\boldsymbol{q}j}}}{\partial \log{V}}\).GRUNEISEN = 2and3compute the generalized parameters \(\gamma_{\boldsymbol{q}j}^{\mu\nu} = -\frac{\partial \log{\omega_{\boldsymbol{q}j}}}{\partial \varepsilon_{\mu\nu}}\) for the diagonal or all 6 symmetric strain components, respectively, and the output files change to a long format with one line per (k point, branch) containing the phonon frequency and the strain components. The volumetric value equals one third of the trace, \(\gamma_{\boldsymbol{q}j} = (\gamma_{\boldsymbol{q}j}^{xx}+\gamma_{\boldsymbol{q}j}^{yy}+\gamma_{\boldsymbol{q}j}^{zz})/3\). See this page for the formalism.
Note
To compute Grüneisen parameters, cubic force constants must be contained in the FCSFILE file.
DELTA_A-tag : Magnitude of the isotropic strain used by
NEWFCS = 1
- Default:
0.001
- Type:
Double
- Description:
When
NEWFCS = 1and the&strainfield is not given, the force constants are estimated for the isotropic strains \(\pm\)DELTA_A.
NEWFCS-tag = 0 | 1
0
Do not estimate force constants of deformed systems
1
Estimate force constants of deformed systems and save them as
PREFIX_+.h5 andPREFIX_-.h5 (XML withFILE_FORMAT = text)
- Default:
0
- Type:
Integer
- Description:
When
MODE = phononsandNEWFCS = 1, the harmonic (and, whenQUARTIC = 1, cubic) force constants of deformed systems are estimated from the cubic (and quartic) force constants inFCSFILEand saved asPREFIX_+.h5 andPREFIX_-.h5 (orPREFIX_+.xml andPREFIX_-.xml withFILE_FORMAT = text, or in a build without HDF5 support). The strain tensor \(u\) should be specified in the&strainfield; it is applied as \(+u\) and \(-u\) in the two created files. When the&strainfield is not given, a small isotropic strain of \(\pm\) DELTA_A is applied. The created files contain the deformed lattice vectors and the corrected force constants, and can be used directly asFCSFILEof subsequent phonon calculations. Since each created file carries a single supercell structure, all force constants must come fromFCSFILE; whenFC2FILEorFC3FILEis given, the files are not written and a warning is printed.
SUBLATTICE_RELAX-tag = 0 | 1
0
Clamped-ion strain derivatives: only the affine (homogeneous) deformation of the atomic positions is considered
1
Relaxed-ion strain derivatives: the strain-induced internal (sublattice) displacements are additionally included
- Default:
0
- Type:
Integer
- Description:
Selects the clamped-ion or relaxed-ion path of the strain derivatives used by GRUNEISEN and NEWFCS. With
SUBLATTICE_RELAX = 1, the internal coordinates are relaxed to first order in the strain: the sublattice displacement response \(X = -\mathsf{K}^{+}\Lambda\) is computed from the harmonic force constants, the strain derivatives of the IFCs gain the internal-strain leg, and the structures written byNEWFCScarry the induced internal displacements. The relaxed-ion path is normally the relevant one for quasiharmonic properties of crystals with internal structural parameters; the two paths coincide when symmetry forbids strain-induced internal displacements (e.g. under hydrostatic strain in diamond-structure crystals).
PRINTEVAL-tag = 0 | 1
0
Do not print phonon frequencies to separate files
1
Print phonon frequencies (eigenvalues) to files
- Default:
0
- Type:
Integer
- Description:
When
PRINTEVAL = 1, the phonon frequencies are saved inPREFIX.eval (KPMODE = 0),PREFIX.band.eval (KPMODE = 1), andPREFIX.mesh.eval (KPMODE = 2). The file format follows FILE_FORMAT: the defaulth5writes the corresponding *.eval.h5 files (schemaalamode:eigenvalues) instead of the text files;FILE_FORMAT = text(or a build without HDF5 support) writes the plain-text files.
PRINTEVEC-tag = 0 | 1
0
Do not print phonon eigenvectors
1
Print phonon eigenvectors in the
PREFIX.evec file
- Default:
0
- Type:
Integer
- Description:
The file format follows FILE_FORMAT: the default
h5writesPREFIX[.band|.mesh].evec.h5 (schemaalamode:eigenvectors);FILE_FORMAT = text(or a build without HDF5 support) writes the plain-textPREFIX[.band|.mesh].evec files.
PROJECTION_AXES-tag = e1x e1y e1z [, e2x e2y e2z]
- Default:
None
- Type:
Array of doubles (one or two vectors separated by a comma)
- Description:
When given, the eigenvectors of degenerate phonon modes are transformed within each degenerate subspace so that they align with the specified direction(s), which are given in Cartesian coordinates. Up to two axes can be given, separated by a comma; additional entries are ignored with a warning. This option affects the outputs that depend on eigenvectors, such as PRINTEVEC and ANIME.
PRINTXSF-tag = 0 | 1
0
Do not save an AXSF file
1
Create an AXSF file
PREFIX.axsf
- Default:
0
- Type:
Integer
- Description:
This is to visualize the direction of vibrational modes at gamma (0, 0, 0) by XCrySDen. This option is valid only when
MODE = phonons.
PRINTVEL-tag = 0 | 1
0
Do not print group velocity
1
Store phonon velocities to a file
- Default:
0
- Type:
Integer
- Description:
When
MODE = phononsandPRINTVEL = 1, group velocities of phonons will be stored inPREFIX.phvel (KPMODE = 1) orPREFIX.phvel_all (KPMODE = 2).
PRINTMSD-tag = 0 | 1
0
Do not print mean-square-displacement (MSD) of atoms
1
Save MSD of atoms to the file
PREFIX.msd
- Default:
0
- Type:
Integer
- Description:
This flag is available only when
MODE = phononsand KPMODE = 2.
DOS-tag = 0 | 1
0
Do not compute the phonon DOS
1
The total phonon DOS is computed and stored in
PREFIX.dos
- Default:
1
- Type:
Integer
- Description:
This flag is available only when
MODE = phononsand KPMODE = 2. SetDOS = 0to skip the DOS calculation. See also PDOS.
PDOS-tag = 0 | 1
0
Only the total DOS will be printed in
PREFIX.dos1
Atom-projected phonon DOS will be stored in
PREFIX.dos
- Default:
0
- Type:
Integer
- Description:
This flag is available only when
MODE = phononsand KPMODE = 2.
LONGITUDINAL_DOS-tag = 0 | 1
0
Do not compute the longitudinal-projected DOS
1
The phonon DOS projected onto the longitudinal direction (polarization parallel to the wave vector) is stored in
PREFIX.longitudinal_dos
- Default:
0
- Type:
Integer
- Description:
This flag is available only when
MODE = phononsand KPMODE = 2.
TDOS-tag = 0 | 1
0
Do not compute two-phonon DOS
1
Two-phonon DOSs will be stored in
PREFIX.tdos
- Default:
0
- Type:
Integer
- Description:
This flag is available only when
MODE = phononsand KPMODE = 2.Note
Calculation of two-phonon DOS is computationally expensive.
SPS-tag = 0 | 1 | 2
0
Do not compute scattering phase space
1
Total and mode-decomposed scattering phase space involvingthe three-phonon processes will be stored inPREFIX.sps2
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
MODE = phononsand KPMODE = 2.
PRINTPR-tag = 0 | 1
0
Do not compute the (atomic) participation ratio
1
Compute participation ratio and atomic participation ratio, which will bestored inPREFIX.pr andPREFIX.apr respectively.
- Default:
0
- Type:
Integer
- Description:
This flag is available when
MODE = phonons.
UCORR-tag = 0 | 1
0
Do nothing
1
Compute the displacement-displacement correlation function.The result is stored inPREFIX.ucorr
- Default:
0
- Type:
Integer
- Description:
The displacement-displacement correlation function involves two atoms. The first atom is located in the primitive cell at the center (shift1=[0,0,0]) and the second atom is located in the \(\ell'\) th cell. The translation vector to the \(\ell'\) th cell can be specified by the
SHIFT_UCORRtag. This tag is effective only whenMODE = phononsand KPMODE = 2
SHIFT_UCORR-tag = l1, l2, l3
- Default:
[0, 0, 0]
- Type:
Array of integers
- Description:
This tag specifies the translation vector used for computing the displacement-displacement (uu) correlation function. For example, if one wants to compute the uu correlation function between an atom 1 in the cell at the center and atom 2 in the neighboring cell at \(\boldsymbol{r}(\ell')=(1,0,0)\),
SHIFT_UCORRshould be set asSHIFT_UCORR = 1 0 0.
IRREPS-tag = 0 | 1
0
Do nothing
1
Assign irreducible representations (Mulliken symbols) and IR/Ramanactivities to the phonon modes at the Gamma point.The result is stored inPREFIX.irreps
- Default:
0
- Type:
Integer
- Description:
When
MODE = phononsandIRREPS = 1, each zone-center phonon multiplet is assigned an irreducible representation of the crystal point group by projecting the eigenvectors of the analytic (without the non-analytic correction) dynamical matrix onto the characters of the point-group operations. Each multiplet is labeled as IR-active, Raman-active, both, silent, or acoustic, and the decomposition of the total vibrational representation is printed. WhenBORNINFOis given, the IR oscillator-strength tensors \(S_{\alpha\beta} = \sum_{\nu} Z^{*}_{\nu,\alpha} Z^{*}_{\nu,\beta}\) (unit: \(e^{2}\,\text{amu}^{-1}\)) are also reported. Labels that depend on the axis convention (e.g. \(B_{1}\) vs. \(B_{2}\)) follow the standardized frame reported in the output; the raw characters are printed so that labels can be re-derived under any other convention. This tag is effective only whenMODE = phononsand is not supported for noncollinear magnetic systems.
ZMODE-tag = 0 | 1
0
Do nothing
1
Compute the mode effective charges of the zone-center phonons.The result is stored inPREFIX.zmode
- Default:
0
- Type:
Integer
- Description:
When
MODE = phononsandZMODE = 1, the mode effective charges are computed for the phonon modes at the Gamma point and saved inPREFIX.zmode. The unit of the mode effective charge is \(e \; \text{amu}^{-1/2}\).
DIELEC-tag = 0 | 1
0
Do nothing
1
Compute the frequency-dependent dielectric function
- Default:
0
- Type:
Integer
- Description:
When
DIELEC = 1, the phonon contribution to the frequency-dependent dielectric function \(\epsilon(\omega)\) is computed from the Born effective charges and the zone-center phonon modes and saved inPREFIX.dielec (MODE = phonons).BORNINFOmust be given. WhenMODE = SCPH(QHA), the dielectric function is computed with the temperature-renormalized phonon frequencies and saved inPREFIX.scph_dielec (PREFIX.qha_dielec).
QUARTIC-tag = 0 | 1 | 2
0
Quartic force constants are not used.
1
Read the quartic force constants and enable the quartic terms.QUARTIC = 1is set automatically whenMODE = SCPHorMODE = QHA.2
In the mode analysis (KS_INPUT), additionally computethe contribution of a specific four-phonon diagram to the linewidth (expensive).
- Default:
0
- Type:
Integer
- Description:
When
QUARTIC = 1, the quartic force constants are read fromFCSFILE(orFC4FILE). In the mode analysis withREALPART = 1, the frequency shift due to the loop diagram of the quartic anharmonicity is then computed in addition to the third-order terms. The former role ofQUARTICas the switch of four-phonon scattering inMODE = kappais deprecated in favor of INCLUDE_4PH;QUARTIC > 0withoutINCLUDE_4PHstill enables it, with a warning.
KS_INPUT-tag : File containing a list of phonon modes to be analyzed (deprecated)
- Default:
None
- Type:
String
- Description:
Deprecated in favor of
MODE = selfenergy(targets in&kpoint, integration mesh and switches in&selfenergy), which also accepts wave vectors off the mesh and band paths. WhenMODE = kappaandKS_INPUTis given, the mode analysis of the phonon modes listed in the specified file is performed instead of the thermal conductivity calculation. The first line of the file gives the number of entries, and each of the following lines contains the fractional coordinates of a \(k\) point and a branch index (1-based) ask1 k2 k3 s. Each \(k\) point must be a point of the grid given in the&kpointfield (KPMODE = 2). The quantities to be computed are selected by SELF_ENERGY, REALPART, SELF_W, PRINTV3, and PRINTV4.
SELF_ENERGY-tag = 0 | 1
0
Do nothing
1
Compute the temperature dependence of the phonon linewidth forthe modes given inKS_INPUT
- Default:
0
- Type:
Integer
- Description:
For each mode listed in KS_INPUT, the linewidth (FWHM = \(2\Gamma\)) due to three-phonon interactions is computed as a function of temperature and saved in
PREFIX.Gamma.[number]. WithQUARTIC = 2, contributions of specific four-phonon diagrams are appended. WhenREALPART = 1, the frequency shift is also computed and saved inPREFIX.Shift.[number].
REALPART-tag = 0 | 1
- Default:
0
- Type:
Integer
- Description:
When
REALPART = 1is used with KS_INPUT andSELF_ENERGY = 1, the real part of the phonon self-energy — the frequency shift due to the tadpole and bubble diagrams of the cubic anharmonicity and, ifQUARTIC = 1, the loop diagram of the quartic anharmonicity — is computed and saved inPREFIX.Shift.[number]. This option works only withISMEAR = 0.
SELF_W-tag = 0 | 1
- Default:
0
- Type:
Integer
- Description:
When
SELF_W = 1is used with KS_INPUT, the frequency dependence of the three-phonon (bubble) self-energy is computed at each temperature for the modes listed inKS_INPUTand saved inPREFIX.Self.[number], from which spectral functions can be obtained. This option works only with the tetrahedron method (ISMEAR = -1).
PRINTV3-tag = 0 | 1 | 2
0
Do nothing
1
Print \(|V_{3}|^{2}\) matrix elements in
PREFIX.V3.[number]2
Print \(\Phi_{3}\) matrix elements in
PREFIX.Phi3.[number]
- Default:
0
- Type:
Integer
- Description:
For each mode listed in KS_INPUT, the three-phonon matrix elements involving the mode are printed.
PRINTV3 = 1prints the squared elements \(|V_{3}(-qj; q'j', q''j'')|^{2}\) in units of cm-2, whilePRINTV3 = 2prints the complex elements \(\Phi_{3}(qj; q'j', q''j'')\) in units of Ry/(u1/2 Bohr)3.
PRINTV4-tag = 0 | 1 | 2
0
Do nothing
1
Print \(|V_{4}|^{2}\) matrix elements in
PREFIX.V4.[number]2
Print \(\Phi_{4}\) matrix elements in
PREFIX.Phi4.[number]
- Default:
0
- Type:
Integer
- Description:
Same as PRINTV3, but for the four-phonon matrix elements \(|V_{4}(-qj; q_1 j_1, q_2 j_2, q_3 j_3)|^{2}\) (in cm-2) and \(\Phi_{4}\) (in Ry/(u1/2 Bohr)4). The quartic force constants are required (
QUARTIC = 1).
FC2_EWALD-tag = 0 | 1
0
Do nothing
1
Print the dipole-dipole and short-range components of the harmonicforce constants inPREFIX.fc2_ewald
- Default:
0
- Type:
Integer
- Description:
Available only when
NONANALYTIC = 3. For each pair of atoms, the original harmonic force constant, its dipole-dipole (Ewald) part, and the short-range remainder are printed, which is useful for checking the long-range separation of the harmonic force constants.
FE_BUBBLE-tag = 0 | 1
0
Do nothing
1
Compute the bubble correction to the vibrational free energy and save itinPREFIX.thermo (MODE = phonons) orPREFIX.scph_thermo (MODE = SCPH)
- Default:
0
- Type:
Integer
- Description:
When
FE_BUBBLE = 1, the lowest-order correction of the cubic anharmonicity to the vibrational free energy, which comes from the bubble diagram (see Bubble correction to the free energy), is computed on the uniform \(k\) mesh of the&kpointfield. The cubic force constants are needed, and the tag works only withMODE = phononsandMODE = SCPH. WithMODE = phonons, KPMODE = 2 is required, and the harmonic phonons are used at all temperatures. The result is written in the last column, “Free energy (Bubble)”, ofPREFIX.thermo. It is not included in the column “Free energy (QHA)”, so the free energy including the bubble correction is the sum of the two columns. WithMODE = SCPH, KPMODE = 2 is also required, and the bubble correction is computed with the SCPH frequencies and eigenvectors of each temperature interpolated fromKMESH_INTERPOLATEonto the&kpointmesh. The result is written in the column “F_{vib} (Bubble correction)” ofPREFIX.scph_thermo and is included in the column “F_{total}”. In both modes, the heat capacity and the entropy do not include the bubble contribution. WithCLASSICAL = 1, the classical occupation factors are used.FE_BUBBLE = 1cannot be combined withRELAX_STR\(\neq\) 0, and therefore not withMODE = QHAeither. The computational cost grows as \(N_{q}^{2}\), where \(N_{q}\) is the number of \(k\) points of the mesh.
ANIME-tag = k1, k2, k3
- Default:
None
- Type:
Array of doubles
- Description:
This tag is to animate vibrational mode. k1, k2, and k3 specify the momentum of phonon modes to animate, which should be given in units of the reciprocal lattice vector. For example,
ANIME = 0.0 0.0 0.5will animate phonon modes at (0, 0, 1/2). WhenANIMEis given,ANIME_CELLSIZEis also necessary. You can choose the format of animation files, either AXSF or XYZ, byANIME_FORMATtag.
ANIME_FRAMES-tag: The number of frames saved in animation files
- Default:
20
- Type:
Integer
ANIME_CELLSIZE-tag = L1, L2, L3
- Default:
None
- Type:
Array of integers
- Description:
This tag specifies the cell size for animation. L1, L2, and L3 should be large enough to be commensurate with the reciprocal point given by the
ANIMEtag.
ANIME_FORMAT-tag = xsf | xyz
- Default:
xyz
- Type:
String
- Description:
When
ANIME_FORMAT = xsf,PREFIX.anime???.axsf files are created for XcrySDen. WhenANIME_FORMAT = xyz,PREFIX.anime???.xyz files are created for VMD (and any other supporting software such as Jmol).
“&kappa”-field (Read only when MODE = kappa)#
In version 1.x, ISOTOPE, ISOFACT, KAPPA_SPEC, and KAPPA_COHERENT were given in the &analysis field.
They now belong to the &kappa field, and an old input file that keeps them in &analysis stops with an error.
SOLVER-tag : Solver level of the Boltzmann transport equation
RTA
Relaxation-time approximation (single-mode approximation)
IBTE
Iterative solution of the linearized BTE (result in
PREFIX.kl_iter)VBTE
Variational solution by preconditioned conjugate gradients (result in
PREFIX.kl_iter)DBTE
Direct solution: dense eigendecomposition of the collision kernel (diagnostic; small meshes; result in
PREFIX.kl_iter)
- Default:
RTA
- Type:
String
- Description:
Case insensitive. For the theoretical background of the three non-RTA solvers, please see this page. The
IBTEiteration is controlled by MIN_CYCLE, MAX_CYCLE, ITER_THRESHOLD, and IBTE_MIXING. With the defaultFILE_FORMAT = h5, the per-temperature results are stored in the/iterativebtegroup ofPREFIX.kappa.h5 and an interrupted temperature sweep restarts from the missing temperatures (RESTART = 0forces a recomputation). Temperatures whose iteration hitsMAX_CYCLEor diverges are reported and flagged as unconverged (also in a comment line ofPREFIX.kl_iter, with the lowest-residual iterate kept); a restart continues their iteration from the stored deviation function instead of skipping them.
IBTEandVBTEstop when the relative residual of the linear system, \(\|b - A F\| / \|b\|\), falls belowITER_THRESHOLD(default \(10^{-4}\)); temperatures that do not reach it are flagged as unconverged in the log, inPREFIX.kl_iter and in/iterativebte/convergedofPREFIX.kappa.h5.The non-RTA solvers work with velocities averaged over degenerate modes. The intra-block part of the velocity diad, \(\mathrm{Tr}(P V^{\alpha} P V^{\beta}) - d\,\bar{v}^{\alpha}\bar{v}^{\beta}\) for a degenerate block \(P\) of dimension \(d\), which the RTA includes through the velocity-matrix block traces, is added to kappa at the RTA level (in Si it raises kappa by 0.7 % at a 16x16x16 mesh and 0.4 % at 24x24x24).
SOLVER = VBTEsolves the same linearized BTE asIBTEby preconditioned conjugate gradients (CG) in the star-weighted inner product. The operator is self-adjoint for fixed-width smearing (ISMEAR = 0, 1), and kappa, the value of the variational functional, then has an error quadratic in the residual, so CG usually needs fewer operator applications thanIBTE. The tetrahedron and adaptive weights (ISMEAR = -1, 2) make the discretized operator slightly non-symmetric, and CG then stagnates or breaks down at low temperature and in normal-process-dominated crystals. For these kernelsVBTEuses the BiCGSTAB method instead (two operator applications per iteration, kappa error linear in the residual), which converged in 3-11 iterations per temperature in Si (20-1000 K) and BAs (100-1000 K), whereIBTEneeds up to about 70 iterations. With fixed-width smearing,VBTEfalls back to BiCGSTAB if CG fails.MIN_CYCLEandIBTE_MIXINGare not used byVBTE. All non-RTA solvers share the/iterativebterestart state inPREFIX.kappa.h5.
SOLVER = DBTEis a diagnostic solver: it assembles the collision kernel on the irreducible wedge as an explicit dense matrix - restricted to the degeneracy-reduced, little-group-invariant basis, in the Omega normalization whose diagonal is \(1/\tau\) - symmetrizes it as \((A + A^{T})/2\), and computes its full eigendecomposition with LAPACKdsyevdon MPI rank 0 (multithreaded if the LAPACK library is, e.g. throughMKL_NUM_THREADS). The symmetrization is exact for fixed-width smearing, where DBTE is the exact reference forIBTEandVBTE. With the tetrahedron or adaptive methods DBTE solves the symmetrized kernel, a slightly different system: in Si it differs from theIBTE/VBTEsolution by 0.02-0.2 % at 100 K and above (decreasing with the mesh density), but by several percent or more below about 30 K. Temperatures at which the symmetrized kernel has negative eigenvalues are flagged as unconverged. It reports what the matrix-free solvers cannot access: the residual asymmetry of the discretized kernel, violations of positive semidefiniteness (a direct probe of a too-coarse mesh or an inadequate smearing width), the near-null part of the spectrum (scattering rates in cm^-1) with its overlap onto the momentum-drift directions, and the sensitivity of kappa to dropping the softest modes. All iterative-family solvers use the detailed-balance-symmetric occupation kernel (\(g_1 g_2 g_3\) with \(g = \sqrt{n(n+1)}\), identical on the energy shell to the raw occupation products), so for fixed-width smearing the three solvers agree to their tolerances; with the tetrahedron or adaptive methods a small residual difference remains from the direction dependence of the integration weights. Memory scales with the square of the reduced dimension; oversized problems abort with a clear message.Caution
SOLVER = DBTEkeeps the dense kernel on MPI rank 0 and is limited to small k meshes (\(3 N_{k}^{\mathrm{irred}} N_{\mathrm{branch}} \le 25000\)). For production runs useIBTEorVBTE.
INCLUDE_4PH-tag = 0 | 1
0
Compute three-phonon scattering rates only
1
Additionally compute four-phonon scattering rates
- Default:
0
- Type:
Integer
- Description:
The explicit switch for the four-phonon channel. It requires quartic force constants (
FCSFILEcontaining Order4, orFC4FILE) and activates the FC4 machinery automatically; the related settings areKMESH_COARSE,ISMEAR_4PH,EPSILON_4PH, andINTERPOLATOR.The quartic matrix elements of all band triples of a momentum-conserving quartet are evaluated by successive eigenvector contractions of the Fourier-transformed quartic force constants, so the cost per quartet grows as \((3N_{\mathrm{atom}})^4\) and is independent of the number of force-constant terms once they have been Fourier transformed. Band triples outside the smearing window are discarded before any matrix element is formed.
VERBOSITY = 2prints a per-mode timing breakdown of the kernel. The three-phonon matrix elements of the RTA and IBTE solvers are evaluated by the same factorization (cost \((3N_{\mathrm{atom}})^3\) per triplet for a fixed mode, \((3N_{\mathrm{atom}})^4\) for the collision matrix), which matters for cells with more than a few atoms. The dense contractions use Eigen; building with-DUSE_EIGEN_BLAS=ONroutes them through the BLAS library, which is faster for large cells (pin the BLAS thread count to 1, e.g.OPENBLAS_NUM_THREADS=1, when OpenMP threads are used).
KMESH_COARSE-tag = k1, k2, k3
- Default:
The same \(k\) mesh as given in the
&kpointfield- Type:
Array of integers
- Description:
\(k\) mesh used for evaluating the four-phonon scattering rates when
INCLUDE_4PH = 1. Because four-phonon calculations are far more expensive than three-phonon ones, a mesh coarser than that of the&kpointfield can be given here; the computed rates are then interpolated onto the dense mesh by the method selected with INTERPOLATOR.
ISMEAR_4PH-tag = -1 | 0 | 1 | 2
-1
Not implemented for four-phonon scattering; automatically switched to 2
0
Lorentzian smearing with width of
EPSILON_4PH1
Gaussian smearing with width of
EPSILON_4PH2
Adaptive Gaussian smearing
- Default:
1
- Type:
Integer
- Description:
Brillouin-zone integration method for the four-phonon scattering rates (
INCLUDE_4PH = 1), independent of the three-phonon setting ISMEAR.ISMEAR_4PH = 2uses the same adaptive-broadening scheme asISMEAR = 2, generalized to the three-mode energy denominators of the four-phonon processes and evaluated on the (possibly coarser) mesh given byKMESH_COARSE; the width is scaled by ADAPTIVE_FACTOR andEPSILON_4PHis not used. Adaptive smearing is recommended for the coarse four-phonon meshes, where a single fixed width is hard to converge.
EPSILON_4PH-tag : Smearing width for four-phonon scattering rates in units of Kayser (cm-1)
- Default:
10.0
- Type:
Double
- Description:
Used when
ISMEAR_4PH = 0or1; neglected whenISMEAR_4PH = 2. Because the four-phonon phase space is much larger and the mesh usually coarser than for three-phonon processes, the optimal width generally differs fromEPSILON.
INTERPOLATOR-tag = linear | log-linear | modified-log-linear
linear
Trilinear interpolation of the scattering rates
log-linear
Trilinear interpolation of the logarithm of the scattering rates
modified-log-linear
Same as log-linear, but for the acoustic branches theinterpolation cells containing the \(\Gamma\) pointare avoided
- Default:
log-linear
- Type:
String
- Description:
Method for interpolating the four-phonon scattering rates computed on KMESH_COARSE onto the dense \(k\) mesh of the
&kpointfield. The value is case-insensitive.
WRITE_INTERPOL-tag = 0 | 1
- Default:
0
- Type:
Integer
- Description:
When
WRITE_INTERPOL = 1and the four-phonon scattering rates are interpolated (INCLUDE_4PH = 1), the interpolated linewidths on the dense \(k\) mesh are written toPREFIX.interpolated_gamma, which is useful for checking the interpolation quality.
ADAPTIVE_FACTOR-tag : Scaling prefactor \(\alpha\) of the adaptive smearing width
- Default:
1.0
- Type:
Double
- Description:
Multiplies the automatically determined Gaussian widths of the adaptive smearing method, for both
ISMEAR = 2(three-phonon) andISMEAR_4PH = 2(four-phonon). The default is usually adequate; smaller values sharpen the energy conservation (and may require denser meshes), larger values smooth it.
RESTART-tag : Flag to restart the calculation when
MODE = kappa
0
Calculate from scratch
1
Restart from the existing file
- Default:
1 if there is a file named
PREFIX.kappa.h5 orPREFIX.result; 0 otherwise- Type:
Integer
- Description:
With the default
FILE_FORMAT = h5, the restart state lives inPREFIX.kappa.h5. A legacy textPREFIX.result file (from an older run orFILE_FORMAT = text) is imported into the HDF5 file once, read-only, and left untouched. This tag is also accepted in the&generalfield for backward compatibility (deprecated); the&kappavalue wins when both are given.
RESTART_4PH-tag : Flag to restart the four-phonon part of the calculation when
INCLUDE_4PH = 1
0
Calculate the four-phonon scattering rates from scratch
1
Restart from the existing file
- Default:
1 if there is a file named
PREFIX.kappa.h5 orPREFIX.4ph.result; 0 otherwise- Type:
Integer
- Description:
Controls the four-phonon channel independently of RESTART (the two channels are stored side by side in
PREFIX.kappa.h5 but restart separately).RESTART_4PH = 0discards only the previously computed four-phonon scattering rates; the three-phonon data are kept.
KAPPA_COHERENT-tag = 0 | 1 | 2
0
Do not compute the coherent component of thermal conductivity
1
Compute the coherent component of thermal conductivity and save it in
PREFIX.kl_coherent.2
In addition to above (KAPPA_COHERENT = 1), all elements of the coherent termare saved inPREFIX.kc_elem.
- Default:
0
- Type:
Integer
- Description:
This flag is available when
MODE = kappa. For the theoretical details, please see this page. The Peierls term uses the velocity matrix regardless of this flag; setting it to 1 or 2 additionally stores the full band off-diagonal matrix, which costs \(N_{q}(3N_{\kappa})^{2}\times 3\) complex numbers on the root process.Caution
Still experimental. Please check the validity of results carefully.
KAPPA_SPEC-tag = 0 | 1
0
Do not compute the thermal conductivity spectra
1
Compute the thermal conductivity spectra, which will be stored in
PREFIX.kl_spec
- Default:
0
- Type:
Integer
- Description:
This flag is available when
MODE = kappa. WithISMEAR = -1, each irreducible k point enters the spectrum with the tetrahedron weight of its representative instead of the weights of its star members. The spectral shape is therefore approximate on coarse meshes, while its energy integral still equals the thermal conductivity.
ISOTOPE-tag = 0 | 1 | 2
0
Do not consider phonon-isotope scatterings
1
Consider phonon-isotope scatterings
2
Consider phonon-isotope scatterings as inISOTOPE = 1andthe calculated selfenergy is stored inPREFIX.self_isotope
- Default:
1
- Type:
Integer
- Description:
When
MODE = kappaandISOTOPE = 1 or 2, phonon scatterings due to isotopes will be considered perturbatively. The computation is negligibly cheap, so it is enabled by default withISOFACTtaken from the internal natural-abundance database; setISOTOPE = 0for isotopically pure crystals, or giveISOFACTexplicitly for enriched samples (required for elements without a database entry). The per-mode isotope linewidths and the factors used are stored inPREFIX.kappa.h5 (/scattering/isotope/gamma,/metadata/isotope_factors).
ISOFACT-tag : Isotope factor for each atomic species (in the order of the
KD-tag)
- Default:
Automatically calculated from the
KDtag- Type:
Array of doubles
- Description:
Isotope factor is a dimensionless value defined by \(\sum_{i} f_{i} (1 - m_{i}/\bar{m})^{2}\). Here, \(f_{i}\) is the fraction of the \(i\)th isotope of an element having mass \(m_{i}\), and \(\bar{m}=\sum_{i}f_{i}m_{i}\) is the average mass, respectively. This quantity is equivalent to \(g_{2}\) appearing in the original paper by S. Tamura [Phys. Rev. B, 27, 858.].
ISOTOPE_INSCATTERING-tag = 0 | 1
0
Isotope scattering enters the iterative solvers as an RTA-level (diagonal) rate only
1
The elastic isotope-disorder channel (Tamura kernel) becomes part of the collision operator, including its in-scattering term
- Default:
1
- Type:
Integer
- Description:
Used by
SOLVER = IBTEandVBTEwhenISOTOPE >= 1(SOLVER = RTAis unaffected). With the in-scattering term the isotope diagonal is the row sum of the operator entries, so the elastic channel annihilates constant deviation functions exactly. The effect on kappa is positive (in-scattering restores heat flux) and grows with the mass variance and towards low temperatures; for natural silicon it is below 0.2 %. Boundary scattering remains exactly diagonal (it has no in-scattering term), and the four-phonon channel is treated at the RTA level.
LEN_BOUNDARY-tag : Characteristic length for boundary scattering in units of meter
- Default:
0.0 (no boundary scattering)
- Type:
Double
- Description:
When
LEN_BOUNDARY > 0, a boundary scattering rate \(|\boldsymbol{v}_{qj}|/L\) with \(L\) =LEN_BOUNDARYis added to the phonon linewidths used for the thermal conductivity, where \(\boldsymbol{v}_{qj}\) is the group velocity of each phonon mode.
MIN_CYCLE-tag : Minimum number of iterations of the iterative BTE solver
- Default:
1
- Type:
Integer
- Description:
Used when
SOLVER = IBTE. The convergence test starts only afterMIN_CYCLEiterations have been performed.
MAX_CYCLE-tag : Maximum number of iterations of the iterative BTE solver
- Default:
100
- Type:
Integer
- Description:
Used when
SOLVER = IBTEorVBTE. If the iteration does not converge withinMAX_CYCLEcycles, the iterate with the lowest residual is kept, the temperature is flagged as unconverged, and the calculation proceeds to the next temperature. ForIBTEstarted from zero,MAX_CYCLE = 1keeps the first iterate, the RTA-like \(F_0 = b/Q\), whose residual is not evaluated (reported as nan). ForVBTEthe limit applies separately to the CG and BiCGSTAB stages.
ITER_THRESHOLD-tag : Convergence criterion of the iterative BTE solver
- Default:
1.0e-4
- Type:
Double
- Description:
Used when
SOLVER = IBTEorVBTE. The iteration at each temperature stops when the relative residual of the linear system, \(\|b - A F\| / \|b\|\) (in the norm weighted by the star multiplicities of the irreducible k points), becomes smaller thanITER_THRESHOLD(see SOLVER). The error of kappa is roughly linear in the residual forIBTEand quadratic forVBTEwith fixed-width smearing.Values above \(10^{-3}\) trigger a warning.
IBTE_MIXING-tag : Mixing factor of the iterative BTE solver
- Default:
0.9
- Type:
Double
- Description:
Used when
SOLVER = IBTE. In each iteration, the updated nonequilibrium distribution is mixed with the previous one as \(f_{\mathrm{new}} \leftarrow \alpha f_{\mathrm{new}} + (1-\alpha) f_{\mathrm{old}}\) with \(\alpha\) =IBTE_MIXING. Values smaller than 1 damp oscillations of slowly converging iterations.
Format of BORNINFO#
When one wants to consider the LO-TO splitting near the \(\Gamma\) point, it is necessary to set NONANALYTIC > 0 and
provide BORNINFO file containing dielectric tensor \(\epsilon^{\infty}\) and Born effective charge \(Z^{*}\).
In BORNINFO file, the dielectric tensor should be written in first 3 lines which are followed by Born effective charge tensors
for each atom as the following.
Here, \(N_p\) is the number of atoms contained in the primitive cell.
Attention
Please pay attention to the order of Born effective charges.