# Running FDS

This chapter explains how to obtain, install and run FDS and Smokeview. The explanation covers Fedora Linux, Ubuntu Linux and Windows XP.

## Online resources and user support

The primary resource for detailed instructions on how to download executables, manuals, source code and related utilities, is the FDS-SMV website:
* http://firemodels.github.io/fds-smv/
FDS has two separate manuals:
* FDS5 technical reference
* FDS5 user's guide.
The FDS5 technical reference guide is broken into three volumes:
* Mathematical model;
* Verification;
* Experimental validation.
Smokeview has its own manual:
* Smokeview user's guide.
The FDS and Smokeview user's guides only describe the mechanics of using the computer programs. The technical reference guides provides the theory, algorithm details, and verification and validation work.
Along with the FDS manuals, there are resources available on the Internet. These include an issue tracker, that allows you to report bugs, feature requests and ask specific clarifying questions, and group discussions, which support more general topics than just specific problems.
Before using these on-line resources, it is important to first try to solve your own problems by performing simple test calculations, or debugging your input file.

## Graphical user interface

FDS has an independently developed graphical user interface named BlenderFDS:
* http://www.blenderfds.org/
See specific chapter [cha:BlenderFDS] for more information.

## Version numbers

Each release of FDS and Smokeview is identified by a version number such as FDS_5.0.1 or SMV_5.0.1, where the first number is the major release (5), the second number (0) is the minor release, and the third (1) indicates the maintenance release number.
As a general pattern, major releases will occur every year or so. As the name implies, they dramatically change the functionality or capabilities of the model. Minor releases occur every few months, and may cause minor changes in functionality. Maintenance releases are more frequent and are just bug fixes or small refinements, and should not affect code functionality. The release notes can help you decide whether the changes should effect the type of applications that you typically do.

## Hardware requirements

FDS requires one or more fast CPUs and a substantial amount of random-access memory (RAM) to run efficiently. For minimum specifications, the system should have at least a 1 GHz CPU, and 1 GB RAM. The CPU speed will determine how long the computation will take to finish, while the amount of RAM will determine how many mesh cells can be held in memory.
1 GB RAM can hold around 10$^6$ cells. To understand the physical meaning, a 20 m x 10 m x 5 m computational domain contains 10$^6$ cells, when discretized with cubic cells of 10 cm side.
A large hard drive is required to store the output of the calculations. It is not unusual for the output of a single calculation to consume many gigabytes of storage space.
Smokeview needs an OpenGL graphics card. Look for graphics cards that specifically list OpenGL support for the operating system you intend to use.

## Serial and parallel calculations

FDS can perform serial and parallel calculations:
Serial calculations are performed in a single process that uses only one core of current multi-core CPUs.
Parallel calculation splits the computational burden on many processes that can be assigned to many different cores or CPUs. These CPUs can reside on a single workstation or in a cluster of networked computers.
Setting up a cluster of computers is a complex task and it is out of the scope of this manual.

## Installing on Fedora Linux

These instructions require a basic knowledge of Fedora Linux.
Fedora has several flavors, here it will be assumed that the 64 bit workstation version is being used.
The 64 bit version has the ability to address more RAM memory than 32 bit version (over 4 GB). The 32 bit version is limited to 4 GB of RAM memory.

### First install

To install FDS and Smokeview on an Fedora Linux system, first, you can either download the latest version of the precompiled FDS and Smokeview for Linux from download page on the web site, or compile it yourself by cloning the repository. If using the pre-compiled version, follow the instructions . If compiling it your self, make sure you have a Fortran compiler, then if you want to enable multiprocessor support, install (if you wish to use another MPI library, you will change the installation scripts in the source code). Finally compile the code you have cloned from the repository. The pre-compiled version automatically modifies your paths to ensure it is easy to start Fire dynamics simulator, while you will need to do this yourself if you compile the code yourself.

## Installing on Ubuntu Linux

