Document that for spherical coordinates theta is going from x to y and phi is going from xy-plane to z

[zsoerenm]

Document that for spherical coordinates theta is going from x to y and phi is going from xy-plane to z.

This definition of phi differs from the mathematically defined phi:
https://en.wikipedia.org/wiki/Spherical_coordinate_system

[andyferris]

So phi is "backwards", more or less?

Is this pretty much universal, or just the convention wikipedia has chosen?

[c42f]

As discussed on the wikipedia page, there's no consensus on the symbols used, with theta and phi swapped in physics and mathematics.

We should choose the most common one if we can, and just document that. (Are we really using a latitude-like angle rather than a polar angle? That seems like a mistake to me!)

[andyferris]

Yes, it might be a mistake.

[zsoerenm]

I think the most common one is the mathematically one. Wolfram Alpha is also using the mathematical definition: http://mathworld.wolfram.com/SphericalCoordinates.html
And it is the same for mathinsight.org: http://mathinsight.org/spherical_coordinates

Unfortunately I can't upload a svg file here. But here you have got a png and a pdf file:

SphericalCoordinates.pdf
That is the current definition in CoordinationTransformation.jl. I'm happy to generate new pictures, if you change the definition.

[Joel-Dahne]

I realize that this issue is quite old but I thought I would something as well. I think it would be beneficial to use one of the versions mentioned in the above linked wikipedia article, instead of the currently used one which is a bit non-standard. If you should use "the mathematics" one or "the physics" one I'm not sure. However I would say that Wikipedia's categorization is not completely accurate, I have encountered "the physics" one several time in a mathematical context. For example The NIST Digital Library uses the physics convention as is seen here.

[c42f]

There's no great solution to this but clearly the current situation is bad.

Here's my suggested way forward:

1. Deprecate the use of Spherical and introduce MathSpherical and ISOSpherical (or perhaps PhysSpherical ? better names?).
2. Remove Spherical entirely after a deprecation cycle.
3. Possibly, at a later date, we could reintroduce const Spherical = ISOSpherical. Though it might be best to avoid the ambiguity entirely by just not doing this.

I'm sure a PR to implement step 1. would be gratefully received :-)

[Kolaru]

Maybe there is no need to change the internal representation of anything (after all, as long as the use is consistent, it doesn't matter what convention one uses to bother). For the (often painful) cases when this matters, I would advise the addition of helper function to get the angles in a unambiguous way, independently of the internal representation. According to mathworld, the naming could be e.g.

azimuth(s::Spherical) = s.θ
latitude(s::Spherical) = s.ϕ
colatitude(s::Spherical) = π - s.ϕ

[c42f]

An excellent point, thank you! Even simpler, I think we should just rename the internal fields to azimuth and colatitute, and be done with it. A getproperty implementation could provide a reasonable deprecation of the previous internal field names as aliases. The only issue is what to do with the constructor. I think we'd need to provide a keyword version during the transition and deprecate the positional args.

Actually I feel like this is a reasonable solution to the fundamental ambiguity in naming in symbols: simply use neither of the standard conventions :-)

In the future, we might consider re-introducing access to the internal fields via θ and ϕ, just documenting very clearly what the convention is.

[protogeezer]

I liked the suggestion to add an ISOSpherical type made last year by c42f - since I needed it for my own work I added it to a local copy of CT. If desired I can make a pull request. I was stymied earlier because the fork I made seems to be lacking the v0.5.1 tag. I'm not sure what I did wrong. Let me know how I can help!

[andyferris]

I just checked; all my physics and maths textbooks use what wikipedia calls the "ISO" standard. I'd suggest we change to that and add a picture to the README. :)

Personally I don't mind breaking changes so long as SemVer reflects this. Really these cooridnate systems were meant to be an "example" and perhaps helpful to people doing undergraduate excercises. But we can work around things with deprecations/name changes if people feel strongly.