Fire Simulation for Engineers/FDS/Input File Basics



This chapter teaches the logic of FDS input file, its organization and its grammar. Then the standard reference system is explained and some tips and tricks are exposed.

Syntax of the input file
All the necessary information to perform an FDS simulation has to be contained in a single text file. The input file is saved with a name such as. There should be no blank spaces in the job name.

Data is specified within the input file by using namelist groups. Each namelist group record occupies a line of text and begins with the  character. The  must be the first character of the line of text and should be followed by the name of the namelist group. Then a comma-delimited list of the input parameters is inserted. Finally a forward slash  character closes the namelist group, as shown in the following figure:



Spaces and new lines can be freely inserted to visually format the namelist group. FDS uses the information contained between the    delimiters, the rest is ignored. Thus, comments and notes can be written outside the    delimiters. For example:

It is recommended that each namelist group be clearly commented to justify the choice of its parameters and to link it to literature references or direct experimentation. For example, comments like these:

help the reviewer keeping track of the sources of information employed by the user. By deeply commenting the code, the input file becomes the complete and only source of information about the simulated case.

The parameter values can be of the following types: Sometimes the parameters are multidimensional arrays. For example,  indicates that the third material component of the second layer is brick.
 * Integers, as in
 * Real numbers, as in
 * Groups of real numbers, as in
 * Groups of integers, as in
 * Character strings, as in
 * Groups of character strings, as in
 * Logical parameters, as in  or   The periods must be included.

To speed up data input, you can use this notation  which means that the surface is composed by three different layers made respectively of plastic, insulation and steel. The notation  means array element 1 through 3, inclusive.

A simplified notation is accepted, too. is equivalent to

These last surfaces are composed by two different layers made respectively of plastic and steel.

The code is case sensitive:  is not the same as.

To ensure that FDS reads the entire input file, add  or a comment as the last line at the end of the input file.

Writing an input file
When looking at a new scenario, first select a pre-written input file that resembles the case, make the necessary changes, then run the case at fairly low grid resolution to determine if the geometry is set up correctly.

The following file is a slightly modified and simplified version of pplume5.fds, generally included in FDS software distribution:

Not all kinds of FDS namelist groups are listed in this input files. In fact, another general rule of thumb when writing input files is to only add to the file parameters that are to change from their default value. That way, you can more easily distinguish between what you impose and FDS defaults.

In general, the namelist records can be entered in any order in the input file, but it is a good idea to organize them in some systematic way. Be aware that the order of identical namelist groups can be significant. When properties overlap the general rule is first-come, first-served.

For the sake of clarity, users often group similar namelists in homogeneous sections identified by heading comments, as shown in the former example input file.

The logic behind most FDS input files
This section presents the logic behind most FDS input files, this same logic is used for the organization of this manual.

General configuration
First, general configuration is performed.

The case receives a name via the  namelist group, the simulation time is set via the   namelist group. Other miscellaneous parameters are prescribed via the  namelist group.

Then gas phase combustion reaction is set up via the  namelist group, the radiation model is configured with.

Computational domain
Second, the computational domain is defined via the  namelist group. All FDS calculations must be performed within a domain that is made up of rectilinear volumes called meshes. Each mesh is divided into rectangular cells, the number of which depends on the desired resolution of the flow dynamics.

Some initial conditions are prescribed for the flow domain via the  namelist group.

Properties
Third, some properties are set up: This is the most challenging part of setting up the simulation: first, for both real and simulated fires, the growth of the fire is very sensitive to the thermal properties of the surrounding materials. Second, even if all the material properties are known to some degree, the physical phenomena of interest may not be simulated properly due to limitations in the model algorithms or resolution of the numerical mesh.
 * the properties of each material ,
 * the properties of extra gas species ,
 * the properties of Lagrangian particles ,
 * and the types of boundary conditions.

It is your responsibility to supply the thermal properties of the materials, and then assess the performance of the model to ensure that the phenomena of interest are being captured.

Solid geometry
Fourth, the solid geometry is entered via,  ,   namelist groups.
 * A considerable amount of work in setting up a calculation lies in specifying the geometry of the space to be modeled and applying boundary conditions to these objects. The geometry is described in terms of obstructions to the gas phase flow.
 * A boundary condition needs to be assigned to each bounding surface of the gas phase domain describing its thermal properties. Both solid obstruction faces and the exterior boundaries of the computational domain need a boundary condition assigned. A fire is just one type of boundary condition.

Control logic
Fifth, some control logic and automation is introduced via,  ,   namelist groups: devices can be used to control various actions, like creating and removing obstructions, or activating and deactivating fans and vents.

Output
Finally, the user prescribes the output quantities. All output quantities must be specified at the start of the calculation. In most cases, there is no way to retrieve information after the calculation ends if it was not specified from the start. Much like in an actual experiment, the user must decide before the calculation begins what information to save.

In summary
The following table summarizes this logic and shows a proposed systematic organization of an input file in sections:

Keep it simple
Novice users tend to forget that FDS is not a Computer Aided Design (CAD) tool, but a CFD code.

First, not all geometrical details, all physical and chemical properties of all involved objects need to be entered in the input file.

Looking at the example proposed in Figure [fig:Modeling-reality-in-FDS5], chair and table frame effect on the fluid flow can be considered negligible. On the contrary, the influences to fluid flow of the separating wall, the table top and seats can become important, depending on the objective of the analysis.

