EOS contracts and model specifications

This page documents the passive data, model, parameter, solver, report, and plot contracts used by the EOS operations. Construct these objects through quantas.api.eos; numerical evaluators and solver implementations remain internal.

Dataset and domain capabilities

quantas.api.eos.Dataset

alias of EOSDataset

quantas.api.eos.FitDomain

alias of EOSFitDomain

quantas.api.eos.CapabilityStatus

alias of EOSCapabilityStatus

quantas.api.eos.DomainCapability

alias of EOSDomainCapability

quantas.api.eos.DOMAIN_CAPABILITIES = (EOSDomainCapability(domain=<EOSFitDomain.PRESSURE_VOLUME: 'pv'>, status=<EOSCapabilityStatus.PUBLIC: 'public'>, fitting=True, calculator=True, diagnostics=True, plotting=True, note='Isothermal volumetric and axial pressure EOS fitting.'), EOSDomainCapability(domain=<EOSFitDomain.VOLUME_TEMPERATURE: 'vt'>, status=<EOSCapabilityStatus.PUBLIC: 'public'>, fitting=True, calculator=True, diagnostics=True, plotting=True, note='Volumetric and axial thermal-expansion fitting.'), EOSDomainCapability(domain=<EOSFitDomain.PRESSURE_VOLUME_TEMPERATURE: 'pvt'>, status=<EOSCapabilityStatus.PUBLIC: 'public'>, fitting=True, calculator=True, diagnostics=True, plotting=True, note='Coupled P-V-T fitting, including thermal-pressure models.'), EOSDomainCapability(domain=<EOSFitDomain.ENERGY_VOLUME: 'ev'>, status=<EOSCapabilityStatus.CORE_ONLY: 'core_only'>, fitting=False, calculator=False, diagnostics=False, plotting=False, note='Integrated energy EOS remain stable numerical core functionality used by QHA; no public EOS E-V fitting workflow is currently provided.'))

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

Model and parameter contracts

class quantas.api.eos.PVTModel(pressure_model, coupling, temperature_model=None, thermal_pressure_model=None, mgd_normalization=None)

Bases: object

Describe one compositional pressure-volume-temperature model.

Parameters:
pressure_modelEOSModel or str

Reference isothermal pressure-volume EOS.

couplingPVTCouplingFamily or str

Temperature-coupling prescription.

temperature_modelTemperatureEOSModel, str, or None, optional

V–T model used to calculate V0(T) for the linear-bulk-modulus and Anderson–Gruneisen prescriptions. It must be omitted for the thermal-pressure prescription.

thermal_pressure_modelThermalPressureModel, str, or None, optional

Oscillator model used by the thermal-pressure prescription. Omission preserves the historical Holland–Powell Einstein default.

mgd_normalizationMGDNormalization or None, optional

Cell or molar atom-count normalization. It is required only for MGD.

Raises:
ValueError

If the temperature-model requirement is inconsistent with the coupling family.

Parameters:

  • pressure_model (EOSModel | str)

  • coupling (PVTCouplingFamily | str)

  • temperature_model (TemperatureEOSModel | str | None)

  • thermal_pressure_model (ThermalPressureModel | str | None)

  • mgd_normalization (MGDNormalization | None)

property pressure_spec: EOSModel

Return the canonical reference isothermal EOS specification.

property coupling_family: PVTCouplingFamily

Return the canonical temperature-coupling family.

property thermal_spec: TemperatureEOSModel | None

Return the canonical V–T model, when the coupling uses one.

property thermal_pressure_spec: ThermalPressureModel | None

Return the selected thermal-pressure oscillator model.

property mgd_normalization_spec: MGDNormalization | None

Return the MGD normalization, when applicable.

property tag: str

Return a stable composite model tag.

as_dict()

Return a serialization-ready model description.

Return type:

dict[str, object]

class quantas.api.eos.MGDNormalization(volume_basis, atoms_per_unit, formula=None, formula_units_per_cell=None)

Bases: object

Describe the atom-count normalization of MGD thermal pressure.

Parameters:
volume_basisMGDVolumeBasis or str

