SHTOOLS --- Tools for working with spherical harmonics

> Home > Documentation

Installation Instructions

SHTOOLS can be installed in several ways. If you will be using only the Python components, it is recommended to use the pip package manager. If you will be writing and compiling Fortran 95 code, it is recommended to use either the Brew package manager (on OSX), or to compile using the Makefile.

1. Python package installer: pip

The easiest way to install the Python components of SHTOOLS is to use pip. First, make sure that you have the necessary dependencies installed. This can be done on most linux distributions using

sudo apt-get install libblas-dev liblapack-dev g++ gfortran libfftw3-dev tcsh

or on OSX using brew

brew install fftw --with-fortran

Then, execute the following command in a unix terminal:

pip install pyshtools

If you want to instead work on a developer version, download the SHTOOLS repository from GitHub. Then, in the SHTOOLS main directory, execute

pip install .

which will install pyshtools in the system Python library. If you would like to install the files in the current working directory, so that you can easily edit the source files and link them to the system Python directory, enter the following command instead:

pip install -e .

To uninstall pyshtools from your system directory, enter

pip uninstall pyshtools

Note that this will only install the Python version that corresponds to the version of pip being used. On some systems, it may be necessary to specify pip2.7 or pip3.5.

2. Homebrew package manager (OSX)

If brew is already installed, it is only necessary to enter the following commands in the terminal:

brew tap shtools/shtools
brew install shtools

This will install only the Fortran 95 component of SHTOOLS. To also install the Fortran 95 OpenMP component, add the option --with-openmp to the last command. Brew can also install the Python components (using the Makefile approach below), but this is not encouraged.

3. Manual installation using make

Before installing SHTOOLS, it will be necessary to have a Fortran 95 compiler, Python, and the FFTW, LAPACK, and BLAS libraries installed on your computer. After this is done, the Fortran 95, Python 2, and Python 3 components of SHTOOLS can be compiled in most cases by executing the following command in a unix shell in the main SHTOOLS directory:

make

To compile individual components, such as Fortran 95, Fortran 95 with OpenMP, Python 2, and Python 3, use

make fortran fortran-mp python2 python3

To compile and run the Fortran 95 and Python test suites, use

make fortran-tests
make python2-tests
make python3-tests

To delete the compiled archive, module files, object files, and test suite files, use

make clean

By default, the Makefile will use the binaries gfortran, f2py and python (for Python 2), and f2py3 and python3 (for Python 3). Different compilers and options can be specified by passing optional arguments to the Makefile using the syntax

make F95="MyCompiler" F95FLAGS="MyCompilerFlags"

where "MyCompiler" and "MyCompilerFlags" are to be replaced by the path of the compiler name and options, respectively. Supported options include:

F95="Name (including path) of the f95 compiler"
F95FLAGS="F95 compiler options"
F2PY="Name (including path) of the Python 2 f2py executable"
F2PY3="Name (including path) of the Python 3 f2py executable"
PYTHON="Name (including path) of the Python 2 executable"
PYTHON3="Name (including path) of the Python 3 executable"
FFTW=Name and path of the FFTW3 library of the form "-Lpath -lfftw3"
LAPACK=Name and path of the LAPACK library of the form "-Lpath -llapack"
BLAS=Name and path of the BLAS library of the form "-Lpath -lblas"

Successful compilation will create the library file libSHTOOLS.a (and libSHTOOLS-mp.a when compiling with OpenMP) in the directory lib, will place a few compiled module files in the directory modules, and will create a few .so files in the directory pyshtools. The resulting output should look something like this. If you need to recompile SHTOOLS a second time using a different set of compiler flags, it will be necessary to first remove all the previously compiled object files by using make clean.

To make all files available at a system level, run

make install

This will move the compiled SHTOOLS files and documentation to

SYSPYPATH/pyshtools (python module)
SYSLIBPATH (libSHTOOLS.a, libSHTOOLS-mp.a)
SYSMODPATH (fftw3.mod, planetsconstants.mod, shtools.mod)
SYSSHAREPATH/shtools/examples (example files)
SYSSHAREPATH/man/man1 (man pages)
SYSDOCPATH/shtools (index.html, web documentation)

The locations of the above directories can be set as optional arguments passed to the Makefile, and the default locations are

SYSPYPATH=python variable sysconfig.get_path("platlib")
SYSLIBPATH=/usr/local/lib
SYSMODPATH=/usr/local/include
SYSSHAREPATH=/usr/local/share
SYSDOCPATH=/usr/local/share/doc

To remove all installed SHTOOLS files, use

make uninstall

To access the unix man pages, it will be necessary to add SYSSHAREPATH/man to your man path.

3.1 Python compiler specific flags

When compiling the python wrappers and running the python examples, it is important to use the correct versions of f2py and python. Most systems provide binaries that include the name of the python version, such as python2.7, python3.5, f2py2.7 and f2py3.5. These binaries may or may not be linked to generic names such as python and f2py. If there are incompatibilities with your system's naming convention and those described above, it will be necessary to pass the optional arguments PYTHON, PYTHON3, F2PY and F2PY3 to the Makefile.

If binaries do not exist for f2py, the python wrappers can be generated by specifying the following:

make F2PY="python -m numpy.f2py" F2PY3="python3 -m numpy.f2py"

This is necessary on OSX (using the brew installation), as installing both Python 2 and 3 will create only a single f2py that is overwritten by the last install.

3.2 Fortran compiler specific flags and optimizations

Default compiler options are specified in the main Makefile for a few common compilers (gfortran, Absoft f95, g95, and ifort). If it is necessary to change these, consider the following guidelines.

One should always use some form of optimization when compiling SHTOOLS, such as by specifying the option

-O3

Performance will likely be increased by 10s of percent by specifying the compiler to target the host architecture

-march=host (f95)

-march=native (gfortran)

and to use fast math

-speed_math=11 (f95)

-ffast-math (gfortran)

The biggest difficulty in compiling SHTOOLS is setting the compiler flags so that the external subroutine names are in a format that is compatible with the already compiled FFTW and LAPACK libraries. In general, it is necessary to ensure that the SHTOOLS subroutine names are in lower case and have the right number of underscores appended to them.

For Absoft ProFortran, this is achieved by setting

-YEXT_NAMES=LCS -YEXT_SFX=_

For g95, it will be necessary to use one of the following:

-fno-second-underscore (most likely)
-fno-underscoring

For gfortran, it is generally not necessary to use any special flags, though it could arise that one of the following might be necessary:

-fno-underscoring
-fsecond-underscore

For the Intel Fortran compiler ifort, it will be necessary to use

-free -Tf

in order that the compiler recognizes files with the extension .f95 as fortran 95 files. In this case, the f95 file should come directly after the option -Tf.

Setting the right compiler flags is more complicated when the FFTW and LAPACK libraries have different naming and underscoring conventions. In order to accommodate this case, underscores can be added explicitly to either the LAPACK or FFTW subroutine names in the SHTOOLS source code by specifying the optional make arguments when building the archive:

FFTW_UNDERSCORE=1 (to add an extra underscore to the FFTW routine names)
LAPACK_UNDERSCORE=1 (to add an extra underscore to the LAPACK routine names)

For both cases, compiler flags should probably be set so that underscores are not appended to routine names. See the FAQ for further information.

To generate 64 bit code, use the compiler option

-m64

For this case, it will be necessary to use 64-bit compiled FFTW and LAPACK libraries.

> Home > Documentation

Laboratoire Lagrange Observatoire de la Côte d'Azur © 2016 SHTOOLS