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.
Edit me