# 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, , based on the input vector . However, a given evaluation point may lie outside the bounds of the table. In this scenario, is instead evaluated at the clipped point , which represents the closest point to 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 of the table input, a one-dimensional linear extrapolation of is computed as

(4.11)

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)

where is the maximum absolute value of 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, , 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 to . The actual observed ranges required during the simulation, however, vary as widely as to .

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 in magnitude. For `dissipation_rate_stoich_mean`, however, the relative interpolant error is as great as . 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% |
     ------------------------------------------------------------------------------------------------------------------------------------