File Exchange

Real/Complex Spherical Harmonic Transform, Gaunt Coefficients and Rotations

version 1.5.0.0 (1.23 MB) by
A small collection of routines for the Spherical Harmonic Transform and Gaunt coefficients.

Updated 26 May 2021

From GitHub

# Spherical Harmonic Transform Library
#### A collection of MATLAB routines for the Spherical Harmonic Transform and related manipulations in the spherical harmonic spectrum.

---
> Archontis Politis, 2015
> Department of Signal Processing and Acoustics, Aalto University, Finland
> archontis.politis@aalto.fi
---

This Matlab/Octave library was developed during my doctoral research in the [Communication Acoustics Research Group] (http://spa.aalto.fi/en/research/research_groups/communication_acoustics/), Aalto University, Finland. If you would like to reference the code, you can refer to my dissertation published [here](https://aaltodoc.aalto.fi/handle/123456789/22499):

Archontis Politis, Microphone array processing for parametric spatial audio techniques, 2016
Doctoral Dissertation, Department of Signal Processing and Acoustics, Aalto University, Finland

## Description

Both real and complex SH are supported. The orthonormalised versions of SH
are used. More specifically, the complex SHs are given by:

Y_{nm}(\theta,\phi) =
(-1)^m \sqrt{\frac{2n+1}{4\pi}\frac{(n-m)!}{(n+m)!}} P_l^m(\cos\theta) e^{im\phi}

and the real ones as in:

R_{nm}(\theta,\phi) =
\sqrt{\frac{2n+1}{4\pi}\frac{(n-|m|)!}{(n+|m|)!}} P_l^{|m|}(\cos\theta) N_m(\phi)

where

N_m(\phi) = \sqrt{2} cos(m\phi}, m>0
N_m(\phi) = 1, m>0
N_m(\phi) = \sqrt{2} sin(|m|\phi}, m<0

Note that the Condon-Shortley phase of (-1)^m is not introduced in the code for
the complex SH since it is included in the definition of the associated
Legendre functions in Matlab (and it is canceled out in the code of the real SH).

The functionality of the library is demonstrated in detail in [http://research.spa.aalto.fi/projects/sht-lib/sht.html]
or in the included script TEST_SCRIPTS_SHT.m.

The SHT transform can be done by:

a) direct summation, for appropriate sampling schemes along with their
integration weights, such as the uniform spherical t-Designs, the Fliege-Maier
sets, Gauss-Legendre quadrature grids, Lebedev grids and others.

b) least-squares, weighted or not, for arbitrary sampling schemes. In this
case weights can be provided externally, or use generic weights based on the
areas of the spherical polygons around each evaluation point determined by
the Voronoi diagram of the points on the unit sphere, using the included
functions.

MAT-files containing t-Designs and Fliege-Maier sets are also included.

McLaren's Improved Snub Cube and Other New Spherical Designs in Three
Dimensions, R. H. Hardin and N. J. A. Sloane, Discrete and Computational
Geometry, 15 (1996), pp. 429-441.

