Thermoelastic input

Thermoelasticity uses a schema-versioned YAML file describing a series of hydrostatically pre-stressed elastic tensors at different volumes. The file is normally generated from CRYSTAL outputs and then coupled to a separate native QHA result during calibration.

The current accepted schema is:

schema:
  name: quantas-thermoelastic-input
  version: '1.0'

Earlier unnormalized pre-release layouts are rejected. Regenerate them with quantas thermoelasticity inpgen so that tensor-frame provenance is explicit.

Complete example

Download the dolomite example

Top-level structure

A current file contains:

schema: {...}
job: Dolomite PBE0 QSA thermoelasticity
method: quasistatic
interface: crystal
conventions: {...}
units: {...}
reference: {...}
elastic_data:
  - {...}
  - {...}

method must currently be quasistatic. interface and job are provenance. The scientific values are carried by reference and elastic_data.

Conventions and units

The generated file records the conventions used to interpret every tensor:

conventions:
  strain: eulerian-finite-strain
  stiffness: wallace-hydrostatic-stress-strain
  prestress: applied-by-crystal-pressure-keyword
  tensor_orientation: crystal
  voigt_order: [11, 22, 33, 23, 13, 12]

The normative units are:

Quantity	Unit
Pressure	GPa
Stiffness	GPa
Volume	Angstrom cubed
Density	kg m^-3
Static energy	Hartree
Lattice vectors	Angstrom

The reader validates numerical values according to these conventions; unit labels are not used as permission to mix unit systems inside one file.

Reference block

reference.index identifies one element of the sorted elastic series used to define the common Cartesian frame. The generator normally chooses the state closest to zero pressure. This frame reference is not necessarily the thermodynamic EOS volume V0.

reference.structure stores:

natom;
a 3 x 3 direct lattice with vectors by rows;
ordered atomic numbers;
ordered fractional coordinates.

reference.symmetry stores the crystallographic interpretation used during normalization:

space-group number and international symbol;
Hall number, Hall symbol, and setting choice;
point group;
detected elastic system;
symprec and angular tolerance.

Atom order is part of the contract. The volume series is not treated as a set of unrelated cells that may be reordered independently.

Elastic data records

Each entry in elastic_data represents one static state:

- source: calculation.out
  pressure: 5.0
  stress_pressure: 4.998
  volume: 104.2
  density: 2930.0
  energy: -1405.123456789
  lattice:
    - [a11, a12, a13]
    - [a21, a22, a23]
    - [a31, a32, a33]
  stiffness:
    - [C11, C12, C13, C14, C15, C16]
    - [...]
  frame: {...}

source: Original electronic-structure output used to construct the record.
pressure: Hydrostatic pressure requested through CRYSTAL’s PRESSURE keyword and used for the pre-stress correction.
stress_pressure: Pressure reconstructed from the final unstrained stress tensor. A mismatch with pressure is a validation diagnostic.
volume: Primitive normalization-cell volume. It must be finite, positive, unique, and consistent with the determinant of lattice.
density: Density of the same primitive cell. Across the series, density * volume should reconstruct one constant cell mass within numerical tolerance.
energy: Static DFT energy of the same primitive cell. The reference EOS used by the thermoelastic calibration is taken from the QHA archive, but the SOEC energy remains valuable provenance and a consistency check.
stiffness: Full symmetric 6 x 6 Wallace stress–strain tensor in GPa, using the engineering Voigt convention.

All records must have been calculated with the hydrostatic pre-stress correction. Quantas does not apply that correction a second time and does not accept a series containing uncorrected points.

Frame metadata

Schema 1.0 requires a frame mapping for every state. At minimum it contains:

status: Normalization status, normally normalized.
method: Current generator value right_polar_decomposition_corotation.
rotation_to_reference: 3 x 3 orthogonal matrix used to co-rotate lattice and stiffness into the reference Cartesian frame.
principal_logarithmic_strain: Three principal logarithmic strains after rigid rotation has been removed.
source_lattice: Original lattice before co-rotation.

Generated records may additionally store removed rotation angle, maximum ordered-atom displacement, and other diagnostics. These values are provenance and validation evidence; they are not extra fit parameters.

Series-level requirements

After parsing, records are ordered by increasing volume. The series must satisfy:

at least one record is present;
volumes are finite, positive, unique, and strictly increasing after sorting;
every stiffness matrix is finite and symmetric;
every density is finite and positive;
lattice determinants agree with reported volumes;
all points share species, ordered atoms, symmetry interpretation, and one co-rotated Cartesian frame;
reference.index is valid;
every point records applied hydrostatic pre-stress.

A large pressure range does not compensate for poor volume coverage around the reference EOS minimum. Fit support is diagnosed later and stored in the native HDF5 result.

Relationship to the QHA file

The YAML contains the static elastic series only. The QHA result supplied to thermoelasticity run provides:

static volumes and energies used for the cold reference EOS;
temperature and pressure grids;
equilibrium volume V(P,T);
optional volume uncertainty;
heat capacity and Cartesian thermal-expansion tensor required for adiabatic conversion.

The normalization cells of the elastic YAML and QHA archive must be physically compatible. A numerically plausible tensor coupled to a differently normalized volume is not a valid calculation.

Generating the file

For a list of CRYSTAL outputs:

quantas thermoelasticity inpgen elastic_outputs.txt \
   --list --jobname "My thermoelastic series" \
   --output thermoelastic.yaml

The generator performs code-specific parsing, pressure checks, atom correspondence, symmetry analysis, and frame co-rotation. Hand editing should be limited to provenance fields unless the user is prepared to reproduce all validation steps.

Inspection from Python

from quantas.api import thermoelasticity

data = thermoelasticity.read_input("thermoelastic.yaml")
series = data.elastic_series

print(series.npoints)
print(series.volume_bounds)
print(series.pressures)
print(series.stiffness.shape)   # (npoint, 6, 6)
print(series.reference_index)

Validation checklist

The source calculations all use CRYSTAL PRESSURE.
Volumes bracket or closely surround the intended reference state.
The reference atom ordering is preserved at every state.
Frame metadata is present for every record.
The same primitive-cell normalization is used by volume, energy, density, lattice, stiffness, and QHA.
No rotation or pressure correction has been applied twice.
The file was generated with the current schema rather than copied from an earlier pre-release snapshot.