Thermoelasticity contracts and selectors

This page documents the passive calibration, analysis, profile, and plotting contracts. Literal selectors are listed explicitly so type-checkers and frontends can expose the same accepted values.

Scientific selectors

quantas.api.thermoelasticity.InputInterface

alias of Literal[‘crystal’]

quantas.api.thermoelasticity.PressureSourcePolicy

alias of Literal[‘auto’, ‘output_stress’, ‘manual’, ‘energy_eos’, ‘energy_polynomial’]

class quantas.api.thermoelasticity.FitMethod(*values)

Bases: str, Enum

Supported general regression strategies.

Attributes:
OLS

Ordinary nonlinear least squares using vertical residuals.

WLS

Weighted nonlinear least squares using dependent-variable standard uncertainties.

EFFECTIVE_VARIANCE

Iteratively reweighted least squares including projected uncertainty from the independent variable.

ODR

Orthogonal distance regression or errors-in-variables fitting.

quantas.api.thermoelasticity.AdiabaticMode

alias of Literal[‘auto’, ‘off’, ‘require’]

quantas.api.thermoelasticity.ExtrapolationPolicy

alias of Literal[‘fail’, ‘warn’, ‘allow’]

quantas.api.thermoelasticity.FitFailurePolicy

alias of Literal[‘stop’, ‘continue’, ‘raise’]

quantas.api.thermoelasticity.QualityPolicy

alias of Literal[‘fail’, ‘warn’, ‘allow’]

quantas.api.thermoelasticity.StabilityPolicy

alias of Literal[‘fail’, ‘warn’, ‘allow’]

quantas.api.thermoelasticity.TensorCondition

alias of Literal[‘isothermal’, ‘adiabatic’]

quantas.api.thermoelasticity.ReportLevel

alias of Literal[‘standard’, ‘extended’, ‘debug’]

Reusable input structures

These aliases close the public annotations of Input and Context. They are passive scientific contracts, not calculator or parser implementations.

class quantas.api.thermoelasticity.CrystalStructure(lattice, fractional_positions, atomic_numbers, label='', metadata=<factory>)

Bases: object

Compact periodic crystal structure.

Parameters:
latticearray_like

Direct lattice vectors in Cartesian coordinates, stored by rows with shape (3, 3) and expressed in angstrom.

fractional_positionsarray_like

Fractional atomic coordinates with shape (natoms, 3).

atomic_numbersarray_like

Atomic numbers with shape (natoms,).

labelstr, optional

Human-readable description of the structure.

metadatadict, optional

Additional parser or provenance metadata.

Raises:
ValueError

If array shapes are inconsistent or the lattice volume is zero.

Parameters:

  • lattice (NDArray[float64])

  • fractional_positions (NDArray[float64])

  • atomic_numbers (NDArray[int64])

  • label (str)

  • metadata (dict[str, Any])

property natoms: int

Return the number of atoms in the structure.

Returns:
int

Number of stored atoms.

property volume: float

Return the positive cell volume in cubic angstrom.

Returns:
float

Absolute determinant of the direct lattice matrix.

spglib_cell()

Return the tuple representation consumed by spglib.

Returns:
tuple

(lattice, fractional_positions, atomic_numbers) with lattice vectors stored by rows.

Return type:

tuple[list[list[float]], list[list[float]], list[int]]

as_dict()

Return a recursively serializable mapping.

Returns:
dict

Structural arrays and metadata suitable for YAML or HDF5 output.

Return type:

dict[str, Any]

class quantas.api.thermoelasticity.SymmetryMetadata(space_group_number=0, international_symbol='', hall_number=0, hall_symbol='', choice='', point_group='', symprec=1e-05, angle_tolerance=-1.0, equivalent_atoms=None, transformation_matrix=None, origin_shift=None)

Bases: object

Symmetry information determined for a reference crystal structure.

Parameters:
space_group_numberint

International space-group number.

international_symbolstr

International short Hermann–Mauguin symbol.

hall_numberint

spglib Hall-number identifier.

hall_symbolstr

Hall symbol.

choicestr

Setting or origin choice reported by spglib.

point_groupstr

Crystallographic point-group symbol.

symprecfloat

Cartesian tolerance in angstrom used for symmetry detection.

