Fluid model
===========

The following inputs are defined using the ``fluid`` prefix.

+--------------------------------------------+-------------------------------------------------------------+--------+----------+
|                                            | Description                                                 |  Type  | Default  |
+============================================+=============================================================+========+==========+
| solve                                      | Specify the name of the fluid or set to ``None`` to disable | String | ``None`` |
|                                            | the fluid solver. The name assigned to the fluid solver is  |        |          |
|                                            | used to specify fluid properties and initial and boundary   |        |          |
|                                            | conditions.                                                 |        |          |
+--------------------------------------------+-------------------------------------------------------------+--------+----------+


The root prefix for the following inputs use the name defined using the ``fluid.solve`` keyword. For example, if the fluid solver
is named ``myfluid``, then the following keywords are preceded with ``myfluid`` and a period. Currently, MFIX-Exa only supports
a single fluid; therefore, it is common to name the fluid ``fluid``. This is illustrated later in example input snippets.

.. |Sutherland_Eq| replace:: :math:`\mu(T) = \mu_{ref}\left(\frac{T}{T_{ref}}\right)^{3/2}\frac{T_{ref} + S}{T+S}`

.. |Reid_4parm_Eq| replace:: :math:`\mu(T) = A\exp{\left( \frac{B}{T} + CT + DT^2 \right)}`

.. |Sato_Eq| replace:: :math:`\mu^* = 1 + C d_s \rho \mu_{mol} \left|\boldsymbol{u} - \boldsymbol{u_s}\right|`

