prometheus-equilibrium 0.1.0__tar.gz

prometheus_equilibrium-0.1.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run python -c \":*)",
+      "Bash(uv run:*)",
+      "Bash(python3 -)",
+      "Bash(python3 -c ':*)"
+    ]
+  }
+}

prometheus_equilibrium-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Require explicit owner review for deployment and packaging surfaces.
+/.github/workflows/ @1ckendall
+/pyproject.toml @1ckendall
+/uv.lock @1ckendall
+

prometheus_equilibrium-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint (black + isort)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --group dev
+      - run: uv run pre-commit run --all-files
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --group dev
+      - run: uv run pytest

prometheus_equilibrium-0.1.0/.github/workflows/python-publish-testpypi.yml

@@ -0,0 +1,95 @@
+name: Upload Python Package (TestPyPI)
+
+on:
+  release:
+    types: [prereleased]
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: "Release tag to publish (for example: v0.2.0rc1)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Resolve and validate release tag format
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          RELEASE_TAG_FROM_EVENT: ${{ github.event.release.tag_name }}
+          RELEASE_TAG_FROM_INPUT: ${{ github.event.inputs.release_tag }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import sys
+
+          event_name = os.environ.get("EVENT_NAME", "").strip()
+          if event_name == "release":
+              tag = os.environ.get("RELEASE_TAG_FROM_EVENT", "").strip()
+          else:
+              tag = os.environ.get("RELEASE_TAG_FROM_INPUT", "").strip()
+
+          if not tag:
+              print("No release tag provided.")
+              sys.exit(1)
+
+          if not re.fullmatch(r"v\d+\.\d+\.\d+(?:(a|b|rc)\d+)?", tag):
+              print(
+                  f"Invalid release tag '{tag}'. Expected vMAJOR.MINOR.PATCH "
+                  "(optionally with a/b/rc prerelease suffix)."
+              )
+              sys.exit(1)
+
+          print(f"Using release tag: {tag}")
+          with open(os.environ["GITHUB_ENV"], "a", encoding="utf-8") as fh:
+              fh.write(f"RELEASE_TAG={tag}\n")
+          PY
+
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ref: refs/tags/${{ env.RELEASE_TAG }}
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists-testpypi
+          path: dist/
+
+  testpypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+    environment:
+      name: testpypi
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists-testpypi
+          path: dist/
+
+      - name: Publish release distributions to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          repository-url: https://test.pypi.org/legacy/
+

prometheus_equilibrium-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,93 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: "Release tag to publish (for example: v0.2.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Resolve and validate release tag format
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          RELEASE_TAG_FROM_EVENT: ${{ github.event.release.tag_name }}
+          RELEASE_TAG_FROM_INPUT: ${{ github.event.inputs.release_tag }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import sys
+
+          event_name = os.environ.get("EVENT_NAME", "").strip()
+          if event_name == "release":
+              tag = os.environ.get("RELEASE_TAG_FROM_EVENT", "").strip()
+          else:
+              tag = os.environ.get("RELEASE_TAG_FROM_INPUT", "").strip()
+
+          if not tag:
+              print("No release tag provided.")
+              sys.exit(1)
+
+          if not re.fullmatch(r"v\d+\.\d+\.\d+(?:(a|b|rc)\d+)?", tag):
+              print(
+                  f"Invalid release tag '{tag}'. Expected vMAJOR.MINOR.PATCH "
+                  "(optionally with a/b/rc prerelease suffix)."
+              )
+              sys.exit(1)
+
+          print(f"Using release tag: {tag}")
+          with open(os.environ["GITHUB_ENV"], "a", encoding="utf-8") as fh:
+              fh.write(f"RELEASE_TAG={tag}\n")
+          PY
+
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ref: refs/tags/${{ env.RELEASE_TAG }}
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists-pypi
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+    environment:
+      name: publishers
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists-pypi
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

prometheus_equilibrium-0.1.0/.gitignore

@@ -0,0 +1,168 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+/.idea
+/Prometheus/JANAF_Cache
+
+# Benchmark output files
+benchmark_output.txt
+benchmark_db_output.txt
+benchmark_debug.log
+solver_debug.log

prometheus_equilibrium-0.1.0/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "pypropep"]
+	path = pypropep
+	url = https://github.com/jonnydyer/pypropep.git
+[submodule "cea"]
+	path = cea
+	url = https://github.com/nasa/cea.git

prometheus_equilibrium-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 25.1.0
+    hooks:
+      - id: black
+        language_version: python3.12
+
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        args: ["--profile", "black"]

prometheus_equilibrium-0.1.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    # Install the package itself so autodoc can import prometheus and its deps
+    - method: pip
+      path: .
+    # Doc-only dependencies (Sphinx theme etc.)
+    - requirements: docs/requirements.txt

prometheus_equilibrium-0.1.0/CLAUDE.md

@@ -0,0 +1,159 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Prometheus is an open-source combustion equilibrium solver for Python. It parses thermodynamic data from multiple sources (BURCAT/NASA-7, NASA-9, JANAF, CEA), builds a species database, and implements equilibrium solvers. The long-term goal is H₂/O₂ combustion validation against RocketCEA.
+
+## Development Commands
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+uv sync                                                    # Install dependencies
+uv run pytest                                              # Run the test suite
+uv run pytest tests/test_solver_gmcb.py                   # Run a single test file
+uv run pytest tests/test_solver_gmcb.py::test_hp_h2o2     # Run a single test
+uv run python tests/benchmark.py                           # Full solver vs. RocketCEA benchmark (170 cases)
+uv run python compare_rocketcea.py                         # G-McB vs. CEA single-case comparison
+uv run python prometheus_equilibrium/thermo_data/parsers/cea.py           # Re-convert CEA thermo.inp → cea_nasa9.json
+uv run prometheus-build-all-thermo                            # Re-generate all thermo databases in one command
+uv run prometheus-build-legacy all                            # Re-generate terra.json + afcesic.json (calibrated)
+uv run black prometheus_equilibrium/ tests/                               # Format code
+uv run isort prometheus_equilibrium/ tests/                               # Sort imports
+```
+
+`tests/benchmark.py` is the primary regression benchmark. It tests H2/O2, CH4/O2, N2H4/N2O4, and NH3/O2 across 11 O/F ratios and 5 pressures (170 cases) against RocketCEA and reports temperature error, mean molar mass, γ, Cp, and speed of sound.
+
+## Implementation Status
+
+Current state:
+
+- **Complete**: all thermodynamic data parsing; `Chemical`, `Species`, `JANAF`, `NASASevenCoeff`, `NASANineCoeff`, `SpeciesDatabase`; `Mixture` (all properties); `ElementMatrix` (all methods including `select_basis`); `EquilibriumProblem`; `EquilibriumSolution` (all derived properties); `GordonMcBrideSolver`; `MajorSpeciesSolver`.
+- **Not yet implemented**: `PEPSolver._tp_equilibrium` (raises `NotImplementedError`).
+
+## Architecture
+
+### Module layout
+
+```
+prometheus_equilibrium/
+  core/constants.py          — element molar masses, R, P° = 1e5 Pa
+  equilibrium/
+    species.py               — Chemical, Species, JANAF, NASASevenCoeff, NASANineCoeff, SpeciesDatabase
+    _thermo_kernels.py       — optional Numba JIT kernels for NASASevenCoeff/NASANineCoeff hot path
+    mixture.py               — Mixture (species list + mutable moles array)
+    element_matrix.py        — ElementMatrix (stoichiometric matrix A)
+    problem.py               — EquilibriumProblem, ProblemType enum
+    solution.py              — EquilibriumSolution dataclass + derived properties
+    solver.py                — EquilibriumSolver ABC, _ReactionAdjustmentBase, all three solver classes
+    performance.py           — PerformanceSolver (frozen + shifting nozzle expansion)
+  gui/                       — PySide6 desktop interface
+  propellants/
+    loader.py                — PropellantDatabase, SyntheticSpecies, TOML-based propellant definitions
+  thermo_data/
+    compiler.py              — thermo data compiler
+    parsers/                 — individual format parsers
+      burcat.py              — BURCAT/NASA-7 format
+      cea.py                 — CEA thermo.inp format (also converts thermo.inp → cea_nasa9.json)
+      janaf.py               — JANAF CSV format
+      shomate.py             — Shomate polynomial format
+      terra.py               — TERRA binary format
+      _common.py             — shared parsing utilities
+  tools/build_db.py          — parse raw .thr/.jnf files → nasa7.json, nasa9.json, janaf.csv
+  tools/build_legacy_thermo.py — parse TERRA/AFCESIC binaries + calibrate AFCESIC references
+tests/                       — pytest unit tests (mock species, no external DB dependency)
+tests/benchmark.py           — integration benchmark vs. RocketCEA
+```
+
+### Species and database
+
+`Chemical` → `Species` (abstract) → `JANAF`, `NASASevenCoeff`, `NASANineCoeff`. All species carry `elements: dict[str, float]`, `state`, `condensed` (0=gas, 1=condensed), and `alias`. Thermodynamic methods accept scalar float or `np.ndarray`; scalar calls take a fast path that skips NumPy overhead (and optionally uses Numba from `_thermo_kernels.py`).
+
+`SpeciesDatabase` loads up to five sources; call `load()` before use:
+
+```python
+db = SpeciesDatabase(
+    nasa7_path="prometheus_equilibrium/thermo_data/nasa7.json",
+    nasa9_path="prometheus_equilibrium/thermo_data/nasa9.json",
+    janaf_path="prometheus_equilibrium/thermo_data/janaf.csv",
+    cea_nasa9_path="prometheus_equilibrium/thermo_data/cea_nasa9.json",  # optional, CEA-sourced polynomials
+)
+db.load(include_janaf=False)  # benchmark.py uses include_janaf=False for stability
+```
+
+Priority when the same species ID appears in multiple sources (default): NASA-9 > NASA-7 > JANAF > TERRA > AFCESIC. This can be overridden via `SpeciesDatabase(..., source_priority=...)` or `db.load(source_priority=...)`. `get_species(elements, max_atoms=N)` returns all species whose element set is a subset of `elements`; `max_atoms` filters out large molecules (benchmark.py uses `max_atoms=20`).
+
+Canonical species ID: `{HillFormula}_{PHASE}` — e.g. `CO2_G`, `H2O_L`, `Al2O3_S`. Hill order: C first, H second, then alphabetical.
+
+### Equilibrium data flow
+
+```
+EquilibriumProblem  →  Solver.solve()  →  EquilibriumSolution
+      ↑                     ↑
+  reactants+products    ElementMatrix
+  (ProblemType.HP etc)  (from mixture.species)
+```
+
+`EquilibriumProblem` is purely declarative. `initial_mixture()` distributes moles equally across all gas-phase products as a starting guess. `b0_array(elements)` returns the element-abundance vector from reactants.
+
+`Mixture` always keeps gas species before condensed (enforced at construction). The solver mutates `mixture.moles` in-place during Newton iteration.
+
+`ElementMatrix` stores `A[i,k]` = atoms of element k in species i. Key methods: `element_abundances(n)` → `Aᵀ·n`, `select_basis(moles)` → Browne/Gram-Schmidt basis indices, `reaction_coefficients(basis)` → ν = C·B⁻¹ (used by Hybrid).
+
+### Solver hierarchy
+
+```
+EquilibriumSolver (ABC)
+  ├── _ReactionAdjustmentBase
+  │     ├── MajorSpeciesSolver  ← recommended default
+  │     └── PEPSolver     ← not yet implemented
+  └── GordonMcBrideSolver  ← reference / validation
+```
+
+**`MajorSpeciesSolver`** (96.5% convergence, 0.013% mean T error vs RocketCEA):
+- Inner loop (`_tp_equilibrium`): compressed Newton on major gas species only — matrix is always S×S regardless of species count. Minor species set analytically from element potentials π after each Newton step.
+- Outer loop (`_temperature_search`): Newton + interval-halving to satisfy energy constraint (HP/SP).
+- `_tp_equilibrium` returns a 4-tuple `(mixture, pi, n_iters, converged_bool)`; `_temperature_search` returns a 5-tuple `(mixture, T, pi, n_outer, converged_bool)`. `solve()` uses the returned `converged` flag directly — it does NOT recheck element residuals, as the "final exact update" in `_temperature_search` temporarily disturbs element balance.
+
+**`GordonMcBrideSolver`** (72.9% convergence, 0.82% mean T error — reference/validation):
+- Single Newton loop solving π, Δnc, Δln(n), Δln(T) simultaneously. Matrix size (S+nc+1)² for TP or (S+nc+2)² for HP/SP.
+- Stability fix: tracks `n_var` as the *previous iteration's* `n_gas_total`. This gives `G[idx_n, idx_n] = n_gas_total_current − n_gas_total_prev ≠ 0`, preventing runaway `delta_ln_n` on lean mixtures. `n_var` is stored before `_apply_update`, so the next iteration sees the change. `mu_gas` always uses the actual current `n_gas_total`, not `n_var`.
+
+**Shared** (`_ReactionAdjustmentBase`): `_temperature_search`, `_split_major_minor`, `_manage_condensed_phases`, `_initialise` (validates, filters ionic species, removes products not coverable from reactant elements).
+
+### Key design constants
+
+- All temperatures in Kelvin, energies in J/mol, pressures in Pa (P° = 1e5 Pa = 1 bar)
+- `_LOG_CONC_TOL = math.log(1e-8)` — concentration floor; species with `ln(nⱼ) - ln(n) ≤ _LOG_CONC_TOL` are zeroed
+- Convergence tolerance: `5e-6` (step size criterion) for both solvers
+- `_ReactionAdjustmentBase.__init__` defaults: `max_iterations=50`, `tolerance=5e-6`, `minor_threshold=1e-2`
+
+### Reference material and submodules
+
+- `cea/` — git submodule: NASA CEA Fortran source (Gordon-McBride reference implementation, especially `cea/source/`)
+- `pypropep/` — git submodule: C implementation of Propep (PEP reference); uses NASA-format thermo data — **not relevant to AFCESIC**
+- `pep-for-zos/` — git submodule: historical PEP Fortran source for z/OS (1970s Naval Weapons Center origin)
+- `terra/` — external equilibrium solver (BASIC source + compiled binaries); not integrated into Prometheus
+- `papers/` — Villars-Browne PEP paper and NASA RP-1311
+
+We use Google-style docstrings throughout. **All new docstrings must use Google style** (`Args:`, `Returns:`, `Raises:`, `Attributes:`, `Example:`, `Note:` sections with 4-space-indented content). NumPy/reStructuredText docstring styles are not used in this project.
+
+## Documentation
+
+Sphinx docs live in `docs/`. Build with:
+
+```bash
+uv run --group docs sphinx-build -b html docs docs/_build/html
+# or, on Unix/macOS:
+cd docs && make html
+```
+
+The docs use `sphinx.ext.autodoc` + `sphinx.ext.autosummary` (with `:recursive:`) to automatically discover and document every module, class, and function in `prometheus_equilibrium/`. The Napoleon extension translates Google-style docstrings. Theme: `renku` (package: `renku-sphinx-theme`).
+
+The `docs/` directory structure:
+- `index.rst` — landing page + quick-start
+- `thermo/` — thermodynamic database guide and TERRA integration notes
+- `solver_comparison.rst` — algorithm analysis for MajorSpeciesSolver, G-McB, PEP
+- `api/` — auto-generated API reference stubs