Harmonic Approximation API

quantas.api.ha exposes the complete supported lifecycle for harmonic thermodynamics: create or read a normalized phonon input, run the calculation, retrieve the typed payload, build reports and plots, and persist the result.

Minimal lifecycle

from pathlib import Path
from quantas.api import ha, rendering

options = ha.Options(
    temperature_min=0.0,
    temperature_max=1000.0,
    temperature_step=100.0,
)
result_data = ha.run("mgo_b3lyp.yaml", options=options)
result = ha.get_result(result_data)

report = rendering.render_tables(ha.build_report(result_data))
Path("mgo_ha.log").write_text(report, encoding="utf-8")
ha.write_result(result_data, "mgo_ha.hdf5", report_text=report)

The returned payload retains the volume axis even when only one volume is present. Temperature-dependent properties normally have shape (nT, nV); zero-point energy remains temperature independent.

Passive contracts

quantas.api.ha.Input

alias of HAInput

quantas.api.ha.Options

alias of HAOptions

quantas.api.ha.Result

alias of HAResult

Input preparation

create_input converts supported code-specific outputs to the normalized phonon YAML contract. read_input parses that YAML. normalize_input accepts either the public HA input, the shared phonon input contract, or a path.

quantas.api.ha.create_input(source, destination, *, interface='crystal', is_list=False, reference=0, jobname='Quantas HA input', formula_units=1)

Create a normalized HA YAML input from an interface output.

Parameters:
sourcestr or Path

Quantum-mechanical output file or file list.

destinationstr or Path

Destination YAML path.

interfacestr, optional

Code-specific reader identifier.

is_listbool, optional

Interpret source as a text file containing multiple output paths.

referenceint, optional

Reference structure index for multi-structure inputs.

jobnamestr, optional

Human-readable workflow title.

formula_unitsint, optional

Formula units represented by the crystallographic cell.

Returns:
Path

Written YAML input path.

Raises:
ValueError

If source data cannot be parsed or normalized.

Parameters:

  • source (str | Path)

  • destination (str | Path)

  • interface (str)

  • is_list (bool)

  • reference (int)

  • jobname (str)

  • formula_units (int)

Return type:

Path

quantas.api.ha.read_input(source)

Read one Quantas HA input file.

Parameters:
sourcestr or Path

Quantas phonon YAML path.

Returns:
Input

Validated harmonic input contract.

Raises:
ValueError

If the input is malformed or incomplete.

Parameters:

source (str | Path)

Return type:

HAInput

quantas.api.ha.normalize_input(source)

Return a normalized HA input contract.

Parameters:
sourceInput, PhononInputData, str, or Path

Existing harmonic/phonon contract or YAML path.

Returns:
Input

Validated harmonic input suitable for run().

Raises:
TypeError

If the input type is unsupported.

ValueError

If a supplied file cannot be parsed.

Parameters:

source (HAInput | PhononInputData | str | Path)

Return type:

HAInput

Calculation and typed results

quantas.api.ha.run(input_data, options=None, observer=None)

Run a harmonic thermodynamic workflow.

Parameters:
input_dataInput, PhononInputData, str, or Path

Harmonic input contract, neutral phonon data, or YAML path.

optionsOptions or None, optional

Temperature grid, units, and scientific calculation controls.

observerObserver or None, optional

Frontend-neutral event observer.

Returns:
ResultData

Complete result envelope containing a harmonic payload.

Raises:
ValueError

If the input or selected temperature domain is invalid.

Parameters:
Return type:

ResultData

quantas.api.ha.get_result(result)

Return the typed HA payload from a result envelope.

Parameters:
resultResultData

Complete Quantas result envelope.

Returns:
Result

Module-specific harmonic result.

Raises:
ValueError

If the envelope is not a valid HA result.

Parameters:

result (ResultData)

Return type:

HAResult

Reports, plots, and persistence

quantas.api.ha.build_report(result)

Build frontend-neutral HA report tables.

Parameters:
resultResultData

Complete harmonic result envelope.

Returns:
list of ReportTable

Ordered raw-value report tables.

Raises:
ValueError

If the result envelope is invalid.

Parameters:

result (ResultData)

Return type:

list[ReportTable]

quantas.api.ha.build_plots(result, properties=None, *, unit=None)

Build frontend-neutral HA plots.

Parameters:
resultResultData

Complete harmonic result envelope.

Returns:
PlotCollection

Neutral thermodynamic plot specifications.

Raises:
ValueError

If the result envelope is invalid.

Parameters:

  • result (ResultData)

  • properties (str | list[str] | tuple[str, ...] | None)

  • unit (str | None)

Return type:

PlotCollection

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

Write a native Quantas HA HDF5 result.

Parameters:
resultResultData

Complete HA 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.ha.read_result(source)

Read a native Quantas HA HDF5 result.

Parameters:
sourcestr or Path

Native Quantas HDF5 path.

Returns:
ResultData

Restored result envelope.

Raises:
ValueError

If the file is not a supported HA result.

Parameters:

source (str | Path)

Return type:

ResultData

See also