Property accessors

PyThermo provides curated Julia accessor functions for the most common thermodynamic, transport, and identity properties of Species and Mixture. Each accessor wraps the underlying thermo Python attribute, attaches a Unitful unit, and (for constants that may be absent from the database) returns missing rather than nothing.

For properties not covered by a curated accessor, the getproperty fallthrough still works: c.molecular_diameter, c.GWP, c.Hf, etc. See the upstream thermo.Chemical and thermo.Mixture references for the full attribute list.

Two-tier missing-value handling

State-dependent properties (T, P, density, Cp, viscosity, …) are strict: their return type is Quantity, and accessing a property that thermo can not evaluate at the current state throws.

Per-substance constants whose database entry may genuinely be absent (Tc, Pc, omega, Tb, Hvap, Psat) are optional: they return missing when thermo returns None, and otherwise a Quantity. The one dimensionless optional, acentric_factor, follows the same NoUnits convention as the strict dimensionless accessors (prandtl, the curve-based path of compressibility) and so returns Union{Float64, Missing} rather than Union{Quantity, Missing}.

Phase variants

State-dependent properties whose Python attribute has phase-suffixed variants (e.g. rhog, rhol, rhos for gas/liquid/solid density) accept an optional positional Symbol:

density(c)            # current phase, equivalent to c.rho
density(c, :gas)      # c.rhog
density(c, :liquid)   # c.rhol
density(c, :solid)    # c.rhos   (where defined)

Phases that thermo does not expose for a given property throw ArgumentError — for example viscosity(c, :solid) (no mus attribute). The supported phases for each accessor are listed in the cheatsheet below and in the per-accessor docstring.

State

PyThermo.density — Function
density(c::Chemical)
density(c::Chemical, phase::Symbol)

Mass density at the chemical's current state.

Without a phase argument, forwards to rho. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → rhog
  • :liquid → rhol
  • :solid → rhos
source
PyThermo.molar_density — Function
molar_density(c::Chemical)
molar_density(c::Chemical, phase::Symbol)

Molar density at the chemical's current state.

Without a phase argument, forwards to rhom. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → rhogm
  • :liquid → rholm
  • :solid → rhosm
source
PyThermo.molar_volume — Function
molar_volume(c::Chemical)
molar_volume(c::Chemical, phase::Symbol)

Molar volume at the chemical's current state.

Without a phase argument, forwards to Vm. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → Vmg
  • :liquid → Vml
  • :solid → Vms
source
PyThermo.compressibility — Function
compressibility(c::Chemical) -> Float64
compressibility(c::Chemical, phase::Symbol) -> Float64

Compressibility factor Z = PV/(nRT) at the chemical's current state. Dimensionless.

For a Mixture, forwards to thermo's EOS-aware Z.

For a Species, the no-argument call uses the attached cubic EOS (Peng-Robinson by default) to return the real-gas gas-phase factor (eos.Z_g), refreshing the EOS at the current T/P first. For non-gas phases, or for species whose EOS does not expose Z_g (e.g. helium in the supercritical-at-STP regime), it falls back to thermo's curve-based Z, which is pinned near 1.0.

The explicit phase-argument form (compressibility(c, :gas/:liquid/:solid)) returns thermo's curve-based per-phase value (Zg/Zl/Zs); this is not EOS-derived and may sit near 1.0 for a Species. It therefore need not equal the no-argument result, which is EOS-derived for a gas-phase Species.

source
PyThermo.phase — Function
phase(c::Chemical) -> Symbol

Aggregate phase at the chemical's current state — one of :gas, :liquid, :solid, or :two_phase. The last is returned for any coexisting-phase state (thermo strings such as "l/g"), which a Mixture reaches when a flash lands inside a phase envelope — e.g. the cooled result of adiabatic mixing (see Mixture). Throws ErrorException if thermo returns an unrecognized phase string.

source

phase returns :gas, :liquid, :solid, or :two_phase. The last covers a coexisting-phase state, which a Mixture reaches when a flash lands inside a phase envelope (see adiabatic mixing).

Caloric

PyThermo.heat_capacity — Function
heat_capacity(c::Chemical)
heat_capacity(c::Chemical, phase::Symbol)

Isobaric specific heat capacity (mass basis) at the chemical's current state.

Without a phase argument, forwards to Cp. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → Cpg
  • :liquid → Cpl
  • :solid → Cps
source
PyThermo.molar_heat_capacity — Function
molar_heat_capacity(c::Chemical)
molar_heat_capacity(c::Chemical, phase::Symbol)

