Return the spectrum of the magnetic field as a function of spherical harmonic degree.

## Usage

array = mag_spectrum(clm, a, r, [potential, normalization, degrees, lmax, convention, unit, base])

## Returns

- array : ndarray, shape (len(degrees))
- 1-D ndarray of the spectrum.

## Parameters

- clm : ndarray, shape (2, lmax + 1, lmax + 1)
- ndarray containing the spherical harmonic coefficients.
- a : float
- The reference radius of the spherical harmonic coefficients.
- r : float
- The radius at which the spectrum is evaluated.
- potential : bool, optional, default = False
- If True, calculate the spectrum of the magnetic potential. Otherwise, calculate the spectrum of the magnetic intensity (default).
- normalization : str, optional, default = ‘schmidt’
- ‘4pi’, ‘ortho’, ‘schmidt’, or ‘unnorm’ for geodesy 4pi normalized, orthonormalized, Schmidt semi-normalized, or unnormalized coefficients, respectively.
- lmax : int, optional, default = len(clm[0,:,0]) - 1.
- Maximum spherical harmonic degree to output.
- degrees : ndarray, optional, default = numpy.arange(lmax+1)
- Array containing the spherical harmonic degrees where the spectrum is computed.
- convention : str, optional, default = ‘power’
- The type of spectrum to return: ‘power’ for power spectrum, ‘energy’ for energy spectrum, and ‘l2norm’ for the l2-norm spectrum.
- unit : str, optional, default = ‘per_l’
- If ‘per_l’, return the total contribution to the spectrum for each spherical harmonic degree l. If ‘per_lm’, return the average contribution to the spectrum for each coefficient at spherical harmonic degree l. If ‘per_dlogl’, return the spectrum per log interval dlog_a(l).
- base : float, optional, default = 10.
- The logarithm base when calculating the ‘per_dlogl’ spectrum.

## Notes

This function returns either the power spectrum, energy spectrum, or l2-norm spectrum of a global magnetic field. Total power is defined as the integral of the function squared over all space, divided by the area the function spans. If the mean of the function is zero, this is equivalent to the variance of the function. The total energy is the integral of the function squared over all space and is 4pi times the total power. The l2-norm is simply the sum of the magnitude of the spherical harmonic coefficients squared. The default behaviour of this function is to return the Lowes-Mauersberger spectrum, which is the total power of the magnetic field strength as a function of spherical harmonic degree (see below).

The magnetic potential and magnetic field are defined respectively by the two equations

U = a**2 \sum_{l, m}^L (a/r)**(l+1) glm Ylm, B = - \Del U.

Here, a is the reference radius of the spherical harmonic coefficients, r is the radius at which the function is evalulated, and L is the maximum spherical harmonic degree of the expansion. If the optional parameter potential is set to True, the spectrum of the magnetic potential will be calculated. Otherwise, the default behavior is to calculate the spectrum of the magnetic field intensity.

The output spectrum can be expresed using one of three units. ‘per_l’ returns the contribution to the total spectrum from all angular orders at degree l. ‘per_lm’ returns the average contribution to the total spectrum from a single coefficient at degree l, and is equal to the ‘per_l’ spectrum divided by (2l+1). ‘per_dlogl’ returns the contribution to the total spectrum from all angular orders over an infinitessimal logarithmic degree band. The contrubution in the band dlog_a(l) is spectrum(l, ‘per_dlogl’)*dlog_a(l), where a is the base, and where spectrum(l, ‘per_dlogl) is equal to spectrum(l, ‘per_l’)*l*log(a).

When no optional parameters are specified, the Lowes-Mauersberger power spectrum is calculated. Explicitly, this corrresponds to convention = ‘power’, unit = ‘per_l’, and potential = False.

Edit me