while for the Fliege-Maier sets see [http://www.personal.soton.ac.uk/jf1w07/nodes/nodes.html](http://www.personal.soton.ac.uk/jf1w07/nodes/nodes.html) and

The distribution of points on the sphere and corresponding cubature
formulae, J. Fliege and U. Maier, IMA Journal of Numerical Analysis (1999),
19 (2): 317-334

Some routines in the library evaluate Gaunt coefficients, which express the
integral of the three spherical harmonics. These can be evaluated either
through Clebsch-Gordan coefficients, or from the related Wigner-3j symbols.
Here they are evaluated through the Wigner-3j symbols through the formula
introduced in

Translational addition theorems for spherical vector wave functions,
O. R. Cruzan, Quart. Appl. Math. 20, 33:40 (1962)

which can be also found in [http://mathworld.wolfram.com/Wigner3j-Symbol.html, Eq.17.](http://mathworld.wolfram.com/Wigner3j-Symbol.html)

Finally, a few routines are included that compute coefficients of
rotated functions, either for the simple case of an axisymmetric kernel
rotated to some direction (\theta_0, \phi_0), or the more complex case of
arbitrary functions were full rotation matrices are constructed from Euler
angles. The algorithm used is according to the recursive method of Ivanic and
Ruedenberg, as can be found in

Ivanic, J., Ruedenberg, K. (1996). Rotation Matrices for Real
Spherical Harmonics. Direct Determination by Recursion. The Journal
of Physical Chemistry, 100(15), 6342?6347.

and with the corrections of

Ivanic, J., Ruedenberg, K. (1998). Rotation Matrices for Real
Spherical Harmonics. Direct Determination by Recursion Page: Additions
and Corrections. Journal of Physical Chemistry A, 102(45), 9099?9100.

Rotation matrices for both real and complex SH can be obtained.

For more details on the functions, check their help output in Matlab.
contact archontis.politis@aalto.fi

Cite As

Archontis Politis (2021). Real/Complex Spherical Harmonic Transform, Gaunt Coefficients and Rotations (https://github.com/polarch/Spherical-Harmonic-Transform), GitHub. Retrieved .

Dimitris Sarvanis

pengxin chen

good job, thank you so much!

qiulei chun

Hello, I am a student from China. This toolkit has solved the problem of spherical wave transmission calculation in large numerical aperture.

Mayur Nirmal

Théo Auclair

Zichao Wen

Hello,
just wanted to drop in and leave huge 'thank you', as your work has already helped me a lot and I'm going to base on it even more in near future.

Ines FENNI

Li Zheng

Hi, Archontis,
Very good package. Thanks. I just wand, is there any possible add the Gauss-Legendre quadrature grids to the package as you mentioned at the introduction? Thanks.

Li

Natan

Archontis Politis

@siti

Hi, I am not sure I get the question. Which function are you referring to?

Yes you can compute a suitable order of expansion of a spherical cap using the routines in the library; by approximating it for example incrementally increasing the order and computing the least-squares error till it is below some accuracy threshold that you need.

However, take note that you can approximate spherical caps in a much more compact form with other spherical basis functions that are localised (and they relate to SHs). Search for example spherical slepian functions or for example the work of Simons et al.

siti bahari

hi

I would like to know whether can this function calculate the real degrees n(k)m for given spherical cap?

Archontis Politis

@Laurette

Hi, glad to hear the library was useful on your work. I'm using these operations in the context of acoustical processing (and some graphics) and my published work is on applications. But if you could cite the url that would be great, I think it's quite common nowadays. If on the other hand you don't think it fits the style of your journal, no worries.
May I ask which field you applied these on?

Laurette Tuckerman

Having successfully used this routine, I would like to cite it (and you) in my journal article. Do you have any suggestions for doing so? Should I cite this url or should I cite something else that you have written?

Archontis Politis

@Lionel

Hm, strange I just tried it and it contains all the files of the library. And the list of files on the right is generated straight from the zip file I uploaded... Can you try again?

Lionel

Hi,

Thanks!
LB

Archontis Politis

@Mehdi:

It looks like the website ate my previous post, I was saying that I'm not sure but out of the top of my head in the case that each data point is at different radii, each one should be weighted differently with radial weights from the center, giving an elemnt-wise product of the normal SH matrix and a matric of weights for each data point. So I think that after the product matrix is construted an LS-solution similar to the one in the code for the SH tranform can be computed.

Archontis Politis

@ Mehdi:

About your question, if you meant to make a derivative version of the library and upload it as a separate one, you also have my blessing :-).

Mehdi

Absolutely wonderful SH toolbox! You have saved me a lot of time!

I do have a small question though:

I am using these tools in the context of planetary magnetism, which requires solving a diffusion equation around a sphere.

In essence, I have an input surface potential, and decompose it into its spherical harmonics using your code (Each spherical harmonic is then solved separately).

However, I now want to input satellite data, which measures the potential at different heights: since each spherical harmonic has a different radial rate of decay I need to weigh them before applying the least square method.

Here is the question: you do have a weighted version for the least square fit, but it weighs the data points rather than the spheric harmonics. Did you consider this alternative problem?

If not, may I use your code and modify it to produce a version that addresses this issue?

Again, thank you very much for this!
Mehdi

Mehdi

Archontis Politis

@ Simone Winkler:

Hi, probably you have figured that by now, it should be also in the help description of the leastSquaresSHT.m and weightedLeastSquaresSHT.m. You can convert your cartesian coordinates to spherical ones and omit the radius, then pass the values along with their respective directions. More precisely:

F = [value1; value2; ...]
dirs = [azimuth1 inclination1; azimuth2 inclination2; ...]

where:

[F_N, Y_N] = leastSquaresSHT(N, F, dirs, basisType);

Simone Winkler

Hi Archontis,

thanks for this - the number of SH transforms out there seems to be very limited!

Can you explain what the input data needs to look like? Right now I have a 3D dataset in cartesian coordinates.

Thanks!
Simone

MATLAB Release Compatibility
Created with R2014b
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!