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: ndarray, lagrange_multipliers: ndarray, history: List[ConvergenceStep] | None = None, failure_reason: NonConvergenceReason | None = None, element_balance_error: float | None = None, last_step_norm: float | None = None, gamma_s: float | None = None)

Bases: object

Converged thermodynamic state from an equilibrium calculation.

mixture

Converged species mixture with mole amounts nⱼ.

Type:: prometheus_equilibrium.equilibrium.mixture.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₀ − Aᵀ·n, shape (n_elements,).

Type:: numpy.ndarray

lagrange_multipliers

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

Type:: numpy.ndarray

history

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

Type:: List[prometheus_equilibrium.equilibrium.solution.ConvergenceStep] | None

failure_reason

If converged is False, the enum value describing why the solver stopped. None on a successful solve.

Type:: prometheus_equilibrium.equilibrium.diagnostics.NonConvergenceReason | None

element_balance_error

max(|b₀ − Aᵀ·n|) over all elements at the final iteration. Always populated (even on convergence) so it can be used to verify element conservation independently.

Type:: float | None

last_step_norm

Solver-specific convergence criterion on the final iteration — the same quantity that is compared against tolerance. For Newton solvers this is max(|nⱼ·Δln nⱼ| / n_gas, |Δln n|); for PEP and the outer temperature search it is the energy/element residual norm at the last step. Always populated.

Type:: float | None

mixture: Mixture

temperature: float

pressure: float

converged: bool

iterations: int

residuals: ndarray

lagrange_multipliers: ndarray

history: List[ConvergenceStep] | None = None

failure_reason: NonConvergenceReason | None = None

element_balance_error: float | None = None

last_step_norm: float | None = None

gamma_s: float | None = None: Equilibrium isentropic exponent γₛ (RP-1311). Set by PerformanceSolver after a converged SP solve. None for frozen solutions or HP chamber solves; isentropic_gamma falls back to the frozen γ when this is 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)].

For a two-phase (gas + condensed) mixture only the gas fraction contributes PV work, so the correct relation is:

\[C_{v,\text{mix}} = C_{p,\text{mix}} - f \cdot R\]

where \(f = n_{\text{gas}} / n_{\text{total}}\) is the gas mole fraction. For a pure gas (\(f = 1\)) this reduces to the ideal-gas relation \(C_v = C_p - R\).

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 isentropic_gamma: float

Isentropic exponent for nozzle flow calculations.

Returns the equilibrium γₛ (NASA RP-1311) if it was computed and stored by PerformanceSolver after a shifting SP solve, otherwise returns the frozen γ = Cp/Cv.

Returns:: γₛ > 1 (equilibrium) or γ = Cp/Cv (frozen fallback).

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 gas_entropy: float: Gas-phase molar entropy S_gas [J/(mol_gas·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.

For a two-phase (gas + condensed) mixture in homogeneous flow the condensed particles travel with the gas and contribute inertia. The correct formula accounts for both the gas fraction f and the total mixture mean molar mass \(\bar{M}_{\text{mix}}\):

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

where \(f = n_{\text{gas}} / n_{\text{total}}\) and \(\gamma\) is computed from the two-phase Cv (see cv). For a pure gas (\(f = 1\), \(\bar{M}_{\text{mix}} = \bar{M}_{\text{gas}}\)) this reduces to the standard ideal-gas formula.

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

property density: float

Total mixture density ρ [kg/m³] at equilibrium T and P.

Accounts for both gas and condensed phases (homogeneous two-phase flow). Only the gas fraction contributes to the pressure, so:

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

where \(f = n_{\text{gas}} / n_{\text{total}}\) and \(\bar{M}_{\text{mix}}\) is the total (gas + condensed) mean molar mass. For a pure gas (\(f = 1\), \(\bar{M}_{\text{mix}} = \bar{M}_{\text{gas}}\)) this reduces to the ideal-gas law \(\rho = P \bar{M} / (R 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].

property total_gas_entropy: float: Total gas-phase entropy Σⱼ∈gas nⱼ·Sⱼ_mix(T,P) [J/K].

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