4.14.2. Setting up chemical reaction cases¶

Chemical reactions are specified in the data file (mfix.dat) by providing species aliases and chemical equations. Rate expressions are specified in one or two user defined subroutines, usr_rates.f and usr_rates_des.f, respectively. Heats of reaction are automatically calculated. Optionally, users may specify constant heats of reaction in the data file.

Tip

An overview of using legacy rrates.f files is given at the end of this section. However, this method is no longer supported.

Chemical reactions specification

There are five general steps to incorporating chemical reactions into a simulation:

Provide species names in the data file (SPECIES_G, SPECIES_S).
Assign a unique identifier (alias) to each species in the data file. (SPECIES_ALIAS_G and SPECIES_ALIAS_S)
Define chemical reaction parameters in the data file.
Define chemical reaction rates in usr_rates.f and/or usr_rates_des.f.
Use build_mfixsolver to rebuild the MFiX executable.

Note

Species names must appear exactly as given in the materials database (see the Thermochemical Properties section).

Note

Reactions are limited to homogeneous or two-phase heterogeneous reactions (e.g., species from three separate phases cannot be referenced by any single chemical reaction).

The following explains each step in more detail.

4.14.2.1. Species names¶

Provide species names in the data file (SPECIES_G, SPECIES_S).

4.14.2.2. Species identifiers¶

Each species must be assigned a unique identifier (alias).

Alias formatting restrictions:

Aliases must be unique.

Aliases are limited to 32 characters and must be a valid Fortran variable name (i.e., alphanumeric characters or underscore, and starting with a letter).

Aliases are not case sensitive.

Aliases cannot conflict with existing MFiX variable names (e.g., a species alias of MU_g will cause an error when compiling MFiX).

4.14.2.3. Reaction parameters¶

Define chemical reactions in the data file using species aliases.

Each reaction is identified by a reaction construct, and a reaction block is used to group reaction constructs in the data file. A reaction construct has the format, rxn_name{…}, where rxn_name is a unique identifier for the reaction. Reaction identifiers are limited to 32 characters and must follow Fortran variable naming convention.

Reaction input format:

MFiX processes chemical reaction data differently than other input in the data file. A reaction block indicates the start and end of the reaction input. A reaction construct groups a single reaction’s input parameters. There are two reaction block types:

@(RXNS)…@(END) – indicates continuum phase chemical reactions (all TFM gas and solids phase reactions and DEM homogeneous gas phase reactions).

@(DES_RXNS)…@(DES_END) – indicates heterogeneous DEM chemical reactions (particle/gas).

Note

A data file can only contain one reaction block of each type, whereas a reaction block must contain one or more reaction constructs.

The following keywords are available within a reaction construct.

CHEM_EQ The chemical equation, contained in quotes

DH Heat of reaction

fracDH(Phase) Fractional heat of reaction to assign to the indicated phase

Reaction construct formatting notes:

Chemical reactions are always specified as irreversible with reactants on the left and products on the right. (CHEM_EQ = “Reactants –> Products”)

An arrow or equals sign can be used to distinguish reactants from products. (Reactants –> Products or Reactants = Products)

Reversible reactions are specified as two irreversible reactions. (see below example, Athermal, gas phase, reversible reaction)
Chemical equations may span several lines by including an ampersand (&) at the end of the line. As the example below illustrates, each line of the chemical equation is contained in quotation marks and the ampersand is located to the right of the second quotation mark.
@(RXNS)                       !  Begin reaction block
CH4_Combustion {              !  Reaction 1 construct
chem_eq = "CH4 + 2O2 --> " &  !  Chemical Reaction Line 1
"CO2 + 2H2O"                  !  Chemical Reaction Line 2
}                             !  End reaction 1 construct
@(END)
Chemical equations must be enclosed within single or double quotes. CHEM_EQ = ‘Reactants –> Products’ or “Reactants –> Products”)

Equations can be split across multiple lines using the & character.

Each chemical equation is limited to 512 characters, including spaces.

Catalytic reactions should contain a species from the catalyst phase in the chemical equation with a coefficient of zero. This insures the proper assignment of the heat of reaction. (CHEM_EQ = ‘A + 0.Cat –>3.0*R’ where Cat is a catalyst phase species)

Catalyst phase species can be listed as a product, reactant, or both.

