chaosmagpy.model_utils.design_gauss

chaosmagpy.model_utils.design_gauss(radius, theta, phi, nmax, *, nmin=None, mmax=None, source=None)[source]

Computes matrices to connect the radial, colatitude and azimuthal field components to the magnetic potential field in terms of spherical harmonic coefficients (Schmidt quasi-normalized).

Parameters
radiusndarray, shape (…)

Array containing the radius in kilometers.

thetandarray, shape (…)

Array containing the colatitude in degrees \([0^\circ,180^\circ]\).

phindarray, shape (…)

Array containing the longitude in degrees.

nmaxint, positive

Maximum degree of the sphercial harmonic expansion.

nminint, positive, optional

Minimum degree of the sphercial harmonic expansion (defaults to 1).

mmaxint, positive, optional

Maximum order of the spherical harmonic expansion (defaults to nmax). For mmax = 0, for example, only the zonal terms are returned.

source{‘internal’, ‘external’}, optional

Magnetic field source (default is an internal source).

Returns
A_radius, A_theta, A_phindarray, shape (…, M)

Matrices for radial, colatitude and azimuthal field components. The second dimension M varies depending on nmax, nmin and mmax.

Warning

The function can also return the design matrix for the field components at the geographic poles, i.e. where theta == 0. or theta == 180.. However, users should be careful when doing this because the vector basis for spherical geocentric coordinates, \({{\mathbf{e}_r, \mathbf{e}_\theta, \mathbf{e}_\phi}}\), depends on longitude, which is not well defined at the poles. That is, at the poles, any value for the longitude maps to the same location in euclidean coordinates but gives a different vector basis in spherical geocentric coordinates. Nonetheless, by choosing a specific value for the longitude at the poles, users can define the vector basis, which then establishes the meaning of the spherical geocentric components. The vector basis for the horizontal components is defined as

\[\begin{split}\mathbf{e}_\theta &= \cos\theta\cos\phi\mathbf{e}_x - \cos\theta\sin\phi\mathbf{e}_y - \sin\theta\mathbf{e}_z\\ \mathbf{e}_\phi &= -\sin\phi\mathbf{e}_x + \cos\phi\mathbf{e}_y\end{split}\]

Hence, at the geographic north pole as given by theta = 0. and phi = 0. (chosen by the user), the returned design matrix A_theta will be for components along the direction \(\mathbf{e}_\theta = \mathbf{e}_x\) and A_phi for components along \(\mathbf{e}_\phi = \mathbf{e}_y\). However, if phi = 180. is chosen, A_theta will be for components along \(\mathbf{e}_\theta = -\mathbf{e}_x\) and A_phi along \(\mathbf{e}_\phi = -\mathbf{e}_y\).