Thermoelasticity calibration API

Calibration combines a normalized elastic-volume series with a QHA result, fits the reference EOS and independent stiffness components, and returns a reusable quantas.api.common.ResultData envelope.

Input construction and normalization

quantas.api.thermoelasticity.create_input(sources, destination, *, interface='crystal', is_list=False, jobname='Quantas quasi-static thermoelastic input', reference=None, symprec=1e-05, angle_tolerance=-1.0, elastic_tolerance=0.001, pressure_tolerance=0.05, structure_correspondence_tolerance=0.5)

Create a thermoelastic YAML input from elastic-tensor outputs.

Parameters:

sourcesstr, Path, or sequence of str or Path: Code-specific elastic-tensor outputs or a file-list path.
destinationstr or Path: Destination YAML path.
interfacestr, optional: Code-specific interface identifier.
is_listbool, optional: Interpret a single source as a text file containing output paths.
jobnamestr, optional: Human-readable workflow title.
referenceint or None, optional: Reference elastic-volume point.
symprecfloat, optional: Cartesian symmetry tolerance.
angle_tolerancefloat, optional: Symmetry angle tolerance in degrees.
elastic_tolerancefloat, optional: Elastic symmetry tolerance in GPa.
pressure_tolerancefloat, optional: Pressure consistency tolerance in GPa.
structure_correspondence_tolerancefloat, optional: Atomic correspondence tolerance in angstrom.

Returns:

Path: Written thermoelastic YAML path.

Raises:

ValueError: If outputs are inconsistent or cannot be normalized to one elastic volume series.

Parameters:

sources (str | Path | Sequence[str | Path])
destination (str | Path)
interface (str)
is_list (bool)
jobname (str)
reference (int | None)
symprec (float)
angle_tolerance (float)
elastic_tolerance (float)
pressure_tolerance (float)
structure_correspondence_tolerance (float)

Return type:

Path

quantas.api.thermoelasticity.read_input(source)

Read one Quantas thermoelastic input file.

Parameters:

sourcestr or Path: Quantas thermoelastic YAML path.

Returns:

Input: Validated elastic-volume input contract.

Raises:

ValueError: If the YAML schema or elastic series is invalid.

Parameters:

source (str | Path)

Return type:

ThermoelasticInput

quantas.api.thermoelasticity.normalize_input(source)

Return a normalized thermoelastic input contract.

Parameters:

sourceInput, str, or Path: Existing input contract or YAML path.

Returns:

Input: Validated input suitable for coupling.

Raises:

TypeError: If the source type is unsupported.
ValueError: If a supplied YAML file is invalid.

Parameters:

source (ThermoelasticInput | str | Path)

Return type:

ThermoelasticInput

QHA coupling context

quantas.api.thermoelasticity.prepare_context(input_data, qha_source, *, qha_options=None)

Build the validated QHA–elasticity coupling context.

Parameters:

input_dataInput, str, or Path: Elastic-volume series or thermoelastic YAML path.
qha_sourceResultData, QHAInput, PhononInputData, str, or Path: Existing QHA result, HDF5 path, or QHA input requiring calculation.
qha_optionsQHAOptions or None, optional: Options used only when a QHA calculation is required.

Returns:

Context: Coupling context with volume coverage and data-completeness diagnostics.

Raises:

ValueError: If the QHA and elastic datasets cannot be coupled consistently.

Parameters:

input_data (ThermoelasticInput | str | Path)
qha_source (ResultData | QHAInput | PhononInputData | str | Path)
qha_options (QHAOptions | None)

Return type:

ThermoelasticContext

Calculation

quantas.api.thermoelasticity.run(input_data, qha_source, *, options=None, qha_options=None, profiles=(), observer=None)

Run the complete QHA–elasticity thermoelastic workflow.

Parameters:

input_dataInput, str, or Path: Elastic-volume series or thermoelastic YAML path.
qha_sourceResultData, QHAInput, PhononInputData, str, or Path: QHA result, native HDF5 path, or input requiring a QHA calculation.
optionsOptions or None, optional: Thermoelastic fitting and reconstruction controls.
qha_optionsQHAOptions or None, optional: Options used only when qha_source must be calculated.
profilessequence of DepthProfile, optional: Depth paths evaluated after model calibration.
observerObserver or None, optional: Frontend-neutral workflow observer.

