HA and QHA phonon YAML

HA and QHA share one normalized YAML contract for static energies, volume-dependent phonon frequencies, q-point integration data, explicit units, mode-continuity provenance, and optional structural information. The same file can be used by both modules; QHA adds stricter scientific requirements when mode-resolved frequency interpolation is selected.

A complete current example is available here:

Download the MgO example

The public readers return quantas.api.ha.Input or quantas.api.qha.Input. Numerical arrays are validated and converted to float64 before calculation. YAML flow-style vectors such as [1, 2, 3] and block-style sequences are semantically equivalent; the current generator uses compact formatting only to improve readability.

An optional top-level kieffer block may enrich physically applicable primitive Gamma-only inputs with three additional acoustic branches. It does not change the entries under phonon.

Important

This page defines the normalized data contract. The scientific procedure used to reconstruct primitive structures and establish phonon-mode continuity is documented separately in Phonon input generation and mode continuity.

Minimal contract

A compact multi-volume file has this logical form:

job: Example material
natom: 2
formula_units: 1
units:
  energy: Ha
  volume: angstrom^3
  frequency: cm^-1
  length: angstrom
provenance:
  interface: crystal
  sources: [vol01.out, vol02.out, vol03.out]
  reference_index: 0

mode_continuity: assumed
supercell:
- [2, 0, 0]
- [0, 2, 0]
- [0, 0, 2]

qpoints: 2
volume: [18.0, 19.0, 20.0]
energy: [-100.01, -100.03, -100.02]

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. Current files generated by Quantas also write units and provenance explicitly. supercell records the integer expansion used by the upstream phonon calculation; it must not be confused with the primitive lattice matrices stored under structure.

Units

Current generated files carry one explicit unit mapping for the complete phonon dataset:

units:
  energy: Ha
  volume: angstrom^3
  frequency: cm^-1
  length: angstrom

All four labels are required when an explicit units mapping is present. They describe the numerical input, not merely the display format.

Historical Quantas phonon YAML files without units remain readable. For backward compatibility they use the established interpretation:

Quantity	Historical interpretation
Energy	Hartree per cell
Volume	Angstrom cubed
Frequency	cm^-1
Structural length	Angstrom

Warning

Unit metadata and numerical arrays form one scientific contract. Changing a unit label changes the interpretation of the stored numbers. Do not edit the units mapping as though it were a renderer preference.

Provenance

Current generated files may contain

provenance:
  interface: crystal
  sources: [vol01.out, vol02.out, vol03.out]
  reference_index: 0

interface: Identifies the input adapter used to construct the normalized file.
sources: Lists the external outputs used to construct the dataset.
reference_index: Records the source state used for reference metadata and final branch labels where applicable. For the Quantas adjacent-volume tracker, the reference does not alter the local mode assignments.

Additional provenance fields may be added by an interface, but readers must not infer the scientific file type from the external source filename.

Volume and energy arrays

volume and energy 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 thermodynamic cell as volume;
energy is the static energy of that cell;
the number of modes is 3 * natom;
optional structural lattice determinants describe the same normalized volumes within validation tolerance.

The top-level volume array is the direct thermodynamic input. A structure.volume_series.volume array may also appear when a structural path is available. The duplication is currently retained deliberately because the phonon contract and the structural path are independently inspectable objects. They must agree numerically.

Optional Kieffer acoustic data

quantas ha add-kieffer and quantas qha add-kieffer add a mapping of the following form:

kieffer:
  method: kieffer-sine-wave
  composition: additional-acoustic-branches
  units:
    volume: angstrom^3
    cutoff_frequency: Hz
    effective_velocity: km/s
    pressure: GPa
  states:
  - volume: 80.0
    cutoff_frequency: [3.1e12, 4.0e12, 6.8e12]
    effective_velocity: [3.2, 4.1, 7.0]
    source: direct
    source_elastic_indices: [0]
    metadata:
      tensor_kind: wallace_hydrostatic
      pressure_gpa: 2.0
      pressure_source: output_stress
      quadrature:
        mu_order: 24
        phi_order: 48
        direction_count: 1152
        relative_errors: [1.0e-6, 8.0e-7, 4.0e-7]
  provenance:
    elastic_interface: crystal
    pressure_source: output_stress

All state values use canonical units independent of the main phonon-frequency unit. Cutoffs are ordinary frequencies, not angular frequencies. State order is increasing in volume and every state records the corresponding source elastic index. QHA requires a unique direct match for every sampled phonon volume; HA requires exactly one state.

When pressure is obtained from the QHA static energy path, pressure_model is normative provenance rather than input for a later refit: it stores the model actually used during enrichment and the pressures already applied to the raw elastic tensors. energy_eos records the canonical EOS family and order; energy_polynomial records its degree. The complete generated mapping also contains fit parameters, residual diagnostics, warnings, and one explicit volume-match record per state.

An abbreviated energy-EOS provenance block is:

provenance:
  elastic_interface: crystal
  pressure_source: energy_eos
  pressure_model:
    method: energy_eos
    relation: P(V) = -dE/dV
    source_dataset: phonon_input_static_energy
    energy_unit: Ha
    volume_unit: angstrom^3
    volume_length_unit: angstrom
    pressure_unit: GPa
    settings:
      eos: BM3
      eos_family: birchmurnaghan
      eos_order: 3
    evaluated_pressures_gpa: [2.0, 0.0, -2.0]
    fit:
      success: true
      quality: good
      parameter_names: [E0, K0, KP, V0]
    volume_matches:
    - elastic_index: 0
      phonon_index: 0
      elastic_volume: 80.0
      phonon_volume: 80.0
      absolute_difference: 0.0
      relative_difference: 0.0

