There is a newer version of this record available.

Software Open Access


mrk-w; MMesch; Ilya Oshchepkov; Elliott Sales de Andrade; xoviat; Benda Xu; Stefan Schröder; Akihisa Hattori; Aaryaman Vasishta; Andrew Walker; Katrin Leinweber

Version 4.7 Datasets

The new datasets module allows users to easily download spherical harmonic coefficient datasets and return them as SHCoeffs, SHGravCoeffs or SHMagCoeffs class instances.

To load a dataset, call the relevant method as in these examples:

    hlm = pysh.datasets.Venus.VenusTopo719()  # Venus shape
    clm = pysh.datasets.Earth.EGM2008()  # Earth gravity
    glm = pysh.datasetes.Earth.WDMAM2_800()  # Earth magnetic field
    clm = pysh.datasets.Moon.GRGM1200B()  # Gravity of the Moon
Better IO routines
  • Added the functions (in the module shio) shwrite(),read_dov() write_dov(), read_bshc(), write_bshc() and write_igcem_gfc() to read and write 'shtools', 'dov', 'bshc', and 'icgem' files.
  • Added the function shio.read_igrf() for reading IGRF formatted files, and returning coefficients for a specified year.
  • The SHCoeffs, SHMagCoeffs and SHGravCoeffs methods to_file() and from_file() now accept all file formats.
  • Added support for reading gzip and zip files in shread, SHCoeffs.from_file(), SHGravCoeffs.from_file(), SHMagCoeffs.from_file(), and read_icgem_gfc()
  • Fixed a minor bug where netcdf files would not accept boolean attributes.
Admittance and correlation methods
  • Added the methods admittance(), correlation() and admitcorr() for the classes SHCoeffs, SHGravCoeffs, and SHMagCoeffs to compute the admittance and/or correlation with another function.
  • Added the methods plot_admittance(), plot_correlation() and plot_admitcorr() to easily plot these functions.
Better plotting routines
  • Added the option legend_loc to most plotting routines to allow fine control over where the legend is placed.
  • Minor bug fixes concerning colorbar parameters cb_offset and cb_triangles.
Better treatmentment of uncertainties
  • Added the option to include error coefficients in the class SHCoeffs.
  • Added the boolean option errors to the method to_array() in order to control whether the error coefficients are returned with the function spherical harmonic coefficients.
  • Added the option legend_error to the SHCoeffs, SHMagCoeffs and SHGravCoeffs method plot_spectrum() to provide a customized legend entry for the error spectrum.
New attributes for SHCoeffs, SHGravCoeffs and SHMagCoeffs
  • Added the attribute error_kind to specify the type of errors.
  • Added the attribute units to all grid and coefficient classes.
  • Added the attribute epoch to SHGravCoeffs, SHGravGrid , SHGeoid and SHTensor.
  • Added the attribute year to SHMagCoeffs, SHMagGrid , and SHTensor.
Improved Documentation
  • The web documentation has been broken into two separate components: pyshtools (python) and SHTOOLS (Fortran 95).
  • Reorganized the web documentation for clarity (re-organization of tutorials and guides, creation of a separate page for shtools grid formats, creation of separate pages for datasets, constants, and spherical harmonic coefficient file coeeficients).
  • The python tutorial notebooks are now rendered by the jupyter nbviewer web page. From this viewer, the user can easily download the notebook, or run it in a binder session.
  • Updated the documentation for installing pyshtools using Conda.
Initial support for fpm

Initial experimental support is added for use with fpm: the fortran package manager.

To install as a stand-alone project, it is only necesssary to use the command

fpm build

This will place the necessary .mod and .a files in a subdirectory of build.

To include shtools as a dependency in a project that compiles with fpm, you only need to add the following to the fpm.toml file:

SHTOOLS = {git=""}

In the current state of fpm (which is undergoing active development), it is not possible to link to system wide libraries, such as fftw and lapack, which are required by shtools.

Other changes
  • Add option empty to return an empty gird when initializing an SHgrid withfrom_zeros().
  • Add method from_ellipsoid() to SHGrid to initial a class instance with a triaxial ellipsoid.
  • Added error checks to the pyshtools function YilmIndexVector.
  • Renamed the constant module to constants, and reogranized the constants in a more logical way (i.e., constants.Mars.r instead of constants.Mars.r_mars).
  • Added a gmt xarray accessor for use with pygmt.
  • Fixed a bug in Curve2Mask python wrapper when using extended grids, and fixed a bug in the fortran code when the input file contained points at exactly 0 or 360 degree.
  • pyshtools versioning is now done using versioneer, instead of the homemade system that was in the (which was somewhat complicated and needed to set ISREALESED to True or False). Versioneer gets the version number automatically from git tags.
  • Update fortran 95 source files to be consistent with the documentation and SHTOOLS.f95 interface block. In particular, several variable names of c and sh were renamed to cilm.

Files (36.0 MB)
Name Size
36.0 MB Download
All versions This version
Views 1,84836
Downloads 2532
Data volume 5.9 GB71.9 MB
Unique views 1,60030
Unique downloads 1742


Cite as