Finish docs (?) and include function for user-prescribed materials

mirgecom/gas_model.py

@@ -407,7 +407,9 @@ def make_fluid_state(cv, gas_model,
             tortuosity=gas_model.wall_model.tortuosity(tau)
         )
 
-        temperature = gas_model.get_temperature(cv=cv, wv=wv, tseed=temperature_seed)
+        # FIXME is there a way to pass the argument to "niter"?
+        temperature = gas_model.get_temperature(cv=cv, wv=wv,
+            tseed=temperature_seed, niter=3)
 
         pressure = gas_model.get_pressure(cv, wv, temperature)
 

mirgecom/materials/__init__.py

@@ -28,4 +28,5 @@
 .. automodule:: mirgecom.materials.initializer
 .. automodule:: mirgecom.materials.carbon_fiber
 .. automodule:: mirgecom.materials.tacot
+.. automodule:: mirgecom.materials.simple_material
 """

mirgecom/materials/initializer.py

@@ -58,14 +58,16 @@ def __call__(self, x_vec, wall_model):
 class PorousWallInitializer:
     """Initializer for porous materials."""
 
-    def __init__(self, pressure, temperature, species, material_densities):
+    def __init__(self, temperature, species, material_densities,
+                 pressure=None, density=None):
 
         self._pres = pressure
+        self._mass = density
         self._y = species
         self._temp = temperature
         self._wall_density = material_densities
 
-    def __call__(self, x_vec, gas_model):
+    def __call__(self, dim, x_vec, gas_model):
         """Evaluate the wall+gas properties for porous materials.
 
         Parameters
@@ -78,18 +80,23 @@ def __call__(self, x_vec, gas_model):
         actx = x_vec[0].array_context
         zeros = actx.np.zeros_like(x_vec[0])
 
-        pressure = self._pres + zeros
         temperature = self._temp + zeros
         species_mass_frac = self._y + zeros
+        wall_density = self._wall_density + zeros
 
-        tau = gas_model.decomposition_progress(self._wall_density)
+        tau = gas_model.decomposition_progress(wall_density)
 
         eps_gas = gas_model.wall_model.void_fraction(tau)
-        eps_rho_gas = eps_gas*gas_model.eos.get_density(pressure, temperature,
-                                                        species_mass_frac)
+        if self._mass is None:
+            pressure = self._pres + zeros
+            eps_rho_gas = eps_gas*gas_model.eos.get_density(pressure,
+                temperature, species_mass_frac)
+        else:
+            density = self._mass + zeros
+            eps_rho_gas = eps_gas*density
 
         # internal energy (kinetic energy is neglected)
