Replace Pyrometheus with MFC-owned thermochemistry generation

[sbryngelson]

Summary

MFC currently requires an external Pyrometheus release to change generated thermochemistry kernels. Move the Fortran generation path into MFC so thermodynamic, kinetic, transport, and device-annotation changes can be developed and reviewed with the solver. Remove Pyrometheus and JAX from the toolchain and replace their remaining mixing-layer initialization uses.

• Add a Fortran-only generator under toolchain/mfc/thermochem, adapted from Pyrometheus 1.1.1 with its MIT license retained. Preserve the m_thermochem interface, existing numerical formulas, precision options, and CPU/OpenACC/OpenMP generation. Cantera supplies mechanism data; Pymbolic and Mako handle build-time expressions and templates.
• Validate the supported ideal-gas/NASA7, Arrhenius, third-body, Troe, and Lindemann mechanism features before emission. Fingerprint mechanism contents and generator sources for build reuse.
• Share Cantera-only initial-profile generation across the temporal 2D, spatial 2D, and temporal 3D reacting mixing-layer examples, preserving their grid/file layouts and perturbations. Update cache identities and document the supported physics and initialization model.

Numerical behavior

The generated solver routines retain the previous formulas, with review fixes for working-precision selection and safe evaluation at zero reduced pressure. Mixed-storage builds use double-precision chemistry arguments. Single-precision literals now use sp throughout, so single-precision roundoff can differ from the former double-literal expressions. The default cold mixing-layer profiles still mix stream composition and enthalpy. All 16 selected chemistry regressions pass against the existing golden results; no golden files are changed.

The --hot initialization intentionally changes: a Cantera unity-Lewis counterflow flame is mapped by inlet-normalized Bilger mixture fraction onto the prescribed tanh layer, with temperature recovered at the mixed stream enthalpy. This replaces the former JAX flamelet solver's scalar-dissipation matching. Each example exposes a nominal flame_strain_rate (default 100/s). The documentation identifies this as an initial seed, not an identical replacement for the former steady flamelet calculation.

Validation

• Python 3.9.25 compatibility: fresh full toolchain installation with Pymbolic 2022.2 and Cantera 3.1.0, followed by 742 passing toolchain tests. The dependency lower bound permits Python 3.9-compatible Pymbolic releases.
• Full ./mfc.sh precheck -j 12 passed at commit time: formatting, spelling, toolchain lint and unit tests, source lint, documentation references, parameter documentation, and validation of all example cases.
• ./mfc.sh test --no-mpi -j 8 --only Chemistry: 16 passed, 0 failed against existing golden results, including substepped reactions, diffusion, isothermal walls, and all three mixing-layer cases.
• New compiled-kernel and initial-profile tests: 20 passed on Python 3.12 and 3.9. Compare four mechanisms against Cantera, including thermodynamics, energy/enthalpy inversion, production/destruction rates, elemental conservation, transport, single precision, directive compilation, mixed-storage interface compatibility, long species-name lookup, and zero-concentration falloff with floating-point exception traps. GNU compilation treats real narrowing-conversion warnings as errors.
• Existing case-validator and build-compatibility tests: 87 passed.
• Before the review corrections, generated Fortran matched Pyrometheus 1.1.1 for four mechanisms and six precision/offload combinations after normalizing formatting and removing an unused macro. The final generator intentionally differs in literal kinds, metadata length, and the guarded Troe logarithm; Cantera comparisons validate those corrections.
• NVIDIA A100 OpenACC device-kernel checks passed: double precision at the existing tolerance; single precision at a separately evaluated 1e-4 relative tolerance, with maximum scaled relative difference 3.13e-5 (the CPU test tolerance remains 3e-5). OpenMP directives were compiled and exercised on the host; OpenMP device execution, AMD hardware, and MPI execution were not tested in this validation.
• All three examples generated both cold and hot initial conditions in a fresh environment without Pyrometheus or JAX installed.
• Wheel packaging includes the Fortran template and license, with no Pyrometheus/JAX requirements. Formatting and documentation checks passed.

Review fixes

• Address all four inline Copilot findings: mixed-build working precision, full-length species metadata, precision-specific real constants, and removal of the unused direct SciPy dependency.
• Guard the Troe logarithm against eager Fortran merge evaluation at zero concentration and remove the stale diffusivity comment noted in the review summary.
• Fix the failing documentation link using a Doxygen page reference. Targeted rendering with Doxygen 1.16.1 confirms the link resolves to the generated thermochemistry page.

