Calling SHTOOLS routines
To access the SHTOOLS functions and subroutines in your code, it is necessary to place the statement
directly after the program, subroutine, or function declaration (i.e., before an
implicit none statement). The SHTOOLS module contains an interface block that declares the subroutines and functions used in this archive and allows for the use of implicitly shaped arrays. It should be noted that all arrays passed to a subroutine or function can be larger than that specified in the documentation.
Linking to the SHTOOLS library
When compiling a code that references SHTOOLS, it will be necessary to link to the SHTOOLS library and module files. For this purpose, it may be useful to define the environment variables
SHTOOLSLIBPATH using the default file locations. In a C-shell, this is accomplished using
setenv SHTOOLSLIBPATH = "/usr/local/lib" setenv SHTOOLSMODPATH = "/usr/local/include"
whereas for a bash shell the syntax is
export SHTOOLSLIBPATH = "/usr/local/lib" export SHTOOLSMODPATH = "/usr/local/include"
In addition, most routines require linking to libraries that are compatible with the fast Fourier transform package FFTW, and the linear algebra packages LAPACK and BLAS. SHTOOLS is compatible with the FFT routines in Intel’s MKL library. Furthermore, it is noted that there are many different system optimized versions of LAPACK and BLAS, some of which may be pre-installed on your machine.
Typical examples of compiling and linking a program
MyProgram.f95 to the necessary library and module files are given below for several common compilers.
gfortran MyProgram.f95 -I$SHTOOLSMODPATH -L$SHTOOLSLIBPATH -lSHTOOLS -lfftw3 -lm -llapack -lblas -O3 -m64 -o MyProgram
Absoft Pro Fortran (f95)
f95 MyProgram.f95 -p $SHTOOLSMODPATH -L$SHTOOLSLIBPATH -YEXT_NAMES=LCS -YEXT_SFX=_ -lSHTOOLS -lfftw3 -lm -llapack -lblas -O3 -m64 -o MyProgram
g95 MyProgram.f95 -I$SHTOOLSMODPATH -L$SHTOOLSLIBPATH -fno-second-underscore -lSHTOOLS -lfftw3 -lm -llapack -lblas -O3 -m64 -o MyProgram
Intel Fortran (ifort)
ifort -fpp -free -I$SHTOOLSMODPATH -L$SHTOOLSLIBPATH -lSHTOOLS -lfftw3 -lm -llapack -lblas -O3 -m64 -Tf MyProgram.f95 -o MyProgram
Note that the position of the source file in the above examples might be important for some compilers. Note also that on macOS, linking to the preinstalled LAPACK and BLAS libraries can be accomplished using
-framework Accelerate. (See installing SHTOOLS for more details).
The Fortran 95 routines in the OpenMP version of SHTOOLS are OpenMP compatible and OpenMP thread-safe. To use these routines in a program that uses OpenMP, it is necessary to link to the library
libSHTOOLS-mp.a and to add one of the following compiler options:
-fopenmp # gfortran -openmp # Absoft Pro Fortran -qopenmp # ifort
Fortran array indices
Fortran arrays usually start with an index of 1. However, with spherical harmonic functions and coefficients a degree-0 term exists. In order to deal with this, all arrays that are a function of spherical harmonic degree
l and order
m have 1 added to each of their indices. For instance, the real Fortran array
clm is related to the spherical harmonic coefficients by
In this notation, the positive and negative angular orders correspond to the cosine and sine coefficients, respectively (see the page real spherical harmonics for more information).
Using optional parameters
Many of the subroutines and functions in this archive can accept one or more optional parameters. To specify these parameters, it is only necessary to use the syntax
call SHRead (FILENAME, CILM, LMAX, SKIP=1, ERROR=errorcoef)
ERROR are the names of two optional parameters, and the constant
1 and variable
errorcoef are their respective arguments.
Documentation for the Fortran 95 subroutines and functions in SHTOOLS can be accessed by their unix man pages, using all lower case letters. As an example, to access the
MakeGridDH man page, use
Alternatively, the man pages can be accessed from the Fortran 95 Routines menu on this web site.Edit me