<html xmlns="http://www.w3.org/1999/xhtml">

<script async src="https://www.googletagmanager.com/gtag/js?id=G-SY496B9L99"></script>

window.dataLayer = window.dataLayer || [];

function gtag(){dataLayer.push(arguments);}

gtag('js', new Date());

gtag('config', 'G-SY496B9L99');

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>

<meta http-equiv="X-UA-Compatible" content="IE=9"/>

<meta name="generator" content="Doxygen 1.16.1"/>

<meta name="viewport" content="width=device-width, initial-scale=1"/>

<title>MFC: Thermochemistry implementation</title>

<meta name="description" content="Thermochemistry implementation — MFC documentation. Open-source exascale multiphase flow solver." />

<meta name="keywords" content="exascale, fluid dynamics, cfd, computational fluid dynamics, compressible, hpc, bryngelson, colonius, subgrid, multiphase, frontier, summit, el capitan, aurora, amd gpu, gpu, nvidia"/>

<link href="tabs.css" rel="stylesheet" type="text/css"/>

<script type="text/javascript" src="jquery.js"></script>

<script type="text/javascript" src="dynsections.js"></script>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<script type="text/javascript" src="navtreedata.js"></script>

<script type="text/javascript" src="navtree.js"></script>

<script type="text/javascript" src="cookie.js"></script>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<script type="text/javascript" src="search/searchdata.js"></script>

<script type="text/javascript" src="search/search.js"></script>

<script type="text/x-mathjax-config">

extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],

jax: ["input/TeX","output/HTML-CSS"],

extensions: ["tex2jax.js"],

jax: ["input/TeX", "output/HTML-CSS"],

tex2jax: {

inlineMath: [ ['$', '$'], ["\\(","\\)"] ],

displayMath: [ ['$$','$$'], ["\\[","\\]"] ],

processEscapes: true,

ignoreClass: "line" // Ignore code blocks: https://web.archive.org/web/20120430100225/http://www.mathjax.org/docs/1.1/options/tex2jax.html

},

"HTML-CSS": {

fonts: ["TeX"]

}

<script type="text/javascript" async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js"></script>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

<link rel="shortcut icon" href="icon.ico" type="image/x-icon" />

<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>

<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>

<link href="custom.css" rel="stylesheet" type="text/css"/>

<div id="top"><!-- do not remove this div, it is closed by doxygen! -->

<div id="titlearea">

<table cellspacing="0" cellpadding="0">

<tbody>

<tr style="height: 56px;">

<td id="projectlogo"><img alt="Logo" src="icon.ico"/></td>

<td id="projectalign" style="padding-left: 0.5em;">

<div id="projectname">MFC

</div>

<div id="projectbrief">Exascale flow solver</div>

</td>

</tr>

</tbody>

