docs: updated installation page

docs/getting-started/installation.md

@@ -1,158 +1,154 @@
 ---
+title: Installation
 layout: single
+classes: wide
 sidebar:
   nav: "leftcontents"
 toc: true
 toc_label: "Installation Guide"
 toc_icon: "cogs"
-last_modified_at: 2020-11-27
+last_modified_at: 2021-07-26
 ---
 
 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](../../pylbo/installing_pylbo/). Note that the compilers noted below are only recommended,
-and it is quite possible that Legolas also builds with lower versions (we haven't tested that).
+[Pylbo](../../pylbo/about_pylbo/). Note that the compilers noted below are only recommended,
+and it is quite possible that Legolas also builds with lower versions.
 
 # Dependencies
 ## Compilation
-- Fortran compiler
-    - gfortran v8.x+ (recommended and tested)
-    - Intel compilers v18.0+ (not tested)
+- gfortran v8.x+
 - CMake v3.12+
-- Python v3.6+
 - make
 
-**Note:** Python is needed for Pylbo, not for Legolas itself. You can still run Legolas
+## 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](/getting-started/installation/#installing-as-a-package)).
+- Python v3.6+
+- [Numpy](https://numpy.org), for obvious reasons.
+- [Matplotlib](https://matplotlib.org), for plotting.
+- [f90nml](https://f90nml.readthedocs.io/en/latest/), to handle reading and writing of Fortran namelists.
+- [tqdm](https://tqdm.github.io), used for progress bars.
+- [psutil](https://psutil.readthedocs.io/en/latest/), for management of multiprocessing resources during parallel runs.
+
+**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).
 {: .notice--info}
 
-## Linear algebra
-### BLAS and LAPACK
+## BLAS and LAPACK
 The [BLAS](http://www.netlib.org/blas/) and [LAPACK](http://www.netlib.org/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. In general, it is sufficient if you have them installed through
-```bash
-sudo apt-get install libblas-dev
-sudo apt-get install liblapack-dev
-```
-if you're on Linux, or through
-```bash
-brew install openblas
-brew install lapack
-```
-using [HomeBrew](https://brew.sh) on macOS. Note that macOS ships with a default BLAS/LAPACK installation
-as part of the [vecLib](https://developer.apple.com/documentation/accelerate/veclib) framework.
+they are installed. An easy (but not the only) way to install these packages is as follows
+- **Linux**
+  ```bash
+  sudo apt-get install libblas-dev
+  sudo apt-get install liblapack-dev
+  ```
+- **macOS**, using [HomeBrew](https://brew.sh).
+  ```bash
+  brew install openblas
+  brew install lapack
+  ```
+   Note that macOS ships with a default BLAS/LAPACK installation as part of the
+  [vecLib](https://developer.apple.com/documentation/accelerate/veclib) framework, so a custom installation is optional.
+  {: .notice--info}
+
 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](https://www.caam.rice.edu/software/ARPACK/) library (and its parallel counterpart
-PARPACK is an **optional** dependency, so
+## ARPACK
+The [ARPACK](https://www.caam.rice.edu/software/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 maintained [arpack-ng](https://github.com/opencollab/arpack-ng) repository to
-install ARPACK. If CMake fails to find the library and you have it installed, you can set the
-`$ARPACK_ROOT` environment variable, pointing to the top-level of your local `arpack-ng` repository.
-
-
-### SCALAPACK
-The [SCALAPACK](http://www.netlib.org/scalapack/) package is an **optional** depencency.
-CMake has been configured to find and link this library, but this feature is currently
-disabled since Legolas does not have SCALAPACK routines implemented (yet).
-
-
-### MUMPS
-The [MUMPS](http://mumps.enseeiht.fr) library is an **optional** dependency.
-CMake has been configured to find and link this library, but this feature is currently
-disabled since Legolas does not have MUMPS routines implemented (yet).
+We recommend using the maintained [arpack-ng](https://github.com/opencollab/arpack-ng) repository to
+install ARPACK. You can execute the piece of code below to clone the repository and install:
+```bash
+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.
 
 
-# Building Legolas
-## Obtaining the code
+# Legolas
 Legolas can be obtained by cloning the online repository:
 ```bash
 git clone https://github.com/n-claes/legolas.git
 ```
 which will put it in the local repository `legolas`.
-CMake has been configured for an out-of-source build, meaning that the repository stays clean.
-This allows for easy updates through `git pull`.
-
-## Environment variables
-For an easy setup we recommend setting the environment variable `$LEGOLASDIR` and adding
-the `setup_tools` folder to your PATH. This can be done by editing your `.bashrc` (or `.zshrc` on macOS)
-as follows
+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
 ```bash
-export LEGOLASDIR='path_to_the_legolas_directory'
+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.
 
-## Compiling the code
-Compiling the code is quite straightforward, and for your convenience we have provided a simple shell script
-to do everything at once. Compiling the code can either be done from inside the repository or from a dedicated folder somewhere.
-The latter option will be particularly useful when you're setting up your own problems.
-
-**Note:** whichever of the two options you choose, `Legolas` is _always_ compiled in a directory called `build`
-_inside_ the main repository, which is ignored by git. Because we make heavy use of submodules (which prevent
-compilation cascades when changes are made), you don't have to recompile the code every time you set up a new problem.
-Only the modified user-defined submodule is recompiled, and the "new" executable is placed in the same directory.
-{: .notice--info}
-
-### 1. In-repository build
-The first option is building inside the repository. To do so, navigate to the legolas source directory and do
+## Compilation
+To compile Legolas you first navigate to the `legolas` directory:
 ```bash
-sh setup_tools/buildlegolas.sh
+cd $LEGOLASDIR
 ```
-This will create a directory `build` inside the repository (which is ignored by git), and places the `legolas`
-executable in the topmost directory. You can also do it manually:
+Next you have the option of compiling the code manually, or to use the shell script we provided which
+automatically takes care of creating build folders and calling the various make commands.
+- For a manual build
+  ```bash
+  mkdir build
+  cd build
+  cmake ..
+  make
+  ```
+- For an automagic build
+  ```bash
+  buildlegolas.sh
+  ```
+
+## Doing a clean build
+To do a fresh compilation you can call the build script with an additional argument
 ```bash
-mkdir build
-cd build
-cmake ..
-make
-```
-An in-repository build is fine if you want to run pre-implemented problems, but note that when you start modifying
-equilibria (or adding your own) you are essentially modifying the source files. This means that you will probably run
-into merge conflicts soon when you're updating the code (and we all hate those!) so we don't recommend doing it like this.
-
-### 2. Out-of-repository build (recommended)
-This is the recommended way to build Legolas. This requires you to have set the environment variable and PATH
-modification described above. To setup a folder for a Legolas build, call `setuplegolas.py` from the command line and
-follow the instructions. The script will do (and ask you) a couple of things:
-1. Copy over `CMakeLists.txt`.
-2. Copy over `pylbo_wrapper.py`, which you will need if you want to plot the results afterwards.
-3. Copy over a default parfile if none was found.
-4. Copy over the default user submodule template if none was found.
-5. Modify the build script to include the custom submodule if found.
-
-Next you simply build as described before, either through `buildlegolas.sh` which does everything automatically, or
-manually through
-```bash
-mkdir build
-cd build
-cmake ..
-make
+buildlegolas.sh clean
 ```
-In both cases the executable is placed in the same directory as the parfile and user submodule.
-
-# Doing a clean build
-Since we use CMake for compilation there is no exact `make clean` equivalent as there is with GNU Make.
-Instead, you can do one of the following things:
-1. Navigate to the `build` directory (inside the repository or the local one) and do `make clean`.
-   This removes the compiled object files and lets you do a fresh `make` compilation.
-2. Remove the (local) `build` directory, re-create it and compile again. This is perhaps best way to 
-   do it, since that means that the `CMakeCache` is removed as well.
-   
-You can also do this automatically from any directory by supplying an additional argument to `buildlegolas.sh`.
-Say you just compiled in a local directory and you want to do a fresh compilation, simply call
+This will remove
+1. the legolas executable in the current working directory (if found)
+2. the `build` folder in the current working directory
+3. the `build` folder in the legolas directory
+
+You can also remove these folders manually instead if you prefer.
+
+# Pylbo
+The Pylbo framework is automatically included in the `legolas/post_processing` folder when you
+clone the repository.
+## Installing as a package
+This is the recommended installation option. To do so, navigate to the `post_processing` folder and do the following:
 ```bash
-buildlegolas.sh clean
+cd post_processing
+python setup.py develop
 ```
-This will remove the `build` folder in the main legolas directory, the local `build` directory and the local executable (if one is found).
+This will automatically install the listed [dependencies](/getting-started/installation/#post-processing) if they are not already installed. Activate any conda/virtualenv environment
+beforehand in order to install pylbo there. The `develop` argument means that you 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](/getting-started/installation/#legolas)).
+  ```bash
+  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 `";"`. -->