Logical coordinates for spherical harmonic mesh

[kidder]

Proposed changes

Computes the logical coordinates for a spherical harmonic basis

Upgrade instructions

Code review checklist

• The code is documented and the documentation renders correctly. Run
  make doc to generate the documentation locally into BUILD_DIR/docs/html.
  Then open index.html.
• The code follows the stylistic and code quality guidelines listed in the
  code review guide.
• The PR lists upgrade instructions and is labeled bugfix or
  new feature if appropriate.

Further comments

[nilsvu]

Move spherepack to PRIVATE

[kidder]

done

[nilsvu]

Add a comment and a note in the docs that the theta direction is identified by Gauss quadrature and the phi direction is identified by equiangular.

Also add notes that logical coordinates for the spherical harmonic basis will be already in spherical coordinates, not in [-1, 1], presumably because we never need the [-1, 1] coordinates and spherepack works directly with the collocation points in spherical coordinates.

[nilsdeppe]

The basis functions are not defined on -1 to 1. It's only the standard Jacobi polynomials that are defined on this interval. There are basis functions defined on 0, 1, 0, infty, -infty, 0, -infty, infty, 0, pi, etc. It's just that Jacobi polynomials happen to be orthonormal on [-1, 1], that's all. There's nothing generally special about those two numbers. This is just how basis functions work. I have nothing against stating the domain of the basis functions (we should do so for all of them, then!), but we shouldn't add any language implying there's something "weird" because they aren't on -1, 1 and that we magically "hid" the -1, 1 coordinates. That's not what's happening, there are no -1, 1 coordinates for all basis functions.

[nilsvu]

Sounds good, there is a relation to Jacobi polynomials though since we use Legendre-Gauss points in cos(theta). Anyway, just stating the domain of the logical coords seems useful, and stating what collocation points are used for the ylm basis.

[kidder]

I expanded the documentation.

[nilsvu]

Move the computation of the collocation points one level deeper if possible, into Spectral::collocation_points. That way you also get the static caching for free.

[kidder]

While it is possible, I don't think it makes sense to do so. There are currently ten functions that use the macro SPECTRAL_QUANTITY_FOR_MESH and only collocation_points would make sense with Basis::SphericalHarmonic. So since the branching is unique, why bury it and then require error handling for all the other functions? Furthermore collocation_points calls compute_collocation_points_and_weights to get the collcation points, and I don't think there are any useful weights

[nilsdeppe]

https://en.cppreference.com/w/cpp/language/attributes/fallthrough

[kidder]

done