Installation

Installing GemPy

We provide the latest release version of GemPy via PyPi package services. We highly recommend using PyPi,

$ pip install gempy

as it will take care of automatically installing all the required dependencies - except in windows that required one extra step.

Windows Installation

Windows does not have a gcc compilers pre-installed. The easiest way to get a aesara compatible compiler is by using the aesara conda installation. Therefore the process would be the following:

$ conda install aesara

$ pip install gempy

Notes:

  • The conda version of aesara comes with a non critical bug that will rise a warning (scan_perform.c) when computing a model with gempy. Once the compiler is installed, installing the pip version of aesara will solve the problem:

$ pip install aesara --force-reinstall

Developers Installation

If you are planning to contribute in gempy the easiest way is to clone the repository from GitHub and use

$ pip install -e .

on the repository root. Notice that on the repo you can also find a optional-requirements.txt for more experimental functionality. Finally to compile sphinx you will need:

$ pip install sphinx, sphinx-gallery

Manual installation

If you want to use the newest, cutting-edge version of GemPy you can clone the current repository by downloading it manually or by using Git by calling

$ git clone https://github.com/cgre-aachen/gempy.git

and then manually install it using the provided Python install file by calling

$ python gempy/setup.py install

in the cloned or downloaded repository folder.

Alternatively to running setup.py, you can use pip to handle the installation from the repository and the updating of the path variables. For this, navigate to the root of the cloned repository and run

$ pip install -e .

Make sure you have installed all necessary dependencies listed below before using GemPy.

Dependencies

GemPy requires Python 3.x and makes use of numerous open-source libraries:

  • pandas

  • aesara>=1.0.4

  • matplotlib

  • numpy

  • pytest

  • seaborn>=0.9

  • networkx

  • scikit-image>=0.17

  • pyvista

Optional requirements:

  • gdal

  • qgrid==1.3.0

  • pymc3

  • pyevtk

  • pyqrcode

  • mplstereonet

Overall we recommend the use of a dedicated Python distribution, such as Anaconda, for hassle-free package installation. We are currently working on providing GemPy also via Anaconda Cloud, for easier installation of its dependencies.

Conflictive packages.

Installing aesara (especially under Windows) and vtk can sometimes be difficult. Here, we provide advice that should use in most cases (but certainly not all):

  • aesara:

    install the following packages before installing aesara:

    $ conda install mingw libpython m2w64-toolchain

    Then install aesara via

    $ conda install aesara

    If the installation fails at some point try to re-install anaconda for a single user (no administrator privileges) and with the Path Environment set. To use aesara with numpy version 1.16.0 or following, it has to be updated to aesara 1.0.4 using

    $ pip install aesara --upgrade

    Note that this is not yet available in the conda package manager.

  • vtk :

    There have been compatibility problems between with the vtk package and python 3.8. The simplest solution to install it is to use $ conda install python==3.6 to downgrade the python version and then using $ pip install vtk .

Docker

Finally we also provide precompiled Docker images hosted on Docker Hub with all necessary dependencies to get GemPy up and running (except vtk).

Docker is an operating-system-level-visualization software, meaning that we can package a tiny operating system with pre-installed software into a Docker image. This Docker image can then be shared with and run by others, enabling them to use intricate dependencies with just a few commands. For this to work the user needs to have a working Docker installation.

Pull Docker image from DockerHub

The easiest way to get gempy running is by running the pre-compiled Docker image (containing everything you need) directly from the cloud service Docker Hub to get a locally running Docker container. Make sure to set your Docker daemon to Linux containers in Docker’s context menu.

$ docker run -it -p 8899:8899 leguark/gempy

This will automatically pull the Docker image from Docker Hub and run it, opening a command line shell inside of the running Docker container. There you have access to the file system inside of the container. Note that this pre-compiled Docker image already contains the GemPy repository.

Once you are in the docker console if you want to open the tutorials you will need to run:

$ jupyter notebook --ip 0.0.0.0 --port 8899 --no-browser --allow-root

Notice that we are running the notebook on the port 8899 to try to avoid conflicts with jupyter servers running in your system. If everything worked fine, the address to the jupyter notebook will be display on the console. It has to look something like this (Just be aware of the brackets):

