Symmetrized harmonics demo


  • Changed coeffs to dict. self.coeffs[formats] now holds coeffs for formats libmsym, SH, DF and XR.

  • Added ePSproc data types interface.

  • Fixed plotXlm() for older versions of pySHtools (tested v4.5, current v4.9).

    • Titles now OK.

    • Colourbars not working in older versions?



Symmetrized (or generalised) harmonics, which essentially provide correctly symmetrized expansions of spherical harmonics (\(Y_{lm}\)) functions for a given irreducible representation, \(\Gamma\), can be defined by linear combinations of spherical harmonics (refs. Altmann1963,Altmann1965,Chandra1987 as below):

\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}


  • \(\Gamma\) is an irreducible representation,

  • (\(l\), \(\lambda\)) define the usual spherical harmonic indicies (rank, order)

  • \(b_{hl\lambda}^{\Gamma\mu}\) are symmetrization coefficients,

  • index \(\mu\) allows for indexing of degenerate components,

  • \(h\) indexs cases where multiple components are required with all other quantum numbers identical.

    The exact form of these coefficients will depend on the point-group of the system, see, e.g. refs. (Chandra1987,Reid1994).

Refs for symmetrized harmonics:

  • Altmann, S. and Cracknell, A. (1965) ‘Lattice harmonics I. Cubic groups’, Reviews of Modern Physics, 37(1), pp. 19– 32.

  • Altmann, S.L. and Bradley, C.J. (1963) ‘On the Symmetries of Spherical Harmonics’, Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences, 255(1054), pp. 199–215. doi:10.1098/rsta.1963.0002.

  • Chandra, N. (1987) ‘Photoelectron spectroscopic studies of polyatomic molecules. I. Theory’, Journal of Physics B: Atomic and Molecular Physics, 20(14), pp. 3405–3415. doi:10.1088/0022-3700/20/14/013.

  • Reid, K.L. and Powis, I. (1994) ‘Symmetry considerations in molecular photoionization: Fixed molecule photoelectron angular distributions in C3v molecules as observed in photoelectron–photoion coincidence experiments’, The Journal of Chemical Physics, 100(2), p. 1066. doi:10.1063/1.466638.

Numerical methods

  • Point-groups, character table generation and symmetrization (computing \(b_{hl\lambda}^{\Gamma\mu}\) parameters) is handled by libmsym (based on, see also (Johansson2017) for methodology.

  • Spherical harmonic expansions and conversions (real, imaginary, normalization etc.) and basic ploting (2D maps) are handled by pySHtools. Full definitions for the spherical harmonic types and normalisations available can be found at

  • TODO: Interface to PEMtk/ePSproc for other plotters and handling routines. Currently minimally implemented by output to BLM Xarray.

Modern computational refs:

  • Boiko, D.L., Féron, P. and Besnard, P. (2006) ‘Simple method to obtain symmetry harmonics of point groups’, The Journal of Chemical Physics, 125(9), p. 094104. doi:10.1063/1.2338040.

  • Johansson, M. and Veryazov, V. (2017) ‘Automatic procedure for generating symmetry adapted wavefunctions’, Journal of Cheminformatics, 9(1), p. 8. doi:10.1186/s13321-017-0193-3. (Manuscript for libmsym library.)

Installation notes


The routines here require libmsym, which requires a local build and install: see

If installed to the standard location (/usr/local/lib/) this may just work, but if python gives import errors OSError: cannot open shared object file: No such file or directory then try additionally running sudo ldconfig /usr/local/lib/ at the command line.

Routines have been tested with libmsym v0.2.2, March 2022 (last commit


Can be installed via Conda conda install -c conda-forge pyshtools or pip pip install pyshtools, see

Routines have been tested with v4.5 and 4.9 (current March 2022).


from pemtk.sym.symHarm import symHarm