4.4.3. Tabulated Material Properties

When using a flamelet model in Fuego, one must first pre-calculate a table of necessary properties as functions of the transported scalars (e.g. mixture fraction). The theory behind this approach is described in detail in Laminar Flamelet Turbulent Combustion Model, so this section will focus on how to set up a Fuego material model using a pre-computed flamelet table. You can also refer to the SpitFire wiki for details on how to generate a flamelet table.

Inside the Property Specification block, you will supply reference values for the property inputs as with the basic and Cantera materials. The nested Tabular Property Library block then defines the table file to use and links the table variables and properties with Fuego variables and properties (if necessary).

BEGIN PROPERTY SPECIFICATION FOR FUEGO MATERIAL gas
    REFERENCE mixture_fraction = 0.0
    REFERENCE scaled_scalar_variance = 0.0
    REFERENCE scalar_diss_rate = 0.0
    REFERENCE temperature = 300.0 # or REFERENCE heat_loss = 0
    REFERENCE pressure = 1.0

    BEGIN TABULAR PROPERTY LIBRARY SLFM
      TABLE UNITS ARE IN MKS
      LIBRARY HDF5 FILE = methane_plume.h5
    END TABULAR PROPERTY LIBRARY SLFM

    SCHMIDT_NUMBER = 0.9
    PRANDTL_NUMBER = 0.9

END   PROPERTY SPECIFICATION FOR FUEGO MATERIAL gas

4.4.3.1. Mapping Table Inputs and Outputs

To translate between table outputs and inputs and Fuego variables, most tables can simply use default settings with the most common names used in table generation. However, if your table has non-standard naming for inputs or properties you can specify this mapping manually.

Note

If you have any custom names in the inputs or outputs, no automatic mapping is used for that group so you must supply mapping for all inputs and/or all outputs.

BEGIN PROPERTY SPECIFICATION FOR FUEGO MATERIAL gas
    # ...

    BEGIN TABULAR PROPERTY LIBRARY SLFM
      TABLE UNITS ARE IN MKS
      LIBRARY HDF5 FILE = methane_plume.h5

      USE FIELD mixture_fraction       FOR LIBRARY INPUT mixture_fraction_mean
      USE FIELD scaled_scalar_variance FOR LIBRARY INPUT scaled_scalar_variance_mean
      USE FIELD scalar_diss_rate       FOR LIBRARY INPUT dissipation_rate_stoich_mean
      USE FIELD heat_loss              FOR LIBRARY INPUT enthalpy_defect_stoich_mean

      USE LIBRARY VARIABLE density           FOR PROPERTY density
      USE LIBRARY VARIABLE viscosity         FOR PROPERTY viscosity
      USE LIBRARY VARIABLE temperature       FOR PROPERTY temperature
      USE LIBRARY VARIABLE heat_capacity_cp  FOR PROPERTY specific_heat
      USE LIBRARY VARIABLE enthalpy          FOR PROPERTY enthalpy
      USE LIBRARY VARIABLE enthalpy_cons     FOR PROPERTY conserved_enthalpy

    END TABULAR PROPERTY LIBRARY SLFM

END   PROPERTY SPECIFICATION FOR FUEGO MATERIAL gas

4.4.3.2. Soot Model Terms

To activate the pre-configured Aksit-Moss SNL soot model you can add the Use Aerosol model aksit_moss_snl in the tabular property block. This will add pre-configured soot and radiation source terms, as well as progress variables soot_moles_per_mass and soot_mass_fraction.

BEGIN PROPERTY SPECIFICATION FOR FUEGO MATERIAL gas
  # ...
  BEGIN TABULAR PROPERTY LIBRARY SLFM
    LIBRARY HDF5 FILE = ./pure-ethylene.h5
    TABLE UNITS ARE IN mks
    USE AEROSOL MODEL aksit_moss_snl
  END TABULAR PROPERTY LIBRARY SLFM
END

4.4.3.3. Radiation Terms

If you are not using a pre-made soot model, and have radiative transport active, you will need to define models for absorption and rad_source to be passed to the PMR solver. These expressions may be simple copies of table sources, as below, or may be a user-defined function to include effects of soot.

BEGIN PROPERTY SPECIFICATION FOR FUEGO MATERIAL gas
    # ...

    BEGIN TABULAR PROPERTY LIBRARY SLFM
      TABLE UNITS ARE IN MKS
      LIBRARY HDF5 FILE = methane_plume.h5

      #### RADIATION SOURCE TERMS
      USE LIBRARY SOURCE gas_abs_coeff  AS gas_abs_coeff
      USE LIBRARY SOURCE gas_rad_source AS gas_rad_source
      AUXILIARY VARIABLE absorption EXPRESSION = "gas_abs_coeff"
      AUXILIARY VARIABLE rad_source EXPRESSION = "gas_rad_source"

    END TABULAR PROPERTY LIBRARY SLFM

