prometheus_equilibrium.equilibrium.species
Classes
|
AFCESIC thermodynamic polynomial species. |
|
|
|
|
|
NASA Nine-Coefficient Polynomial species. |
|
NASA Seven-Coefficient Polynomial species. |
|
NIST Shomate equation species. |
|
|
|
Loads thermodynamic species from multiple database formats and provides element-based filtering and deduplication. |
|
Coefficients from the TERRA computer program, developed by Boris Georgievich Trusov at Bauman Moscow State Technical University. |
- class prometheus_equilibrium.equilibrium.species.Chemical(elements: dict[slice(<class 'str'>, <class 'float'>, None)], state: ~typing.Literal['S', 'L', 'G'], phase: str | None = None)
Bases:
object
- class prometheus_equilibrium.equilibrium.species.Species(elements: dict, state: Literal['S', 'L', 'G'], phase: str | None = None)
Bases:
Chemical- property formula: str
Helper to print formula in Hill order (C first, H second, then alphabetical).
- abstractmethod specific_heat_capacity(T: float | ndarray) float | ndarray
Returns the specific heat capacity in J/mol K
- abstractmethod enthalpy(T: float | ndarray) float | ndarray
Computes the sensible enthalpy in J/mol
- reduced_gibbs(T: float | ndarray) float | ndarray
Dimensionless standard Gibbs free energy G°/(RT) = H°/(RT) − S°/R.
This is the reduced chemical potential μⱼ°/(RT) used in the equilibrium condition (Gordon-McBride, RP-1311 §2):
μⱼ/RT = μⱼ°/RT + ln(nⱼ/n) + ln(P/P°) [gas phase]
At equilibrium μⱼ/RT = Σₖ πₖ·A[j,k], where πₖ are the modified Lagrange multipliers and A[j,k] is the stoichiometric coefficient of element k in species j.
- reduced_enthalpy(T: float | ndarray) float | ndarray
Dimensionless standard enthalpy H°/(RT).
Appears in the energy-constraint row of the Newton Jacobian (HP and UV problems) and in the definition of reduced_gibbs.
- class prometheus_equilibrium.equilibrium.species.JANAF(elements: dict, state: Literal['S', 'L', 'G'], temperature: tuple, specific_heat_capacity: tuple, enthalpy: tuple, entropy: tuple, phase: str | None = None, h_formation: float = 0.0)
Bases:
Species- specific_heat_capacity(T: float | ndarray) float | ndarray
Returns the specific heat capacity in J/mol K
- class prometheus_equilibrium.equilibrium.species.NASASevenCoeff(elements: dict, state: Literal['S', 'L', 'G'], temperature: tuple, coefficients: tuple[tuple, tuple], phase: str | None = None)
Bases:
SpeciesNASA Seven-Coefficient Polynomial species. Defined by the following equations:
\[ \begin{align}\begin{aligned}C_p(T) = R \cdot \left(a_1 + a_2 T + a_3 T^2 + a_4 T^3 + a_5 T^4\right)\\ H(T) = R \cdot T \cdot \left(a_1 + \frac{a_2 T}{2} + \frac{a_3 T^2}{3} + \frac{a_4 T^3}{4} + \frac{a_5 T^4}{5} + \frac{a_6}{T}\right)\\ S(T) = R \cdot \left(a_1 \ln(T) + a_2 T + \frac{a_3 T^2}{2} + \frac{a_4 T^3}{3} + \frac{a_5 T^4}{4} + a_7\right)\\where :math:`R` is the universal gas constant, and :math:`a_i` are the coefficients for the respective temperature range. The coefficients are typically provided for two temperature ranges: low (T_low to T_common) and high (T_common to T_high). The class handles both ranges.\end{aligned}\end{align} \]- specific_heat_capacity(T: float | ndarray) float | ndarray
Calculates the specific heat capacity using a piecewise polynomial.
- reduced_gibbs(T: float | ndarray) float | ndarray
Dimensionless standard Gibbs free energy G°/(RT) = H°/(RT) − S°/R.
This is the reduced chemical potential μⱼ°/(RT) used in the equilibrium condition (Gordon-McBride, RP-1311 §2):
μⱼ/RT = μⱼ°/RT + ln(nⱼ/n) + ln(P/P°) [gas phase]
At equilibrium μⱼ/RT = Σₖ πₖ·A[j,k], where πₖ are the modified Lagrange multipliers and A[j,k] is the stoichiometric coefficient of element k in species j.
- class prometheus_equilibrium.equilibrium.species.NASANineCoeff(elements: dict, state: Literal['S', 'L', 'G'], temperatures: tuple[float], exponents: tuple[tuple[float]], coefficients: tuple[tuple[float]], phase: str | None = None, alias: str | None = None, source_attribution: str | None = None)
Bases:
SpeciesNASA Nine-Coefficient Polynomial species.
- specific_heat_capacity(T: float | ndarray) float | ndarray
Returns the specific heat capacity in J/mol K
- class prometheus_equilibrium.equilibrium.species.ShomateCoeff(elements: dict, state: Literal['S', 'L', 'G'], temperatures: tuple, coefficients: tuple, phase: str | None = None, alias: str | None = None)
Bases:
SpeciesNIST Shomate equation species.
The Shomate form is used by the NIST WebBook and covers many condensed-phase species not present in NASA-7/9 databases. This class also serves as the container for species imported from the TERRA database, which uses a mathematically compatible reduced Gibbs energy (Phi-star) polynomial.
- Equation Form (with t = T/1000):
Cp°(T) = A + Bt + Ct² + Dt³ + E/t² [J/mol/K] H°(T) = (At + Bt²/2 + Ct³/3 + Dt⁴/4 − E/t + F) × 1000 [J/mol] S°(T) = A·ln(t) + Bt + Ct²/2 + Dt³/3 − E/(2t²) + G [J/mol/K]
- TERRA Integration:
TERRA coefficients (f1…f7) are mapped to Shomate (A…G) using the following transformations (accounting for TERRA’s x = T/10000 scaling):
A = f2 B = 0.2 * f5 C = 0.06 * f6 D = 0.012 * f7 E = 200.0 * f3 F = (H_meta - 10000*f4 - shift) / 1000 G = f1 + f2 - f2 * ln(10)
The F coefficient encodes the standard enthalpy of formation at 298.15 K per NIST convention: H°(T) [kJ/mol] = At + Bt²/2 + … + F, where F is chosen so that the formula reproduces ΔfH°(298.15 K) at t = 0.29815. The H coefficient (= ΔfH°(298.15 K) in kJ/mol) is stored for reference only and is not used by the evaluation routines.
JSON schema (shomate.json):
{ "Bi2O3_S": { "elements": {"Bi": 2, "O": 3}, "phase": "S", "alias": "Bi2O3", "segments": [ { "t_low": 298.0, "t_high": 1097.0, "coefficients": [A, B, C, D, E, F, G, H] } ] } }
- temperatures
Segment boundary temperatures [K], length n_segs+1.
- coefficients
Per-segment Shomate coefficients [A,B,C,D,E,F,G,H], one tuple of 8 floats per segment.
- alias
Optional original source name.
- classmethod from_terra(elements: dict, state: Literal['S', 'L', 'G'], temperatures: tuple, terra_coefficients: tuple, phase: str | None = None, alias: str | None = None) ShomateCoeff
Create a ShomateCoeff species from TERRA f1-f7 coefficients.
Mapping (x = T/1000): TERRA Cp = f2 + 2f3/x^2 + 2f5*x + 6f6*x^2 + 12f7*x^3 Shomate Cp = A + B*t + C*t^2 + D*t^3 + E/t^2
A = f[1] B = 2*f[4] C = 6*f[5] D = 12*f[6] E = 2*f[2] F = -f[3] G = f[0] + f[1]
- specific_heat_capacity(T: float | ndarray) float | ndarray
Cp°(T) = A + Bt + Ct² + Dt³ + E/t² [J/mol/K].
- enthalpy(T: float | ndarray) float | ndarray
H°(T) = (At + Bt²/2 + Ct³/3 + Dt⁴/4 − E/t + F) × 1000 [J/mol].
- entropy(T: float | ndarray) float | ndarray
S°(T) = A·ln(t) + Bt + Ct²/2 + Dt³/3 − E/(2t²) + G [J/mol/K].
- class prometheus_equilibrium.equilibrium.species.AFCESICCoeff(elements: dict, state: Literal['S', 'L', 'G'], temperature: tuple, low_coefficients: tuple, high_coefficients: tuple, rf: float, ch: float, phase: str | None = None)
Bases:
SpeciesAFCESIC thermodynamic polynomial species.
The AFCESIC database (Air Force Chemical Equilibrium Specific Impulse Code) stores heat-capacity data as two sets of five float32 coefficients in θ = T/1000. The low-temperature set uses forward powers of θ while the high-temperature set uses inverse powers, giving natural convergence at combustion temperatures.
Low-T range (T_low ≤ T ≤ T_mid, typically 300–1200 K):
Cp = b₁ + b₂θ + b₃θ² + b₄θ³ + b₅θ⁴ [cal/(mol·K)] H = 1000·(b₁θ + b₂θ²/2 + b₃θ³/3 + b₄θ⁴/4 + b₅θ⁵/5) + RF [cal/mol] S = b₁·ln θ + b₂θ + b₃θ²/2 + b₄θ³/3 + b₅θ⁴/4 + CH [cal/(mol·K)]High-T range (T_mid < T ≤ T_high, typically 1200–6000 K):
Cp = a₁ + a₂/θ + a₃/θ² + a₄/θ³ + a₅/θ⁴ [cal/(mol·K)] H = 1000·(a₁θ + a₂·ln θ − a₃/θ − a₄/(2θ²) − a₅/(3θ³)) + H₀_hi [cal/mol] S = a₁·ln θ − a₂/θ − a₃/(2θ²) − a₄/(3θ³) − a₅/(4θ⁴) + S₀_hi [cal/(mol·K)]The high-T integration constants
H₀_hiandS₀_hiare derived from continuity of H and S at T_mid (θ_mid = 1.2, T = 1200 K). Note: the original AFCESIC format specifies T_mid = 1000 K, but inspection of the polynomial coefficients shows the smoothest crossover for this dataset occurs at 1200 K; 1000 K produces a visible discontinuity in H and S.- Parameters:
elements – Element composition, e.g.
{"H": 2, "O": 1}.state –
"G","L", or"S".temperature –
(T_low, T_mid, T_high)in Kelvin.low_coefficients –
(b₁, b₂, b₃, b₄, b₅)— forward-power Cp coefficients for the low-T range [cal/(mol·K)].high_coefficients –
(a₁, a₂, a₃, a₄, a₅)— inverse-power Cp coefficients for the high-T range [cal/(mol·K)].rf – Enthalpy integration constant RF (low-T range) [kcal/mol ÷ 1000].
ch – Entropy integration constant CH (low-T range) [cal/(mol·K)].
phase – Optional phase label for display.
- specific_heat_capacity(T: float | ndarray) float | ndarray
Returns the specific heat capacity in J/mol K
- reduced_gibbs(T: float | ndarray) float | ndarray
Dimensionless standard Gibbs free energy G°/(RT) = H°/(RT) − S°/R.
This is the reduced chemical potential μⱼ°/(RT) used in the equilibrium condition (Gordon-McBride, RP-1311 §2):
μⱼ/RT = μⱼ°/RT + ln(nⱼ/n) + ln(P/P°) [gas phase]
At equilibrium μⱼ/RT = Σₖ πₖ·A[j,k], where πₖ are the modified Lagrange multipliers and A[j,k] is the stoichiometric coefficient of element k in species j.
- class prometheus_equilibrium.equilibrium.species.TERRACoeff(elements: dict, state: Literal['S', 'L', 'G'], temperatures: tuple, coefficients: tuple, phase: str | None = None)
Bases:
SpeciesCoefficients from the TERRA computer program, developed by Boris Georgievich Trusov at Bauman Moscow State Technical University.
In TERRA, the thermodynamic properties are derived from the reduced Gibbs energy G* (in J/mol K), defined using 7 coefficients:
\[G^*(x) = f_1 + f_2 \ln x + f_3 x^{-2} + f_4 x^{-1} + f_5 x + f_6 x^2 + f_7 x^3\]where the scaled temperature x is defined as:
\[x = T \cdot 10^{-3}\]Using the thermodynamic relations G* = S - H/T and dG*/dT = H/T^2, we derive:
\[ \begin{align}\begin{aligned}H(x) = 1000 \cdot (f_2 x - 2f_3 x^{-1} - f_4 + f_5 x^2 + 2f_6 x^3 + 3f_7 x^4)\\S(x) = f_1 + f_2(1 + \ln x) - f_3 x^{-2} + 2f_5 x + 3f_6 x^2 + 4f_7 x^3\\C_p(x) = f_2 + 2f_3 x^{-2} + 2f_5 x + 6f_6 x^2 + 12f_7 x^3\end{aligned}\end{align} \]
- class prometheus_equilibrium.equilibrium.species.SpeciesDatabase(nasa7_path: str | None = None, nasa9_path: str | None = None, janaf_path: str | None = None, shomate_path: str | None = None, afcesic_path: str | None = None, terra_path: str | None = None, source_priority: Sequence[str] | Dict[str, int] | None = None)
Bases:
objectLoads thermodynamic species from multiple database formats and provides element-based filtering and deduplication.
When the same species (same composition and phase) exists in multiple enabled databases, a priority-based selection is performed.
- Priority (highest wins, default):
NASA-9 > NASA-7 > JANAF > TERRA > AFCESIC
Users can override this with
source_priorityin__init__orload().- set_source_priority(source_priority: Sequence[str] | Dict[str, int] | None) None
Set source-priority rules used during deduplication.
- Parameters:
source_priority – Either an ordered sequence (highest first) or a dict mapping source name to integer priority.
- load(include_nasa7: bool = True, include_nasa9: bool = True, include_afcesic: bool = False, include_janaf: bool = False, include_shomate: bool = False, include_terra: bool = True, source_priority: Sequence[str] | Dict[str, int] | None = None) None
Load thermodynamic databases into the raw species list.
- get_species(elements: set, max_atoms: int | None = None, enabled_databases: List[str] | None = None) List[Species]
Return unique product species from enabled databases for specified elements.