ExoGibbs

Differentiable Thermochemical Equilibrium, powered by JAX.

The optimization scheme is based on the Lagrange multiplier, similar to NASA/CEA algorithm. The terminology follows Smith and Missen, Chemical Reaction Equilibrium Analysis (1983, Wiley-Interscience).

Basic Use

from jax import config
config.update("jax_enable_x64", True)

from exogibbs.api.gas import EquilibriumOptions, solve_profile
from exogibbs.presets.ykb4 import chemsetup

chem = chemsetup()
opts = EquilibriumOptions(epsilon_crit=1e-15, max_iter=1000)
res = solve_profile(
    chem,
    temperature_profile,
    pressure_profile,
    chem.element_vector_reference,
    Pref=1.0,
    options=opts,
)
nk_result = res.x #mixing ratio

presets

• ykb4: number of species: 160 elements: 12
• fastchem: number of species: 523 elements: 28
• fastchem4: number of gas species: 422 elements: 28
• fastchem4_cond: number of condensate species: 219

v0.6 release highlights

Version 0.6 strengthens condensate equilibrium with canonical amount-gauge normalization, stricter zero-barrier closure and physical audits, and stable solver shapes across profile support changes. Rainout and custom/grid initializers now follow a consistent caller-gauge contract. Budget and rainout diagnostic schemas advance to v2.

This release also adds validation examples for KCl/Na2S condensation, forsterite-enstatite competition, and Fe-FeS local equilibrium versus sequential rainout, together with timing tools for the documented examples and repeated full-catalog L-dwarf profiles.

See the condensate solver guide, the profile and rainout guide, and the documented example benchmarks.

v0.5 release highlights

Version 0.5 adds a custom VJP for fixed-support condensate equilibrium, opt-in bottom-to-top rainout profiles, condensate grid initialization, and end-to-end ExoJAX/NumPyro NUTS examples. The differentiable contract is local to a fixed condensate support; support changes and rainout propagation remain outside automatic differentiation.

See the condensate solver guide, the profile and rainout guide, and the Ito et al. (2025) validation.

v0.4 validation milestone

An independent four-point comparison with FastChem 4.0.3 found identical major-gas species sets at 0.1 bar and 1200, 1400, 1600, and 1800 K, with convergence and elemental-budget closure in both solvers. This supports the scoped v0.4 major-gas milestone for the gas phase of the production gas-plus-condensate solver. Detailed condensate phase selection was outside the scoped v0.4 claim.

See the v0.4 FastChem validation demo and the technical comparison protocol. Readable Python plots are provided for gas-only and gas-plus-condensate comparisons. The comparison example lineage also records the restored grid-initializer, analytical H and H/C/O, and historical YK B4 regression demonstrations without treating them as extra v0.4 acceptance points.

Documentation

Install the pinned documentation dependencies and build the HTML pages with:

python -m pip install -e ".[docs]"
./update_doc.sh

The generated API reference and HTML output are written under documents/ and are intentionally excluded from version control. CI also publishes the HTML output as the Documentation HTML artifact.

ExoGibbs is designed to plug into ExoJAX and enable gradient-based equilibrium retrievals. It is still in a beta stage, so please use it at your own risk.

This package bundles equilibrium-constant and elemental-abundance data from FastChem v3.1.3 and v4.0.3 in the fastchem and fastchem4 presets. FastChem is distributed under the GNU General Public License v3 (GPLv3). Accordingly, ExoGibbs is also distributed under the GPLv3 license.