Isobaric molar heat capacity at the chemical's current state.

Without a phase argument, forwards to Cpm. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → Cpgm
  • :liquid → Cplm
  • :solid → Cpsm
source
PyThermo.isochoric_heat_capacity — Function
isochoric_heat_capacity(c::Chemical)

Isochoric (constant-volume) specific heat capacity (mass basis).

Gas-phase only: thermo exposes no current-phase, liquid, or solid constant-volume heat capacity, so this always forwards to the gas-phase value (Cvg) regardless of the chemical's actual phase.

Forwards to the Python attribute Cvg. Throws if the underlying value is unavailable.

source
PyThermo.enthalpy — Function
enthalpy(c::Chemical)

Specific enthalpy (mass basis) at the chemical's current state, relative to thermo's internal reference state.

Forwards to the Python attribute H. Throws if the underlying value is unavailable.

source
PyThermo.molar_enthalpy — Function
molar_enthalpy(c::Chemical)

Molar enthalpy at the chemical's current state, relative to thermo's internal reference state.

Forwards to the Python attribute Hm. Throws if the underlying value is unavailable.

source
PyThermo.entropy — Function
entropy(c::Chemical)

Specific entropy (mass basis) at the chemical's current state, relative to thermo's internal reference state.

Forwards to the Python attribute S. Throws if the underlying value is unavailable.

source
PyThermo.molar_entropy — Function
molar_entropy(c::Chemical)

Molar entropy at the chemical's current state, relative to thermo's internal reference state.

Forwards to the Python attribute Sm. Throws if the underlying value is unavailable.

source
PyThermo.internal_energy — Function
internal_energy(c::Chemical)

Specific internal energy (mass basis) at the chemical's current state, relative to thermo's internal reference state.

Forwards to the Python attribute U. Throws if the underlying value is unavailable.

source
PyThermo.molar_internal_energy — Function
molar_internal_energy(c::Chemical)

Molar internal energy at the chemical's current state, relative to thermo's internal reference state.

Forwards to the Python attribute Um. Throws if the underlying value is unavailable.

source

Transport

PyThermo.viscosity — Function
viscosity(c::Chemical)
viscosity(c::Chemical, phase::Symbol)

Dynamic viscosity at the chemical's current state.

Without a phase argument, forwards to mu. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → mug
  • :liquid → mul
source
PyThermo.kinematic_viscosity — Function
kinematic_viscosity(c::Chemical)
kinematic_viscosity(c::Chemical, phase::Symbol)

Kinematic viscosity (μ / ρ) at the chemical's current state.

Without a phase argument, forwards to nu. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → nug
  • :liquid → nul
source
PyThermo.thermal_conductivity — Function
thermal_conductivity(c::Chemical)
thermal_conductivity(c::Chemical, phase::Symbol)

Thermal conductivity at the chemical's current state.

Without a phase argument, forwards to k. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → kg
  • :liquid → kl
source
PyThermo.thermal_diffusivity — Function
thermal_diffusivity(c::Chemical)
thermal_diffusivity(c::Chemical, phase::Symbol)

Thermal diffusivity (k / (ρ Cp)) at the chemical's current state.

Without a phase argument, forwards to alpha. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → alphag
  • :liquid → alphal
source
PyThermo.prandtl — Function
prandtl(c::Chemical)
prandtl(c::Chemical, phase::Symbol)

Prandtl number (Cp μ / k) at the chemical's current state. Dimensionless.

Without a phase argument, forwards to Pr. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → Prg
  • :liquid → Prl
source
PyThermo.surface_tension — Function
surface_tension(c::Chemical)

Liquid-vapor surface tension at the chemical's current state.

Forwards to the Python attribute sigma. Throws if the underlying value is unavailable.

source

Derived

PyThermo.isentropic_exponent — Function
isentropic_exponent(c::Chemical) -> Float64

Isentropic exponent γ = Cp / Cv at the chemical's current state. Dimensionless.

source
PyThermo.soundspeed — Function
soundspeed(c::Chemical) -> Quantity{m/s}

Real-gas sound speed at the chemical's current state.

For a Mixture, forwards to thermo's speed_of_sound directly.

For a Species, uses the attached cubic EOS (Peng-Robinson by default) to evaluate

a² = γ_real · (∂P/∂ρ_mass)_T

with γ_real = (Cpgm + Cp_dep_g) / (Cvgm + Cv_dep_g) and (∂P/∂ρ_mass)_T = eos.dP_drho_g / MW. The EOS-derived path is gas-phase only — for non-gas phases or for species whose EOS does not expose departure derivatives (e.g. helium in the supercritical-at-STP regime), the ideal-gas formula a = √(γ R T) is used instead.