+--------------------------------------------+------------------------------------------------------------+--------+----------+
|                                            | Description                                                |  Type  | Default  |
+============================================+============================================================+========+==========+
| viscosity.molecular                        | Specify which molecular viscosity model to use.            | String |  None    |
|                                            |                                                            |        |          |
|                                            | Available options include:                                 |        |          |
|                                            |                                                            |        |          |
|                                            | * ``constant`` constant viscosity                          |        |          |
|                                            | * ``Sutherland`` :cite:p:`suth1893`                        |        |          |
|                                            |                                                            |        |          |
|                                            |      |Sutherland_Eq|                                       |        |          |
|                                            |                                                            |        |          |
|                                            | * ``Reid`` :cite:p:`reid87`                                |        |          |
|                                            |                                                            |        |          |
|                                            |      |Reid_4parm_Eq|                                       |        |          |
|                                            |                                                            |        |          |
|                                            | A viscosity model is required if the fluid solver is       |        |          |
|                                            | enabled.                                                   |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.molecular.constant               | Constant fluid viscosity.                                  |  Real  |  0       |
|                                            |                                                            |        |          |
|                                            | A value is required for ``constant`` viscosity model.      |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.molecular.Sutherland.T_ref       | Sutherland model reference temperature                     |  Real  |  0       |
|                                            |                                                            |        |          |
|                                            | A value is required for ``Sutherland`` viscosity model.    |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.molecular.Sutherland.mu_ref      | Sutherland model reference viscosity at T_ref              |  Real  |  0       |
|                                            |                                                            |        |          |
|                                            | A value is required for ``Sutherland`` viscosity model.    |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.molecular.Sutherland.S           | Sutherland model temperature                               |  Real  |  0       |
|                                            |                                                            |        |          |
|                                            | A value is required for ``Sutherland`` viscosity model.    |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.molecular.Reid.A,                | Reid model constants                                       |  Real  |  0       |
| viscosity.molecular.Reid.B,                |                                                            |        |          |
| viscosity.molecular.Reid.C, and            | Values are required for ``Reid`` viscosity model.          |        |          |
| viscosity.molecular.Reid.D                 |                                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.eddy                             | Specify eddy viscosity model.                              | String | None     |
|                                            |                                                            |        |          |
|                                            | Available options include:                                 |        |          |
|                                            |                                                            |        |          |
|                                            | * ``None`` No eddy viscosity model                         |        |          |
|                                            | * ``Smagorinsky-Lilly`` :cite:p:`Smag63,Lilly66`           |        |          |
|                                            | * ``WALE`` :cite:p:`ducros98`                              |        |          |
|                                            |                                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.eddy.Smagorinsky-Lilly.constant  | Smagorinsky-Lilly constant which usually has values        | Real   | None     |
|                                            | between 0.1 and 0.2.                                       |        |          |
|                                            |                                                            |        |          |
|                                            | A value is required when using the ``Smagorinsky-Lilly``   |        |          |
|                                            | eddy viscosity model.                                      |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.eddy.WALE.constant               | WALE eddy viscosity model constant.                        | Real   | 0.325    |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.suspension                       | Specify suspension viscosity model of the form             | String | None     |
|                                            |                                                            |        |          |
|                                            |    :math:`\mu_{susp}=\mu_{mol}(\mu^* - 1)`                 |        |          |
|                                            |                                                            |        |          |
|                                            | Available options include:                                 |        |          |
|                                            |                                                            |        |          |
|                                            | * ``None`` No eddy suspension model                        |        |          |
|                                            |                                                            |        |          |
|                                            |      :math:`\mu^*=1`                                       |        |          |
|                                            |                                                            |        |          |
|                                            | * ``Einstein`` :cite:p:`einstein11`                        |        |          |
|                                            |                                                            |        |          |
|                                            |      :math:`\mu^*=1 + 2.5\varepsilon_s`                    |        |          |
|                                            |                                                            |        |          |
|                                            | * ``Brinkman`` :cite:p:`brinkman52,gibilaro07`             |        |          |
|                                            |                                                            |        |          |
|                                            |      :math:`\mu^*=(1-\varepsilon_s)^{-c}`                  |        |          |
|                                            |                                                            |        |          |
|                                            | * ``Roscoe`` :cite:p:`roscoe52,krieger59,maron56`          |        |          |
|                                            |                                                            |        |          |
|                                            |      :math:`\mu^*=(1-\varepsilon_s/c_1)^{-c_2}`            |        |          |
|                                            |                                                            |        |          |
|                                            | * ``ChengLaw`` :cite:p:`cheng03`                           |        |          |
|                                            |                                                            |        |          |
|                                            |      :math:`\mu^*=e^{2.5(1/(1-\varepsilon_s)^c-1)/c}`      |        |          |
|                                            |                                                            |        |          |
|                                            | * ``Sato`` :cite:p:`sato81`                                |        |          |
|                                            |                                                            |        |          |
|                                            |      |Sato_Eq|                                             |        |          |
|                                            |                                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.suspension.Brinkman.constant     | Constant for exponent in Brinkman suspension expression.   | Real   | None     |
|                                            |                                                            |        |          |
|                                            | A value is required when using the model ``Brinkman``.     |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.suspension.Roscoe.c1             | Constant for max packing in Roscoe suspension expression.  | Real   | None     |
|                                            |                                                            |        |          |
|                                            | A value is required when using the model ``Roscoe``.       |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.suspension.Roscoe.c2             | Constant for exponent in Roscoe suspension expression.     | Real   | None     |
|                                            |                                                            |        |          |
|                                            | A value is required when using the model ``Roscoe``.       |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.suspension.ChengLaw.constant     | Constant for exponent in ChengLaw suspension expression.   | Real   | None     |
|                                            |                                                            |        |          |
|                                            | A value is required when using the model ``ChengLaw``.     |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.suspension.Sato.constant         | Constant for Sato suspension expression.                   | Real   | 0.65     |
|                                            |                                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| viscosity.max_effective_factor             | Max limit of the effective viscosity as a factor of the    | Real   | 1.e6     |
|                                            | molecular viscosity                                        |        |          |
|                                            |                                                            |        |          |
|                                            | :math:`\mu_{eff} < fac*\mu_{mol}`, where                   |        |          |
|                                            | :math:`\mu_{eff} = \mu_{mol} + \mu_{eddy} + \mu_{susp}`    |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| species                                    | Specify the species that constitute the fluid.             | String |  None    |
|                                            |                                                            |        |          |
|                                            | All listed species must be properly defined. See the       |        |          |
|                                            | :ref:`species definition documentation<InputsSpeciesDefs>` |        |          |
|                                            | for additional details.                                    |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| molecular_weight                           | Constant fluid molecular weight.                           | Real   |    0     |
|                                            |                                                            |        |          |
|                                            | A molecular weight should only be defined when using one   |        |          |
|                                            | of the *ideal gas* constraints and the species equations   |        |          |
|                                            | are not solved.                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| specific_heat                              | Specify which specific heat model to use for the fluid.    | String |  None    |
|                                            | Available options include:                                 |        |          |
|                                            |                                                            |        |          |
|                                            | * ``constant`` - the fluid has a constant specific heat    |        |          |
|                                            |                                                            |        |          |
|                                            | * ``NASA7-poly`` the fluid specific heat is defined by a   |        |          |
|                                            |   low-temperature (T < 1000K) polynomial and a             |        |          |
|                                            |   high-temperature (T > 1000K) polynomial.                 |        |          |
|                                            |                                                            |        |          |
|                                            |   NASA7 polynomial format:                                 |        |          |
|                                            |                                                            |        |          |
|                                            |      :math:`c_p(T) = \sum_{i=0}^5 a_iT^i`                  |        |          |
|                                            |                                                            |        |          |
|                                            | * ``mixture`` - a *mixture* specific heat is computed      |        |          |
|                                            |   from :ref:`species specific heats<InputsSpeciesDefs>`    |        |          |
|                                            |   and local species mass fractions.                        |        |          |
|                                            |                                                            |        |          |
|                                            |      :math:`c_{p,\mathrm{mixture}} = \sum_n X_n c_{p,n}`   |        |          |
|                                            |                                                            |        |          |
|                                            | A specific heat model is required if advecting enthalpy.   |        |          |
|                                            | Furthermore, the model must be ``mixture`` if species      |        |          |
|                                            | equations are solved.                                      |        |          |
|                                            |                                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| specific_heat.constant                     | Constant fluid specific heat                               | Real   |  0       |
|                                            | A value is required for ``constant`` specific heat model.  |        |          |
|                                            |                                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| specific_heat.NASA7.a[i]                   | Specific heat polynomial coefficients. Polynomial          | Real   |  0.  0.  |
|                                            | coefficients are required if the fluid specific heat       |        |          |
|                                            | model is ``NASA7-poly``.                                   |        |          |
|                                            |                                                            |        |          |
|                                            | Each polynomial is defined by six coefficients (``a0``,    |        |          |
|                                            | ..., ``a5``), and two values are required for each         |        |          |
|                                            | coefficient. The first value is the low temperature        |        |          |
|                                            | polynomial coefficient (T < 1000K) and the second is the   |        |          |
|                                            | coefficient for the high temperature polynomial            |        |          |
|                                            | (T > 1000K). A total of twelve coefficients are required.  |        |          |
|                                            |                                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| thermal_conductivity                       | Specify which thermal conductivity model to use for        | String |  None    |
|                                            | fluid. Available options include:                          |        |          |
|                                            |                                                            |        |          |
|                                            | * ``constant`` - the fluid has a constant thermal          |        |          |
|                                            |   conductivity model                                       |        |          |
|                                            |                                                            |        |          |
|                                            | A thermal conductivity model is required if advecting      |        |          |
|                                            | enthalpy.                                                  |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| thermal_conductivity.constant              | Constant fluid thermal conductivity.                       | Real   |  0       |
|                                            | A value is required for ``constant`` thermal conductivity  |        |          |
|                                            | model.                                                     |        |          |
|                                            |                                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| thermodynamic_pressure                     | Thermodynamic pressure.                                    | Real   |  0       |
|                                            | A value is required when using the                         |        |          |
|                                            | ``IdealGasClosedSystem`` constraint. If using the          |        |          |
|                                            | ``IdealGasOpenSystem`` constraint, then the value must     |        |          |
|                                            | match all specified outflow pressures.                     |        |          |
|                                            |                                                            |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+
| reference_temperature                      | Reference temperature used to compute specific             | Real   | 298.     |
|                                            | enthalpy                                                   |        |          |
+--------------------------------------------+------------------------------------------------------------+--------+----------+


