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. For example,

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.

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 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,

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

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

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

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.

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”:

conda env create -f conda_environments/default.yml

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

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:

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.