Thermo API¶

Thermodynamic property models and data access.

ThermoProperty¶

ThermoProperty `dataclass` ¶

Enhanced thermodynamic property with CHETAH-style breakdown support.

Provides: - Value with uncertainty - Group contribution breakdown (when available) - Literature references - Comparison with database reference values

Backward compatible: all enhanced fields are optional.

deviation `property` ¶

deviation: float | None

Deviation from reference value (estimate - reference).

deviation_percent `property` ¶

deviation_percent: float | None

Percent deviation from reference value.

has_breakdown ¶

has_breakdown() -> bool

Check if detailed breakdown is available.

has_reference ¶

has_reference() -> bool

Check if reference value is available for comparison.

format_breakdown ¶

format_breakdown(property_name: str = 'ENTHALPY OF FORMATION') -> str

Return CHETAH-style breakdown table.

Parameters¶

property_name : str Name to show in header

Returns¶

str Formatted breakdown table

Example Output¶

ENTHALPY OF FORMATION (GAS) CALCULATION¶

Group Count Contribution Total¶

C-(H)3(C) 2 -10.00 -20.00 C-(H)2(C)2 1 -5.00 -5.00

ESTIMATED VALUE (Benson GA): -25.00 kJ/mol

REFERENCE VALUE (NIST WebBook): -26.50 kJ/mol DEVIATION: +1.50 kJ/mol

References: - Benson, S.W. (1976) - NIST Chemistry WebBook, SRD 69

Attributes¶

Attribute	Type	Description
`value`	float	Property value
`unit`	str	Unit of measurement
`uncertainty`	float	None
`source`	str	None
`phase`	str	Phase ('g', 'l', 's')
`breakdown`	tuple[GroupContribution, ...]	Group contributions
`references`	tuple[Reference, ...]	Literature references
`reference_value`	ThermoValue	None
`estimation_method`	str	Estimation method used
`temperature_K`	float	Temperature in Kelvin

Properties¶

Property	Type	Description
`deviation`	float	None
`deviation_percent`	float	None

Methods¶

def has_breakdown(self) -> bool

Check if group contribution breakdown is available.

def has_reference(self) -> bool

Check if reference value is available.

def format_breakdown(self, property_name: str = "ENTHALPY OF FORMATION") -> str

Format CHETAH-style breakdown table.

Float Conversion¶

hf = compound.enthalpy_of_formation
value = float(hf)  # Get raw float

ThermoState¶

ThermoState `dataclass` ¶

Immutable thermodynamic state at a specific temperature.

Provides grouped access to all temperature-dependent properties at a single temperature. Use Compound.thermo_at(T=...) to create.

Attributes¶

temperature : float Temperature in Kelvin

Properties¶

H : ThermoProperty Enthalpy of formation [kJ/mol] S : ThermoProperty Standard entropy [J/(mol·K)] Cp : ThermoProperty Heat capacity at constant pressure [J/(mol·K)] G : ThermoProperty Gibbs free energy of formation [kJ/mol]

Examples¶

from phoenix import Compound ethanol = Compound.from_smiles('CCO') state = ethanol.thermo_at(T=500) print(f"H = {state.H.value:.2f} kJ/mol") print(f"S = {state.S.value:.2f} J/(mol·K)") print(f"G = {state.G.value:.2f} kJ/mol")

H `cached` `property` ¶

H: ThermoProperty

Enthalpy of formation at this temperature [kJ/mol].

S `cached` `property` ¶

S: ThermoProperty

Standard entropy at this temperature [J/(mol·K)].

Cp `cached` `property` ¶

Cp: ThermoProperty

Heat capacity at this temperature [J/(mol·K)].

G `cached` `property` ¶

G: ThermoProperty

Gibbs free energy of formation at this temperature [kJ/mol].

Calculated as G = H - T*S, with appropriate unit conversion.

enthalpy `property` ¶

enthalpy: ThermoProperty

Alias for H (enthalpy of formation).

entropy `property` ¶

entropy: ThermoProperty

Alias for S (standard entropy).

heat_capacity `property` ¶

heat_capacity: ThermoProperty

Alias for Cp (heat capacity).

gibbs_energy `property` ¶

gibbs_energy: ThermoProperty

Alias for G (Gibbs free energy).

__post_init__ ¶

__post_init__() -> None

