Thursday, December 20, 2012

FDS 6 Verification and Validation

In recent years, we have formalized the process of developing and releasing new versions of FDS and Smokeview, taking our cue from the way it is done by commercial software developers. The key to this process is a set of calculations that we divide into two categories -- relatively short, simple test cases that we use to verify that the programs are properly solving the equations we've written down, and relatively long, sometimes complex cases that we use to validate the accuracy of the model by comparing with actual experiments.

The short verification cases are the sample input files that we distribute with each new bundle. They are run each night automatically by a script we call 'firebot' to catch simple coding mistakes that we inevitably make as we develop new routines. We not only run these cases, but we also automatically regenerate all the plots that you find in the FDS and Smokeview User's Guide, plus the FDS Verification Guide. Any result that falls outside of a certain tolerance is reported to all of us via email, and we then fix the problem while it is still fresh on our minds.

The longer validation cases are run with each minor release of FDS and Smokeview because it takes between one and two weeks to complete all the cases (about 800 calculations) on our 256 core linux cluster. Because these cases are run less frequently, there almost always is something amiss about one or two cases that is more difficult to diagnose. In fact, a good part of the two years we spent preparing FDS 6 was devoted to addressing discrepancies in some of our most reliable experimental data sets. As frustrating as it was, the fact that we knew about it all was due to the new process of V&V that we initiated. In the past, it was far more difficult to detect a fundamental problem with the algorithm because we did not systematically run all the cases at once and analyze the results in a consistent way. Basically, we just eye-balled things, but that does not always reveal subtle problems.

When we released FDS version 1 in 2000, we did not have a formal process of V&V. We did develop test cases, and we did compare calculations with experiment, but we did not do it in a systematic way. We felt that papers published by ourselves and others would suffice, but we soon learned that this was not the case. This lesson was reinforced when we began working with the US Nuclear Regulatory Commission on a V&V of five different fire models that are commonly used by the nuclear industry. The most important lesson we learned is that published results using older versions of the software cannot be used to justify the use of a model to the AHJ (Authority Having Jurisdiction). We cannot republish our validation papers with the release of each new version, so we decided to develop and maintain our own versions of the V&V guides that the NRC published (NUREG-1824).

Now the FDS Verification and Validation Guides are the key volumes that quantify the robustness and accuracy of the model. When we say that FDS can or cannot do something, what we really mean is that we have documented calculations that show the range and accuracy of the model for a particular application. For those of you using FDS for design or forensic applications, the FDS V&V Guides should be the first place to look to determine if FDS is appropriate for your use. Every few days someone writes to the Discussion Group asking something like, "Does anybody know if FDS can do ...?" What that person really ought to do is check the V&V Guides. The question should not only be can it be done, but also how well can it be done. FDS has alot of potential applications, but you need to check the Guides before deciding if it is applicable.

Finally, we spend a considerable amount of work putting the V&V Guides together, running the cases, working on the statistics, the scripts, and so on. We have appealed to the user community, especially the students and profs working with FDS, to help us with V&V cases. So far, the results have been disappointing. For a variety of reasons, we are not able to capture in our Guides the work with FDS that we see submitted to journals and conferences. We suspect that the main reason for this is that a student's first objective is to graduate, then maybe publish the thesis in some way. Working with us to get the results into our Guides is either a low priority or something that no one has even considered. I sometimes meet students at meetings who do not think that their thesis work is worthy of our Guides. Think again -- not only would the work be worthy in most cases, but it is a necessity. In order for us all to continue to develop and use tools like FDS and Smokeview, we all have to contribute to their upkeep. In this case, that means extending the range of application represented by the V&V cases. If you did your thesis on smoke detector algorithms, it is in your best interest to get this work into the Guides so that we can maintain the capability in future versions. If you just hack some routine into FDS 5.3.whatever, don't expect it to be accepted down the road by the AHJ. Further, owing to the relatively small size of fire protection engineering, there are probably few other engineering disciplines where a masters degree student can have his or her work put directly into practice so readily. Ask engineers in other disciplines what kinds of software packages they use and whether or not they have any means to be involved in their development. One of the appealing things about FPE is that there are so many opportunities to have an impact. To see how you can have an impact, read through the following wiki:

Friday, December 14, 2012

