Introduction#

CHarm is a C library to work with spherical harmonics up to almost arbitrarily high degrees. The library is accompanied by a Python wrapper called PyHarm.

Features#

  • Supports real-valued fully-normalized surface and solid spherical harmonics (the geodetic norm).

  • Performs FFT-based surface spherical harmonic analysis and solid spherical harmonic synthesis with minimized memory requirements.

  • Stable up to high degrees and orders (tens of thousands and beyond).

  • Available in single, double and quadruple precision.

  • Supports point and mean data values (both analysis and synthesis).

  • Supports synthesis at grids and at scattered points/cells. Grid-wise computations are done by FFT whenever possible. If FFT cannot be applied, the less efficient Chebyshev recurrences are used along the latitude parallels instead.

  • Computes the full first- and second-order gradients at evaluation points (e.g., the gravitational vector and the gravitational tensor).

  • Supports the Gauss–Legendre and Driscoll–Healy quadratures.

  • Integrates solid spherical harmonic expansions (e.g., of the gravitational potential) on band-limited irregular surfaces (e.g., on the Earth’s surface). [1]

  • Computes Fourier coefficients of fully-normalized associated Legendre functions of the first kind up to ultra-high harmonic degrees.

  • Supports OpenMP parallelization for shared-memory architectures.

  • Supports AVX, AVX2 and AVX-512 SIMD CPU instructions to improve the performance.

  • Performs discrete FFT by FFTW.

  • Ships with a Python wrapper to enable high-level programming while retaining the efficiency of the C language. The wrapper, called PyHarm, wraps CHarm using ctypes and is fully integrated with numpy.

Source code#

GitHub: blazej-bucha/charm

  • Releases are pushed to master and the development happens in develop.

  • Tarball and zip files of releases: blazej-bucha/charm

Documentation#

The documentation of the latest version from the master branch is available at https://www.charmlib.org.

A pre-compiled HTML documentation is also available in docs/build/html. Alternatively, it can be built by executing make html after the configure call (requires doxygen and Python modules sphinx, sphinx_book_theme and breathe). Other formats of the documentation, for instance, a PDF file, can be built with cd docs && make latexpdf, etc. To list all available formats, execute cd docs && make help.

Contact#

Should you have any comments, questions, bug report or criticism, please feel free to contact the author, Blažej Bucha, at blazej.bucha@stuba.sk. Further products developed by the author can be found at https://www.blazejbucha.com.

Other spherical-harmonic-based libraries#

Many other libraries for working with spherical harmonics are available, each having its pros and cons. Explore! A few examples are:

  • SHTOOLS: Fortran95 library with Python API,

  • SHTns: a C library for spherical harmonic transforms,

  • ISPACK: a Fortran library for spherical harmonic transforms,

  • Libsharp: a C99 library for spherical harmonic transforms,

  • healpy: a Python package to handle pixelated data on the sphere building on the HEALPix C++ library,

  • HARMONIC_SYNTH: a Fortran code for spherical harmonic synthesis written by the EGM2008 development team.

  • SPHEREPACK: a Fortran library of spherical harmonic transforms,

  • SHAVEL: a program for the spherical harmonic analysis of a horizontal vector field sampled in an equiangular grid on a sphere

  • ICGEM: Online calculation service for working with Earth and celestial gravitational models,

  • FaVeST: Fast Vector Spherical Harmonic Transforms in MATLAB.

  • SHBundle: Spherical harmonic analysis and synthesis in MATLAB up to high degrees and orders,

  • Spherical Harmonics Manipulator: Spherical harmonic synthesis in sparse points and grids (no longer maintained),

  • GrafLab and isGrafLab: MATLAB-based software packages for spherical harmonic synthesis of gravity field functionals up to high degrees and orders (tens of thousands and well beyond).