Appendix: Output Data

During the running of a simulation, there is a variety of information that is output by the code which can be used for monitoring the execution of the code as well as evaluating the flow solution. In the following sections, we give a detailed description of the information which is available.

Data Printed to Standard Output

When issuing the command to run the stream code, one should normally re-direct standard output and standard error to a log file so that this information is saved for both real-time monitoring and later analysis should some problem occur during execution of the code. One can do this by using a command like the following on the command line or in an execution script:

mpirun -np 1 stream -q solution caseName >& caseName.log &

Upon examination of the log file, one will see several types of information, each detailed in the following sections.

Residual Data

The primary means of evaluating whether the code is operating properly is to examine the residual data for the run. A residual line in the log file begins with the characters R: and is followed by the residual information. For the iterative solver Stream, the format of the residual line is as follows:

R: n it uRes vRes wRes ppRes eRes kRes omegaRes yRes

The table below provides the definitions of the residual variables shown above. Refer to the last column in the table for information which indicates the conditions under which the specific values will be output.

Residual Variable Definitions
Variable	Description	Output
n	Time step number	Always
it	Iteration number	Always
uRes	Momentum eq. x-component residual	Always
vRes	Momentum eq. y-component residual	Always
wRes	Momentum eq. z-component residual	Always
ppRes	Pressure-correction residual	Always
eRes	Energy eq. residual	Compressible flow
kRes	Turbulent kinetic energy eq. residual	Turbulent flow
omegaRes	Specific dissipation rate eq. residual	Turbulent flow
yRes	Species eq. maximum residual	Multi-species mixture

For the solver, the residuals for all equations except pressure-correction are defined as the sum over all cells of the absolute value of the corresponding residual for each of the cells in the domain. The cell residual is defined as the right-hand side minus the left-hand side of the discretized cell equation. For the solver, the pressure correction residual is computed as the sum over all cells of the absolute value of the discretized continuity equation for each of the cells in the domain.

By default, the residuals sent to standard output are not normalized. To normalize the residuals based on characteristic values pertinent to the problem at hand, one can use the run control file variable referenceValue as follows:

referenceValue: <L=2.0, rho=10.0, v=3.0, h=1000.0, k=0.01,omega=2000.0>

This variable defines the pertinent reference values which are used to normalize the total solution residuals that are printed to standard output. Refer to the table below for a description of how these reference values are used. Note that there is no residual reference value required for species mass fraction since these values always remain in the range of zero to unity.

Residual Normalization Reference Values
Residual Variable	Description
uRes, vRes, wRes	\(\rho v^{2} L^{2}\)
ppRes	\(\rho v L^{2}\)
eRes	\(\rho v h L^{2}\)
kRes	\(\rho v k L^{2}\)
omegaRes	\(\rho v \omega L^{2}\)
yRes	\(\rho v L^{2}\)

Regardless of whether the residuals have been normalized or not, when monitoring the residual values to determine acceptable convergence of the simulation, use the following guidelines. For steady-flow simulations in which one is using maxIterationsPerTimeStep=1, look for approximately three to four orders of magnitude drop in each of the residuals from their maximum value in the simulation to indicate complete convergence. While running the simulation past this level of convergence will continue to refine the solution, changes in the solution after this point will generally be very minor. For unsteady simulations in which maxIterationsPerTimeStep>1 one should also look for approximately three to four orders of magnitude drop in the residuals within each time step in order to eliminate the iterative (SIMPLE) error in the solution and give the full time-accurate behavior of the temporal differencing scheme.

Regarding complete convergence of a simulation, it is important to note that the above levels of residual drop can usually be achieved on model problems with ideal meshes. For non-model problems employing engineering meshes, it is often possible to achieve only two orders of magnitude residual drop, sometimes even less. This apparent lack of convergence is often caused by very localized problematic regions which may or may not impact a significant portion of the problem domain. To evaluate the suitability of the convergence, one will have to resort to more sophisticated measures such as a direct examination of the distribution of the cell residuals throughout the domain to determine the extent of non-convergence.

Integrated Data

During the simulation, a variety of integrated data is also redirected to standard output based on the value of the run control file variable print_freq, which is used as follows (default value shown):

print_freq: 100

If this line is not present in the run control file, then the default value will be used. Integrated data is output when the expression (n mod print_freq)? = 0 evaluates to true, where n represents the time step number. There are two forms of data that are output, integrated volume data and integrated boundary data. Integrated volume data will appear as follows:

Integrated Volume Data

Integrated Volumetric Data (Complete Domain)
  total volume = 6.2100e-07 mˆ3
  total mass = 3.8311e-05 kg
  total energy = -1.6704e+01 J
  total enthalpy = -1.2421e+01 J
  total species masses: [H2=1.0000e-06,O2=3.0000e-06,H2O=3.4311e-05]

