Skip to content

MainIdea

Jump to bottom
lukas edited this page May 19, 2017 · 1 revision

Table of Contents

Motivation

FDS is a widely used fire and smoke spread simulation tool. Its input file format (FORTRAN namelist format) is based on absolute numbers, e.g. geometry information. This tool allows to formulate FDS input files in a relative way, i.e. as functions of variables. The used file format is XML.

Usage

The FDSgeogen project consists basically of a single Python script fgg_create.py that parses XML files. The usage on Linux / UNIX based operating systems is very simple via the provided links (without the .py extension, for convenience) in the top directory and the shebang command:

fgg_create input.xml

To use a specific Python version, it is always possible to do the explicit call

python fgg_create input.xml

The Python script assumes that the first passed argument is the XML file to be parsed.

Note: For convenience add the main directory of fdsgeogen to your PATH environment variable, i.e.:

export PATH=$PATH:/path/to/fdsgeogen

XML Syntax

The input file format used for FDSgeogen is XML. Check the XML Wikipedia page for further information.

Basically an XML file consists of tags and attributes. Tags may contain attributes and cover blocks and are enclosed by < and >. Simple examples are:

  • an empty tag named some_tag_a 
<some_tag_a />
  • a start and stop tag some_tag_b 
<some_tag_b> 
some other input 
</some_tag_b>

Attributes are associated with a tag and are key/value pairs. The value is always enclosed by ". For example:

  • attribute attrib_1 with the value 45 in an empty tag
<some_tag_c attrib_1="45" />
  • two attributes fire and size with according values
<some_tag_d fire="big" size="144" >
some other input
</some_tag_d>

Variables definition

FDSgeogen allows to define variables, which can be used for further reference. The tag [wiki:TagVar var] indicates the declaration and assignment of a variable. The name of the variable is defined by the attribute-key. Multiple attributes define multiple variables. Supported types are the Python types int, float and str, e.g.

  • variable named nx with the value 12 
<var nx="12" />
  • two floating point variables
<var dim_x="3.4" dim_y="1e-3" />
  • a character string variable
<var mat_id="'concrete'" />

Formatted strings with Python

A common situation is the creation of strings, which have embedded variable values. Python offers many possibilities for doing that, see string-formatting.

The basic idea is to have a common string that includes place holders (start with % and end with e.g. d, e, f, s) that are substituted with variable values. These values are passed to the string via the % operator as a tuple. The syntax is as follows for a string containing two variable values.

'some string and two place holders: %d %f'%(integer_value, float_value)'

Here are some basic examples:

  • integer value: '%d'%(4) will result in '4'
  • integer value with fixed width: '%4d'%(5) will result in ' 5'
  • integer value with fixed width, but filled with zeros: '%04d'%(7)' will result in '0007'
  • float values in decimal and exponential format: 'decimal: %f; exponential: %e'%(144.5, 1632.2) results in 'decimal: 144.500000; exponential: 1.632200e+03'
  • strings may as well be included: 'chosen chid: %s'%('myfdstest') will result in 'chosen chid: myfdstest'

Common situations in FDSgeogen:

  • create subdirectory or FDS input file name as a function of the parameter set id (para_id). The following example will construct a subdirectory name starting with id_ and followed by three characters (width three, filled with zeros) representing the parameter set id:
<info chid="'analysis'" subdir="'id_%03d'%para_id" title="'Example file for FDSgeogen'" outfile="'analysis_hole.fds'"/>
  • print variable values to the FDS input file, just for documentation or further usage:
<var a="5.6" fn="'myfunction'" ceiling="2" />
<dump str="'!! value of a      : %f'%a" />
<dump str="'!! value of fn     : %s'%fn" />
<dump str="'!! value of ceiling: %d'%ceiling" />

Variables access

Any attribute-value is evaluated by the Python interpreter, considering all available Python routines and variables (so far) defined in the XML file.

  • simple algebraic operations, here the variable nx will have a value of 146 (the sum of 144 and 2):
<var nx="144 + 2" />
  • accessing variable values, here the variable dim_x will be assigned a value of 2.0
<var nx="20" />
<var dim_x="0.1 * nx" />

Debugging

At some point during the XML processing, there might be the need to provide debugging information. The tag dbg provides a simple way to output information to the console. The output value is defined in the attribute print. A fully running example is:

<fds>

    <var nx="20" />
    
    <dbg print="nx * 4" />

</fds>

It outputs the following

80

to the console -- and generates an empty undefined FDS inputfile: per default named output.fds, with a minimal content.

All Python string formatting is possible to generate more meaningful output, e.g.:

<fds>

    <var nx="20" ny="40"/>
    
    <dbg print="'value of nx and ny: %d, %d'%(nx, ny)" />

</fds>

will produce the following console output

value of nx and ny: 20, 40
Clone this wiki locally