Analysis

Hole in One

hole_in_one is the top-level script of analysis functionality offered in omc3. In most of your use cases, this is the file you will want to call. It handles: - frequency spectra of Turn-by-Turn BPM data, - various lattice optics parameters from frequency spectra, - various lattice optics parameters from Turn-by-Turn BPM data,

A general analysis workflow, from straight out turn-by-turn measurement or simulations files to results, goes as follows:

Analysis Workflow
Turn-by-Turn BPM data	--->	frequency spectra	--->	various lattice optics parameters

The first step above consists in frequency analysis performed by harpy, while the second one is optics analysis performed by measure_optics. Each corresponding stage is represented by a different set of files:

Corresponding Files
SDDS file: .sdds	--->	Tfs files: .lin[xy]	--->	Tfs files: .tfs

To run either of the two or both steps, see options --harpy and --optics.

omc3.hole_in_one.hole_in_one_entrypoint(opt, rest)

Runs frequency analysis and measures lattice optics.

Hole_in_one Kwargs:

• harpy: Runs frequency analysis

  Flags: --harpy Action: store_true

• optics: Measures the lattice optics Flags: --optics Action: store_true

Harpy Kwargs:

• files: TbT files to analyse

  Flags: --files Required: True

• outputdir: Output directory.

  Flags: --outputdir Required: True

• suffix (str): User-defined suffix for the output filenames.

  Flags: --suffix

• to_write: Choose the type of output.

  Flags: --to_write Choices: ('lin', 'spectra', 'full_spectra', 'bpm_summary') Default: ['lin', 'bpm_summary']

• turns (int): Turn index to start and first turn index to be ignored.

  Flags: --turns Default: [0, 50000]

• bunch_ids (int): Bunches to process in multi-bunch file. If not specified, all bunches are processed.

  Flags: --bunch_ids

• unit (str): A unit of TbT BPM orbit data. All cuts and output are in ‘m’.

  Flags: --unit Choices: ('m', 'cm', 'mm', 'um') Default: m

• tbt_datatype (str): Choose datatype from which to import (e.g LHC binary SDDS, numpy npz).

  Flags: --tbt_datatype Default: LHC

--Cleaning--

• clean: If present, the data are first cleaned.

  Flags: --clean Action: store_true

• bad_bpms: Bad BPMs to clean.

  Flags: --bad_bpms

• first_bpm (str): First BPM in the measurement. Used to resynchronise the TbT data with model.

  Flags: --first_bpm

• keep_exact_zeros: If present, will not remove BPMs with exact zeros in TbT data.

  Flags: --keep_exact_zeros Action: store_true

• max_peak (float): Removes BPMs where the maximum orbit > limit.

  Flags: --max_peak Default: 0.02

• model: Model for BPM locations

  Flags: --model

• num_svd_iterations (int): Maximal number of iterations of U matrix elements removal and renormalisation in iterative SVD cleaning of dominant BPMs. This is also equal to maximal number of BPMs removed per SVD mode.

  Flags: --num_svd_iterations Default: 3

• opposite_direction: If present, beam in the opposite direction to model is assumed for resynchronisation of BPMs.

  Flags: --opposite_direction Action: store_true

• peak_to_peak (float): Peak to peak amplitude cut. This removes BPMs, where abs(max(turn values) - min(turn values)) <= threshold.

  Flags: --peak_to_peak Default: 1e-08

• sing_val (int): Keep this amount of largest singular values.

  Flags: --sing_val Default: 12

• svd_dominance_limit (float): Limit for single BPM dominating a mode.

  Flags: --svd_dominance_limit Default: 0.925

• wrong_polarity_bpms: BPMs with swapped polarity in both planes.

  Flags: --wrong_polarity_bpms

--Frequency Analysis--

• autotunes (str): The main tunes are guessed as the strongest line in SV^T matrix frequency spectrum: Synchrotron tune below ~0.03, betatron tunes above ~0.03.

  Flags: --autotunes Choices: ('all', 'transverse')

