Installing the `torx` environment and Jupyter kernel

To install the Tor-X environment (see what is Tor-X), you can use the shell script install_env.sh, which should work on most Linux systems (i.e. MPCDF machines, TOK cluster, Marconi). Note that you need a minimum working version of Python (>=3.10) on your system to run this script.

For help and examples run ./install_env.sh --help or ./install_env.sh -h in your terminal from the torx base folder.

install_env.sh performs the following steps.

Creates a python virtual environment env.
Installs the packages listed in infra/requirements.in into the virtual environment.
Installs the torx module, as well as the external modules in subprojects. This lets you use e.g. import torx without worrying about relative paths.
Installs a Jupyter kernel called torx (see what is Tor-X).

You can also copy out lines from the .sh script and run them in a bash shell. This is useful if you encounter errors.

Activating and deactivating the environment

Once you’ve successfully installed the environment, you can activate it by running source <path to torx>/env/bin/activate in the command-line.

Activating the environment modifies your $PATH such that when you ask for an executable like python or dask, it uses the version in env/bin. You can run which python to check this.

To deactivate it, simply run deactivate.

Git-LFS

Git-LFS is used to store large reference files used in tests. For the notebooks and tests to work, these files must be downloaded after cloning the repo. Use the following commands

module load git-lfs && git lfs install && git lfs pull

FLARE

The FLARE code is used in some simulation cases for magnetic mesh generation. It also comes with a variety of tools for analysis of the magnetic field geometry in fusion devices. This is an external library provided originally here which has been forked to phoenix for ease of use in the MPCDF infrastructure. The reference for this code is provided here: https://doi.org/10.1088/1741-4326/ad7303.

The MOOSE library is also installed as a prerequisite for FLARE. Similarly, this also has a phoenix fork.

Installation of MOOSE and FLARE with Tor-X

The Tor-X installation script provides a straightforward method for installing FLARE and its dependencies.

It is recommended that you first export the following variables to your environment:

export MOOSE_HOME="<path_to_directory_for_moose>"
export MOOSE_PREFIX="$MOOSE_HOME/install"

export FLARE_HOME="<path_to_directory_for_flare>"
export FLARE_PREFIX="$FLARE_HOME/install"

Load the appropriate modules. Note these will depend on your HPC environment. The following modules are confirmed to work on MPCDF Raven/Viper.

module load gcc/14 netcdf-serial/4.9.2 mkl/2025.1 openmpi/5.0 python-waterboa/2024.06

For an alternative python module, python-waterboa/2025.06 can also be used.

You can then install MOOSE and FLARE along with the required Python dependencies by running the Torx install script with the -fr option:

./install_env -fr --clean

The --clean or -c command is only necessary if you already have a torx environment installed. See also ./install_env -h for other variable options.

This installation should also allow direct import of FLARE as a module in Python via f2py, if you want to use any of the FLARE functions inside Python.

Troubleshooting FLARE

If you have issues with FLARE not detecting the MOOSE installation, try exporting MOOSE to PKG_CONFIG_PATH:

export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:$MOOSE_PREFIX/lib/pkgconfig"

Similarly if FLARE is not detected:

export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:$FLARE_PREFIX/lib/pkgconfig"

Other useful exports that may help with issues are provided here:

export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:$MKLROOT/lib/pkgconfig" 
  
export PATH="$MOOSE_PREFIX/bin:$PATH"
export PYTHONPATH="$MOOSE_PREFIX/lib/python:$PYTHONPATH"
export LD_LIBRARY_PATH="$MOOSE_PREFIX/lib:$LD_LIBRARY_PATH"
  
export PATH="$FLARE_PREFIX/bin:$PATH"
export PYTHONPATH="$FLARE_PREFIX/lib/python:$PYTHONPATH"
export LD_LIBRARY_PATH="$FLARE_PREFIX/lib:$LD_LIBRARY_PATH"