-
Notifications
You must be signed in to change notification settings - Fork 618
FDS Daily Workflow
In this wiki we will describe how to work within "our system" in the firemodels group at NIST. Some of this guidance is specific to the NIST working environment, but some is of general usefulness. As a prerequisite, read the Git Notes Getting Started wiki. Here we will assume you have forked the firemodels/fds repository to <your GitHub username>/fds and have cloned your repo to your local account on our linux cluster "blaze" or "burn".
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.
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 FDS_Repo=/<PATTH TO YOUR REPO>/<YOUR REPO NAME>
alias fds_db="$FDS_Repo/Build/mpi_intel_linux_64_db/fds_mpi_intel_linux_64_db"
alias fds_dv="$FDS_Repo/Build/mpi_intel_linux_64_dv/fds_mpi_intel_linux_64_dv"
alias qfds.sh="$FDS_Repo/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).
Setting aliases is a one-time thing. In this section, we will describe what we do on a daily basis.
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/FireModels_rmcdermo/fds/. So, I type
$ cd GitHub/FireModels_rmcdermo/fds
First, make sure you are on the master branch of your repo. Type
$ git branch -a
* master
remotes/firemodels/master
remotes/origin/HEAD -> origin/development
remotes/origin/master
If you do not see the output shown above -- most importantly the asterisk next to master -- 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 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/master
...
Push these changes to your forked repo on GitHub so that this repo also stays up-to-date.
$ git push origin master
...
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. 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.
CD into Build and do an ls. You will see several choices or "platforms" for compiling FDS.
$ cd Build
$ ls
...
If you are not 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_64.
$ cd mpi_intel_linux_64
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 mpi_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 : October 6, 2017 13:14:52
Version : FDS 6.5.3
Revision : FDS6.5.3-2910-gac8eed8-master
Revision Date : Thu Oct 5 15:41:24 2017 -0400
Compiler : Intel ifort 17.0.4
Compilation Date : Oct 05, 2017 15:50:52
MPI Enabled; Number of MPI Processes: 1
OpenMP Enabled; Number of OpenMP Threads: 4
MPI version: 3.1
MPI library version: Open MPI v3.0.0, package: Open MPI gforney@burn Distribution, ident: 3.0.0, repo rev: v3.0.0, Sep 12, 2017
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
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.
All of the above may look daunting at first, but it will quickly become routine. You are simply going to do this:
- git remote update
- git merge firemodels/master
- compile the new code