Equilibrate API

ChemEquiAnalysis computes thermochemical equilibrium for a specified pressure, temperature, and elemental or species composition. Results are exposed as properties on the same object after a successful solve.

Construction

photochem.equilibrate.ChemEquiAnalysis(
    thermofile,
    atoms=None,
    species=None,
)

The constructor is shown explicitly because Python's runtime inspection does not expose constructor parameters for compiled extension classes.

ChemEquiAnalysis

ChemEquiAnalysis()

Chemical-equilibrium solver and state from its most recent solve.

Name and mass properties are established during construction. Composition and thermodynamic result properties are updated by solve and solve_metallicity; check the returned convergence flag before using them. Array-valued properties return copies.

Initialize a chemical-equilibrium solver from thermodynamic data.

Python accepts YAML thermodynamic files. Supplying only atoms selects every compatible species; supplying only species selects every atom in those species; and supplying neither uses the entire file. The two selections are mutually exclusive in Python.

Parameters:

Name	Type	Description	Default
thermofile	str	Path to a YAML thermodynamic file.	required
atoms	sequence of str	Nonempty atom-name selection.	required
species	sequence of str	Nonempty species-name selection.	required

Raises:

Type	Description
EquilibrateException	If the file or selections are invalid, or an entry exceeds the supported 20-character length.

atoms_names property

atoms_names

list[str]: Atom names in the ordering used by atom-indexed arrays.

c_pe property

c_pe

float: Equilibrium specific heat at constant pressure (erg/(g K)).

condensate_mass property

condensate_mass

ndarray, shape (nc,): Read-only copy of condensate molar masses (g/mol).

condensate_names property

condensate_names

list[str]: Condensate names in condensed-phase array ordering.

gamma2 property

gamma2

float: Second adiabatic exponent, 1 / (1 - nabla_ad).

gas_mass property

gas_mass

ndarray, shape (ng,): Read-only copy of gas molar masses (g/mol).

gas_names property

gas_names

list[str]: Gas names in the ordering used by gas-phase arrays.

mass_tol property

mass_tol

float: Dimensionless mass-balance convergence tolerance.

massfracs_species property

massfracs_species

ndarray, shape (ns,): Read-only copy of species mass fractions across all phases.

molfracs_atoms property

molfracs_atoms

ndarray, shape (na,): Read-only copy of atom mole fractions across all phases.

molfracs_atoms_condensate property

molfracs_atoms_condensate

ndarray, shape (na,): Read-only copy of condensed-phase atom mole fractions.

molfracs_atoms_gas property

molfracs_atoms_gas

ndarray, shape (na,): Read-only copy of gas-phase atom mole fractions.

molfracs_atoms_sun property

molfracs_atoms_sun

ndarray, shape (na,): Writable reference solar atom mole fractions.

Values follow atoms_names order. Getting this property returns a copy; assign the complete array to update the reference used by solve_metallicity.

molfracs_species property

molfracs_species

ndarray, shape (ns,): Read-only copy of species mole fractions across all phases.

molfracs_species_condensate property

molfracs_species_condensate

ndarray, shape (nc,): Read-only copy of condensed species mole fractions.

molfracs_species_gas property

molfracs_species_gas

ndarray, shape (ng,): Read-only copy of gas-phase species mole fractions.

mubar property

mubar

float: Mean molecular weight of the equilibrium gas phase (g/mol).

nabla_ad property

nabla_ad

float: Adiabatic logarithmic temperature gradient, dln(T)/dln(P).

rho property

rho

float: Equilibrium gas mass density (g/cm^3).

species_mass property

species_mass

ndarray, shape (ns,): Read-only copy of species molar masses (g/mol).

species_names property

species_names

list[str]: All species names in the ordering used by full-species arrays.

use_prev_guess property

use_prev_guess

bool: Whether to initialize from the previous converged solution.

verbose property

verbose

bool: Whether the equilibrium solver prints iteration details.

solve method descriptor

solve(P, T, molfracs_atoms=None, molfracs_species=None)

Compute chemical equilibrium from atom or species mole fractions.

Supply exactly one composition array. It is normalized internally. On a completed solve, the result properties contain the latest equilibrium state and the return value reports whether the iteration converged.

Parameters:

Name	Type	Description	Default
P	float	Pressure (dyn/cm^2).	required
T	float	Temperature (K).	required
molfracs_atoms	(ndarray, shape(na))	Nonnegative atom mole fractions in atoms_names order.	None
molfracs_species	(ndarray, shape(ns))	Nonnegative species mole fractions in species_names order.	None

Returns:

Type	Description
bool	Whether the equilibrium iteration met its tolerances.

Raises:

Type	Description
EquilibrateException	If the inputs are invalid or the compiled solver reports an error.

solve_metallicity method descriptor

solve_metallicity(P, T, metallicity, CtoO=None)

Compute chemical equilibrium from metallicity and an optional C/O ratio.

Heavy-element abundances in molfracs_atoms_sun are scaled relative to H and He. If CtoO is supplied, carbon and oxygen are redistributed while preserving their combined abundance. Result properties are updated as in solve.

Parameters:

Name	Type	Description	Default
P	float	Pressure (dyn/cm^2).	required
T	float	Temperature (K).	required
metallicity	float	Positive metallicity relative to the reference solar composition.	required
CtoO	float	Positive C/O ratio relative to the reference solar value. A value of 1 preserves solar C/O.	None

Returns:

Type	Description
bool	Whether the equilibrium iteration met its tolerances.

Raises:

Type	Description
EquilibrateException	If metallicity or C/O is nonpositive, required C or O atoms are absent, or the compiled solver reports an error.