Confusing documentation for scipy.special.sph_harm

[EmperorDali]

The documentation for scipy.special.sph_harm states that this function computes

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

I am not an expert in spherical harmonics, but to my eyes this notation imples that scipy is computing spherical harmonics without the Condon-Shortley phase factor.

However, scipy is actually computing the spherical harmonics with CS phase:

sph_harm(1,1,0,np.pi/2)
(-0.3454941494713355+0j)

compare this to

Y_1^1(\theta,\phi) = \sqrt{\frac{3}{4\pi}}e^{i\theta}(-1)(1-\cos(\phi))^2

which is a spherical harmonic with CS phase, see table here

Presumably this is because scipy includes the CS phase factor with the associated Legendre function scipy.special.lpmv. I believe this is another convention that is used, however the documentation for scipy.special.lpmv doesn't state what exactly is being computed.

We should 1) update the documentation for lpmv to indicate that the function computes the associated Legendre polynomials with CS phase 2) add a note to the documentation for sph_harm indicating that the function returns spherical harmonics with CS phase.

[larsoner]

Sounds good to me. We should also 3) add tests for this to be sure, via manual evaluation of the equation and/or cross-checking with other packages. Do you have time to make a PR?

[person142]

Hey @EmperorDali note that the wiki page defines

Y_1^1(theta, phi) = stuff*exp(i*phi)*sin(theta)

whereas SciPy defines

Y_1^1(theta, phi) = stuff*exp(i*theta)*sin(phi).

If I flip the arguments in your example I get

>>> sph_harm(1, 1, np.pi/2, 0)
(-0+0j)

which matches the wiki expression. So I think everything defined correctly in the documentation.

[larsoner]

Oh great, the multiple definitions of spherical harmonics strike again...

[ev-br]

Given the amount of confusion this generates over the years, it'd probably be good to add an explicit form of the low-order harmonics (m=1, l=-1, 0, 1) and mention the Condon-Schockley phase.

[person142]

And while someone was working on that, they could also add a full definition of lpmv and mention the Condon-Shortley phase (or lack thereof) there too.

[EmperorDali]

@person142 I don't agree with what you wrote. Note that when I copied Y_1^1 from the table to my first post I interchanged \theta and \phi, to match scipy's convention.

If you look at my post, you'll see I did stuff*exp(i*theta)*sin(phi), both in scipy code and in direct computation by Y_1^1

[person142]

Ah, I worked directly from the wiki page and missed that. Apologies.

The function lpmv is in specfun, so I cracked open Zhang and Jin who indeed define

P_v^m(x) = (-1)^m (1 - x^2)^{m/2} (d^m/dx^m) P_v(x).

[person142]

The refguide for the Legendre functions could also use some improvements:

https://scipy.github.io/devdocs/special.html#legendre-functions

In particular it's difficult to figure out the differences between the functions at a glance. Also, given the names of the functions (consider lpmv and lpmn, neither of which are very descriptive) I'd say that adding some aliases would be a good idea.

Edit: aliases are a bit OT for this issue though; just something to think about.

[larsoner]

Yes it could be cleaned up a bit. I'll see if I can find some time to do it.