• is_free_kick: If present, it will perform the free kick phase correction

  Flags: --free_kick Action: store_true

• natdeltas (float): Guess for the offsets of natural tunes from the driven tunes (x, y, z). Disabled when set to 0.

  Flags: --natdeltas

• nattunes (float): Guess for the natural tunes (x, y, z). Disabled when set to 0.

  Flags: --nattunes

• output_bits (int): Number (frequency, complex coefficient) pairs in the output is up to 2 ** output_bits (maximal in case full spectra is output). There is one pair (with maximal amplitude of complex coefficient) per interval of size 2 ** (- output_bits - 1).

  Flags: --output_bits Default: 12

• tolerance (float): Tolerance specifying an interval in frequency domain, where to look for the tunes.

  Flags: --tolerance Default: 0.01

• tune_clean_limit (float): The tune cleaning wont remove BPMs because of measured tune outliers closer to the average tune than this limit.

  Flags: --tune_clean_limit Default: 1e-05

• tunes (float): Guess for the main tunes [x, y, z]. Tunez is disabled when set to 0

  Flags: --tunes

• turn_bits (int): Number (frequency, complex coefficient) pairs in the calculation is 2 ** turn_bits, i.e. the difference between two neighbouring frequencies is 2 ** (- turn_bits - 1).

  Flags: --turn_bits Default: 20

• window (str): Windowing function to be used for frequency analysis.

  Flags: --window Choices: ('rectangle', 'welch', 'triangle', 'hann', 'hamming', 'nuttal3', 'nuttal4') Default: hann

• resonances (int): Maximum magnet order of resonance lines to calculate.

  Flags: --resonances Choices: (2 <= n <= 8) Default: 4

Optics Kwargs:

• files: Files for analysis

  Flags: --files Required: True

• outputdir: Output directory

  Flags: --outputdir Required: True

• calibrationdir (str): Path to calibration files directory.

  Flags: --calibrationdir

• chromatic_beating: Calculate chromatic beatings: W, PHI and coupling

  Flags: --chromatic_beating Action: store_true

• compensation (str): Mode of compensation for the analysis after driven beam excitation.

Flags: -compensation Choices: ("model", "equation", "none") Default: model

• coupling_method (int): Coupling analysis option: disabled, 1 BPM or 2 BPMs method

  Flags: --coupling_method Choices: (0, 1, 2) Default: 2

• coupling_pairing: Pairing mode for 2 BPM coupling method. If 0 is given, omc3 will try to determine the best candidate. If a number n>=1 is given, then some BPMs are skipped and the n-th following BPM downstream is used for the pairing.

  Flags: --coupling_pairing Choices: (0, n>=1) Default: 0.

• nonlinear: Calculate higher order RDTs or CRDT

  Flags: --nonlinear Choices: (rdt, crdt) Default: None

• rdt_magnet_order: Maximum magnet order for RDTs calculation if --nonlinear is given

  Flags: --rdt_magnet_order Choices: (2 <= n <= 8) Default: 4

• only_coupling: Calculate only coupling.

  Flags: --only_coupling Action: store_true

• range_of_bpms (int): Range of BPMs for beta from phase calculation

  Flags: --range_of_bpms Choices: (5, 7, 9, 11, 13, 15) Default: 11

• three_bpm_method: Use 3 BPM method in beta from phase

  Flags: --three_bpm_method Action: store_true

• three_d_excitation: Use 3D kicks to calculate dispersion. Action: store_true

• isolation_forest: If present, remove outlying BPMs with isolation forest.

  Flags: --isolation_forest Action: store_true

• second_order_dispersion: If present, calculate second order dispersion.

  Flags: --second_order_dispersion Action: store_true

• union: If present, the phase advances are calculate for union of BPMs with at least 3 valid measurements, instead of intersection .

  Flags: --union Action: store_true

• analyse_dpp (float): Filter files to analyse by this value (in analysis for tune, phase, rdt and crdt)..

  Flags: --analyse_dpp Default: 0