AI assistance

Implemented and tested with OpenAI Codex at the author's request. The author requested ownership of the generator inside MFC and replacement of the example-only flamelet dependency. The contribution-policy acknowledgement below is left for the human author to confirm.

Contribution Policy

We do not accept pull requests generated primarily by AI without genuine understanding or real-world usage context.

All contributions are expected to demonstrate:

• A clear understanding of the codebase
• Alignment with product direction
• Thoughtful reasoning behind changes
• Evidence of real-world usage or hands-on experience with the problem

If these expectations are not met, we would prefer to implement the changes ourselves rather than spend time reviewing low-effort submissions.

---

Acknowledgement

• I confirm this PR meets the above expectations and reflects my own understanding and real-world context.

---

PR template credit: junegunn

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical mixed-precision and species-name issues, plus moderate precision/domain-safety issues, remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2 · 1 · 1

Open (4)

• Fix mixed-precision real kind selection · New
• Prevent truncation of long species names · New
• Emit scalar-type-specific Fortran literals · New
• Remove unused mandatory scipy dependency · New

What changed in this PR

This PR moves thermochemistry generation into MFC and replaces Pyrometheus/JAX mixing-layer initialization with shared Cantera-based profiles.

Changes:

• Adds validated Fortran generation, fingerprinting, build integration, and tests.
• Adds shared cold/hot profile generation for reacting mixing-layer examples.
• Updates dependencies, licensing, documentation, and caching.

Unresolved findings:

• Critical: Mixed builds use the wrong precision kind, causing chemistry compilation failures.
• Critical: Species metadata truncates valid names longer than 12 characters.
• Moderate: Troe expressions may evaluate invalid logarithms for nonpositive pressure.
• Moderate: Hard-coded double-precision literals undermine the single-precision path.
• Nits: Update stale initialization documentation and remove the unused SciPy dependency.

File	Summary
toolchain/​pyproject.toml	Updates chemistry dependencies.
toolchain/​mfc/​thermochem/​module.f90.mako	Defines generated thermochemistry routines and metadata.
toolchain/​mfc/​thermochem/​LICENSE	Retains the Pyrometheus MIT license.
toolchain/​mfc/​thermochem/​fortran.py	Implements validation and Fortran emission.
toolchain/​mfc/​thermochem/​fingerprint.py	Adds mechanism and generator fingerprints.
toolchain/​mfc/​thermochem/​expressions.py	Generates symbolic thermochemistry expressions.
toolchain/​mfc/​thermochem/​__init__.py	Exposes the generator API.
toolchain/​mfc/​test_thermochem.py	Tests generated thermochemistry kernels.
toolchain/​mfc/​test_flamelet.py	Tests profile initialization invariants.
toolchain/​mfc/​run/​input.py	Integrates generation into builds.
toolchain/​mfc/​flamelet.py	Provides shared Cantera profile generation.
toolchain/​mfc/​common.py	Updates dependency documentation.
toolchain/​mfc/​build.py	Incorporates generator and mechanism fingerprints.
README.md	Updates the chemistry overview.
examples/​3D_reacting_mixing_layer/​README.md	Documents 3D initialization behavior.
examples/​3D_reacting_mixing_layer/​flamelet_ic.py	Uses shared 3D profile generation.
examples/​3D_reacting_mixing_layer/​case.py	Updates hot-mode configuration and caching.
examples/​2D_spatial_reacting_mixing_layer/​flamelet_ic.py	Uses shared spatial profile generation.
examples/​2D_spatial_reacting_mixing_layer/​case.py	Updates spatial hot-mode configuration and caching.
examples/​2D_reacting_mixing_layer/​flamelet_ic.py	Uses shared temporal profile generation.
examples/​2D_reacting_mixing_layer/​case.py	Updates temporal hot-mode configuration and caching.
docs/​documentation/​thermochemistry.md	Documents generation and initialization models.
docs/​documentation/​equations.md	Updates thermochemistry references.
docs/​documentation/​case.md	Documents supported generated chemistry.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.48%. Comparing base (dd7877d) to head (1605df9).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1915   +/-   ##
=======================================
  Coverage   61.48%   61.48%           
=======================================
  Files          86       86           
  Lines       22485    22485           
  Branches     3298     3298           
=======================================
  Hits        13826    13826           
  Misses       6206     6206           
  Partials     2453     2453           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.