version 1.5.0.0 (1.23 MB) by
Archontis Politis

A small collection of routines for the Spherical Harmonic Transform and Gaunt coefficients.

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

For more information on t-designs, see [http://neilsloane.com/sphdesigns/](http://neilsloane.com/sphdesigns/) and

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.

For any questions, comments, corrections, or general feedback, please

contact archontis.politis@aalto.fi

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

Created with
R2014b

Compatible with any release

- Signal Processing > Audio Toolbox > Simulation, Tuning, and Visualization >
- Signal Processing > Signal Processing Toolbox > Transforms, Correlation, and Modeling > Transforms > Hilbert and Walsh-Hadamard Transforms >
- MATLAB > Mathematics > Computational Geometry > Elementary Polygons >
- Engineering > Mechanical Engineering > Acoustics, Noise and Vibration >

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

Start Hunting!Create scripts with code, output, and formatted text in a single executable document.

Ali-higo Ebo AdouDimitris Sarvanispengxin chengood job, thank you so much!

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

Mayur NirmalThéo AuclairZichao WenAdam SzwajcowskiHello,

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.

Adam

Ines FENNILi ZhengHi, 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

NatanArchontis 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 baharihi

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 TuckermanHaving 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?

LionelHi,

The download zip does not include anything else than a license file, could you please include the actual scripts?

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:

Oops, that should have been Hadamard (elementwise) product instead of Kronecker...

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

MehdiAbsolutely 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

MehdiArchontis 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 WinklerHi 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