source
PyThermo.isobaric_expansion — Function
isobaric_expansion(c::Chemical)
isobaric_expansion(c::Chemical, phase::Symbol)

Isobaric expansion coefficient β = (1/V)(∂V/∂T)_P at the chemical's current state.

Without a phase argument, forwards to isobaric_expansion. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → isobaric_expansion_g
  • :liquid → isobaric_expansion_l
source
PyThermo.joule_thomson — Function
joule_thomson(c::Chemical)
joule_thomson(c::Chemical, phase::Symbol)

Joule-Thomson coefficient μJT = (∂T/∂P)H at the chemical's current state.

Without a phase argument, forwards to JT. Throws if the underlying value is unavailable.

Phase-specific Python attributes:

  • :gas → JTg
  • :liquid → JTl
source

Identity

PyThermo.molecular_weight — Function
molecular_weight(c::Chemical) -> Quantity{g/mol}

Molecular weight. For mixtures, this is the mole-fraction-weighted average of the component molecular weights.

Note: thermo's MW attribute is in g/mol, not kg/mol; the returned Quantity preserves that unit.

source
PyThermo.CAS — Function
CAS(s::Species) -> String

CAS registry number. Defined on Species only; for the per-component CAS numbers of a Mixture, use the property fallthrough (m.CASs).

source
PyThermo.formula — Function
formula(s::Species) -> String

Empirical chemical formula. Defined on Species only.

source

Mixture composition

PyThermo.mole_fractions — Function
mole_fractions(m::Mixture) -> Vector{Float64}

Mole fractions of the mixture's components, in the same order as m.IDs.

source
PyThermo.mass_fractions — Function
mass_fractions(m::Mixture) -> Vector{Float64}

Mass fractions of the mixture's components, in the same order as m.IDs.

source
PyThermo.components — Function
components(m::Mixture) -> Vector{Pair{String, Float64}}

Mixture composition as a vector of "ID" => mole_fraction pairs. The order matches m.IDs.

source

Optional constants

PyThermo.T_critical — Function
T_critical(c::Chemical)

Critical-point temperature. Returns missing if not available.

Forwards to the Python attribute Tc. Returns missing if the underlying value is unavailable.

source
PyThermo.P_critical — Function
P_critical(c::Chemical)

Critical-point pressure. Returns missing if not available.

Forwards to the Python attribute Pc. Returns missing if the underlying value is unavailable.

source
PyThermo.acentric_factor — Function
acentric_factor(c::Chemical)

Pitzer acentric factor ω. Dimensionless. Returns missing if not available.

Forwards to the Python attribute omega. Returns missing if the underlying value is unavailable.

source
PyThermo.T_boiling — Function
T_boiling(c::Chemical)

Normal boiling point (1 atm). Returns missing if not available.

Forwards to the Python attribute Tb. Returns missing if the underlying value is unavailable.

source
PyThermo.enthalpy_vaporization — Function
enthalpy_vaporization(c::Chemical)

Specific enthalpy of vaporization at the chemical's current temperature. Returns missing if the chemical is above its critical point or has no vaporization data.

Forwards to the Python attribute Hvap. Returns missing if the underlying value is unavailable.

source
PyThermo.P_saturation — Function
P_saturation(c::Chemical)

Vapor pressure at the chemical's current temperature. Returns missing if the chemical is above its critical point or has no Psat correlation.

Forwards to the Python attribute Psat. Returns missing if the underlying value is unavailable.

source

State updates

PyThermo.setstate! — Function
setstate!(c::Chemical; T=nothing, P=nothing) -> Chemical

Set temperature and/or pressure and re-flash the chemical's state. Unlike assignment to c.T / c.P, this calls the underlying calculate method, which correctly handles phase changes.

Either or both of T and P may be provided. Unitful quantities are converted to K / Pa; bare Real values are taken to already be in K / Pa.

Examples

julia> using Unitful

julia> SF6 = Species("SF6")
Species(SF6, 298.1 K, 1.013e+05 Pa)

julia> setstate!(SF6, T=20u"K");

julia> SF6.phase
"s"
source

thermo → PyThermo cheatsheet

The table below maps thermo's Python attribute names to the corresponding PyThermo accessors. Phase-variant columns indicate the supported phase argument for the no-suffix accessor.

State

