Quasi-Harmonic Approximation API

quantas.api.qha exposes preflight inspection, quasi-harmonic calculation, result validation, method comparison, plotting, reporting, and native HDF5 persistence.

Recommended lifecycle

from quantas.api import qha

options = qha.Options(
    scheme="freq",
    minimization="poly",
    thermal_expansion_method="mixed_derivative",
    energy_degree=3,
    frequency_degree=3,
)
preview = qha.inspect(
    "mgo_b3lyp.yaml",
    options=options,
    polynomial_degree=3,
    eos="BM3",
)
inspection_tables = qha.build_inspection_report(preview)
inspection_plots = qha.build_inspection_plots(preview)
result_data = qha.run("mgo_b3lyp.yaml", options=options)
summary = qha.validate_result(result_data)
result = qha.get_result(result_data)

Use inspect() before a production run to examine static volume support, fit quality, and the pressure interval represented by the sampled energies.

Scientific option types

The public selectors accept the following literal values:

Scheme: freq or td;
Minimization: poly or eos;
ThermalExpansionMethod: mixed_derivative, mode_gruneisen, or numerical;
PolynomialDerivativeMethod: local_grid or analytic;
ModeContinuity: verified, assumed, unknown, or unreliable;
FitFailurePolicy: continue, stop, or raise.

quantas.api.qha.Scheme: alias of Literal[‘freq’, ‘td’]

quantas.api.qha.Minimization: alias of Literal[‘poly’, ‘eos’]

quantas.api.qha.ThermalExpansionMethod: alias of Literal[‘mixed_derivative’, ‘mode_gruneisen’, ‘numerical’]

quantas.api.qha.PolynomialDerivativeMethod: alias of Literal[‘local_grid’, ‘analytic’]

quantas.api.qha.ModeContinuity: alias of Literal[‘verified’, ‘assumed’, ‘unknown’, ‘unreliable’]

quantas.api.qha.FitFailurePolicy: alias of Literal[‘continue’, ‘stop’, ‘raise’]

quantas.api.qha.CurveAxis: alias of Literal[‘temperature’, ‘pressure’]

quantas.api.qha.PhononInterface: alias of Literal[‘crystal’, ‘crystal-qha’, ‘phonopy’]

quantas.api.qha.TableFileFormat: alias of Literal[‘txt’, ‘csv’]

quantas.api.qha.TableFormat: alias of QHATableFormat

Passive contracts

quantas.api.qha.Input: alias of QHAInput

quantas.api.qha.Options: alias of QHAOptions

quantas.api.qha.PlotOptions: alias of QHAPlotOptions

quantas.api.qha.Result: alias of QHAResult

class quantas.api.qha.KiefferVolumeSeries(states, interpolation_method=None, metadata=<factory>)

Increasing volume series of Kieffer acoustic cutoff states.

Parameters:

statestuple of KiefferCutoffState: Cutoff states ordered by increasing volume.
interpolation_methodstr or None, optional: Method used when at least one state is interpolated.
metadatadict, optional: Series-level provenance.

Raises:

ValueError: If ordering or interpolation provenance is invalid.

Parameters:

states (tuple[KiefferCutoffState, ...])
interpolation_method (str | None)
metadata (dict[str, Any])

property volumes: NDArray[float64]: Return primitive-cell volumes in angstrom cubed.

property frequencies_hz: NDArray[float64]: Return cutoffs with shape (3, nvol) for thermodynamic functions.

property effective_velocities_km_s: NDArray[float64]: Return effective velocities with shape (3, nvol).

quantas.api.qha.Preview: alias of PressureVolumePreview

class quantas.api.qha.StructureVolumeSeries(reference, lattices, fractional_positions, volumes, normalization, symmetry=None, primitive_to_crystallographic=None, diagnostics=(), orientation='crystal', reference_index=0, metadata=<factory>, source_lattices=None, source_fractional_positions=None)

Bases: object

Primitive structural path sampled as a function of volume.

Parameters:

