Merge pull request firemodels#12034 from drjfloyd/master

FDS User Guide: Document external controls

Manuals/FDS_User_Guide/FDS_User_Guide.tex

@@ -7888,7 +7888,8 @@ \section{Advanced Control Functions: The \texorpdfstring{{\tt CTRL}}{CTRL} Namel
 {\ct MAX}                         & Maximum value of the {\ct INPUT}s \\ \hline
 {\ct MIN}                         & Minimum value of the {\ct INPUT}s \\ \hline
 {\ct PID}                         & A Proportional-Integral-Derivative control for the {\ct INPUT}\\ \hline
-{\ct PERCENTILE}                  & Calculate the user-specified percentile for a function \\ \hline
+{\ct PERCENTILE}                  & Calculate the user-specified percentile for a function \\ \hline                & External file control, see Section~\ref{info:external_control} \\ \hline
+{\ct EXTERNAL}           
 \end{tabular}
 \end{center}
 \end{table}
@@ -8271,6 +8272,50 @@ \subsection{Freezing the Output Value, Example Case: hrr\_freeze}
 
 \input{smv_objects.tex}
 
+\section{External Control of FDS (Beta)}
+\label{info:external_control}
+\label{external_control}
+
+It is possible to externally control some aspects of an FDS simulation while the simulation is running. Any FDS input that has either a {\ct RAMP\_ID} or a {\ct CTRL\_ID} as one of its inputs can be externally controlled. A {\ct RAMP} can be externally controlled by setting {\ct EXTERNAL\_FILE} on {\ct RAMP}. A {\ct CTRL} can be externally controlled by setting {\ct FUNCTION\_TYPE='EXTERNAL'}.
+
+When external control is selected, FDS will set the value of the {\ct RAMP} or the logical state of the {\ct CTRL} based on values contained in a csv file whose name is given by {\ct EXTERNAL\_FILENAME} on {\ct MISC}. This file will be checked for new values every {\ct DT\_EXTERNAL} on {\ct TIME} seconds. Only those inputs whose values are being changed need to specified. For inputs not specified or if the file does not exist or cannot be opened (e.g., locked by the operating system during a file write), the current values will be kept. The initial values are defined with either {\ct INITIAL\_VALUE} on {\ct RAMP} or {\ct INITIAL\_STATE} on {\ct CTRL}.
+
+The csv file format is:
+\begin{lstlisting}
+	Type(1), ID(1), Value(1)
+	Type(2), ID(2), Value(2)
+	.
+	.
+\end{lstlisting}
+where {\ct Type} is either {\ct RAMP} or {\ct CTRL}, {\ct ID} is the corresponding {\ct ID} in the FDS input files, and {\ct Value} is the new output value for a {\ct RAMP} or the new logical state for a {\ct CTRL} where positive values mean the {\ct CTRL} evaluates as {\ct TRUE} and negative values mean the function evaluates as {\ct FALSE}.
+
+An example set of inputs is below:
+\begin{lstlisting}
+&MISC EXTERNAL_FILENAME='external_test_input.csv'/
+&TIME T_END=10,DT_EXTERNAL=5/
+
+&OBST XB=0.0,0.1,0,1,0,1/
+&VENT XB=0.1,0.1,0,1,0,1,SURF_ID='FLOW',CTRL_ID='VENT CTRL'/
+&SURF ID='FLOW',VEL=-1,COLOR='BLUE',TAU_V=0/
+&CTRL ID='VENT CTRL',FUNCTION_TYPE='EXTERNAL',INITIAL_STATE=T/
+
+&VENT XB=2,2,0,1,0,1,SURF_ID='HOT'/
+&SURF ID='HOT',TMP_FRONT=1000,RAMP_T='T RAMP',COLOR='RED'/
+&RAMP ID='T RAMP',EXTERNAL_FILE=T,INITIAL_VALUE=0.081633/
+\end{lstlisting}
+In these inputs a vent with a fixed velocity is externally controlled by a {\ct CTRL} that is initially {\ct TRUE}, and a vent with a fixed temperature is externally controlled with a {\ct RAMP} with an initial ramp value that results in a temperature of 100~$^\circ$C. These vents are applied to two faces of a 1 m$^3$ box. At 5~s, the csv file is read with contents of:
+\begin{lstlisting}
+RAMP,"T RAMP"   , 1
+CTRL,"VENT CTRL",-1
+\end{lstlisting}
+This turns off the velocity vent (a negative {\ct CTRL} value means set the state to {\ct .FALSE.}) and sets the fixed temperature vent to 1000~$^\circ$C (a {\ct RAMP} value of 1 means apply the full value of {\ct TMP\_FRONT}). Note that the {\ct ID} strings are enclosed in quotes. This is only required if the string has a space or comma in it.  Results of running the case are shown in Fig.~\ref{external_control_fig}
+
+\begin{figure}[ht]
+	\includegraphics[width=3in]{SCRIPT_FIGURES/external_test_temperature}
+	\includegraphics[width=3in]{SCRIPT_FIGURES/external_test_velocity}
+	\caption[Results of the {\ct external\_test} test case]{(Left) Surface temperature. (Right) Wall velocity.}
+	\label{external_control_fig}
+\end{figure}
 
 
 \chapter{Numerical Considerations}
@@ -11898,6 +11943,7 @@ \section{\texorpdfstring{{\tt MISC}}{MISC} (Miscellaneous Parameters)}
 {\ct C\_VREMAN}                                     & Real         & Section~\ref{info:LES}                  &            & 0.07              \\ \hline
 {\ct C\_WALE}                                       & Real         & Section~\ref{info:LES}                  &            & 0.60              \\ \hline
 {\ct DEPOSITION}                                    & Logical      & Section~\ref{info:deposition}           &            & {\ct T}           \\ \hline
+{\ct EXTERNAL\_FILEMANE}                            & Character   & Section~\ref{info:external_control}     &            &                   \\ \hline
 {\ct FIXED\_LES\_FILTER\_WIDTH}                     & Real         & Section~\ref{info:LES}                  & m          &                   \\ \hline
 {\ct FLUX\_LIMITER}                                 & Integer      & Section~\ref{info:flux_limiters}        &            & 2                 \\ \hline
 {\ct FREEZE\_VELOCITY}                              & Logical      & Section~\ref{info:freeze_velocity}      &            & {\ct F}           \\ \hline
@@ -12404,8 +12450,10 @@ \section{\texorpdfstring{{\tt RAMP}}{RAMP} (Ramp Function Parameters)}
 {\ct CTRL\_ID\_DEP}                 & Character     & Section~\ref{info:RAMP_DEP_ID}              &                       &             \\ \hline
 {\ct DEVC\_ID}                      & Character     & Section~\ref{info:RAMPDEVC}                 &                       &             \\ \hline
 {\ct DEVC\_ID\_DEP}                 & Character     & Section~\ref{info:RAMP_DEP_ID}              &                       &             \\ \hline
+{\ct EXTERNAL\_FILE}                & Logical       & Section~\ref{info:external_control}         &                       &  F          \\ \hline
 {\ct F}                             & Real          & Chapter~\ref{info:RAMP}                     &                       &             \\ \hline
 {\ct ID}                            & Character     & Chapter~\ref{info:RAMP}                     &                       &             \\ \hline
+{\ct INITIAL\_VALUE}                & Real          & Section~\ref{info:external_control}         &                       &             \\ \hline
 {\ct NUMBER\_INTERPOLATION\_POINTS} & Integer       & Chapter~\ref{info:RAMP}                     &                       &  5000       \\ \hline
 {\ct T}                             & Real          & Chapter~\ref{info:RAMP}                     & s (or $^\circ$C)      &             \\ \hline
 {\ct X}                             & Real          & Section~\ref{info:GVEC}                     & m                     &             \\ \hline
@@ -12812,6 +12860,7 @@ \section{\texorpdfstring{{\tt TIME}}{TIME} (Time Parameters)}
 {\ct DT}                        & Real       & Section~\ref{info:TIME_Control}           & s           &                 \\ \hline
 {\ct DT\_END\_FILL}             & Real       & Section~\ref{info:TIME_Control}           & s           & $1.0 \times 10^{-6}$  \\ \hline
 {\ct DT\_END\_MINIMUM}          & Real       & Section~\ref{info:TIME_Control}           & s           &  {\ct 2.*EPSILON}  \\ \hline
+{\ct DT\_EXTERNAL               & Real       & Section~\ref{info:external_control}       & s           & 0               \\ \hline
 {\ct LIMITING\_DT\_RATIO}       & Real       & Section~\ref{info:Errors}                 &             &  0.0001         \\ \hline
 {\ct LOCK\_TIME\_STEP}          & Logical    & Section~\ref{info:TIME_Control}           &             & {\ct F}   \\ \hline
 {\ct RESTRICT\_TIME\_STEP}      & Logical    & Section~\ref{info:TIME_Control}           &             & {\ct T}    \\ \hline

Source/read.f90

@@ -9234,7 +9234,7 @@ SUBROUTINE READ_RAMP
          DEVC_ID_DEP = 'null'
          CTRL_ID_DEP = 'null'
          EXTERNAL_FILE = .FALSE.
-         INITIAL_VALUE = 0._EB
+         INITIAL_VALUE = -2.E20_EB
          CALL CHECKREAD('RAMP',LU_INPUT,IOS)  ; IF (STOP_STATUS==SETUP_STOP) RETURN
          IF (IOS==1) EXIT SEARCH_LOOP
          READ(LU_INPUT,NML=RAMP,ERR=56,IOSTAT=IOS)
@@ -9247,6 +9247,11 @@ SUBROUTINE READ_RAMP
          IF (EXTERNAL_FILE) THEN
             READ_EXTERNAL = .TRUE.
             RP%EXTERNAL_FILE = EXTERNAL_FILE
+            IF (INITIAL_VALUE <-1.E20_EB) THEN
+               WRITE(MESSAGE,'(A,A,A)') 'ERROR: Problem with RAMP ID:',TRIM(ID),&
+               '. Externally controlled RAMP requires an INITIAL_VALUE.'
+               CALL SHUTDOWN(MESSAGE)
+            ENDIF
             RP%LAST = INITIAL_VALUE
             RAMP_TYPE(N) = 'EXTERNAL'
          ENDIF

Utilities/Matlab/FDS_verification_dataplot_inputs.csv

@@ -133,6 +133,8 @@ d,energy_budget_tmix,Energy_Budget/energy_budget_tmix_git.txt,Energy_Budget/ener
 d,energy_budget_solid,Energy_Budget/energy_budget_solid_git.txt,Energy_Budget/energy_budget_solid.csv,1,2,Time,T_g Exact|T_w Exact,Exact {T_g}|Exact {T_w},ko|ro,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Energy_Budget/energy_budget_solid_devc.csv,2,3,Time,T_g FDS|T_w FDS,FDS {T_g}|FDS {T_w},k-|r-,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Energy Budget (solid),Time (s),Temperature (°C),0,2000,1,9.00E+01,1.00E+02,1,no,0.05 0.90,SouthEast,,1,linear,FDS_Verification_Guide/SCRIPT_FIGURES/energy_budget_solid_T,Relative Error,end,0.01,Energy Budget,m+,m,TeX
 d,energy_budget_solid,Energy_Budget/energy_budget_solid_git.txt,Energy_Budget/energy_budget_solid.csv,1,2,Time,P Exact,P Exact,ko,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Energy_Budget/energy_budget_solid_devc.csv,2,3,Time,P FDS,P FDS,k-,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Energy Budget (solid),Time (s),Pressure (Pa),0,2000,1,2.00E+04,2.40E+04,1,no,0.05 0.90,SouthEast,,1,linear,FDS_Verification_Guide/SCRIPT_FIGURES/energy_budget_solid_P,Relative Error,end,0.01,Energy Budget,m+,m,TeX
 d,enthalpy,Pyrolysis/enthalpy_git.txt,Pyrolysis/enthalpy.csv,1,2,Time,T_slab,Analytical (T\_slab),ko,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Pyrolysis/enthalpy_devc.csv,2,3,Time,T_slab,FDS (T\_slab),k-,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Surface Temperature (enthalpy),Time (s),Temperature (°C),0,4,1,0,200,1,no,0.05 0.90,SouthEast,,1,linear,FDS_Verification_Guide/SCRIPT_FIGURES/enthalpy,Relative Error,end,0.01,Pyrolysis,yd,y,TeX
+d,external_control,Miscellaneous/external_test_git.txt,Miscellaneous/external_test.csv,2,3,Time,V,Expected,ko,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Miscellaneous/external_test_devc.csv,2,3,Time,V,FDS,k-,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Wall Velocity,Time (s),Velocity (m/s),0,10,1,-2,1,1,no,0.05 0.90,SouthEast,,1,linear,FDS_User_Guide/SCRIPT_FIGURES/external_test_velocity,Absolute Error,end,0.0001,Controls,kd,k,TeX
+d,external_control,Miscellaneous/external_test_git.txt,Miscellaneous/external_test.csv,1,2,Time,V,Expected,ko,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Miscellaneous/external_test_devc.csv,2,3,Time,V,FDS,k-,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Wall Velocity,Time (s),Velocity (m/s),0,10,1,-2,1,1,no,0.05 0.90,SouthEast,,1,linear,FDS_Verification_Guide/SCRIPT_FIGURES/external_test_velocity,Absolute Error,end,0.0001,Controls,kd,k,TeX
 d,fan_test,HVAC/fan_test_git.txt,HVAC/fan_test.csv,1,2,Time,pres_1|pres_2,Ideal (pres\_1)|Ideal (pres\_2),ko|ro,0,100000,,0,100000,-1.00E+09,1.00E+09,0,HVAC/fan_test_devc.csv,2,3,Time,pres_1|pres_2,FDS (pres\_1)|FDS (pres\_2),k-|r-,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Pressure (fan\_test),Time (s),Pressure (Pa),0,60,1,-8,8,1,no,0.05 0.90,East,,1,linear,FDS_Verification_Guide/SCRIPT_FIGURES/fan_test_Pressure,Relative Error,end,0.04,HVAC,ms,m,TeX
 d,fan_test,HVAC/fan_test_git.txt,HVAC/fan_test.csv,1,2,Time,vflow1|vflow2,Ideal (vflow\_1)|Ideal (vflow\_2),ko|ro,0,100000,,0,100000,-1.00E+09,1.00E+09,0,HVAC/fan_test_devc.csv,2,3,Time,vflow1|vflow2,FDS (vflow\_1)|FDS (vflow\_2),k-|r-,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Volume Flow (fan\_test),Time (s),Volume Flow (m³/s),0,60,1,-0.08,0.08,1,no,0.05 0.90,East,,1,linear,FDS_Verification_Guide/SCRIPT_FIGURES/fan_test_Volume_Flow,Relative Error,end,0.02,HVAC,kd,k,TeX
 d,qfan_test,HVAC/qfan_test_git.txt,HVAC/qfan_test.csv,1,2,Time,pres_1|pres_2,Ideal (pres\_1)|Ideal (pres\_2),ko|ro,0,100000,,0,100000,-1.00E+09,1.00E+09,0,HVAC/qfan_test_devc.csv,2,3,Time,pres_1|pres_2,FDS (pres\_1)|FDS (pres\_2),k-|r-,0,100000,,0,100000,-1.00E+09,1.00E+09,0,Pressure (qfan\_test),Time (s),Pressure (Pa),0,20,1,-4,4,1,no,0.05 0.90,East,,1,linear,FDS_Verification_Guide/SCRIPT_FIGURES/qfan_test_Pressure,Relative Error,end,0.04,HVAC,ms,m,TeX

Verification/Controls/special_time_ramps.fds

@@ -4,6 +4,8 @@
 
 &TIME T_END=100. /
 
+&RADI RADIATION=F/
+
 &DEVC ID='t', QUANTITY='TIME', XYZ=0,0,0 /
 &CTRL ID='t-t0', FUNCTION_TYPE='SUM', INPUT_ID='t','CONSTANT', CONSTANT=-5. /
 &CTRL ID='2*pi*(t-t0)/10', FUNCTION_TYPE='MULTIPLY', INPUT_ID='CONSTANT','t-t0', CONSTANT=0.62831853 /

Verification/FDS_Cases.sh

@@ -316,6 +316,7 @@ $QFDS -p 2 -d Miscellaneous part_path_ramp_jog.fds
 $QFDS -d Miscellaneous devc_interpolation_velocity.fds
 $QFDS -d Miscellaneous devc_interpolation_temperature.fds
 $QFDS -d Miscellaneous init_overlap.fds
+$QFDS -p 2 -d Miscellaneous external_test.fds
 
 $QFDS -d NS_Analytical_Solution ns2d_16.fds
 $QFDS -d NS_Analytical_Solution ns2d_16_nupt1.fds

Verification/Miscellaneous/external_test.csv

@@ -0,0 +1,8 @@
+s,m/s,C
+Time,V,T
+0,0,100
+2,-1,100
+4,-1,100
+6,0,1000
+8,0,1000
+10,0,1000

Verification/Miscellaneous/external_test.fds

@@ -0,0 +1,32 @@
+&HEAD CHID='external_test',TITLE='Test of External Control'/
+
+&MESH IJK=10,10,10,XB=0,1,0,1,0,1,MULT_ID='M1'/
+&MULT ID='M1',I_UPPER=1,DX=1/
+
+&TIME T_END=10,DT_EXTERNAL=5/
+
+&MISC EXTERNAL_FILENAME='external_test_input.csv'/
+
+&RADI RADIATION=F/
+
+&DUMP NFRAMES=20/
+
+&CTRL ID='VENT CTRL',FUNCTION_TYPE='EXTERNAL',INITIAL_STATE=T/
+
+&SURF ID='HOT',TMP_FRONT=1000,RAMP_T='T RAMP',COLOR='RED'/
+&SURF ID='FLOW',VEL=-1,COLOR='BLUE',TAU_V=0/
+
+&OBST XB=0,0.1,0,1,0,1/
+&VENT XB=0.1,0.1,0,1,0,1,SURF_ID='FLOW',CTRL_ID='VENT CTRL'/
+&VENT XB=2,2,0,1,0,1,SURF_ID='HOT'/
+&VENT PBZ=0,SURF_ID='OPEN'/
+&VENT PBZ=1,SURF_ID='OPEN'/
+
+&RAMP ID='T RAMP',EXTERNAL_FILE=T,INITIAL_VALUE=0.081633/
+
+&DEVC XYZ=0.1,0.5,0.5,QUANTITY='NORMAL VELOCITY',ID='V',IOR=1/
+&DEVC XYZ=2.0,0.5,0.5,QUANTITY='WALL TEMPERATURE',ID='T',IOR=-1/
+
+
+&SLCF QUANTITY='TEMPERATURE',VECTOR=T,PBY=0.5/
+

Verification/Miscellaneous/external_test_input.csv

@@ -0,0 +1,2 @@
+RAMP,"T RAMP",1
+CTRL,"VENT CTRL",-1