angle_tolerancefloat

Angular tolerance in degrees used for symmetry detection. A negative value denotes spglib’s internal default.

equivalent_atomsarray_like or None, optional

Mapping from each atom to its crystallographic equivalence class.

transformation_matrixarray_like or None, optional

Transformation matrix reported by spglib for its standard setting.

origin_shiftarray_like or None, optional

Origin shift reported by spglib.

Parameters:

  • space_group_number (int)

  • international_symbol (str)

  • hall_number (int)

  • hall_symbol (str)

  • choice (str)

  • point_group (str)

  • symprec (float)

  • angle_tolerance (float)

  • equivalent_atoms (NDArray[int64] | None)

  • transformation_matrix (NDArray[float64] | None)

  • origin_shift (NDArray[float64] | None)

as_dict()

Return a recursively serializable symmetry mapping.

Returns:
dict

Symmetry identifiers, tolerances, and transformations.

Return type:

dict[str, Any]

class quantas.api.thermoelasticity.ElasticVolumePoint(source, pressure, stress_pressure, volume, density, energy, stiffness, lattice, prestress_applied=True, metadata=<factory>)

Bases: object

One hydrostatically pre-stressed elastic tensor at a sampled volume.

Parameters:
sourcestr or Path

Source CRYSTAL output file.

pressurefloat

Pressure used by CRYSTAL for the hydrostatic pre-stress correction, in GPa.

stress_pressurefloat

Pressure calculated from the final unstrained stress tensor, in GPa. NaN records that the backend did not provide this diagnostic.

volumefloat

Primitive-cell volume in angstrom cubed.

densityfloat

Crystal density in kg m^-3.

energyfloat

Static DFT energy in hartree.

stiffnessarray_like

Symmetric (6, 6) Wallace stiffness matrix in GPa.

latticearray_like

Final primitive direct-lattice vectors, stored by rows in angstrom.

prestress_appliedbool, optional

Whether the stored stiffness includes the hydrostatic pre-stress terms required by QSA. The correction may have been applied by CRYSTAL or by Quantas during input generation.

metadatadict, optional

Frame-normalization diagnostics and source provenance.

Raises:
ValueError

If scalar values or arrays are invalid.

Parameters:

  • source (str | Path)

  • pressure (float)

  • stress_pressure (float)

  • volume (float)

  • density (float)

  • energy (float)

  • stiffness (NDArray[float64])

  • lattice (NDArray[float64])

  • prestress_applied (bool)

  • metadata (dict[str, Any])

as_dict()

Return a recursively serializable point mapping.

Return type:

dict[str, Any]

class quantas.api.thermoelasticity.ElasticVolumeSeries(points, reference_structure, symmetry, elastic_symmetry, reference_index, orientation='crystal', metadata=<factory>)

Bases: object

Volume-dependent second-order elastic data in a common CRYSTAL frame.

Parameters:
pointstuple of ElasticVolumePoint

Elastic data sorted by increasing primitive-cell volume.

reference_structureCrystalStructure

Compact primitive structure used to define species, atom ordering, and the common CRYSTAL Cartesian frame.

symmetrySymmetryMetadata

Crystallographic symmetry of the reference structure.

elastic_symmetrystr

Elastic crystal-system pattern detected from the stiffness matrices.

reference_indexint

Index of the reference point in the sorted series.

orientationstr, optional

Description of the tensor and lattice frame.

metadatadict, optional

Additional provenance and validation metadata.

Raises:
ValueError

If the series is empty, unsorted, duplicated, or inconsistent.

Parameters:
property npoints: int

Return the number of sampled elastic volumes.

property volumes: NDArray[float64]

Return sampled primitive-cell volumes in angstrom cubed.

property pressures: NDArray[float64]

Return CRYSTAL elastic pre-stress pressures in GPa.

property stress_pressures: NDArray[float64]

Return final stress-tensor pressures in GPa, with NaN if unavailable.

property densities: NDArray[float64]

Return sampled densities in kg m^-3.

property energies: NDArray[float64]

Return sampled static DFT energies in hartree.

property stiffness: NDArray[float64]

Return sampled stiffness matrices with shape (npoints, 6, 6).

property lattices: NDArray[float64]

