Working with spherical harmonics


This notebook gives a brief introduction to some of the conventions and functionality for handling spherical harmonics and related functions, using low-level ePSproc routines. Note some higher-level routines are available in the base class.

Expansions in (complex) spherical harmonics

In general, expansions in complex harmonics are used, with expansion parameters \(\beta_{L,M}\). A given function is then written as:

\begin{equation} I(\theta,\phi)=\sum_{l,m}\beta_{l,m}Y_{l,m}(\theta,\phi)\label{eq:sph-harmonics} \end{equation}

For additional control and conversion, the SHtools library can also be used - this includes some useful utility functions including converting between different forms (e.g. real and complex forms), and basic plotters.

For use of real spherical harmonics, see the ‘working with real harmonics notebook’.

Expansions in Legendre polynomials

For cylindrically-symmetric cases (\(m=0\)), general expansions in Legendre polynomials are also sufficient and often used:

\begin{equation} I(\theta)=\sum_{l}\beta_{l}P^0_l(\cos(\theta))\label{eq:lg-expansion} \end{equation}

Where the “Legendre” and “spherical harmonic” expansion parameters for the harmonics defined above can be related by:

\begin{equation} \beta^{Sph}_{l,0} = \sqrt{(2L+1)/4\pi}\beta^{Lg}_{l} \end{equation}

Expansions in symmetrized harmonics

In some case, symmetrized or generalised harmonics are useful. These are defined similarly, but with expansion coeffs additionally set by (point group) symmetry. A basic implementation can be found in the PEMtk package, defined as:

\begin{equation} X_{hl}^{\Gamma\mu*}(\theta,\phi)=\sum_{\lambda}b_{hl\lambda}^{\Gamma\mu}Y_{l,\lambda}(\theta,\phi)\label{eq:symm-harmonics} \end{equation}

Where the \(b_{hl\lambda}^{\Gamma\mu}\) are defined by symmetry. General function expansions can then be written as a set of spherical harmonics including symmetrization, or an equivalent expansion in symmetrized harmonics (here not all indices may be necessary):

\begin{equation} I(\theta,\phi)=\sum_{h,l,\Gamma,\mu}\beta_{hl}^{\Gamma\mu}X_{hl}^{\Gamma\mu*}(\theta,\phi)=\sum_{h,l,\Gamma,\mu}\sum_{\lambda}b_{hl\lambda}^{\Gamma\mu}\beta_{l,\lambda}Y_{l,\lambda}(\theta,\phi)\label{eq:symm-harmonics-2} \end{equation}

Numerical implementation

Various tools are currently implemented in ePSProc (as of Sept. 2022), and are illustrated below. In particular:

  • ep.sphCalc contains the base routines for generation of harmonics.

  • ep.sphPlot implements basic plotting routines.

  • ep.sphFuncs.sphConv implements additional handling and tools, including conversion routines.

The base class implements some more sophisticated plotting options.

The default routines in ePSproc make use of scipy.special.sph_harm as the default calculation routine. Note the \((\theta, \phi)\) definition, and normalisation, corresponding to the usual “physics” convention (\(\theta\) defined from the z-axis, includes the Condon-Shortley phase, and orthonormalised):

\begin{equation} Y_{l,m}(\theta,\phi) = (-1)^m\sqrt{\frac{2l+1}{4\pi} \frac{(l-m)!}{(l+m)!}}e^{i m \phi} P^m_l(\cos(\theta)) \end{equation}

For more details, see also Wikipaedia, which has matching defintions plus further discussion. Note that in the Scipy routines the Condon-Shortley phase term, \((-1)^m\), is actually included in the associated Legendre polynomial function \(P^m_l\), but is written explicitly above.

Conjugates and \(\pm m\) sign swaps are implemented in ep.sphFuncs.sphConv.sphConj as per Blum:

\begin{equation} Y_{l,m} = (-1)^m Y_{l,-m}^* \end{equation}


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.