Accelerator Kwargs:

• accel: Choose the accelerator to use. More details can be found in omc3/model/manager.py

  Flags: --accel Required: True

• model_dir: Model directory, specify if --model option is not used.

  Flags: --model_dir

• For the rest, please see get_parameters() methods in child Accelerator classes, which are declared in omc3/model/accelerators/*.py.

Amplitude Detuning Analysis

Entrypoint for amplitude detuning analysis.

This module provides functionality to run amplitude detuning analysis with additionally getting BBQ data from timber, averaging and filtering this data and subtracting it from the measurement data.

Furthermore, the orthogonal distance regression is utilized to get a linear or quadratic fit from the measurements.

Arguments:

--Required--

• beam (int):

  Which beam to use.

• kick (PathOrStr):

  Location of the kick files (parent folder).

• plane (str):

  Plane of the kicks. ‘X’ or ‘Y’ or ‘XY’.

  choices: ['X', 'Y', 'XY']

--Optional--

• bbq_filtering_method (str):

  Filtering method for the bbq to use. ‘cut’ cuts around a given tune, ‘minmax’ lets you specify the limits and ‘outliers’ uses the outlier filtering from utils.

  choices: ['cut', 'minmax', 'outliers']

  default: outliers

• bbq_in (UnionPathStrInt):

  Fill number of desired data to extract from timber or path to presaved bbq-tfs-file. Use the string ‘kick’ to use the timestamps in the kickfile for timber extraction. Not giving this parameter skips bbq compensation.

• detuning_order (int):

  Order of the detuning as int. Basically just the order of the applied fit.

  default: 1

• fine_cut (float):

  Cut, i.e. tolerance, of the tune (fine cleaning for ‘minmax’ or ‘cut’).

• fine_window (int):

  Length of the moving average window, i.e the number of data points (fine cleaning for ‘minmax’ or ‘cut’).

• label (str):

  Label to identify this run.

• outlier_limit (float):

  Limit, i.e. cut, on outliers (Method ‘outliers’)

  default: 0.0002

• output (PathOrStr):

  Output directory for the modified kickfile and bbq data.

• tune_cut (float):

  Cuts for the tune. For BBQ cleaning (Method ‘cut’).

• tunes (float):

  Tunes for BBQ cleaning (Method ‘cut’).

• tunes_minmax (float):

  Tunes minima and maxima in the order x_min, x_max, y_min, y_max. For BBQ cleaning (Method ‘minmax’).

• window_length (int):

  Length of the moving average window. (# data points)

  default: 20

omc3.amplitude_detuning_analysis.analyse_with_bbq_corrections(opt: DotDict) → Tuple[TfsDataFrame, TfsDataFrame]

Create amplitude detuning analysis with BBQ correction from timber data.

Returns:

The amplitude detuning analysis results as a TfsDataFrame and the BBQ data as a TfsDataFrame.

omc3.amplitude_detuning_analysis.double_action_analysis(kick_df: TfsDataFrame, detuning_order: int = 1, corrected: bool = False) → TfsDataFrame

Performs the full 2D/4D fitting of the data.

omc3.amplitude_detuning_analysis.get_approx_bbq_interval(bbq_df: TfsDataFrame, time_array: Sequence[CERNDatetime], window: int) → Tuple[CERNDatetime, CERNDatetime]

Get approximate start and end times for averaging, based on window length and kick interval.

omc3.amplitude_detuning_analysis.get_kick_and_bbq_df(kick: Path | str, bbq_in: Path | str, beam: int = None, filter_opt: OutlierFilterOpt | Tuple[MinMaxFilterOpt, MinMaxFilterOpt] = None) → Tuple[TfsDataFrame, TfsDataFrame]

Load the input data.

omc3.amplitude_detuning_analysis.single_action_analysis(kick_df: TfsDataFrame, kick_plane: str, detuning_order: int = 1, corrected: bool = False) → TfsDataFrame

Performs the fit one action and tune pane at a time.