10.1. ALM: Input files#
Format of input files#
Each input file should consist of entry fields. Available entry fields are
&general, &interaction, &cutoff, &cell, &position, and &optimize.
Each entry field starts from the key label &field and ends at the terminate character “/”. (This is equivalent to Fortran namelist.)
For example, &general entry field of program alm should be given like
&general
# Comment line
PREFIX = prefix
MODE = optimize
/
Multiple entries can be put in a single line. Also, characters put on the right of sharp (“#”) are neglected. Therefore, the above example is equivalent to the following:
&general
PREFIX = prefix; MODE = optimize # Comment line
/
Each variable must be given inside the appropriate entry field.
List of supported input variables#
&general |
|||
&interaction |
|||
&optimize |
|||
Description of input variables#
“&general”-field#
PREFIX-tag : Job prefix to be used for names of output files
- Default:
None
- Type:
String
MODE-tag = optimize | suggest
optimize
Estimate harmonic and anharmonic IFCs.This mode requires an appropriate &optimize field.suggest
Suggests the displacement patterns necessaryto estimate harmonic and anharmonic IFCs.
- Default:
None
- Type:
String
NAT-tag : Number of atoms in the supercell
- Default:
The number of entries in the
&positionfield (or inSTRUCTURE_FILE)- Type:
Integer
KD-tag : List of atomic species
- Default:
None
- Type:
Array of strings
- Example:
In the case of GaAs, it should be
KD = Ga As.
STRUCTURE_FILE-tag : File containing the input structure
- Default:
None
- Type:
String
- Description:
When this tag is given, alm reads the lattice vectors, atomic species, and atomic coordinates from the specified file in the VASP POSCAR format. In this case, the
&celland&positionfields are ignored, andNATandKDare inferred from the structure file.The POSCAR file may use direct or Cartesian coordinates. A
Selective dynamicsline is accepted, but the selective-dynamics flags themselves are ignored.Note
A POSCAR is always interpreted in Angstrom (the VASP convention), independent of the LENGTH_UNIT tag.
SUPERCELL-tag : Transformation matrix from the input cell to the supercell
- Default:
1
- Type:
Integer matrix
- Description:
This tag specifies the target supercell as \((\boldsymbol{a}_{s}, \boldsymbol{b}_{s}, \boldsymbol{c}_{s})^{T} = M (\boldsymbol{a}_{\mathrm{in}}, \boldsymbol{b}_{\mathrm{in}}, \boldsymbol{c}_{\mathrm{in}})^{T}\). If the input structure is already the supercell used for the force calculations, keep the default value.
The matrix can be written as one, three, or nine entries. One entry
nmeansn n n; three entriesn1 n2 n3mean a diagonal matrix; nine entries give the full matrix in row-major order. The determinant must be a nonzero integer.- Example:
SUPERCELL = 2 2 2creates a 2x2x2 supercell from the input cell.SUPERCELL = 2 0 0 0 2 0 0 0 1creates a 2x2x1 supercell.
PRIMCELL-tag : Transformation matrix from the input cell to the primitive cell
- Default:
1
- Type:
Matrix or
Auto- Description:
This tag specifies the primitive cell as \((\boldsymbol{a}_{p}, \boldsymbol{b}_{p}, \boldsymbol{c}_{p})^{T} = M (\boldsymbol{a}_{\mathrm{in}}, \boldsymbol{b}_{\mathrm{in}}, \boldsymbol{c}_{\mathrm{in}})^{T}\). The matrix can be written as one, three, or nine entries, using the same convention as
SUPERCELL. Fractional entries such as1/2are accepted. The determinant of the inverse matrix must be a nonzero integer.
PRIMCELL = Autouses spglib to detect the primitive cell from the input structure. This is useful when the input structure is a conventional cell or a supercell and the primitive-cell transformation is not obvious.- Example:
PRIMCELL = 1/2 0 0 0 1/2 0 0 0 1/2defines a primitive cell whose lattice vectors are one half of the corresponding input-cell lattice vectors.
TOLERANCE-tag : Tolerance for finding symmetry operations
- Default:
1.0e-3
- Type:
Double
TOL_CONST-tag : Tolerance used when reducing the constraints between force constants
- Default:
1.0e-6
- Type:
Double
- Description:
Numerical tolerance used to detect linearly dependent constraints (the rank of the constraint matrix) when the constraints of
ICONSTand the symmetry relations are reduced. The default value is usually sufficient; see also the note on the input precision under ICONST.
SYMMETRIZE_STRUCTURE-tag = 0 | 1
0
Use the input structure as given.
1
Symmetrize the lattice vectors and atomic positions to the space group that spglib detectswithinTOLERANCE. The structure is not standardized: the cell choice, atom order, andorientation are kept, the lattice changes only by a symmetric (rotation-free) strain, andthe atoms are not shifted as a whole. The symmetrized structure is used for all later stepsand written to the output files.
- Default:
0
- Type:
Integer
- Description:
Useful when the input coordinates are given with only a few digits, e.g.
0.3333333333instead of 1/3. The changes of the lattice vectors and atomic positions are printed to the standard output. The input displacements inDFSETare not modified. Not available withNONCOLLINEAR = 1or withPERIODIC = 0in any direction.The symmetrization is applied to the input cell, i.e., the structure given by
&celland&positionor bySTRUCTURE_FILE, right after it is read. The supercell (SUPERCELL) and the primitive cell (PRIMCELL, includingPRIMCELL = Auto) are then built from the symmetrized input cell, so they are symmetric as well.When
SYMMETRIZE_STRUCTURE = 0, ALM checks how far the input structure deviates from the ideal structure of its space group and prints a warning recommendingSYMMETRIZE_STRUCTURE = 1if a lattice-vector component or an atomic position deviates by more than \(10^{-6}\) bohr.
PRINTSYM-tag = 0 | 1
0
Symmetry operations won’t be saved in “SYMM_INFO”
1
Symmetry operations will be saved in “SYMM_INFO”
- Default:
0
- type:
Integer
FCSYM_BASIS-tag = Cartesian | Lattice
Cartesian, C
Symmetry reduction of force constant is performed in the Cartesian basis
Lattice, L
Symmetry reduction of force constant is performed in the \(\boldsymbol{a}_1, \boldsymbol{a}_2, \boldsymbol{a}_3\) basis
- Default:
Cartesian (changed from Lattice in version 2.0)
- type:
String
- Description:
The calculation results should not depend on the choice of
FCSYM_BASISwhenLMODEL = ols. For other regression methods (enet, adaptive LASSO), an optimal value of theL1_ALPHAchanges when you change theFCSYM_BASISoption.
FCSYM_BASIS = Cartesianis the default because it is required for the rotational invariance constraints.FCSYM_BASIS = Latticecan be more robust when the input structure is given with only a few digits, e.g., hexagonal cells with \(\sqrt{3}/2\) written as 0.866025. In such cases, settingSYMMETRIZE_STRUCTURE = 1is recommended instead of, or in addition to,FCSYM_BASIS = Lattice.For more details about the symmetry reduction of force constants, please see here.
Important
When
FCSYM_BASIS = Lattice, the basis of force constants saved inPREFIX.fcs becomes the \(\boldsymbol{a}_1, \boldsymbol{a}_2, \boldsymbol{a}_3\) basis. Hence, to compare the values of force constants saved inPREFIX.fcs, you will have to change their basis to the Cartesian basis manually. The basis of force constants saved inPREFIX.xml is Cartesian irrespective of theFCSYM_BASISvalue.Also, imposing the constraints for rotational invariance with
FCSYM_BASIS = Latticeis not supported. Therefore, if you want to apply the constraints for rotational invariance, please useFCSYM_BASIS = Cartesian.
MAGMOM-tag : List of magnetic moments
- Default:
0 … 0 (
NATentries whenNONCOLLINEAR = 0, 3xNATentries whenNONCOLLINEAR = 1.)- type:
Array of double
- Example:
When a supercell contains 64 atoms and the local magnetic moments of the first 32 atoms are up and those of the last 32 atoms are down, please set the
MAGMOMtag asMAGMOM = 32*1 32*-1. The wildcard (*) is available whenNONCOLLINEAR = 0. For the noncollinear case (NONCOLLINEAR = 1), the wildcard is not supported. So, please give the magnetic moment explicitly asMAGMOM = 0 0 1 0 0 1 0 0 1 ... 0 0 -1 0 0 -1 ...(3\(\times\)NATentries in one line).Note
MAGMOMinformation is used only for generating space group operations. So, the values of the magnetic moment are somewhat arbitrary. For the 4\(\times\) 4\(\times\) 4 supercell of ferromagnetic bcc Fe (64 atoms), for instance,MAGMOM = 64*1andMAGMOM = 64*2give the same results. By contrast,MAGMOM = 32*1 32*2of course gives a different result because it breaks the symmetry of the original lattice.
NONCOLLINEAR-tag = 0 | 1
- Default:
0
- type:
Integer
- Description:
When
NONCOLLINEAR = 1, the code accepts a noncollinear magnetic structure as an input to theMAGMOMtag and uses it for generating space group operations. The spin quantization axis is fixed to the (0,0,1) direction of the Cartesian axis.Caution
Still experimental. Please use with care.
PERIODIC-tag = PERIODIC[1], PERIODIC[2], PERIODIC[3]
0
Do not consider periodic boundary conditions whensearching for interacting atoms.1
Consider periodic boundary conditions whensearching for interacting atoms.
- Default:
1 1 1
- type:
Array of integers
- Description:
This tag is useful for generating interacting atoms in low dimensional systems. When
PERIODIC[i]is zero, periodic boundary condition is turned off along the direction of the lattice vector \(\boldsymbol{a}_{i}\).
NMAXSAVE-tag : The maximum order of anharmonic force constants written to the force-constant files (
PREFIX.h5 andPREFIX.xml)
- Default:
min(5,
NORDER)- Type:
Integer
- Example:
If your model includes anharmonic terms up to the sixth-order (
NORDER = 5), but you want to avoid printing out the fifth-order and sixth-order IFCs, please setNMAXSAVE = 3.
FCS_ALAMODE-tag = 0 | 1
0
Write the force constants to
PREFIX.h5 only1
Additionally write the legacy
PREFIX.xml file and the plain-textPREFIX.fcs listing
- Default:
0
- Type:
Integer
- Description:
The HDF5 file
PREFIX.h5 is the standard force-constant output and is always written. SetFCS_ALAMODE = 1to also produce the legacy XML file and the human-readablePREFIX.fcs listing, e.g. for external tools that have not migrated to the HDF5 format yet. anphon reads both formats.
HESSIAN-tag = 0 | 1
0
Do not save the Hessian matrix
1
Save the entire Hessian matrix of the supercell as PREFIX.hessian.
- Default:
0
- type:
Integer
FC3_SHENGBTE-tag = 0 | 1
0
Do not save the third-order force constants for the ShengBTE code1
Save the third-order force constants for the ShengBTE code in PREFIX.FORCE_CONSTANTS_3RD.
- Default:
0
- type:
Integer
- Description:
The file has the layout of ShengBTE’s
FORCE_CONSTANTS_3RD: the force constants in eV/Å3 and the lattice vectors of the periodic images in Å, independent ofFCS_UNIT_OUTPUT. It is written only whenNORDER >= 2; otherwise a warning is printed and no file is written. ShengBTE reads a file namedFORCE_CONSTANTS_3RD, so remove thePREFIX.part or link the file. To convert existing force constants instead, see Converting force constants (phonopy, phono3py, ShengBTE).
FC4_SHENGBTE-tag = 0 | 1
0
Do not save the fourth-order force constants for the FourPhonon code1
Save the fourth-order force constants for the FourPhonon code in PREFIX.FORCE_CONSTANTS_4TH.
- Default:
0
- type:
Integer
- Description:
The file has the layout of
FORCE_CONSTANTS_4THread by FourPhonon, the four-phonon extension of ShengBTE: the force constants in eV/Å4 and the lattice vectors of the periodic images in Å, independent ofFCS_UNIT_OUTPUT. It is written only whenNORDER >= 3; otherwise a warning is printed and no file is written. Remove thePREFIX.part or link the file toFORCE_CONSTANTS_4TH.
FC_ZERO_THR-tag : Threshold value used when trimming force constants written to the force-constant files
- Default:
1.0e-12
- Type:
Double
- Description:
FC_ZERO_THRdefines the threshold of force constants to be saved inPREFIX.h5 (andPREFIX.xml). If the absolute value of a force constant is smaller thanFC_ZERO_THR, it will NOT be printed out.Note
If the harmonic force constants are calculated using a model potential (e.g., classical FF) where the interaction becomes zero beyond a certain cutoff radius, the default value of
FC_ZERO_THRmay drop small but nonzero force constants. This issue may be resolved by using a smallerFC_ZERO_THR, sayFC_ZERO_THR = 1.0e-15. The force constants that become exactly zero due to symmetry and acoustic sum rule constraints will not be printed even when settingFC_ZERO_THR = 0.
FORMAT_PATTERN-tag = yaml | old
yaml
Write the displacement-pattern files in the YAML format
old
Write them in the plain-text format of ALAMODE 1.x
- Default:
yaml
- Type:
String
- Description:
Format of the displacement-pattern files
PREFIX.pattern_HARMONIC,PREFIX.pattern_ANHARM3, … written withMODE = suggest.displace.py --pattern_filereads both formats;oldis kept for external scripts written for the 1.x format.
LENGTH_UNIT-tag = bohr | angstrom
- Default:
bohr
- Type:
String
- Description:
Unit of the length-type input data: the
&celllattice vectors, the displacements in theDFSETfile, and the&cutoffradii. The data are converted to Bohr internally, so the internal model and all outputs are unaffected. ASTRUCTURE_FILE(POSCAR) is always interpreted in Angstrom, independent of this tag.
FORCE_UNIT-tag = Ry/bohr | eV/angstrom | Ha/bohr
- Default:
Ry/bohr
- Type:
String
- Description:
Unit of the forces in the
DFSETfile, converted to Ry/bohr internally.
FCS_UNIT_OUTPUT-tag = Ry/bohr | eV/angstrom
- Default:
Ry/bohr
- Type:
String
- Description:
Unit system of the force constants written to the HDF5 file (
PREFIX.h5). WitheV/angstrom, the force constant values (eV/angstromn), the lattice vectors, and the shift vectors (angstrom) are converted consistently, and theunitattributes stored in the file are updated accordingly; anphon reads these attributes and converts the data back internally. The XML (PREFIX.xml) andPREFIX.fcs outputs always stay in Rydberg atomic units.
“&interaction”-field#
NORDER-tag : The order of force constants to be calculated. Anharmonic terms up to \((m+1)\)th order will be considered with
NORDER= \(m\).
- Default:
None
- Type:
Integer
- Example:
NORDER = 1to calculate harmonic terms only,NORDER = 2to include cubic terms as well, and so on.
NBODY-tag : Entry for excluding multiple-body interactions from anharmonic force constants
- Default:
NBODY= [2, 3, 4, …,NORDER+ 1]- Type:
Array of integers
- Description:
This tag may be useful for excluding multi-body clusters which are supposedly less important. For example, a set of fourth-order IFCs \(\{\Phi_{ijkl}\}\), where \(i, j, k\), and \(l\) label atoms in the supercell, can be categorized into four different subsets; on-site, two-body, three-body, and four-body terms. Neglecting the Cartesian coordinates of IFCs for simplicity, each subset contains the IFC elements shown as follows:
on-site
\(\{\Phi_{iiii}\}\)two-body
\(\{\Phi_{iijj}\}\), \(\{\Phi_{iiij}\}\) (\(i\neq j\))three-body
\(\{\Phi_{iijk}\}\) (\(i\neq j, i\neq k, j \neq k\))four-body
\(\{\Phi_{ijkl}\}\) (all subscripts are different from each other)Since the four-body clusters are expected to be less important than the three-body and less-body clusters, you may want to exclude the four-body terms from the Taylor expansion potential because the number of such terms is huge. This can be done by setting the
NBODYtag asNBODY = 2 3 3together withNORDER = 3.- More examples:
NORDER = 2; NBODY = 2 2includes harmonic and cubic IFCs but excludes three-body clusters from the cubic terms.
NORDER = 5; NBODY = 2 3 3 2 2includes anharmonic terms up to the sixth-order, where the four-body clusters are excluded from the fourth-order IFCs, and the multi (\(\geq 3\))-body clusters are excluded from the fifth- and sixth-order IFCs.
“&cutoff”-field#
In this entry field, one needs to specify cutoff radii of interaction for each order in units of bohr (or of LENGTH_UNIT if given).
In the current implementation, cutoff radii should be defined for every possible pair of atomic elements.
For example, the cutoff entry for a harmonic calculation (NORDER = 1) of Si should be like
&cutoff
Si-Si 10.0
/
This means that the cutoff radius of 10 \(a_{0}\) is used for harmonic Si-Si terms.
Please note that the first column should be two character strings, which are contained in the KD-tag,
connected by a hyphen (’-’).
When one wants to consider cubic terms (NORDER = 2), please specify the cutoff radius for cubic terms in the third column as the following:
&cutoff
Si-Si 10.0 5.6 # Pair r_{2} r_{3}
/
Instead of giving specific cutoff radii, one can write “None” as follows:
&cutoff
Si-Si None 5.6
/
which means that all possible harmonic terms between Si-Si atoms will be included.
Caution
Setting ‘None’ for anharmonic terms can greatly increase the number of parameters and thereby increase the computational cost.
When there are more than two atomic elements, please specify the cutoff radii between every possible pair of atomic elements. In the case of MgO, the cutoff entry should be like
&cutoff
Mg-Mg 8.0
O-O 8.0
Mg-O 10.0
/
which can equivalently be written by using the wild card (’*’) as
&cutoff
*-* 8.0
Mg-O 10.0 # Overwrite the cutoff radius for Mg-O harmonic interactions
/
Important
Cutoff radii specified by an earlier entry are overwritten by a new entry that comes later.
Once the cutoff radii are properly given, harmonic force constants \(\Phi_{i,j}^{\mu,\nu}\) satisfying \(r_{ij} \le r_{c}^{\mathrm{KD}[i]-\mathrm{KD}[j]}\) will be searched.
In the case of cubic terms, force constants \(\Phi_{ijk}^{\mu\nu\lambda}\) satisfying \(r_{ij} \le r_{c}^{\mathrm{KD}[i]-\mathrm{KD}[j]}\), \(r_{ik} \le r_{c}^{\mathrm{KD}[i]-\mathrm{KD}[k]}\), and \(r_{jk} \le r_{c}^{\mathrm{KD}[j]-\mathrm{KD}[k]}\) will be searched and determined by fitting.
“&cell”-field#
Please give the cell parameters in this entry in units of bohr (or of LENGTH_UNIT if given) as the following:
&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})\).
“&position”-field#
In this field, one needs to specify the atomic element and fractional coordinate of atoms in the supercell. Each line should be
ikd xf[1] xf[2] xf[3]
where ikd is an integer specifying the atomic element in the order of the KD tag and xf[i] is the
fractional coordinate of an atom. There should be NAT such lines in the &position entry field.
“&optimize”-field#
This field is necessary when MODE = optimize.
LMODEL-tag : Choice of the linear model used for estimating force constants
“least-squares”, “LS”, “OLS”, 1
Ordinary least square
“elastic-net”, “enet”, 2
Elastic net
“adaptive-lasso”, 3
Adaptive LASSO
- Default:
least-squares
- Type:
String
- Description:
When
LMODEL = ols, the force constants are estimated from the displacement-force datasets via the ordinary least-squares (OLS), which is usually sufficient to calculate harmonic and third-order force constants.The elastic net (
LMODEL = enet) or adaptive LASSO (LMODEL = adaptive-lasso) are useful for calculating fourth-order (and higher-order) force constants. When the elastic net or adaptive LASSO is selected, the users have to set the following related tags:CV,L1_RATIO,L1_ALPHA,CV_MAXALPHA,CV_MINALPHA,CV_NALPHA,STANDARDIZE,ENET_DNORM,MAXITER,CONV_TOL,NWRITE,SOLUTION_PATH,DEBIAS_OLS,STOP_CRITERION.
DFSET-tag: File name containing displacement-force datasets for training
- Default:
None
- Type:
String
- Description:
The format of
DFSETcan be found here
NDATA-tag : Number of displacement-force data sets
- Default:
None
- Type:
Integer
- Description:
If
NDATAis not given, the code reads all lines ofDFSET(excluding comment lines) and estimatesNDATAby dividing the line number byNAT. If the number of lines is not divisible byNAT, an error is raised.DFSETshould contain at leastNDATA\(\times\)NATlines.
NSTART, NEND-tags : Specifies the range of data to be used for training
- Default:
NSTART = 1,NEND = NDATA- Type:
Integer
- Example:
To use the data in the range of [20:30] out of 50 entries, the tags should be
NSTART = 20andNEND = 30.
SKIP-tag : Specifies the range of data to be skipped for training
- Default:
None
- Type:
Two integers connected by a hyphen
- Description:
SKIP=\(i\)-\(j\) skips the data in the range of [\(i\):\(j\)]. The \(i\) and \(j\) must satisfy \(1\leq i \leq j \leq\)NDATA. This option may be useful when doing cross-validation manually (CV=-1).
ICONST-tag = 0 | 1 | 2 | 3 | 4 | 11 | 12 | 13 | 14
0
No constraints
1
Constraint for translational invariance is imposed between IFCs.Available only whenLMODEL = ols.11
Same asICONST = 1but the constraint is imposed algebraically rather than numerically.Select this option whenLMODEL = enetoradaptive-lasso.2
In addition toICONST = 1, constraints for rotational invariance will beimposed up to (NORDER+ 1)th order. Available only whenLMODEL = ols.3
In addition toICONST = 2, constraints for rotational invariance between (NORDER+ 1)th orderand (NORDER+ 2)th order, which are zero, will be considered.Available only whenLMODEL = ols.4
In addition toICONST = 2, constraints for the Huang invariance will be imposed.Available only whenLMODEL = ols. For a stressed reference structure, seeSTRESS.12
Same asICONST = 2but imposed algebraically. Usable with anyLMODEL.13
Same asICONST = 3but imposed algebraically. Usable with anyLMODEL.14
Same asICONST = 4but imposed algebraically. Usable with anyLMODEL.Note
When
LMODEL = enetoradaptive-lasso,ICONST = 1, 2, 3, 4are not rejected but are treated asICONST = 11, 12, 13, 14, respectively, i.e., the constraints are imposed algebraically.Note
With
ICONST = 12, 13, 14, the inter-order rotational constraints make some higher-order IFCs linear functions of lower-order ones. These dependent IFCs are eliminated before the fit, so they are not penalized by the L1 term ofLMODEL = enetoradaptive-lasso. As inICONST = 2, 3, 4, inter-order constraints involving an order fixed byFC2FIXorFC3FIXare not imposed.Note
The rotational constraints (
ICONST = 2, 3, 4, 12, 13, 14) are built from the Cartesian atomic positions, so the input structure must be symmetric to nearly machine precision. If the lattice vectors or positions are given with only about 10 digits, the inter-order constraints have no clear rank, and the number of free parameters and the resulting IFCs may depend onICONST,ALGO_REDUCTION, andTOL_CONST. Give the structure with full double precision or setSYMMETRIZE_STRUCTURE = 1.Even with an exact structure, a structure with internal relaxation (atoms off high-symmetry positions) combined with a short cutoff of the highest order can give nearly dependent rotational constraints.
ICONST = 2, 3, 4and, with the defaultALGO_REDUCTION = 3,ICONST = 12, 13, 14drop those weaker thanTOL_CONST(relative, row by row). The otherALGO_REDUCTIONoptions, andALGO_REDUCTION = 3for constraint blocks too large for the dense QR in ALM built withoutUSE_SUITESPARSE_BACKEND, decide the rank in several Gauss-Jordan stages and may keep some of them, which shows up as a fitting error larger than withICONST = 2, 3, 4. In that case, useICONST = 2, 3, 4(withLMODEL = ols), or increaseTOL_CONSTor the cutoff radius.
- Default:
11
- Type:
Integer
- Description:
See this page for the numerical formulae.
PERIODIC_IMAGE_CONV-tag = 0 | 1
0
Impose the constraints on IFCs (acoustic sum rule) in the considering supercell.
1
Consider the periodic images when generating the constraints.The resultant IFCs simultaneously satisfy the permutation symmetry, ASR,and the space group symmetry in the infinite space.For more details, please see Appendix D of the original paper.(Note that we use the term “mirror image” instead of “periodic image” in the paper.)
- Default:
1
- Type:
Integer
ROTAXIS-tag : Rotation axis used to estimate constraints for rotational invariance. This entry is necessary when
ICONST = 2, 3, 4, 12, 13, 14.
- Default:
None
- Type:
String
- Example:
When one wants to consider the rotational invariance around the \(x\)-axis, one should give
ROTAXIS = x. If one needs additional constraints for the rotation around the \(y\)-axis,ROTAXISshould beROTAXIS = xy.
STRESS-tag : Cauchy stress \(\sigma\) of the reference structure (in GPa) used to generalize the Huang invariance
- Default:
None (stress-free Huang invariance)
- Type:
Array of double (6 or 9 values)
- Description:
The Huang invariance imposed with
ICONST = 4or14assumes a stress-free reference structure. When the reference structure is under a stress \(\sigma\), the long-wavelength condition becomes\[[\alpha\beta,\gamma\delta] - [\gamma\delta,\alpha\beta] = \sigma_{\gamma\delta}\delta_{\alpha\beta} - \sigma_{\alpha\beta}\delta_{\gamma\delta}, \quad [\alpha\beta,\gamma\delta] = -\frac{1}{2\Omega}\sum_{\kappa,\ell\kappa'} \Phi_{\alpha\beta}(0\kappa;\ell\kappa')\, x_{\gamma} x_{\delta},\]where \(\boldsymbol{x} = \boldsymbol{r}(\ell\kappa') - \boldsymbol{r}(0\kappa)\) and \(\Omega\) is the volume of the primitive cell.
STRESSgives \(\sigma\) either as 9 values (the \(3\times 3\) tensor, row by row) or as 6 Voigt values in the orderxx yy zz yz xz xy, in the Cartesian frame of the input lattice vectors.The sign convention is tension positive. Note that the stress printed by VASP (
in kBline of OUTCAR) is positive under compression: convert it as \(\sigma = -0.1 \times\) (VASP value) GPa. ASE’sget_stress()is already tension positive (in eV/Å3). LAMMPS reports the pressure tensor, so \(\sigma = -p\).The input tensor is symmetrized, \((\sigma + \sigma^{T})/2\), and averaged over the point group of the structure; the input and symmetrized tensors are printed, and a warning is shown when the removed part exceeds 1% of \(|\sigma|\). A hydrostatic stress does not change the Huang conditions.
STRESSis ignored (with a warning) unlessICONST = 4or14.- Example:
STRESS = 1.2 0.1 0.7 0 0 0.2(Voigt, GPa)
ALGO_REDUCTION-tag = 0 | 1 | 2 | 3 | 4
0
No separate reduction step; the elimination map is built by sparseGauss-Jordan elimination, i.e., the same result asALGO_REDUCTION = 11
Sparse Gauss-Jordan elimination (legacy)
2
Rank-revealing QR row selection followed by sparse Gauss-Jordan elimination
3
Rank-revealing QR row selection with the scale-freeTOL_CONSTtest, followed by sparseGauss-Jordan elimination with threshold pivoting. Higher-order IFCs are expressed throughlower-order ones where the pivot size allows; the log reports how many relations go the otherway. WithoutUSE_SUITESPARSE_BACKEND, blocks above 5e7 matrix elements use the Gauss-Jordanelimination with partial pivoting of earlier versions.4
Reduced echelon form from a sparse Householder QR (SuiteSparseQR) with scale-aware rankdetection. Requires ALM built withUSE_SUITESPARSE_BACKEND.
- Default:
3
- Type:
Integer
- Description:
Algorithm used to reduce the constraints to an elimination map when
ICONST >= 11. All options keep the independent parameters as individual IFCs;ICONST = 1, 2, 3, 4always use a rank-revealing QR.
FC2FIX-tag : File to which the harmonic terms are fixed upon training
- Default:
None
- Type:
String
- Description:
When the
FC2FIX-tag is given, harmonic force constants are fixed to the values stored in theFC2FIXfile. This may be useful for optimizing cubic and higher-order terms without changing the harmonic terms. Please make sure that the number of harmonic terms in the new computational condition is the same as that in theFC2FIXfile.Note
FC2XMLis a deprecated alias ofFC2FIXkept for backward compatibility. It will be removed in a future release, so please useFC2FIXinstead.Important
When
FC2FIXis an XML file, theFCSYM_BASISoption must be the same as the one used when creating it. IfFCSYM_BASISis not given, the basis recorded in the XML file is used, so files created with the old default (Lattice, before version 2.0) still work. An explicitly givenFCSYM_BASISthat differs from the file raises an error. An HDF5 (.h5) file can be used with either basis.
FC3FIX-tag : File to which the cubic terms are fixed upon training
- Default:
None
- Type:
String
- Description:
Same as the
FC2FIX-tag, butFC3FIXis used to fix cubic force constants. (FC3XMLis a deprecated alias ofFC3FIX.)Important
When
FC3FIXis an XML file, theFCSYM_BASISoption must be the same as the one used when creating it. IfFCSYM_BASISis not given, the basis recorded in the XML file is used, so files created with the old default (Lattice, before version 2.0) still work. An explicitly givenFCSYM_BASISthat differs from the file raises an error. An HDF5 (.h5) file can be used with either basis.
SPARSE-tag = 0 | 1
0
Use a direct solver (SVD or QRD) to estimate force constants
1
Use a sparse solver to estimate force constants
- Default:
0
- Type:
Integer
- Description:
When you want to calculate force constants of a large system and generate training datasets by displacing only a few atoms from equilibrium positions, the resulting sensing matrix becomes large but sparse. For such matrices, a sparse solver is expected to be more efficient than SVD or QRD in terms of both memory usage and computational time. Effective when
LMODEL = ols.When to use: prefer
SPARSE = 1for large systems whose sensing matrix is genuinely sparse (only a handful of atoms displaced per configuration). For small or dense problems the default direct solvers (SPARSE = 0) are usually faster, and the sparse factorization can even use more memory because of fill-in. When the sensing matrix is dense but large, consider USE_CHOLESKY instead.Note
The sparse path has two different solver routes. With algebraic constraints (
ICONST >= 10; the default isICONST = 11), the reduced sparse least-squares problem is solved by theSPARSESOLVERselected below. With constraints imposed numerically (ICONST = 1, 2, 3, 4), the sparse path instead assembles the symmetric-indefinite KKT system. The merged constraint matrix is first reduced to full row rank by a rank-revealing QR (essential: a rank-deficient constraint matrix makes the KKT singular and the fitted IFCs violate the acoustic-sum-rule / rotational invariance). The KKT solver is then chosen by build: Intel MKL PARDISO (-DUSE_MKL_BACKEND=yes) or Apple Accelerate (-DUSE_ACCEL_BACKEND=yes) use a symmetric-indefiniteLDLT; SuiteSparse (-DUSE_SUITESPARSE_BACKEND=yes) adds the multithreaded SuiteSparseQR fallback; otherwise Eigen’s serialSparseLUandSparseQRfallbacks are used. See Optional linear-algebra backends on the installation page.
SPARSESOLVER-tag : Type of the sparse solver to use
- Default:
SimplicialLDLT
- Type:
String
- Description:
Selects the sparse solver used for the unconstrained or algebraically constrained sparse OLS fit (
LMODEL = ols,SPARSE = 1, andICONST >= 10). Available options are SimplicialLDLT (sparse Cholesky on the normal matrix, direct), SparseQR (direct sparse QR), and the iterative Krylov solvers ConjugateGradient, LeastSquaresConjugateGradient, and BiCGSTAB. When an iterative solver is selected, the stopping criterion is controlled by theCONV_TOLandMAXITERtags. As a rule of thumb, use SimplicialLDLT (the default) for well-conditioned problems, SparseQR when the direct factorization fails or the matrix is poorly conditioned, and the iterative solvers when even the sparse factorization is too large to store.Two additional high-performance solvers are available when ALM is built with the SuiteSparse backend (
-DUSE_SUITESPARSE_BACKEND=yes; see Optional linear-algebra backends): SuiteSparseQR, a multithreaded rank-revealing multifrontal sparse QR that factorizes the rectangular sensing matrix directly (a faster, parallel alternative to SparseQR for large or ill-conditioned problems), and CHOLMOD, a supernodal sparse Cholesky on the normal matrix \(A^{\mathsf T}A\) (a faster alternative to SimplicialLDLT for well-conditioned problems). Selecting either of these without building the SuiteSparse backend stops with an error.With numerically imposed constraints (
ICONST = 1, 2, 3, 4), most values ofSPARSESOLVERdo not select the KKT direct solver. The code first tries the KKT backend compiled into the executable (MKL/PARDISO or Apple/Accelerate LDLT), then SuiteSparseQR if the SuiteSparse backend is enabled, then Eigen’s built-in sparse fallbacks. MINRES is the special exception (experimental): selectingSPARSESOLVER = MINRESchooses an iterative solver for this KKT path. It never forms the dense factor used by direct solvers, so it can be the memory-feasible choice when direct KKT factorizations exhaust memory because the constraint matrix has dense rows (the rotational-invariance constraints ofICONST = 2, 3). It is preconditioned by a block-diagonal SPD preconditioner (Jacobi on \(A^{\mathsf T}A\) plus the dense constraint Schur complement);CONV_TOLandMAXITERcontrol the stopping criterion. After the solve it checks the true KKT residual and\|C x - d\|and aborts if they are not met, rather than returning a solution that would violate the sum rules. On badly-scaled or extremely ill-conditioned KKT systems the simple block-diagonal preconditioner may be insufficient and MINRES will report non-convergence – in that case raiseMAXITER/ loosenCONV_TOL, or use a direct LDLT backend on a reduced problem.
SPARSESOLVERis ignored byUSE_CHOLESKY = 1. In that mode the code forms \(A^{\mathsf T}A\) directly and uses a sparse Cholesky factorization (CHOLMOD when the SuiteSparse backend is available, otherwise SimplicialLDLT).See also
Eigen documentation page: Solving Sparse Linear Systems
USE_CHOLESKY-tag = 0 | 1
0
Use a direct solver (SVD or QRD) to estimate force constants
1
Solve the normal equations by Cholesky decomposition
- Default:
0
- Type:
Integer
- Description:
When
USE_CHOLESKY = 1, the ordinary least-squares fit is obtained by forming the normal equations \(A^{\mathsf{T}} A\,\boldsymbol{\Phi} = A^{\mathsf{T}} \boldsymbol{b}\) and factorizing \(A^{\mathsf{T}} A\) with a Cholesky decomposition (a denseLLT, or a sparse Cholesky factorization whenSPARSE = 1:CHOLMODwith the SuiteSparse backend, otherwiseSimplicialLDLT). This is typically about twice as fast and uses noticeably less memory than the default SVD/QRD direct solvers, which makes it attractive for large, well-conditioned overdetermined fits (many more rows than columns). The trade-off is accuracy: forming \(A^{\mathsf{T}} A\) squares the condition number of \(A\), so the solution degrades when the sensing matrix is ill-conditioned. Keep the defaultUSE_CHOLESKY = 0(SVD/QRD) when robustness matters or the fit is close to rank-deficient. Effective whenLMODEL = ols.Important
USE_CHOLESKY = 1cannot be combined with the numerically imposed constraintsICONST = 1, 2, 3, 4. When constraints are required, impose them algebraically withICONST = 11, 12, 13, 14instead; otherwise the code stops with an error.
CHUNKSIZE-tag : Number of configurations processed per pass when building \(A^{\mathsf{T}} A\)
- Default:
100
- Type:
Integer
- Description:
Relevant only when
USE_CHOLESKY = 1. Instead of forming the full dense sensing matrix \(A\) (size \(N_{\mathrm{rows}} \times N_{\mathrm{cols}}\)) at once, the normal-equations matrix \(A^{\mathsf{T}} A\) is accumulated in chunks ofCHUNKSIZEtraining configurations: for each chunk only a small block of \(A\) is built and added into \(A^{\mathsf{T}} A\). This caps the peak memory at roughly the larger of \(A^{\mathsf{T}} A\) itself and one chunk’s block (proportional toCHUNKSIZE\(\times\, N_{\mathrm{cols}}\)), rather than the full \(A\). A smallerCHUNKSIZElowers the peak memory but uses more passes with smaller, less efficient matrix products; a largerCHUNKSIZEis faster but needs more memory. Lowering it below the point where one chunk is already smaller than \(A^{\mathsf{T}} A\) gives no further savings, since \(A^{\mathsf{T}} A\) sets the memory floor. The default (100) is a reasonable balance; reduce it if the chunk block does not fit in memory.
NWRITE-tag : Interval of the progress output of iterative L1 solvers
- Default:
1000
- Type:
Integer
- Description:
The progress of the L1 solver iteration (
LMODEL = enet | adaptive-lasso) is printed everyNWRITEiterations whenVERBOSITY >= 2is set in the&generalfield.
MAXITER-tag : Number of maximum iterations in iterative algorithms
- Default:
10,000
- Type:
Integer
- Description:
Effective when an iterative solver is selected via
SPARSESOLVER(whenLMODEL = ols) or whenLMODEL = enet | adaptive-lasso.
CONV_TOL-tag : Convergence criterion of iterative algorithms
- Default:
1.0e-8
- Type:
Double
- Description:
When
LMODEL = olsand an iterative solver is selected viaSPARSESOLVER,CONV_TOLvalue is passed to the Eigen3 function via setTolerance(). WhenLMODEL = enet | adaptive-lasso, the L1 solver iteration stops at \(i\)th iteration if \(\sqrt{\frac{1}{N}|\boldsymbol{\Phi}_{i} - \boldsymbol{\Phi}_{i-1}|_{2}^{2}} <\)CONV_TOLis satisfied, where \(N\) is the length of the vector \(\boldsymbol{\Phi}\).See also
Eigen documentation page: IterativeSolverBase
L1_RATIO-tag : The ratio of the L1 regularization term
- Default:
1.0 (LASSO)
- Type:
Double
- Description:
The
L1_RATIOchanges the regularization term asL1_ALPHA\(\times\) [L1_RATIO\(|\boldsymbol{\Phi}|_{1}\) + \(\frac{1}{2}\) (1-L1_RATIO) \(|\boldsymbol{\Phi}|_{2}^{2}\)]. Therefore,L1_RATIO = 1corresponds to LASSO.L1_RATIOmust be0 < L1_ratio <= 1. Effective whenLMODEL = enet. See also here.
L1_SOLVER-tag = cd | fista | admm
cd
Use the coordinate descent solver.
fista
Use the fast iterative shrinkage-thresholding algorithm.
admm
Use the alternating direction method of multipliers (experimental).
- Default:
cd
- Type:
String
- Description:
Selects the iterative solver used when
LMODEL = enet | adaptive-lasso. All three solvers target the same elastic-net or adaptive-LASSO objective and are interchangeable. Thecdsolver is the coordinate descent method; it warm-starts along the cross-validation alpha path and is the fastest choice for that path, so it is the recommended default. Thefistasolver avoids forming the dense \(N \times N\) Gram matrix and can reduce memory usage for large dense L1-regularized problems. Theadmmsolver is provided mainly for research and cross-checking; on warm-started alpha paths it is generally slower thancdand offers no advantage for the typical problem sizes here.
L1_ALPHA-tag : The coefficient of the L1 regularization term
- Default:
0.0
- Type:
Double
- Description:
This tag is used when
LMODEL = enet | adaptive-lassoandCV = 0. See also here.
CV-tag : Cross-validation mode for elastic net
0
Cross-validation mode is off.The elastic net optimization is solved with the givenL1_ALPHAvalue.The force constants are written toPREFIX.h5 (andPREFIX.xml /PREFIX.fcs withFCS_ALAMODE = 1).>= 2
CV-fold cross-validation is performed automatically.NDATAtraining datasets are divided intoCVsubsets, andCVdifferent combinations oftraining-validation datasets are created internally. For each combination, the elastic netoptimization is solved with the variousL1_ALPHAvalues defined by theCV_MINALPHA,CV_MAXALPHA, andCV_NALPHAtags. The result of each cross-validation is stored inPREFIX.cvset[1, …,CV], and their average and deviation are stored inPREFIX.cvscore.-1
The cross-validation is performed manually.The Taylor expansion potential is trained by using the training datasets inDFSET, andthe validation score is calculated by using the data inDFSET_CVfor variousL1_ALPHAvaluesdefined by theCV_MINALPHA,CV_MAXALPHA, andCV_NALPHAtags.After the calculation, the fitting and validation errors are stored inPREFIX.cvset.This option may be convenient for a large-scale problem since multiple optimization tasks withdifferent training-validation datasets can be done in parallel.
- Default:
0
- Type:
Integer
- Description:
This tag is used when
LMODEL = enet | adaptive-lasso.
DFSET_CV-tag : File name containing displacement-force datasets used for manual cross-validation
- Default:
DFSET_CV = DFSET- Type:
String
- Description:
This tag is used when
LMODEL = enet | adaptive-lassoandCV = -1.
NDATA_CV-tag : Number of displacement-force validation datasets
- Default:
None
- Type:
Integer
- Description:
This tag is used when
LMODEL = enet | adaptive-lassoandCV = -1.
NSTART_CV, NEND_CV-tags : Specifies the range of data to be used for validation
- Default:
NSTART_CV = 1,NEND_CV = NDATA_CV- Type:
Integer
- Description:
This tag is used when
LMODEL = enet | adaptive-lassoandCV = -1.
CV_MINALPHA, CV_MAXALPHA, CV_NALPHA-tags : Options to specify the
L1_ALPHAvalues used in cross-validation
- Default:
CV_MAXALPHAis set automatically
CV_MINALPHA = CV_MAXALPHA * 1.0e-6
CV_NALPHA = 50- Type:
Double, Double, Integer
- Description:
CV_NALPHAvalues ofL1_ALPHAare generated fromCV_MINALPHAtoCV_MAXALPHAin logarithmic scale. WhenCV_MAXALPHAis not specified by user, the code automatically setsCV_MAXALPHAso that the maximumL1_ALPHAmakes all coefficients zero. The default value ofCV_MINALPHAisCV_MAXALPHA * 1.0e-6, which is reasonable in many cases. If the minimum value of the validation score is found atCV_MINALPHA, you may need to use a smaller value ofCV_MINALPHA. This tag is used whenLMODEL = enet | adaptive-lassoand the cross-validation mode is on (CV > 0orCV = -1).
STANDARDIZE-tag = 0 | 1
0
Do not standardize the sensing matrix
1
Each column of the sensing matrix is standardized in such a way that its mean valuebecomes 0 and standard deviation becomes 1.
- Default:
1
- Type:
Integer
- Description:
This option influences the optimal
L1_ALPHAvalue. So, if you change theSTANDARDIZEoption, you have to rerun the cross-validation. Effective whenLMODEL = enet | adaptive-lasso.
ENET_DNORM-tag : Normalization factor of atomic displacements
- Default:
1.0
- Type:
Double
- Description:
The normalization factor of atomic displacement \(u_{0}\) in units of bohr. When \(u_{0} (\neq 1)\) is given, the displacement data are scaled as \(u_{i} \rightarrow u_{i}/u_{0}\) before constructing the sensing matrix. This option influences the optimal
L1_ALPHAvalue. So, if you change theENET_DNORMvalue, you will have to rerun the cross-validation. Effective only whenLMODEL = enetandSTANDARDIZE = 0.
SOLUTION_PATH-tag = 0 | 1
0
Do not save the solution path.
1
Save the solution path inPREFIX.solution_path (CV = -1) or, for eachcross-validation subset, inPREFIX.solution_path1, …,PREFIX.solution_pathN (CV >= 2).
- Default:
0
- Type:
Integer
- Description:
Effective when
LMODEL = enet | adaptive-lassoand the cross-validation mode is on.
DEBIAS_OLS-tag = 0 | 1
0
Save the solution of the L1-regularized problem to the force-constant files.
1
After the solution of the elastic net or adaptive LASSO optimization problem is obtained,only non-zero coefficients are collected, and the ordinary least-squares fitting issolved again with the non-zero coefficients before saving the results to the force-constantfiles. This might be useful to reduce the bias of the L1-regularized solution.
- Default:
0
- Type:
Integer
- Description:
Effective when
LMODEL = enet | adaptive-lassoandCV = 0.
STOP_CRITERION-tag : The scan over
L1_ALPHAstops when the cross-validation score keeps increasing inSTOP_CRITERIONconsecutive steps
- Default:
5
- Type:
Integer
- Description:
Effective when
LMODEL = enet | adaptive-lassoand the cross-validation mode is turned on (CV > 0orCV = -1).
How to make a DFSET file#
Format of DFSET#
The displacement-force data sets obtained by first-principles (or classical force-field) calculations
have to be saved to a file, say DFSET. Then, the force constants are estimated by setting DFSET = DFSET and with MODE = optimize.
The DFSET file must contain the atomic displacements and corresponding forces in Cartesian coordinate for at least NDATA structures (displacement patterns)
in the following format (one line per atom, blocks separated by an optional
comment line beginning with #):
# Structure number 1 (this is just a comment line)
u_x(1) u_y(1) u_z(1) f_x(1) f_y(1) f_z(1)
u_x(2) u_y(2) u_z(2) f_x(2) f_y(2) f_z(2)
... ... ... ... ... ...
u_x(NAT) u_y(NAT) u_z(NAT) f_x(NAT) f_y(NAT) f_z(NAT)
# Structure number 2
u_x(1) u_y(1) u_z(1) f_x(1) f_y(1) f_z(1)
... ... ... ... ... ...
Here, NAT is the number of atoms in the supercell.
The unit of displacements and forces must be bohr and Ry/bohr, respectively,
unless other units are declared with the LENGTH_UNIT and
FORCE_UNIT tags (e.g., LENGTH_UNIT = angstrom; FORCE_UNIT = eV/angstrom
for data taken directly from VASP output).