Repository files navigation

CHarm is a C library to work with spherical harmonics up to almost arbitrarilyhigh 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 sphericalharmonic 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-wisecomputations are done by FFT whenever possible. If FFT cannot be applied,the less efficient Chebyshev recurrences are used along the latitudeparallels 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.
• Implements spectral gravity forward modelling of band-limited topographicmasses with an arbitrary integration radius and 3D density.[1]
• Evaluates integrals of solid spherical harmonic expansions (e.g., of thegravitational potential) on band-limited irregular surfaces (e.g., on theEarth's surface).[1]
• Computes Fourier coefficients of fully-normalized associated Legendrefunctions of the first kind up to ultra-high harmonic degrees.
• Supports SIMD parallelization on the level of a single CPU core (SSE4.1, AVX,AVX2, AVX-512 and NEON).
• SupportsOpenMP parallelization forshared-memory architectures.
• SupportsMPI parallelization for shared- anddistributed-memory architectures.
• Performs discrete FFT byFFTW.
• For spectral gravity forward modelling with spatially limited integrationradius,MPFR is used to enable arbitrary precisionarithmetic on floating point numbers.
• Ships with a Python wrapper to enable high-level programming while retainingthe efficiency of the C language. The wrapper, called PyHarm, wraps CHarmusingctypes and is fullyintegrated withnumpy.

• PyHarm (Python wrapper): On Linux (x86_64), macOS (x86_64, ARM64) andWindows (x86_64), install PyHarm usingpip:

  pip install pyharm

  This will install PyHarm together will all the dependencies. These includea pre-compiled CHarm library, which is internally called by PyHarm, someother 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 buildCHarm from source. This step is not required if you plan to use the Pythoninterface only.

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

• PyHarm (Python wrapper): On Linux (x86_64), macOS (x86_64, ARM64) andWindows (x86_64), install PyHarm usingpip:

  pip install pyharm

  This will install PyHarm together will all the dependencies. These includea pre-compiled CHarm library, which is internally called by PyHarm, someother C libraries (FFTW, MPFR, GMP and OpenMP libraries) and the Pythonpackage NumPy.

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

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

GitHub:https://github.com/blazej-bucha/charm

• Releases are pushed tomaster 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 themaster branch is availableathttps://www.charmlib.org.

A pre-compiled HTML documentation is also available indocs/build/html.Alternatively, it can be built by executingmake html after theconfigure call (requires--enable-python,--enable-mpi,--enable-mpfr,doxygen and Python modulessphinx,sphinx_book_theme andbreathe). Other formats of the documentation,for instance, a PDF file, can be built withcd docs && make latexpdf, etc.To list all available formats, executecd docs && make help.

Should you have any comments, questions, bug report or criticism, please feelfree to contact the author, Blažej Bucha, atblazej.bucha@stuba.sk. Furtherproducts developed by the author can be found athttps://www.blazejbucha.com.

We prefer to pronounce CHarm and PyHarm like the wordssee harm andpieharm. But it is indeed quite charming to pronounce CHarm like the wordcharm, especially when the library works like a charm.

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

• SHTOOLS: Fortran95 library with Python API,
• SHTns: a C library for sphericalharmonic transforms,
• ISPACK: a Fortran library forspherical harmonic transforms,
• Libsharp: a C99 library forspherical harmonic transforms,
• healpy: a Pythonpackage to handle pixelated data on the sphere building on theHEALPix C++ library,
• HARMONIC_SYNTH: a Fortrancode for spherical harmonic synthesis written by the EGM2008 developmentteam.
• SPHEREPACK: a Fortranlibrary of spherical harmonic transforms,
• SHAVEL: a program for thespherical harmonic analysis of a horizontal vector field sampled in anequiangular grid on a sphere
• ICGEM: Online calculation service forworking with Earth and celestial gravitational models,
• FaVeST: Fast Vector SphericalHarmonic Transforms in MATLAB.
• SHBundle:Spherical harmonic analysis and synthesis in MATLAB up to high degrees andorders,
• Spherical Harmonics Manipulator: Spherical harmonicsynthesis in sparse points and grids (no longer maintained),
• GrafLab andisGrafLab: MATLAB-based software packagesfor spherical harmonic synthesis of gravity field functionals up to highdegrees and orders (tens of thousands and well beyond).