Working with real spherical harmonics


This notebook gives a brief introduction to some of the conventions and functionality for handling real spherical harmonics and related functions, using low-level ePSproc routines. For complex spherical harmonics, and more general method notes, see ‘working with complex harmonics’ - note the complex forms are generally used in ePSproc, and general correct handling for cases using real spherical harmonics is not currently implemented/guaranteed.

Note some higher-level routines are available in the base class.


Per the Wikipaedia definitions, the real spherical harmonics can be defined as:

\begin{aligned} Y_{\ell m}&={\begin{cases}{\dfrac {i}{\sqrt {2}}}\left(Y_{\ell }^{m}-(-1)^{m}\,Y_{\ell }^{-m}\right)&{\text{if}}\ m\lt0 \\Y_{\ell }^{0}&{\text{if}}\ m=0 \\{\dfrac {1}{\sqrt {2}}}\left(Y_{\ell }^{-m}+(-1)^{m}\,Y_{\ell }^{m}\right)&{\text{if}}\ m\gt0.\end{cases}} \\&={\begin{cases}{\dfrac {i}{\sqrt {2}}}\left(Y_{\ell }^{-|m|}-(-1)^{m}\,Y_{\ell }^{|m|}\right)&{\text{if}}\ m\lt0 \\Y_{\ell }^{0}&{\text{if}}\ m=0 \\{\dfrac {1}{\sqrt {2}}}\left(Y_{\ell }^{-|m|}+(-1)^{m}\,Y_{\ell }^{|m|}\right)&{\text{if}}\ m\gt0.\end{cases}} \\&={\begin{cases}{\sqrt {2}}\,(-1)^{m}\,\Im [{Y_{\ell }^{|m|}}]&{\text{if}}\ m\lt0 \\Y_{\ell }^{0}&{\text{if}}\ m=0 \\{\sqrt {2}}\,(-1)^{m}\,\Re [{Y_{\ell }^{m}}]&{\text{if}}\ m\gt0.\end{cases}} \end{aligned}

Where \(Y_{\ell m}\) are real harmonics, and \(Y_{\ell }^{m}\) are complex.

And the inverse relations:

\begin{aligned} Y_{\ell }^{m}={\begin{cases}{\dfrac {1}{\sqrt {2}}}\left(Y_{\ell |m|}-iY_{\ell ,-|m|}\right)&{\text{if}}\ m\lt0 \\[4pt]Y_{\ell 0}&{\text{if}}\ m=0 \\[4pt]{\dfrac {(-1)^{m}}{\sqrt {2}}}\left(Y_{\ell |m|}+iY_{\ell ,-|m|}\right)&{\text{if}}\ m\gt0.\end{cases}} \end{aligned}

The real harmonics can also be written explicitly as:

\begin{aligned} Y_{\ell m}={\begin{cases}\left(-1\right)^{m}{\sqrt {2}}{\sqrt {{\dfrac {2\ell +1}{4\pi }}{\dfrac {(\ell -|m|)!}{(\ell +|m|)!}}}}\;P_{\ell }^{|m|}(\cos \theta )\ \sin(|m|\varphi )&{\text{if }}m\lt0 \\[4pt]{\sqrt {\dfrac {2\ell +1}{4\pi }}}\ P_{\ell }^{m}(\cos \theta )&{\text{if }}m=0 \\[4pt]\left(-1\right)^{m}{\sqrt {2}}{\sqrt {{\dfrac {2\ell +1}{4\pi }}{\dfrac {(\ell -m)!}{(\ell +m)!}}}}\;P_{\ell }^{m}(\cos \theta )\ \cos(m\varphi )&{\text{if }}m\gt0\,.\end{cases}} \end{aligned}

For futher information, see wikipeadia or the SHtools introduction to real spherical harmonics.

Numerical implementation

ePSproc currently (Sept. 2022) implements:

  • Generation of real harmonics.

  • Conversion of real harmonic coefficients to complex harmonic coefficients.

General handling for real spherical harmonics is not guaranteed however, although - as per above - they can be defined simply by suitable combinations of complex harmonics. Note that the default routines in ePSproc make use of scipy.special.sph_harm as the default calculation routine, this is implemented with a default \((\theta, \phi)\) definition, and normalisation, corresponding to the usual “physics” convention (\(\theta\) defined from the z-axis, includes the Condon-Shortley phase, and orthonormalised). See ‘working with complex harmonics’ for further discussion; the real harmonics are then defined from the complex forms following the final definition given above, where the Condon-Shortley phase is already included in the \(Y_{\ell }^{|m|}\) terms:

\begin{aligned} Y_{\ell m}&={\begin{cases}{\sqrt {2}}\,\Im [{Y_{\ell }^{|m|}}]&{\text{if}}\ m\lt0 \\Y_{\ell }^{0}&{\text{if}}\ m=0 \\{\sqrt {2}}\,\Re [{Y_{\ell }^{m}}]&{\text{if}}\ m\gt0.\end{cases}} \end{aligned}

(For a basic python routine, see Visualizing the real forms of the spherical harmonics.)


import xarray as xr
import pandas as pd
import numpy as np
import epsproc as ep

# Set compact XR repr
xr.set_options(display_expand_data = False)
OMP: Info #273: omp_set_nested routine deprecated, please use omp_set_max_active_levels instead.
* sparse not found, sparse matrix forms not available.
* natsort not found, some sorting functions not available.
* Hvplot not found, some hvPlotters may not be available. See for package details.
* Setting plotter defaults with epsproc.basicPlotters.setPlotters(). Run directly to modify, or change options in local env.