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.
- 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, AVX-512 and NEON 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.
[1] | This routine is unique to CHarm. |
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 GOMP) 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.
GitHub: https://github.com/blazej-bucha/charm
- Releases are pushed to
master
and the development happens indevelop
. - Tarball and zip files of releases: https://github.com/blazej-bucha/charm/releases
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
.
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.
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.
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).