Harpy

Clean

This module contains the cleaning functionality of harpy.

omc3.harpy.clean.clean(harpy_input, bpm_data, model)

Cleans BPM TbT matrix: removes BPMs not present in the model and based on specified cuts. Also cleans the noise using singular value decomposition.

Parameters:

• harpy_input -- The input object containing the analysis settings.

• bpm_data -- DataFrame of BPM TbT matrix indexed by BPM names.

• model -- model containing BPMs longitudinal locations indexed by BPM names.

Returns:

Clean BPM matrix, its decomposition, bad BPMs summary and estimated BPM resolutions

omc3.harpy.clean.svd_decomposition(matrix, num_singular_values, dominance_limit=None, num_iter=None)

Computes reduced (K largest values) singular value decomposition of a matrix. Requiring K singular values from MxN matrix results in matrices sized: ((M,K) x diag(K) x (K,N))

Parameters:

• matrix -- matrix to be decomposed.

• num_singular_values -- Required number of singular values for reconstruction.

• dominance_limit -- limit on SVD dominance.

• num_iter -- maximal number of iteration to remove elements and renormalise matrices.

Returns:

An indexed DataFrame of U matrix (M,K), the product of S and V^T matrices (diag(K).x(K,N)), and the U matrix mask for cleaned elements.

Constants

Specific constants to be used in harpy, to help with consistency.

Frequency

This module contains the frequency calculations related functionality of harpy.

It provides functions to calculate the frequency spectra of turn-by-turn data. This calculation is done using a combination of SVD decomposition zero_padded fft to speed up the analysis. Also searches for resonances in the calculated spectra.

omc3.harpy.frequency.clean_by_tune(tunes: Series, tune_clean_limit: Number) → Series

Looks for outliers in the tunes pandas Series and returns their indices.

Parameters:

• tunes (pd.Series) -- Pandas series with the tunes per BPM and the BPM names as index.

• tune_clean_limit -- No BPM will find as outlier if its distance to the average is lower than this limit.

omc3.harpy.frequency.estimate_tunes(harpy_input, usvs)

Estimates the tunes from the FFT of decomposed data.

Parameters:

• harpy_input -- Analysis settings.

• usvs -- dictionary per plane of (U and SV^T matrices).

Returns:

list of estimated tunes [x, y, z].

omc3.harpy.frequency.find_resonances(tunes, nturns, plane, spectra, order_resonances)

Finds higher order lines in the spectra.

Parameters:

• tunes -- list of tunes [x, y, z].

• nturns -- length of analysed data.

• plane -- marking the horizontal or vertical plane, X or Y.

• spectra -- frequencies and complex coefficients.

Returns:

A DataFrame.

omc3.harpy.frequency.get_freq_mask(harpy_input, tunes, auto_tol)

Computes mask to get intervals around resonances in frequency domain.

Parameters:

• harpy_input -- A HarpyInput object.

• tunes -- list of tunes [x, y, z].

• auto_tol -- automatically calculated tolerance.

Returns:

Boolean array.

omc3.harpy.frequency.harpy_per_plane(harpy_input, bpm_matrix, usv, tunes, plane)

Calculates the spectra of TbT data, finds the main lines and cleans the BPMs for which the main line hasn’t been found or is too far from its average over BPMs.

Parameters:

• harpy_input -- Analysis settings.

• bpm_matrix -- TbT BPM matrix.

• usv -- U and SV^T matrices decomposed matrices, can be None.

• tunes -- list of tunes [x, y, z].

• plane -- marking the horizontal or vertical plane, X or Y.

Returns:

A tuple of DataFrame (containing the main lines), Spectra, and Bad BPMs summary.

omc3.harpy.frequency.windowed_padded_rfft(harpy_input, matrix, tunes, svd=None)

Calculates the spectra using specified windowing function and zero-padding.

Parameters:

• harpy_input -- A HarpyInput object.

• matrix -- pd.DataFrame of TbT matrix (BPMs x turns).

• tunes -- list of tunes [x, y, z].

• svd -- reduced (U_matrix, np.dot(S_matrix, V_matrix)) of original TbT matrix, defaults to None.

Returns:

Tuple of pd.DataFrames, for frequencies and coefficients.

omc3.harpy.frequency.windowing(length, window='hamming')

Provides specified windowing function of given length.

Currently, the following windowing functions are implemented (sorted by increasing width of main lobe, also decreasing spectral leakage in closest lobes): rectangle, welch, triangle, hann, hamming, nuttal3, and nuttal4.

Parameters:

• length -- length of the window.

• window -- type of the windowing function.

Returns:

Normalised windowing function of specified type and length.

Handler

This module contains high-level functions to manage most functionality of harpy. Tools are provided to handle the cleaning, frequency analysis and resonance search for a single-bunch TbtData.

omc3.harpy.handler.run_per_bunch(tbt_data, harpy_input)

Cleans data, analyses frequencies and searches for resonances.

Parameters:

• tbt_data -- single bunch TbtData.

• harpy_input -- Analysis settings taken from the commandline.

Returns:

Dictionary with a TfsDataFrame per plane.

Kicker

This module contains phase correction functionality of harpy. It provides tools to correct phases of a main spectral line in a case where damped (exponentially decaying) oscillations are analysed.

omc3.harpy.kicker.phase_correction(bpm_data_orig, lin_frame, plane)

Corrects phase of main spectral line assuming exponentially decaying oscillations.

Parameters:

• bpm_data_orig -- matrix of original TbtData.

• lin_frame -- DataFrame in which to correct the results.

• plane -- marking the horizontal or vertical plane, X or Y.

Returns:

A DataFrame with corrected phases.