To access the notebook, open this file in a browser:
        file:///root/.local/share/jupyter/runtime/nbserver-286-open.html
Or copy and paste one of these URLs:
   http://(ce2cdcc55bb0 or 127.0.0.1):8899/?token=97d52c1dc321c42083d8c1b4d

Windows installation guide (March 2020)

  1. This step is only important if you want GPU acceleration. Install CUDA if you do not have it already.

    • For CUDA > 10 (For RTX cards you need those drivers):

      • Go to your cuda installation (probably C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2\bin )

      • Duplicate cublas64_XX and nvrtc64_XX and rename them to cublas64_70 and nvrtc64_70.

  2. Install Conda (recommended: latest miniconda)

    1. Use conda prompt as the python terminal

      Install Anaconda with the options “for current user”.

    Add conda enviroment:

    $ conda create --name gempy python==3.7

    or

    1. Set up conda in the powershell

      Install Anaconda with the options “for current user” and “add conda to Path environment”.

      $ conda init powershell

      As admin: $ Set-ExecutionPolicy RemoteSigned

      After this stage we should have a new empty environment attached to a user

  3. Install aesara and associated packages from the Anaconda prompt as administrator:

    $ conda update --all

    $ conda install libpython

    $ conda install m2w64-toolchain

    $ conda install git

    $ pip install aesara

  4. Install GemPy

    install the latest release version of GemPy via PyPi:

    $ pip install gempy

    Alternatively, if you need the latest developments in GemPy, follow the instruction from the chapter Manual Installation instead.

  5. Set up Jupyter to work properly with conda environments:

    $ conda install Jupyter

    $ conda install nb_conda_kernels

    $ pip install jupyter-conda

  6. Optional requirements:

    $ pip install pyevtk

    $ conda install gdal

Note :b

  • some other packages required by aesara are already included in Anaconda: numpy, scipy, mkl-service, nose, and sphinx.

  • pydot-ng (suggested on aesara web site) yields a lot of errors, therefore we dropped this. It is needed to handle large picture for gif/images and probably it is not needed by GemPy.

  • Trying to install all the packages in one go does not work, as well as doing the same in Anaconda Navigator, or installing an older Anaconda release with Python 3.5 (Anaconda3 4.2.0) as indicated in some tutorial on aesara.

MacOS installation guide (May 2020)

Note: The following guide is for a standard installation (no GPU support). It should work on MacOS 10.14 as well as 10.15 (Catalina).

  1. Install Anaconda (Python Version 3.7)

    For a minimal installation, you can install the Miniconda distribution. The full Anaconda distribution contains some additional features, IDE’s etc. and is available on the Anaconda page.

  2. Create a GemPy conda environment

    We strongly suggest to create a separate conda environment, to avoid conflicts with other Python installations and packages on your system. This is easily done in a bash terminal:

    $ conda create --name gempy python==3.7

    Set up Jupyter to work properly with conda environments:

    $ python -m ipykernel install --user --name gempy

    Activate the new environment (do this every time you create a new terminal session):

    $ conda activate gempy

    You should now see (gempy) at the beginning of the command line. If the previous command fails (some known issues), then try:

    $ source activate gempy

  3. Install the Xcode command-line tools

    In order for aesara to access the system compilers on MacOS, the Xcode command-line tools are required. To automatically install the correct version for your OS, run:

    $ xcode-select --install

    Follow the installation instructions. After the installation is complete, open Software  Update from your System Preferences and install any available updates for the command-line tools.

  4. Install required Python packages

    $ conda update --all

    Install aesara via PyPi

    $ pip install aesara

    Test the aesara installation: run python, then try import aesara. If you get an error (e.g. stdio.h not found), then:

    Test if the Xcode command-line tools are correctly installed and up-to-date.(info for example here). If this still fails, try installing aesara through conda-forge instead:

    $ conda install -c conda-forge aesara

  5. Install GemPy

    install the latest release version of GemPy via PyPi:

    $ pip install gempy

    Alternatively, if you need the latest developments in GemPy, follow the instruction from the chapter Manual Installation instead.

  6. Install optional requirements:

    $ pip install pyvista

    $ pip install pyevtk

    $ conda install gdal