FireX: Merge with firemodels/master

Manuals/FDS_Technical_Reference_Guide/Appendices.tex

@@ -424,11 +424,11 @@ \chapter{Gas Phase Absorption Coefficients}
 
 By default in FDS, the pathlength, $L$, is 10~cm. It can also be specified by the user. If $T=T_{\rm rad}$ the intensity does not depend on $\kappa_{n,i,{\rm e}}$, and the value $\kappa_{n,i,{\rm e}}(T_{\rm rad})$ is therefore interpolated from the neighboring temperatures.
 
-In cases with only one band ($N$=1), the smaller of the two absorption coefficients is used:
+In cases of non-zero path length, the smaller of the two absorption coefficients is used:
 \be
    \kappa_{n,i}=\min \Big( \kappa_{n,i,{\rm P}}(Y_i,T),\kappa_{n,i,{\rm e}}(Y_i,T,L) \Big)
 \ee
-If $N>1$ or $L=0$, $\kappa_{n,i}=\kappa_{n,i,{\rm P}}$. Note that the spectral data within RADCAL are used whenever the gas mixture contains water vapor, fuel or combustion products, regardless of the number of radiation bands $N$.
+If $L=0$, $\kappa_{n,i}=\kappa_{n,i,{\rm P}}$. Note that the spectral data within RADCAL are used whenever the gas mixture contains water vapor, fuel or combustion products, regardless of the number of radiation bands $N$.
 
 \textbf{Note on wavenumber, wavelength, and frequency}: some confusion might arise when dealing with the various quantities describing the wave nature of radiation. These quantities are wavenumber $\om$, wavelength $\la$, and frequency denoted here $\nu$. Most users may be familiar with the frequency $\nu$, in units of \textit{hertz}, ${\rm Hz}$, representing the number of cycles per second. While this unit is preferred for radiation waves of low energy such as radio waves, wavelength and wavenumber are preferred for waves of higher energy. Wavenumber and wavelength are related to frequency through \cite{Penner:1959}
 \be

Manuals/FDS_User_Guide/FDS_User_Guide.tex

@@ -306,9 +306,10 @@ \subsubsection{Devices and Output}
 \chapter{Getting Started}
 \label{info:gettingstarted}
 
