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",
)
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’]

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

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

Input, inspection, and calculation

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.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.run(input_data, options=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.
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)
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

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.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

Quasi-Harmonic Approximation API

Recommended lifecycle

Scientific option types

Passive contracts

Input, inspection, and calculation

Validation and comparison

Reporting, plotting, and persistence

See also