Skip to content

Run Command


xfds run --help
Usage: xfds run [OPTIONS] [FDS_FILE] COMMAND [ARGS]...

  Run an FDS in a Docker container.

  [FDS_FILE]  The FDS file or directory to run. If a **FDS file** is
              specified, the FDS model will run. If a **directory** is
              specified, xFDS will find the first FDS file in the directory
              and assume that is what it should run. If no fds file exists,
              xFDS will default to interactive mode. if **nothing** is
              specified, the current directory is used and the above rules are
              applied.   [default: .]

  -i, --interactive               Launch Docke-r container in interactive mode
                                  (`docker run -it`). By default, the Docker
                                  image will run the FDS model, but
                                  interactive mode will put you into the
                                  container where you can start the FDS model
                                  manually. This is good for when you are
                                  rapidly iterating and don't want to wait for
                                  the Docker image load time.
  -n, --processors INTEGER RANGE  Specify number of processors. If the number
                                  of processors is greater than 1, it will
                                  invoke MPI for you (`mpiexec -n #`). Ignored
                                  if interactive mode is enabled.   [default:
                                  1; x>=1]
  -v, --fds TEXT                  Specify FDS version to use. The FDS version
                                  can also be extracted from the file path or
                                  metadata in the FDS file.
  --help                          Show this message and exit.

  Developed by


The xFDS run command is a convience wrapper for docker run. xFDS determines the appropriate arguments for the model and exectues the docker run command for you.

Unless stated otherwise, the commands below assume you are at /home/pbdtools/models with the following directory structure.

Directory Structure under /home/pbdtools/models/
/home/pbdtools/models $ tree
├── multi_mesh # More than 1 processor required
│   └── multi_mesh.fds

├── multiple_files # Multiple fds files in directory
│   ├── model_01.fds
│   └── model_02.fds

└── single_mesh # Only 1 processor required
    └── single_mesh.fds

Working in Different Shells

The xfds run command simplifies and unifies what you have to type into the terminal. The sytax for using FDS Dockerfiles without xFDS is sligntly different depending on what shell you're using. Each shell has it's own way of referring to the current directory.

  • Linux / Mac - Bash $(pwd)
  • Windows Powershell ${pwd}
  • Windows Command Prompt %cd%

You can see the differences in the command syntaxes.

docker run --rm -v $(pwd):/workdir openbcl/fds fds <filename>.fds
docker run --rm -v ${pwd}:/workdir openbcl/fds fds <filename>.fds
docker run --rm -v %cd%:/workdir openbcl/fds fds <filename>.fds

xFDS eliminates this concern by using the absolute path in place of the shortcuts for the current directory. While generating the command to execute Docker, xFDS will also name the Docker container based on the file name and FDS version.

For example, if you're in /home/pbdtools/models/single_mesh, executing xfds run will have the output below.

xFDS Command
xfds run
Command called by xFDS
docker run --rm --name single_mesh-latest -v /home/pbdtools/models/single_mesh:/workdir openbcl/fds:latest fds single_mesh.fds

For the rest of the examples, the xFDS command will be shown, and you can tab over to the equivalent Docker command as follows. The current directory will also be shown.

xfds run
docker run --rm --name single_mesh-latest -v /home/pbdtools/models/single_mesh:/workdir openbcl/fds:latest fds single_mesh.fds

Single vs Multiple Processors

The only difference between running a single processor model and a MPI processor is supplying the number of processors desired with the -n flag. xFDS will automatically call mpiexec if needed.

Single processor

xfds run
docker run --rm --name single_mesh-latest -v /home/pbdtools/models/single_mesh:/workdir openbcl/fds:latest fds single_mesh.fds

Two processors

xfds run -n 2
docker run --rm --name multi_mesh-latest -v /home/pbdtools/models/multi_mesh:/workdir openbcl/fds:latest mpiexec -n 2 fds multi_mesh.fds

Running From Different Directories

