Installation

We only support installation on recent mac and linux systems, not on windows.

You need Python 3 in order to install SurfaceTopography.

In complement to the instructions below, you will find examples of system setups and intallation workflows in our singularity containers singularity containers and our testing workflows

Optional dependencies

NetCDF and FFTW3

Direct installation with pip

SurfaceTopography can be installed by invoking

python3 -m pip  install [--user] SurfaceTopography

Or if you want the latest unreleased version

python3 -m pip  install [--user] git+https://github.com/ContactEngineering/SurfaceTopography.git

The command will install other dependencies including muSpectre_, NuMPI and runtests.

If you want to install all optional dependencies for full functionality:

wget https://raw.githubusercontent.com/ContactEngineering/SurfaceTopography/master/requirements.txt
# I found the url to the requirements files using
# https://api.github.com/repos/ContactEngineering/SurfaceTopography/contents/requirements.txt
python3 -m pip install [--user] -r requirements.txt --no-binary numpy
rm requirements.txt

Tip: to install NetCDF on ubuntu, you can for example use

sudo apt-get install libnetcdf-dev

See also our singularity container for an example installation on ubuntu.

Tip: to install NetCDF on mac using Homebrew,

brew install netcdf

Installation: Common problems

  • Sometimes muFFT will not find the FFTW3 installation you expect. You can specify the directory where you installed FFTW3 by setting the environment variable FFTWDIR (e.g. to $USER/.local).

  • If muFFT is unable to find the NetCDF libraries (the FileIONetCDF class is missing), then set the environment variables NETCDFDIR (for serial compile) or PNETCDFDIR (for parallel compiles, to e.g. $USER/.local).

  • Sometimes the installation fails because muFFT attempts to compile with MPI support but not all necessary libraries are available.

  • Note that if you do not install a tagged version of a dependency (e.g. because you install from the master branch via`git+` or from source using directly setup.py), pip will attempt to reinstall that dependency despite it is already installed. In that case you need to avoid using pip install and install SurfaceTopography from the source directory using `Meson.

Reporting installation problems

  1. Make sure that you carefully read all these instructions.

  2. Try to find similar issues in our issues or forum discussions.

  3. Please open an issue or a discussion in the forum.

When reporting a problem, please provide us with following information:

  • your system configuration,

  • your python3 environment (output of python3 -m pip list)

  • The output of the verbose installation e.g. python3 -m pip install –verbose –global-option=”–verbose”

Installation from source directory

First you need to run

git submodule update --init --recursive

in the source directory.

SurfaceTopography can be installed from source by invoking

python3 -m pip install [--user] .

in the source directoy. The command line parameter –user is optional and leads to a local installation in the current user’s $HOME/.local directory.

Alternative build and installation options

  • meson build
    meson setup build
cd build
meson compile
meson install

    on mac meson install has issues with finding the correct installation directories. You have to specify them manually:

    SITEPACK=$(python3 -m site --user-site)

    meson setup  --prefix=$(python3 -m site --user-base) .  builiddir --python.purelibdir $SITEPACK --python.platlibdir $SITEPACK

  • Editable mode installations are supported by new versions of meson. However there are bugs on mac still.

    python3 -m pip install -e .

  • Building and installing a wheel:

    rm -rf dist
python3 -m build -w -n .
python3 -m pip uninstall -y SurfaceTopography
python3 -m pip install dist/*.whl

Singularity container

We provide a definition file to build a singularity container here .