referenceCrystalStructure: Reference primitive structure used to maintain atom correspondence and cell orientation across the sampled volumes.
latticesarray_like: Primitive direct lattice matrices with shape (nvol, 3, 3).
fractional_positionsarray_like: Primitive fractional coordinates with shape (nvol, natoms, 3).
volumesarray_like: Primitive-cell volumes with shape (nvol,).
normalizationCellNormalization: Description of the thermodynamic normalization cell.
symmetrySymmetryMetadata or None, optional: Symmetry metadata for the reference structure.
primitive_to_crystallographicarray_like or None, optional: CRYSTAL transformation from the primitive to crystallographic cell.
diagnosticssequence of StructureReconstructionDiagnostics, optional: Reconstruction diagnostics for each sampled volume.
orientationstr, optional: Description of the Cartesian/basis convention. "crystal" denotes continuity with the CRYSTAL source orientation.
reference_indexint, optional: Index of the reference structure within the sampled series.
metadatadict, optional: Additional provenance metadata.
source_latticesarray_like or None, optional: Full source-cell lattices retained in memory for optional provenance storage.
source_fractional_positionssequence or None, optional: Full source-cell fractional positions retained in memory for optional provenance storage. Atom counts may differ among entries, so a tuple is used instead of a rectangular array.

Raises:

ValueError: If array shapes or atom counts are inconsistent.

Parameters:

reference (CrystalStructure)
lattices (NDArray[float64])
fractional_positions (NDArray[float64])
volumes (NDArray[float64])
normalization (CellNormalization)
symmetry (SymmetryMetadata | None)
primitive_to_crystallographic (NDArray[float64] | None)
diagnostics (tuple[StructureReconstructionDiagnostics, ...])
orientation (str)
reference_index (int)
metadata (dict[str, Any])
source_lattices (NDArray[float64] | None)
source_fractional_positions (tuple[NDArray[float64], ...] | None)

property nvol: int

Return the number of sampled structures.

Returns:

int: Number of volume points.

property natoms: int

Return the primitive atom count.

Returns:

int: Number of atoms in each compact primitive structure.

has_source_supercells()

Return whether full source-cell structures are retained.

Returns:

bool: True when both source lattices and positions are available.

Return type:

bool

as_dict(*, include_source=False)

Return a recursively serializable structural-series mapping.

Parameters:

include_sourcebool, optional: Include full source supercells when they are retained. The compact primitive path is always included.

Returns:

dict: Structure, symmetry, normalization, and reconstruction data.

Parameters:

include_source (bool)

Return type:

dict[str, Any]

Input, inspection, and calculation

create_input shares the HA/QHA phonon generator. For independent multi-volume outputs, the normalized YAML may contain Quantas eigenvector-based mode-continuity diagnostics; for native QHA sources it preserves source-managed continuity provenance. See Phonon input generation and mode continuity.

The kieffer_cutoffs argument accepts one direct cutoff state for every sampled primitive-cell volume. Both QHA schemes are supported. The frequency scheme fits the cutoff-volume relations and evaluates them during minimization and at the final equilibrium volumes; mode-Gruneisen analysis remains disabled for Kieffer-enriched runs until its acoustic weighting is implemented.

quantas.api.qha.create_input(source, destination, *, interface='crystal', is_list=False, reference=0, jobname='Quantas QHA input', formula_units=1, observer=None)

Create a normalized QHA YAML input from phonon output data.

QHA and HA intentionally share the same frontend-neutral phonon input generator. This public wrapper keeps the QHA lifecycle discoverable from quantas.api.qha without duplicating parsing or YAML logic. For independent multi-volume sources, compatible eigenvectors are tracked between adjacent volumes; native QHA sources retain their own continuity provenance.

Parameters:

source, destination, interface, is_list, reference, formula_units: See quantas.api.ha.create_input().
jobnamestr, optional: Human-readable QHA workflow title.
observerObserver or None, optional: Frontend-neutral observer receiving input-generation events.

Returns:

Path: Written YAML input path.

Parameters:

source (str | Path)
destination (str | Path)
interface (Literal['crystal', 'crystal-qha', 'phonopy'])
is_list (bool)
reference (int)
jobname (str)
formula_units (int)
observer (Observer | None)

Return type:

Path

quantas.api.qha.add_kieffer_input(source, destination, elastic_outputs, *, interface='crystal', pressure_policy='auto', manual_pressures_gpa=None, eos='BM3', polynomial_degree=3, maxfev=None, mu_order=12, phi_order=24, refinement_factor=2, batch_size=512)

Create a new QHA input enriched with Kieffer acoustic cutoffs.

Pressures for raw elastic tensors may come from the selected output interface, explicit values, an energy EOS, or a polynomial representation of the static energy-volume data already stored in source.

Parameters:

