Installation

Due to the heavy use of object-oriented features (Fortran 2003) and submodules (Fortran 2008), Legolas requires relatively recent Fortran compilers. This page gives a detailed overview of required and optional dependencies to successfully build and run both Legolas and the post-processing framework Pylbo. Note that the compilers noted below are only recommended, and it is quite possible that Legolas also builds with lower versions.

Dependencies

Compilation

• gfortran v8.x+
• CMake v3.12+
• make

Post-processing

The post-processing framework Pylbo has a few standard dependencies, all of which will be automatically installed if you choose the Pylbo package install (see below).

• Python v3.6+
• Numpy, for obvious reasons.
• Matplotlib, for plotting.
• f90nml, to handle reading and writing of Fortran namelists.
• tqdm, used for progress bars.
• psutil, for management of multiprocessing resources during parallel runs.

You can alternatively install these manually using

pip install numpy matplotlib f90nml tqdm psutils


or

conda install numpy matplotlib f90nml tqdm psutils


depending on your preference. On Linux it’s usually best to use the versions available in your package repository.

Note: Python is only needed for Pylbo, not for Legolas itself. You can still run Legolas if the Python requirements are not satisfied, however you will not be able to immediately see the results after the run finishes (so set show_results=.false. in the parfile).

BLAS and LAPACK

The BLAS and LAPACK linear algebra packages are required dependencies, and you will not be able to compile without them. We recommend version 3.5 or higher. CMake is configured in such a way that both libraries should be found and linked automatically if they are installed. An easy (but not the only) way to install these packages is as follows

• Linux (Debian/Ubuntu)
sudo apt-get install libblas-dev
sudo apt-get install liblapack-dev

• macOS, using HomeBrew.
brew install openblas
brew install lapack


Note that macOS ships with a default BLAS/LAPACK installation as part of the vecLib framework, so a custom installation is optional.

If you did a manual compilation of the BLAS and LAPACK libraries (if you don’t have sudo rights, for example), CMake may not find the libraries by default. In that case it will throw a warning, and you may have to set the $BLAS_LIBRARIES and $LAPACK_LIBRARIES variables which link to the compiled libraries.

ARPACK

The ARPACK library is an optional dependency, so Legolas will compile and run just fine if you don’t have this installed (related modules are conditionally compiled). Also here CMake will try to automatically find and link the libraries if installed.

We recommend using the actively maintained arpack-ng. Unfortunately most operating systems do not have this version readily available, so you will have to install it manually using the following commands.

git clone https://github.com/opencollab/arpack-ng.git
cd arpack-ng
mkdir build
mkdir installed
cd build
cmake -DEXAMPLES=ON -DMPI=OFF -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=../installed ..
make
make install


Afterwards you export the $ARPACK_ROOT environment variable, pointing to your arpack-ng folder. Legolas Legolas can be obtained by cloning the online repository: git clone https://github.com/n-claes/legolas.git  which will put it in the local repository legolas. Next you set the environment variable $LEGOLASDIR which points to this directory and add the setup_tools subdirectory to your PATH. For example, if you cloned the legolas repository to /users/codes/legolas, you can edit your .bashrc (or .zshrc on macOS) as follows

export LEGOLASDIR="/users/codes/legolas"
PATH="$PATH:$LEGOLASDIR/setup_tools"


The last line allows for easy access to the buildlegolas.sh and setuplegolas.py scripts in the setup_tools folder, such that they can be called from any directory.

Compilation

To compile Legolas you first navigate to the legolas directory:

Installing as a package

This is the recommended installation option. To do so, navigate to the post_processing folder and do the following:

cd post_processing
python setup.py develop


This will automatically install the listed dependencies if they are not already installed. Activate any conda/virtualenv environment beforehand in order to install Pylbo there. The develop argument means that the package will be automatically updated whenever you update the repository.

Sourcing the folder

Another possibility is adding the folder to your PYTHONPATH. If the above option is not available, i.e. if you can not manage your python installation then this is a valid alternative. Note that in this case you will have to install all dependencies yourself.

• macOS/Linux Edit .zshrc/.bashrc or similar, we assume that you have already set the $LEGOLASDIR environment variable (see here). export PYTHONPATH=$LEGOLASDIR/post_processing:\$PYTHONPATH

• Windows Go to Start > Control panel > Edit the system environment variables > tab "advanced" > environment variables. Create or edit the PYTHONPATH environment variable and add the full path to the post_processing folder. Multiple paths are separated by a semicolon ";".

Next steps

Now that you’ve successfully installed Legolas and Pylbo you can move on to your first run.