Example inputs
--------------

Incompressible fluid
^^^^^^^^^^^^^^^^^^^^

The following setup shows how to define the most basic fluid model where the
only required physical property is fluid viscosity. We are using the ``IncompressibleFluid``
constraint; therefore, the *constant* fluid density is defined
by the initial and boundary conditions. The fluid energy and species equations
are not solved.

.. code-block:: bash
   :caption: Snippet of inputs defining a simple incompressible fluid. This is not a complete input file.

   mfix.constraint = IncompressibleFluid

   mfix.advect_density  = 0
   mfix.advect_enthalpy = 0
   mfix.solve_species   = 0


   # Fluid model settings
   # -----------------------------------------------------------------------
   fluid.solve = fluid0

   fluid0.viscosity.molecular = constant
   fluid0.viscosity.molecular.constant = 1.8e-5


   # Initial Conditions
   # -----------------------------------------------------------------------
   ic.regions = full-domain

   ic.full-domain.fluid0.volfrac   =  1.0
   ic.full-domain.fluid0.density   =  1.0

   ic.full-domain.fluid0.velocity  =  0.0  0.0  0.0


   # Boundary Conditions
   # -----------------------------------------------------------------------
   bc.regions = inlet  outlet

   bc.inlet = mi
   bc.inlet.fluid0.volfrac  =  1.0
   bc.inlet.fluid0.density  =  1.0

   bc.inlet.fluid0.velocity =  1.0e-8  0.0  0.0

   bc.outlet = po
   bc.outlet.fluid0.pressure =  0.


Simple ideal gas
^^^^^^^^^^^^^^^^

In the following example, we use the ``IdealGasOpenSystem`` so that the fluid
density is calculated from the ideal gas equation of state.  In addition to
viscosity, we must also provide the fluid molecular weight. The fluid energy
and species equations are not solved, but the *constant* fluid temperature is
required in the initial and boundary conditions to fully specify the equation
of state. Lastly, the outflow boundary pressure is taken as the thermodynamic
pressure when evaluating the equation of state.