These instructions require a basic knowledge of an Ubuntu Linux computer.
Ubuntu Linux operating system comes in two basic flavors:
Ubuntu Linux 32 bit, that can be installed on any type of computer.
Ubuntu Linux 64 bit, that can be installed on all AMD 64 bit CPUs with AMD64 extension and all Intel CPUs with EM64T extension.
The 64 bit version has the ability to address more RAM memory than 32 bit version (over 4 GB). The 32 bit version is limited to 4 GB of RAM memory.
Be aware that Smokeview works much better on a good dedicated graphic card. Some cheap graphic cards can prevent you from using it on Linux.

### First install

To install FDS and Smokeview on an Ubuntu Linux system, first, download the latest version of the precompiled FDS and Smokeview for Linux from download page on the official web site. Depending on your Ubuntu flavor, download the 32 bit or the 64 bit compressed archive of the FDS distribution.
After downloading to your computer, extract the archive by right clicking on its icon and selecting Extract here in the context menu.
Then, move the extracted FDS folder to your preferred location, for example your home directory. In my case the resulting path to FDS folder would be /home/egissi/FDS, as /home/egissi is my home folder.
After that, look at hidden files of your home folder by selecting View->Show hidden files menu in the Nautilus file browser. Locate the .bashrc file in your home directory, and open it for editing by double-clicking its icon.
Append the following text to the .bashrc file in the editor window:
Edit the emphasized line and set your actual path to the FDS folder. After that, save the .bashrc file and close the text editor.
Open Synaptic package manager by selecting System->Administration->Synaptic package manager menu and install:
On Ubuntu Linux 32 bit: lam-runtime software package;
On Ubuntu Linux 64 bit: lam-runtime and ia32-libs software packages.
Ubuntu Linux takes care for you of all the needed software dependencies.
Close your session and log-in again to put into effect the environment modifications. Your Ubuntu Linux system is now ready to perform serial and parallel simulations on a multi-core or multi-CPU workstation.

### Installing a new version

When installing a new version of FDS and Smokeview, just delete the old FDS folder. After downloading the new version, extract the new FDS folder and drag it to the same position as before.
Your Ubuntu Linux system is now ready to perform serial and parallel simulations with the new version.

## Compiling an optimized binary

As FDS is open source software, users can always download the latest version of FDS source code and compile it by themselves using a Fortran 90 and C compiler. Direct compilation is often applied to obtain an FDS binary that is optimized for the specific hardware and platform and to fully take advantage of its speed.
Compilation is a complex task and is out of the scope of the present manual.

## Performing a calculation

The typical procedure for using FDS and Smokeview is to:
1. Set up an FDS input file, as mycase.fds, and put it in a folder, as mycase folder. See following chapters to learn how to do it.
2. Run FDS on the input files. FDS starts and creates many output files in the mycase folder.
3. While FDS is running, monitor the development of the calculation.
4. Analyze the generated output files with Smokeview.

## Installing on Windows XP

To install or reinstall FDS and Smokeview on a Windows XP system, download Windows installation package from official website.
The Windows file is a self-extracting compressed archive that will install FDS, Smokeview and all associated files in the Program Files/FDS folder.
Launch the installation by double-clicking on the downloaded file.
At the end of the install process, your Windows XP system is ready to perform serial calculations.

### Running serial FDS on Fedora Linux

On a Fedora Linux computer open up a terminal window. Then, if using the pre-compiled version execute one of the following commands:
fds mycase.fds
If unsure, just look inside FDS/FDS6/bin folder to discover the right name for FDS binaries.
Then the simulation starts and its progress is indicated by diagnostic output that is written out onto the screen.

### Running serial FDS on Ubuntu Linux

On an Ubuntu Linux computer select Applications->Accessories->Terminal menu to open the command prompt. Move into the mycase folder, where the input file for the case is located, with the cd command.
Then execute one of the following commands:
On Ubuntu Linux 32 bit: fds5_intel_linux_32 mycase.fds
On Ubuntu Linux 64 bit: fds5_intel_linux_64 mycase.fds
If unsure, just look inside FDS/FDS5/bin folder to discover the right name for FDS binaries.
Then the simulation starts and its progress is indicated by diagnostic output that is written out onto the screen.

### Running serial FDS on Windows XP