"cell" means that volumes are crystallographic cell volumes in Angstrom cubed. "molar-formula-unit" means molar volumes in cubic centimetres per mole of formula units.

atoms_per_unitfloat

Number of atoms in the volume unit. This is atoms per cell for cell volumes and atoms per formula unit for molar formula-unit volumes.

formulastr or None, optional

Optional chemical formula retained for provenance.

formula_units_per_cellfloat or None, optional

Number of formula units in the cell. It is meaningful only for the cell basis and is retained for validation and provenance.

Raises:
ValueError

If counts are non-positive, inconsistent with the formula, or invalid for the selected volume basis.

Parameters:

  • volume_basis (MGDVolumeBasis | str)

  • atoms_per_unit (float)

  • formula (str | None)

  • formula_units_per_cell (float | None)

classmethod cell(*, atoms_per_cell=None, formula=None, formula_units_per_cell=None)

Build cell-volume normalization from atoms or formula + Z.

Parameters:
atoms_per_cellfloat or None, optional

Explicit number of atoms in the crystallographic cell.

formulastr or None, optional

Formula of one formula unit.

formula_units_per_cellfloat or None, optional

Number Z of formula units in the cell.

Returns:
MGDNormalization

Validated cell-volume normalization.

Raises:
ValueError

If neither an explicit atom count nor a complete formula + Z specification is supplied, or if redundant values disagree.

Parameters:

  • atoms_per_cell (float | None)

  • formula (str | None)

  • formula_units_per_cell (float | None)

Return type:

MGDNormalization

classmethod molar_formula_unit(*, atoms_per_formula_unit=None, formula=None)

Build molar formula-unit normalization.

Parameters:
atoms_per_formula_unitfloat or None, optional

Explicit atom count in one formula unit.

formulastr or None, optional

Formula from which the atom count may be inferred.

Returns:
MGDNormalization

Validated molar formula-unit normalization.

Raises:
ValueError

If neither a formula nor an explicit atom count is supplied, or if redundant values disagree.

Parameters:

  • atoms_per_formula_unit (float | None)

  • formula (str | None)

Return type:

MGDNormalization

property basis: MGDVolumeBasis

Return the canonical volume basis.

property canonical_volume_unit: str

Return the canonical volume unit required by this basis.

property atoms_per_cell: float | None

Return atoms per cell when using cell-volume normalization.

property atoms_per_formula_unit: float | None

Return atoms per formula unit for molar normalization.

as_dict()

Return a serialization-ready normalization description.

Return type:

dict[str, str | float | None]

class quantas.api.eos.ParameterConstraint(name, state=ParameterState.FREE, initial_value=None, value=None, lower_bound=-inf, upper_bound=inf, unit=None, description='', metadata=<factory>)

Bases: ParameterDefinition

EOS-facing parameter constraint using the general fitting contract.

Parameters:

  • name (str)

  • state (ParameterState)

  • initial_value (float | None)

  • value (float | None)

  • lower_bound (float)

  • upper_bound (float)

  • unit (str | None)

  • description (str)

  • metadata (Mapping[str, Any])

Fit request and result

quantas.api.eos.FitRequest

alias of EOSFitRequest

quantas.api.eos.FitOptions

alias of EOSFitOptions

quantas.api.eos.FitResult

alias of EOSFitResult

Regression selectors and solver options

SolverOptions is the public union of the four supported passive solver option contracts. These objects select and configure a backend; they are not numerical solver instances.

class quantas.api.eos.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.

class quantas.api.eos.CovarianceScaling(*values)

Bases: str, Enum

Policy applied to covariance from weighted regression.

Attributes:
ABSOLUTE

Preserve the absolute scale of supplied standard uncertainties.

REDUCED_CHI_SQUARE

Multiply covariance by the reduced chi-square. Parameter standard errors may therefore increase or decrease.

INFLATE_ONLY

Multiply covariance by max(1, reduced_chi_square). This reproduces the uncertainty-rescaling convention used by EosFit7.

class quantas.api.eos.ODRDifferenceScheme(*values)

Bases: str, Enum

Finite-difference scheme used by an ODR backend.

Attributes:
FORWARD

Forward finite differences. This is the native ODRPACK95 default.

