prometheus_equilibrium.equilibrium.solution

EquilibriumSolution — converged state from a chemical equilibrium calculation.

For rocket propulsion the two primary calculations are:

Combustion chamber (HP problem): reactants at known enthalpy and chamber pressure → equilibrium temperature T_c, species composition, mixture properties (Cp, γ, M̄).
Nozzle expansion (SP problem): chamber state isentropically expanded to throat or exit → T_e, P_e, frozen/shifting species, specific impulse.

This class holds the output of either calculation and provides properties relevant to both. Rocket-specific derived quantities (c*, Isp, ṁ, …) are computed from combinations of the basic mixture properties.

class prometheus_equilibrium.equilibrium.solution.ConvergenceStep(temperature: float, max_residual: float, mole_fractions: Dict[str, float])

Bases: object

Snapshot of solver state at a single iteration.

temperature: float

max_residual: float

mole_fractions: Dict[str, float]

class prometheus_equilibrium.equilibrium.solution.EquilibriumSolution(mixture: Mixture, temperature: float, pressure: float, converged: bool, iterations: int, residuals: np.ndarray, lagrange_multipliers: np.ndarray, history: List[ConvergenceStep] = None)

Bases: object

Converged thermodynamic state from an equilibrium calculation.

mixture

Converged species mixture with mole amounts nⱼ.

Type:: Mixture

temperature

Equilibrium temperature T [K].

Type:: float

pressure

Equilibrium pressure P [Pa].

Type:: float

converged

True if all convergence criteria were satisfied.

Type:: bool

iterations

Number of Newton iterations taken.

Type:: int

residuals

Final element-balance residuals ||Δb||, shape (n_elements,).

Type:: np.ndarray

lagrange_multipliers

Converged reduced Lagrange multipliers π, shape (n_elements,). The chemical potential of element k at equilibrium is λₖ = −R·T·πₖ.

Type:: np.ndarray

history

List of states at each iteration, used for convergence plots.

Type:: List[ConvergenceStep]

mixture: Mixture

temperature: float

pressure: float

converged: bool

iterations: int

residuals: np.ndarray

lagrange_multipliers: np.ndarray

history: List[ConvergenceStep] = None

property mole_fractions: Dict[str, float]

xⱼ}.

Returns:: Dict mapping each species’ human-readable formula to its mole fraction.
Type:: Mole fractions {species_formula

major_species(threshold: float = 0.0001) → Dict[str, float]

Mole fractions of species above threshold (default 0.01 %).

Parameters:: threshold – Minimum mole fraction to include in the result.
Returns:: Dict of {element_string: mole_fraction} for all species with xⱼ ≥ threshold, sorted descending by mole fraction.

property mean_molar_mass: float

Mean molar mass M̄ [kg/mol].

For a two-phase mixture this includes both gas and condensed species weighted by mole fraction. Use gas_mean_molar_mass for rocket performance calculations.

property gas_mean_molar_mass: float

Gas-phase mean molar mass M̄_gas [kg/mol].

Used for speed of sound and density in the presence of condensed products (e.g. Al₂O₃ in aluminised propellants).

property cp: float

Mixture Cp at equilibrium T [J/(mol·K)].

Molar Cp over all species (gas + condensed), per mole of mixture. This is the frozen Cp (composition fixed).

property cv: float

Mixture Cv at equilibrium T [J/(mol·K)].

Ideal-gas approximation: Cv = Cp − R. Only valid for the gas-phase contribution; for mixtures with significant condensed mass the correction is smaller.

property gamma: float

Ratio of specific heats γ = Cp / Cv (frozen-flow isentropic exponent).

Returns:: Dimensionless γ > 1. For an ideal monatomic gas γ = 5/3; for a diatomic gas γ ≈ 7/5.

property enthalpy: float: Mixture absolute enthalpy H [J/mol] at equilibrium T.

property entropy: float: Mixture entropy S [J/(mol·K)] at equilibrium T and P.

property gibbs: float: Mixture Gibbs free energy G = H − T·S [J/mol].

property speed_of_sound: float

Frozen speed of sound a [m/s] at the equilibrium state.

Uses the gas-phase mean molar mass (excludes condensed species):

\[a = \sqrt{\gamma \cdot R \cdot T \,/\, \bar{M}_{\text{gas}}}\]

Returns:: Speed of sound in m/s.
Raises:: ValueError – If there are no gas-phase species.

property density: float

Gas-phase mixture density ρ [kg/m³] at equilibrium T and P.

From the ideal-gas law:

\[\rho = \frac{P \cdot \bar{M}_{\text{gas}}}{R \cdot T}\]

characteristic_velocity(throat: EquilibriumSolution) → float

Characteristic velocity c* [m/s].

Computed from the throat conditions (isentropic, frozen flow):

\[c^* = \frac{a_t}{\Gamma} \quad\text{where }\Gamma = \sqrt{\gamma_t} \left(\frac{2}{\gamma_t+1}\right)^{(\gamma_t+1)/[2(\gamma_t-1)]}\]

Parameters:: throat – The converged state at the nozzle throat (Mach 1).
Returns:: Characteristic velocity c* in m/s.

specific_impulse(throat: EquilibriumSolution, exit: EquilibriumSolution, ambient_pressure: float = 0.0) → float

Specific impulse Isp [s].

Vacuum Isp (ambient_pressure=0) is the standard figure of merit. Uses the enthalpy-drop formula for exit velocity:

\[v_e = \sqrt{2 (h_c - h_e)}\]

where h_c and h_e are the extensive enthalpies [J/kg] at chamber and exit conditions.

Parameters:

throat – Converged state at the nozzle throat.
exit – Converged state at the nozzle exit plane.
ambient_pressure – Ambient back-pressure [Pa]. Use 0 for vacuum Isp.

Returns:

Specific impulse in seconds (referenced to standard g₀ = 9.80665 m/s²).

property total_enthalpy: float: Total mixture enthalpy H_total = Σ nⱼ·Hⱼ°(T) [J].

property total_entropy: float: Total mixture entropy S_total = Σ nⱼ·Sⱼ_mix(T,P) [J/K].

summary() → str: Human-readable summary of the equilibrium state.