SuperFreq

class superfreq.SuperFreq(t, p=1, keep_calm=False)

Bases: object

Implementation of the Numerical Analysis of Fundamental Frequencies method of Laskar, later modified by Valluri and Merritt (see references below), with some slight modifications.

This algorithm attempts to numerically find the fundamental frequencies of an input orbit (time series) and can also find approximate actions for the orbit. The basic idea is to Fourier transform the orbit convolved with a Hanning filter, find the most significant peak, subtract that frequency, and iterate on this until convergence or for a fixed number of terms. The fundamental frequencies can then be solved for by assuming that the frequencies found by the above method are integer combinations of the fundamental frequencies.

For more information, see:

• Laskar, J., Froeschlé, C., and Celletti, A. (1992)
• Laskar, J. (1993)
• Papaphilippou, Y. and Laskar, J. (1996)
• Valluri, M. and Merritt, D. (1998)

Parameters:

t : array_like

Array of times.

p : int (optional)

Coefficient for Hamming filter – default p=1 which is a Hanning filter, used by Laskar and Valluri/Merritt.

keep_calm : bool (optional)

If something fails when solving for the frequency of a given component, keep_calm determines whether to throw a RuntimeError or exit gracefully. If set to True, will exit quietly and carry on to the next component. If False, will die if any frequency determination fails.

Methods Summary

find_fundamental_frequencies(fs[, min_freq, …])	Solve for the fundamental frequencies of each specified time series.
frecoder(f[, nintvec, break_condition])	For a given number of iterations, or until the break condition is met: solve for strongest frequency of the input time series, subtract it from the time series, and iterate.
frequency(f[, omega0, return_fft])	Find the most significant frequency of a (complex) time series, \(f(t)\), by Fourier transforming the function convolved with a Hanning filter and picking the most significant peak.
gso(ecap, omega, k)	Gram-Schmidt orthonormalization of the time series.
hanning_product(u1, u2)	Compute the scalar product of two ‘vectors’, u1 and u2.

Methods Documentation

find_fundamental_frequencies(fs, min_freq=1e-06, min_freq_diff=1e-06, **frecoder_kwargs)

Solve for the fundamental frequencies of each specified time series.

This is most commonly a 2D array, a tuple, or iterable of individual complex time series. For example, if your orbit is 2D, you might pass in a tuple with \(x +i \, v_x\) as the 0th element and \(y +i \, v_y\) as the 1st element.

Any extra keyword arguments are passed to SuperFreq.frecoder().

Parameters:

fs : array_like, iterable

The iterable of (complex) time series. If an array-like object, should be 2D with length along axis=0 equal to the number of time series. See description above.

min_freq : numeric (optional)

The minimum (absolute) frequency value to consider a non-zero frequency component.

min_freq_diff : numeric (optional)

The minimum (absolute) frequency difference to distinguish two frequencies.

**frecoder_kwargs

Any extra keyword arguments are passed to SuperFreq.frecoder().

Returns:

freqs : numpy.ndarray

The fundamental frequencies of the orbit. This will have the same number of elements as the dimensionality of the orbit.

table : numpy.ndarray

The full table of frequency modes, amplitudes, and phases for all components detected in the FFT.

freq_ixes : numpy.ndarray

The indices of the rows of the table that correspond to the modes identified as the fundamental frequencies.

frecoder(f, nintvec=12, break_condition=1e-07)

For a given number of iterations, or until the break condition is met: solve for strongest frequency of the input time series, subtract it from the time series, and iterate.

Parameters:

f : array_like

Complex time-series, e.g., \(x(t) + i \, v_x(t)\).

nintvec : int (optional)

Number of integer vectors to find or number of frequencies to find and subtract.

break_condition : numeric (optional)

Break the iterations of the time series maximum value or amplitude of the subtracted frequency is smaller than this value. Set to None if you want to always iterate for nintvec frequencies.

Returns:

omega : numpy.ndarray

Array of frequencies for each component in the time series.

ampl : numpy.ndarray

Array of real amplitudes for each component in the time series.

phi : numpy.ndarray

Array of phases for the complex amplitudes for each component in the time series.

frequency(f, omega0=None, return_fft=False)

Find the most significant frequency of a (complex) time series, \(f(t)\), by Fourier transforming the function convolved with a Hanning filter and picking the most significant peak. This assumes the time series, f, is aligned with / given at the times specified when constructing this object. An internal function.

Parameters:

f : array_like

Complex time-series, e.g., \(x(t) + i \, v_x(t)\).

omega0 : numeric (optional)

Force finding the peak around the input freuency.

return_fft : bool (optional)

Return the FFT along with the most significant frequency.

Returns:

freq : numeric

The strongest frequency in the specified complex time series, f.

omegas : ndarray

An array of frequencies.

fft : ndarray

The FFT of the input time series f.

gso(ecap, omega, k)

Gram-Schmidt orthonormalization of the time series.

..math:

e_k(t) = \exp (i \omega_k t)

with all previous functions.

Parameters:

ecap : array_like

omega : numeric

Frequency of current component.

k : int

Index of maximum frequency found so far.

Returns:

ei : numpy.ndarray

Orthonormalized time series.

hanning_product(u1, u2)

Compute the scalar product of two ‘vectors’, u1 and u2. The scalar product is defined with the Hanning filter as

\[<u_1, u_2> = \frac{1}{2 T} \int \, u_1(t) \, \chi(t) \, u_2^*(t)\,dt\]

Parameters:

u1 : array_like

u2 : array_like

Returns:

prod : float

Scalar product.