-FDS is a computer program that solves equations that describe the evolution of fire. It is a Fortran program that reads input parameters from a text file, computes a numerical solution to the governing equations, and writes user-specified output data to files. Smokeview is a companion program that reads FDS output files and produces animations on the computer screen. Smokeview has a simple menu-driven interface. FDS does not. However, there are various third-party programs that have been developed to generate the text file containing the input parameters needed by FDS.
+FDS is a Fortran program that solves the equations governing fire or other thermally-driven, low Mach number flows. FDS reads input parameters from a text file, computes a numerical solution to the governing equations, and writes user-specified output data to files. Smokeview\footnote{A separate document~\cite{Smokeview_Users_Guide} describes how to use Smokeview.} is a companion program that reads FDS output files and produces animations on the computer screen. Smokeview has a simple menu-driven interface. FDS does not. However, there are various third-party programs that have been developed to generate the text file containing the input parameters needed by FDS.
+
+Some third-party applications, like \href{https://www.thunderheadeng.com/pyrosim/}{PyroSim from Thunderhead Engineering}, have graphical interfaces for specifying input parameters and for viewing results. FDS is the core solver of such a package, but Smokeview would be replaced by a program that is compatible with the geometry engine used to build the model. If you are using a package like PyroSim, FDS would be installed as part of the larger package and you can skip the next section which is intended for those who want to download and install FDS and Smokeview only.
 
-This guide describes how to obtain FDS and Smokeview and how to use FDS. A separate document~\cite{Smokeview_Users_Guide} describes how to use Smokeview.
 
 \section{How to Acquire FDS and Smokeview}
 \label{info:acquire}
@@ -322,7 +323,6 @@ \section{How to Acquire FDS and Smokeview}
 \noindent
 The typical FDS/Smokeview distribution consists of an installation package or compressed archive, which is available for MS Windows, macOS, and Linux.
 
-Old versions can be kept by copying the old version's installation directly to another location so that it is not overwritten when installing a new version.
 
 
 \section{Computer Hardware Requirements}
@@ -347,6 +347,8 @@ \section{Installation Testing}
 
 If you are running FDS under a quality assurance plan that requires installation testing, a test procedure is provided in Appendix B of the FDS Verification Guide~\cite{FDS_Verification_Guide}.  This guide can be obtained from the FDS-SMV website.
 
+If you are a first-time user or you simply want to ensure that FDS and Smokeview have been installed properly on your computer, run\footnote{On a Windows computer, FDS is typically installed in a directory that is read-only for most users. Copy the sample input file and move it to a directory for which you have write-privilege.} the case called \ct{Examples/Fire/simple_test.fds} following the instructions in the next chapter. This case requires only a few tens of minutes to complete and allows you to visualize the results of a very simple fire scenario. As you learn about new features in the chapters to follow, this case can serve as a useful testbed. The text file \ct{simple_test.fds} contains parameters organized by {\em namelist} groups that are listed alphabetically in Chapter~\ref{info:namelists}. All FDS input parameters are listed in these tables, and each has a hyperlink to a section in this guide that explains its use.
+
 
 
 \chapter{Running FDS}
@@ -10545,7 +10547,7 @@ \subsection{Thermocouples}
    \frac{D_{\rm TC}}{6} \, \rho_{\rm TC} \, c_{\rm TC} \, \frac{\d T_{\rm TC}}{\d t} = \epsilon_{\rm TC} \, (U/4 - \sigma T_{\rm TC}^4) + h(T_{\rm g} - T_{\rm TC})
    \label{TC}
 \ee
-where $\epsilon_{\rm TC}$ is the emissivity of the thermocouple, $U$ is the integrated radiative intensity, $T_{\rm g}$ is the true gas temperature, and $h$ is the heat transfer coefficient to a small sphere, $h=k \, \NU / D_{\rm TC}$. The bead \ct{DIAMETER}, \ct{EMISSIVITY}, \ct{DENSITY}, and \ct{SPECIFIC_HEAT} are given on the associated \ct{PROP} line. To over-ride the calculated value of the heat transfer coefficient, set \ct{HEAT_TRANSFER_COEFFICIENT} on the \ct{PROP} line (\si{W/(m.K)}). The default value for the bead diameter is 0.001~m. The default emissivity is 0.85. The default values for the bead density and specific heat are that of nickel; 8908~kg/m$^3$ and 0.44~kJ/kg/K, respectively. See the discussion on heat transfer to a water droplet in the Technical Reference Guide for details of the convective heat transfer to a small sphere.
+where $\epsilon_{\rm TC}$ is the emissivity of the thermocouple, $U$ is the integrated radiative intensity, $T_{\rm g}$ is the true gas temperature, and $h$ is the heat transfer coefficient to a small sphere, $h=k \, \NU / D_{\rm TC}$. The bead \ct{DIAMETER}, \ct{EMISSIVITY}, \ct{DENSITY}, and \ct{SPECIFIC_HEAT} or \ct{SPECIFIC_HEAT_RAMP} are given on the associated \ct{PROP} line. To over-ride the calculated value of the heat transfer coefficient, set \ct{HEAT_TRANSFER_COEFFICIENT} on the \ct{PROP} line (\si{W/(m.K)}). The default value for the bead diameter is 0.001~m. The default emissivity is 0.85. The default values for the bead density and specific heat are that for a Type-K thermocouple; 8700~kg/m$^3$ and a linear ramp from 0.4515~kJ/kg/K at 20\,$^\circ$C to 0.6010~kJ/kg/K at 1200\,$^\circ$C, respectively. See the discussion on heat transfer to a water droplet in the Technical Reference Guide for details of the convective heat transfer to a small sphere.
 
 The above discussion is appropriate for a so-called ``bare bead''  thermocouple, but often thermocouples are shielded or sheathed in various ways to mitigate the effect of thermal radiation. In such cases, there is no obvious bead diameter and there may be multiple metals and air gaps in the construction. Usually, the manufacturer provides a time constant, which is defined as the time required for the sensor to respond to 63.2~\% of its total output signal when suddenly plunged into a warm air stream flowing at 20~m/s. The analysis and testing is typically done at relatively low temperature, in which case the radiation term in Eq.~(\ref{TC}) can be neglected and the time constant, $\tau$, can be defined in terms of effective thermal properties and an effective diameter:
 \be
@@ -13188,7 +13190,7 @@ \section{\texorpdfstring{{\tt PROP}}{PROP} (Device Properties)}
 \ct{CALIBRATION_CONSTANT}             & Real          & Section~\ref{info:bidir_probe}            &                       & 0.93                 \\ \hline
 \ct{CHARACTERISTIC_VELOCITY}          & Real          & Section~\ref{info:pressure_coefficient}   & m/s                   & 1.                   \\ \hline
 \ct{C_FACTOR}                         & Real          & Section~\ref{info:sprinklers}             & (m/s)$^{1/2}$         & 0.                   \\ \hline
-\ct{DENSITY}                           & Real          & Section~\ref{info:THERMOCOUPLE}           & kg/m$^3$              & 8908.                \\ \hline
+\ct{DENSITY}                           & Real          & Section~\ref{info:THERMOCOUPLE}           & kg/m$^3$              & 8700.                \\ \hline
 \ct{DIAMETER}                          & Real          & Section~\ref{info:THERMOCOUPLE}           & m                     & 0.001                \\ \hline
 \ct{EMISSIVITY}                        & Real          & Section~\ref{info:THERMOCOUPLE}           &                       & 0.85                 \\ \hline
 \ct{FED_ACTIVITY}                     & Integer       & Section~\ref{info:FED}                    &                       & 2                    \\ \hline
@@ -13232,7 +13234,8 @@ \section{\texorpdfstring{{\tt PROP}}{PROP} (Device Properties)}
 \ct{SMOKEVIEW_PARAMETERS(:)}          & Char.~Array   & Section~\ref{info:SMOKEVIEW_PARAMETERS}   &                       &                      \\ \hline
 \ct{SPARK}                             & Logical       & Section~\ref{info:ignition}               &                       & \ct{F}              \\ \hline
 \ct{SPEC_ID}                          & Character     & Section~\ref{info:alternative_smoke}      &                       &                      \\ \hline
-\ct{SPECIFIC_HEAT}                    & Real          & Section~\ref{info:THERMOCOUPLE}           & $\si{kJ/(kg.K)}$      & 0.44                 \\ \hline
+\ct{SPECIFIC_HEAT}                    & Real          & Section~\ref{info:THERMOCOUPLE}           & $\si{kJ/(kg.K)}$      &                     \\ \hline
+\ct{SPECIFIC_HEAT_RAMP}               & Character     & Section~\ref{info:THERMOCOUPLE}           &                       &                     \\ \hline
 \ct{SPRAY_ANGLE(2,2)}                 & Real          & Section~\ref{info:sprinklers}             & degrees               & 60.,75.              \\ \hline
 \ct{SPRAY_PATTERN_BETA}              & Real          & Section~\ref{info:sprinklers}             & degrees               & 5.                   \\ \hline
 \ct{SPRAY_PATTERN_MU}                & Real          & Section~\ref{info:sprinklers}             & degrees               & 0.                   \\ \hline

Manuals/FDS_Verification_Guide/FDS_Verification_Guide.tex

@@ -4423,6 +4423,15 @@ \subsection{Thermophoretic Settling and Deposition of Aerosols\\(\texorpdfstring
 
 This verification test consists of two test cases. The second case, \ct{aerosol\_thermophoretic\_deposition\_2}, reverses the temperature gradient. The case consists of a box 1~cm on a side with adiabatic, free-slip side walls and a 100 K temperature gradient over the height of the box. The box is filled with two gas species each having a molecular weight of 28.8~g/mol, a viscosity of $2\times10^{-5}$~\si{kg/(m.s)}, a thermal conductivity of 0.025~\si{W/(m.K)}, and specific heat of 1~\si{kJ/(kg.K)}, and zero diffusivity. One of the gas species is defined as an aerosol with a diameter of 1~$\mu$m, a solid phase density of 2000~\si{kg/m^3}, and a solid phase conductivity of 1~\si{W/(m.K)}. The initial mass fraction of the aerosol is $1\times10^{-5}$. The gas temperature is initialized to its steady-state temperature gradient. \ct{STRATIFICATION}, \ct{NOISE}, and all aerosol behaviors except for \ct{THERMOPHORETIC\_SETTLING} and \ct{THERMOPHORETIC\_DEPOSITION} are turned off. Thermophoretic settling rates are weakly dependent on the gas density. Since there is a temperature gradient, the settling rates are not uniform over the height of the box. Unlike the gravitational settling case, this means over long enough time periods the overall settling rate is not linear in time; however, for a short time period a near linear settling rate is expected and can be determined analytically.
 
+Using the equation for the thermophoretic velocity, $u_{\rm th}$, the thermophoretic velocities for the gas cells adjacent to the hot and cold walls are respectively 2.25E-4~\si{m/s} and 2.15E-4~\si{m/s}. Adjacent to the cold wall, $u_{\rm th}$ is the rate at which the aerosol deposits onto the wall. Over the simulation time of 2~s, the soot will move 4.29E-4~m which is 42.9~\% of the cell size. That fraction of the aerosol in the cell will deposit which is 5.05E-9~\si{kg/m^2}. Adjacent to the hot wall, $u_{\rm th}$ is the rate at which the aerosol leaves the cell. Over the simulation time of 2~s, the soot will move 4.49E-4~m which is 44.9~\% of the cell size. One minus that fraction of the original aerosol density in the cell will remain which is 4.98E-6~\si{kg/m^3}.
+
+The thermophorertic velocity is given by
+\be
+u_{\rm th} = \frac{K_{\rm th} \nu}{T_{\rm g}} \; \frac{\d T}{\d x}
+\ee
+where $K_{\rm th}$ is a coefficient dependent on the particle size and solid conductivity, $\nu$ is the kinematic viscosity, $T_{\rm g}$ is the cell gas temperature, and $\frac{\d T}{\d x}$ is the temperature gradient.
+
+
 \begin{figure}[ht]
 \noindent
 \begin{tabular*}{\textwidth}{l@{\extracolsep{\fill}}r}

Source/chem.f90

@@ -783,7 +783,8 @@ END FUNCTION DDTMP_TROE
 !> \brief cvode interface for ODE integrator. Call sundials cvode in serial mode.
 !> \param CC species concentration (kmol/m3) array
 !> \param ZZ_0 initial species mass fraction array (of the unbuned zone),needed for mixing+chem
-!> \param TMP_IN is the temperature of the cell (unburned zone)
+!> \param TMP_IN is the temperature of the mixed zone (For DNS it is cell temp)
+!> \param TMP_UNMIX is the unmix zone temperature
 !> \param PR_IN is the pressure
 !> \param ZETA0 is the initial unmixed fraction 
 !> \param TAU_MIX is Mixing timescale
@@ -792,13 +793,13 @@ END FUNCTION DDTMP_TROE
 !> \param TEND is the end time in seconds
 !> \param RTOL is the relative error for all the species (REAL_EB)
 !> \param ATOL is the absolute error tolerance array for the species (REAL_EB)
-!> \param TMP_OUT reactor calculated temperature at the end
+!> \param TMP_OUT reactor calculated mixing zone temperature at the end
 !> \param CHEM_TIME Chemical time scale
 !> \param WRITE_SUBSTEPS Whether to write cvode substeps. Only write for first cfd step.
 !> \param CVODE_CALL_OPTION 1:CV_NORMAL, 2=CV_ONE_STEP
 !> \details This is the interface subroutine to the other modules.
 
-SUBROUTINE CVODE_SERIAL(CC,ZZ_0, TMP_IN, PR_IN, ZETA0, TAU_MIX, CELL_MASS, TCUR,TEND, RTOL, ATOL, &
+SUBROUTINE CVODE_SERIAL(CC,ZZ_0, TMP_IN, TMP_UNMIX, PR_IN, ZETA0, TAU_MIX, CELL_MASS, TCUR,TEND, RTOL, ATOL, &
                         TMP_OUT, CHEM_TIME, WRITE_SUBSTEPS, CVODE_CALL_OPTION)
 USE PHYSICAL_FUNCTIONS, ONLY : MOLAR_CONC_TO_MASS_FRAC, CALC_EQUIV_RATIO, GET_ENTHALPY, GET_MOLECULAR_WEIGHT
 USE COMP_FUNCTIONS, ONLY: GET_FILE_NUMBER
@@ -813,7 +814,7 @@ SUBROUTINE CVODE_SERIAL(CC,ZZ_0, TMP_IN, PR_IN, ZETA0, TAU_MIX, CELL_MASS, TCUR,
 USE FSUNDIALS_NVECTOR_MOD      ! FORTRAN INTERFACE TO GENERIC N_VECTOR
 
 REAL(EB), INTENT(INOUT) :: CC(N_TRACKED_SPECIES)
-REAL(EB), INTENT(IN)    :: ZZ_0(N_TRACKED_SPECIES),TMP_IN,PR_IN,ZETA0,TAU_MIX,CELL_MASS,TCUR,TEND
+REAL(EB), INTENT(IN)    :: ZZ_0(N_TRACKED_SPECIES),TMP_IN,TMP_UNMIX,PR_IN,ZETA0,TAU_MIX,CELL_MASS,TCUR,TEND
 REAL(EB), INTENT(IN)    :: ATOL(N_TRACKED_SPECIES)
 REAL(EB), INTENT(IN)    :: RTOL
 REAL(EB), INTENT(OUT)   :: TMP_OUT,CHEM_TIME
@@ -841,7 +842,7 @@ SUBROUTINE CVODE_SERIAL(CC,ZZ_0, TMP_IN, PR_IN, ZETA0, TAU_MIX, CELL_MASS, TCUR,
 TYPE(C_PTR)                    :: USERDATAPTR  ! USER DATA CONTAINS MIXING INFORMATION
 
 REAL(EB) :: ZZ(N_TRACKED_SPECIES), EQUIV, H_IN
-INTEGER :: CVODE_TASK, NS, NTRY, MAXTRY, SUBSTEP_COUNT
+INTEGER :: CVODE_TASK, NS, NTRY, MAXTRY, SUBSTEP_COUNT, MAXTRY_FAC
 REAL(EB) :: H_G
 TYPE(USERDATA), TARGET :: USER_DATA
 LOGICAL :: ONLY_FIRST_STEP=.TRUE. ! Needed in CV_ONE_STEP
@@ -948,7 +949,7 @@ SUBROUTINE CVODE_SERIAL(CC,ZZ_0, TMP_IN, PR_IN, ZETA0, TAU_MIX, CELL_MASS, TCUR,
 USER_DATA%CELL_MASS = CELL_MASS
 ALLOCATE(USER_DATA%ZZ_0(N_TRACKED_SPECIES))
 USER_DATA%ZZ_0 = ZZ_0
-CALL GET_ENTHALPY(ZZ_0,H_IN,TMP_IN)
+CALL GET_ENTHALPY(ZZ_0,H_IN,TMP_UNMIX)
 USER_DATA%H_IN = H_IN 
 USERDATAPTR = C_LOC(USER_DATA)
 IERR_C = FCVODESETUSERDATA(CVODE_MEM, USERDATAPTR)
@@ -987,12 +988,14 @@ SUBROUTINE CVODE_SERIAL(CC,ZZ_0, TMP_IN, PR_IN, ZETA0, TAU_MIX, CELL_MASS, TCUR,
       ENDIF  
    END DO
 
-
 ENDIF
 
 IF (IERR_C /= 0) THEN
-   MAXTRY = CVODE_MAX_TRY
    ! If all internal substeps are taken try two more times. This will allow larger CFD timestep.
+   ! Make MAXTRY at least CVODE_MAX_TRY or for larger timestep (>1E-3) scale it proportionaly.
+   MAXTRY_FAC = CEILING((TEND-TCUR)/1.0E-3_EB)
+   MAXTRY_FAC = MIN(MAX(MAXTRY_FAC,1),50)
+   MAXTRY = CVODE_MAX_TRY*MAXTRY_FAC
    IF (IERR_C == CV_TOO_MUCH_WORK) THEN !CV_TOO_MUCH_WORK == all internal substeps are taken
       NTRY = 0
       DO WHILE (NTRY < MAXTRY)
@@ -1008,8 +1011,8 @@ SUBROUTINE CVODE_SERIAL(CC,ZZ_0, TMP_IN, PR_IN, ZETA0, TAU_MIX, CELL_MASS, TCUR,
 
    IF (IERR_C .NE. CV_SUCCESS) THEN
       IF (IERR_C == CV_TOO_MUCH_WORK) THEN
-         WRITE(LU_ERR,'(A, 2E18.8, A)')" WARN: CVODE took all internal substeps. CUR_CFD_TIME, DT=", CUR_CFD_TIME, (TEND-TCUR), &
-                     ". If the warning persists, reduce the timestep."
+         WRITE(LU_ERR,'(A, 2E18.8, I8, A)')" WARN: CVODE took all internal substeps. CUR_CFD_TIME, DT, MAXTRY=", CUR_CFD_TIME, &
+                     (TEND-TCUR), MAXTRY, ". If the warning persists, reduce the timestep."
       ELSE
          WRITE(LU_ERR,'(A, I4, A, 2E18.8, A)')" WARN: CVODE didn't finish ODE solution with message code:", IERR_C, &
                         " and CUR_CFD_TIME, DT=", CUR_CFD_TIME, (TEND-TCUR), ". If the warning persists, reduce the timestep."