SHTOOLS can be installed using the brew and macports package managers, or manually using the Makefile.

## brew (macOS, Linux, Windows)

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

brew install shtools


The shtools libraries libSHTOOLS.a and libSHTOOLS-mp.a will be installed in the directory /usr/local/lib, and the compiled module files will be installed in /usr/local/include.

To run the test suite, use

brew test shtools


The output of the tests can be inspected in the user’s logs directory (on macOS, this is Library/Logs/Homebrew/shtools).

## macports (macOS)

If the macports package manager is already installed, it is only necessary to enter the following command in the terminal:

sudo port install shtools


To install the OpenMP components along with the standard Fortran 95 library, add the option +openmp to the last command:

sudo port install shtools +openmp


The shtools library libSHTOOLS.a (and optionally libSHTOOLS-mp.a) will be installed in the directory /opt/local/lib, and the compiled module files will be installed in /opt/local/include. To run the test suite, which is located in /opt/local/share/examples/shtools, use the command

sudo port test shtools


## Using the Makefile

Before trying to install the Fortran 95 components of SHTOOLS, it will be necessary to have a Fortran 95 compiler and LAPACK, BLAS and FFTW3-compatible libraries. On most linux distributions, this can be accomplished using

sudo apt-get install gcc gfortran libfftw3-dev libblas-dev liblapack-dev


or on macOS using

brew install fftw  # using brew
sudo port install fftw-3  # using macports
conda install fftw  # using conda
# lapack and blas can be accessed by linking to the system '-framework Accelerate' or by installin openblas


The Fortran 95 components of SHTOOLS can then be compiled in most cases by executing the following command in a unix shell in the main directory:

make


To compile the Fortran 95 components with OpenMP use

make fortran-mp


To compile and run the Fortran 95 test suites, use

make fortran-tests


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

make clean


By default, the Makefile will use the gfortran compiler. 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"
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, and will place a few compiled module files in the directory include. 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, execute

make install


This will move the compiled SHTOOLS files and documentation to

SYSLIBPATH  # libSHTOOLS.a, libSHTOOLS-mp.a
SYSMODPATH  # ftypes.mod, fftw3.mod, planetsconstants.mod, shtools.mod
SYSSHAREPATH/shtools/examples  # example files
SYSSHAREPATH/man/man1  # man pages


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

SYSLIBPATH = /usr/local/lib
SYSMODPATH = /usr/local/include
SYSSHAREPATH = /usr/local/share


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.

## Fortran 95 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 the LAPACK subroutine names in the SHTOOLS source code by specifying the optional make arguments when building the archive:

LAPACK_UNDERSCORE=1  # add an extra underscore to the LAPACK routine names


For this case, compiler flags should probably be set so that underscores are not appended to routine names. See Fortran 95 problems 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.