GCM for liquid fuel properties in spray (#615)

* Add GCM functions

* Add temperature unit conversions

* Parse GCM inputs, add mw to liqprops

* Forgot to add changes to SpraySetup

* Fix Y2X function

* Add sigma=-1 so GCM compiles, need to figure out logic for spray breakup init

* Parse for family, add template to getInpVal

* Generalize requirements for BreakupSpray model during initialization

* remove unwanted spaces in CONTRIBUTING.md

* Formatting

* Update plots in docs to show diff between LiqPropsType

* Add GCM to docs

* Update spray validation in docs

* Fix typo in docs

* Resolve clang-tidy errors

* Overload rho_mix

* Add base struct for LiqProps, use gas-phase mw when SPRAY_FUEL_NUM <= NUM_SPECIES

* More clang-tidy fixes

* Fix spelling error in Docs/sphinx/Spray.rst

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Add many const, SprayUnits::, and all other required changes

* Const in calcBoilT function

* Fix static_assert

* Reorg of SprayProps

---------

Co-authored-by: Bruce Perry <Bruce.Perry@nrel.gov>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

CONTRIBUTING.md

@@ -11,34 +11,37 @@ Follow [GitHub directions](https://docs.github.com/en/free-pro-team@latest/githu
 to fork *PelePhysics* main repo on your GitHub account, and use a recursive `git clone` to get your fork of *PelePhysics* and its dependencies.
 
 Then step into the *PelePhysics* folder and add the main *PelePhysics* repository as the `upstream` remote in order to keep track of the main repo :
-
-       git add remote upstream https://github.com/AMReX-Combustion/PelePhysics
+~~~
+git add remote upstream https://github.com/AMReX-Combustion/PelePhysics
+~~~
 
 At any point, you can update the `development` branch of your local repository with changes implemented in the main *PelePhysics* repo by pulling from `upstream` :
-
-        git checkout development
-        git pull upstream development
+~~~
+git checkout development
+git pull upstream development
+~~~
 
 We recommend setting your development branch to track the upstream one instead of your fork:
-
-        git branch -u upstream/development
+~~~
+git branch -u upstream/development
+~~~
 
 You are now free to modify your own fork of *PelePhysics*. To add a new feature to *PelePhysics*, the procedure is:
 
 1. Create a branch for the new feature from the `development` branch (locally) :
-
-        git checkout development
-        git checkout -b AmazingNewFeature
-
+   ~~~
+   git checkout development
+   git checkout -b AmazingNewFeature
+   ~~~
 2. and commit your changes to your local repo :
-
-        git commit -m "Developed AmazingNewFeature"
-
+   ~~~
+   git commit -m "Developed AmazingNewFeature"
+   ~~~
 3. Alongside your development, regularly merge changes from the main repo `development` branch into your `AmazingNewFeature` branch,
 fix any conflicts, and push your changes to your GitHub fork :
-
-        git push -u origin AmazingNewFeature
-
+   ~~~
+   git push -u origin AmazingNewFeature
+   ~~~
 4. When you are ready to propose your new feature/improvement/bug fix to the main *PelePhysics* repo, reiterate Step 3 and submit a PR through the GitHub page from your fork onto the `development` branch of the main repo:
 
  - Click on the ``compare & pull request`` button to start your PR.
@@ -56,8 +59,9 @@ If you want to fix a bug, make a small pull request that only fixes a bug.
 ## PelePhysics Coding Style Guide
 
 Source code files can be automatically formatted to adhere to the appropriate formatting rules using ``clang-format``. To format all files, use the command:
-
-        find Source Testing \( -name "*.cpp" -o -name "*.H" \) -exec clang-format -i {} +
+~~~
+find Source Testing \( -name "*.cpp" -o -name "*.H" \) -exec clang-format -i {} +
+~~~
 
 from within the PelePhysics base directory. You can also format files individually using ``clang-format -i /path/to/file``. Adherence to this format is checked for all PRs.
 

Docs/sphinx/Spray.rst

@@ -22,11 +22,17 @@ Firstly, spray modeling relies on the following assumptions:
 
 * The radiation, Soret, and Dufour effects are neglected
 
-Secondly, accurate spray modeling requires accurate thermophysical and transport properties for both the gas and liquid phases. The gas phase properties are computed using information from the mechanism files in `PelePhysics` while the liquid-phase properties are provided by the user. 
-The required inputs and the forms of the component-level and mixture-level liquid-phase properties are discussed in detail in the :ref:`Liquid Spray Properties <SprayLiquidProperties>` section.
+Secondly, accurate spray modeling depends on accurate thermophysical and transport properties for both the gas and liquid phases.  
+Gas-phase properties are obtained directly from the mechanism files in `PelePhysics`, while liquid-phase properties are derived from user-provided inputs for each liquid fuel species.  
+Currently, two approaches are available for estimating liquid fuel properties:
 
-The evaporation models follow the work by Abramzon and Sirignano [#abram]_ and the multicomponent evaporation is based on work by Tonini. [#ton]_ Details regarding the energy balance are provided in Ge et al. [#Ge]_
+* The original PeleMP [#owen]_ method, which utilizes a combination of constant values and temperature-based fits.
+
+* A group contribution method (GCM) based on the work of Constantinou & Gani [#gani94]_ [#gani95]_ and Govindaraju & Ihme [#govindaraju]_, previously implemented and validated in `FuelLib <https://github.com/nrel/fuellib>`_. 
+
+Further details on the required inputs, as well as the formulations of both component-level and mixture-level liquid-phase properties, are provided in the :ref:`Liquid Spray Properties <SprayLiquidProperties>` section.
 
+The evaporation models follow the work by Abramzon and Sirignano [#abram]_ and the multicomponent evaporation is based on work by Tonini. [#ton]_ Details regarding the energy balance are provided in Ge et al. [#Ge]_
 The subscript notation for this section is: :math:`d` relates to the liquid droplet, :math:`v` relates to the vapor state that is in equilibrium with the liquid and gas phase, :math:`L` relates to the liquid phase, and :math:`g` relates to the gas phase. The subscript :math:`r` relates to the reference state with which to approximate the thermophysical and transport properties. This reference state is assumed to be in the evaporating film that surrounds the droplet state and is approximated as
 
 .. math::
@@ -239,7 +245,7 @@ The procedure is as follows for updating the spray droplet:
 
    For such cases, fully three-dimensional simulations are recommended.
 
-   
+
 Spray Flags and Inputs
 ======================
 
@@ -292,13 +298,35 @@ Spray Flags and Inputs
 Liquid Spray Properties
 -----------------------
 
-* The units for `PeleLM` and `PeleLMeX` are MKS while the units for `PeleC` are CGS. This is the same for the spray inputs. E.g. when running a spray simulation coupled with `PeleC`, the units for ``particles.fuel_cp`` must be in erg/g.
+The required inputs and corresponding correlations for the original *PeleMP* [#owen]_ 
+and the *FuelLib-based GCM* are outlined in the subsections below. Please note the following details:  
+
+**Units:**  
+
+* `PeleLM` and `PeleLMeX` use MKS units, while `PeleC` uses CGS units. The Spray inputs follow the same convention.  
 
-* There are many required ``particles.`` flags in the input file for liquid fuel properties. For demonstration purposes, 2 liquid species of ``NC7H16`` and ``NC10H22`` will be used.
+* For example, when running a spray simulation coupled with `PeleC`, the values for ``particles.fuel_cp`` must be provided in erg/g.  
 
-  * Many values must be specified on a per-species basis. Following the current example, one would have to specify ``particles.NC7H16_crit_temp = 540.`` and ``particles.NC10H22_crit_temp = 617.`` to set a critical temperature of 540 K for ``NC7H16`` and 617 K for ``NC10H22``.
+**Input flags:**  
 
-* The following table lists other inputs related to ``particles.``, where ``SP`` will refer to a fuel species name
+* A number of ``particles.`` flags are required in the input file to define liquid fuel properties.  
+
+* For demonstration purposes, two liquid species will be used: ``NC7H16`` and ``NC10H22``.  
+
+* Many values must be specified on a per-species basis. In this example, one would need to specify:  
+   
+   - ``particles.NC7H16_crit_temp = 540`` critical temperature of 540 K for ``NC7H16``  
+   
+   - ``particles.NC10H22_crit_temp = 617`` critical temperatures of 617 K for ``NC10H22``.
+
+**Additional method-specific inputs:**  
+   
+   * The following tables list other required inputs related to ``particles.``,  where ``SP`` refers to a given fuel species name.  
+
+The source code for the liquid spray properties can be found in ``SprayProperties.H``.
+
+PeleMP Implementation
+^^^^^^^^^^^^^^^^^^^^^
 
 .. table::
 
@@ -322,10 +350,13 @@ Liquid Spray Properties
    |                       |                               |             |                   |
    +-----------------------+-------------------------------+-------------+-------------------+
    |``SP_lambda``          |Liquid thermal conductivity    |No           |0.                 |
-   |                       |(currently unused)             |             |                   |
+   |                       |                               |             |                   |
    +-----------------------+-------------------------------+-------------+-------------------+
    |``SP_mu``              |Liquid dynamic viscosity       |No           |0.                 |
-   |                       |(currently unused)             |             |                   |
+   |                       |                               |             |                   |
+   +-----------------------+-------------------------------+-------------+-------------------+
+   |``SP_sigma``           |Liquid surface tension         |No           |0.                 |
+   |                       |                               |             |                   |
    +-----------------------+-------------------------------+-------------+-------------------+
 
 
@@ -359,6 +390,53 @@ Liquid Spray Properties
   If only a single value is provided, :math:`a_n` is assigned to that value and the other coefficients are set to zero, effectively using a constant value for the parameters.
 
 
+FuelLib-Based GCM
+^^^^^^^^^^^^^^^^^
+
+Currently the *GCM* approach of estimating liquid fuel properties is only available in PeleLMeX and requires:
+
+* Setting the compile-time flag ``SPRAY_GCM=TRUE`` in the case's ``GNUmakefile``
+
+* Generating a liquid-fuel-specific GCM input file from FuelLib, and copying the input file into the case directory.
+   
+   - The process for generating this input file is provided in FuelLib's tutorial: `Exporting GCM Properties for Pele <https://nrel.github.io/FuelLib/tutorials.html#exporting-gcm-properties-for-pele>`_.
+
+   - An example of using the GCM in Pele is provided in ``PeleLMeX/Exec/RegTests/SingleDropEvap``.
+
+The following inputs are generated from FuelLib for each liquid fuel species.
+
+.. table::
+
+   +------------------------+-------------------------------+-------------+
+   |Input                   |Description                    |Required     |
+   +========================+===============================+=============+
+   |``SP_family``           |Compound family                |Yes          |
+   +------------------------+-------------------------------+-------------+
+   |``SP_molar_weight``     |Molecular weight               |Yes          |
+   +------------------------+-------------------------------+-------------+
+   |``SP_crit_temp``        |Critical temperature           |Yes          |
+   +------------------------+-------------------------------+-------------+
+   |``SP_crit_press``       |Critical pressure              |Yes          |
+   +------------------------+-------------------------------+-------------+
+   |``SP_crit_vol``         |Critical volume                |Yes          |
+   +------------------------+-------------------------------+-------------+
+   |``SP_boil_temp``        |Boiling temperature at         |Yes          |
+   |                        |atmospheric pressure           |             |
+   +------------------------+-------------------------------+-------------+
+   |``SP_accentric_factor`` |Critical temperature           |Yes          |
+   +------------------------+-------------------------------+-------------+
+   |``SP_molar_vol``        |Molecular volume               |Yes          |
+   +------------------------+-------------------------------+-------------+
+   |``SP_cp_a``,            |GCM coefficients for specific  |Yes          |
+   |``SP_cp_c``,            |heat                           |             |
+   |``SP_cp_c``             |                               |             |
+   +------------------------+-------------------------------+-------------+
+   |``SP_latent``           |Latent heat at 298.15 K        |Yes          |
+   +------------------------+-------------------------------+-------------+
+
+The specific equations, correlations and mixture rules used in the GCM implementation are detailed in the `Fuel Property Prediction Model <https://nrel.github.io/FuelLib/fuelprops.html>`_ section of FuelLib's documentation.
+
+
 Spray Injection
 ---------------
 
@@ -484,9 +562,13 @@ Spray Validation
 Single Droplet Tests
 --------------------
 
-Single droplet tests are performed in 2D with PeleLMeX and compared with experimental results published in literature. These tests are setup in ``PeleLMeX/Exec/RegTests/SprayEvap``. To run a test case, simply open ``Validate.py`` and set the case name from the table below, for example ::
+Single droplet tests are performed in 2D with PeleLMeX and compared with experimental results published in literature. These tests are setup in ``PeleLMeX/Exec/RegTests/SingleDropEvap`` and can be compiled with ``SPRAY_GCM=TRUE`` or ``FALSE``. To run a test case with the *PeleMP* or *GCM* liquid properties, simply open ``Validate.py`` and set the ``LiqPropsType`` and case name from the table below, for example ::
 
-  case = WongLin()
+   # Liquid properties model: "mp" or "gcm"
+   LiqPropsType = "mp" 
+
+   # Case object
+   case = WongLin(LiqPropsType)
 
 then run ``python Validate.py``.
 The following table details the parameters of each test:
@@ -533,18 +615,25 @@ The following table details the parameters of each test:
 
    Droplet evaporation of heptane, decane, and a binary mixture of heptane and decane compared to experimental measurements from with Runge et al. [#runge]_
 
+.. [#owen] "PeleMP: The Multiphysics Solver for the Combustion Pele Adaptive Mesh Refinement Code Suite," L. D. Owen, W. Ge, M. Rieth, M. Arienti, L. Esclapez, B. S. Soriano, M. E. Mueller, M. Day, R. Sankaran, and J. H. Chen, J. Fluids Eng., vol. 146, no. 4, pp. 1-18 (2024), doi: `10.1115/1.4064494 <https://doi.org/10.1115/1.4064494>`_.
 
-.. [#ton] "Fuel spray modeling in direct-injection diesel and gasoline engines", S. Tonini, Dissertation, City University London (2006), url: `https://openaccess.city.ac.uk/id/eprint/8486/ <https://openaccess.city.ac.uk/id/eprint/8486/>`_.
+.. [#gani94] "New group contribution method for estimating properties of pure compounds", L. Constantinou, and R. Gani, AIChE J., Vol. 40, No. 10, pp.1697-1710 (1994), doi: `10.1002/aic.690401011 <https://doi.org/10.1002/aic.690401011>`_. 
 
-.. [#abram] "Droplet vaporization model for spray combustion calculations", B. Abramzon and W. A. Sirignano, Int. J. Heat Mass Transfer, Vol. 32, No. 9, pp. 1605-1618 (1989)
+.. [#gani95] "Estimation of the acentric factor and the liquid molar volume at 298 K using a new group contribution method", L. Constantinou, and R. Gani, Fluid Phase Equilibria, Vol. 103, No. 1, pp.11-22 (1995), doi: `10.1016/0378-3812(94)02593-P. <https://doi.org/10.1016/0378-3812(94)02593-P.>`_. 
+
+.. [#govindaraju] "Group contribution method for multicomponent evaporation with application to transportation fuels", Int. J. of Heat and Mass Transfer, Vol. 102, pp.833–845 (2016), doi: `10.1016/j.ijheatmasstransfer.2016.06.079 <https://doi.org/10.1016/j.ijheatmasstransfer.2016.06.079>`_.
+
+.. [#abram] "Droplet vaporization model for spray combustion calculations", B. Abramzon and W. A. Sirignano, Int. J. Heat Mass Transfer, vol. 32, no. 9, pp. 1605-1618 (1989), doi: `10.1016/0017-9310(89)90043-4 <https://doi.org/10.1016/0017-9310(89)90043-4>`_.
+
+.. [#ton] "Fuel spray modeling in direct-injection diesel and gasoline engines", S. Tonini, Dissertation, City University London (2006), url: `https://openaccess.city.ac.uk/id/eprint/8486/ <https://openaccess.city.ac.uk/id/eprint/8486/>`_.
 
-.. [#Ge] "Development of a CPU/GPU portable software library for Lagrangian-Eulerian simulations of liquid sprays", W. Ge and R. Sankaran and J. H. Chen, Int. J. Multiph. Flow, Vol. 128 (2020), doi: `10.1016/j.ijmultiphaseflow.2020.103293 <https://doi.org/10.1016/j.ijmultiphaseflow.2020.103293>`_.
+.. [#Ge] "Development of a CPU/GPU portable software library for Lagrangian-Eulerian simulations of liquid sprays", W. Ge and R. Sankaran and J. H. Chen, Int. J. Multiph. Flow, vol. 128 (2020), doi: `10.1016/j.ijmultiphaseflow.2020.103293 <https://doi.org/10.1016/j.ijmultiphaseflow.2020.103293>`_.
 
-.. [#nomura] “Experimental study on high-pressure droplet evaporation using microgravity conditions”, H. Nomura and Y. Ujiie and H. J. Rath and J. Sato and M. Kono, Symposium (International) on Combustion, vol. 26, no. 1, pp. 1267–1273 (1996), doi: `10.1016/S0082-0784(96)80344-4 <https://doi.org/10.1016/S0082-0784(96)80344-4>`_.
+.. [#nomura] "Experimental study on high-pressure droplet evaporation using microgravity conditions", H. Nomura and Y. Ujiie and H. J. Rath and J. Sato and M. Kono, Symposium (International) on Combustion, vol. 26, no. 1, pp. 1267–1273 (1996), doi: `10.1016/S0082-0784(96)80344-4 <https://doi.org/10.1016/S0082-0784(96)80344-4>`_.
 
-.. [#wonglin] “Internal temperature distributions of droplets vaporizing in high-temperature convective flows”, S.-C. Wong and A.-C. Lin, J. Fluid Mech., vol. 237, pp. 671–687 (1992), doi: `10.1017/S0022112092003574 <https://doi.org/10.1017/S0022112092003574>`_.  
+.. [#wonglin] "Internal temperature distributions of droplets vaporizing in high-temperature convective flows", S.-C. Wong and A.-C. Lin, J. Fluid Mech., vol. 237, pp. 671–687 (1992), doi: `10.1017/S0022112092003574 <https://doi.org/10.1017/S0022112092003574>`_.  
 
-.. [#daif] "Comparison of multicomponent fuel droplet vaporization experiments in forced convection with the Sirignano model", A. Daı̈f and M. Bouaziz and X. Chesneau and A. Ali Chérif, Exp. Therm. Fluid Sci., Vol. 18, No. 4, pp. 282-290, Issn 0894-1777 (1998), doi: `10.1016/S0894-1777(98)10035-3 <https://doi.org/10.1016/S0894-1777(98)10035-3>`_.
+.. [#daif] "Comparison of multicomponent fuel droplet vaporization experiments in forced convection with the Sirignano model", A. Daı̈f and M. Bouaziz and X. Chesneau and A. Ali Chérif, Exp. Therm. Fluid Sci., vol. 18, no. 4, pp. 282-290, Issn 0894-1777 (1998), doi: `10.1016/S0894-1777(98)10035-3 <https://doi.org/10.1016/S0894-1777(98)10035-3>`_.
 
-.. [#runge] "Low-temperature vaporization of JP-4 and JP-8 fuel droplets", T. Runge and M. Teske and C. E. Polymeropoulos, At. Sprays, Vol. 8, pp. 25-44 (1998), doi: `10.1615/AtomizSpr.v8.i1.20 <https://doi.org/10.1615/AtomizSpr.v8.i1.20>`_.
+.. [#runge] "Low-temperature vaporization of JP-4 and JP-8 fuel droplets", T. Runge and M. Teske and C. E. Polymeropoulos, At. Sprays, vol. 8, pp. 25-44 (1998), doi: `10.1615/AtomizSpr.v8.i1.20 <https://doi.org/10.1615/AtomizSpr.v8.i1.20>`_.
 

Docs/sphinx/Visualization/daif_res_2025.png

@@ -30,7 +30,6 @@ updateBreakupKHRT(
   const amrex::Real We_crit = 6.;
   // RT model constants
   const amrex::Real A1 = 0.188;
-  SprayUnits SPU;
   // Retrieve particle data
   amrex::RealVect vel_part(AMREX_D_DECL(
     p.rdata(SprayComps::pstateVel), p.rdata(SprayComps::pstateVel + 1),
@@ -48,7 +47,7 @@ updateBreakupKHRT(
   // Should not create child droplets that are near to or less than the minimum
   // allowable mass to avoid unphysical evaporation of mass
   amrex::Real min_rad =
-    4. * std::cbrt(SPU.min_mass * 3. / (4. * M_PI * rho_part));
+    4. * std::cbrt(SprayUnits::min_mass * 3. / (4. * M_PI * rho_part));
   amrex::Real shed_mass = p.rdata(SprayComps::pstateBM1);
   amrex::Real N0 = p.rdata(SprayComps::pstateN0);
   // To prolong RT breakup, rt_time is set to -1 on injection. RT breakup can

Docs/sphinx/Visualization/nomura_res_2025.png

@@ -29,7 +29,6 @@ updateBreakupTAB(
   // Constants for ETAB
   const amrex::Real Wet = 80.;
   const amrex::Real k2 = 2. / 9.;
-  SprayUnits SPU;
 
   // Retrieve particle data
   amrex::RealVect vel_part(AMREX_D_DECL(
@@ -50,7 +49,7 @@ updateBreakupTAB(
   amrex::Real Utan_total = 0.;
   amrex::Real rad_part = 0.5 * dia_part;
   amrex::Real min_rad =
-    4. * std::cbrt(SPU.min_mass * 3. / (4. * M_PI * rho_part));
+    4. * std::cbrt(SprayUnits::min_mass * 3. / (4. * M_PI * rho_part));
   if (rad_part < min_rad) {
     return 0.;
   }