Return sampled primitive lattice matrices.

property volume_bounds: tuple[float, float]

Return minimum and maximum sampled elastic volumes.

class quantas.api.thermoelasticity.QHAInput(jobname='Unknown', natoms=0, formula_units=1, supercell=None, qpoints=0, volume=None, energy=None, frequencies=None, weights=None, qcoords=None, structure=None, units=<factory>, source=None, metadata=<factory>, mode_continuity='assumed')

Bases: PhononInputData

Input data for a quasi-harmonic approximation calculation.

Parameters:
mode_continuity{“verified”, “assumed”, “unknown”, “unreliable”}, optional

Status describing whether phonon-mode ordering is continuous across the sampled volume sequence.

Parameters:

  • jobname (str)

  • natoms (int)

  • formula_units (int)

  • supercell (ndarray | None)

  • qpoints (int)

  • volume (ndarray | None)

  • energy (ndarray | None)

  • frequencies (ndarray | None)

  • weights (ndarray | None)

  • qcoords (ndarray | None)

  • structure (StructureVolumeSeries | None)

  • units (dict[str, str])

  • source (str | Path | None)

  • metadata (dict[str, Any])

  • mode_continuity (Literal['verified', 'assumed', 'unknown', 'unreliable'])

has_mode_continuity_data()

Return whether the array layout can represent continuous modes.

Returns:
bool

True when frequencies have shape (qpoints, modes, volumes) and the volume axis matches the sampled-volume array.

Return type:

bool

mode_continuity_status()

Return the normalized phonon-mode continuity status.

Returns:
str

One of verified, assumed, unknown, or unreliable.

Return type:

str

has_mode_continuity()

Return whether mode-continuous analysis is permitted.

Returns:
bool

True when the data layout is suitable and continuity is marked either verified or assumed.

Return type:

bool

has_verified_mode_continuity()

Return whether mode continuity was explicitly verified.

Returns:
bool

True only for structurally valid data marked verified.

Return type:

bool

validate_shapes()

Validate array dimensions required by QHA calculations.

Raises:
ValueError

If structural, energetic, q-point, or phonon arrays are inconsistent.

Return type:

None

class quantas.api.thermoelasticity.QHAOptions(temperature_min=298.15, temperature_max=298.15, temperature_step=1.0, pressure_min=0.0, pressure_max=0.0, pressure_step=1.0, scheme='freq', minimization='poly', eos='BM3', energy_degree=3, free_energy_degree=3, frequency_degree=3, structural_degree=3, polynomial_derivative_method='local_grid', polynomial_grid_points=5, polynomial_grid_separation=0.05, energy_unit='Ha', volume_unit='A', frequency_unit='cm^-1', temperature_unit='K', pressure_unit='GPa', debug=False, store_fit_diagnostics=True, estimate_uncertainties=True, uncertainty_method='covariance', uncertainty_relative_step=1e-05, uncertainty_confidence_level=0.95, uncertainty_samples=10000, uncertainty_seed=None, uncertainty_minimum_success_fraction=0.8, extrapolation_policy='warn', fit_failure_policy='stop', fit_quality_policy='warn', max_consecutive_failures=5, calculate_gruneisen=True, calculate_mode_gruneisen=True, thermal_expansion_method='mixed_derivative', gruneisen_allow_nonpositive=True, gruneisen_min_cv_fraction=0.01, metadata=<factory>)

Bases: object

Options controlling a quasi-harmonic approximation calculation.

Parameters:
temperature_minfloat, optional

Minimum temperature of the calculation range.

temperature_maxfloat, optional

Maximum temperature of the calculation range.

temperature_stepfloat, optional

Temperature increment.

pressure_minfloat, optional

Minimum pressure of the calculation range.

pressure_maxfloat, optional

Maximum pressure of the calculation range.

pressure_stepfloat, optional

Pressure increment.

scheme{“freq”, “td”}, optional

QHA scheme used for volume-dependent thermodynamics.

minimization{“poly”, “eos”}, optional

Method used to determine equilibrium volumes at each P, T point.

eosstr, optional

Equation of state used when minimization is "eos".

energy_degreeint, optional

Polynomial degree used for static energy fits.

free_energy_degreeint, optional