FDS 6 RC2 and Defining Species in FDS 6

To all of you who have provided feedback on FDS 6 RC1, thank you.  Based on feedback we have made some changes to inputs, fixed a few bugs, and have now released FDS 6 RC2.  You can download FDS 6 RC2 from the list of all available downloads.   A major set of changes from RC1 to RC2 is the specification of species.  Based on feedback on the inputs for the new lumped species capability, we have removed the SMIX input and moved the definition of lumped species to the SPEC input.

The remainder of this post will be another in our continuing series on topics in the FDS 6 Release Notes.  This post will focus on some significant changes made to species definitions in FDS 6 including the recent changes in RC2.

FDS 2 through the early versions of FDS 5 gave two options to tracking species.  You could define a primitive species that was tracked by FDS (like the water vapor from sprinklers), or you could make use of a reaction progress variable (which we termed at the time the mixture fraction).  In FDS 5.2 we began shifting, under the hood, the tracking of species from the conserved progress variables to a lumped species approach.  A lumped species is simply an equivalent gas species that represents a mixture of gasses that are always transported together in the same ratio.  For example, air can be considered as a lumped species consisting of 79 % N2 21 % O2 (and trace amounts of other gasses).  As input, however, you could still only use primitive species or access predefined lumped species by using a simple REAC line input.  In this case the predefined species were air and products.  The species were defined based upon the fuel you specified and the single-step reaction of:

Fuel + Air -> Products

For example if the fuel was propane you had:

C3H8 + 5 (O2 + 3.76 N2) ->3 CO2 + 4 H2O + 5 (3.76) N2

In this case the Air species would be the N2+O2 mixture on the left hand side of the equation (the actual species also has ambient CO2 and H2O) and the Product species was the mixture of gasses on the right hand side of the equation.

Doing this was motivated by a few factors.  First, by taking this approach we no longer needed to make use of complex state relationships to obtain the mass fractions of gasses.  Instead, simply multiplying the vector of lumped species by a transformation matrix would give the primitive species. Second, there were requests to track toxicant and irritant products (HCl, HCN, etc.) in order to compute FED and FIC. Trying to provide flexibility to add additional species within the progress variable framework would have been more difficult than the lumped species approach. Lastly, there were other development efforts to make the combustion model more flexible (which will be the subject of a future blog post) and those would be aided by a more flexible set of species inputs. 

What does all this mean for you?  If all you wish to do is use the REAC inputs for simple chemistry with the single-step combustion that was in FDS 5, the changes to species will remain under the hood.  Moving beyond the predefined species present in FDS 5, you now have the ability to define your own.  You now have two types of species that you can input, a primitive species (a single gas) or a lumped species.  For example adding the line shown below will cause FDS to track the species H2.


FDS 6 comes with a much larger set of predefined primitive species, but FDS 6 also allows you to define your own species with better control over the properties than in FDS 5.  You can also define the chemistry of the species which will enable FDS to automatically compute is molecular weight and the formula can then be used with the new REAC capabilities. For exampe:


To input a lumped species, you must first define all the primitive species and then define how those species combine to form the lumped species.  For example, the lines below create a lumped species called AIR that consists of 79 % N2 and 21 % O2.  The LUMPED_COMPONENT_ONLY=.TRUE. tells FDS that the primitive species of NITROGEN and OXYGEN are only found in a lumped species and that FDS should not allocate memory to track them separately.:


Consider this set of inputs:

The above defines three lumped species that are all H2S.  Consider a case where you needed to simulate small leaks of H2S from a variety of sources.  If the leaks are small enough that they don't change the normal ambient airflow, then you could simulate multiple leaks at once provided you had a method to distinguish one leak from another.  With the lines above you can easily define a set of species that have the same properties, but are tracked separately.  If you were to use SPEC_ID='H2S-1' on an output, you would just get that species.  If you were to use SPEC_ID='HYDROGEN SULFIDE' you would get the sum of all three of the lumped species.

In addition to the changes discussed above there are three other notable improvements to the &SPEC input.  First, you can now define temperature dependent properties for custom species (FDS 5 limited you to constant properties). Second, the definition of liquid properties has been moved from &PART to &SPEC so that all species data is processed in one location.  Third, we have added the ability to define some simple aerosol properties.  This last was done to support recent efforts in adding aerosol deposition models to FDS (to compute soot deposition).

