chaosmagpy.coordinate_utils.rotate_gauss_fft

chaosmagpy.coordinate_utils.rotate_gauss_fft(nmax, kmax, *, qfunc=None, step=None, N=None, filter=None, save_to=None, reference=None, scaled=None, start_date=None)

Compute Fourier coefficients of the timeseries of matrices that transform spherical harmonic expansions (degree kmax) from a time-dependent reference system (GSM, SM) to GEO (degree nmax).

Parameters:

nmaxint

Maximum degree of spherical harmonic expansion with respect to the geographic reference frame (GEO).

kmaxint

Maximum degree of spherical harmonic expansion with respect to the rotated reference system.

qfunccallable

Callable q = qfunc(freq, k) that returns the complex q-response q (ndarray, shape (N,)) given a frequency vector freq (ndarray, shape (N,)) in (1/sec) and the index k (int) counting the Gauss coefficients in natural order, i.e. k = 0 is \(g_1^0\), k = 1 is \(g_1^1\), k = 2 is \(h_1^1\) and so on.

stepfloat

Sample spacing given in hours (default is 1.0 hour).

Nint, optional

Number of samples for which to evaluate the FFT (default is N = 8*365.25*24 equiv. to 8 years using default sample spacing).

filterint, optional

Set filter length, i.e. number of Fourier coefficients to be saved (default is int(N/2+1)).

save_tostr, optional

Path and file name to store output in npz-format. Defaults to False, i.e. no file is written.

reference{‘gsm’, ‘sm’}, optional

Time-dependent reference system (default is GSM).

scaledbool, optional (default is False)

If True, the function returns scaled Fourier coefficients, i.e. the non-bias terms (all non-zero frequency terms) are multiplied by a factor of 2. Hence, taking the real part of the first half of the spectrum multiplied with the complex exponentials results in the correctly scaled and time-shifted real-valued harmonics.

start_datefloat, optional (defaults to 0.0, i.e. Jan 1, 2000)

Time point from which to compute the time series of coefficient matrices in modified Julian date.

Returns:

frequency, spectrum, frequency_ind, spectrum_indndarray, shape (filter, nmax (nmax + 2), kmax (kmax + 2))

Unsorted vector of positive frequencies in 1/days and complex fourier spectrum of rotation matrices to transform spherical harmonic expansions.

Notes

If save_to=<filepath>, then an *.npz-file is written with the keywords {‘frequency’, ‘spectrum’, ‘frequency_ind’, ‘spectrum_ind’, …} and all the possible keywords. Among them, 'dipole' means the three spherical harmonic coefficients of the dipole set in basicConfig['params.dipole'].

About the discrete Fourier transform (DFT) used here:

A discrete periodic signal \(x[n]\) with \(n\in [0, N-1]\) (period of N) is represented in terms of complex-exponentials as

\[x[n] = \sum_{k=0}^{N-1}X[k]w_N^{kn}, \qquad w_N = \exp(i 2\pi/N)\]

Here, \(X[k]\), \(k\in [0, N-1]\) is the Fourier transform of \(x[n]\). The DFT is defined as:

\[X[k] = \frac{1}{N}\sum_{n=0}^{N-1}x[n]w_N^{-kn}\]

In numpy, this operation is implemented with

import numpy as np

X = np.fft.fft(x) / N

Finally, if save_to is given, only half of the Fourier coefficients X[0:int(N/2)+1] (right-exclusive) are saved (or less if filter is specified).