After having set up an input file, open up a command prompt window: select Start->Run menu, then type cmd. Move into the mycase folder, where the input file for the case is located, with the cd command.
Then run the code by typing the following command:
fds5 mycase.fds
where fds5 is the name of FDS binary and mycase.fds is the input file name.
A serial calculation starts and its progress is indicated by diagnostic output that is written out onto the screen.

### Running parallel FDS on Fedora Linux

Parallel computers can be configured very differently, hence it is difficult to give a guide that will work for all configurations.
Using OpenMPI installed on Fedora Linux computer a typical command to perform a parallel calculation is:
The exact name of the binary will depend upon the compilation options. In many cases, MPI will still be effective in speeding up calculations on a multicore laptop/desktop/workstation. Hence, once you have serial simulations working, users should try using this model. Further instructions for running on a cluster can be found .

### Running parallel FDS on Ubuntu Linux

FDS uses the Message Passing Library (MPI) for parallel computing.
MPI is a language-independent communications protocol used to program parallel computers. Both point-to-point and collective communication are supported. MPI's goals are high performance, scalability, and portability. MPI is the dominant model used in high-performance computing today.
The input file for both single and parallel versions of FDS are the same. In fact, it is recommended that before embarking on parallel processing, you should run your input file in serial mode to ensure that it is properly set up.
To run FDS in parallel, you must break up the computational domain into multiple meshes so that the workload can be divided among the available processors.
For the parallel version to work well, there has to be a comparable number of cells in each mesh, or otherwise most of the computers will sit idle waiting for the one with the largest mesh to finish processing each time step.
On an Ubuntu Linux computer as configured before, type the following commands to perform a parallel calculation:
On Ubuntu Linux 32 bit:
On Ubuntu Linux 64 bit:
The lamboot command starts the MPI environment.
The mpirun command starts an MPI application, in our case fds5_mpi_intel_linux_32 or fds5_mpi_intel_linux_64, where -np 4 is the number of started processes. The number of processes must match the number of meshes that span the computational domain of the input case.
At the end of the calculation, the MPI server is safely stopped with lamhalt command.

## Monitoring progress

Diagnostics for a given calculation are written into a text file called mycase.out, contained in the case folder mycase. The CPU usage and simulation time are written here, so you can monitor it to see how far along the program has progressed.
The application System->Administration->Gnome System Monitor is a process viewer that provides a dynamic real-time view of a running system.

## Stop a calculation

To stop a calculation before its scheduled time, create an empty file in the mycase folder called mycase.stop. The mere existence of this file stops the program gracefully, causing it to dump out the latest flow variables for viewing in Smokeview.
Since calculations can be hours or days long, FDS can be restarted by adding
to the fds file. See FDS User Guide for broader details.

## Visualizing results

Smokeview is used before, during and after model runs:
* before, to check the input data;
* during a calculation, to monitor a simulation’s progress;
* in a post-processing step, to visualize FDS data after a calculation has been completed.
On Windows XP, Smokeview may be started by double-clicking on the file named mycase.smv, contained in the case folder.
On Ubuntu Linux, Smokeview is run from the command prompt by typing:
On Ubuntu Linux 32 bit: smv5_linux_32 mycase.smv
On Ubuntu Linux 64 bit: smv5_linux_64 mycase.smv
If unsure, just look inside FDS/FDS5/bin folder to discover the right name for Smokeview binary.
Inside Smokeview, menus are accessed by clicking on the graphical window with the right mouse button. The Load/Unload menu may be used to read in the data files to be visualized. The Show/Hide menu may be used to change how the visualizations are presented.
For the most part, the menu choices are self explanatory. In case of need, help on using Smokeview can be found on [Smokeview user's guide].

## Output files

FDS writes out many output files in the mycase folder:
Diagnostic output: the file mycase.out consists of a list of input parameters, and an accounting of various important quantities, including CPU usage.
Heat release rate and related quantities:
the HRRHeat Release Rate (HRR) of the fire, plus other global energy-related quantities, are automatically written into a text file called mycase_hrr.csv
Device output data: data associated with particular devices (link temperatures, smoke obscuration, thermocouples, etc.) is output in comma delimited format in a file called mycase_devc.csv and many other types of files, used by Smokeview for visualisation.
The comma delimited format files can easily be imported into Openoffice.org Calc or Microsoft Excel for further analysis.