13. HDF5 files#

ALAMODE stores the force constants and the main results in HDF5 files. HDF5 is a portable binary format organized like a file system: groups (folders) contain datasets (arrays) and other groups, and both can carry attributes (small labels such as units). The chart below shows which program writes each file and which program reads it.

Which programs write and read the HDF5 files of ALAMODE

HDF5 files of ALAMODE and the programs that write and read them.#

Which programs write and read the HDF5 files of ALAMODE

HDF5 files of ALAMODE and the programs that write and read them.#

13.1. Reading the files#

List the contents of a file with h5ls -r PREFIX.h5 (from the HDF5 tools), or read it in Python with h5py:

import h5py

with h5py.File("PREFIX.kappa.h5", "r") as f:
    print(f.attrs["schema"])               # which kind of file this is
    T = f["metadata/temperatures"][:]      # K
    kappa = f["kappa/kappa_peierls"][:]    # (nT, 3, 3), W/mK
    print(f["kappa/kappa_peierls"].attrs["unit"])

The files share a few conventions:

  • The root attributes identify the file: schema (e.g. alamode:kappa_result), format_version, alamode_version, alamode_git_commit, and created_date (PREFIX.selfenergy.h5 has /metadata/version and /metadata/mode instead).

  • Physical quantities carry their unit in a unit attribute.

  • Indices of atoms, coordinates (0, 1, 2 = \(x, y, z\)), and branches start from 0.

  • /metadata/input_variables records the input variables of the run that wrote the file, one attribute per tag.

In the figures below, folder-shaped boxes are groups, the boxes next to them list their datasets with the shapes (() is a scalar) and units ([ ]), and dashed boxes are written only under the condition shown. The symbols for the array sizes are explained at the bottom of each figure.

13.2. Force constants (PREFIX.h5)#

Written by alm (MODE = optimize), and by anphon for strained cells (NEWFCS = 1). anphon reads it through FCSFILE (or FC2FILE, FC3FILE, FC4FILE).

Layout of the force-constant file

Layout of the force-constant file (schema alamode:force_constants).#

Layout of the force-constant file

Layout of the force-constant file (schema alamode:force_constants).#

  • /ForceConstants/Order2, Order3, Order4, …: the harmonic, cubic, quartic, … force constants, one row per force constant \(\Phi_{\alpha_1 \cdots \alpha_n}(i_1, \ldots, i_n)\):

    • force_constant_values: the value, in the unit given by its unit attribute (Ry/bohrn by default; eV/Ån with FCS_UNIT_OUTPUT of alm or from fcconvert.py).

    • atom_indices: the atoms \(i_1, \ldots, i_n\) as indices in the primitive cell; atom_indices_supercell: the same atoms in the supercell.

    • coord_indices: the Cartesian components \(\alpha_1, \ldots, \alpha_n\).

    • shift_vectors: the vectors from the first atom to the other atoms (Cartesian, in the unit of its unit attribute: bohr by default, Å with eV/Ån force constants).

  • /PrimitiveCell and /SuperCell: lattice vectors (one vector per row, in the length unit of the file), fractional coordinates, elements, atomic kinds, and mapping_table, which gives the supercell index of every primitive-cell atom in each translated cell.

13.3. Thermal conductivity (PREFIX.kappa.h5)#

Written by MODE = kappa. The file is updated during the run, so an interrupted calculation continues from it with RESTART = 1, and analyzer.py reads it for lifetimes, mean free paths, and cumulative thermal conductivity.

Layout of the thermal-conductivity file

Layout of PREFIX.kappa.h5 (schema alamode:kappa_result).#

Layout of the thermal-conductivity file