.. code-block:: bash
   :caption: Snippet of inputs defining a simple ideal gas. This is not a complete input file.

   mfix.constraint = IdealGasOpenSystem

   mfix.advect_density  = 1
   mfix.advect_enthalpy = 0
   mfix.solve_species   = 0


   # Fluid model settings
   # -----------------------------------------------------------------------
   fluid.solve = fluid0

   fluid0.viscosity.molecular = constant
   fluid0.viscosity.molecular.constant = 1.8e-5

   fluid0.molecular_weight = 29.0e-3


   # Initial Conditions
   # -----------------------------------------------------------------------
   ic.regions = full-domain

   ic.full-domain.fluid0.volfrac   =  1.0

   ic.full-domain.fluid0.velocity  =  0.0  0.0  0.0

   ic.full-domain.fluid0.temperature = 300.0


   # Boundary Conditions
   # -----------------------------------------------------------------------
   bc.regions = inlet  outlet

   bc.inlet = mi
   bc.inlet.fluid0.volfrac  =  1.0

   bc.inlet.fluid0.velocity =  1.0e-8  0.0  0.0

   bc.inlet.fluid0.temperature = 300.0

   bc.outlet = po
   bc.outlet.fluid0.pressure =  101325.



Ideal gas with energy
^^^^^^^^^^^^^^^^^^^^^

In the last example, we use the ``IdealGasOpenSystem``, however unlike the
previous demonstration, the energy equation is solved. Therefore, we must
define the fluid viscosity, molecular weight, thermal conductivity, and
specific heat. Again, the fluid temperature is required in the initial and
boundary conditions, and the outflow boundary pressure is taken as the
thermodynamic pressure for the system.


.. code-block:: bash
   :caption: Snippet of inputs defining an idea gas with energy. This is not a complete input file.

   mfix.constraint = IdealGasOpenSystem

   mfix.advect_density  = 1
   mfix.advect_enthalpy = 1
   mfix.solve_species   = 0


   # Fluid model settings
   # -----------------------------------------------------------------------
   fluid.solve = fluid0

   fluid0.viscosity.molecular = constant
   fluid0.viscosity.molecular.constant = 2.0e-5

   fluid0.thermal_conductivity = constant
   fluid0.thermal_conductivity.constant = 0.026

   fluid0.molecular_weight = 28.96518e-3

   fluid0.specific_heat = NASA7-poly

   fluid0.specific_heat.NASA7.a0 =  5.95960930E+00   3.08792717E+00
   fluid0.specific_heat.NASA7.a1 =  3.56839620E+00   1.24597184E-03
   fluid0.specific_heat.NASA7.a2 = -6.78729429E-04  -4.23718945E-07
   fluid0.specific_heat.NASA7.a3 =  1.55371476E-06   6.74774789E-11
   fluid0.specific_heat.NASA7.a4 = -3.29937060E-12  -3.97076972E-15
   fluid0.specific_heat.NASA7.a5 = -4.66395387E-13  -9.95262755E+02


   # Initial Conditions
   # -----------------------------------------------------------------------
   ic.regions = full-domain

   ic.full-domain.fluid0.volfrac   =  1.0

   ic.full-domain.fluid0.velocity  =  0.0  0.0  0.0

   ic.full-domain.fluid0.temperature = 300.0

   # Boundary Conditions
   # -----------------------------------------------------------------------
   bc.regions = inlet  outlet

   bc.inlet = mi
   bc.inlet.fluid0.volfrac  =  1.0

   bc.inlet.fluid0.velocity =  1.0e-8  0.0  0.0

   bc.inlet.fluid0.temperature = 300.0

   bc.outlet = po
   bc.outlet.fluid0.pressure =  101325.


The following inputs are defined using the ``fluid`` prefix and control the convergence criteria
of the damped Newton solver used to compute temperature from enthalpy and specific heat.

+------------------------------------------+----------------------------------------------------------+--------+----------+
|                                          | Description                                              |  Type  | Default  |
+==========================================+==========================================================+========+==========+
| newton_solver.absolute_tol               | Define absolute tolerance for the Newton solver          |  Real  |  1.e-8   |
+------------------------------------------+----------------------------------------------------------+--------+----------+
| newton_solver.relative_tol               | Define relative tolerance for the Newton solver          |  Real  |  1.e-8   |
+------------------------------------------+----------------------------------------------------------+--------+----------+
| newton_solver.max_iterations             | Define max number of iterations for the Newton solver    |  int   |  500     |
+------------------------------------------+----------------------------------------------------------+--------+----------+