Friday, November 9, 2012

Resources for FDS-SMV Development and Collaboration

Have you checked out the latest resources for FDS-SMV development and collaboration? It’s now more convenient than ever for students, researchers, and beta testers working with FDS-SMV to collaborate in real-time with the FDS-SMV development team while working on analytical verification cases, experimental validation cases, improvements to the code, and so on.
Here are some resources to keep you in touch with ongoing FDS-SMV development:
1) The FDS-SMV Wiki Pages are a great resource for new, interested, or current developers and collaborators. Here, you can find supplemental FDS and Smokeview compilation instructions, FDS and Smokeview research road maps, tips and guides on contributing to the verification and validation suite, instructions on how to access the subversion (SVN) code repository, and more. So, which SVN revision number should you be working with? How can you quickly gauge the status of development versions of FDS? That brings us to the next item…
2) The Firebot Build Status Wiki Page provides a performance snapshot of the latest FDS-SMV code revisions. Here you can see the status of the nightly FDS-SMV build (e.g., if a given revision was successful, had warnings, or had any other code issues). The nightly Firebot testing process is the driving force behind the continuous integration system in place for FDS-SMV. This process is described in detail in the FDS Configuration Management Plan. Essentially, the Firebot process involves a full suite of nightly tests that compile debug and release versions of FDS and Smokeview, a full run of almost 400 FDS verification cases, scripted generation of figures via Smokeview, plotting and statistical output of verification cases using Matlab, and generation of the latest FDS-SMV documentation/manuals. You can always view the latest FDS-SMV manuals via the next item…
3) The nightly FDS-SMV manuals (linked on the top of the Firebot status page) provide a way for collaborators to view the latest documentation related to FDS and Smokeview. The FDS User, Technical Verification, and Validation Guides; FDS Configuration Management Plan; and Smokeview User, Technical, and Verification Guides are built each night during the Firebot testing process. The resulting manuals can be accessed via the above link. For example, after reporting an issue with the documentation, you can verify the corrected results the very next day by viewing the nightly manuals. Important note: The content of the “unofficial” nightly manuals can change often! So, when reporting an issue with the nightly manuals, be sure to refer to the SVN revision number and date on the front pages of each guide.
These are just a few of the tools to help collaborators work with the latest versions of FDS and Smokeview. We hope that these resources make it easier for students, collaborators, researchers, beta testers, etc. to work more closely with the FDS-SMV development team. And we highly encourage those working with or planning to work with FDS development, verification, validation, etc. to contact the FDS-SMV development team early on via email or the FDS-SMV Discussion Group.

Thursday, November 8, 2012

Installing FDS 6 on Linux and Mac

As we strive to make the FDS and Smokeview experience consistent across different operating systems, the bundle downloads for Linux and Mac now make use of an installation script to install the FDS-SMV programs, documentation, and example files. The benefits of the installer script are 1) a consistent menu-driven interface to install FDS and Smokeview to a user-specified location, and 2) automatic setup of shortcuts for the "fds" and "smokeview" commands, which is consistent with the Windows version of FDS and Smokeview.

The default installation location for Linux is /home/<username>/FDS/FDS6, and the default install location for Mac OS X is /Applications/FDS/FDS6. This location can be modified during the installation process. Also, the drag-and-drop launcher program is still available on Mac OS X by extracting the archive located in /Applications/FDS/FDS6/bin/.

Detailed instructions on how to install FDS and Smokeview upon downloading the .sh installer bundles can be found on the Wiki Pages:

Installation notes for Linux:

Installation notes for Mac:


As part of our continuing series on topics in the FDS 6release notes, this blog post will focus on FDS 6 pyrolysis model.

The basic 1-D heat transfer and pyrolysis model for solid surfaces remains almost the same. However, several of the input parameters have been changed to expand the functionality and readability of the input file. The most significant change in functionality deals with the potential swelling or shrinking of the surface layers. This requires a slightly different treatment of the pyrolysis reactions' residue materials.

