Thermoelasticity post-fit analysis and export API

Post-fit analysis evaluates the calibrated model at requested states. A grid analysis and a profile-only analysis are separate operations because a generic P–T rectangle should not be constructed when only a geological path is required.

Grid construction and analysis

quantas.api.thermoelasticity.regular_grid(start, stop, step)

Return an inclusive validated float64 grid.

Parameters:

  • start (float)

  • stop (float)

  • step (float)

Return type:

NDArray[float64]

quantas.api.thermoelasticity.analyze_grid(result_data, *, temperature=None, pressure=None, profiles=(), extrapolation_policy=None)

Create a post-fit archive for a grid and optional depth profiles.

Parameters:

  • result_data (ResultData)

  • temperature (ArrayLike | None)

  • pressure (ArrayLike | None)

  • profiles (Sequence[ThermoelasticDepthProfile])

  • extrapolation_policy (str | None)

Return type:

ResultData

quantas.api.thermoelasticity.analyze_profiles(result_data, profiles, *, options=None, extrapolation_policy=None)

Evaluate only geological profiles without reconstructing a P-T grid.

Parameters:
result_dataResultData

Completed thermoelastic fit archive.

profilessequence of ThermoelasticDepthProfile

One or more named depth-pressure-temperature paths.

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

Override the policy stored in the fit archive.

Returns:
ResultData

Copy of the fit result retaining its archived QHA support fields and containing evaluated profile results, while leaving grid stiffness arrays absent.

Raises:
ValueError

If fitting did not complete or no profile was supplied.

Parameters:

  • result_data (ResultData)

  • profiles (Sequence[ThermoelasticDepthProfile])

  • options (ThermoelasticOptions | None)

  • extrapolation_policy (str | None)

Return type:

ResultData

Profiles

quantas.api.thermoelasticity.profile_presets()

Return all built-in profile specifications in stable display order.

Returns:
tuple of ThermoelasticProfilePreset

Quantitative scientific Earth-profile presets.

Return type:

tuple[ThermoelasticProfilePreset, …]

quantas.api.thermoelasticity.build_profile_preset(name)

Build one named built-in geological profile.

Parameters:
namestr

Preset identifier returned by thermoelastic_profile_presets().

Returns:
ThermoelasticDepthProfile

Generated profile.

Raises:
ValueError

If name is not a known preset.

Parameters:

name (str)

Return type:

ThermoelasticDepthProfile

quantas.api.thermoelasticity.read_depth_profile(filename, *, name=None)

Read a depth-pressure-temperature profile from CSV or whitespace text.

Parameters:
filenamestr or Path

Input file. A header containing depth_km, P_GPa and T_K is required. Comma-separated and whitespace-separated files are accepted.

namestr or None, optional

Profile identifier. The filename stem is used by default.

Returns:
ThermoelasticDepthProfile

Sorted and validated profile.

Raises:
ValueError

If required columns are absent, values are invalid, or depths repeat.

Parameters:

  • filename (str | Path)

  • name (str | None)

Return type:

ThermoelasticDepthProfile

quantas.api.thermoelasticity.read_profile_spec(filename)

Read a composed geothermobarometric profile from YAML.

Parameters:
filenamestr or Path

Earth-profile YAML specification. Pressure and temperature models are built independently by quantas.core.physics.earth_profiles; relative tabulated paths are resolved from the YAML location.

Returns:
ThermoelasticDepthProfile

Evaluated profile adapted to the thermoelastic workflow contract.

Raises:
ValueError

If the specification or any referenced model is invalid.

Parameters:

filename (str | Path)

Return type:

ThermoelasticDepthProfile

quantas.api.thermoelasticity.write_profile_template(filename, *, overwrite=False)

Write an editable Earth-profile YAML specification template.

Parameters:
filenamestr or Path

Destination YAML file.

overwritebool, optional

Replace an existing file.

Returns:
Path

Written template path.

Parameters:

  • filename (str | Path)

  • overwrite (bool)

Return type:

Path

Notes

The template combines PREM pressure with a two-part temperature model: a user-editable continental conductive lithosphere and the Katsura (2022) mantle adiabat. All values are examples and should be reviewed for the intended tectonic setting.

Tensor selection and report tables

quantas.api.thermoelasticity.select_stiffness_tensor(result, condition='isothermal')

Return stiffness and uncertainty for one thermodynamic condition.

Parameters:
resultThermoelasticResult or ThermoelasticProfileResult

