Python environment

The multi-physics capabilities of Kraken build on the Python packages Cerberus, Cetus and KrakenTools. Setting these packages up may require some initial preparation from the side of the Python environment.

Kraken has been tested with Python 3.8, 3.9 and 3.10 but many modern Python 3 versions are likely to work.

You can use Kraken in your normal environment by setting up the Python paths and other environmental variables in e.g. your .bashrc-file, but utilizing a virtual environment can be useful for setting up all of the required packages and libraries in a way that minimizes potential conflicts with other packages and libraries.

The following is a walkthrough for setting up a virtual environment in Linux. See also Virtual environment on Windows.

Installing virtualenvwrapper

Install a recent Python3 version, e.g. Python 3.8. First you should figure out where this Python was installed as you will need the path later. You can do this with

which python3.8

The command should yield a full path to the Python binary (your-python-binary-path, used later in the setup), such as:

/usr/bin/python3.8

Make sure that you also have pip installed for the same Python version, e.g. by running

python3.8 -m pip

If you don't have pip installed, you may need to install it from a package such as sudo apt install python3-pip or manually in some other way.

With this modern Python version (no need to use full path here), use the following command to install the virtualenvwrapper package using the package handling module of Python, pip:

python3.8 -m pip install virtualenvwrapper

In some recent installations, you may get an error: externally-managed-environment, which can be circumvented with an additional switch python3.8 -m pip install --break-system-packages virtualenvwrapper Now you'll need to check where the virtualenwrapper shell script was installed using, for example

find ~ -name "virtualenvwrapper.sh" -type f

You should get some path (your-virtualenvwrapper.sh-path used later in the setup) similar to

/home/vvvillehe/.local/bin/virtualenvwrapper.sh

In a similar manner, install virtualenv and figure out where it was installed

python3.8 -m pip install virtualenv
find ~ -name "virtualenv" -type f

to get your-virtualenv-path such as

/home/vvvillehe/.local/bin/virtualenv

Add the following lines to your .bashrc:

# New virtual environments will be stored under this folder
export WORKON_HOME=~/Envs

# Which python has virtualenvwrapper installed
export VIRTUALENVWRAPPER_PYTHON=your-python-binary-path

# Where was virtualenv installed
export VIRTUALENVWRAPPER_VIRTUALENV=your-virtualenv-path

# Where was virtualenvwrapper.sh installed
source your-virtualenvwrapper.sh-path

For example:

# New virtual environments will be stored under this folder
export WORKON_HOME=~/Envs

# Which python has virtualenvwrapper installed
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3.8

# Where was virtualenv installed
export VIRTUALENVWRAPPER_VIRTUALENV=~/.local/bin/virtualenv

# Where was virtualenvwrapper.sh installed
source ~/.local/bin/virtualenvwrapper.sh

At this point, you should open a new terminal window so that the added commands get executed and continue the setup in that terminal.

Creating a virtual environment for Kraken

Create a new virtual environment called kraken

mkvirtualenv kraken

After this, you can activate the kraken environment (to load all installed dependencies) with

workon kraken

You should see a (kraken) in your command line path indicating that this is the virtual environment you are working on.

deactivate

will close the virtual environment.

Installing dependencies

Start with activating the virtual environment

workon kraken

Any Python packages you install while working on a virtual environment will be contained in that environment. Also, since you defined the Python binary that virtualenvwrapper should use, the simple command

python

will always use that binary while working on a virtual environment. This means you can simply install the required packages with

python -m pip install numpy
python -m pip install scipy
python -m pip install matplotlib
python -m pip install serpenttools

Adding folders to the Python path

We'll also need to add the folders of our own Python modules such as KrakenTools and Cerberus to the Python path included in the virtual environment

add2virtualenv ~/kraken-1.2/KrakenTools
add2virtualenv ~/kraken-1.2/Cerberus
add2virtualenv ~/kraken-1.2/Cetus

The paths above depend on where you set cloned the repositories and should point to the root of the repository.

Setting up environment variables

You can also include and restrict certain environment variables (ANTS_EXE_PATH, SERPENT_DATA etc.) to the virtual environment. The definitions should be added to the

~/Envs/kraken/bin/postactivate

file, whose contents will be included after the kraken environment is activated via workon kraken. You can modify the contents of the file to include, e.g.

export ANTS_EXE_PATH=/home/vvvillehe/kraken-1.2/Ants/bin/Release/gfortran/ants
export SUPERFINIX_EXE_PATH=/home/vvvillehe/kraken-1.2/SuperFINIX/superfinix

These can be set up later once you have managed to compile the solvers. Of course you can also set up these environment variables in your ~/.bashrc file.

Working with the virtual environment

After setting everything up once, you can activate the virtual environment using

workon kraken

and deactivate it using

deactivate