Validate temperature on creation.

Attributes¶

Attribute	Type	Description
`temperature`	float	Temperature in Kelvin

Properties¶

Property	Alias	Type	Unit	Description
`H`	`enthalpy`	ThermoProperty	kJ/mol	Enthalpy of formation
`S`	`entropy`	ThermoProperty	J/(mol·K)	Standard entropy
`Cp`	`heat_capacity`	ThermoProperty	J/(mol·K)	Heat capacity
`G`	`gibbs_energy`	ThermoProperty	kJ/mol	Gibbs free energy

Example¶

from phoenix import Compound

compound = Compound.from_smiles("CCO")
state = compound.thermo_at(T=500)

print(f"T = {state.temperature} K")
print(f"H = {state.H.value:.2f} kJ/mol")
print(f"S = {state.S.value:.2f} J/(mol·K)")
print(f"Cp = {state.Cp.value:.2f} J/(mol·K)")
print(f"G = {state.G.value:.2f} kJ/mol")

ThermoPropertyAccessor¶

ThermoPropertyAccessor ¶

Enables dual property/method access for temperature-dependent properties.

When accessed as attribute: returns value at 298.15 K (backward compatible) When called as method: returns value at specified temperature

Examples¶

compound = Compound.from_smiles('CCO')

As property (298.15 K)¶

hf = compound.enthalpy_of_formation print(hf) # Shows value at 298.15 K

As method with temperature¶

hf_500 = compound.enthalpy_of_formation(T=500) print(hf_500) # Shows value at 500 K

Vectorized with NumPy¶

import numpy as np temps = np.linspace(300, 1000, 100) values = compound.enthalpy_of_formation(T=temps) # Returns ndarray

value `property` ¶

value: float

Property value at default temperature.

unit `property` ¶

unit: str

Property unit.

uncertainty `property` ¶

uncertainty: float | None

Property uncertainty at default temperature.

source `property` ¶

source: str | None

Property source.

temperature_K `property` ¶

temperature_K: float

Temperature at which default value is calculated.

init ¶

__init__(compound: Compound, calc_func: Callable[[Compound, float], ThermoProperty], name: str)

Initialize accessor.

Parameters¶

compound : Compound The compound to calculate properties for calc_func : callable Function (compound, T) -> ThermoProperty name : str Property name for display

repr ¶

__repr__() -> str

Return string representation at default temperature.

str ¶

__str__() -> str

Return string at default temperature.

float ¶

__float__() -> float

Return float value at default temperature.

call ¶

__call__(*, T: float | ndarray = TEMP_DEFAULT) -> ThermoProperty | np.ndarray

Calculate property at specified temperature(s).

Parameters¶

T : float or numpy.ndarray Temperature in Kelvin (keyword-only)

Returns¶

ThermoProperty or numpy.ndarray Single ThermoProperty for scalar T, array of values for array T

Enables dual property/method access for temperature-dependent properties.

Usage¶

# As property (298.15 K)
hf = compound.enthalpy_of_formation
print(hf.value)  # Value at 298.15 K

# As method with temperature
hf_500 = compound.enthalpy_of_formation(T=500)
print(hf_500.value)  # Value at 500 K

# Vectorized with NumPy
import numpy as np
temps = np.linspace(300, 1000, 100)
values = compound.enthalpy_of_formation(T=temps)  # Returns ndarray

Properties¶

Property	Type	Description
`value`	float	Value at default temperature
`unit`	str	Unit of measurement
`uncertainty`	float	None
`source`	str	None
`temperature_K`	float	Default temperature (298.15)

GroupContribution¶

GroupContribution `dataclass` ¶

Single Benson group contribution to a thermodynamic property.

Attributes¶

group_name : str Group notation (e.g., "C-(H)3(C)", "Cb-H") count : int Number of occurrences in molecule contribution : float Contribution per group (in property units) property_type : str Property type: "Hf", "S", "Cp" source : str Data source (e.g., "Benson 1976", "pgradd")

total `property` ¶

total: float

Total contribution (count * contribution).

Attributes¶

Attribute	Type	Description
`group_name`	str	Group notation
`count`	int	Number of occurrences
`contribution`	float	Contribution per group
`property_type`	str	"Hf", "S", or "Cp"
`source`	str	Data source

Properties¶

Property	Type	Description
`total`	float	count × contribution

