Tune Analysis

Constants

Specific constants and helpers to be used in tune_analysis, to help with consistency.

class omc3.tune_analysis.constants.AmpDetData(tune_plane: str, action_plane: str, action: pandas.core.series.Series, action_err: pandas.core.series.Series, tune: pandas.core.series.Series, tune_err: pandas.core.series.Series)

class omc3.tune_analysis.constants.FakeOdrOutput(beta: Sequence[float], sd_beta: Sequence[float])

omc3.tune_analysis.constants.get_action_col(plane: str) → str

Label for the action column.

omc3.tune_analysis.constants.get_action_err_col(plane: str) → str

Label for the action error column.

omc3.tune_analysis.constants.get_action_label(plane: str, unit: str) → str

Action label for the action/tune plots.

omc3.tune_analysis.constants.get_bbq_col(plane: str) → str

Label for the BBQ column

omc3.tune_analysis.constants.get_corr_natq_err_col(plane: str) → str

Return the standard deviation for the corrected natural tune.

omc3.tune_analysis.constants.get_detuning_exponent_for_order(order: int) → int

Returns the default exponent for detuning orders. Highly Empirical.

omc3.tune_analysis.constants.get_fine_cut_header() → str

Header to store the fine cut.

omc3.tune_analysis.constants.get_fine_window_header() → str

Header to store the moving average fine window length

omc3.tune_analysis.constants.get_mav_col(plane: str) → str

Label for the moving average BBQ column.

omc3.tune_analysis.constants.get_mav_err_col(plane: str) → str

Label for the standard deviation of the moving average data.

omc3.tune_analysis.constants.get_mav_window_header() → str

Header to store the moving average window length

omc3.tune_analysis.constants.get_max_tune_header(plane: str) → str

Header to store the maximum tune cut.

omc3.tune_analysis.constants.get_min_tune_header(plane: str) → str

Header to store the minimum tune cut.

omc3.tune_analysis.constants.get_natq_col(plane: str) → str

Label for the natural tune column.

omc3.tune_analysis.constants.get_natq_corr_col(plane: str) → str

Label for the corrected natural tune column.

omc3.tune_analysis.constants.get_natq_err_col(plane: str) → str

Label for the natural tune error column.

omc3.tune_analysis.constants.get_odr_header_coeff(q_plane: str, j_plane: str, order: int) → str

Header key for odr coefficient for term of given order (i.e. beta[order])

omc3.tune_analysis.constants.get_odr_header_coeff_corrected(q_plane: str, j_plane: str, order: int) → str

Header key for corrected odr coefficient for term of given order (i.e. beta[order])

omc3.tune_analysis.constants.get_odr_header_err_coeff(q_plane: str, j_plane: str, order: int) → str

Header key for odr coefficient standard deviation for term of given order (i.e. sd_beta[order])

omc3.tune_analysis.constants.get_odr_header_err_coeff_corrected(q_plane: str, j_plane: str, order: int) → str

Header key for corrected odr coefficient standard deviation for term of given order (i.e. sd_beta[order])

omc3.tune_analysis.constants.get_outlier_limit_header() → str

Header to store the outlier limit.

omc3.tune_analysis.constants.get_tend_head() → str

Label for fill end time from header.

omc3.tune_analysis.constants.get_timber_bbq_key(plane: str, beam: int) → str

Key to extract bbq from timber.

omc3.tune_analysis.constants.get_time_col() → str

Label for the TIME column.

omc3.tune_analysis.constants.get_tstart_head() → str

Label for fill start time from header.

omc3.tune_analysis.constants.get_tune_label(plane: str, scale: int = None) → str

Tune label for the action/tune plots.

omc3.tune_analysis.constants.get_used_in_mav_col(plane: str) → str

Label for the column showing if BBQ value was used in moving average.

BBQ Tools

Tools to handle BBQ data.

class omc3.tune_analysis.bbq_tools.MinMaxFilterOpt(window: int, min: float = None, max: float = None, fine_window: int = None, fine_cut: float = None)

Options for moving average with min/max filter.

Parameters:

• window -- length of the averaging window.

• min -- minimum value (for filtering).

• max -- maximum value (for filtering).

• fine_window -- length of the averaging window for fine cleaning.

• fine_cut -- allowed deviation for fine cleaning.

class omc3.tune_analysis.bbq_tools.OutlierFilterOpt(window: int, limit: float = 0.0)

Options for moving average with outlier filter.

Parameters:

• window -- length of the averaging window.

• limit -- cleaning limit, i.e. points with deviating less than this limit from the average will not be cleaned

omc3.tune_analysis.bbq_tools.clean_outliers_moving_average(data_series: Series, filter_opt: OutlierFilterOpt) → Tuple[Series, Series, ndarray[Any, dtype[bool]]]

Get a moving average of the data_series over length entries, by means of outlier filter. The values are shifted, so that the averaged value takes ceil((length-1)/2) values previous and floor((length-1)/2) following values into account.

Parameters:

• data_series -- Series of data.

