SHTOOLS --- Tools for working with spherical harmonics

HOME DOWNLOAD DOCUMENTATION FORUM FAQ

> Home > Documentation

Frequently Asked Questions

General

Compiling Problems

Linking Problems

Runtime Problems

Who maintains SHTOOLS?

This archive was created, and is maintained, by Mark Wieczorek. If you have any questions, send me a mail at wieczor@ipgp.fr. If you are looking for my web site, go to www.ipgp.fr/~wieczor.

I have a question or suggestion.

Before sending send me a mail, please read the documentation, read the FAQ, and consult the user forum. Please realize that I am neither a professional web designer nor a professional programmer. I would be greatful for any advice or help on how to improve the website, makefiles, etc.

Do you plan on making a routine to...

Perhaps. If it is simple, then sure. If it is more complicated, I'll add this to my to-do list. If you are impatient, enquire about my consulting fees.

Can I use the SHTOOLS library with C, F77 and Matlab codes?

Probably, but I don't know how. If you get this to work, let me know how you did it, and I will add these instructions to the documentation. This is something that I would like to do in the future.

How do I cite SHTOOLS in a publication?

At this point, there is not a publication describing this archive of code (though I intend on writing a short announcement for EOS in the near future). I suggest simply giving the URL, as in this example sentence:

"Our spherical harmonic analyses were performed using the freely available software archive SHTOOLS (available at http://www.ipgp.fr/~wieczor/SHTOOLS/SHTOOLS.html)."

If you are using a routine that is based on an algorithm that I developed (such as the computation of potential anomalies resulting from finite-amplitude topography, multitaper spectral analyses, or computation of the geoid) then you should reference the appropriate publication cited in the man pages.

Where can I find more information?

Consider joining the discussion group SHTOOLS at Google Groups. Other online resources are:

Will you help me with my homework?

Absolutely not.

I don't understand Fortran. Will you explain step by step how to modify the example codes?

No. There is probably a way to call the SHTOOLS routines from other languages, such as C or Matlab. Please let me know if you get this to work.

How do I make images with the output from SHTOOLS?

The output from SHTOOLS is typically in the form of an ASCII raster file. Any standard software, such as MATLAB, should be able to read these files, though you will probably have to specify the number of rows and columns. Personally, I use the free unix-based software GMT, and frequently make use of the Molleweide projection.

SHTOOLS won't compile on my computer.

If the command make all (or make all2) results in compilation errors

  1. Verify that you have the latest release of SHTOOLS.
  2. Go to the SHTOOLS Google group to see if this problem has already been documented.
  3. Send me the output generated by the Makefile, along with information on the operating system and fortran compiler that you are using.

If you are having problems linking an already compiled SHTOOLS library to your code, see the "linking problems" below. If you are instead receiving compilation errors in your code, only contact me after you have thoroughly debugged your program. If you are receiving non fatal warnings, please let me know so that I can clean up the relevant code.

Can I compile SHTOOLS with Fortran 77?

No, you must use a fortran 90/95 compiler. Two free Fortran 90/95 compilers are gfortran (as part of GCC) and g95.

Linking fails because dgels, dstegr or dsytrd are undefined.

Linking your program to the SHTOOLS and LAPACK libraries might result in an error similar to one of the following:

ld: Undefined symbols:
_dgels
../../lib/libSHTOOLS2.0.a(SHExpandLSQ.o) reference to undefined _dgels
link failed.

or

ld: Undefined symbols:
_dstegr
_dsytrd
../../lib/libSHTOOLS2.0.a(EigValSym.o) reference to undefined _dstegr
../../lib/libSHTOOLS2.0.a(EigValSym.o) reference to undefined _dsytrd
../../lib/libSHTOOLS2.0.a(EigValVecSymTri.o) reference to undefined _dstegr
link failed.

If the linker is correctly finding the LAPACK library, the most likely cause of this is that the LAPACK subroutine names in the default SHTOOLS source code are not exactly the same as in the LAPACK library itself. If SHTOOLS is able to link to the FFTW library correctly, try rebuilding SHTOOLS using

make clean
make all2

This will compile an alterative set of source files that explictly appends underscores to the LAPACK subroutine names. These alternative files have "2" appended to their names in the directory src. If you get similar link errors, but with an added underscore, this probably means that the linker can't find the LAPACK libarary. See also How do I know if I need to append underscores to external function and subroutine names?

