prometheus_equilibrium.equilibrium.problem

EquilibriumProblem — specification of a chemical equilibrium calculation.

A problem is fully defined by:

  1. Reactants: the initial mixture whose element composition fixes the conserved element abundance vector b₀.

  2. Products: candidate product species (any subset of the species database that contains the right elements).

  3. Constraint type: which pair of thermodynamic variables is held constant during the calculation (TP, HP, SP, TV, UV, or SV).

  4. Constraint values: numerical values of the two fixed variables.

The problem object does not run any iteration — it is purely declarative. Pass it to an EquilibriumSolver to obtain an EquilibriumSolution.

Constraint types

Following NASA CEA (RP-1311) naming conventions:

TP — constant T [K] and P [Pa] HP — constant H [J] and P [Pa] (adiabatic combustion at const P) SP — constant S [J/K] and P [Pa] (isentropic nozzle expansion) TV — constant T [K] and V [m³] UV — constant U [J] and V [m³] (constant-volume explosion) SV — constant S [J/K] and V [m³] (isentropic compression)

Classes

EquilibriumProblem(reactants, products, ...)

Declarative specification of a chemical equilibrium problem.

ProblemType(*values)

Which pair of thermodynamic variables is held constant.
class prometheus_equilibrium.equilibrium.problem.ProblemType(*values)

Bases: Enum

Which pair of thermodynamic variables is held constant.

TP = 'TP'
HP = 'HP'
SP = 'SP'
TV = 'TV'
UV = 'UV'
SV = 'SV'
property fixed_temperature: bool

True if temperature is a fixed input (TP or TV problems).

property fixed_pressure: bool

True if pressure is a fixed input (TP, HP, SP problems).

property energy_constraint: str | None

‘H’, ‘S’, ‘U’, or None.

Type:

Which energy-like quantity is fixed

class prometheus_equilibrium.equilibrium.problem.EquilibriumProblem(reactants: Dict[Species, float], products: List[Species], problem_type: ProblemType, constraint1: float, constraint2: float, pressure: float = 100000.0, t_init: float | None = None, sp_entropy_mode: str = 'total')

Bases: object

Declarative specification of a chemical equilibrium problem.

Parameters

reactantsdict {Species: float}

Reactant species mapped to their mole amounts [mol]. These define the conserved element abundances b₀ = A^T · n_reactants.

productslist of Species

Candidate product species. Typically obtained from SpeciesDatabase.get_species(element_set); the solver will find the subset that minimises Gibbs free energy.

problem_typeProblemType

Which pair of thermodynamic variables is held constant.

constraint1float

Value of the first fixed variable. Interpretation by problem type:

  • TP : T [K]

  • HP : H [J] (total enthalpy of the reactant mixture)

  • SP : S [J/K]

  • TV : T [K]

  • UV : U [J]

  • SV : S [J/K]

constraint2float

Value of the second fixed variable. Interpretation by problem type:

  • TP : P [Pa]

  • HP : P [Pa]

  • SP : P [Pa]

  • TV : V [m³]

  • UV : V [m³]

  • SV : V [m³]

pressurefloat, optional

Reference pressure [Pa] for ideal-gas chemical-potential calculations. Defaults to 1 bar (1e5 Pa). For TP/HP/SP problems this is the same as constraint2; it is kept as a separate parameter for TV/UV/SV problems where pressure is not fixed.

t_initfloat, optional

Initial temperature estimate [K] for the Newton iteration. If None, a default of 3000 K is used for combustion problems.

classmethod from_mass_fractions(species_mass: Dict[Species, float], products: List[Species], problem_type: ProblemType, constraint1: float, constraint2: float, **kwargs) → EquilibriumProblem

Construct from reactants given as mass amounts [kg].

Converts each reactant’s mass to moles using its molar mass (species.molar_mass() returns kg/mol), then delegates to the standard constructor.

Parameters:

  • species_mass – Mass of each reactant species in kilograms.

  • products – Candidate product species.

  • problem_type – Thermodynamic constraint type.

  • constraint1 – First constraint value.

  • constraint2 – Second constraint value.

  • **kwargs – Forwarded to the standard constructor (e.g. t_init).

element_abundances() → Dict[str, float]

Compute b₀: total moles of each element from the reactant mixture.

b₀[k] = Σⱼ  n_reactant[j] × A[j, k]

where A[j, k] is the stoichiometric coefficient of element k in reactant species j. This is the conserved quantity that the equilibrium composition must satisfy.

Returns a dict {element_symbol: total_moles}.

b0_array(elements: List[str]) → ndarray

Return b₀ as a NumPy array aligned to elements.

Parameters

elementslist of str

Ordered element list matching the columns of an ElementMatrix.

Returns

np.ndarray, shape (n_elements,)

initial_mixture() → Mixture

Construct a starting-guess Mixture for the Newton iteration.

Follows the strategy from cpropep / RP-1311 §3.2: distribute moles equally among all gas-phase product species; set all condensed species to zero (the solver will include them when their chemical potential condition is satisfied).

The total initial gas moles is set to the mean element abundance (Σ b₀ₖ / n_elements) as a physically reasonable scale — this puts the starting composition in the right order of magnitude without requiring a more expensive atom-balance initialisation. The G-McB Newton iteration is robust enough to converge from this simple guess.

Returns

Mixture

All product species in gas-first order. Gas species have equal positive mole amounts; condensed species start at zero.

validate() → None

Verify the problem is well-posed before handing it to the solver.

Checks

  • At least one reactant species is provided.

  • At least one product species is provided.

  • All element abundances in b₀ are non-negative.

  • Every element in b₀ is represented by at least one product species.

  • The initial temperature estimate is positive.

  • For TP/TV: constraint1 (T) > 0.

  • For HP/SP/UV/SV: constraint2 has physically reasonable sign.

Raises

ValueError

With a descriptive message identifying the first failed check.