{"action":"created","issue":{"url":"https://api.github.com/repos/scipy/scipy/issues/6657","repository_url":"https://api.github.com/repos/scipy/scipy","labels_url":"https://api.github.com/repos/scipy/scipy/issues/6657/labels{/name}","comments_url":"https://api.github.com/repos/scipy/scipy/issues/6657/comments","events_url":"https://api.github.com/repos/scipy/scipy/issues/6657/events","html_url":"https://github.com/scipy/scipy/issues/6657","id":181505183,"number":6657,"title":"Confusing documentation for `scipy.special.sph_harm`","user":{"login":"EmperorDali","id":10357776,"avatar_url":"https://avatars.githubusercontent.com/u/10357776?v=3","gravatar_id":"","url":"https://api.github.com/users/EmperorDali","html_url":"https://github.com/EmperorDali","followers_url":"https://api.github.com/users/EmperorDali/followers","following_url":"https://api.github.com/users/EmperorDali/following{/other_user}","gists_url":"https://api.github.com/users/EmperorDali/gists{/gist_id}","starred_url":"https://api.github.com/users/EmperorDali/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/EmperorDali/subscriptions","organizations_url":"https://api.github.com/users/EmperorDali/orgs","repos_url":"https://api.github.com/users/EmperorDali/repos","events_url":"https://api.github.com/users/EmperorDali/events{/privacy}","received_events_url":"https://api.github.com/users/EmperorDali/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":3,"created_at":"2016-10-06T19:32:20Z","updated_at":"2016-10-06T21:57:42Z","closed_at":null,"body":"The [documentation](http://docs.scipy.org/doc/scipy/reference/generated/scipy.special.sph_harm.html#scipy.special.sph_harm) for `scipy.special.sph_harm` states that this function computes \r\n\r\n> Y_n^m(\\theta,\\phi) = \\sqrt{\\frac{2n+1}{4\\pi}\\frac{(n-m)!}{(n+m)!}} e^{im\\theta}P_n^m(\\cos(\\phi))\r\n\r\nI 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](https://en.wikipedia.org/wiki/Spherical_harmonics#Condon.E2.80.93Shortley_phase) factor.  \r\n\r\nHowever, `scipy` is actually computing the spherical harmonics _with_ CS phase:\r\n\r\n> sph_harm(1,1,0,np.pi/2)\r\n> (-0.3454941494713355+0j)\r\n\r\ncompare this to \r\n\r\n> Y_1^1(\\theta,\\phi) = \\sqrt{\\frac{3}{4\\pi}}e^{i\\theta}(-1)(1-\\cos(\\phi))^2\r\n\r\nwhich is a spherical harmonic _with_ CS phase, [see table here](https://en.wikipedia.org/wiki/Table_of_spherical_harmonics#Spherical_harmonics)\r\n\r\nPresumably 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.\r\n\r\nWe 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. "},"comment":{"url":"https://api.github.com/repos/scipy/scipy/issues/comments/252100529","html_url":"https://github.com/scipy/scipy/issues/6657#issuecomment-252100529","issue_url":"https://api.github.com/repos/scipy/scipy/issues/6657","id":252100529,"user":{"login":"ev-br","id":2133832,"avatar_url":"https://avatars.githubusercontent.com/u/2133832?v=3","gravatar_id":"","url":"https://api.github.com/users/ev-br","html_url":"https://github.com/ev-br","followers_url":"https://api.github.com/users/ev-br/followers","following_url":"https://api.github.com/users/ev-br/following{/other_user}","gists_url":"https://api.github.com/users/ev-br/gists{/gist_id}","starred_url":"https://api.github.com/users/ev-br/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ev-br/subscriptions","organizations_url":"https://api.github.com/users/ev-br/orgs","repos_url":"https://api.github.com/users/ev-br/repos","events_url":"https://api.github.com/users/ev-br/events{/privacy}","received_events_url":"https://api.github.com/users/ev-br/received_events","type":"User","site_admin":false},"created_at":"2016-10-06T21:57:42Z","updated_at":"2016-10-06T21:57:42Z","body":"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."}}
{"actor":{"display_login":"ev-br"}}