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 mycase.fds. 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:

&OBST XB=0.5,1.1,0.5,1.1,0.0,0.1 / A comment

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:

&REAC ID='polyurethane', SOOT_YIELD=0.1875, CO_YIELD=0.02775,
      C=1.0, H=1.75, O=0.25, N=0.065,
      HEAT_OF_COMBUSTION=25300., IDEAL=.TRUE. / 
      Gas phase reaction: polyurethane flexible foam (means)
      from Tewarson SFPE Handbook 3rd ed,
      SFPE handbook table 3-4.14, p. 3-112.

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:

• Integers, as in T_END=5400
• Real numbers, as in CO_YIELD=0.008
• Groups of real numbers, as in XYZ=6.04,0.28,3.65
• Groups of integers, as in IJK=90,36,38
• Character strings, as in CHID='this_is_a_string'
• Groups of character strings, as in SURF_IDS='burner','steel'
• Logical parameters, as in POROUS_FLOOR=.FALSE. or POROUS_FLOOR=.TRUE. The periods must be included.

Sometimes the parameters are multidimensional arrays. For example, MATL_ID(2,3)='brick' indicates that the third material component of the second layer is brick.

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

A simplified notation is accepted, too. MATL_ID='plastic','steel' is equivalent to MATL_ID(1:2,1)='plastic','steel'

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

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

To ensure that FDS reads the entire input file, add &TAIL / 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:

!!! General configuration

&HEAD CHID='pplume5', TITLE='Plume case' /
      name of the case and a brief explanation

&TIME T_END=10.0 /
      the simulation will end at 10 seconds

&MISC SURF_DEFAULT='wall', TMPA=25. /
      all bounding surfaces have
      a 'wall' boundary condition
      unless otherwise specified,
      the ambient temperature is set to 25°C.

&REAC ID='polyurethane', SOOT_YIELD=0.10,
      N=1.0, C=6.3, H=7.1, O=2.1 /
      predominant fuel gas for the mixture fraction model
      of gas phase combustion

!!! Computational domain

&MESH IJK=32,32,16, XB=0.0,1.6,0.0,1.6,0.0,0.8 /
&MESH IJK=32,32,16, XB=0.0,1.6,0.0,1.6,0.8,1.6 /
&MESH IJK=32,32,16, XB=0.0,1.6,0.0,1.6,1.6,2.4 /
&MESH IJK=32,32,16, XB=0.0,1.6,0.0,1.6,2.4,3.2 /
      four connected calculation meshes
      and their cell numbers

!!! Properties

&MATL ID='gypsum_plaster', CONDUCTIVITY=0.48,
      SPECIFIC_HEAT=0.84, DENSITY=1440. /
      thermophysical properties of 'gypsum plaster' material

&PART ID='tracers', MASSLESS=.TRUE., SAMPLING_FACTOR=1 /
      a type of Lagrangian particles

&SURF ID='burner', HRRPUA=600.,
      PART_ID='tracers', COLOR='RASPBERRY' /
      a type of boundary conditions named 'burner'

&SURF ID='wall', RGB=200,200,200, MATL_ID='gypsum_plaster',
      THICKNESS=0.012 /
      a type of boundary conditions named 'wall'

!!! Solid geometry

&VENT XB=0.5,1.1,0.5,1.1,0.1,0.1, SURF_ID='burner' /
      the 'burner' boundary condition
      is imposed to a plane face

&OBST XB=0.5,1.1,0.5,1.1,0.0,0.1, SURF_ID='wall' /
      a solid is created, 'wall' boundary condition
      is imposed to all its faces

&VENT XB=0.0,0.0,0.0,1.6,0.0,3.2, SURF_ID='OPEN'/
&VENT XB=1.6,1.6,0.0,1.6,0.0,3.2, SURF_ID='OPEN'/
&VENT XB=0.0,1.6,0.0,0.0,0.0,3.2, SURF_ID='OPEN'/
&VENT XB=0.0,1.6,1.6,1.6,0.0,3.2, SURF_ID='OPEN'/
&VENT XB=0.0,1.6,0.0,1.6,3.2,3.2, SURF_ID='OPEN'/
      the 'OPEN' boundary condition is imposed to
      the exterior boundaries of the computational domain

!!! Output

&DEVC XYZ=1.2,1.2,2.9, QUANTITY='THERMOCOUPLE', ID='tc1' /
      send to output: the data collected by a thermocouple
&ISOF QUANTITY='TEMPERATURE', VALUE(1)=100.0 /
      3D contours of temperature at 100°C
&SLCF PBX=0.8, QUANTITY='TEMPERATURE', VECTOR=.TRUE. /
      vector slices colored by temperature
