chaosmagpy.coordinate_utils.sh_analysis

chaosmagpy.coordinate_utils.sh_analysis(func, nmax, kmax=None)[source]

Perform a spherical harmonic expansion of a function defined on a spherical surface.

Parameters:
func: callable

Function takes two inputs: colatitude in degrees and longitude in degrees. The function must accept 2-D arrays and preserve shapes.

nmax: int

Maximum spherical harmonic degree of the expansion.

kmax: int, optional, greater than or equal to nmax

Maximum spherical harmonic degree needed to resolve the output of func. This basically increases the number of points in colatitude, which improves the accuracy of the numerical integration (defaults to nmax). Ignored if kmax < nmax.

Returns:
coeffs: ndarray, shape (nmax*(nmax+2),)

Coefficients of the spherical harmonic expansion.

Examples

First, a straight forward example using the spherical harmonic \(Y_1^1\):

>>> import chaosmagpy as cp
>>> import numpy as np
>>> #
>>> def func(theta, phi):
>>>     n, m = 1, 1
>>>     Pnm = cp.model_utils.legendre_poly(n, theta)
>>>     if m >= 0:
>>>         return np.cos(m*np.radians(phi))*Pnm[n, m]
>>>     else:
>>>         return np.sin(abs(m)*np.radians(phi))*Pnm[n, abs(m)]

>>> cp.coordinate_utils.sh_analysis(func, nmax=1)
    array([0.0000000e+00, 1.0000000e+00, 1.2246468e-16])

Now, an example where the numerical integration is not sufficiently accurate:

>>> def func(theta, phi):
>>>     n, m = 7, 0  # increased degree to n=7
>>>     Pnm = cp.model_utils.legendre_poly(n, theta)
>>>     return Pnm[n, m]

>>> cp.coordinate_utils.sh_analysis(func, nmax=1)
    array([0.55555556, 0.00000000e+00, 0.00000000e+00])  # g10 is wrong

But, by setting kmax=7 and, thus, increasing the number of integration points:

>>> cp.coordinate_utils.sh_analysis(func, nmax=1, kmax=7)
    array([-1.14491749e-16, 0.00000000e+00, -0.00000000e+00])