ThermoValue¶

ThermoValue `dataclass` ¶

A thermodynamic value with full provenance.

Used for reference values from databases.

Attributes¶

Attribute	Type	Description
`value`	float	Property value
`unit`	str	Unit
`uncertainty`	float	None
`method`	str	Determination method
`references`	tuple[Reference, ...]	Literature references

Estimation Functions¶

estimate_delta_hf¶

from phoenix.thermo.benson import estimate_delta_hf

def estimate_delta_hf(compound: Compound, T: float = 298.15) -> ThermoProperty

Estimate enthalpy of formation using Benson GA.

estimate_entropy¶

from phoenix.thermo.benson import estimate_entropy

def estimate_entropy(compound: Compound, T: float = 298.15) -> ThermoProperty

Estimate standard entropy using Benson GA.

estimate_heat_capacity¶

from phoenix.thermo.benson import estimate_heat_capacity

def estimate_heat_capacity(compound: Compound, temperature_K: float = 298.15) -> ThermoProperty

Estimate heat capacity using Benson GA.

Data Access¶

get_formation_enthalpy¶

from phoenix.thermo.data import get_formation_enthalpy

def get_formation_enthalpy(formula: str) -> FormationEnthalpyData

Get reference formation enthalpy data.

Temperature Constants¶

from phoenix.thermo.models import (
    TEMP_MIN_WARN,   # 200.0 K - warn below
    TEMP_MAX_WARN,   # 6000.0 K - warn above
    TEMP_DEFAULT,    # 298.15 K - standard state
)

Example: Full Breakdown¶

from phoenix import Compound

compound = Compound.from_smiles("CCC")  # Propane
hf = compound.enthalpy_of_formation

# Print CHETAH-style breakdown
if hf.has_breakdown():
    print(hf.format_breakdown())

# Access individual contributions
for group in hf.breakdown:
    print(f"{group.group_name}: {group.count} × {group.contribution:.2f} = {group.total:.2f}")

Thermo API¶

ThermoProperty¶

ThermoProperty dataclass ¶

deviation property ¶

deviation_percent property ¶

has_breakdown ¶

has_reference ¶

format_breakdown ¶

Parameters¶

Returns¶

Example Output¶

ENTHALPY OF FORMATION (GAS) CALCULATION¶

Group Count Contribution Total¶

Attributes¶

Properties¶

Methods¶

Float Conversion¶

ThermoState¶

ThermoState dataclass ¶

Attributes¶

Properties¶

Examples¶

H cached property ¶

S cached property ¶

Cp cached property ¶

G cached property ¶

enthalpy property ¶

entropy property ¶

heat_capacity property ¶

gibbs_energy property ¶

__post_init__ ¶

Attributes¶

Properties¶

Example¶

ThermoPropertyAccessor¶

ThermoPropertyAccessor ¶

Examples¶

As property (298.15 K)¶

As method with temperature¶

Vectorized with NumPy¶

value property ¶

unit property ¶

uncertainty property ¶

source property ¶

temperature_K property ¶

__init__ ¶

Parameters¶

__repr__ ¶

__str__ ¶

__float__ ¶

__call__ ¶

Parameters¶

Returns¶

Usage¶

Properties¶

GroupContribution¶

GroupContribution dataclass ¶

Attributes¶

total property ¶

Attributes¶

Properties¶

ThermoValue¶

ThermoValue dataclass ¶

Attributes¶

Estimation Functions¶

estimate_delta_hf¶

estimate_entropy¶

estimate_heat_capacity¶

Data Access¶

get_formation_enthalpy¶

Temperature Constants¶

Example: Full Breakdown¶

ThermoProperty `dataclass` ¶

deviation `property` ¶

deviation_percent `property` ¶

ThermoState `dataclass` ¶

H `cached` `property` ¶

S `cached` `property` ¶

Cp `cached` `property` ¶

G `cached` `property` ¶

enthalpy `property` ¶

entropy `property` ¶

heat_capacity `property` ¶

gibbs_energy `property` ¶

value `property` ¶

unit `property` ¶

uncertainty `property` ¶

source `property` ¶

temperature_K `property` ¶

init ¶

repr ¶

str ¶

float ¶

call ¶

GroupContribution `dataclass` ¶

total `property` ¶

ThermoValue `dataclass` ¶