-        eps_rho_solid = sum(self._wall_density)
+        eps_rho_solid = sum(wall_density)
         bulk_energy = (
             eps_rho_solid*gas_model.wall_model.enthalpy(temperature, tau)
             + eps_rho_gas*gas_model.eos.get_internal_energy(temperature,
@@ -100,5 +107,5 @@ def __call__(self, x_vec, gas_model):
 
         species_mass = eps_rho_gas*species_mass_frac
 
-        return make_conserved(dim=2, mass=eps_rho_gas, energy=bulk_energy,
+        return make_conserved(dim=dim, mass=eps_rho_gas, energy=bulk_energy,
             momentum=momentum, species_mass=species_mass)

mirgecom/materials/simple_material.py

@@ -0,0 +1,109 @@
+""":mod:`mirgecom.materials.simple_material` for user-defined materials."""
+
+__copyright__ = """
+Copyright (C) 2023 University of Illinois Board of Trustees
+"""
+
+__license__ = """
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+"""
+
+from typing import Optional
+from meshmode.dof_array import DOFArray
+from mirgecom.wall_model import PorousWallProperties
+
+
+class SolidProperties(PorousWallProperties):
+    """Evaluate the properties of the solid state containing only fibers.
+
+    .. automethod:: void_fraction
+    .. automethod:: enthalpy
+    .. automethod:: heat_capacity
+    .. automethod:: thermal_conductivity
+    .. automethod:: volume_fraction
+    .. automethod:: permeability
+    .. automethod:: emissivity
+    .. automethod:: tortuosity
+    .. automethod:: decomposition_progress
+    """
+
+    def __init__(self, char_mass, virgin_mass, enthalpy_func, heat_capacity_func,
+                 thermal_conductivity_func, volume_fraction_func, permeability_func,
+                 emissivity_func, tortuosity_func):
+
+        self._char_mass = char_mass
+        self._virgin_mass = virgin_mass
+        self._enthalpy_func = enthalpy_func
+        self._heat_capacity_func = heat_capacity_func
+        self._thermal_conductivity_func = thermal_conductivity_func
+        self._volume_fraction_func = volume_fraction_func
+        self._permeability_func = permeability_func
+        self._emissivity_func = emissivity_func
+        self._tortuosity_func = tortuosity_func
+
+    def void_fraction(self, tau: DOFArray) -> DOFArray:
+        r"""Return the volumetric fraction $\epsilon$ filled with gas.
+
+        The fractions of gas and solid phases must sum to one,
+        $\epsilon_g + \epsilon_s = 1$. Both depend only on the oxidation
+        progress ratio $\tau$.
+        """
+        return 1.0 - self.volume_fraction(tau)
+
+    def enthalpy(self, temperature: DOFArray, tau: Optional[DOFArray]) -> DOFArray:
+        r"""Evaluate the solid enthalpy $h_s$ of the fibers."""
+        return self._enthalpy_func(temperature)
+
+    def heat_capacity(self, temperature: DOFArray,
+                      tau: Optional[DOFArray]) -> DOFArray:
+        r"""Evaluate the heat capacity $C_{p_s}$ of the fibers."""
+        return self._heat_capacity_func(temperature)
+
+    def thermal_conductivity(self, temperature: DOFArray,
+                                   tau: DOFArray) -> DOFArray:
+        r"""Evaluate the thermal conductivity $\kappa$ of the fibers.
+
+        It employs a rescaling of the experimental data based on the fiber
+        shrinkage during the oxidation.
+        """
+        return self._thermal_conductivity_func(temperature)
+
+    def volume_fraction(self, tau: DOFArray) -> DOFArray:
+        r"""Fraction $\phi$ occupied by the solid."""
+        actx = tau.array_context
+        return self._volume_fraction_func(tau) + actx.np.zeros_like(tau)
+
+    def permeability(self, tau: DOFArray) -> DOFArray:
+        r"""Permeability $K$ of the porous material."""
+        actx = tau.array_context
+        return self._permeability_func(tau) + actx.np.zeros_like(tau)
+
+    def emissivity(self, tau: DOFArray) -> DOFArray:
+        """Emissivity for energy radiation."""
+        actx = tau.array_context
+        return self._emissivity_func(tau) + actx.np.zeros_like(tau)
+
+    def tortuosity(self, tau: DOFArray) -> DOFArray:
+        r"""Tortuosity $\eta$ affects the species diffusivity."""
+        actx = tau.array_context
+        return self._tortuosity_func(tau) + actx.np.zeros_like(tau)
+
+    def decomposition_progress(self, mass: DOFArray) -> DOFArray:
+        r"""Evaluate the progress rate $\tau$."""
+        return 1.0 - (self._virgin_mass - mass)/self._virgin_mass

mirgecom/wall_model.py

@@ -272,33 +272,39 @@ def heat_capacity(self, cv: ConservedVars, wv: PorousWallVars,
 @dataclass(frozen=True)
 class PorousFlowModel(PorousFlowEOS):
     """
-    <A very important description>...
+    This is the main class of the porous media flow and is the
+    equivalent to :class:`~mirgecom.gas_model.GasModel`. It wraps:
 
     .. attribute:: wall_model
+
+        The thermophysical properties of the wall material and its EOS.
+
     .. attribute:: eos
+
+        The thermophysical properties of the gas and its EOS. For now, only
+        mixtures are considered.
+
     .. attribute:: transport
 
+        Transport class that governs how the gas flows through the porous
+        media. This is accounted for in
+        :class:`~mirgecom.transport.PorousWallTransport`
+
+    It also include functions that combine the properties of the porous
+    material and the gas that permeates, yielding the actual porous flow EOS:
+
     .. automethod:: solid_density
+    .. automethod:: decomposition_progress
     .. automethod:: get_temperature
     .. automethod:: get_pressure
     .. automethod:: internal_energy
     .. automethod:: heat_capacity
-    .. automethod:: decomposition_progress
     """
 
     eos: GasEOS
     transport: TransportModel
     wall_model: PorousWallProperties
 
-    def decomposition_progress(self, material_densities) -> DOFArray:
-        r"""Evaluate the progress ratio $\tau$ of the decomposition.
-
-        Where $\tau=1$, the material is locally virgin. On the other hand, if
-        $\tau=0$, then the fibers were all consumed.
-        """
-        mass = self.solid_density(material_densities)
-        return self.wall_model.decomposition_progress(mass)
-
     def solid_density(self, material_densities) -> DOFArray:
         r"""Return the solid density $\epsilon_s \rho_s$.
 
@@ -313,6 +319,15 @@ def solid_density(self, material_densities) -> DOFArray:
             return material_densities
         return sum(material_densities)
 
+    def decomposition_progress(self, material_densities) -> DOFArray:
+        r"""Evaluate the progress ratio $\tau$ of the decomposition.
+
+        Where $\tau=1$, the material is locally virgin. On the other hand, if
+        $\tau=0$, then the fibers were all consumed.
+        """
+        mass = self.solid_density(material_densities)
+        return self.wall_model.decomposition_progress(mass)
+
     def get_temperature(self, cv: ConservedVars, wv: PorousWallVars,
                         tseed: DOFArray, niter=3) -> DOFArray:
         r"""Evaluate the temperature based on solid+gas properties.
@@ -345,18 +360,36 @@ def get_temperature(self, cv: ConservedVars, wv: PorousWallVars,
 
     def get_pressure(self, cv: ConservedVars, wv: PorousWallVars,
                      temperature: DOFArray) -> DOFArray:
-        """Return the pressure of the gas considering the void fraction."""
+        r"""Return the pressure of the gas considering the void fraction.
+
+        Since the density is evaluated based on the entire bulk material, i.e.,
+        considering the void fraction, the pressure is evaluated as
+
+        .. math::
+            P = \frac{\epsilon \rho}{\epsilon} \frac{R}{M} T
+
+        where $\epsilon \rho$ is stored in :class:`~mirgecom.fluid.ConservedVars`
+        and $M$ is the molar mass of the mixture.
+        """
         return self.eos.pressure(cv, temperature)/wv.void_fraction
 
     def internal_energy(self, cv: ConservedVars, wv: PorousWallVars,
                  temperature: DOFArray) -> DOFArray:
-        """Return the enthalpy of the gas+solid material."""
+        r"""Return the enthalpy of the gas+solid material.
+
+        .. math::
+            \rho e = \epsilon_s \rho_s e_s + \epsilon_g \rho_g e_g
+        """
         return (cv.mass*self.eos.get_internal_energy(temperature,
                                                 cv.species_mass_fractions)
                 + wv.density*self.wall_model.enthalpy(temperature, wv.tau))
 
     def heat_capacity(self, cv: ConservedVars, wv: PorousWallVars,
                  temperature: DOFArray) -> DOFArray:
-        """Return the heat capacity of the gas+solid material."""
+        r"""Return the heat capacity of the gas+solid material.
+
+        .. math::
+            \rho e = \epsilon_s \rho_s {C_p}_s + \epsilon_g \rho_g {C_v}_g
+        """
         return (cv.mass*self.eos.heat_capacity_cv(cv, temperature)
                 + wv.density*self.wall_model.heat_capacity(temperature, wv.tau))