The maximum number of reactions is 100.

Several examples illustrating the data file input (steps 2 and 3) are provided below. Within the data input file, comments are preceded with an exclamation mark (!).

4.14.2.4. Build custom solver¶

Use build_mfixsolver to rebuild the MFiX executable.

See Building Custom Interactive Solver for detailed instructions on building the custom MFiX solver.

Rebuilding mfixsolver is required after making any of the following modifications:

Changing the number, order, or alias of any species in the data file.

Changing the number, order, or name of any chemical reaction in the data file.

Changing the chemical reaction rates in either usr_rates.f or usr_rates_des.f.

Note

build_mfixsolver preprocesses the data file to generate the species.inc file which is included within the usr_rates.f and usr_rates_des.f files as code. Therefore changes in the data file may result in the executable being out of date.

4.14.2.5. Extra notes¶

Below is additional reaction information.

To write out reaction rates to SPx file:

1. In the data file, mfix.dat, set NRR to the desired number of reaction rates to be written out to the file *.SPA. This number is typically less than or equal to the total number of reactions. 2. In a reaction UDF (usr_rates.f or usr_rates_des.f) assign the desired reaction information to the variable ReactionRates. ReactionRates is a two-dimensional array. The first index references the fluid cell, IJK, while the second index ranges from 1 to NRR.

Note

If the second index exceeds NRR, a run time error can result from over indexing the array. Using logical checks can eliminate potential errors!

Two of the above examples illustrate using the ReactionRates variable:

Methane Combustion: The calculated reaction rate is directly stored and a logical check is used to prevent over indexing of the ReactionRates array.
DES droplet evaporation: The calculated reaction rate is added to the storage array. Adding the calculated data to the storage variable is needed in DES since several discrete particles may exist in a single fluid cell. Again, a logical check is performed to prevent over indexing the array.

Use an existing (legacy) rrates.f file:

The legacy rrates.f file should be copied to the run directory. Additionally, the following keywords should be specified in the data file:

USE_RRATES

SPECIES_NAME(PHASE)

NMAX(PHASE)

Note

Legacy species keywords, NMAX(m) and SPECIES_NAME(n), are required when using a legacy rrates.f file. Current species keywords NMAX_g, NMAX_s, SPECIES_g, and SPECIES_s cannot be used.

Note

The only modification needed for a legacy mfix.dat and rrates.f file combination is the inclusion of USE_RRATES=.TRUE. in the data file. An example of legacy file usage can be found in: legacy_tutorials/reactor1b Legacy tutorials can be found by downloading the source tarball. They are meant to provide representative setups for older versions of MFiX (before the launch of the GUI), and are not guaranteed to run with the latest version of MFiX.

Additional remarks:

Building with chemical reaction support requires that the mfix input file be present in the run directory as the species aliases and reaction identifiers are needed to construct a species.inc file.

Species aliases and reaction identifiers must be unique. The build performs a cursory check on the supplied data and exits if non-unique entries are identified.

If any species alias or reaction identifier conflicts with an existing global variable in MFiX, an error will be reported and the code will fail to compile.

4.14.2.6. Stiff chemistry solver¶

A stiff chemistry solver has been fully integrated into MFiX. This approach first solves the convection/diffusion equations without chemical reaction source terms. A coupled set of ODEs is then directly integrated to impose chemical reactions effects. This approach may decrease simulation time by permitting larger time steps within the convection/diffusion model. However, the stiff chemistry solver may increase simulation time, especially if reactions are not stiff. Reactions are specified using the same approach outlined in the chemical reactions section.

The stiff chemistry solver is invoked by specifying the keywords STIFF_CHEMISTRY and STIFF_CHEM_MAX_STEPS

Note

The stiff chemistry solver does not support legacy rrates.f files

Note

The stiff chemistry solver is not available with DES simulations.

Additional remarks:

Variables governing ODE convergence criteria are specified as parameters in stiff_chem_mod.f found in the model/chem directory. Additional information on these parameters and their usage is available in model/ODEPACK.F.

Running your simulation in debug mode is recommended for the first time. This will catch some common programmatic errors in the usr_rates.f file. Additionally, the stiff chemistry solver checks for NaNs calculated in the usr_rates.f file.

The tutorial located in tutorials/tfm/silane_pyrolysis_2d shows how to use the stiff chemistry solver.