..
   Installation instructions for the toolbox. This file should cover the
   necessary topics for both complete beginners and users familiar with Python.
   It should also provide tailored instructions for specific HPC systems that
   we make use of if relevant.

Installation instructions
=========================

To install gbspy, you will first need to get a copy of the source by cloning
the repository, which you can do with the help of `Git <https://git-scm.com/>`_.
For example,

.. code-block:: bash

   git clone https://c4science.ch/diffusion/11407/python_scripts.git
   cd python_scripts

Before installing the package, you will need a functional Python environment.
If you have already configured Python on the target machine, you can probably
skip the next section.

Installing Python itself
------------------------

Depending on your operating system, you may have to install Python yourself.
This is usually easy and well documented if you have administrative priviledges
on the target machines, but may be less straightforward otherwise.
The decision tree below may provide guidance on which route is best followed.

.. raw:: html

    <object data="_static/python_install_flowchart.svg" type="image/svg+xml"></object>

Anaconda is a distribution of Python and R which targets scientific computing.
Anaconda provides its own package repository and package manager tool. A
lightweight version of Anaconda, called Miniconda, also exists and comes with
minimal dependencies. Anaconda is language agnostic, which implies that
libraries and tools other than Python packages may be installed in Anaconda
environments, such as the GNU C Compiler (gcc), HDF5 or FFTW.
Anaconda requires setting your path environment variables, and may thus create
conflicts with other tools modifying the paths (such as the Modules package).
You may want to avoid Anaconda on machines where path configuration is
critical, such as HPC clusters.

Note that a version of Python lower than 3.7 may fullfill all the package's
dependencies and be suitable to install gbspy. However, we still recommend 3.7
as it is the oldest `currently supported <https://endoflife.date/python>`_
release.

Installing GBSpy
----------------

It is strongly advised to create a virtual environment in which gbspy will be
installed. Virtual environments allow you to install a package in an isolated
location rather than in the global site-packages directory.

The installation process is described for both a regular Python and Anaconda
environment below.

Regular Python
^^^^^^^^^^^^^^

To start, create a virtual environment replacing the path below with a location
of your choice,

.. code-block:: bash

   python3 -m venv /path/to/new/virtual/environment

This environment then needs to be explicitely activate. On a Unix system, for
example:

.. code-block:: bash

   source /path/to/new/virtual/environment/bin/activate

You can check that this environment is enabled by inspecting the output of
``which pip``. To install gbspy, place yourself at the root of the git
repository (in the same directory as the ``setup.cfg``) and run

.. code-block:: bash

   pip install .

This should also install dependencies required by gbspy and will take some
time. Note that when modifying the code, you will need to install the package
again to enable your modifications.

For more information on how to use virtual environments, please refer to the
`Python Packaging User Guide <https://packaging.python.org/en/latest/tutorials/installing-packages/>`_.

Anaconda
^^^^^^^^

As mentionned before, Anaconda environments provide their own package manager:
``conda``. Conda environments are managed globally (contrarily to venvs which
can be installed anywhere) and created through ``conda``. The instructions
below should cover both Anaconda and Miniconda installations.

Conda environments can either be created by issuing multiple commands to the
package manager, or by reading a specially formatted environment file.
An environment file is provided with this repository in the
``conda_environments`` folder.

The following command will install the necessary dependencies for gbspy in a
new conda environment named "gbspy":

.. code-block:: bash

   conda env create -f conda_environments/default.yml

As with Python's virtual environments, one also needs to activate it
explicitely:

.. code-block:: bash

   conda activate gbspy

The steps above, however, do not install gbspy itself, step for which we still
rely on ``pip``. It is however a good idea to prevent ``pip`` from installing
anything else but gbspy, since it will otherwise mix Anaconda and PyPi packages
in our environment. The following command installs only gbspy disregarding any
unfulfilled dependency:

.. code-block:: python

   pip install --no-deps .

As noted in the previous section, you will need to install the package again to
enable your modifications when working with the code.

Machine specific instructions
-----------------------------

While the steps detailed in the previous sections should be enough to start
working with gbspy on most platforms, some systems may require particular
attention.
This section covers machine specific instructions regarding the Python
environment, known issues and workarounds.

..
   MARCONI
   ^^^^^^^

   * Provides Python modules
   * Port forwarding tool for interactive notebooks

   Piz Daint
   ^^^^^^^^^

   * Python modules
   * site-packages
   * Jupyter portal and kernel creation utilities

   For more information, see the `official documentation
   <https://user.cscs.ch/tools/interactive/python/>`_.

   SCITAS Clusters
   ^^^^^^^^^^^^^^^

   * Provides Python modules
   * site-packages
   * Jupyter portal

   SuperMUC
   ^^^^^^^^

   * Firewall and SOCKS proxy
   * pysocks for pip