So, the first step of the analysis process is to formulate the problem by seeking answers to the following questions:
 * What is the objective of the analysis?
 * What is the easiest way to obtain that objective?
 * What input data needs to be included?

Approximations of the geometry and simplifications of the properties are always required to allow an analysis with reasonable effort.

It is better to start off with a relatively simple file that captures the main features of the problem without getting tied down with too much detail that might mask a fundamental flaw in the calculation.

Initial calculations ought to be meshed coarsely so that the run times are less than an hour and corrections can easily be made without wasting too much time. As you learn how to write input files, you will continually run and re-run your case as you add in complexity.

Each model, its input data
When entering data into the input file, it is suggested to always consider how models inside FDS will use that data.

For example: Imagine that the wall separating room 1 and room 2 of Figure [fig:Modeling-reality-in-FDS5] is 0.19m thick. Thus, during the calculation:
 * The hydrodynamic model needs to know which cells of the computational domain are open to fluid flow and which are instead occupied by solid obstructions. The geometry is discretized and the maximum resolution is the grid cell size.
 * The heat transfer model needs the characteristics and the thicknesses of the bounding surfaces of the flow domain to perform heat transfer calculation.
 * Taken the cell size equal to 0.30 m, the hydrodynamic model considers that wall as if it was 0.30 m thick, because the geometry must conform to the underlying grid. That information is used to obstacle the fluid flow.
 * The heat transfer model performs a one-dimensional heat transfer calculation of the wall using the real 0.19 m thickness and the material properties.

It may sound strange to novice users, but that wall is… both 0.30 m and 0.19 m thick for FDS.

Units of measurement
FDS employs the units of measurement from the International System (SI).

Lengths are expressed in m, time in s, mass in kg, temperature in °C, pressure in Pa, heat in kJ, power in kW, conductivity in W/m/K, heat flux in kW/m2, molecular weight in g/mol, ...

This manual contains a comprehensive list of frequent namelist parameters and their units. For a complete list consult the documentation.

Reference coordinate system
FDS coordinate system conforms to the right hand rule. By default, the z axis is considered the vertical.

For computational reasons, it is always preferable for the longest horizontal dimension of the model be aligned with the x axis. This often shortens the calculation time.

Prescribing geometric entities
Many namelist groups extend their action to volumes, faces, segments, points or planes. As shown in the figure, FDS geometrical entities are always described using some conventional rules.

Volumes
A volume is always represented by a single right parallelepiped with edges parallel to the axis. Its position and dimensions are described by the coordinates of two opposite vertices: if point A=(xA, yA, zA) and point B=(xB,yB,zB) are the opposite vertices, its coordinates are entered as:

.

For example: uses the parameter  to define a solid obstacle that spans the volume starting at the origin (0.5, 2.0, -2.0) and extending 1 m in the positive x direction, 1.5 m in the positive y direction, and 2 m in the positive z direction.

Faces
A face is represented by a right plane face with edges parallel to the axis. Its position and dimensions are described by the coordinates of two opposite vertices, that must lie on the same plane. For example: uses the parameter  to define a flat face perpendicular to the z axis imposing a particular boundary condition over a solid. Two of the six coordinates are the same, denoting a flat face as opposed to a solid.

Segments
A segment is bounded by two end points. If point A=(xA, yA, zA) and point B=(xB, yB, zB) are the end points, its coordinates are entered following the same convection valid for volumes.

For example, is a beam smoke detector between (0.5, 2.0, -2.0) and (1.5, 3.5, 0.) end points.

Points
A point is simply identified by its 3 coordinates. For example, the line: uses the parameter  to insert a thermocouple at the point of coordinates (2., 3., 4.).

Planes
A plane is represented by a right plane perpendicular to one of the reference axis. For example, these lines:

All use the parameters,  ,   to specify the coordinate in the direction of the perpendicular axis.

Prescribing orientations
Some FDS entities need the prescription of a particular orientation. This is done with one of the following parameters:  or.

The parameter, index of orientation, is used to prescribe one of the six possible orientations parallel to axis:
 * if the orientation is in the positive x direction set ,
 * negative x direction ,
 * positive y ,
 * negative y ,
 * positive z ,
 * negative z.

For example, the line: designates the surface temperature of a wall facing the negative y direction.

The parameter  is used for entities that require a free directional specification, like a sprinkler. is specified with a triplet of real number values that indicate the components of the direction vector. The default value of  is (0, 0, -1).

For example, the line: designates a nozzle oriented towards the (1,1,0) vector.

Prescribing colors and aspect
Colors of objects can be prescribed with two parameters:  and.

The  parameter is followed by a triplet of integer numbers in the range from 0 to 255, indicating the amount of red, green and blue that make up the color.

The  parameter calls the name of a predefined color that must be entered exactly as it is listed in the color table. For example, a coloured solid obstacle is obtained with: You can rapidly find the whole color table of more than 500 colors in the documentation.

For example, both the parameter  and the parameter   can be used to obtain a blue object.

Objects can be made semi-transparent by assigning a  parameter. The parameter value is a real ranging from 0 to 1, with 0 being fully transparent. The parameter should always be set along with  or.

Using  causes the object not to be drawn in Smokeview. The parameter  causes the object to be drawn as an outline.

= References =