Polynomial degree used for Helmholtz free-energy fits.

frequency_degreeint, optional

Polynomial degree used for mode-resolved frequency fits.

structural_degreeint, optional

Polynomial degree used for the deviatoric logarithmic-strain path when structural cells are available. Axial and tensorial thermal expansion are calculated automatically from this path.

polynomial_derivative_method{“local_grid”, “analytic”}, optional

Method used to calculate polynomial K_T and K'_T values.

polynomial_grid_pointsint, optional

Number of volumes in the local derivative grid.

polynomial_grid_separationfloat, optional

Adjacent local-grid spacing as a percentage of the equilibrium volume.

energy_unitstr, optional

Energy unit used for input static energies and final energy-like results.

volume_unitstr, optional

Length unit used to express unit-cell volumes.

frequency_unitstr, optional

Frequency unit used by the input phonon data.

temperature_unitstr, optional

Temperature unit used by the input temperature range.

pressure_unitstr, optional

Pressure unit used by the input pressure range.

debugbool, optional

If True, store and expose detailed fit diagnostics.

store_fit_diagnosticsbool, optional

If True, retain structured diagnostics from local fits.

estimate_uncertaintiesbool, optional

If True, request uncertainty estimates where supported.

uncertainty_methodstr, optional

Method requested for uncertainty estimates.

uncertainty_relative_stepfloat, optional

Relative EOS-parameter step used by linear covariance propagation.

uncertainty_confidence_levelfloat, optional

Confidence probability used for propagated EOS intervals.

uncertainty_samplesint, optional

Number of correlated EOS parameter samples used by Monte Carlo propagation.

uncertainty_seedint or None, optional

Random seed used by Monte Carlo propagation.

uncertainty_minimum_success_fractionfloat, optional

Minimum accepted fraction of physical Monte Carlo EOS states.

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

Policy applied when an equilibrium volume is outside the sampled volume interval.

fit_failure_policy{“continue”, “stop”, “raise”}, optional

Policy applied when a local fit fails.

fit_quality_policy{“warn”, “stop”}, optional

Policy applied when a local fit is successful but poor.

max_consecutive_failuresint, optional

Maximum number of consecutive local fit failures before a workflow stops when the failure policy is "stop".

calculate_gruneisenbool, optional

If True, calculate the thermodynamic Grüneisen parameter from alpha_V K_T V / C_V.

calculate_mode_gruneisenbool, optional

If True and the frequency scheme is selected, calculate mode-resolved and heat-capacity-weighted Grüneisen parameters.

thermal_expansion_method{“mixed_derivative”, “mode_gruneisen”, “numerical”}, optional

Method used to calculate the volumetric thermal-expansion coefficient. The mixed derivative of the fitted free-energy surface is the default. The mode-Grüneisen method is available only for the frequency scheme, while the numerical volume derivative is retained as a fallback.

gruneisen_allow_nonpositivebool, optional

If True, non-positive modes are excluded from mode averages rather than invalidating the full calculation.

gruneisen_min_cv_fractionfloat, optional

Minimum fraction of the Dulong-Petit heat capacity required before the macroscopic alpha_V K_T V / C_V ratio is considered resolved.

metadatadict, optional

Additional caller-defined options.

Parameters:

  • temperature_min (float)

  • temperature_max (float)

  • temperature_step (float)

  • pressure_min (float)

  • pressure_max (float)

  • pressure_step (float)

  • scheme (Literal['freq', 'td'])

  • minimization (Literal['poly', 'eos'])

  • eos (str)

  • energy_degree (int)

  • free_energy_degree (int)

  • frequency_degree (int)

  • structural_degree (int)

  • polynomial_derivative_method (Literal['local_grid', 'analytic'])

  • polynomial_grid_points (int)

  • polynomial_grid_separation (float)

  • energy_unit (str)

  • volume_unit (str)

  • frequency_unit (str)

  • temperature_unit (str)

  • pressure_unit (str)

  • debug (bool)

  • store_fit_diagnostics (bool)

  • estimate_uncertainties (bool)

  • uncertainty_method (Literal['none', 'covariance', 'bootstrap', 'montecarlo'])

  • uncertainty_relative_step (float)

  • uncertainty_confidence_level (float)

  • uncertainty_samples (int)

  • uncertainty_seed (int | None)

  • uncertainty_minimum_success_fraction (float)

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

  • fit_failure_policy (Literal['continue', 'stop', 'raise'])

  • fit_quality_policy (Literal['warn', 'stop'])

  • max_consecutive_failures (int)

  • calculate_gruneisen (bool)

  • calculate_mode_gruneisen (bool)

  • thermal_expansion_method (Literal['mixed_derivative', 'mode_gruneisen', 'numerical'])

  • gruneisen_allow_nonpositive (bool)

  • gruneisen_min_cv_fraction (float)

  • metadata (dict[str, Any])

