HA and QHA phonon YAML

HA and QHA share one normalized YAML contract for static energies, volume-dependent phonon frequencies, q-point integration data, and optional structural information. The same file can be used by both modules; QHA adds a mode-continuity declaration because mode-resolved interpolation has stricter requirements than harmonic summation.

A complete current example is available here:

Download the MgO example

The public readers return quantas.api.ha.Input or quantas.api.qha.Input. Arrays are validated and converted to float64 before calculation.

Minimal contract

A compact multi-volume file has this logical form:

job: Example material
natom: 2
formula_units: 1
qpoints: 2
supercell:
  - [2, 0, 0]
  - [0, 2, 0]
  - [0, 0, 2]

volume: [18.0, 19.0, 20.0]
energy: [-100.01, -100.03, -100.02]
mode_continuity: assumed

phonon:
  - q-position: [0.0, 0.0, 0.0]
    weight: 1
    band:
      - frequency: [0.0, 0.0, 0.0]
      - frequency: [0.0, 0.0, 0.0]
      - frequency: [0.0, 0.0, 0.0]
      - frequency: [200.0, 190.0, 180.0]
      - frequency: [300.0, 285.0, 270.0]
      - frequency: [500.0, 480.0, 460.0]
  - q-position: [0.5, 0.0, 0.0]
    weight: 3
    band:
      # six frequency records, each with three volume values

Required top-level fields

Field	Normalized shape	Meaning
`natom`	scalar integer	Number of atoms in the thermodynamic normalization cell. The number of branches is exactly `3 * natom`.
`formula_units`	scalar integer	Number of chemical formula units in that cell. Historical aliases `z` and `Z` are accepted; omission defaults to one.
`qpoints`	scalar integer	Number of entries in `phonon`.
`volume`	`(nvol,)`	Volumes of the thermodynamic normalization cell.
`energy`	`(nvol,)`	Static electronic energies for the same volume sequence.
`phonon`	sequence of `qpoints` mappings	Q-point weights, optional coordinates, and exactly `3 * natom` band records per q-point.

job and supercell are strongly recommended but are not required by the basic reader. job is provenance. supercell records the expansion used by the upstream phonon calculation and is also useful for structural normalization.

Units

The YAML values do not carry per-field unit tags. Their units are supplied by the HA/QHA calculation options. The public defaults are:

Quantity	Default interpretation
Energy	Hartree per cell
Length/volume	Angstrom / Angstrom cubed
Frequency	cm^-1

Changing an input-unit option changes how the same numerical values are interpreted; it is not a display-only conversion. All volumes, energies, and frequencies in one file must use one consistent basis and unit system.

Volume and energy arrays

volume and energy must describe the same ordered states. A scalar is accepted for single-volume HA and is normalized to a length-one array. Multi-volume HA retains one independent harmonic result for every sampled volume. QHA requires enough distinct volumes to support the selected interpolation and minimization models.

The cell basis must be consistent across all fields:

natom and formula_units describe the same cell as volume;
energy is the static energy of that cell;
the number of modes is 3 * natom;
optional structural lattices must have determinants equal to the same volumes, within their validation tolerance.

Q-point records

Each item under phonon has:

weight: Required integration weight. It must be finite and the sum of all weights must be positive.
q-position: Optional fractional q-point coordinates with three components. Coordinates are stored for provenance and mode analysis; they are not used to infer missing weights.
band: A sequence of exactly 3 * natom mappings. Each mapping contains frequency as either a scalar for one volume or a sequence of length nvol.

After reading, frequencies have shape:

(nqpoint, nmode, nvolume)

and weights have shape (nqpoint,).

Q-point weights

Quantas normalizes the supplied weights by their sum before evaluating the thermodynamic sums. It does not currently derive irreducible-Brillouin-zone multiplicities from a separate crystal-symmetry analysis.

Consequently:

a full uniform mesh may use equal weights;
an irreducible mesh requires the symmetry multiplicities supplied by the upstream calculation;
multiplicities must not be guessed from q-point coordinates alone;
a common multiplicative factor is harmless because the weights are normalized, but relative weights are scientifically significant;
Phonopy mappings may carry their native weight values into the Quantas representation.

A weight error affects every extensive vibrational quantity while leaving the file syntactically valid. Weight provenance should therefore be retained with the calculation.

Frequency records and non-positive modes

A frequency series occupies one stable band index across all volumes. Zero or negative values are preserved by the input contract; their scientific handling belongs to the HA/QHA workflow and is reported there. Do not delete acoustic or imaginary modes merely to make the YAML rectangular. The file should represent the upstream calculation faithfully, and the calculation report should document any excluded contributions.

Mode continuity for QHA

mode_continuity accepts four values:

verified: Branch correspondence was established by a documented tracking or mapping procedure.
assumed: The producer assumes that mode indices remain physically corresponding, but no explicit verification was stored.
unknown: Continuity has not been assessed.
unreliable: Known crossings, reordering, or reconstruction failures make mode-resolved interpolation unsafe.

The freq QHA scheme and mode Gruneisen properties require meaningful mode-by-mode correspondence. The td scheme interpolates already integrated thermodynamic quantities and does not require branch continuity.

Optional structural path

Current inputs may include a structure mapping. This block allows QHA to reconstruct equilibrium lattice parameters, axial expansion, and a Cartesian thermal-expansion tensor along the sampled volume path.

The principal children are:

reference: Reference primitive lattice, fractional positions, atomic numbers, label, and provenance metadata.
volume_series: volume, lattice, and fractional_positions arrays for every sampled state. Lattices have shape (nvol, 3, 3) and fractional positions have shape (nvol, natom, 3).
normalization: Basis, source basis, integer expansion matrix, number of repetitions, source atom count, and normalized atom count.
symmetry: Optional space-group and Hall metadata, symmetry tolerance, equivalent-atom mapping, and transformations.
reconstruction: Optional diagnostics describing how a compact primitive path was recovered from an upstream supercell representation.
transformations: Optional matrices such as primitive_to_crystallographic.
orientation and reference_index: Cartesian convention and the sampled state used as structural reference.

A historical YAML without structure remains valid for HA and scalar QHA thermodynamics; structural and axial outputs are then unavailable rather than invented.

Input generation

Use module-specific input generators instead of hand-copying long frequency arrays. They preserve upstream metadata and apply the supported normalization path. Typical commands are documented in the HA and QHA command references and tutorials.

Validation checklist

Before a production run, verify:

len(volume) == len(energy);
every band frequency record has the same number of volume values;
every q-point has exactly 3 * natom bands;
qpoints == len(phonon);
all weights are finite and their sum is positive;
the cell normalization is consistent across energy, volume, modes, and structure;
the selected input units match the numbers in the file;
mode_continuity is honest for the intended QHA scheme;
structural lattices and volumes describe the same cell.