source, destinationstr or Path: Existing QHA YAML input and distinct enriched output path.
elastic_outputssequence of str or Path: One elastic-output file per sampled QHA volume.
interfacestr, optional: Elastic-output reader identifier.
pressure_policystr, optional: Pressure source: "auto", "output_stress", "manual", "energy_eos", or "energy_polynomial". Hyphenated forms are also accepted.
manual_pressures_gpasequence of float or None, optional: One pressure per elastic output when the manual policy is selected.
eosstr, optional: Integrated energy EOS used by "energy_eos".
polynomial_degreeint, optional: Degree used by "energy_polynomial".
maxfevint or None, optional: Optional maximum optimizer evaluations for the energy EOS fit.
mu_order, phi_order, refinement_factor, batch_sizeint, optional: Directional quadrature and batched Christoffel controls.

Returns:

Path: Written Kieffer-enriched YAML input.

Parameters:

source (str | Path)
destination (str | Path)
elastic_outputs (Sequence[str | Path])
interface (str)
pressure_policy (str)
manual_pressures_gpa (Sequence[float] | None)
eos (str)
polynomial_degree (int)
maxfev (int | None)
mu_order (int)
phi_order (int)
refinement_factor (int)
batch_size (int)

Return type:

Path

quantas.api.qha.available_energy_eos()

Return EOS tags accepted by QHA energy minimization options.

Return type:: tuple[str, …]

quantas.api.qha.read_input(source)

Read one Quantas QHA input file.

Parameters:

sourcestr or Path: Quantas multi-volume phonon YAML path.

Returns:

Input: Validated quasi-harmonic input contract.

Raises:

ValueError: If the file is malformed or lacks required volume/phonon data.

Parameters:

source (str | Path)

Return type:

QHAInput

quantas.api.qha.read_kieffer_input(source)

Read the Kieffer cutoff series embedded in a QHA YAML input.

Parameters:: source (str | Path)
Return type:: KiefferVolumeSeries

quantas.api.qha.normalize_input(source)

Return a normalized QHA input contract.

Parameters:

sourceInput, PhononInputData, str, or Path: Existing QHA/phonon contract or YAML path.

Returns:

Input: Validated QHA input suitable for inspect() and run().

Raises:

TypeError: If the input type is unsupported.
ValueError: If a supplied file cannot be parsed.

Parameters:

source (QHAInput | PhononInputData | str | Path)

Return type:

QHAInput

quantas.api.qha.inspect(input_data, options=None, *, include_polynomial=True, include_eos=True, polynomial_degree=None, eos=None, maxfev=None)

Inspect pressure-volume behavior without running the full workflow.

Parameters:

input_dataInput, PhononInputData, str, or Path: QHA input contract, neutral phonon data, or YAML path.
optionsOptions or None, optional: QHA defaults used by the preview.
include_polynomialbool, optional: Include the static polynomial preview.
include_eosbool, optional: Include the energy-EOS preview.
polynomial_degreeint or None, optional: Explicit static-energy polynomial degree.
eosstr or None, optional: Explicit integrated energy-EOS tag.
maxfevint or None, optional: Maximum optimizer evaluations for the EOS preview.

Returns:

Preview: Structured pressure-volume range and fit diagnostics.

Raises:

ValueError: If required volume/energy data are unavailable or a fit is invalid.

Parameters:

input_data (QHAInput | PhononInputData | str | Path)
options (QHAOptions | None)
include_polynomial (bool)
include_eos (bool)
polynomial_degree (int | None)
eos (str | None)
maxfev (int | None)

Return type:

PressureVolumePreview

quantas.api.qha.build_inspection_report(preview)

Build frontend-neutral tables for a QHA input inspection.

Parameters:

previewPreview: Structured preview returned by inspect().

Returns:

list of ReportTable: Input values, fit diagnostics, and fitted parameter tables.

Parameters:

preview (PressureVolumePreview)

Return type:

list[ReportTable]

quantas.api.qha.build_inspection_plots(preview, *, sample_points=201)

Build the frontend-neutral energy-volume inspection plot.

Successful polynomial and EOS fits are sampled only inside the observed volume interval. The selected EOS and all fit diagnostics come from the supplied Preview; no fit is repeated by the frontend.

Parameters:

previewPreview: Structured preview returned by inspect().
sample_pointsint, optional: Number of points used to sample each successful fitted curve.

Returns:

PlotCollection: Collection containing the observed energy-volume data and every successful fitted curve.