From same directory as the fds file

xfds run
docker run --rm --name single_mesh-latest -v /home/pbdtools/models/single_mesh:/workdir openbcl/fds:latest fds single_mesh.fds

From a parent directory

xfds run single_mesh
docker run --rm --name single_mesh-latest -v /home/pbdtools/models/single_mesh:/workdir openbcl/fds:latest fds single_mesh.fds

Multiple files in the same directory

If there are multiple fds files in the directory, xFDS will default to the first one.

xfds run
docker run --rm --name model_01-latest -v /home/pbdtools/models/multiple_files:/workdir openbcl/fds:latest fds model_01.fds

If you want to run model_02.fds, you must specify it.

xfds run model_02.fds
docker run --rm --name model_01-latest -v /home/pbdtools/models/multiple_files:/workdir openbcl/fds:latest fds model_02.fds

Specifying FDS Version

FDS Dockerfiles supports most versions of FDS. xFDS will default to the latest version. If you would like to specify an older version you can pass the desired version to xFDS. See the fds-dockerfiles repo for information on supported versions.

These examples will pretend like you want to run FDS 6.7.5. xFDS will use the openbcl/fds:6.7.5 image and FDS version will be appended to the container name. This way it is clear what model and version are running.

These subsections also indicate the priority of different methods. Specifying a version on the command line will take the highest precidence while a version in the file path will be the lowest priority.

Command Line Argument

xfds run --fds 6.7.5
xfds run -v 6.7.5
docker run --rm --name single_mesh-6.7.5 -v /home/cohan/github/pbdtools/models/single_mesh:/workdir openbcl/fds:6.7.5 fds single_mesh.fds

File Metadata

xFDS supports metadata in FDS input files via the MultiMarkdown Specification. If you want to ensure a file is always run with the same version of FDS, you can specify a fds keyword at the top of the file and xFDS will call the appropriate container.

This method has the benefit of documenting the intended version of FDS for a model which can be useful if you are returning to a project after a while. Furthermore, this prevents your models from unexpectedly running on a different version if a new version of FDS is released mid project.

fds: 6.7.5
xfds run
docker run --rm --name single_mesh-6.7.5 -v /home/cohan/github/pbdtools/models/single_mesh:/workdir openbcl/fds:6.7.5 fds single_mesh.fds

File Path

xFDS will read the full path to the model and determine if a folder is specifying a version of FDS. The version can use periods (.) or underscores (_) and may be preceeded by either fds or v. The following paths are equivalent and all run FDS 6.7.5.


xfds run
docker run --rm --name single_mesh-6.7.5 -v /home/cohan/github/pbdtools/models/6.7.5/single_mesh:/workdir openbcl/fds:6.7.5 fds single_mesh.fds

This method is particularly useful if you have tests that you need to run on different versions. You can copy the entire directory over, rename the version folder, and then all the models will use that new version.

Interactive Mode

Interactive mode is useful if you need to quickly iterate on a given model, but don't want to incur the startup cost for the container. To enter interactive mode, pass the -i flag to xFDS.

xfds run -i
docker run --rm -it --name fds-latest -v /home/pbdtools/models/single_mesh:/workdir openbcl/fds:latest

This will put you in a terminal inside the container.

Inside Container
root@00a83c3c6390:/workdir# pwd
root@00a83c3c6390:/workdir# ls
root@00a83c3c6390:/workdir# fds

 Fire Dynamics Simulator

 Current Date     : June 23, 2022  19:44:42
 Revision         : FDS6.7.8-0-gfbf3e11ee-release
 Revision Date    : Tue May 24 18:07:45 2022 -0400
 Compiler         : ifort version 2021.5.0
 Compilation Date : May 25, 2022 06:01:34

 MPI Enabled;    Number of MPI Processes:       1
 OpenMP Disabled

 MPI version: 3.1
 MPI library version: Intel(R) MPI Library 2021.4 for Linux* OS

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