Linking fails because e_wsfe, z_abs, c_sqrt, s_cmp, etc., are undefined.

Linking your program to the SHTOOLS, LAPACK, BLAS, and FFTW libraries might result in link errors similar to:

/usr/lib///liblapack.so: undefined reference to `e_wsfe'
/usr/lib///liblapack.so: undefined reference to `z_abs'
/usr/lib///liblapack.so: undefined reference to `c_sqrt'
/usr/lib///liblapack.so: undefined reference to `s_cmp'
/usr/lib///liblapack.so: undefined reference to `z_exp'
/usr/lib///liblapack.so: undefined reference to `c_exp'
/usr/lib///liblapack.so: undefined reference to `do_fio'
/usr/lib///liblapack.so: undefined reference to `z_sqrt'
/usr/lib///liblapack.so: undefined reference to `s_cat'
/usr/lib///liblapack.so: undefined reference to `s_stop'
/usr/lib///liblapack.so: undefined reference to `c_abs'
/usr/lib///liblapack.so: undefined reference to `s_wsfe'
/usr/lib///liblapack.so: undefined reference to `s_copy'

This can arise when the offending libraries were built using the g77 compiler. In order to rectify this, it should only be necessary to link to the additional library libg2c.a (i.e., g77 to c). Assuming that this library can be found by the linker, just append -lg2c to the list of libraries passed to the linker. If the g2c libary can not be found by the linker, an easy way to find its location is by using either the "locate" or "find" shell commands

locate libg2c.a
find /usr -name libg2c.a

where the find command searches the directory /usr. This pathname can then be added to the linker's search path by using the option -Ldirname, by, for example,

-L/usr/lib/gcc/i586-mandrake-linux-gnu/3.4.3 -lg2c

The linker can't seem to find either the LAPACK, BLAS, or FFTW libraries.

The linker ld generally searches for libraries in the directories /lib, /usr/lib and /usr/local/lib. When passing -lname to the linker, it will search for the filename libname.a in these directories. Additional directories can be added to the search path by passing one or more -Ldirname to the linker. For instance, to link to the library /Users/Me/Lapack/liblapack.a you would pass the following to the linker

-L/Users/Me/Lapack -llapack

If you do not know the location of a given library, it can be easily found using either the "locate" or "find" shell commands

locate lapack.a
find /usr -name lapack.a

where the find command searches the directory /usr.

Note that the LAPACK and BLAS library names might be somewhat different than assumed in this documentation. For instance, the LAPACK and BLAS libraries might be invoked by passing -llapack3, -lf77BLAS, or -lcblas to the linker. Note that if the library ATLAS is present, it can be substituted for the BLAS library. If you are certain that the library exists, and that the linker is attempting to link to it, then see How do I know if I need to append underscores to external function and subroutine names?

How do I know if I need to append underscores to external function and subroutine names?

When making libraries such as LAPACK and FFTW, some compilers by default add a trailing underscore to external function and subroutine names. If the function and subroutine names in the SHTOOLS source code do not correspond exactly to what is in the external library, the linker will not be able to resolve all of the symbols, and you will receive a link error (see the above examples). Most compilers have options that allows you to "modify" the name of the subroutine and function name by specifying arguments such as "fold external function names to lower case", "do not append trailing underscores to external function names", and so on. For example, the latter case corresponds to -fno-underscoring for the g95 compiler.

If you are certain that you have correctly installed the FFTW, LAPACK and BLAS libraries, and that the linker can indeed find them, then it is quite possible that a linking problem is related to a trailing underscore being present in the external library, but not in the function and subroutine names in SHTOOLS (or vice versa). While one might first try recompiling SHTOOLS with or without underscores being present, it is simple to inspect these libraries to determine whether underscores are indeed needed or not. For instance, on my machine the unix command "display name list"

nm -j /Applications/Absoft/lib/liblapack.a | grep dgels

yields

/Applications/Absoft/lib/liblapack.a(dgels.o):
_dgels_
/Applications/Absoft/lib/liblapack.a(dgelsd.o):
_dgelsd_
/Applications/Absoft/lib/liblapack.a(dgelss.o):
_dgelss_
/Applications/Absoft/lib/liblapack.a(dgelsx.o):
_dgelsx_
/Applications/Absoft/lib/liblapack.a(dgelsy.o):
_dgelsy_

indicating that it is necessary to append trailing underscores to LAPACK subroutine names. However,