temperature_grid()

Return the temperature grid used by the QHA workflow.

Returns:
ndarray

One-dimensional temperature array generated with the Quantas grid convention np.arange(min, max + step, step).

Raises:
ValueError

If the temperature step is not positive or the maximum temperature is smaller than the minimum temperature.

Return type:

ndarray

pressure_grid()

Return the pressure grid used by the QHA workflow.

Returns:
ndarray

One-dimensional pressure array generated with the Quantas grid convention np.arange(min, max + step, step).

Raises:
ValueError

If the pressure step is not positive or the maximum pressure is smaller than the minimum pressure.

Return type:

ndarray

requires_mode_continuity()

Return whether the selected options require mode continuity.

Returns:
bool

True for methods that operate directly on mode-resolved frequency changes over volume.

Return type:

bool

validate()

Validate option values before running a QHA workflow.

Raises:
ValueError

If an option has an unsupported value or an invalid numerical setting.

Return type:

None

class quantas.api.thermoelasticity.QHAThermoelasticPayload(*args, **kwargs)

Bases: Protocol

Structural protocol for QHA fields consumed by thermoelasticity.

Calibration and result contracts

quantas.api.thermoelasticity.Input

alias of ThermoelasticInput

quantas.api.thermoelasticity.Context

alias of ThermoelasticContext

quantas.api.thermoelasticity.Options

alias of ThermoelasticOptions

quantas.api.thermoelasticity.Result

alias of ThermoelasticResult

Profile contracts

quantas.api.thermoelasticity.ProfilePreset

alias of ThermoelasticProfilePreset

quantas.api.thermoelasticity.DepthProfile

alias of ThermoelasticDepthProfile

quantas.api.thermoelasticity.ProfileResult

alias of ThermoelasticProfileResult

Plot selectors

quantas.api.thermoelasticity.ComponentGroup

alias of Literal[‘independent’, ‘normal’, ‘shear’, ‘coupling’, ‘offdiagonal’, ‘all’]

quantas.api.thermoelasticity.PTQuantity

alias of Literal[‘value’, ‘uncertainty’, ‘relative-uncertainty’]

quantas.api.thermoelasticity.PlotLayout

alias of Literal[‘auto’, ‘overlay’, ‘facets’, ‘separate’]

quantas.api.thermoelasticity.PlotPreset

alias of Literal[‘analysis’, ‘publication’, ‘monochrome’]

quantas.api.thermoelasticity.ProfileBackground

alias of Literal[‘none’, ‘temperature’]

quantas.api.thermoelasticity.ProfileColor

alias of Literal[‘component’, ‘temperature’, ‘none’]

quantas.api.thermoelasticity.ProfileMode

alias of Literal[‘absolute’, ‘relative’]

quantas.api.thermoelasticity.UncertaintyMode

alias of Literal[‘auto’, ‘none’, ‘band’, ‘bars’]

Plot option contracts

quantas.api.thermoelasticity.PlotStyleOptions

alias of ThermoelasticPlotStyleOptions

quantas.api.thermoelasticity.FitPlotOptions

alias of ThermoelasticFitPlotOptions

quantas.api.thermoelasticity.PTPlotOptions

alias of ThermoelasticPTPlotOptions

quantas.api.thermoelasticity.ProfilePlotOptions

alias of ThermoelasticProfilePlotOptions

quantas.api.thermoelasticity.ComparePlotOptions

alias of ThermoelasticComparePlotOptions

quantas.api.thermoelasticity.DomainPlotOptions

alias of ThermoelasticDomainPlotOptions