Returns:

ResultData: Calibrated result envelope, optionally extended with profile analyses.

Raises:

ValueError: If coupling, fitting, reconstruction, or profile evaluation fails.

Parameters:

input_data (ThermoelasticInput | str | Path)
qha_source (ResultData | QHAInput | PhononInputData | str | Path)
options (ThermoelasticOptions | None)
qha_options (QHAOptions | None)
profiles (Sequence[ThermoelasticDepthProfile])
observer (Observer | None)

Return type:

ResultData

Notes

Optional depth profiles use the same post-fit engine as the CLI and future GUI, so all frontends share the same numerical path.

quantas.api.thermoelasticity.run_context(context, *, options=None, observer=None)

Run a thermoelastic workflow from a prevalidated context.

Parameters:

contextContext: Validated QHA–elasticity coupling context.
optionsOptions or None, optional: Fit, quality, stability, frame, and reconstruction controls.
observerObserver or None, optional: Frontend-neutral workflow observer.

Returns:

ResultData: Calibrated thermoelastic fit result envelope.

Raises:

ValueError: If fitting, quality, or stability requirements are not satisfied.

Parameters:

context (ThermoelasticContext)
options (ThermoelasticOptions | None)
observer (Observer | None)

Return type:

ResultData

Typed result and persistence

quantas.api.thermoelasticity.get_result(result)

Return the typed thermoelastic payload from a result envelope.

Parameters:

resultResultData: Complete Quantas result envelope.

Returns:

Result: Module-specific thermoelastic result.

Raises:

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

Parameters:

result (ResultData)

Return type:

ThermoelasticResult

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

Write a native Quantas thermoelastic HDF5 result.

Parameters:

resultResultData: Complete thermoelastic 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.thermoelasticity.read_result(source)

Read a native Quantas thermoelastic HDF5 result.

Parameters:

sourcestr or Path: Native Quantas HDF5 path.

Returns:

ResultData: Restored result envelope.

Raises:

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

Parameters:

source (str | Path)

Return type:

ResultData

Calibration reporting and default plots

quantas.api.thermoelasticity.build_report(result, *, level='standard')

Build frontend-neutral thermoelastic report tables.

Parameters:

resultResultData or Result: Complete envelope or module-specific thermoelastic result.
level{“standard”, “extended”, “debug”}, optional: Scientific report detail.

Returns:

list of ReportTable: Ordered fit, reconstruction, stability, and provenance tables.

Raises:

ValueError: If the result is invalid.

Parameters:

result (ResultData | ThermoelasticResult)
level (Literal['standard', 'extended', 'debug'])

Return type:

list[ReportTable]

quantas.api.thermoelasticity.build_fit_plots(result, components=None, *, component_group='independent', options=None)

Build observed, fitted, confidence-band, and residual specifications.

Parameters:

resultResultData or ThermoelasticResult: Thermoelastic fit result.
componentssequence of str or None, optional: Explicit independent components. When omitted, component_group is resolved against the available result.
component_groupThermoelasticComponentGroup, optional: Semantic component group used when components is omitted. Fit plots are emitted only for components carrying independent fit records.
optionsThermoelasticFitPlotOptions or None, optional: Fit-plot controls.

Returns:

PlotCollection: One line or two-panel fit specification per selected component.

Raises:

ValueError: If no selected component has a fit record.

Parameters:

result (ResultData | ThermoelasticResult)
components (Sequence[str] | None)
component_group (Literal['independent', 'normal', 'shear', 'coupling', 'offdiagonal', 'all'])
options (ThermoelasticFitPlotOptions | None)

Return type:

PlotCollection

quantas.api.thermoelasticity.build_plots(result)

Build default plots appropriate for the result stage.

Parameters:

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

Returns:

PlotCollection: Fit, pressure-temperature, or profile plots selected from the data available in the result.

Raises:

ValueError: If the result is invalid or lacks plottable data.

Parameters:

result (ResultData | ThermoelasticResult)

Return type:

PlotCollection