Layout of PREFIX.kappa.h5 (schema alamode:kappa_result).#

  • /kappa: the thermal-conductivity tensors in W/mK, one \(3 \times 3\) tensor per temperature. kappa_peierls is the usual (Peierls) term, the content of PREFIX.kl. With KAPPA_COHERENT > 0, kappa_coherent and their sum kappa_total are added. The scattering_processes attribute of each tensor names the scattering included, e.g. 3ph+4ph+isotope. With INCLUDE_4PH = 1, kappa_3ph_only keeps the three-phonon-only result, and with KAPPA_SPEC = 1, kappa_spec holds the spectrum on the frequency axis energy_axis.

  • /scattering/3ph: phonon frequencies (cm-1) and linewidths \(\Gamma\) (cm-1) at the irreducible \(k\) points, and group velocities (m/s) on the full mesh. The lifetime is \(\tau = 1/(2\Gamma)\). gamma has one row per mode (\(k\) point × branch) and one column per temperature; gamma_computed marks the rows already calculated, which is what makes restarting possible. equiv_knum and equiv_offsets list the full-mesh \(k\) points that belong to each irreducible point.

  • /scattering/4ph (INCLUDE_4PH = 1) has the same layout for the four-phonon linewidths, and /scattering/isotope (ISOTOPE > 0) holds the isotope-scattering linewidths.

  • /iterativebte (SOLVER = IBTE, VBTE or DBTE): the beyond-RTA solution per temperature. Its solver and convergence_threshold attributes record the run that produced it; on restart with another SOLVER or a smaller ITER_THRESHOLD, the stored results are re-converged from the stored solution.

  • /metadata: temperatures, the primitive cell, smearing settings, and the input variables. relaxed_cell_convention holds, per temperature, the geometry convention of the run that computed it: 0 without RELAXED_STRUCTURE and 2 with it (see RELAXED_STRUCTURE).

The notebook Analysing PREFIX.kappa.h5 reads this file and rebuilds the thermal conductivity from the lifetimes and velocities in it.

When the harmonic force constants depend on temperature (FC2_TEMPERATURE with an SCPH or QHA result), the file is temperature resolved (root attribute temperature_resolved = 1): frequencies and velocities gain a leading temperature axis, and runs at different temperatures accumulate in one file.

13.4. SCPH and QHA results (PREFIX.scph.h5, PREFIX.qha.h5)#

Written by MODE = SCPH and MODE = QHA at the end of the run. A later run uses it through FC2_TEMPERATURE (with FCSFILE, FC2FILE, or DFC2FILE) and RELAXED_STRUCTURE, and to restart the calculation.

Layout of the SCPH and QHA result file

Layout of PREFIX.scph.h5 and PREFIX.qha.h5 (schema alamode:scph_state).#

Layout of the SCPH and QHA result file

Layout of PREFIX.scph.h5 and PREFIX.qha.h5 (schema alamode:scph_state).#

  • /ForceConstants/Order2: the harmonic force constants folded onto the supercell of KMESH_INTERPOLATE; Order2_temperature_dependent/force_constant_values holds the effective (renormalized) values at every temperature and uses the index datasets of Order2. See Force constants and corrections with NONANALYTIC > 0 for what they mean with NONANALYTIC > 0.

  • /convergence: whether the SCPH iteration (scph) and the structural optimization (structure) converged at each temperature. Later runs refuse unconverged temperatures unless ALLOW_UNCONVERGED is set.

  • /structure (RELAX_STR > 0): the relaxed structure at each temperature: the displacement gradient u_tensor, the atomic displacements u0 (bohr), and the space group spg_label. /provenance records a fingerprint of the force constants used, which RELAXED_STRUCTURE checks.

  • /dymat, V0: the change of the dynamical matrix and the potential energy used to restart the calculation.

  • /settings: the temperatures and meshes of the run. The root attribute mode is SCPH or QHA. nonanalytic is the NONANALYTIC of the run, and delta_baseline = 1 marks the convention of the corrections described below. dielectric_tensor_processed and born_charges_processed hold \(\varepsilon_\infty\) and \(Z^*\) as the run used them (after the acoustic sum rule and BORNSYM) whenever Born charges were loaded; RELAXED_STRUCTURE reads them.

