Follow-up on FDS 5 Release

["Kevin McGrattan" <kevin.mcgrattan@nist.gov>]

All

Earlier this week we announced the release of version 5 of FDS/Smokeview.  This is a follow-up with some additional information.

Version 5 of FDS is considerably different than previous versions (Smokeview has several new features, but is not radically 
different in terms of its overall functionality).  We actually should refer to the new version using the Roman numeral V because of 
our new emphasis on Versioning, Verification, Validation.  Consider each in turn...

Versioning.  This seems trivial, but we did not really have a version control system in place for FDS until now.  Up through version 
4, when we corrected enough bugs in FDS, we just recompiled the code and posted the new version.  We relied on the date of 
compilation moreso than the 4.02 or whatever.  The trouble with this system is that there was no way of knowing what happened 
between 4.02 and 4.03.  Major changes, or just a bug fix?  Almost all software programs you use employ a hierarchy of numbers to 
indicate the version, and we have adopted the most common system.  So now, FDS 5.1.4, for example, indicates the major, minor, and 
maintenance release (Smokeview uses the same system, but its versions need not exactly match those of FDS).  Maintenance is 
basically a bug fix, with no change in functionality.  If you ever have trouble with FDS (or Smokeview), the first thing to do is 
upgrade (simply by downloading from the "Download" page) to the latest maintenance release.  Commerical software often does this 
automatically for you when updates or patches are available.  We do not want to do this for several reasons -- we don't want to 
"take over" your machine, it takes a considerable amount of IT staff to develop and maintain this type of functionality, and there 
might be situations where you want to run the exact same version of FDS when working on a particular project.  When we release a new 
"minor" version (5.0.26 to 5.1.0, for example), this implies some change in functionality that goes beyond just a bug fix.  If you 
are in the middle of a project, you might want to consider if the change from 5.0 to 5.1 would change your results in such a way 
that would complicate a parameter sensitivity study.  An example of a change from 5.0 to 5.1 might be where we change a heat 
transfer coefficient or empirical correlation that we feel (based on V&V work) does a better job than before.  The new version of 
FDS need not produce radically different results -- but if you were assessing the affect of various input parameters the change 
might complicate your analysis.  We do not expect minor upgrades more often than every few months.  Maintenance upgrades might occur 
every few weeks.  Major, as you know, no sooner than every few years.

One additional facet of version control.  All the source code and manuals, plus miscellaneous other materials, are located in a 
central repository and under Subversion control.  What does this mean?  We now use a service of Google known as GoogleCode (links 
are at the FDS/SMV Home Page).  Each time we make even the most minor of changes to anything, we commit the change to the central 
repository and the "subversion" number of the entire FDS/Smokeview "project" is updated by 1.  This is the so-called SVN number that 
you will see printed out in the FDS and Smokeview files, and in the manuals.   It is an integer from 1 to whatever that indicates 
the "state" of the project.  It is more meaningful for us developers than the version number, 5.0.4 or whatever, because it allows 
us to "dial back" to recover the source code or manuals whenever we want to know what changed from then to now.  Who did it, why 
they did it, when they did it, and so on.  Just be aware of it, and report it whenever you send in a bug or question, along with the 
FDS or Smokeview version number, 5.0.4 or whatever.

Verification.  Version control is actually one of the many facets of Verification.  Verification, in the narrow sense, means that 
the equations of the model are being solved properly.  Verifying this involves checking all the various subroutines for accuracy, 
ensuring that bugs are not introduced as changes are made, tracking changes in the source code, and so on.  You will notice that the 
sample cases of past versions of FDS have been replaced by several dozen "verification" cases.  The FDS User's Guide describes most 
of these, and we will continue to add cases and documentation.  We want FDS users to get in the habit of running "test cases" before 
embarking on full-blown analyses.  A past problem for us has been when someone reports a bug or peculiar behavior in a calculation 
that has an input file that is thousands of lines long.  Where to even begin figuring out what is wrong?  When we compile FDS or 
Smokeview, we sometimes find errors in the various compilers we use.  However, when we report these errors to Intel or IBM or 
whomever, we cannot simply give them a 50,000 line code and say "there's a problem..."  We have to do a considerable amount of 
detective work in narrowing down the problem in such a way that the error is absolutely obvious.  During the beta testing period, 
those reporting bugs did a very good job of at least pointing us in the right direction.  That helps us solve the problem as quickly 
as possible.

Validation.  Over the past several years, the US Nuclear Regulatory Commission, along with the Electric Power Research Institute 
(EPRI), have conducted a Verification and Validation study of 5 fire models, including FDS and CFAST, the NIST zone model.  The 
reports are available from the NRC web site (a google search on NUREG-1824 will get you there).  Although the study was done with 
FDS 4, we are redoing everything with FDS 5, and we will soon release a Validation Supplement to the FDS Tech Guide.  This 
"Validation Suite" will continue to grow, and we will continually rerun these cases with minor and major releases.  The experimental 
datasets and FDS input files are available, and we urge that you use the various cases when considering whether or not FDS is 
appropriate for a given application.

This text will be added to a wiki at http://code.google.com/p/fds-smv/

Kevin


Kevin McGrattan
National Institute of Standards and Technology
100 Bureau Drive, Mail Stop 8663
Gaithersburg MD 20899
Phone: 301 975 2712
Fax:       301 975 4052