Parameters:

preview (PressureVolumePreview)
sample_points (int)

Return type:

PlotCollection

quantas.api.qha.run(input_data, options=None, kieffer_cutoffs=None, observer=None)

Run a quasi-harmonic thermodynamic workflow.

Parameters:

input_dataInput, PhononInputData, str, or Path: QHA input contract, neutral phonon data, or YAML path.
optionsOptions or None, optional: Thermodynamic domain, fitting, minimization, and unit controls.
kieffer_cutoffsKiefferVolumeSeries or None, optional: Direct multi-volume acoustic cutoffs for either QHA scheme.
observerObserver or None, optional: Frontend-neutral event observer.

Returns:

ResultData: Complete result envelope containing a QHA payload.

Raises:

ValueError: If the input, fits, or requested thermodynamic domain are invalid.

Parameters:

input_data (QHAInput | PhononInputData | str | Path)
options (QHAOptions | None)
kieffer_cutoffs (KiefferVolumeSeries | None)
observer (Observer | None)

Return type:

ResultData

quantas.api.qha.get_result(result)

Return the typed QHA payload from a result envelope.

Parameters:

resultResultData: Complete Quantas result envelope.

Returns:

Result: Module-specific quasi-harmonic result.

Raises:

ValueError: If the envelope is not a valid QHA result.

Parameters:

result (ResultData)

Return type:

QHAResult

Validation and comparison

validate_result evaluates completeness and internal consistency of one result. compare_results compares two results on common P–T states and is appropriate for method-sensitivity studies such as freq versus td or polynomial versus EOS minimization.

quantas.api.qha.ValidationSummary: alias of QHAValidationSummary

class quantas.api.qha.PropertyDifference(property_name, maximum_absolute, maximum_relative, root_mean_square, compared_points, maximum_absolute_temperature, maximum_absolute_pressure, maximum_relative_temperature, maximum_relative_pressure)

Bases: object

Numerical difference between two QHA property arrays.

Parameters:

property_namestr: QHA result attribute name.
maximum_absolutefloat: Maximum absolute difference.
maximum_relativefloat: Maximum symmetric relative difference.
root_mean_squarefloat: Root-mean-square absolute difference.
compared_pointsint: Number of finite points included in the comparison.
maximum_absolute_temperature, maximum_absolute_pressurefloat: Pressure-temperature location of the maximum absolute difference.
maximum_relative_temperature, maximum_relative_pressurefloat: Pressure-temperature location of the maximum relative difference.

Parameters:

property_name (str)
maximum_absolute (float)
maximum_relative (float)
root_mean_square (float)
compared_points (int)
maximum_absolute_temperature (float)
maximum_absolute_pressure (float)
maximum_relative_temperature (float)
maximum_relative_pressure (float)

quantas.api.qha.validate_result(result, input_data, *, numerical_tolerance=1e-10)

Validate one QHA result on its pressure-temperature grid.

Parameters:

resultQHAResult: Result to validate.
input_dataQHAInput: Input data used to establish sampled-volume and normalization limits.
numerical_tolerancefloat, optional: Absolute tolerance used for thermodynamic inequalities and zero-kelvin identities.

Returns:

QHAValidationSummary: Structured validation summary.

Raises:

ValueError: If the result does not contain pressure-temperature grids or equilibrium volumes.

Parameters:

result (QHAResult)
input_data (QHAInput)
numerical_tolerance (float)

Return type:

QHAValidationSummary

quantas.api.qha.compare_results(first, second, *, properties=('equilibrium_volume', 'isothermal_bulk_modulus', 'bulk_modulus_derivative', 'adiabatic_bulk_modulus', 'thermal_expansion', 'isochoric_heat_capacity', 'isobaric_heat_capacity', 'heat_capacity_difference', 'free_energy'))

Compare corresponding property arrays from two QHA results.

Parameters:

first, secondQHAResult: Results defined on the same pressure-temperature grid.
propertiesiterable of str, optional: Result attributes to compare.

Returns:

list of PropertyDifference: Difference metrics for available compatible arrays.

Raises:

ValueError: If temperature or pressure grids differ.

Parameters:

first (QHAResult)
second (QHAResult)
properties (Iterable[str])

Return type:

list[PropertyDifference]

Reporting, plotting, and persistence