&BNDF QUANTITY='WALL TEMPERATURE' /
      surface 'WALL_TEMPERATURE' at all solid obstructions
&TAIL / end of file

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 HEAD namelist group, the simulation time is set via the TIME namelist group. Other miscellaneous parameters are prescribed via the MISC namelist group.

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

Computational domain

Second, the computational domain is defined via the MESH 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 INIT namelist group.

Properties

Third, some properties are set up:

• the properties of each material (MATL),
• the properties of extra gas species (SPEC),
• the properties of Lagrangian particles (PART),
• and the types of boundary conditions (SURF).

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.

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 OBST, VENT, HOLE 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 PROP, DEVC, CTRL 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 (DEVC, SLCF, BNDF, ISOF). 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:

Section	Contents	Namelist groups
General configuration	General information required to perform a simulation, as its name, duration and other miscellaneous parameters.	HEAD, TIME, MISC
	Main gas phase combustion reaction and radiation model.	REAC, RADI
Computational domain	Computational domain: dimensions and grid.	MESH
	Initial conditions of the computational domain.	INIT
Properties	Materials, temperature dependent thermophysical properties.	MATL, RAMP (temperature)
	Extra gas species properties.	SPEC
	Lagrangian particles properties.	PART
	Boundary conditions, time dependent boundary conditions.	SURF, RAMP (time)
Solid geometry	Description of solid geometry, assignment of boundary conditions to bounding surfaces.	OBST, HOLE, VENT
Control logic	General properties of devices, devices and control functions used to control various actions, like creating and removing solid obstructions or activating and deactivating boundary conditions.	PROP, DEVC, CTRL
Output	List of calculated quantities to output.	DUMP, DEVC, SLCF, BNDF, ISOF

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:

• 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.

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:

• 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/m², 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.

Right-hand rule

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

FDS geometric entities

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=(x_A, y_A, z_A) and point B=(x_B,y_B,z_B) are the opposite vertices, its coordinates are entered as:

xA, xB, yA, yB, zA, zB.

For example:

&OBST XB=0.5,1.5,2.0,3.5,-2.0,0., SURF_ID='wall' /

uses the parameter XB 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:

&VENT XB=0.5,1.1,2.0,3.1,-2.0,-2.0, SURF_ID='fire' /

uses the parameter XB 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=(x_A, y_A, z_A) and point B=(x_B, y_B, z_B) are the end points, its coordinates are entered following the same convection valid for volumes.

For example,

&DEVC XB=0.5,1.5,2.0,3.5,-2.0,0., QUANTITY='PATH OBSCURATION',
      ID='beam1', SETPOINT=0.33 /

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:

&DEVC XYZ=2.,3.,4., QUANTITY='THERMOCOUPLE', ID='termo1' /

uses the parameter XYZ 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:

&SLCF PBX=0.5, QUANTITY='TEMPERATURE' /
! is a plane perpendicular to the x axis and intersecting its point (.5,0.,0.).

&SLCF PBY=1.5, QUANTITY='TEMPERATURE' /
! is a plane perpendicular to the y axis and intersecting its point (0.,1.5,0.).

&SLCF PBZ=-.5, QUANTITY='TEMPERATURE' /
! is a plane perpendicular to the z axis and intersecting its point (0.,0.,-.5).

All use the parameters PBX, PBY, PBZ 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: IOR or ORIENTATION.

The parameter IOR, 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 IOR=1,
• negative x direction IOR=-1,
• positive y IOR=2,
• negative y IOR=-2,
• positive z IOR=3,
• negative z IOR=-3.

For example, the line:

&DEVC XYZ=0.7,0.9,2.1, QUANTITY='WALL TEMPERATURE',
      IOR=-2, ID='ST-1' /

designates the surface temperature of a wall facing the negative y direction.

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

For example, the line:

&DEVC XYZ=23.91,21.28,0.50, PROP_ID='nozzle',
      ORIENTATION=1.,1.,0., ID='noz_1' /

designates a nozzle oriented towards the (1,1,0) vector.

Prescribing colors and aspect

Colors of objects can be prescribed with two parameters: RGB and COLOR.

The RGB 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 COLOR 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:

&OBST XB=0.5,1.5,2.0,3.5,-2.0,0.
      COLOR='MAGENTA' /

You can rapidly find the whole color table of more than 500 colors in the documentation.

For example, both the parameter RGB=0,0,255 and the parameter COLOR='BLUE' can be used to obtain a blue object.

Objects can be made semi-transparent by assigning a TRANSPARENCY 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 RGB or COLOR.

Using COLOR='INVISIBLE' causes the object not to be drawn in Smokeview. The parameter OUTLINE=.TRUE. causes the object to be drawn as an outline.