Repository files navigation

SHTOOLS/pyshtools is a Fortran-95/Python library that can be used for spherical harmonic transforms, multitaper spectral analyses, expansions of gridded data into Slepian basis functions, standard operations on global gravitational and magnetic field data.

• FEATURES
• HOW TO USE
• INSTALLATION
  • pyshtools (for Python)
    • Install usingconda
    • Install usingpip
    • For Developers
  • SHTOOLS (for Fortran 95)
    • Install using thebrew package manager (MacOS, Linux, Windows)
    • Install using themacports package manager (MacOS)
    • Install from source
• CONTRIBUTING
• MAINTAINERS AND CONTRIBUTORS
• LICENSE
• REFERENCES

• Supports all standard normalizations and phase conventions of the spherical harmonic functions.

• Effortless conversion between real and complex harmonics, and between different normalization and phase conventions.

• Use of both regularly sampled geographic grids and grids appropriate for Gauss-Legendre quadrature.

• Spherical harmonic transforms proven to be accurate up to about degree 2800 for the native Fortran 95 backend and beyond using theDUCC0 backend.

• Perform localized multitaper spectral analyses, or expand gridded data in terms of localized Slepian basis functions.

• Support for standard data and file formats, includingxarray andnetcdf.

• Import research-grade gravity, topography, and magnetic field datasets with a single command.

• Creation of publication quality maps usingCartopy andPyGMT.

• Support multithreaded programming using theOpenMP API.

A variety of Python tutorials and guides are available to explain the main library features. To get started, click on the following Python tutorials and run them interactively in Binder:

• Spherical harmonic coefficients and grids
• Localization windows and spectral analysis
• Gravity and magnetic fields
• Plotting maps

SHTOOLS can be invoked in any Fortran 95 or Python program. The core software is written in Fortran 95, and Python wrappers and dedicated classes allow simple access to the fortran-compiled routines. To install it, run these commands below:

conda install -c conda-forge pyshtoolsconda update -c conda-forge pyshtools# to upgrade a pre-existing installation

pip install pyshtoolspip install --upgrade pyshtools# to upgrade a pre-existing installationpip install pyshtools --no-binary pyshtools# build from sourcepip install git+https://github.com/SHTOOLS/SHTOOLS@develop# install the develop branch from source

Install the system level build requirements:

sudo apt-get install build-essential cmake gfortran# Debian, Ubuntu and derivativessudo dnf group install"C Development Tools and Libraries""Development Tools"# Fedora, Centos, RHEL and derivativessudo dnf install cmake gcc-fortran# Fedora, Centos, RHEL and derivativesxcode-select --install# macOS

Then clone the shtools repo, install the other dependencies, and install manually in a conda environment:

git clone https://github.com/SHTOOLS/SHTOOLS.gitcd shtoolsconda create -n your_env_name python=3.xx# create a new conda environment, if desiredconda env update -n your_env_name -f environment.ymlconda activate your_env_name# activate the new conda environmentpip install --no-build-isolation -e.# install into the shtools folder and link to the active python environment

brew install shtools

sudo port install shtools

Clone or download the this repo, and then execute one (or both) of the following commands in theshtools directory:

make fortranmake fortran-mp# for OpenMP Fortran routines

Further installation instructions and options can be found in theweb documentation.

We work on thedevelop branch and only push releases tomaster. Please base all pull requests ondevelop.

For the full list of contributors, see theAUTHORS file.

This project uses the BSD 3-Clause license, as found in theLICENSE file.

• Mark A. Wieczorek and Matthias Meschede (2018). SHTools --- Tools for working with spherical harmonics,Geochemistry, Geophysics, Geosystems, 19, 2574-2592, doi:10.1029/2018GC007529.
• Mark Wieczorek,et al. (2019). SHTOOLS/SHTOOLS. Zenodo, doi:10.5281/zenodo.3457861