The purpose of the changes in the input parameters has been to support and to make use of the major developments that have taken place in the species/combustion solver. FDS 6 has much more versatile way of handling gaseous species and multiple combustion reactions than the versions before - a topic worth of a separate blog post. You can now associate the products of the burning surfaces to any of gases that are being tracked by FDS. This is true for both surfaces with specified burning rate and surfaces with pyrolysis reactions. We have tried to make the logic of using keywords, such as SPEC_ID, consistent throughout the code.

The solid products of the pyrolysis reactions are called residue. In FDS5, they were identified using a RESIDUE keyword, now using MATL_ID keyword. So, not much change here. But unlike before, the densities of the residue materials can now have a great influence on the behaviour of the pyrolysis process. Previously, the bulk density of the residue, such as a char layer, was determined by the density of the initial material layer and the effective yield of the material from one or more reactions producing it. Now, the thickness of the layer will be adjusted so that the residue material's density becomes what has been actually specified as a density of that material. Some practical applications of this feature are listed below:
• Non-charring materials will shrink as material is removed from the condensed phase to the gas phase.
• Porous materials like foams would shrink when the material melts and forms a non-porous layer.
• Some charring materials swell, i.e., get thicker, when a porous char layer is formed.
• Intumescent fire protection materials would swell significantly, creating an insulating layer.

For example, if the original material with DENSITY = 500 is completely converted into another material with DENSITY = 1000, the thickness of the layer will become half of the original. Or, if the original material with DENSITY = 1000 is completely converted into a material with DENSITY = 500, the thickness will become twice the original. You can, of course, prevent this from taking place if you know that the material will retain the original thickness. 

See the User's guide for an explanation on how the shrinking / swelling will be determined if there are more than one simultaneously reacting materials. Examples of shrinking and swelling materials are given in verification case shrink_swell.fds.

As a summary, you must pay more attention on the specification of MATL densities for the pyrolysis model than before.

Tuesday, November 6, 2012


As part of our continuing series on topics in the FDS 6 release notes, this blog post will focus on HVAC features in FDS 6. 

Through version 5.5.2, you could only specify pre-defined boundary conditions for inlet and outlet flows (i.e. temperature, species, and velocity/mass flow were explicitly defined in the input file).  There are a number of situations where these standard FDS inputs were not sufficient to model the behavior of a building: smoke can move through ducts to remote compartments and reduce their visibility, heating and cooling systems will turn on and off as temperatures change which will impact the movement and temperature of smoke, facilities that must maintain negative pressures can lose that ability as filters clog with soot, and in a multicompartment ventilation system the pressurization of a compartment due to a fire will change the flow rates in the system.  In addition to limitations in the current inputs, the FDS leakage model had stability issues with large leakage areas or complicated arrangements of leakage paths.

To address these limitations and to generally improve the ability of FDS to model buildings, an HVAC submodel was developed.  The first version of the model was released in FDS 5.5.3.  This model was limited in its functionality and did not work with MPI versions of FDS.  Development has since continued, and FDS 6 contains an improved HVAC model with additional functionality including being compatible with the MPI versions of FDS.

With a CFD code there are a couple of approaches one could take to model HVAC systems.  One could model a system by modeling each duct using the CFD solver.  This approach would be very costly given the number of grid cells that would be required to correctly resolve the flows and pressure drops in an HVAC system. Additionally, one would have to undergo the time consuming process of verifying that one was obtaining the correct pressure drops throughout the system.  A second approach is to use a specialized HVAC solver that treats the HVAC system in a simplified manner and couples it to the CFD solver.  This second approach was used.

The HVAC model in FDS 6 is a network HVAC model based on the solver found in MELCOR (a United States Nuclear Regulatory Commission code for analyzing containment buildings).  In brief, this model treats an HVAC system as a collection of nodes and junctions.  A junction would represent a duct, and a node would represent where two or more ducts connect or where a duct is connected to the remainder of  the FDS domain.  The model solves equations for the conservation of mass, energy, and momentum of the HVAC system.  For each junction, a velocity is predicted and for each node a pressure, temperature, and set of species mass fractions is predicted.  The particular solution method currently used does not account for transport delays in a duct.  That is, whatever mass and energy enters the system during a time step, also leaves the system in that same time step.  Multiple HVAC systems can be defined in one input file and the solver will attempt to identify independent systems (e.g. systems that do not have inlets or outlets in the same pressure zone) in order to reduce the computational cost.

