Move PeleMP docs into PelePhysics (#449)

* Added initial documentation files * Mimic conf.py file from PeleC * Updating docs * Started adding more documentation and equations * Changed name of write_spray_ascii_file to write_ascii_files, added spray inputs and equations to documentation * Fix error in Equations.rst * Fix typo in documentation * Added more equations to the documentation * Fix doc typo * More documentation changes * Attempt at fixing table in documentation * More doc fixes * Missed a space * Configure equations * Updated documentation with more equations, removed unnecessary include statements in soot files * Aligned equations in documentation * Changed name of mean diameter input for distributions, added more spray inputs to documentation * More minor doc changes * Allow text in tables to wrap * Slight documentation changes * Updated documents to reflect latest change for boiling method * Added ChiSquared distribution, updated document to include latest injection routine inputs * More document changes * Trying something to see if it triggers the gh-pages workflow * Improve quality of injection image in docs * Attempt at using footnotes for bibliography in documentation * Wrong type of footnote code * Added a space next to footnote in call * Switched footnote to ref * Added jet names and checks for uniqueness, add routine to read jet checkpoint data, changed comments for SprayParticles.H to match doxygen format in case that ever gets implemented, removed SprayWalls.cpp file, added SprayIO.cpp file * Slight change to documentation * Add documentation about min parcels for jets * More injection documentation changes * More injection documentation stuff * Redid way liquid properties are specified in the input file and changed documentation and example problems to match, this will require changes in many different repos * Added a body force to the spray equations * Updated spray documentation with assumptions list * Tried adding single droplet verification results to documentation * Fix documentation bugs * More document changes * Another attempt * Redo verification images in documentation * Slight doc changes * Formulations are the same but the routines for multicomponent evaporation are simplified, removed gas phase molar fractions and inverse molecular weights from GasPhaseVals struct, updated documentation to reflect changes in code * More documentation improvements * Typo in doc equation * Start adding soot equations to documentation * Removed todos from soot files, added SootInput file * Fix soot input typos * Update documentation based on latest changes * movement * Moving the spray docs around * Reorg soot docs * white space cleanup * spelling --------- Co-authored-by: Landon Owen <[email protected]>
AMReX-Combustion · Dec 7, 2023 · 262ae76 · 262ae76
1 parent ed74fd6
commit 262ae76
Show file tree

Hide file tree

Showing 9 changed files with 552 additions and 3 deletions.
diff --git a/Docs/sphinx/Soot.rst b/Docs/sphinx/Soot.rst
@@ -0,0 +1,49 @@
+.. highlight:: rst
+
+.. _Soot:
+
+****
+Soot
+****
+
+Soot Equations
+==============
+
+Soot formation, growth, and oxidation is modeled using the hybrid-method of moments (HMOM) model developed by Mueller et al. [#mueller]_. This approach combines the numerical ease of the method of moments with interpolative closure (MOMIC) with the ability to capture the bimodal nature of the soot number density function (NDF) provided by the direct quadrature method of moments (DQMOM). :math:`M_{x,y}` is the moment of the soot NDF, where :math:`x` is the order for volume and :math:`y` for surface area; these terms are modeled according to
+
+.. math::
+   M_{x,y} = N_0 V_0^x S_0^y + \exp{\left(\sum_{r=0}^R \sum_{k = 0}^r a_{r,k} x^k y^{r-k}\right)},
+
+where :math:`R` is the order of the polynomial interpolation, :math:`a_{r,k}` are the interpolation coefficients, :math:`N_0` is the weight of the delta function, and :math:`V_0` and :math:`S_0` are the volume and surface area of the nucleated spherical soot particles, respectively. The location of the delta function is fixed at coordinates :math:`V_0` and :math:`S_0` and assumed to be equal to the nucleated particle size.
+The nucleated particle volume and surface area are fixed according to :math:`V_0 = 2 W_C C_{\rm{dimer}} / \rho_{\rm{soot}}` and :math:`S_0 = (36 \pi)^{1/3} V_0^{2/3}`, where :math:`W_C` is the molar mass of carbon, :math:`C_{\rm{dimer}}` is the average number of carbon atoms per dimer, and :math:`\rho_{\rm{soot}}` is the density of soot (:math:`\rho_{\rm{soot}} = 1800 {\text{ kg/m}}^3`). If the first-order polynomial interpolation of the moments (:math:`R=1`) is used, the above equation reduces to
+
+.. math::
+   M_{x,y} = N_0 V_0^x S_0^y + N_L V_L^x S_L^y,
+
+where :math:`V_L` and :math:`S_L` are the mean volume and surface area of the second mode (large particles). For first-order polynomial interpolation, four transport equations are solved: :math:`M_{0,0}` (number density), :math:`M_{1,0}` (volume fraction, also denoted as :math:`f_v`), :math:`M_{0,1}`, and :math:`N_0`.
+The governing equations for the soot moments are [#bisetti]_
+
+.. math::
+   \frac{\partial M_{x,y}}{\partial t} + \frac{\partial M_{x,y} \mathbf{u}_g}{\partial \mathbf{X}} = -\frac{\partial \boldsymbol{J}_{M}}{\partial \mathbf{X}} + \dot{M}_{x,y},
+
+where :math:`\boldsymbol{J}_{M}` is the soot mass flux and :math:`\dot{M}_{x,y}` is the soot source term.
+The current formulation ignores the molecular diffusion and thermophoretic effects of the soot, making the first term of the right-hand side zero.
+
+For more details regarding the HMOM model, users are encouraged to consult the references cited.
+
+Soot Flags and Inputs
+======================
+
+* In the ``GNUmakefile``, specify ``USE_SOOT = TRUE`` and ``NUM_SOOT_MOMENTS = N`` where ``N`` is the number of moments to be used in the solution, either 3 or 6.
+
+* Depending on the gas phase solver, soot solving functionality can be turned on in the input file using ``pelec.add_soot_src = 1`` or ``peleLM.do_soot_solve = 1``.
+
+* The chemistry model specified with ``Chemistry_model =`` in  ``GNUmakefile`` must contain the PAH inception species, as well as ``H2``, ``H``, ``OH``, ``H2O``, ``CO``, ``C2H2``, and ``O2``.
+
+* A PAH inception species must be provided in the input file using ``soot.incept_pah =``. Currently, only one of three inputs are accepted: ``A2``, ``A3``, or ``A4``; which correspond to naphthalene (C10H8), phenathrene (C14H10), or pyrene (C16H10).
+
+  * If the inception species is named something other than ``A#`` in the chemistry model, a different name can be specified using ``soot.pah_name =``. However, ``soot.incept_pah`` must be set to ``A2``, ``A3``, or ``A4``.
+
+.. [#mueller] "Hybrid Method of Moments for modeling soot formation and growth", M. E. Mueller and G. Blanquart and H. Pitsch, Comb. Flame, Vol. 156, No. 6, pp. 1143-1155 (2009)
+
+.. [#bisetti] "On the formation and early evolution of soot in turbulent nonpremixed flames", F. Bisetti and G. Blanquart and M. E. Mueller and H. Pitsch, Comb. Flame, Vol. 159, No. 1, pp. 317-335 (2012)
diff --git a/Docs/sphinx/Spray.rst b/Docs/sphinx/Spray.rst
diff --git a/Docs/sphinx/Visualization/abram_res.png b/Docs/sphinx/Visualization/abram_res.png
diff --git a/Docs/sphinx/Visualization/daif_res.png b/Docs/sphinx/Visualization/daif_res.png
diff --git a/Docs/sphinx/Visualization/inject_transform.png b/Docs/sphinx/Visualization/inject_transform.png
diff --git a/Docs/sphinx/Visualization/ton_res.png b/Docs/sphinx/Visualization/ton_res.png
diff --git a/Docs/sphinx/_static/mywrap.css b/Docs/sphinx/_static/mywrap.css
@@ -0,0 +1,6 @@
+
+
+/* override table no-wrap */
+.wy-table-responsive table td, .wy-table-responsive table th {
+white-space: inherit;
+}
diff --git a/Docs/sphinx/conf.py b/Docs/sphinx/conf.py
@@ -4,7 +4,7 @@
 master_doc = 'index'
 project = u'PelePhysics'
 copyright = u'AMReX Copyright (c) 2022, The Regents of the University of California, through Lawrence Berkeley National Laboratory and the Alliance for Sustainable Energy, LLC., through National Renewable Energy Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy).  All rights reserved.'
-author = u'J.B. Bell, M.S. Day, E. Motheau, D. Graves, M. Henry de Frahan, R.W. Grout, N. Wimer, B. Perry, L. Esclapez, M. Hassanaly, J. Rood'
+author = u'J.B. Bell, M.S. Day, E. Motheau, D. Graves, M. Henry de Frahan, R.W. Grout, N. Wimer, B. Perry, L. Esclapez, M. Hassanaly, J. Rood, L. Owen, B. Soriano, M. Arient'
 version = u'2022.10'
 release = u'2022.10'
 language = 'en'
@@ -15,18 +15,20 @@
 numfig_format = {'figure': '%s', 'table': '%s', 'code-block': '%s'}
 html_theme = 'sphinx_rtd_theme'
 htmlhelp_basename = 'PelePhysicsDoc'
+html_static_path = ['_static']
+html_css_files = ['mywrap.css']
 latex_elements = {
 }
 latex_documents = [
     (master_doc, 'PelePhysics.tex', u'PelePhysics Documentation',
      author, 'manual'),
 ]
 man_pages = [
-    (master_doc, 'pelec', u'PelePhysics Documentation',
+    (master_doc, 'pelephysics', u'PelePhysics Documentation',
      [author], 1)
 ]
 texinfo_documents = [
     (master_doc, 'PelePhysics', u'PelePhysics Documentation',
-     author, 'PelePhysics', 'One line description of project.',
+     author, 'PelePhysics', 'Documentation for PelePhysics.',
      'Miscellaneous'),
 ]
diff --git a/Docs/sphinx/index.rst b/Docs/sphinx/index.rst
@@ -37,6 +37,8 @@ point your web browser at the file ``${PELE_PHYSICS_DIR}/build/html/index.html``
    Transport.rst
    Thermodynamics.rst
    EOS.rst
+   Spray.rst
+   Soot.rst
    Utility.rst
    Tutorials.rst
    DeveloperGuide.rst