END   PROPERTY SPECIFICATION FOR FUEGO MATERIAL gas

4.4.3.4. Custom Output

There may be additional tabulated properties you want to output for post-processing or visualization, such as mass fractions. You can output those to nodal fields with the OUTPUT LIBRARY VARIABLE commands, as shown below.

BEGIN PROPERTY SPECIFICATION FOR FUEGO MATERIAL gas
    # ...

    BEGIN TABULAR PROPERTY LIBRARY SLFM
      # ...


      OUTPUT LIBRARY VARIABLE massfraction-C2H4 AS massfraction-C2H4
      OUTPUT LIBRARY VARIABLE massfraction-CO   AS massfraction-CO
      OUTPUT LIBRARY VARIABLE massfraction-CO2  AS massfraction-CO2
      OUTPUT LIBRARY VARIABLE massfraction-O2   AS massfraction-O2

    END TABULAR PROPERTY LIBRARY SLFM

END   PROPERTY SPECIFICATION FOR FUEGO MATERIAL gas

4.4.3.5. Understanding Tabular Property Clipping Diagnostics

The tabular property evaluators allow for the evaluation of a dependent variable, $\phi$ , based on the input vector ${\bf x}$ . However, a given evaluation point ${\bf x}$ may lie outside the bounds of the table. In this scenario, $\phi({\bf x})$ is instead evaluated at the clipped point ${\bf x}^*$ , which represents the closest point to ${\bf x}$ that lies inside the range of the table.

The impact of the tabular property clipping events on the accuracy of the simulation, moreover, is reported during a Fuego simulation. For each component $i$ of the table input, a one-dimensional linear extrapolation of $\phi$ is computed as

(4.11) $\phi_{i,ext}({\bf x}) = \phi({\bf x}^*) + \dfrac{\partial\phi}{\partial{\bf x}_i}({\bf x}^*)\left({\bf x}_i - {\bf x}_i^*\right).$

The relative difference between the linear extrapolation in (4.11) and the property evaluated at the clipped point represents the relative interpolant error,

(4.12) $e_{\phi, i} = \dfrac{\phi_{i,ext}({\bf x}) - \phi({\bf x}^*)}{\vert\vert\phi\vert\vert_{\infty}},$

where $\vert\vert\phi\vert\vert_{\infty}$ is the maximum absolute value of $\phi$ within the bounds of the table. (4.12) provides information regarding the relative error in the interpolant incurred by the clipping event.

Example output of the clipping severity diagnostic for a methane plume fire simulation using the steady laminar flamelet model is shown below. The top row denotes the specific property, $\phi$ , logged in the clipping output. Each clipped component of the input vector is displayed as a separate row. For each row, information regarding logarithmic spacing, constructed table ranges, and the observed range used in the simulation are displayed for each component. For example, the example output shows that dissipation_rate_stoich_mean is logarithmically spaced. The constructed table ranges, displayed in logarithmic terms, vary from $-6.908$ to $2.830$ . The actual observed ranges required during the simulation, however, vary as widely as $-36.84$ to $21.69$ .

The range of values required during a simulation, however, provides limited information on the impact of the clipping event on the simulation. The total number of clipping events and the minimum, maximum, and average values of the relative interpolant error described in (4.12) are presented in the last four columns. This information provides a better metric on the error induced in the clipping event than the range of values required alone. While the required input range for enthalpy_defect_stoich_mean in the example output may seem more severe than dissipation_rate_stoich_mean, the relative interpolant error is no greater than $0.4\%$ in magnitude. For dissipation_rate_stoich_mean, however, the relative interpolant error is as great as $23.64\%$ . In the Fuego logfile, this is marked as a MODERATE severity level warning. This informs the user that errors from property evaluation clipping events may impact the accuracy of a simulation.

Listing 4.1 Example clipping severity output from a Fuego simulation using the steady laminar flamelet model.

 ------------------------------------------------------------------------------------------------------------------------------------
 |                                                             density                                                              |
 ------------------------------------------------------------------------------------------------------------------------------------
 |                              |                    Input Ranges                      |          |     Rel. Interpolant Err.       |
 ------------------------------------------------------------------------------------------------------------------------------------
 |            Input             | Log? |    Table Range*     |     Observed Range*     |  Count   |   Min    |    Max    |   Avg    |
 ------------------------------------------------------------------------------------------------------------------------------------
 | dissipation_rate_stoich_mean |  Yes |     [-6.908, 2.830] |         [-36.84, 21.69] | 30802400 | -0.8716% |    23.65% |  -6.584% |
 | enthalpy_defect_stoich_mean  |   No | [-2.308e+06, 0.000] | [-4.408e+16, 1.707e+16] |  5012642 | -0.3923% | 0.005572% | -0.1500% |
 ------------------------------------------------------------------------------------------------------------------------------------