Thermoelasticity plotting API

These functions build frontend-neutral plot specifications. They do not import or configure Matplotlib directly. Pass the returned quantas.api.plotting.PlotCollection to quantas.api.rendering.render_plots().

Result-aware discovery

quantas.api.thermoelasticity.describe_plots(result)

Return result-aware thermoelastic plot families and scientific context.

Parameters:
resultResultData

Complete thermoelastic result envelope.

Returns:
PlotInventory

Available calibration, P-T, profile, comparison, and domain families, together with exact stored grids, components, tensor conditions, and profile names.

Parameters:

result (ResultData)

Return type:

PlotInventory

The returned quantas.api.plotting.PlotInventory describes cumulative workflow capabilities rather than assigning one exclusive result type. A thermoelastic archive may expose any compatible subset of:

fit

Independent elastic-volume calibration fits and residual diagnostics.

pt

Isothermal or adiabatic stiffness values and uncertainty quantities on a two-dimensional pressure-temperature grid.

profile

Absolute or reference-relative stiffness along archived depth paths.

compare

Isothermal–adiabatic sections at fixed pressure or temperature when both tensor fields are valid.

domain

Equilibrium-volume coverage, extrapolation masks, and optional profile paths.

Point and one-dimensional analysis archives do not advertise contour families. The public default builder falls back to the archived calibration fits instead of attempting to construct an invalid P–T contour. Comparison coordinates are evaluated through the calibrated public analysis engine; they are not nearest-grid selections.

Component resolution

quantas.api.thermoelasticity.resolve_components(result, components=None, *, group='independent', nonzero_tolerance=1e-12)

Resolve explicit components or one semantic component group.

Parameters:
resultThermoelasticResult

Thermoelastic result containing component metadata and, optionally, reconstructed tensors.

componentssequence of str or None, optional

Explicit component labels. When supplied, group is ignored.

groupThermoelasticComponentGroup, optional

Semantic component group.

nonzero_tolerancefloat, optional

Absolute GPa threshold used when full reconstructed tensors are available.

Returns:
tuple of str

Ordered canonical component labels.

Raises:
ValueError

If a requested component or group is unavailable.

Parameters:

  • result (ThermoelasticResult)

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

  • group (Literal['independent', 'normal', 'shear', 'coupling', 'offdiagonal', 'all'])

  • nonzero_tolerance (float)

Return type:

tuple[str, …]

P–T maps

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

Build pressure-temperature maps for selected stiffness components.

Parameters:
resultResultData or ThermoelasticResult

Reconstructed thermoelastic result.

componentssequence of str or None, optional

Explicit components. When omitted, component_group is resolved.

component_groupThermoelasticComponentGroup, optional

Semantic group used when explicit components are absent.

optionsThermoelasticPTPlotOptions or None, optional

Quantity, contour, extrapolation, and layout controls.

Returns:
PlotCollection

Separate or faceted contour specifications.

Raises:
ValueError

If the archive does not contain a two-dimensional P-T grid.

Parameters:

  • result (ResultData | ThermoelasticResult)

  • components (Sequence[str] | None)

  • component_group (Literal['independent', 'normal', 'shear', 'coupling', 'offdiagonal', 'all'])

  • options (ThermoelasticPTPlotOptions | None)

Return type:

PlotCollection

Profile plots

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

Build absolute or relative stiffness plots along a depth profile.

Parameters:
resultResultData or ThermoelasticResult

Thermoelastic result containing one or more archived depth profiles.

profile_namestr or None, optional

Name of the profile to plot. When omitted, the sole archived profile is selected; an archive with several profiles requires an explicit name.

componentssequence of str or None, optional

Explicit stiffness components.

component_groupThermoelasticComponentGroup, optional

Semantic group used when explicit components are absent.

optionsThermoelasticProfilePlotOptions or None, optional

Profile mode, layout, uncertainty, color, and annotation controls.

Returns:
PlotCollection

Overlay, faceted, or separate neutral profile specifications.

Raises:
ValueError

If the requested profile or component data are unavailable.

Parameters:

  • result (ResultData | ThermoelasticResult)

  • profile_name (str | None)

  • components (Sequence[str] | None)

  • component_group (Literal['independent', 'normal', 'shear', 'coupling', 'offdiagonal', 'all'])

  • options (ThermoelasticProfilePlotOptions | None)

Return type:

PlotCollection

Isothermal–adiabatic comparison

quantas.api.thermoelasticity.build_compare_plots(result_data, *, components=None, component_group='independent', options=None)

Build line plots comparing \(C^T_{IJ}\) and \(C^S_{IJ}\).

One pressure or one temperature is held fixed exactly, while the opposite archived coordinate is varied. The model is re-evaluated at the requested coordinate rather than selecting the nearest stored grid plane.

Parameters:
result_dataResultData

Fit or analysis archive containing a thermoelastic payload.

componentssequence of str or None, optional

Explicit stiffness components.

component_groupstr, optional

Semantic component group when explicit labels are absent.

optionsThermoelasticComparePlotOptions or None, optional

Fixed coordinate and presentation controls.

Returns:
PlotCollection

Frontend-neutral line or panel specifications.

Raises:
ValueError

If adiabatic stiffness is unavailable at any requested state.

Parameters:

  • result_data (ResultData)

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

  • component_group (Literal['independent', 'normal', 'shear', 'coupling', 'offdiagonal', 'all'])

  • options (ThermoelasticComparePlotOptions | None)

Return type:

PlotCollection

Domain diagnostics

quantas.api.thermoelasticity.build_domain_plot(result, *, profile_names=None, options=None)

Build a P-T domain map with volume coverage and optional profiles.

Parameters:
resultResultData or ThermoelasticResult

Thermoelastic result containing the QHA grid and optional profiles.

profile_namessequence of str or None, optional

Explicit archived profiles to overlay. None selects all profiles when options.show_profiles is enabled.

optionsThermoelasticDomainPlotOptions or None, optional

Contour, profile, and extrapolation controls.

Returns:
PlotCollection

Collection containing one contour specification.

Raises:
ValueError

If the archive lacks a two-dimensional QHA grid or a requested profile.

Parameters:

  • result (ResultData | ThermoelasticResult)

  • profile_names (Sequence[str] | None)

  • options (ThermoelasticDomainPlotOptions | None)

Return type:

PlotCollection