# Installing the `torx` environment and Jupyter kernel

To install the Tor-X _environment_ (see [what is Tor-X](what-is-torx)), 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.

1. Creates a python virtual environment `env`.
2. Installs the packages listed in `infra/requirements.in` into the virtual environment.
3. 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.
4. Installs a Jupyter kernel called `torx` (see [what is Tor-X](what-is-torx)).

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](https://gitlab.com/hfrerichs/flare) 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](https://doi.org/10.1088/1741-4326/ad7303).

The [MOOSE library](https://gitlab.com/hfrerichs/moose) 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.

1. 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"
```

2. 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.

3. 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"
```