The Python constructors deliberately accept general array-like values and string forms of the source enum. Before YAML serialization, Quantas explicitly normalizes cutoff and velocity triplets to float64 arrays and the source to CutoffVolumeSource. The persisted mapping therefore always contains plain floating-point lists and the canonical direct or interpolated label, independently of the convenient constructor form used by an application.

composition: additional-acoustic-branches is normative: the sine-wave model adds its three branches to the thermodynamic sums. It does not identify, remove, or replace the three calculated translational Gamma modes. The normal harmonic treatment continues to handle the original frequency array according to its existing rules.

Presence is not activation. The HA/QHA readers preserve the optional mapping, but command-line calculations use it only when run --kieffer is selected. Without that flag the standard phonon-only calculation is performed from the same YAML file. A requested activation fails if the block is absent, malformed, or incompatible with the Gamma-only primitive input.

Q-point records

Each item under phonon contains:

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 derive irreducible-Brillouin-zone multiplicities from a separate crystal-symmetry analysis during HA or QHA.

Consequently:

a full uniform mesh may use equal weights when appropriate;
an irreducible mesh requires the multiplicities supplied by the upstream calculation;
multiplicities must not be guessed from q-point coordinates alone;
multiplying all weights by one positive constant does not change a result, but their relative values are scientifically significant;
supported Phonopy mappings may carry their native weights into the normalized representation.

Warning

An incorrect q-point weight can leave the YAML perfectly readable while changing every extensive vibrational quantity. Weight provenance is therefore a scientific input requirement, not optional decoration.

Frequency records and non-positive modes

A frequency series occupies one stable branch index across all volumes. Zero or negative values are preserved by the input contract; their scientific handling belongs to the HA/QHA workflows and is reported there. Do not delete acoustic or imaginary modes merely to make the YAML rectangular.

Generated frequency arrays retain the numerical values supplied by the parser. Display precision in CLI diagnostic tables is separate and never changes the stored float64 values.

Mode continuity for QHA

mode_continuity accepts four values:

verified: A documented procedure established a defensible branch correspondence. This may be Quantas eigenvector tracking or a source-managed QHA workflow; inspect mode_continuity_metadata to distinguish the provenance.
assumed: The producer accepts the stored branch order as continuous, but no explicit verification is recorded. Frequency-based QHA is permitted with a warning.
unknown: Continuity could not be assessed. Frequency-based QHA is not permitted.
unreliable: At least one unresolved tracking or reconstruction condition makes mode-resolved interpolation unsafe. Frequency-based QHA is not permitted.

The freq QHA scheme and mode-Gruneisen analysis require verified or assumed continuity. The td scheme interpolates integrated harmonic properties and does not require branch correspondence.

Warning

verified is a statement about branch correspondence, not about the physical stability or convergence of the phonon calculation. A dynamically unstable or poorly converged spectrum can still be tracked consistently.

Mode-continuity metadata

For Quantas eigenvector tracking the metadata may contain:

method: eigenvector_overlap.
reference_index and volume_order: Reference label and volume-sorted source indices.
traversal: Compression and expansion paths used to express the final branch labels.
minimum_overlap: Weakest selected non-degenerate adjacent-volume scalar product.
minimum_subspace_singular_value: Weakest singular value among matched degenerate eigenspaces.
reordered_assignments and local_reordered_assignments: Final branch-to-raw reorders and local adjacent-volume reorders, respectively.
ambiguous_assignments, low_overlap_assignments, caution_assignments, unresolved_assignments: Aggregate continuity diagnostics.
frequency_fit: Global frequency-path diagnostics and leave-one-out validation metadata.

All numerical thresholds used by the tracking decision are written explicitly so that a generated input remains auditable.

For native CRYSTAL QHA output, the corresponding provenance is compact:

mode_continuity: verified
mode_continuity_metadata:
  method: crystal-qha
  source: crystal

The tracking equations, ambiguity criterion, degenerate-subspace analysis, and leave-one-out validation are documented in Phonon input generation and mode 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:

atomic_numbers: Primitive-cell atomic numbers, normally rendered as one compact YAML array.
reference: Reference primitive lattice, fractional positions, atomic numbers, label, and provenance metadata. A lattice is a 3 x 3 matrix; fractional positions have one three-component row per atom.
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_atoms, coordinate transformation matrix, and origin shift.
reconstruction: Optional per-state 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.

Note

supercell and structure.reference.lattice are different physical objects. supercell is the integer phonon expansion matrix. lattice contains direct lattice vectors of the normalized crystal structure.

Input generation

Use the module-specific input generators instead of hand-copying long frequency arrays. They preserve upstream provenance, validate compatible sampling, normalize supported structural data, and establish mode continuity when the required eigenvectors are available.

Typical commands are documented in quantas ha and quantas qha. The complete scientific procedure is described in Phonon input generation and mode continuity.

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;
explicit unit labels match the numerical values;
mode_continuity is appropriate to the intended QHA scheme;
structural lattices and volumes describe the same cell;
provenance identifies the source route used to construct the dataset.

HA and QHA phonon YAML

Minimal contract

Required top-level fields

Units

Provenance

Volume and energy arrays

Optional Kieffer acoustic data

Q-point records

Q-point weights

Frequency records and non-positive modes

Mode continuity for QHA

Mode-continuity metadata

Optional structural path

Input generation

Validation checklist

Related pages