CENTRAL

Central finite differences. Quantas uses this as the scientific default because it is generally more accurate, at the cost of extra model evaluations.

quantas.api.eos.SolverOptions = quantas.core.math.fitting.options.OLSOptions | quantas.core.math.fitting.options.WLSOptions | quantas.core.math.fitting.options.EffectiveVarianceOptions | quantas.core.math.fitting.options.OrthogonalDistanceOptions

Represent a PEP 604 union type

E.g. for int | str

class quantas.api.eos.OLSOptions(method=FitMethod.OLS, covariance_scaling=None, absolute_sigma=None, max_iterations=None, ftol=None, xtol=None, gtol=None, metadata=<factory>)

Bases: LeastSquaresOptions

Configure ordinary nonlinear least squares.

The solver minimizes unweighted vertical residuals. The method is fixed by the class and therefore cannot disagree with the selected option contract.

Parameters:

  • method (FitMethod)

  • covariance_scaling (CovarianceScaling | None)

  • absolute_sigma (bool | None)

  • max_iterations (int | None)

  • ftol (float | None)

  • xtol (float | None)

  • gtol (float | None)

  • metadata (dict[str, Any])

class quantas.api.eos.WLSOptions(method=FitMethod.WLS, covariance_scaling=None, absolute_sigma=None, max_iterations=None, ftol=None, xtol=None, gtol=None, metadata=<factory>)

Bases: LeastSquaresOptions

Configure weighted nonlinear least squares.

The solver minimizes vertical residuals divided by dependent-variable standard uncertainties. The method is fixed by the class.

Parameters:

  • method (FitMethod)

  • covariance_scaling (CovarianceScaling | None)

  • absolute_sigma (bool | None)

  • max_iterations (int | None)

  • ftol (float | None)

  • xtol (float | None)

  • gtol (float | None)

  • metadata (dict[str, Any])

class quantas.api.eos.EffectiveVarianceOptions(method=FitMethod.EFFECTIVE_VARIANCE, covariance_scaling=None, absolute_sigma=None, max_iterations=None, ftol=None, xtol=None, gtol=None, metadata=<factory>, inner_max_iterations=None, parameter_rtol=1e-10, parameter_atol=1e-12, sigma_rtol=1e-10, sigma_atol=1e-12)

Bases: FitOptions

Configure iterative effective-variance regression.

Effective variance projects independent-variable uncertainty into the dependent-variable direction through the local model derivative and updates the effective standard uncertainties after every nonlinear WLS cycle.

Parameters:
inner_max_iterationsint or None, optional

Maximum model-evaluation count for each inner WLS cycle. None leaves the SciPy backend default unchanged.

parameter_rtol, parameter_atolfloat, optional

Relative and absolute convergence tolerances for the free-parameter vector between reweighting cycles.

sigma_rtol, sigma_atolfloat, optional

Relative and absolute convergence tolerances for the effective standard uncertainty vector.

max_iterationsint or None, optional

Maximum number of outer reweighting cycles. None selects 25.

covariance_scaling, absolute_sigma, ftol, xtol, gtol, metadata

Common controls inherited from FitOptions. The tolerances ftol, xtol, and gtol are passed to each inner WLS cycle.

Raises:
ValueError

If convergence tolerances are invalid.

Parameters:

  • method (FitMethod)

  • covariance_scaling (CovarianceScaling | None)

  • absolute_sigma (bool | None)

  • max_iterations (int | None)

  • ftol (float | None)

  • xtol (float | None)

  • gtol (float | None)

  • metadata (dict[str, Any])

  • inner_max_iterations (int | None)

  • parameter_rtol (float)

  • parameter_atol (float)

  • sigma_rtol (float)

  • sigma_atol (float)

quantas.api.eos.ODROptions

alias of OrthogonalDistanceOptions

Archive slot, report, and plot contracts

quantas.api.eos.ResultSlot

alias of EOSResultSlot

quantas.api.eos.ReportDetail

alias of EOSReportDetail

quantas.api.eos.ReportOptions

alias of EOSReportOptions

quantas.api.eos.PlotOptions

alias of EOSPlotOptions