• filter_opt -- Options for the filtering, see omc3.tune_analysis.bbq_tools.OutlierFilterOpt.

omc3.tune_analysis.bbq_tools.get_moving_average(data_series: Series, filter_opt: MinMaxFilterOpt) → Tuple[Series, Series, Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]]

Get a moving average of the data_series over length entries. The data can be filtered beforehand. The values are shifted, so that the averaged value takes ceil((length-1)/2) values previous and floor((length-1)/2) following values into account.

Parameters:

• data_series -- Series of data.

• filter_opt -- Options for the filtering, see :class:`omc3.tune_analysis.bbq_tools.MinMaxFilterOpt.

Returns:

A filtered and averaged Series, another Series with the error and the mask used for filtering data.

Fitting Tools

This module contains fitting functionality for tune_analysis. It provides tools for fitting functions, mainly via odr.

omc3.tune_analysis.fitting_tools.do_2d_kicks_odr(x: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], y: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], xerr: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], yerr: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])

Returns the odr fit.

Parameters:

• x -- Array of x data (2xN).

• y -- Array of y data (2xN).

• xerr -- Array of x data errors (2xN).

• yerr -- Array of y data errors (2xN).

Returns: Dict[str, Dict[str: odr_fit]] of Odr fits, where the inner

string gives the kick-plane, the outer the tune-plane..

omc3.tune_analysis.fitting_tools.do_odr(x: Series, y: Series, xerr: Series, yerr: Series, order: int)

Returns the odr fit.

Important Convention: The beta-parameter in the ODR models go upwards with order, i.e.

beta[0] = y-Axis offset

beta[1] = slope

beta[2] = quadratic term

etc.

Parameters:

• x -- Series of x data.

• y -- Series of y data.

• xerr -- Series of x data errors.

• yerr -- Series of y data errors.

• order -- fit order, 1 for linear, 2 for quadratic.

Returns: Odr fit. Betas order is index = coefficient of same order.

omc3.tune_analysis.fitting_tools.first_order_detuning_2d(beta: Sequence, x: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Calculates the 2D tune array (Qx, Qy)

Qx = qx0 + dqx/dex * ex + dqx/dey * ey Qy = qy0 + dqy/dex * ex + dqy/dey * ey

Parameters:

• beta -- length 5 tune coefficients in order INPUT_ORDER 0: qx0, 1: qy0, 2: xx, 3: yy, 4: xy/yx

• x -- array size 2xN, [[ex1, ex2, …],[ey1, ey2,…]]

Returns:

2xN [[Qx1, Qx2, …],[Qy1, Qy2, …]]

Return type:

np.array

omc3.tune_analysis.fitting_tools.first_order_detuning_2d_jacobian(beta: Sequence, x: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Jacobian of the 2D tune array:

[[dqx/dex, dqx/dey ],

[dqy/dex, dqy/dey ]]

Parameters:

• beta -- length 5 tune coefficients in order INPUT_ORDER 0: qx0, 1: qy0, 2: xx, 3: yy, 4: xy/yx

• x -- length 2 Sequence, (ex, ey)

Returns:

size 2x2xlen(x) containing the Jacobian of the 2d-fit function.

Return type:

np.array

omc3.tune_analysis.fitting_tools.get_poly_fun(order: int)

Returns the function of polynomial order. (is this pythonic enough?).

omc3.tune_analysis.fitting_tools.map_odr_fit_to_planes(odr_fit) → Dict[str, Dict[str, FakeOdrOutput]]

Maps the calculated odr fit to fake odr fits with beta and sd_beta attributes. These would be the results of first-order amplitude detuning odr-fits when done independently by tune and kick plane.

Returns: Dict[str, Dict[str: odr_fit]] of ODR fits, where the inner

string gives the kick-plane, the outer the tune-plane..

Kick File Modifiers

Functions to add data to or extract data from kick_ac files.

omc3.tune_analysis.kick_file_modifiers.add_bbq_data(kick_df: DataFrame, bbq_df: DataFrame, column: str, bbq_column: str = None)

Add BBQ values from column to kickac dataframe into same column.

Parameters:

• kick_df -- kick DataFrame, which needs to have time as index, best load it with read_timed_dataframe().

• bbq_df -- DataFrame of bbq data with time as index.

• column -- column name to add the data into.

• bbq_column -- column name to get the data from (same as column if not given).

Returns:

Modified kick Dataframe.

omc3.tune_analysis.kick_file_modifiers.add_corrected_natural_tunes(kickac_df: DataFrame) → DataFrame

Adds the corrected natural tunes to kickac_df. Add also the total standard deviation of the natural tune to the kickac dataframe. The total standard deviation is here defined as the standard deviation of the measurement plus the standard deviation of the moving average.

Parameters:

kickac_df -- Dataframe containing the data.

Returns:

Modified kick_ac.

omc3.tune_analysis.kick_file_modifiers.add_moving_average(kickac_df: TfsDataFrame, bbq_df: TfsDataFrame, filter_opt: OutlierFilterOpt | Tuple[MinMaxFilterOpt, MinMaxFilterOpt]) → Tuple[TfsDataFrame, TfsDataFrame]

Adds the moving average of the bbq data to kickac_df and bbq_df.

omc3.tune_analysis.kick_file_modifiers.add_odr(kickac_df: DataFrame, odr_fit: Output, action_plane: str, tune_plane: str, corrected: bool = False)

Adds the odr fit of the (un)corrected data to the header of the kickac_df.

Parameters:

• kickac_df -- Dataframe containing the data.

• odr_fit -- odr-fit data (definitions see detuning_tools.py).

• action_plane -- Plane of the action.

• tune_plane -- Plane of the tune.

• corrected -- (BBQ) corrected data or uncorrected fit?.

Returns:

Modified kick_ac.

omc3.tune_analysis.kick_file_modifiers.convert_bbs_kickdataframe(df: TfsDataFrame) → TfsDataFrame

Converts a kick-dataframe created with the python2 amplitude detuning analysis into a dataframe compatible with omc3’s detuning analysis. Beware that the old files may not contain the error coefficients for the corrected data in the header (the uncorrected errors are used here), as well as no corrected natural tune error columns. And that the offset (coeffient 0) has no error, which is here assumed to be zero (it is not used anyway, but required when reading the data). The action unit is converted from um to m. !!! Be also aware, that due to a bug the Action and Tune planes might be switched !!! This is not taken into account here.

omc3.tune_analysis.kick_file_modifiers.convert_bbs_kickfile(file: Path)

Wrapper for omc3.tune_analysis.kick_file_modifiers.convert_old_kickdataframe() with read/write capabilities.

omc3.tune_analysis.kick_file_modifiers.get_ampdet_data(kickac_df: DataFrame, action_plane: str, tune_plane: str, corrected: bool = False, dropna: bool = True) → AmpDetData

Extract the data needed for the (un)corrected amplitude detuning from kickac_df.

Parameters:

• kickac_df (DataFrame) -- Containing the data (either kick_x, kick_y from optics or kick_ampdet_xy from ampdet analysis)..

• action_plane (str) -- Plane of the action.

• tune_plane (str) -- Plane of the tune.

• corrected (bool) -- if the BBQ-corrected columns should be taken

• dropna (bool) -- drop columns containing NaNs

Returns:

Dataframe containing action, tune, action_err and tune_err columns.

omc3.tune_analysis.kick_file_modifiers.get_odr_data(kickac_df: DataFrame, action_plane: str, tune_plane: str, order: int, corrected: bool = False) → FakeOdrOutput

Extract the data from kickac.

Parameters:

• kickac_df -- Dataframe containing the data.

• action_plane -- Plane of the action.

• tune_plane -- Plane of the tune.

• order -- Order of the odr fit.

• corrected -- (BBQ) corrected data or uncorrected fit?

Returns:

Dictionary containing fit data from odr.

Timber Extraction

Tools to extract data from Timber. It is a bit heavy on the LHC side at the moment.

Please note: this module requires the pytimber package to access Timber functionality, both of which are only possible from inside the CERN network.

To install pytimber along omc3, please do so from inside the CERN network by using the [cern] extra dependency and installing from the acc-py package index (by specifying --index-url https://acc-py-repo.cern.ch/repository/vr-py-releases/simple and --trusted-host acc-py-repo.cern.ch to your pip installation command).

omc3.tune_analysis.timber_extract.extract_between_times(t_start: AcceptableTimeStamp, t_end: AcceptableTimeStamp, keys: Sequence[str] = None, names: Dict[str, str] = None) → TfsDataFrame

Extracts data for keys between t_start and t_end from Timber.

Parameters:

• t_start (AcceptableTimeStamp) -- starting time in CERNDateTime or timestamp.

• t_end (AcceptableTimeStamp) -- end time in local CERNDateTime or timestamp.

• keys (Sequence[str]) -- the different variables names to extract data for.

• names (Dict[str, str) -- dict mapping keys to column names.

Returns:

Extracted data in a TfsDataFrame.

omc3.tune_analysis.timber_extract.get_fill_times(db, fill_number: int) → Tuple[datetime | float, datetime | float]

Returns start and end time of fill with fill number.

Parameters:

• db (pytimber.LoggingDB) -- pytimber database.

• fill_number (int) -- fill number.

Returns:

Tuple of start and end time.

omc3.tune_analysis.timber_extract.get_tune_and_coupling_variables(db) → List[str]

Returns the tune and coupling variable names.

Parameters:

db (pytimber.LoggingDB) -- pytimber database connexion.

Returns:

List of variable names as strings.

omc3.tune_analysis.timber_extract.lhc_fill_to_tfs(fill_number: int, keys: Sequence[str] = None, names: Dict[str, str] = None) → TfsDataFrame

Extracts data for keys of fill from Timber.

Parameters:

• fill_number (int) -- Number of the fill to extract from.

• keys (Sequence[str]) -- the different variables names to extract data for.

• names (Dict[str, str) -- dict mapping keys to column names.

Returns:

The extracted data as a TfsDataFrame.