The HVAC solver is not directly coupled to the FDS solvers for pressure and species transport.  Rather the HVAC solver uses the prior time step conditions to determine the boundary conditions at each inlet and outlet to the HVAC system and the solver returns a new set of boundary conditions that FDS then uses when computing the next time step.  For simulations with pressure zones, the HVAC solver uses the prior time step rate of zone pressure change to estimate the new end of time step pressure. Provided that the FDS solution does not vary greatly between time steps (so the HVAC solver estimated pressure is close to the actual pressure determined by FDS), this coupling approach is stable.  In general this is the case, FDS time steps are typically small enough that the pressure rise between time steps is small.

With the HVAC model one can define the follow components:
  • Ducts with forward and reverse flow losses (ASHRAE and other handbooks contain tables of flow loss data for various types of ducts)
  • Nodes  (e.g. tees, inlet and outlet vents, plenums, etc.) with flow direction dependent losses (as with ducts, values can be found in various handbooks).
  • Fans with three fan models: constant flow, quadratic, and user defined.  The quadratic and user defined models will change the fan flow rate based on the inlet and outlet pressure of the fan.  This would allow, for example, FDS to reduce the flow into a compartment where a growing fire causes a pressure rise that a fan would have to work harder at to overcome.
  • Dampers (currently only fully open or fully closed)
  • Filters with the ability to define different removal efficiencies for different species as well as the impact of filter loading on the pressure drop across the filter
  • Heating / cooling coils with either a fixed amount of heat exchange or an amount computed with a simple heat exchanger efficiency model
The HVAC model has resulted in changes to two other features of FDS:
  1. The POROUS surface input has been removed.  This input was used to allow one to specify a fan in the computational domain that transferred species across it.  This is now handled by the HVAC model.  See the jet_fan.fds example case in the Flowfields subfolder in the FDS 6 Examples folder.
  2. Leakage is now handled by the HVAC model.  A leak is merely some small gap, hole, etc. that allows flow from one room to another.  From a model point of view, this can be considered as a tiny duct that connects two compartments.  By using the HVAC model rather than the prior leakage model, instabilities due to large leakage areas or complex leakage paths are avoided.  Additionally, the prior leakage model could only transfer species if the compartments were separated by a POROUS surface otherwise ambient air was moved by the leakage.  By using the HVAC model, this limitation no longer exists as the HVAC model will compute the species mass transfer.  See the leak_test.fds example case in the HVAC subfolder in the FDS 6 Examples folder.
It is recommended that if you are using the HVAC model that you review the various examples in the FDS User's and Verification Guide; the inputs for which can be found in the HVAC subfolder of the Examples folder where FDS 6 is installed.

Monday, November 5, 2012

Hydrodynamics and Turbulence

Following the announcement of the v6 beta release, we thought it might be helpful expand a little bit on some of the topics in the release notes.  Our aim here is to explain why certain changes were necessary or why certain choices were made in a way that might provide more insight than can be gleaned from just reading the formal documentation (though reading the guides is still highly encouraged!).

The focus in this article will be hydrodynamics and turbulence.  Hydrodynamics is the foundation of any CFD code, especially a reacting flow code like FDS.  Chemical species cannot react until they have mixed, and (in a diffusion flame) they cannot mix until they have been transported.  The velocity field, therefore, plays a critical role in fire dynamics.  In a model like FDS, other things being equal, the model for the turbulent viscosity determines the behavior of the velocity field and hence to a large extent the dynamics of the fire.

In v5, the turbulent viscosity was modeled by constant coefficient Smagorinsky (1963) (csmag), which has the drawback being overly dissipative (have you ever seen a 10-foot fire look like a candle flame?).  Thus, finer grid resolution was required to achieve accurate results.  But even highly resolved flames did not look qualitatively correct.  The reason: csmag is not convergent.  That is, the modeled term does not go away (as it should) when the grid is refined to the level of a DNS.

The original candidate to replace csmag was the dynamic Smagorinsky model (dsmag).  While this model added about 20% to the cost of computing the velocity field, in theory this cost could be recovered by achieving more accurate results (statistically) with coarser grid resolution.  So, dsmag was implemented and run through a battery of verification and validation tests with more or less satisfactory results.  On the plus side, we were getting very realistic-looking flames at moderate grid resolution.  But on the minus side, if the resolution was too coarse (often inevitable in engineering calculations), the flames were erratic---instead of a 10-foot flame looking like a candle, dsmag might produce an unstable ball of fire.