These values represent the total amount of the specified quantity that is currently in the complete domain and are computed based on a summation over all cells of the quantity in question. Total energy is defined as the total internal energy of the flow and does not include the kinetic energy of the bulk fluid motion. The same applies to total enthalpy. For incompressible flow simulations, these two quantities will be zero. In addition, for pure-fluid simulations, the total species masses information will not be output.

Integrated boundary data is provided for each individual boundary condition patch as well as boundary condition patch type. For example, for a two-dimensional incompressible lid-driven cavity flow simulation consisting of a box with a sliding lid and three no-slip walls, one might have the following boundaryCondition variable in the run control file:

Sample Boundary Condition Specification for Integrated Boundary Data

boundary_conditions:
<
BC_1=noslip, // left wall
BC_2=noslip, // right wall
BC_3=noslip, // bottom wall
BC_4=incompressibleInlet(v=-1.0 m/s), // lid
BC_5=symmetry, BC_6=symmetry // symmetry boundaries
>

In this case, one would see output for individual boundary condition patches such as the following:

Sample Specific Integrated Boundary Data

Integrated Boundary Data (BC_1)
  total area = 1.0000e+00 mˆ2
  mass transfer = 0.0000e+00 kg/s
  energy transfer = 0.0000e+00 W
  pressure force = -1.3380e-02 0.0000e+00 0.0000e+00 N
  viscous force = 2.7312e-06 1.6104e-03 -3.1117e-11 N
  total force = -1.3377e-02 1.6104e-03 -3.1117e-11 N

as well as for the collection of all no-slip boundaries such as the following:

Sample Boundary-Type Integrated Boundary Data

Integrated Boundary Data (noslip_BC)
  total area = 3.0000e+00 mˆ2
  mass transfer = 0.0000e+00 kg/s
  energy transfer = 0.0000e+00 W
  pressure force = -3.6021e-02 -3.2994e-06 0.0000e+00 N
  viscous force = 3.6243e-05 -9.7420e-04 2.4459e-11 N
  total force = -3.5985e-02 -9.7750e-04 2.4459e-11 N

It is important to note the conventions associated with these quantities. Mass transfer is defined as the mass flow rate leaving the domain. Thus, for inlet boundaries, one should see a negative value for this quantity and a positive value for outlet boundaries (assuming no major re-entrant flow occurs at the outlet). Energy transfer is defined as the sum of the convective and diffusive internal energy transfer rates and is positive for a net transfer leaving the domain through the boundary. Thus, for no-slip boundaries, the energy transfer value amounts to simply the wall heat flux entering the boundary from the fluid. The pressure, viscous and total forces are defined as forces by the fluid on the boundary.

Field Data Written to Output Directory

During the simulation, nodal field data interpolated from the cell center and boundary face data is written to the output directory based on the value of the run control file variable plot_freq, which is used as follows:

plot_freq: 100

This variable is an optional variable in that there is no default value. If this variable is not included in the run control file, there will be no field data written to file. Field data is output when the expression (n mod plot_freq)? = 0) evaluates to true, where n represents the time step number. It is important to note that data is written at the beginning of the time step, so that the variables that are written represent the state of the simulation before the variables are updated at the new time step. The directory to which field data is written is called /output and can be found in the directory from which the simulation was initiated. This directory will be created if it is not already present. Field data is always written for default variables and optionally written for non-default variables based on user specification with the run control file variable plot_output, which is used in a manner like the following:

plot_output: k, omega, viscosityRatio, laminarViscosity

The table below summarizes many of the variables which can be output, including their status as either a default or non-default variable. The default column in the table indicates variables that are automatically output when they applicable to a simulation. Default variables do not need to be specified in the plot_output line in the run control file.

Common Field Variable Output
Variable	Description	Default
`a`	Speed of sound	Yes
`cfl`	CFL number	No
`cp`	Specific heat	No
`hResidual`	Energy eq. residual	No
`hResidualTT`	Energy eq. turn-over time	No
`k`	Turbulent kinetic energy	No
`kclip`	Turbulent kinetic energy clipped flag	No
`kconduct`	Thermal conductivity	No
`kineticEnergy`	Kinetic energy	No
`kResidual`	Turbulent kinetic energy eq. residual	No
`kResidualTT`	Turbulent kinetic energy eq. turn-over time	No
`laminarViscosity`	Material viscosity	No
`omega`	Specific dissipation rate	No
`omegaclip`	Specific dissipation rate clipped flag	No
`omegaResidual`	Specific dissipation rate eq. residual	No
`omegaResidualTT`	Specific dissipation rate eq. turn-over time	No
`mix`	Species mass fractions	Yes
`pg`	Gauge pressure	Yes
`pPrime`	Pressure-correction	No
`pResidual`	Pressure-correction eq. residual	No
`pResidualTT`	Pressure-correction eq. turn-over time	No
`r`	Density	Yes
`t`	Temperature	Yes
`v`	Velocity	Yes
`viscosityRatio`	Turbulent/laminar viscosity ratio	No
`vort_mag`	Vorticity magnitude	No
`vResidual`	Velocity eq. residual	No
`vResidualTT`	Velocity eq. turn-over time	No