Force constants and corrections with NONANALYTIC > 0#

The corrections (/dymat and the difference Order2_temperature_dependent − Order2, which is also what DFC2FILE and the text file PREFIX.scph_dfc2 carry) are the change of the dynamical matrix relative to the full harmonic dynamical matrix of the run, including its nonanalytic term (marker /settings/delta_baseline = 1). The base values Order2 are the force constants that a run with the same NONANALYTIC turns back into that harmonic matrix at the \(q\) points of the KMESH_INTERPOLATE mesh:

  • NONANALYTIC = 0 and 1: the original harmonic force constants (a reader adds the Parlinski term itself at every \(q\));

  • NONANALYTIC = 2 and 3: the full harmonic matrix including the dipole-dipole part, whose mixed-space or Ewald term vanishes at \(q\) commensurate with the supercell of the file.

Consequently, the force constants of a state file (FCSFILE, FC2FILE with or without FC2_TEMPERATURE, and DFC2FILE) must be read with the NONANALYTIC of the run that wrote it; 2 and 3 may read each other’s files. A file written with NONANALYTIC = 0 may also be read with NONANALYTIC > 0 (e.g. SCPH without the nonanalytic term, then phonons or kappa with it): a warning is printed, because the correction was then computed without the long-range term and the nonanalytic term is added to the harmonic part only, which is an approximation. Other combinations (a file with NONANALYTIC > 0 read with 0, 1 read with 2/3 or the reverse) stop with an error, and so does a restart with a different NONANALYTIC. The agreement with the SCPH/QHA frequencies is exact at the \(q\) points of the KMESH_INTERPOLATE mesh only. Elsewhere the result depends on how the reader interpolates: the total force constants read through FC2_TEMPERATURE are interpolated as a whole, while DFC2FILE interpolates the correction alone as the SCPH run does, and the two differ off the mesh (and so do quantities sampled there, such as group velocities from finite differences and thermal conductivities).

Restart files PREFIX.scph_dymat of version 1.x took the corrections relative to the analytic part of the harmonic matrix. On restart they are converted (NONANALYTIC = 2, 3), and refused for NONANALYTIC = 1, whose Parlinski term had a different phase. PREFIX.scph_dfc2 files of version 1.x, which lack the DELTA_BASELINE header, follow the same convention: with a nonzero non-analytic correction, tools/dfc2.py converts them correctly only for NONANALYTIC = 2 or 3 with KMESH_INTERPOLATE commensurate with the supercell of the harmonic force constants, and prints a note. Tools that read Order2 without anphon (the ALM reader of FC2FIX and the python fcsio reader, which warns) take the values as they are and do not apply this convention.

13.5. Self-energy (PREFIX.selfenergy.h5)#

Written by MODE = selfenergy, with one group per target mode.

Layout of the self-energy file

Layout of PREFIX.selfenergy.h5.#

Layout of the self-energy file

Layout of PREFIX.selfenergy.h5.#

  • /targets/00001, 00002, …: one group per target (wave vector × branch), in the order of the &kpoint field and BRANCHES, with the wave vector xk, the branch, the harmonic frequency, and the requested results: linewidth (the full width \(2\Gamma\), per temperature), the frequency shifts shift_*, the frequency-dependent self-energy self_*, and the final-state analysis fstate_*.

  • /path: the path coordinates when the targets lie on a band path (KPMODE = 1).

  • /spectrum (INTERPOLATE = 1): the spectral function.

  • /metadata: temperatures, the integration mesh, and the input variables.

Note

The linewidth in this file is the full width \(2\Gamma\), while gamma in PREFIX.kappa.h5 is \(\Gamma\).

13.6. Strain couplings (PREFIX.strain.h5)#

The file given as STRAINFILE for cell relaxation is made by the strain tools and is described in One file for all inputs: the strain-coupling container (STRAINFILE).