The solution to this dilemma came in the form of Deardorff’s model (1972), with a twist.  In the model Deardorff originally proposed, he solved a transport equation for the subgrid kinetic energy (sgs ke).  This strategy is expensive, but it allows for the inclusion of complex subgrid physics, like unresolved buoyancy production.  To avoid this cost, we employ a simple algebraic model for the sgs ke based on the scale similarity model of Bardina (1986).  The result is a model that is cheap and performs reasonably well at both coarse and fine resolution.  As an added benefit, the framework is now in place to utilize a transported sgs ke, a topic that might be worth exploring as FDS gets pushed to model large-scale outdoor flows in both wildfire and wind engineering applications.

While the new turbulence model is certainly significant, the change that really defines v6 is the new scalar transport scheme.  The ripple effects of this modification were not fully appreciated until a couple of years after the initial implementation.  What follows is the “saga of removing spurious temperature wiggles.”

Take FDS 5 and simulate a simple fire plume with open boundaries and 20 C ambient air temperature.  Now look closely at the temperature field near the corner of the burner.  You will see unphysical excursions of the local temperature to well below ambient, near 0 C.  Clearly this is undesirable.  What is not as obvious is that there are also unphysical excursions well above ambient, within the fire.  Of course, 1020 C versus 1000 C is not as dramatic a problem.

So why does this happen?  The root cause is central differencing in the solution of the density equation.  Purely centered schemes are notorious for generating dispersion errors---wiggles.  To combat this problem, v5 uses a boundedness correction which tries to prevent the scalar fields (density and species concentration) from going above or below defined limits.  With mass fractions the limits are easy to set (0 and 1).  With density there is only one hard limit (0).

In v6, we have decided to try another approach: total variation diminishing (TVD) scalar transport.  This is a fancy way of saying “we use just the right amount of upwinding.”  Pure upwind schemes are too dissipative (translation: inaccurate).  But TVD schemes are specially designed to track scalar discontinuities with minimal dispersion error and minimal dissipation.  This effectively solved the temperature wiggles problem.

Several TVD schemes are implemented in v6.  The default for LES is Superbee (Roe, 1986), so chosen because this scheme does the best job preserving the scalar variance in highly turbulent flows with coarse grid resolution.  The default scheme for DNS is Charm (Zhou, 1996) because the gradient steepening used in Superbee forces a stair step pattern at high resolution, while Charm is convergent.   A few other schemes (including Godunov and central differencing) are included for completeness; more details can be found in the Tech Guide.

These modifications were completed by the summer of 2009 (yes, you are reading that right).  It seemed at this point that we were very close to a v6 release.  Then… the wheels came off the bus.  In what we thought would be a routine pass through the verification suite, we hit a snag: our energy budget cases were off, by about 10%.  In addition, several of the validation cases now showed low upper layer temperatures---yep, by about 10%.

Hmmm.  A lot of head scratching ensued---two years, in fact, until Jason Floyd finally developed a test case that pinpointed the problem.  Imagine a T-mixer in which equal mass fluxes of a hot gas with a low cp (heat capcity) and a cold gas with a high cp mix and exit together.  The critical aspect of this case is that the flow paths are one cell thick and we artificially set the diffusivity and conductivity to zero.  Thus, any mixing is purely numerical.  What we found was that the outlet stream temperature was mass weighted instead of enthalpy weighted---there was no accounting for the variation in cp.  The pieces of the puzzle finally started to come together because another relatively recent development (actually in v5) was the inclusion of variable temperature specific heats.

The aftermath of this discovery was a torturous dissection of the energy equation (see appendix of the Tech Guide) illustrating that basic assumptions of the low-Mach number approximation can hide the effects of the numerical mixing from TVD transport schemes.  The bright side of the story is that through this analysis we were able to derive corrections for numerical mixing that force FDS to satisfy the discrete, conservative form of the sensible enthalpy equation, ultimately solving the temperature issues.

The benefit of the delayed release is that many other parts of the code were improved in the mean time.  So stay tuned for our next installment.