document.addEventListener('DOMContentLoaded', function() {

var nav = document.createElement('div');

nav.id = 'mfc-nav';

var items = [

['../documentation/index.html', 'documentation', 'User Guide'],

['../api/index.html', 'api', 'API Documentation']

];

var path = window.location.pathname;

var apiPaths = ['/api/', '/pre_process/', '/simulation/', '/post_process/'];

for (var i = 0; i < items.length; i++) {

var a = document.createElement('a');

a.href = items[i][0];

a.textContent = items[i][2];

if (items[i][1] === 'api') {

for (var j = 0; j < apiPaths.length; j++) {

if (path.indexOf(apiPaths[j]) !== -1) { a.className = 'active'; break; }

}

} else {

if (path.indexOf('/' + items[i][1] + '/') !== -1) a.className = 'active';

}

nav.appendChild(a);

}

var sideNav = document.getElementById('side-nav');

if (sideNav) sideNav.insertBefore(nav, sideNav.firstChild);

<script type="text/javascript">

var searchBox = new SearchBox("searchBox", "search/",'.html');

<script type="text/javascript">

$(function() { codefold.init(); });

<script type="text/javascript" src="menudata.js"></script>

<script type="text/javascript" src="menu.js"></script>

<script type="text/javascript">

$(function() {

initMenu('',true,false,'search.php','Search',true);

$(function() { init_search(); });

<div id="main-nav"></div>

<div id="side-nav" class="ui-resizable side-nav-resizable">

<div id="nav-tree">

<div id="nav-tree-contents">

<div id="nav-sync" class="sync"></div>

</div>

</div>

<div id="splitbar" style="-moz-user-select:none;"

class="ui-resizable-handle">

</div>

<script type="text/javascript">

$(function(){initNavTree('thermochemistry.html','',''); });

<div id="container">

<div id="doc-content">

<div id="MSearchSelectWindow"

onmouseover="return searchBox.OnSearchSelectShow()"

onmouseout="return searchBox.OnSearchSelectHide()"

onkeydown="return searchBox.OnSearchSelectKey(event)">

<div id="MSearchResultsWindow">

<div id="MSearchResults">

<div class="SRPage">

<div id="SRIndex">

<div id="SRResults"></div>

<div class="SRStatus" id="Loading">Loading...</div>

<div class="SRStatus" id="Searching">Searching...</div>

<div class="SRStatus" id="NoMatches">No Matches</div>

<div><div class="header">

<div class="headertitle"><div class="title">Thermochemistry implementation </div></div>

<div class="contents">

<div class="textblock"><h1 class="doxsection"><a class="anchor" id="autotoc_md616"></a>

Mechanism generation</h1>

<p>MFC owns the Fortran thermochemistry generator in <span class="tt">toolchain/mfc/thermochem/</span>. Cantera loads a mechanism, and <span class="tt">generate_fortran</span> produces the Fypp source <span class="tt">m_thermochem.fpp</span> in the target's build staging directory. The existing CMake build compiles that module into MFC. Neither Cantera nor Python is called inside the flow solver. Pyrometheus and JAX are not installation or runtime requirements.</p>

<p>The implementation was adapted from the MIT-licensed Pyrometheus 1.1.1 Fortran generator. Its license is retained in <span class="tt">toolchain/mfc/thermochem/LICENSE</span>. Changes are made directly in MFC; no external fork or upstream generator release is required. Pymbolic constructs scalar expressions during generation and Mako renders the Fortran template. Neither is a runtime solver dependency.</p>

<table class="markdownTable">

<tr class="markdownTableHead">

<th class="markdownTableHeadNone">File </th><th class="markdownTableHeadNone">Responsibility </th></tr>

<tr class="markdownTableRowOdd">

<td class="markdownTableBodyNone"><span class="tt">thermochem/expressions.py</span> </td><td class="markdownTableBodyNone">NASA7, reaction-rate, equilibrium and transport expressions </td></tr>

<tr class="markdownTableRowEven">

<td class="markdownTableBodyNone"><span class="tt">thermochem/fortran.py</span> </td><td class="markdownTableBodyNone">Supported-feature checks, expression formatting and module generation </td></tr>

<tr class="markdownTableRowOdd">

<td class="markdownTableBodyNone"><span class="tt">thermochem/module.fpp.mako</span> </td><td class="markdownTableBodyNone">Fortran interface and numerical routines </td></tr>

<tr class="markdownTableRowEven">

<td class="markdownTableBodyNone"><span class="tt">thermochem/surface.py</span>, <span class="tt">surface.fpp.mako</span> </td><td class="markdownTableBodyNone">Heterogeneous surface-chemistry checks and module </td></tr>

<tr class="markdownTableRowOdd">

<td class="markdownTableBodyNone"><span class="tt">thermochem/fingerprint.py</span> </td><td class="markdownTableBodyNone">Mechanism and generator content identities for build reuse </td></tr>

<tr class="markdownTableRowEven">

<td class="markdownTableBodyNone"><span class="tt">run/input.py</span> </td><td class="markdownTableBodyNone">Mechanism resolution and generation for each target </td></tr>

<p>The generator supports ideal-gas mixtures with NASA7 thermodynamics, elementary and third-body Arrhenius reactions, and Troe or Lindemann falloff reactions. It requires gas transport data and positive Arrhenius pre-exponential factors. Other rate types, custom reaction orders and other thermodynamic models are rejected before emission with a species or reaction identifier. Cantera's ability to parse a mechanism does not imply that the generator supports every feature in it.</p>

<p>The generated module provides species metadata, caloric and ideal-gas properties, temperature inversion, net production rates, fused creation/destruction rates, mixture viscosity and thermal conductivity, and species diffusivities. Routines shaped for MFC's callers return what a call site needs from one state: <span class="tt">get_mixture_caloric_state</span> (species cp/R and mixture cp, cv and energy from one pass over the NASA7 fits), <span class="tt">get_mixavg_transport_state</span> (molecular weight, mole fractions, mixture-averaged diffusivities and conductivity, sharing the composition work) and <span class="tt">get_species_enthalpies_mass</span>. They live in the companion module <span class="tt">m_thermochem_state</span>, generated into the same file, so <span class="tt">m_thermochem</span>, which nearly every MFC file reads, is unchanged; nvfortran 24.7 and older crash compiling unrelated files when it grows by these routines. They reuse the separate routines' arithmetic; optimized builds may still differ from separate calls at roundoff. MFC still owns reaction time integration, including alpha-QSS, and spatial transport discretization. The module follows MFC's source conventions: it uses <span class="tt">wp</span> from <span class="tt">m_precision_select</span> and marks device routines with <span class="tt">$:GPU_ROUTINE</span>, so one generated source serves every precision and offload configuration and compiler-specific directive handling stays in MFC's macros. Nonchemistry builds retain the existing dummy <span class="tt">h2o2.yaml</span> module to satisfy the shared Fortran interfaces.</p>

<p>The initial ownership change preserves the previous numerical formulas. In particular, the pure-species diffusion limit retains the self-diffusion coefficient; Cantera's mixture diffusion query may return zero for that degenerate state. Temperature inversion also retains the existing Newton iteration and tolerance. Real constants use the selected working precision: single for single-precision builds and double for default and mixed-storage builds. Single-precision results can therefore differ in roundoff from the former double-literal expressions. Troe falloff guards the logarithm at zero reduced pressure, including when a compiler evaluates both arguments of a Fortran <span class="tt">merge</span> expression.</p>

<h1 class="doxsection"><a class="anchor" id="autotoc_md617"></a>

Surface chemistry</h1>

<p>Reacting immersed boundaries (<span class="tt">surface_cantera_file</span>, <span class="tt">surface_phase</span>) also use <span class="tt">generate_surface_fortran</span>, which writes <span class="tt">m_surface_thermochem.fpp</span> for the simulation target. It shares the gas generator's rate-coefficient and NASA7 expressions and its <span class="tt">wp</span>/<span class="tt">$:GPU_ROUTINE</span> conventions, and calls <span class="tt">m_thermochem</span> for concentrations and gas enthalpies. The module provides the gas-species net production rates and the heat released by the surface reactions; without a surface mechanism both return zero.</p>

<p>The supported model is a bulk solid reacting with gas species: irreversible (interface-)Arrhenius reactions whose rates depend on gas concentrations, with explicit orders allowed. Adjacent bulk phases, such as graphite, have unit activity and enter the reaction enthalpy through their NASA7 thermodynamics at the reference pressure. Sticking, Blowers-Masel and coverage-dependent rates, reversible surface reactions, and surface-site species are rejected before emission.</p>

<h1 class="doxsection"><a class="anchor" id="autotoc_md618"></a>

Mixing-layer initial conditions</h1>

<p>The temporal 2D, spatial 2D and temporal 3D reacting mixing-layer examples share <span class="tt">toolchain/mfc/flamelet.py</span>. Their local <span class="tt">flamelet_ic.py</span> files retain grid generation, coordinate conventions, perturbations and MFC input-file layouts.</p>

<p>The default cold profile uses the prescribed hyperbolic-tangent mixture fraction, linearly mixed stream mass fractions and specific enthalpy, and Cantera's HP temperature recovery. Velocity is interpolated between the prescribed stream velocities. Density follows the ideal-gas mixture equation of state.</p>

<p>With <span class="tt">--hot</span>, Cantera solves a counterflow diffusion flame using unity-Lewis transport. The counterflow width is ten vorticity thicknesses. Each inlet velocity is <span class="tt">flame_strain_rate * width / 2</span>, with mass flux determined by its stream density; <span class="tt">flame_strain_rate</span> is a nominal inlet strain parameter in inverse seconds, not the computed local strain. Its default is 100/s and is set in each example's <span class="tt">case.py</span>. The solution is tabulated against Bilger mixture fraction normalized to the inlet compositions, then mapped to the mixing layer's prescribed tanh profile. Temperature is recovered at the linearly mixed stream enthalpy. Extinguished flames or invalid profiles fail explicitly instead of silently producing a cold initialization.</p>

<p>This hot initialization is a counterflow-based seed for the evolving MFC flow. It replaces the former JAX flamelet solver and its iterative scalar-dissipation matching; it is not numerically identical to that initialization or a steady solution of the mixing-layer equations. Changes to the initialization method and mechanism invalidate the example caches. No precomputed flame data or optional Pyrometheus installation is required.</p>

<h1 class="doxsection"><a class="anchor" id="autotoc_md619"></a>

Validation</h1>

<p>After bootstrapping the toolchain, run:</p>

<div class="fragment"><div class="line">PYTHONPATH=toolchain build/venv/bin/pytest -q \</div>

<div class="line"> toolchain/mfc/test_thermochem.py toolchain/mfc/test_flamelet.py \</div>

<div class="line"> toolchain/mfc/test_surface_chemistry_codegen.py</div>

<div class="line">./mfc.sh test --no-mpi -j 8 --only Chemistry</div>

</div><!-- fragment --><p>The kernel tests compile generated Fortran with GNU Fortran and compare with Cantera for <span class="tt">h2o2.yaml</span>, <span class="tt">gri30.yaml</span>, the bundled San Diego mechanism, and the hydrogen/xenon mechanism. They cover thermodynamics, energy/enthalpy inversion, reaction production and destruction, elemental conservation, transport, single precision, mixed-storage working-precision compatibility, long species names, zero-concentration falloff with floating-point exception traps, and compilation with OpenACC and OpenMP directives. They run the generated source through Fypp with MFC's macros, as the build does. The directive tests execute on the host; they do not validate GPU offload on accelerator hardware.</p>

<p>The surface tests compile the example carbon mechanism's module and compare gas production rates and reaction heat with Cantera's interface kinetics, check the gasified carbon mass balance, and cover each rejected rate law.</p>

<p>Initialization tests check stream limits, normalization, elemental composition, enthalpy, density and a burning hot profile for both mixing-layer mechanisms.</p>

<div style="text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;">Page last updated: 2026-10-08</div> </div></div><!-- contents -->

<div id="page-nav" class="page-nav-panel">

<div id="page-nav-resize-handle"></div>

<div id="page-nav-tree">

<div id="page-nav-contents">

<div id="nav-path" class="navpath">

<ul></ul>