thermo attribute(s)PyThermo accessorUnit
Ttemperature(c)K
Ppressure(c)Pa
rho / rhog / rhol / rhosdensity(c[, :gas/:liquid/:solid])kg/m³
rhom / rhogm / rholm / rhosmmolar_density(c[, phase])mol/m³
Vm / Vmg / Vml / Vmsmolar_volume(c[, phase])m³/mol
Z / Zg / Zl / Zs (see compressibility)compressibility(c[, phase])—
phasephase(c) (:gas/:liquid/:solid/:two_phase)—

Caloric

thermo attribute(s)PyThermo accessorUnit
Cp / Cpg / Cpl / Cpsheat_capacity(c[, phase])J/(kg·K)
Cpm / Cpgm / Cplm / Cpsmmolar_heat_capacity(c[, phase])J/(mol·K)
Cvg (gas only)isochoric_heat_capacity(c)J/(kg·K)
Cvgm (gas only)molar_isochoric_heat_capacity(c)J/(mol·K)
Henthalpy(c)J/kg
Hmmolar_enthalpy(c)J/mol
Sentropy(c)J/(kg·K)
Smmolar_entropy(c)J/(mol·K)
Uinternal_energy(c)J/kg
Ummolar_internal_energy(c)J/mol

Transport

thermo attribute(s)PyThermo accessorUnit
mu / mug / mulviscosity(c[, :gas/:liquid])Pa·s
nu / nug / nulkinematic_viscosity(c[, phase])m²/s
k / kg / klthermal_conductivity(c[, phase])W/(m·K)
alpha / alphag / alphalthermal_diffusivity(c[, phase])m²/s
Pr / Prg / Prlprandtl(c[, phase])—
sigmasurface_tension(c)N/m

Derived

thermo attribute(s)PyThermo accessorUnit
isentropic_exponentisentropic_exponent(c)—
R_specificR_specific(c)J/(kg·K)
EOS-derived (see soundspeed)soundspeed(c)m/s
isobaric_expansion / _g / _lisobaric_expansion(c[, phase])1/K
JT / JTg / JTljoule_thomson(c[, phase])K/Pa

Identity & composition

thermo attribute(s)PyThermo accessorReturn type
MWmolecular_weight(c)Quantity{g/mol}
CASCAS(s) (Species only)String
formulaformula(s) (Species only)String
zsmole_fractions(m)Vector{Float64}
wsmass_fractions(m)Vector{Float64}
IDs + zscomponents(m)Vector{Pair{String, Float64}}

Optional constants

thermo attributePyThermo accessorUnit
TcT_critical(c)K
PcP_critical(c)Pa
omegaacentric_factor(c)—
TbT_boiling(c)K
Hvapenthalpy_vaporization(c)J/kg
PsatP_saturation(c)Pa

Internals

The bulk of the curated accessors are generated by a small macro. These internals are unexported and documented for reference only: external packages can use them to define additional wrappers, but PropSpec's field layout and the macro's argument signature are implementation details and may change in any release without a breaking-version bump.

PyThermo.PropSpec — Type
PropSpec{U, P}

Describes one curated Julian property accessor.

  • name — the Julia function name (e.g. :density).
  • pyattr — the underlying Python attribute name on Chemical/Mixture (e.g. :rho).
  • unit — a Unitful.Units value (use Unitful.NoUnits for genuinely dimensionless quantities).
  • optional — false for strict accessors that throw on None; true for accessors that return missing when the underlying Python value is None.
  • phase_table — nothing, or a NamedTuple mapping phase symbols to per-phase Python attribute names, e.g. (gas = :rhog, liquid = :rhol, solid = :rhos).
  • doc — short docstring fragment used as the first line of the generated docstring.
Not part of the public API

PropSpec is documented so downstream packages can read the field layout, but it is an implementation detail. Its fields and type parameters may change in any release without a breaking-version bump.

source
PyThermo.@thermo_property — Macro
@thermo_property name pyattr unit optional phase_table doc

Define a curated Julian accessor that forwards to a Python attribute on a Chemical (Species or Mixture).

  • unit is a Unitful.Units value (use NoUnits for dimensionless results).
  • optional is false for strict accessors (throw on None) and true for optional accessors (return missing when the Python attribute is None).
  • phase_table is either the literal nothing or a NamedTuple expression like (gas=:rhog, liquid=:rhol, solid=:rhos). When provided, a second method dispatching on (::Chemical, ::Symbol) is also emitted.
  • doc is a short docstring fragment used as the function summary.
Not part of the public API

This macro is documented for reference, but its argument signature is an implementation detail and may change in any release without a breaking-version bump. Downstream packages that build their own wrappers on it do so at their own risk.

source