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.PlotOptions: alias of HAPlotOptions

quantas.api.ha.CurveAxis: alias of Literal[‘temperature’, ‘volume’]

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

class quantas.api.ha.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]

quantas.api.ha.Result: alias of HAResult

class quantas.api.ha.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).

Input preparation

create_input converts supported code-specific outputs to the normalized phonon YAML contract. For compatible multi-volume outputs it also performs the shared structural normalization and mode-continuity analysis when eigenvectors are available. read_input parses the YAML. normalize_input accepts either the public HA input, the shared phonon input contract, or a path.

The scientific generation procedure is documented in Phonon input generation and mode continuity.

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

Create a normalized HA YAML input from an interface output.

Compatible multi-volume sources are checked for common q-point sampling, units, and structural normalization. When normalized phonon eigenvectors are available, the shared generator also evaluates mode continuity and stores its diagnostics in the YAML for possible QHA reuse.

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.
observerObserver or None, optional: Frontend-neutral observer receiving input-generation events.

Returns:

Path: Written YAML input path.

Raises:

ValueError: If source data cannot be parsed or normalized.

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.ha.add_kieffer_input(source, destination, elastic_outputs, *, interface='crystal', pressure_policy='auto', manual_pressures_gpa=None, mu_order=12, phi_order=24, refinement_factor=2, batch_size=512)

Create a new HA input enriched with Kieffer acoustic cutoffs.

Raw elastic tensors are corrected using explicitly selected hydrostatic pressures. Energy-derived pressure sources are reserved for multi-volume QHA inputs. The source phonon input is never overwritten.

Parameters:

source, destinationstr or Path: Existing HA YAML input and distinct enriched output path.
elastic_outputssequence of str or Path: Elastic-output files containing the state at the HA volume.
interfacestr, optional: Elastic-output reader identifier.
pressure_policystr, optional: "auto", "output_stress", or "manual".
manual_pressures_gpasequence of float or None, optional: One pressure per elastic output when the manual policy is selected.
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)
mu_order (int)
phi_order (int)
refinement_factor (int)
batch_size (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.read_kieffer_input(source)

Read the Kieffer cutoff series embedded in an HA YAML input.

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

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

An explicit single-volume Kieffer cutoff series can be supplied through kieffer_cutoffs. This API-stage integration requires primitive Gamma-only phonons and adds three acoustic branches without changing the stored Gamma frequencies. add_kieffer_input provides the corresponding persistent YAML representation, while calculation activation remains explicit through the kieffer_cutoffs argument.

quantas.api.ha.run(input_data, options=None, kieffer_cutoffs=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.
kieffer_cutoffsKiefferVolumeSeries or None, optional: Direct cutoff state used to add the three Kieffer acoustic branches.
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:

input_data (HAInput | PhononInputData | str | Path)
options (HAOptions | None)
kieffer_cutoffs (KiefferVolumeSeries | None)
observer (Observer | None)

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

HA properties are stored on a native temperature-volume grid. The default line representation uses temperature as the independent variable and one curve per sampled volume. PlotOptions(curve_axis="volume") produces the complementary exact-grid sections at selected stored temperatures. Setting The volume-axis representation is available only when at least two matching sampled volumes exist. include_contours=True adds a native-grid volume-temperature map when at least two temperatures and two matching sampled volumes are available.

selected_volumes and selected_temperatures must contain values returned by describe_plots(); Quantas does not interpolate missing coordinates.

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

volume_sections = ha.build_plots(
    result_data,
    properties=("free_energy",),
    options=ha.PlotOptions(
        curve_axis="volume",
        selected_temperatures=(temperatures[0], temperatures[-1]),
        include_contours=True,
    ),
)

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.describe_plots(result)

Return result-aware HA plot properties and sampled grids.

Parameters:

resultResultData: Complete harmonic result envelope.

Returns:

PlotInventory: Available thermodynamic properties, their symbols and units, and the exact temperature and volume context represented by the builder.

Parameters:

result (ResultData)

Return type:

PlotInventory

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

Build frontend-neutral HA plots.

Parameters:

resultResultData: Complete harmonic result envelope.
propertiesstr, list of str, tuple of str, or None, optional: Requested harmonic property identifiers.
unitstr or None, optional: Backwards-compatible energy-unit override. When options also defines energy_unit, both values must agree.
optionsPlotOptions or None, optional: Exact-grid section and contour-preparation options.

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)
options (HAPlotOptions | 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

quantas.api.ha.write_table(result, destination, *, property_name='F', unit=None)

Write one HA thermodynamic property as a neutral text table.

Parameters:

resultResultData: Complete harmonic result envelope.
destinationstr or Path: Destination path. The .dat suffix is applied when absent.
property_namestr, optional: Historical property key or Result attribute name.
unitstr or None, optional: Requested output unit for energy-like, entropy, or heat-capacity data.

Returns:

Path: Written table path.

Raises:

ValueError: If the result or requested property is invalid.

Parameters:

result (ResultData)
destination (str | Path)
property_name (str)
unit (str | None)

Return type:

Path

Harmonic Approximation API

Minimal lifecycle

Passive contracts

Input preparation

Calculation and typed results

Reports, plots, and persistence

See also