nm -j /usr/local/lib/libfftw3.a | grep dfftw_plan_dft_r2c_1d

yields

nm: no name list
_dfftw_plan_dft_r2c_1d

indicating that it is not necessary to append trailing underscores to the FFTW routine names. The discrepancy between the FFTW and LAPACK libraries on my machine makes it somewhat more difficult to link to both simultaneously, and it is for this reason that two different makes are possible: make all and make all2. The first uses source code where the external function names do not contain underscores, whereas the other uses source code where there are trailing underscores appended only to the LAPACK subroutine names. Ideally, I should make a configuration file that will determine which cases are present on an arbitrary machine, but I don't know how to do this yet.

Linking fails because SHTOOLS routines are undefined.

Linking your program to the SHTOOLS library might result in errors such as

TestSHRotate.f95:(.text+0xdb6): undefined reference to `makegrid2d'

The most likely source of this error is that the SHTOOLS library was compiled with a different set of options than used when compiling your program. In particular, it is necessary to use the same compiler options that relate to the naming of external names, such as "fold to lower case" and the appending of underscrores.

I get a "segmentation fault" when running a program that links to the SHTOOLS library.

If the error is related to SHTOOLS, and not your code, then there are a few possible ways to fix this. One possibility is that this problem is related to memory allocation and stack overflows. First, try recompiling your code with the option -s. This will try to allocate dynamic arrays in the dataspace, as opposed to the stack. Second, try increasing the stacksize by typing

limit stacksize unlimited

at the unix prompt. If this works, consider adding this to your default shell initialization file. Finally, try increasing the datasize by typing

limit datasize unlimited

My program crashes when calling SHTOOLS routines.

If your program still crashes after making the above modifications, then try the following:

  1. Read the version history to make certain that you are aware of any recent modifications.
  2. Verify that you have enough memory to perform the calculations. Be aware that some routines dynamically allocate arrays. If you are precomputing the array PLX, consider removing this optional argument.
  3. Verify that the documentation describing the routine is correct by (1) comparing the man pages with the intent and argument ordering in the interface block of the file SHTOOLS.f95, and (2) reading the documentation in the actual source code.
  4. Try recompiling the SHTOOLS library without using optimization, i.e., by removing the fortran flag -O2. If this works, please let me know.
  5. Use a debugger to find out where the error is occurring.
  6. Go to SHTOOLS at Google Groups and see if others are having the same problem.

If this all fails, then let me know which routine is involved, as well as the error message you encounter. Any debugging that is done on your part will help greatly in finding the problem. Be aware that I am not being paid to solve your problems.

How do I specify "optional" parameters in functions and subroutines?

In fortran 95, this can be specified in one of two ways. First, if there is only one possible optional parameter, it is only necessary to include (or exclude) it at the end of the list of arguments. In contrast, if more than one optional parameter is allowed, it is necessary to use the syntax OPTIONALVARIABLENAME=variable at the end of the list of calling arguments. It is strongly suggested that you always directly specify the name of the optional parameter, because it is quite possible that additional optional parameters will be added at a later date.

The LAPACK routine DSTEGR crashes with an arithmetic exception.

The LAPACK rotuine DSTEGR is used to obtain the eigenvalues of a symmetric real tridiagonal matrix. Normal execution of this routine may generate infinities and NANs that are properly treated by ieee-754 floating point standards. If this routine crashes with the message

*** Arithmetic exception: - aborting
Aborted

the LAPACK library was most likely not compiled using full ieee-754 standards. Try recompiling LAPACK with a compiler option such as -ieee=full.

SHExpandGLQ and SHExpandDH are 10 times slower than MakeGridGLQ and MakeGridDH.

The routines SHExpandGLQ and SHExpandDH are the inverse to MakeGridGLQ and MakeGridDH, repsectively. The forward and inverse routines are very symmetric and should, in principle, take the same amount of time to execute. This is indeed the case when using (at least) the Absoft ProFortran and gfortran compilers with optimizations. However, it has been found that the optimizer for the g95 compiler (version 0.91) is not too smart. Even though the forward and inverse routines are very symmetric, one takes about ten times longer to execute than the other. There is probably a way to modify the source code to help the g95 optimizer figure out what to do, but I have so far not been successful in doing this. If you have any suggestions, please let me know.

> Home > Documentation

Centre National de la Recherche Scientifique Institut de Physique du Globe de Paris © 2009 Mark Wieczorek