FDS Validation Process - firemodels/fds GitHub Wiki

This is a summary of how to run and process the FDS validation cases. These cases are simulations of a variety of experiments. These cases are run and processed with each minor release of FDS.

Note that if all you want to do is compile the FDS Validation Guide, make sure you have all the software except the Fortran compiler, check out the FDS Repository, and skip to the last step, "Compiling the FDS Validation Guide."

All of the input files are located in the Validation folder of the FDS Repository. The routines used to automate this process are mainly shell scripts that are appropriate for a unix or linux operating system. Running and processing the Validation Suite on a Windows PC would require the various scripts to be converted to ".bat" files.

Note that this wiki describes how to run the cases that have already been set up. To set up your own case(s), follow the guidance given in the wiki Validation Case Setup Example.

Required Software

  • Git client and an account on GitHub
  • Fortran 2008 compliant compiler (You need this only if you are going to run cases)
  • Intel MPI or Open MPI libraries
  • PBS (Portable Batch System) for job scheduling. At NIST, we use a version of OpenPBS called TORQUE. You only need the job scheduler if you plan to run the validation cases.)
  • Matlab
  • LaTeX, preferably PDF-LaTeX.

Initial Tasks

The process has a number of prerequisite steps:

  • Check out or update the fds, exp, and out repositories under the firemodels organization at GitHub. The instructions can be found at Git Notes Getting Started.
  • Add to your .bashrc file the environment variables for the full paths to your git repositories:
    export FDSSMV=/home/.../firemodels/fds
    export FIREMODELS=/home/.../firemodels
  • If you plan to run the validation cases, compile FDS by running the script make_fds.sh in the appropriate folder of the Build directory. You may have to modify the run scripts if your executable is different than that which is set. The default is currently for 64 bit linux.

Organization

Each sub-directory under fds/Validation represents an experimental test series. The experimental data is kept under version control in a neighboring repository with the same sub-directory structure called firemodels/exp. In the fds repo under fds/Validation/CASENAME/ you will see a folder called FDS_Input_Files. You will also see a couple of bash scripts that run the cases and move the resulting output files to the repository called firemodels/out.

Running the Cases

Unlike the Verification Suite, there is no single script that runs all the Validation cases. There are too many, and it requires running parallel jobs over a cluster of computers. Instead, do the following:

  • cd to fds/Validation in the fds repo
  • One by one, descend into the folders. Each validation case contains a linux/unix shell script called Run_All.sh which automatically runs the input files in a directly called Current_Results which is created automatically by the script. These scripts were designed for a linux batch queuing system.

Processing the Output

  • cd to fds/Validation
  • Type: ./Process_All_Output.csh or process individual cases by running ./Process_Output.sh from within the sub-folders. Make sure that the file is executable. Otherwise, just type: chmod +x *sh. The Process_Output.sh script will copy the output files from Current_Results into the corresponding sub-directory in the neighboring firemodels/out repository (where output files are kept under version control).

Compiling the FDS Validation Guide

You do not have to rerun the Validation Suite if you just want to compile the FDS Validation Guide. But you do have to run the Matlab script FDS_validation_script.m to make all the figures. Here is how you do it:

  • Start up Matlab and cd to fds/Utilities/Matlab
  • Type: FDS_validation_script at the Matlab command prompt. The script takes about 30 minutes to run.
  • cd to fds/Utilities/Scripts and execute the shell script validation_git_stats.sh. This script creates a table for the FDS Validation Guide listing the git hash of the FDS version and the date that each validation case was run.
  • cd to fds/Manuals/FDS_Validation_Guide and at the command prompt type: make_guide.sh. This script runs pdflatex and bibtex such that the FDS Validation Guide is fully compiled with all cross-references properly established.
  • Inspect the various plots and graphs in the Guide for accuracy.