Scalar QHA properties are stored on a native temperature-pressure grid. The default line representation shows each property as a function of temperature at every selected pressure. PlotOptions(curve_axis="pressure") produces the complementary pressure sections at exact stored temperatures when at least two pressure coordinates exist. Filled P–T maps continue to use the complete native grid.

Selections are expressed in the native units reported by describe_plots(). They must match stored coordinates exactly; the first public implementation does not interpolate or snap nearby values.

inventory = qha.describe_plots(result_data)
temperatures = inventory.context_by_key("temperature_grid").values

pressure_sections = qha.build_plots(
    result_data,
    properties=("equilibrium_volume", "isothermal_bulk_modulus"),
    options=qha.PlotOptions(
        curve_axis="pressure",
        selected_temperatures=(temperatures[0], temperatures[-1]),
    ),
)

quantas.api.qha.list_plot_properties(result)

List plot properties available in one QHA result.

Parameters:

resultResultData or Result: Complete envelope or module-specific QHA result.

Returns:

list of tuple of str: (key, attribute, description) records in stable display order.

Parameters:

result (ResultData | QHAResult)

Return type:

list[tuple[str, str, str]]

quantas.api.qha.describe_plots(result)

Return exact-grid QHA properties, sections, maps, and coordinates.

Parameters:

resultResultData: Complete quasi-harmonic result envelope.

Returns:

PlotInventory: Result-aware property metadata, temperature and pressure grids, and supported line-section and contour representations.

Parameters:

result (ResultData)

Return type:

PlotInventory

quantas.api.qha.build_report(result)

Build frontend-neutral QHA report tables.

Parameters:

resultResultData: Complete QHA result envelope.

Returns:

list of ReportTable: Ordered raw-value thermodynamic and structural tables.

Raises:

ValueError: If the result envelope is invalid.

Parameters:

result (ResultData)

Return type:

list[ReportTable]

quantas.api.qha.build_plots(result, properties=None, options=None)

Build frontend-neutral QHA plots.

Parameters:

resultResultData: Complete QHA result envelope.
propertieslist of str, tuple of str, or None, optional: Public property identifiers. Defaults select the standard plot family.
optionsPlotOptions or None, optional: Units, contour, and styling metadata for neutral plot construction.

Returns:

PlotCollection: Neutral one- and two-dimensional plot specifications.

Raises:

ValueError: If a property is unknown or required result data are unavailable.

Parameters:

result (ResultData)
properties (list[str] | tuple[str, ...] | None)
options (QHAPlotOptions | None)

Return type:

PlotCollection

quantas.api.qha.write_result(result, destination, *, report_text=None)

Write a native Quantas QHA HDF5 result.

Parameters:

resultResultData: Complete QHA result envelope.
destinationstr or Path: Destination path.
report_textstr or None, optional: Deterministic report text to embed in diagnostics.

Returns:

Path: Final native HDF5 path.

Raises:

ValueError: If the result envelope is invalid.

Parameters:

result (ResultData)
destination (str | Path)
report_text (str | None)

Return type:

Path

quantas.api.qha.read_result(source)

Read a native Quantas QHA HDF5 result.

Parameters:

sourcestr or Path: Native Quantas HDF5 path.

Returns:

ResultData: Restored result envelope.

Raises:

ValueError: If the file is not a supported QHA result.

Parameters:

source (str | Path)

Return type:

ResultData

quantas.api.qha.write_table(result, destination, *, property_name=None, include_uncertainty=True, file_format=None, table_format=None)

Write QHA pressure-temperature or structural data to a table.

Parameters:

resultResultData: Complete QHA result envelope.
destinationstr or Path: Destination table path.
property_namestr or None, optional: Property key, "structure", or None/"all" for all available pressure-temperature and structural properties.
include_uncertaintybool, optional: Include matching one-standard-deviation columns when present.
file_format{“txt”, “csv”} or None, optional: Output container. When omitted, .csv selects CSV and every other destination selects the human-readable text format.
table_formatTableFormat or None, optional: Numerical formatting rules for the table writer.

Returns:

Path: Written table path.

Parameters:

result (ResultData)
destination (str | Path)
property_name (str | None)
include_uncertainty (bool)
file_format (Literal['txt', 'csv'] | None)
table_format (QHATableFormat | None)

Return type:

Path

Quasi-Harmonic Approximation API

Recommended lifecycle

Scientific option types

Passive contracts

Input, inspection, and calculation

Validation and comparison

Reporting, plotting, and persistence

See also