5. Migrating from 1.x to 2.0#
This page lists what a user of version 1.5 has to change, and what will look different, when moving to ALAMODE 2.0. New features are described in the input-variable pages; see also the ChangeLog.
In short:
Inputs. anphon rejects unknown tags field by field, so a 1.5 input with
FCSXML,NKD, orISOTOPEin&analysisstops at once. Rename and move the tags as shown in Changes in anphon input.Files. alm writes
PREFIX.h5 instead ofPREFIX.xml, and anphon keeps its results and restart data inPREFIX.kappa.h5,PREFIX.scph.h5, andPREFIX.qha.h5.Numbers. Isotope scattering is on by default, and several fixes change the thermal conductivity. See Results that change.
Build. HDF5 and spglib are required, FFTW is no longer used, and CMake >= 3.17 and a C++17 compiler are needed.
5.1. Building#
Item |
1.5 |
2.0 |
|---|---|---|
CMake |
>= 3.1 |
>= 3.17 |
C++ standard |
C++14 |
C++17 |
HDF5 |
optional ( |
required by alm and anphon |
spglib |
alm only |
required by alm and anphon |
FFTW3 |
required by anphon (unless MKL) |
not used |
Boost |
any version |
>= 1.67 (headers only) |
OpenMP |
optional |
required by alm |
Intel MKL |
– |
supported through |
Optional backends |
– |
|
Python interface |
separate project |
|
cmake --install (or make install) now installs the binaries and the common scripts; see Installation.
The legacy Makefile.* files of 1.x (in alm/, anphon/ and tools/) are removed; CMake is the only
supported build.
5.2. Changes in alm#
Tag |
1.5 |
2.0 |
|---|---|---|
|
default 1: |
default 0: only |
|
default |
default |
|
required |
optional; |
|
fix FC2 / FC3 to an XML file |
renamed |
|
0, 1, 2, 3, 11 |
0–4, 10–14: Huang invariance (4, 14), algebraic rotational invariance (12–14), see ICONST |
|
|
|
|
plain-text |
YAML |
New tags you may want when updating old inputs: STRUCTURE_FILE (read a POSCAR), SUPERCELL and PRIMCELL
(build the supercell and the primitive cell inside alm, see SUPERCELL and
PRIMCELL), SYMMETRIZE_STRUCTURE, and the unit tags
LENGTH_UNIT, FORCE_UNIT, and FCS_UNIT_OUTPUT (LENGTH_UNIT).
Notes on the changed defaults:
FCSYM_BASIS. For
LMODEL = olsthe force constants do not depend on the basis. Withenetoradaptive-lassothe optimalL1_ALPHAcan change, so redo the cross-validation. An XML file of 1.5 given asFC2FIX/FC3FIXkeeps working: without an explicitFCSYM_BASIS, alm uses the basis recorded in that file. alm now warns when the input structure deviates from its space group by more than \(10^{-6}\) bohr. In that case, give the coordinates with full precision or set SYMMETRIZE_STRUCTURE = 1.Constraints. With rotational or Huang constraints (
ICONST = 2, 3, 4), constraint rows that are nearly linearly dependent are now dropped, using a relative test with TOL_CONST (default \(10^{-6}\), as in 1.5);ICONST = 1skips this test. Such rows occur, for example, for internally relaxed structures combined with a short cutoff, where imposing them exactly inflates the fitting error. When no row is dropped, the results are the same as before. The algebraic constraints (ICONST >= 11) are reduced by a new algorithm (ALGO_REDUCTION, default 3), which is much faster for large models.Stressed reference structures. The new
STRESStag in&optimizegeneralizes the Huang conditions ofICONST = 4, 14to a reference structure under stress (STRESS).
Input checks are stricter. The following inputs are now errors:
a
DFSETline that does not hold exactly six finite numbers;ICONSToutside 0–4 and 10–14, an invalidROTAXIS,SKIP = 0, andTOLERANCE <= 0;trailing characters after a number (
1.0abc), andnanorinfin numeric fields;a
&cutoffentry that is neither a number nor a token starting withN(None), and unknown element names in&cutoff. Extra columns in a&cutoffline are ignored with a warning;negative
NDATA,NSTART,NEND, data ranges beyond theDFSETsize, duplicateKDentries, andFC2FIX/FC3FIXequal to the output file.
5.3. Changes in anphon input#
anphon stops with Could not recognize the variable ... when a field contains a tag it does not know.
The table lists how 1.5 inputs are treated.
1.5 input |
2.0 |
What to do |
|---|---|---|
|
error |
Use |
|
error |
Delete it. |
|
error |
Delete it. In 1.5, |
|
error |
Move them to the new |
|
error |
Removed. |
|
warning |
Use |
|
warning |
Move it to |
|
accepted, deprecated |
Prefer |
|
warning |
Use |
|
ignored, warning |
|
|
required |
Optional when |
Default changes:
Tag |
1.5 |
2.0 |
Effect |
|---|---|---|---|
|
0 |
1 |
Isotope scattering with natural abundances is included; set |
|
– |
1 |
Time-reversal symmetry also reduces the \(k\) meshes; fewer irreducible points for non-centrosymmetric crystals.
|
|
– |
1 |
SCPH iterations use DIIS mixing; |
|
– |
h5 |
Restart and eigenvector files are HDF5; |
Thermal conductivity, 1.5:
&general
PREFIX = si222
MODE = RTA
NKD = 1; KD = Si
FCSXML = si222.xml
/
&cell
...
/
&kpoint
2
10 10 10
/
&analysis
ISOTOPE = 2
KAPPA_SPEC = 1
/
and 2.0:
&general
PREFIX = si222
MODE = kappa
FCSFILE = si222.h5 # or si222.xml from 1.5
/
&kpoint
2
10 10 10
/
&kappa
ISOTOPE = 2
KAPPA_SPEC = 1
/
Here &cell was dropped because si222.h5 holds the primitive cell. Keep it when alm was run without
PRIMCELL or when FCSFILE is an XML file.
anphon also checks the input more strictly. A 1.5 input may stop for one of these reasons:
The
&cellmust tile the supercell ofFCSFILEexactly. A lattice constant rounded to a few digits makes the transformation matrix non-integer and stops the run: give the lattice constant with full precision, or omit&cellwith an HDF5 file. A left-handed&cell, a&celllarger than the supercell, and, withNONANALYTIC = 2, an FC2 supercell so skewed that some minimum-distance images lie beyond the 26 neighbouring supercells are errors (useNONANALYTIC = 1or3, or a near-orthogonal supercell, in that case).BORNINFOmust hold exactly \(\varepsilon_\infty\) and one \(Z^*\) tensor per atom.Range checks:
DT > 0,TMIN <= TMAX,TMIN >= 0,DELTA_E > 0,EPSILON > 0forISMEAR = 0, 1,0 < TOLERANCE < 0.5,MASS > 0with one value per species,NBANDSnot larger than the number of modes.Malformed numbers, such as
ISOFACT = abcor4.5for a mesh size in&kpoint, are now rejected (earlier versions read them as 0 and 4).EMINandEMAXnow set the DOS energy range (1.5 resetEMINto 0 and followed the eigenvalue range).
5.4. SCPH, QHA, and structural optimization#
Temperature-dependent harmonic force constants. In 1.5, the SCPH (or QHA) force constants were used in a later run
by converting PREFIX.scph_dfc2 with the dfc2 program:
$ dfc2 si222.xml si222_300K.xml si222.scph_dfc2 300
# in the kappa input
FCSXML = si222.xml
FC2XML = si222_300K.xml
In 2.0, anphon reads them from the SCPH result file:
FCSFILE = si222.h5
DFC2FILE = si222.scph.h5
FC2_TEMPERATURE = 300
DFC2FILE adds the correction of FC2_TEMPERATURE to the harmonic force constants of FCSFILE (or FC2FILE),
which may come from a larger supercell than the SCPH run.
Use the same NONANALYTIC and BORNINFO as the SCPH run.
For MODE = kappa, run one temperature per calculation with TMIN = TMAX = FC2_TEMPERATURE.
The results then accumulate in one PREFIX.kappa.h5.
See DFC2FILE and FC2_TEMPERATURE.
tools/dfc2.py (HDF5 version of dfc2) and the dfc2 program are still shipped. Both read the
PREFIX.scph_dfc2 files of 1.x and 2.0.
Relaxed structures. The 1.5 note that the structural optimization cannot be combined with thermal conductivity or bubble calculations no longer applies:
BUBBLE = 1, 2, 3can be used withRELAX_STR > 0.FE_BUBBLEstill cannot.RELAXED_STRUCTURE = 1withFC2_TEMPERATUREruns any mode (kappa,phonons, …) on the structure relaxed at that temperature. The state file of the relaxation run must be given asDFC2FILE(orFC2FILE,FCSFILE); its prefix is that of the earlier run, not thePREFIXof the new one (RELAXED_STRUCTURE). For example:PREFIX = bto_kappa_300K MODE = kappa FCSFILE = bto.h5 DFC2FILE = bto_relax.scph.h5 # written by the SCPH run with PREFIX = bto_relax and RELAX_STR > 0 FC2_TEMPERATURE = 300 RELAXED_STRUCTURE = 1 TMIN = 300; TMAX = 300
Cell relaxation inputs. STRAIN_COUPLING (&relax) replaces the RENORM_* tags.
Its units digit adds up the inputs read from the strain-coupling files: 1 = elastic constants,
2 = strain–force coupling, 4 = strain–harmonic-IFC coupling (STRAIN_COUPLING).
The default, 7, reads all three, which is what the 1.5 defaults did.
1.5 |
2.0 |
|---|---|
(defaults: |
|
|
clear bit 2, e.g. |
|
tens digit 1, e.g. |
|
tens digit 2, e.g. |
|
clear bit 4, e.g. |
|
bit 4; a subset of strain patterns is detected from the file |
The old tags still work; the warning they print names the equivalent STRAIN_COUPLING value.
The text files in STRAIN_IFC_DIR still work, and the HDF5 container STRAINFILE (made by the strain tools,
Tools for the cell-relaxation inputs (strainifc.py, elastic.py, strainfile.py)) is the recommended replacement.
Elastic constants in the text files may now be given in GPa.
Convergence. Temperatures whose SCPH iteration or structural optimization did not converge are flagged in
PREFIX.scph.h5 / PREFIX.qha.h5. Their free energy, heat capacity, and entropy in .scph_thermo / .qha_thermo (and
the DOS, MSD, and ucorr rows) are written as NaN unless ALLOW_UNCONVERGED = 1. Later runs refuse to read those
temperatures unless ALLOW_UNCONVERGED = 1.
5.5. Output files#
The formats of the HDF5 files are described in HDF5 files.
1.5 |
2.0 |
Note |
|---|---|---|
|
|
old files with |
|
|
results and restart data (Thermal conductivity (PREFIX.kappa.h5)); |
|
|
results and restart data (SCPH and QHA results (PREFIX.scph.h5, PREFIX.qha.h5)); |
|
|
|
|
|
same datasets; text |
– |
|
new tag |
|
|
|
– |
|
|
The text outputs (.bands, .dos, .thermo, .kl, .kl_spec, .self_isotope, .scph_bands,
.scph_thermo, .scph_dfc2, .V0, …) are still written in both formats.
.scph_thermo and .qha_thermo now hold the free energies with full precision.
With BCONNECT = 1, 2, the bands are now matched by eigenvectors and frequencies, also across breaks of the path.
The matching also applies to .scph_bands and .qha_bands (BCONNECT).
The log and the HDF5 files record the input variables and the git commit of the binary.
Restarting from 1.5 files. A PREFIX.result file is imported into PREFIX.kappa.h5 once and left untouched,
provided that the restart is enabled (RESTART, on by default when the file exists), FC2_TEMPERATURE is not
given, and PREFIX.kappa.h5 holds no linewidths of that channel yet.
Since TREVSYM = 1 changes the irreducible \(k\) points of non-centrosymmetric crystals,
continue such a run with TREVSYM = 0 (or start with a new PREFIX).
PREFIX.scph_dymat files of 1.x are read as they are for NONANALYTIC = 0, converted for NONANALYTIC = 2, 3,
and refused for NONANALYTIC = 1 (see Force constants and corrections with NONANALYTIC > 0).
Migrated text restart data are not marked as converged.
A restart starts automatically when PREFIX.kappa.h5, PREFIX.scph.h5, … (or the 1.5 text files) exist.
Remove them or change PREFIX to start from scratch.
5.6. Results that change#
Rerunning a 1.5 input with 2.0 can give different numbers for these reasons:
Isotope scattering is on (
ISOTOPE = 1), which lowers \(\kappa\), most strongly around its low-temperature peak.Group velocities. The thermal conductivity uses the velocity matrix of degenerate blocks, which does not depend on the choice of eigenvectors. 1.5 took finite differences of sorted eigenvalues, which mixes branches at crossings and degeneracies. The change is large in supercells and for degenerate branches: a supercell and the primitive cell sampled at the same \(q\) points now give the same \(\kappa\). The velocities are also symmetrized over the little group of \(k\), and the translational modes at \(\Gamma\) have zero velocity.
Tetrahedron weights (
ISMEAR = -1) are averaged over the symmetry-equivalent triplets and the degenerate modes for the three-phonon and isotope linewidths,SELF_W, andFSTATE_W.Time-reversal symmetry (
TREVSYM = 1) can shift the results of non-centrosymmetric crystals slightly withISMEAR = -1, within the \(k\)-mesh convergence error.Physical constants are the CODATA 2018 values instead of older hard-coded constants, which changes the last digits.
Non-analytic correction with
NONANALYTIC = 1(Parlinski): the phase factor of the non-analytic term now uses the atomic positions of the primitive cell, the gauge of the force constants, instead of those of the mapped supercell atoms. Results of new runs can therefore differ from 1.5 when the two positions differ by a lattice vector.alm results change when the default
FCSYM_BASISmatters (enet,adaptive-lasso) and when nearly dependent constraints are dropped (see Changes in alm).
Example: Si. The table compares \(\kappa_{xx}\) (W/mK, RTA) of the Si tutorial run by the 1.5.0 and 2.0 binaries
with the same force constants: one alm 2.0 fit of example/Si/reference/DFSET_harmonic and DFSET_cubic
(the settings of test/test_si.py), written as .xml and read by both versions
(2.0 gives the same numbers from the .h5 file of the same fit).
The anphon input is the 1.5 tutorial input: KD = Si, MASS = 28.0855, the fcc primitive cell with
\(a = 10.203\) Bohr, a \(10\times 10\times 10\) \(k\) mesh, the tetrahedron method (ISMEAR = -1, the default
of both versions), and ISOTOPE set explicitly (in &analysis for 1.5, in &kappa for 2.0).
Version and |
20 K |
50 K |
100 K |
300 K |
1000 K |
|---|---|---|---|---|---|
1.5.0, |
41339 |
4942.7 |
817.88 |
112.25 |
29.832 |
2.0, |
39431 |
5063.8 |
821.58 |
112.35 |
29.934 |
1.5.0, |
2305.6 |
1504.0 |
553.52 |
104.35 |
29.198 |
2.0, |
2366.0 |
1485.4 |
551.46 |
104.37 |
29.285 |
At 300 K, the default isotope scattering lowers \(\kappa\) by 7.1 % (112.35 to 104.37 W/mK), and the other changes (velocities, tetrahedron weights, constants) change it by less than 0.1 % (112.25 to 112.35 W/mK without isotopes). The remaining differences grow at low temperature, where \(\kappa\) on this coarse mesh is dominated by few modes near \(\Gamma\) and is not converged anyway.
5.7. Scripts in tools#
1.5 |
2.0 |
|---|---|
|
|
|
removed; use |
|
the standard deviation of each mode is capped so that its typical atomic displacement does not exceed 0.20 of the
nearest-neighbour distance (individual samples can exceed it), samples are truncated at \(4\sigma\), and positive
frequencies below 10 cm-1 (except the acoustic modes at \(\Gamma\)) are raised to 10 cm-1.
The default random seed is fixed (12345). See |
|
unchanged options; |
– |
new: |
The Python scripts use the CODATA 2018 constants (tools/alamode_constants.py), and displace.py needs PyYAML
to read YAML pattern files.
5.8. Python#
The Python interface is part of the source tree. The distribution
alamode-pythoncontains two packages,almandanphon. Build it withpip install .in thepythondirectory (Python API). It needs Python >= 3.11 and, for theanphonpackage, an MPI library; to buildalmonly, usepip install . -C cmake.define.ALAMODE_PYTHON_ANPHON=OFF.almreplaces the standalone ALM Python module of 1.x and keeps its high-level API (define,set_training_data,optimize,get_fc,set_fc,save_fc,optimizer_control). phonopy’s ALM interface works with it unchanged. Errors are raised as Python exceptions instead of terminating the process. See alm (force constants).The default
TOL_CONSTof the Python API is now \(10^{-6}\), as in the command-line program.anphonis new: it runs anphon from Python and reads the HDF5 results (anphon (phonon properties)).The 1.x Python module
alm(for example the conda-forge packagealm) provides the same top-level module name. Uninstall it before installing 2.0 (conda remove almorpip uninstall alm), so thatimport almpicks up the 2.0 package.