FDS User Guide: Add calculation script for veg fuels

Manuals/FDS_User_Guide/FDS_User_Guide.tex

@@ -7159,17 +7159,19 @@ \chapter{Wildland Fire Spread}
 \section{Thermal Degradation Model for Vegetation}
 \label{vegetation_model}
 
+This section includes a relatively simple description of the thermal decomposition of a vegetative fuel. The FDS Github repository contains \href{https://github.com/firemodels/fds/blob/master/Utilities/Input_File_Tools/vegetation_chemistry.py}{a useful calculation script} for converting basic information about the vegetation into FDS input parameters.
+
 \subsection{Required Information}
 \label{veg_pyrolysis_gas_phase}
 
 To describe the solid and gas phase chemistry of wood or vegetation pyrolysis/combustion in FDS, the following information must be assumed or measured:
 \begin{enumerate}
 \item The elemental composition of the dry vegetation. Dry wood has an elemental composition (by mass) of approximately $Y_{\rm C}=0.50$ carbon, $Y_{\rm H}=0.06$ hydrogen, $Y_{\rm O}=0.44$ oxygen, and trace amounts of inorganics~\cite{Rowell:USFS_Handbook}. A global survey of a wide range of vegetation suggests that the average carbon mass fraction is approximately 0.47~\cite{Ma:BGS2018}.
-\item The char yield, $\nu_{\rm char}$, defined as the fraction of the dry mass that remains after complete anaerobic pyrolysis,
-which is specified with the parameter \ct{NU_MATL} on the \ct{MATL} line that describes the Dry Vegetation. The character string \ct{MATL_ID} on the same \ct{MATL} line indicates the name of the char. 
+\item The char yield, $\nu_{\rm char}$, defined as the fraction of the mass of dry vegetation that remains after complete anaerobic pyrolysis, which is specified with the parameter \ct{NU_MATL} on the \ct{MATL} line that describes the Dry Vegetation. The character string \ct{MATL_ID} on the same \ct{MATL} line indicates the name of the char. 
 \item The ash yield, $\nu_{\rm ash}$, defined as the fraction of the char mass that remains after complete oxidation, which is specified by \ct{NU_MATL} on the \ct{MATL} line describing the char.
-\item The elemental composition of char in terms of the mass fraction of carbon, $Y_{\rm C,char}$, oxygen, $Y_{\rm O,char}$, and inorganics (ash).
-\item The effective molecular weight, $W_{\rm pyr}$, of the fuel gas, or {\em pyrolyzate}, which is taken as a single composite gas species. Preliminary measurments~\cite{Tripi:INTERFLAM2025} suggest that the effective molecular weight of wood pyrolyzate is approximately 25~g/mol.
+\item The elemental composition of char in terms of the mass fraction of carbon, $Y_{\rm C,char}$, oxygen, $Y_{\rm O,char}$, and inorganics (ash). These values are not directly listed in the FDS input file, but rather determine the mass of oxygen that is required to oxidize a unit mass of char. In the formulae below, only the ratio of these two values is of importance.
+\item The energy released per unit mass of oxygen consumed, $E$ (kJ/kg), in the gas phase reaction of the vegetation pyrolyzate. This value is typically taken as $13\,100$~kJ/kg, but may vary for different varieties of vegetation. This value is used in calculation of the gas phase \ct{HEAT_OF_COMBUSTION}.
+\item The effective molecular weight, $W_{\rm pyr}$, of the fuel gas, or {\em pyrolyzate}, which is taken as a single composite gas species. Preliminary measurments~\cite{Tripi:INTERFLAM2025} suggest that the effective molecular weight of wood pyrolyzate is approximately 25~g/mol. This parameter is not directly input in the FDS input file; rather, the values ${\rm x''}$, ${\rm y''}$, and ${\rm z''}$ computed below are input as \ct{C}, \ct{H}, and \ct{O}, respectively, on the \ct{REAC} or \ct{SPEC} line.
 \end{enumerate}
 
 \subsection{Basic Pyrolysis Reactions}

Utilities/Input_File_Tools/vegetation_chemistry.py

@@ -0,0 +1,66 @@
+# This script calculates input parameters for an FDS simulation involving vegetative fuels.
+
+# Modify the following lines for your particular type of fuel. 
+
+Y_C = 0.497        # Mass fraction of carbon in the dry vegetation
+Y_H = 0.059        # Mass fraction of hydrogen in the dry vegetation
+Y_O = 0.406        # Mass fraction of oxygen in the dry vegetation
+Y_C_char = 0.869   # Mass fraction of carbon in the char
+Y_O_char = 0.049   # Mass fraction of oxygen in the char
+nu_char = 0.16     # Fraction of mass of dry vegetation remaining as char after complete anaerobic pyrolysis
+nu_ash = 0.0       # Fraction of mass of char remaining as ash after complete oxidation
+E = 13100          # Energy released per unit mass oxygen consumed during combustion of pyrolyzate (kJ/kg)
+W_pyr = 25         # Effective molecular weight of the pyrolyzate (g/mol)
+
+# Calculated quantities. Some of these quantities are calculated automatically by FDS and are listed here as check.
+
+Y_C_adj = Y_C*(1-nu_char*nu_ash)/(Y_C+Y_H+Y_O)
+Y_H_adj = Y_H*(1-nu_char*nu_ash)/(Y_C+Y_H+Y_O)
+Y_O_adj = Y_O*(1-nu_char*nu_ash)/(Y_C+Y_H+Y_O)
+
+x = (Y_C_adj/12)/(Y_C_adj/12 + Y_H_adj + Y_O_adj/16 + nu_char*nu_ash)
+y = (Y_H_adj   )/(Y_C_adj/12 + Y_H_adj + Y_O_adj/16 + nu_char*nu_ash)
+z = (Y_O_adj/16)/(Y_C_adj/12 + Y_H_adj + Y_O_adj/16 + nu_char*nu_ash)
+
+W_veg = (12*x+y+16*z)/(1-nu_char*nu_ash)
+x_prime = nu_char*W_veg*(1-nu_ash)/(12*(1+Y_O_char/Y_C_char))
+z_prime = 12*x_prime*Y_O_char/(16*Y_C_char)
+
+nu_O2_char = (32*nu_char*W_veg*(1-nu_ash)-44*16*z_prime)/((44-32)*nu_char*W_veg)
+
+nu_CO2 = (1+nu_O2_char-nu_ash)*(nu_char*W_veg)/44
+nu_O2 = nu_O2_char*nu_char*W_veg/32
+nu_pyr = (12*(x-x_prime)+y+16*(z-z_prime))/W_pyr
+
+x_prime_prime = (x-x_prime)/nu_pyr
+y_prime_prime = y/nu_pyr
+z_prime_prime = (z-z_prime)/nu_pyr
+W_pyr_check = 12*x_prime_prime+y_prime_prime+16*z_prime_prime
+
+nu_O2_prime = (2*x_prime_prime+y_prime_prime/2-z_prime_prime)/2
+Delta_h_pyr = (32*nu_O2_prime*E)/W_pyr
+
+print()
+print('The following values are used in the FDS input file:', end='\n\n')
+print(f"{x_prime_prime:.3f}",' x_prime_prime, carbon subscript of pyrolyzate molecule (C on REAC or SPEC line)')
+print(f"{y_prime_prime:.3f}",' y_prime_prime, hydrogen subscript of pyrolyzate molecule (H on REAC or SPEC line)')
+print(f"{z_prime_prime:.3f}",' z_prime_prime, oxygen subscript of pyrolyzate molecule (O on REAC or SPEC line)')
+print(f"{nu_O2_char:.3f}",' nu_O2_char, mass oxygen consumed per unit mass char oxidized (OXYGEN NU_SPEC on MATL line)')
+print(f"{Delta_h_pyr:.0f}",' Delta_h_pyr, pyrolyzate heat of combustion (HEAT_OF_COMBUSTION on REAC line)')
+print()
+print('The following values are not used directly and can be used to check the calculation:', end='\n\n')
+print(f"{Y_C_adj:.3f}",' Y_C_adj, adjusted carbon content')
+print(f"{Y_H_adj:.3f}",' Y_H_adj, adjusted hydrogen content')
+print(f"{Y_O_adj:.3f}",' Y_O_adj, adjusted oxygen content')
+print(f"{x:.3f}",' x, carbon subscript for the dry vegetation molecule')
+print(f"{y:.3f}",' y, hydrogen subscript for the dry vegetation molecule')
+print(f"{z:.3f}",' z, oxygen subscript for the dry vegetation molecule')
+print(f"{W_veg:.3f}",' W_veg, molecular weight of dry vegetation (g/mol)')
+print(f"{x_prime:.3f}",' x_prime, carbon subscript in char molecule')
+print(f"{z_prime:.3f}",' z_prime, oxygen subscript in char molecule')
+print(f"{nu_CO2:.3f}",' nu_CO2, moles CO2 per moles char oxidized')
+print(f"{nu_O2:.3f}",' nu_O2, moles O2 consumed per moles char oxidized')
+print(f"{nu_pyr:.3f}",' nu_pyr, moles pyrolyzate per moles vegetation pyrolyzed')
+print(f"{W_pyr_check:.2f}",' W_pyr_check, algebra check (g/mol)')
+print(f"{nu_O2_prime:.3f}",' nu_O2_prime, moles O2 per mole pyrolyzate consumed')
+