Should one wish to prevent the output of default variables (to save disk space), one may use the run control file variable plot_output_exclusive in a manner like the following:

plot_output_exclusive: r, v

In this example, the variables density and velocity are the only variables that are output. One final run control file variable of interest is the variable plot_modulo, which can be used to restrict the number of data files that are written to the /output directory. This variable is used as follows (default value shown):

plot_modulo: 0

Valid values include any integral numeric value greater than or equal to zero. When field data is scheduled to be written out according to the value of plot_freq described above, the following formats are used for the file names for scalar and vector variables.

Field Data File Name Formats

variable_sca.extension_casename
variable_vec.extension_casename

If plot_modulo=0, the extension is given the same value as the time step number. In this case, unique file names for each scalar and vector variable will be written to the /output directory for each time step for which data is requested. Thus, for example, if one wanted to save data every 1000th time step for the entire simulation, one would set plot_modulo=0 and plot_freq=1000. When the value of plot_modulo is greater than zero, the extension is computed by the expression (extension=n mod plot_modulo). Thus, if one wanted to save data every 100th time step for the most recent 1000 time steps, one would set plot_modulo=1000 and plot_freq=100. In this case, the extension number would cycle between the values 100, 200, 300, 400, 500, 600, 700, 800, 900, 0 for the duration of the simulation.

Boundary Data Written to Output Directory

In addition to field data, certain limited nodal boundary data is written to the /output directory for no-slip boundaries. Consult the table below for a list of variables and their definitions. Boundary data output is also governed by the run control file variables plot_freq and plot_modulo which are used in the same manner as described in the section above for field data. Boundary data can also be written more frequently than field data by using the run control file variable boundary plot_freq in a manner like the following (default value shown):

boundary_plot_freq: 10000000

The large default value effectively prevents this variable from affecting boundary output unless the user specifies a more realistic value. As an example, assuming one had a value of plot_freq=100 and set a value of boundary_plot_freq=75, boundary output would be scheduled both at every 100th time step as well as at every 75th time step. When boundary data is scheduled to be written out according to the value of plot_output and boundary_plot_output, the following formats are used for the file names for scalar and vector variables:

Boundary Data File Name Formats

variable_bnd.extension_casename
variable_bndvec.extension_casename

Computation of the extension is done in the same manner as described above for field data using the variable plot_modulo.

Boundary Variable Output
Variable	Description	Type
`pw`	Wall pressure	Scalar
`qdot`	Heat flux to the wall	Scalar
`tau`	Wall shear stress	Vector
`tw`	Wall temperature	Scalar
`yplus`	Wall \(y^{+}\) value	scalar

Probe Data

Solution information at selected points in the domain can be monitored through time by using the run control file variable probe. This variable allows one to place an arbitrary number of probes throughout the domain. The syntax for the usage of this variable is as follows:

Probe Variable Syntax

probe: <probe0=[0.0, 0.0, 0.0],
        probe1=[0.5 inch, 0.5 inch, 0.5 inch],
        probe2=[1.0 ft, 1.0 ft, 0.5 ft]>

where the vector location provided specifies the location of the probe. Units for the vector components can be optionally provided so the user does not have to do manual conversion if the grid is provided in dimensions other than meters. If units for a probe are not provided, the default unit of meters is assumed for the probe. Units may be specified differently for each probe. Probe naming is up to the user, although the naming convention shown above is conventionally used. For each probe, a data file with the name of the probe as prefix and extension .dat will be created in the directory from which the simulation was initiated. In the above example, one would see files probe0.dat, probe1.dat, and probe2.dat when data first begins to be generated. The format for data entries written to the probe files is as follows:

n t T p rho a v pos dist y0 y1 ...

Refer to the table below for the definitions of the data entries. Probe data is not computed at the exact location of the probe via interpolation from nearby cells. The data at the center of the nearest cell to the probe is what is displayed in the probe file. The center of this cell is located at the value pos, and the distance from the cell center to the requested probe position is given by the value dist. While probe positions may be specified with arbitrary units, the values of pos and dist are always expressed in meters in the probe output files.

