Installation¶
Install xFDS¶
Once you have Python and pipx installed on your machine (see below), you can install xFDS with the following command.
$ pipx install xfds
You can verify that xfds is working by displaying the help text. If this does not work, try troubleshooting pipx
$ xfds --help
Required Third Party Packages¶
Python¶
Info
Python is a high-level general-purpose programming language. If you don't have Python installed on your machine, it is recommended that you get the latest stable version of the Python interpreter. Real Python has a nice article to help you get Python on your machine.
Warning
If you're installing xFDS on Ubuntu, Python may already be installed, but you will have to install pip and venv. pip is needed to install packages such as pipx and venv is required so pipx can install xFDS in an isolated environment.
sudo apt install python3-pip python3-venv
How does xFDS use Python?
xFDS is written in Python! You will need a Python interpreter for xFDS to run.
pipx¶
Info
pipx allows you to install python applications in isolated envrionments. To install pipx, check out their installation instructions
How does xFDS use pipx?
While you could use pip to install xFDS, it could interfere with the Python version your machine uses to function. pipx is the recommended way to install xFDS on your machine.
Docker¶
Info
If you are installing this on a server install Docker Engine. Otherwise, to get the desktop client, install Docker Desktop (includes Docker Engine).
Docker is a platform used to develop and deliver software in packages called containers. These containers are lightweight computing environment that use the host computer's resources, while isolating the running container from the host machine.
Docker can be installed on most modern computers. For instructions on how to setup Docker, visit their getting started page.
How does xFDS use Docker?
The generous folks at BCL have developed a series of Docker images for a variety of FDS versions. The images are maintained under a MIT License on Github and available for use on dockerhub.
To run a multi-core model in a docker image, the user would have to enter the following command into their terminal:
docker run --rm -v $(pwd):/workdir openbcl/fds mpiexec -n 2 fds casename.fds
The xFDS run command simplifies this command and will automatically locate the FDS input file in the current directory with the following command:
xfds run -n 2
If you don't intend to use the run command for running tests locally, you can skip this step.
What's the difference between pipx and Docker? Docker will isolate the container from the rest of the host machine and does not have access to the host machine unless specified. With xFDS, the docker containers only have access to read and write from the specified directory, but cannot interface with the host machines systems and services.
In contrast, pipx isolates the dependencies for xFDS from other Python projects on the host machine. It makes xFDS available on the command line anywhere on the host machine.