Interoperability API

quantas.api.interop contains explicit, scientifically meaningful transformations between public workflows. These functions centralize unit conversion, tensor condition, coverage checks, normalization, and provenance; they are preferable to manually moving arrays between modules.

The complete scientific contracts, CLI equivalents, failure policies, and end-to-end examples are described in Interoperability between workflows. This page defines the callable contract.

QHA loading and coupling

quantas.api.interop.load_qha_result(source, *, options=None)

Load or calculate a validated QHA result envelope.

Parameters:
sourceResultData, QHAInput, PhononInputData, str, or Path

Existing result, QHA/phonon input, native QHA HDF5 path, or YAML input path.

optionsQHAOptions or None, optional

QHA options used only when a calculation is required.

Returns:
ResultData

Validated QHA result envelope.

Raises:
ValueError

If a file or envelope does not contain a valid QHA result.

Parameters:
Return type:

ResultData

quantas.api.interop.qha_to_thermoelastic_context(input_data, qha_source, *, qha_options=None)

Pair elastic-volume input with QHA data and validate coverage.

Parameters:
input_dataThermoelasticInput, str, or Path

Elastic-volume series or thermoelastic YAML path.

qha_sourceResultData, QHAInput, PhononInputData, str, or Path

Existing QHA result, native HDF5 result, or input requiring a QHA run.

qha_optionsQHAOptions or None, optional

Options used when qha_source must be calculated.

Returns:
ThermoelasticContext

Validated coupling context including extrapolation and completeness diagnostics.

Raises:
ValueError

If QHA equilibrium volumes are missing, array shapes are inconsistent, or primitive atomic normalization differs.

Parameters:

  • input_data (ThermoelasticInput | str | Path)

  • qha_source (ResultData | QHAInput | PhononInputData | str | Path)

  • qha_options (QHAOptions | None)

Return type:

ThermoelasticContext

Thermoelastic state to SEISMIC

quantas.api.interop.thermoelastic_to_seismic(source, *, pressure, temperature, tensor_condition='adiabatic', extrapolation_policy='fail')

Build a seismic input from one thermoelastic state.

Parameters:
sourceResultData, str, or Path

Thermoelastic result envelope or native HDF5 path.

pressurefloat

Requested pressure in GPa.

temperaturefloat

Requested temperature in K.

tensor_condition{“isothermal”, “adiabatic”}, optional

Stiffness tensor condition exported to SEISMIC.

extrapolation_policy{“fail”, “warn”, “allow”}, optional

Behavior outside the calibrated volume/thermodynamic domain.

Returns:
SeismicInput

Density and stiffness tensor for the requested state.

Raises:
ValueError

If the state cannot be reconstructed or density/stiffness is invalid.

TypeError

If source is not a result envelope or path.

Parameters:

  • source (ResultData | str | Path)

  • pressure (float)

  • temperature (float)

  • tensor_condition (Literal['isothermal', 'adiabatic'])

  • extrapolation_policy (Literal['fail', 'warn', 'allow'])

Return type:

SeismicInput

Complete public-API example

The downloadable example performs the complete supported chain and writes reusable HDF5 checkpoints:

workflow_api.py

Run it from the project root with:

python examples/interoperability/workflow_api.py \
    --output-dir interoperability_api

See also