Probe Variable Definitions
Variable	Description	Type	Units
`n`	Time step number	Scalar	–
`t`	Solution time	Scalar	s
`T`	Temperature	Scalar	K
`p`	Pressure	Scalar	Pa
`rho`	Density	Scalar	\(\frac{kg}{m^3}\)
`a`	Speed of sound	Scalar	\(\frac{m}{s}\)
`v`	Velocity	Vector	\(\frac{m}{s}\)
`pos`	Nearest cell center	Vector	m
`dist`	Distance from probe to cell center	Vector	m
`y0 y1 …`	Species mass fractions	Scalar	–

The frequency of data output to the probe data files is controlled by the run control file variable probe_freq, which is used in a manner like the following:

probe_freq: 100

Probe data is output when the expression (n mod probe_freq)? = 0 evaluates to true. With the value above, one would see data entries in the probe output files for time step 0 (initial condition) as well as time steps 100, 200, … . It is important to note that data values corresponding to a given entry represent the state of the solution at the beginning of the time step before the governing equations have been solved to update the solution. In other words, the data values correspond to the solution at the end of the previous time step.

Turnover Time

The Stream solver provides an output that assists users in assessing any convergence-related problems they may encounter while running cases. The turnover time metric provides the user with a cell-to-cell assessment of the convergence of each differential equation being solved.

The turnover time metric output variables use the following naming convention <governingEquation>ResidualTT. Examples of the variables that are available in the Stream solver are shown in the table below. The turnover time metric output variables are not output by default and must be specified in the plot_output variable.

Turnover Time Metric Field Variable Output
Variable	Description	Module
pResidualTT`	Pressure-correction eq.	Main Code
`vResidualTT`	Momentum eq.	Main Code
`tResidualTT`	Temperature eq.	Main Code
`hResidualTT`	Total Enthalpy eq.	Main Code
`eResidualTT`	Total Energy eq.	Main Code
`omegaResidualTT`	Omega eq.	Main Code
`kResidualTT`	Turbulent Kinetic Energy eq.	Main Code
`epsilonResidualTT`	Epsilon eq.	Main Code

Consider the case of the turnover time scale metric for the pressure-correction equation.

\begin{align*} \text{TurnoverTimeMetric} &= \log_{10}\left(\frac{\rho V_{\text{cell}}}{R_p} / \tau_{\text{ref}} \right) \\ &= \log_{10}\left(\frac{\tau_{\text{depletion}}}{\tau_{\text{ref}}}\right) \end{align*}

Where \(V_{\text{cell}}\) is the cell volume, \(\rho\) is the cell density, \(R_p\) is the residual of the integrated differential equation over the cell (the subscript p simply denoting that it is the pressure-correction equation residual), and \(\tau_{\text{ref}}\) is a characteristic time scale of the flow, such as the flow-through time. A flow-through time is simply an estimate of the time it would take for the fluid to flow through the domain. For many domains this can be estimated using the inlet velocity and the domain length scale. This characteristic time scale value must be provided by the user in the run control file using the turnoverTimeScale in the diagnostics variable as shown below. The units of the variable are assumed to be in seconds.

diagnostics: <turnoverTimeScale=0.1>

The depletion timescale is defined as \(\tau_{\text{depletion}} = \frac{\rho V_{\text{cell}}}{R_p}\) and is used here to simplify expressions.

The depletion time scale has units of seconds and can be thought of as the time it would take for the residual to deplete the cell of its contents for the governing equation. In this case, it would be the time for the residual to deplete the mass of the cell. The size of the residual is representative of the level of convergence that has been obtained for the governing equation in a particular cell. If a governing equation in a cell is converged to machine-accuracy at any time instant, the value of \(R_p\) will be essentially zero, implying an infinite depletion time. The ratio of the depletion time to the turnover reference timescale gives an intuitive sense of the level of convergence of the cell. The ratio should tend towards very large values in the case of a highly converged cell.

Stream outputs the logarithm of the ratio defined by the TurnoverTimeMetric. Based on this definition, the table below shows the correspondence between the convergence within a cell and the value of the turnover time metric output variable. This sometimes is not possible for flows with complex geometries, but for a converged simulation most of the cells in domain should have a value greater than zero.

Rule-of-Thumb for Turnover Time Metric
Range	Assessment
`TurnoverTimeMetric` < -1	Poor convergence
-1 < `TurnoverTimeMetric` < 0	Fair convergence
0 < `TurnoverTimeMetric` < 1	Good convergence
`TurnoverTimeMetric` > 1	Excellent convergence

One caveat is to remember that this variable is provided as a quick metric to estimate the level of convergence within the simulation domain. In some instances, the characteristic reference timescale might vary within the domain such that in certain regions the timescale is very large and in others it is very small. If you use the largest timescale to normalize the turnover time metric variable for a case like this, it can appear that the region with the much smaller timescale is not well converged when it is converged.