Introduction

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 SIMD parallelization on the level of a single CPU core (AVX, AVX2, AVX-512 and NEON).

  • Supports OpenMP parallelization for shared-memory architectures.

  • Supports MPI parallelization for shared- and distributed-memory architectures.

  • 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.

Installation#

  • PyHarm (Python wrapper): On Linux (x86_64), macOS (x86_64, ARM64) and Windows (x86_64), install PyHarm using pip:

    pip install pyharm

    This will install PyHarm together will all the dependencies. These include a pre-compiled CHarm library, which is internally called by PyHarm, some other C libraries (FFTW and OpenMP library) and the Python package NumPy.

  • CHarm (C library): If you are interested in the C API, you have to build CHarm from source. This step is not required if you plan to use the Python interface only.

Further installation details at https://www.charmlib.org/build/html/install.html.

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 --enable-python, --enable-mpi, 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.

Pronunciation#

We prefer to pronounce CHarm and PyHarm like the words see harm and pie harm. But it is indeed quite charming to pronounce CHarm like the word charm, especially when the library works like a charm.

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).