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.CalibratedSpecies(base: Species, h_offset: float, s_offset: float)
Bases:
SpeciesA condensed species with H/S offsets for thermodynamic continuity across a phase boundary.
When a frozen nozzle expansion crosses a condensed-phase boundary (e.g. Al₂O₃ liquid → solid at the melting point), substituting the new phase species directly would introduce a discontinuity in enthalpy and entropy if the two species come from different databases with different reference states. This wrapper applies constant offsets
ΔhandΔsso thatenthalpyandentropyare continuous at the boundary temperature, regardless of database source.specific_heat_capacitydelegates unmodified to the base species, so the correct phase Cp (solid, not liquid) is used after the transition.- Parameters:
base – The replacement condensed species (e.g. solid Al₂O₃).
h_offset – Enthalpy offset Δh = H_old(T_tr) − H_base(T_tr) [J/mol].
s_offset – Entropy offset Δs = S_old(T_tr) − S_base(T_tr) [J/(mol·K)].
- specific_heat_capacity(T)
Returns the specific heat capacity in J/mol K
- enthalpy(T)
Computes the sensible enthalpy in J/mol
- entropy(T)
Computes entropy in J/mol K
- 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.
- __getitem__(key: str) Species
Return a species by exact canonical key.
- Parameters:
key – Canonical species ID, for example
"H2O_G".- Returns:
Species mapped to the exact key.
- Raises:
KeyError – If the exact key is not present.
- __contains__(key: str) bool
Return whether an exact canonical key exists in the database.
- Parameters:
key – Canonical species ID, for example
"H2O_G".- Returns:
Trueif the exact key exists, otherwiseFalse.
- 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.
- get_species_containing(element: str, enabled_databases: List[str] | None = None) List[Species]
Return unique species containing a specific element from enabled databases.
- find(formula: str, phase: str = 'G') Species
Find the best matching species across all loaded databases.
- condensed_phase_partner(species: Species, T: float) Species | None
Return the best condensed-phase partner for species valid at T.
Searches all loaded condensed species with the same element composition as species for one whose Cp polynomial evaluates to a finite positive value at T. Returns the highest-priority, widest-range match, or
Noneif no valid partner exists (including species itself).- Parameters:
species – The condensed species to replace (must have
condensed == 1).T – Target temperature [K].
- Returns:
A replacement
Speciesobject, orNoneif the current species is already valid or no valid partner exists.