exogibbs.thermo package

Submodules

exogibbs.thermo.stoichiometry module

Stoichiometry utilities: build a formula matrix from molecular formulae.

This module provides: - A parser that converts chemical formula strings (e.g., “H2O”, “C1O2”)

into dictionaries {element: coefficient}.

  • A function to build a formula (stoichiometric) matrix from a DataFrame containing molecular names.

Intended to be used as a low-level utility in ExoGibbs, decoupled from any specific chemical potential source (JANAF, CEA, GGchem, etc.).

exogibbs.thermo.stoichiometry.build_formula_matrix(df_molname: DataFrame, species_col: str = 'JANAF', *, element_order: Sequence[str] | None = None, sanitize: bool = True, species_names: str = 'raw') → Tuple[ndarray, List[str], List[str]] | Tuple[ndarray, List[str], List[str], List[str]]

Build a stoichiometric matrix A (elements x species) from df_molname.

Parameters:

  • species_names – {“raw”, “clean”, “both”}, default “raw”

  • return (Which species labels to)

  • "raw" (-) – return original strings (e.g., “C1N2(CNN)”)

  • "clean" (-) – return sanitized/normalized species (e.g., “C1N2”)

  • "both" (-) – return both (species_raw, species_clean)

Returns:

A, elements, species If species_names == “both”: A, elements, species_raw, species_clean

Return type:

If species_names in {“raw”, “clean”}

exogibbs.thermo.stoichiometry.parse_formula_with_charge(formula: str) → Dict[str, int]

Parse a chemical formula possibly carrying a net ionic charge.

Supports: - Normal neutral molecules: “H2O”, “CO2” - Ions with charge suffix: “H3O+”, “SO4-2”, “Na+” - JANAF-style electron species: “e-”, “e1-”, “e”, “e1” (all treated as electrons) -> represented as {“e-”: n_electrons}

NOTE: We do NOT add an extra charge-derived electron count for pure-electron species,

to avoid double-counting (the base already is electrons).

exogibbs.thermo.stoichiometry.parse_simple_formula(formula: str) → Dict[str, int]

Parse a simple chemical formula string into a dict of element counts.

Examples

“CH4” -> {“C”: 1, “H”: 4} “C1O2” -> {“C”: 1, “O”: 2} “H2O” -> {“H”: 2, “O”: 1}

Notes

  • Numbers are optional; default is 1.

  • Does not currently handle parentheses, charges, or hydrates.

exogibbs.thermo.stoichiometry.sanitize_formula(s: str) → str

Remove leading database markers and trailing parenthetical annotations.

Examples

“*CO2” -> “CO2” “C1N2(CNN)” -> “C1N2” # isomer/state tag removed “C1N2(NCN)” -> “C1N2” “H2O(g)” -> “H2O” “e1-” -> “e1-” # charge kept; handled by parse_formula_with_charge

Module contents