The spherical harmonics Ynm(theta, phi) are the angular portion of the
solution to Laplace's equation in spherical coordinates where azimuthal
symmetry is not present.

Caution

Care must be taken in correctly identifying the arguments to this function:
θ is taken as the polar (colatitudinal) coordinate with θ in [0, π], and φ as
the azimuthal (longitudinal) coordinate with φ in [0,2π). This is the convention
used in Physics, and matches the definition used by Mathematica
in the function SpericalHarmonicY, but is opposite to the usual
mathematical conventions.

Some other sources include an additional Condon-Shortley phase term of
(-1)m in the definition of this function: note however that our definition
of the associated Legendre polynomial already includes this term.

This implementation returns zero for m > n

For θ outside [0, π] and φ outside [0, 2π] this implementation follows the
convention used by Mathematica: the function is periodic with period
π in θ and 2π in φ. Please note that this is not the behaviour one would get
from a casual application of the function's definition. Cautious users
should keep θ and φ to the range [0, π] and [0, 2π] respectively.

The following table shows peak errors for various domains of input arguments.
Note that only results for the widest floating point type on the system
are given as narrower types have effectively
zero error. Peak errors are the same for both the real and imaginary
parts, as the error is dominated by calculation of the associated Legendre
polynomials: especially near the roots of the associated Legendre function.

All values are in units of epsilon.

Table 38. Peak Errors In the Sperical Harmonic Functions

Significand Size

Platform and Compiler

Errors in range

0 < l < 20

53

Win32, Visual C++ 8

Peak=2x104 Mean=700

64

SUSE Linux IA32, g++ 4.1

Peak=2900 Mean=100

64

Red Hat Linux IA64, g++ 3.4.4

Peak=2900 Mean=100

113

HPUX IA64, aCC A.06.06

Peak=6700 Mean=230

Note that the worst errors occur when the degree increases, values greater
than ~120 are very unlikely to produce sensible results, especially when
the order is also large. Further the relative errors are likely to grow
arbitrarily large when the function is very close to a root.

These functions are implemented fairly naively using the formulae given
above. Some extra care is taken to prevent roundoff error when converting
from polar coordinates (so for example the 1-x2 term
used by the associated Legendre functions is calculated without roundoff
error using x = cos(theta), and 1-x2 = sin2(theta)).
The limiting factor in the error rates for these functions is the need
to calculate values near the roots of the associated Legendre functions.