Reconstructed grid or depth-profile result.

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

Requested thermodynamic condition.

Returns:
tuple of ndarray and ndarray or None

Stiffness and optional one-sigma uncertainty in GPa.

Raises:
ValueError

If the requested tensor is unavailable or contains invalid states.

Parameters:

  • result (ThermoelasticResult | ThermoelasticProfileResult)

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

Return type:

tuple[NDArray[float64], NDArray[float64] | None]

quantas.api.thermoelasticity.point_table(result, *, tensor_condition='adiabatic')

Return a compact human-readable table for one reconstructed state.

Parameters:

  • result (ThermoelasticResult)

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

Return type:

ReportTable

quantas.api.thermoelasticity.grid_info_table(result)

Return the archived pressure-temperature coverage summary.

Parameters:

result (ThermoelasticResult)

Return type:

ReportTable

Tabular and interoperable exports

quantas.api.thermoelasticity.write_grid_table(result, filename, *, tensor_condition='both', file_format='csv', include_uncertainties=True, overwrite=False)

Write one wide row per pressure-temperature grid state.

Only symmetry-independent stiffness components are exported. Isothermal and adiabatic fields occupy separate columns when tensor_condition is "both"; rows are never duplicated.

Parameters:

  • result (ThermoelasticResult)

  • filename (str | Path)

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

  • file_format (Literal['csv', 'text'])

  • include_uncertainties (bool)

  • overwrite (bool)

Return type:

Path

quantas.api.thermoelasticity.write_profile_table(result, filename, *, profile_name=None, tensor_condition='both', file_format='csv', include_uncertainties=True, overwrite=False)

Write one wide row per depth along one archived geological profile.

Parameters:
resultThermoelasticResult

Thermoelastic payload containing one or more evaluated profiles.

filenamestr or Path

Destination CSV or deterministic tab-separated text file.

profile_namestr or None, optional

Profile to export. Omission is accepted only when exactly one profile is present.

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

Stiffness fields written as columns.

file_format{“csv”, “text”}, optional

Portable comma-separated or tab-separated representation.

include_uncertaintiesbool, optional

Include one-sigma columns when available.

overwritebool, optional

Replace an existing destination.

Returns:
Path

Written path.

Parameters:

  • result (ThermoelasticResult)

  • filename (str | Path)

  • profile_name (str | None)

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

  • file_format (Literal['csv', 'text'])

  • include_uncertainties (bool)

  • overwrite (bool)

Return type:

Path

quantas.api.thermoelasticity.write_state_input(result, filename, *, tensor_condition='adiabatic', overwrite=False)

Write one reconstructed state in the shared elasticity text format.

The output contains a job title, a complete symmetric 6 x 6 stiffness matrix in GPa, and density in kg m-3. The same file can be read by both quantas.modules.elasticity and quantas.modules.seismic; Elasticity ignores the final density line, while SEISMIC requires it.

Parameters:
resultThermoelasticResult

Reconstructed result containing exactly one pressure-temperature state.

filenamestr or Path

Destination text file.

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

Thermodynamic stiffness condition written to the file.

overwritebool, optional

Replace an existing destination.

Returns:
Path

Written path.

Raises:
ValueError

If the result does not contain exactly one valid state or the requested tensor condition is unavailable.

FileExistsError

If the destination exists and overwrite is false.

Parameters:

  • result (ThermoelasticResult)

  • filename (str | Path)

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

  • overwrite (bool)

Return type:

Path

quantas.api.thermoelasticity.write_tensor_export(result_data, filename, *, file_format='txt', tensor_condition='isothermal', include_uncertainties=True, include_grid=True, include_profiles=True, overwrite=False)

Write reconstructed tensors from one thermoelastic result archive.

Parameters:
result_dataResultData

Result envelope containing a completed thermoelastic payload.

filenamestr or Path

Destination path.

file_format{“txt”, “csv”}, optional

Export format.

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

Thermodynamic tensor condition to export.

include_uncertaintiesbool, optional

Include one-sigma tensor uncertainties where available.

include_grid, include_profilesbool, optional

Select rectangular-grid and depth-profile sections.

overwritebool, optional

Permit replacement of an existing file.

Returns:
Path

Written destination.

Parameters:

  • result_data (ResultData)

  • filename (str | Path)

  • file_format (str)

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

  • include_uncertainties (bool)

  • include_grid (bool)

  • include_profiles (bool)

  • overwrite (bool)

Return type:

Path