FDS Daily Workflow

###Introduction

In this wiki we will describe how to work within "our system" in the firemodels group. As a prerequisite, read the Git Notes Getting Started wiki. Here we will assume you have forked the firemodels/fds-smv repository to <your GitHub username>/fds-smv and have cloned your repo to your local account on our linux cluster "blaze".

The purpose of this workflow is to keep your repository up-to-date with the latest changes to the development version of FDS. We expect developers in our group and all collaborators doing research to work with the latest development version of the code. The build status for the latest version is given here: Firebot_Build_Staus. If the build status is "Build Failure!", you should skip updating for that particular day.

If you are brand new to working on unix/linux systems, it will be very helpful if you do a little homework and get up to speed on some basic commands. Note: Be very careful with rm. And, unless you really know what you are doing, do not type rm *. You will be very disappointed. There is no "undo" from this operation in linux.

###Adding Aliases to Your .bashrc File

It will be handy to have a couple of aliases established for running different versions of FDS.

If you have not already, open a shell (Terminal on Mac, Putty on Windows) and ssh into blaze. Type

$ ssh <hostname>
Enter password

Now you are in your home directory. Open your .bashrc file with vim (here is a vi cheat sheet). Type

$ vi .bashrc

and make sure your have the following lines.

export FDSSMV=~/<YOUR REPO NAME HERE>
alias fds_db="$FDSSMV/FDS_Compilation/intel_linux_64_db/fds_intel_linux_64_db"
alias fds_dv="$FDSSMV/FDS_Compilation/intel_linux_64_dv/fds_intel_linux_64_dv"
alias qfds.sh="$FDSSMV/Utilities/Scripts/qfds.sh"

If you do not have any of these lines, type i to enter "insert mode" and copy these lines into your file. Then type :wq to "write" and "quit" the file.

Close your terminal and reopen it so that new aliases will become active. Now you will be able to simply type, for example, fds_db to run the "debug" version of FDS (once it is compiled, see below).

###Daily Workflow

Setting aliases is a one-time thing. In this section, we will describe what we do on a daily basis.

####Step 0: Get some coffee

####Step 1: Update your repository

For this example, I will be the user with an account on blaze.

If you have not already, open a shell (Terminal on Mac, Putty on Windows) and ssh into blaze. Type

$ ssh <hostname>
Enter password

Change directories ("cd") into your repo's directory. I keep my forked repo in ~/GitHub/fds-smv_rmcdermo/. So, I type

$ cd GitHub/fds-smv_rmcdermo

First, make sure you are on the development branch of your repo. Type

$ git branch -a
* development
  remotes/firemodels/development
  remotes/firemodels/gh-pages
  remotes/firemodels/nist-pages
  remotes/origin/HEAD -> origin/development
  remotes/origin/development

If you do not see the output shown above -- most importantly the asterisk next to development -- then something went wrong in your repo setup; revisit Git Notes Getting Started.

Next, fetch changes from the firemodels central repository. Again, this assumes you have correctly setup the development branch firemodels/fds-smv for remote tracking (see Git Notes Getting Started).

$ git remote update
Fetching origin
...
Fetching firemodels
...

Merge any changes from firemodels into your local repo.

$ git merge firemodels/development
...

Push these changes to your forked repo on GitHub so that this repo also stays up-to-date.

$ git push origin development
...

This is an important step because if and when you find a problem with the code or documentation we would like YOUR help in fixing it. This involves your making changes, committing those changes, pushing the changes to your forked repo, and sending a pull request (see Git Notes Topic Branches), which the project maintainers will then evaluate (again, see Git Notes Getting Started). If your forked repo is not up-to-date with the firemodels central repo, your pull request will be impossible to accept.

If all has gone well at this point you can check the status of your repo and see the following:

$ git status -uno
# On branch development
nothing to commit (use -u to show untracked files)

Let's now move on to compiling the latest code.

####Step 2: Compile the code

CD into FDS_Compilation and do an ls. You will see several choices or "platforms" for compiling FDS.

$ cd FDS_Compilation
$ ls
...

If you are no doing development work you probably just want to compile the release target that works by default with qfds.sh. That target is mpi_intel_linux_64ib. The "ib" indicates that you will be running on the "Infiniband" network on blaze.

$ cd mpi_intel_linux_64ib

Now do an ls of this directory. The first time you enter into this directory you will only see this

$ ls
make_fds.sh

The make_fds.sh script is what you run to compile the code. Once the code is compiled this directory will be populated with object and module files (*.o and *.mod). To do a "clean" compile of the code on a daily basis you will need to remove these files before compiling. So, usually you will now type the following two commands. The rm command can be omitted the first time you compile. But generally it is better to do a clean compile.

$ rm *.o *.mod
$ ./make_fds.sh
...

Note the ./ before make_fds.sh. This says you are running the script from this specific directory.

If you need to do any development or debug work, you will have to compile the debug (_db) or development (_dv) versions of the code. CD up one level, cd .., and back down into whichever target you want to compile. I usually work with the (_dv) version because this version compiles reasonably fast and yet still runs reasonably fast. If I am debugging pesky errors that I cannot find with fds_dv then I will resort to the _db version. The process for compiling each of these versions is the same:

$ cd intel_linux_64_dv
$ rm *.o *.mod
$ ./make_fds.sh
...

Now, because of the alias we set up, you can run fds_dv in the foreground:

$ fds_dv

Fire Dynamics Simulator

 Current Date     : March 24, 2016  11:07:23
 Version          : FDS 6.4.0
 Revision         : Git-r8-483-gaf5fec1
 Revision Date    : Thu Mar 24 10:25:02 2016 -0400
 Compilation Date : Mar 24, 2016  11:03:09

 MPI Disabled
 OpenMP Enabled; Number of OpenMP Threads:   4

 Consult FDS Users Guide Chapter, Running FDS, for further instructions.

 Hit Enter to Escape...

Notice here that the number of OpenMP threads is set to 4. If you see a number here you did not explicitly set or if the number of threads is different than you expect, make sure your have the following line in either your .bashrc file:

export OMP_NUM_THREADS=4

###Running the New Code

One both blaze and burn you can submit jobs to the queueing system via

$ qfds.sh [options] job_name.fds

The options needed to run on multiple cores, etc., can be found by simply typing qfds.sh without any arguments at the command line.

###Summary

All of the above may look daunting at first, but it will quickly become routine. You are simply going to do this:

1. git remote update
2. git merge firemodels/development
3. compile the new code