If only the fortran components of SHTOOLS are required, they can be installed manually using the Makefile or by using the macOS package manager brew.

Fortran 95 library using brew (macOS)

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

brew tap shtools/shtools
brew install shtools

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

brew install shtools --with-openmp

Fortran 95 library 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 libblas-dev liblapack-dev g++ gfortran libfftw3-dev tcsh

or on macOS using brew

brew install fftw
# lapack and blas can be accessed by linking to the system '-framework Accelerate'

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 modules. 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
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

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.

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.

Edit me