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 geographic reference (target reference system).

kmaxint

Maximum degree of spherical harmonic expansion with respect to 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).