Optics Measurements

Measure Optics

This module contains high-level functions to manage most functionality of optics_measurements. It provides functions to compute various lattice optics parameters from frequency spectra.

omc3.optics_measurements.measure_optics.chromatic_beating(input_files, measure_input, tune_dict)[source]

Main function to compute chromatic optics beating.

Parameters:

  • tune_dict --

  • input_files -- InputFiles object containing frequency spectra files (linx/y).

  • measure_input -- ` OpticsInput` object containing analysis settings.

Returns:

omc3.optics_measurements.measure_optics.measure_optics(input_files: InputFiles, measure_input)[source]

Main function to compute various lattice optics parameters from frequency spectra.

Parameters:

  • input_files -- InputFiles object containing frequency spectra files (linx/y).

  • measure_input -- OpticsInput object containing analysis settings.

Returns:

Beta from Amplitude

This module contains some of the beta calculation related functionality of optics_measurements. It provides functions to calculate beta functions from amplitude data.

omc3.optics_measurements.beta_from_amplitude.calculate(meas_input, input_files, tune_dict, beta_phase, header_dict, plane)[source]

Calculates beta and fills the following TfsFiles: f"{AMP_BETA_NAME}{plane.lower()}{EXT}"

Parameters:

  • meas_input -- OpticsInput object.

  • input_files -- InputFiles object contains measurement files.

  • tune_dict -- TuneDict contains measured tunes.

  • beta_phase -- contains beta functions from measured from phase.

  • header_dict -- dictionary of header items common for all output files.

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

Returns:

Beta from Phase

This module contains some of the beta calculation related functionality of optics_measurements. It provides functions to calculate beta and alpha functions from phase advance data.

omc3.optics_measurements.beta_from_phase.calculate(meas_input, tunes, phase_dict, header_dict, plane)[source]

Calculates betas and alphas from phase advances.

Parameters:

  • meas_input -- OpticsInput object

  • tunes -- TuneDict contains measured tunes.

  • phase_dict -- contains measured phase advances.

  • header_dict -- dictionary of header items common for all output files.

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

Returns:

BetaDict object containing specific TfsDataFrame with results.

omc3.optics_measurements.beta_from_phase.calculate_beta_alpha_from_single_combination(c, sin_squared_elements, outer_elmts, cot_model, cot_meas, outer_meas_phase_adv, probed_bpm_name, betmdl1, alfmdl1, range_of_bpms)[source]

Calculates beta and alpha functions as well as the respective covariance matrix lines for the given BPM combination (triplet).

Parameters:

  • c -- relative indices of other two BPMs wrt probed one.

  • sin_squared_elements --

  • outer_elmts --

  • cot_model --

  • cot_meas --

  • outer_meas_phase_adv --

  • probed_bpm_name --

  • betmdl1 --

  • alfmdl1 --

  • range_of_bpms --

Returns:

omc3.optics_measurements.beta_from_phase.n_bpm_method(meas_input, phase, plane, meas_and_mdl_tunes)[source]

Calculates betas and alphas from using all BPM combination within range_of_bpms. It also accounts for systematic errors

Parameters:

  • meas_input -- Optics measurement configuration object.

  • phase -- phase matrices of measurement with errors and model tfs (bpm x bpm).

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

  • meas_and_mdl_tunes -- measured and model tunes.

Returns:

TfsDataFrame containing betas and alfas from phase.

omc3.optics_measurements.beta_from_phase.three_bpm_method(meas_input, phase, plane, meas_and_mdl_tunes)[source]

Calculates betas and alphas from using adjacent BPMs (3 combination). phase["MEAS"], phase["MODEL"], phase["ERRMEAS"] (from get_phases) are of the form:

BPM1

BPM2

BPM3

BPM4

BPM1

0

phi_21

phi_31

phi_41

BPM2

phi_12

0

phi_32

phi_42

BPM3

phi_13

phi_23

0

phi_43

and tilt_slice_matrix(matrix, shift, slice, tune) brings it into the form:

BPM1

BPM2

BPM3

BPM4

BPM_(i-1)

phi_1n

phi_21

phi_32

phi_43

BPM_i

0

0

0

0

BPM_(i+1)

phi_12

phi_23

phi_34

phi_45

cot_phase_*_shift1:

cot(phi_1n) - cot(phi_1n-1)

cot(phi_21) - cot(phi_2n)

cot(phi_32) - cot(phi_31)

NaN

NaN

NaN

NaN

NaN

NaN

cot(phi_13) - cot(phi_12)

cot(phi_24) - cot(phi_23)

cot(phi_35) - cot(phi_34)

  • for the combination xxxABBx: first row,

  • for the combinstion xBBAxxx: fourth row,

  • for the combination xxBABxx: second row of cot_phase_*_shift2.

Parameters:

  • meas_input -- Optics measurement configuration object.

  • phase -- phase matrices of measurement with errors and model tfs (bpm x bpm).

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

  • meas_and_mdl_tunes -- measured and model tunes.

Returns:

TfsDataFrame containing betas and alfas from phase.

Chromatic

This module contains chromatic calculations functionality of optics_measurements. It provides functions to compute various chromatic beam properties.

Constants

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

Combined RDTs

This module contains combined resonance driving terms calculations functionality of optics_measurements. It provides functions to compute combined resonance driving terms following the derivations in https://arxiv.org/pdf/1402.1461.pdf.

Data Models

Models used in optics measurements to store and pass around data.

class omc3.optics_measurements.data_models.InputFiles(files_to_analyse, optics_opt)[source]

Stores the input files, provides methods to gather quantity specific data

Public methods:

  • get_dpps (plane)

  • get_joined_frame (plane, columns, zero_dpp=False, how=’inner’)

  • get_columns (frame, column)

  • get_data (frame, column)

calibrate(calibs: Dict[str, DataFrame])[source]

Use calibration data to rescale amplitude and amplitude error.

Parameters:

calibs (Dict) -- Plane-Dictionary with DataFrames of calibration data.

dpps(plane: str) → ndarray[source]

Gathers measured DPPs from input files corresponding to given plane

Parameters:

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

Returns:

A np.ndarray of DPPs.

static get_columns(frame, column)[source]

Returns list of columns of frame corresponding to column in original files.

Parameters:

  • frame -- joined frame.

  • column -- name of column in original files.

Returns:

list of columns.

get_data(frame, column) → ndarray[source]

Returns data in columns of frame corresponding to column in original files.

Parameters:

  • frame -- joined frame.

  • column -- name of column in original files.

Returns:

A np.narray corresponding to column in original files.

joined_frame(plane, columns, dpp_value=None, dpp_amp=False, how='inner')[source]

Constructs merged DataFrame from InputFiles.

Parameters:

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

  • columns -- list of columns from input files.

  • dpp_value -- merges only files with given dpp_value.

  • dpp_amp -- merges only files with non-zero dpp amplitude (i.e. 3Dkicks).

  • how -- whi way to use for merging: inner (intersection) or outer (union), default is inner.

Returns:

A merged DataFrame from InputFiles.

Dispersion

This module contains dispersion calculations related functionality of optics_measurements. It provides functions to compute orbit, dispersion and normalised dispersion.

omc3.optics_measurements.dispersion.calculate_dispersion(meas_input, input_files, header_dict, plane)[source]

Calculates dispersion.

Parameters:

  • meas_input -- OpticsInput object.

  • input_files -- Stores the input files tfs.

  • header_dict -- OrderedDict containing information about the analysis.

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

Returns:

TfsDataFrame corresponding to output file.

omc3.optics_measurements.dispersion.calculate_normalised_dispersion(meas_input, input_files, beta, header_dict)[source]

Calculates normalised dispersion.

Parameters:

  • meas_input -- OpticsInput object.

  • input_files -- Stores the input files tfs.

  • beta -- measured betas to get dispersion from normalised dispersion.

  • header_dict -- OrderedDict containing information about the analysis.

Returns:

TfsDataFrame corresponding to output file.

omc3.optics_measurements.dispersion.calculate_orbit(meas_input, input_files, header, plane)[source]

Calculates orbit.

Parameters:

  • meas_input -- OpticsInput object

  • input_files -- Stores the input files tfs.

  • header -- OrderedDict containing information about the analysis.

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

Returns:

TfsDataFrame corresponding to output file.

Dpp

This module contains deltap over p calculations related functionality of optics_measurements. It provides functions to computes and arrange dp over p.

omc3.optics_measurements.dpp.arrange_dpps(dpps)[source]

Grouping of dpp-values and averaging them in the bins, also zeroes the bin closest to zero.

Isolation Forest

This module contains the isolation forest functionality of optics_measurements. It provides functions to detect and exclude BPMs with anomalies.

Interaction Point

This module contains IP properties calculations related functionality of optics_measurements. It provides functions to compute beta* from phase.

omc3.optics_measurements.interaction_point.betastar_from_phase(meas_input, phase_d)[source]

Writes the getIP files with the betastar computed using phase advance.

Parameters:

  • meas_input -- Measurement_input object.

  • phase_d -- Output of calculation.

Returns:

A nested dict with the same structure as the phase_d dict.

omc3.optics_measurements.interaction_point.phase_to_betastar(lstar, phase, errphase)[source]

Return the betastar and its error given the phase advance across the IP.

This function computes the betastar using the phase advance between the BPMs around the IP and their distance (lstar). The phase and error in the phase must be given in radians.

Parameters:

  • lstar -- The distance between the BPMs and the IR.

  • phase -- The phase advance between the BPMs at each side of the IP. Must be given in radians.

  • errphase -- The error in phase. Must be given in radians.

Kick

This module contains kick functionality of optics_measurements. It provides functions to compute kick actions.

omc3.optics_measurements.kick.calculate(measure_input, input_files, scale, header_dict, plane)[source]
Parameters:

  • measure_input -- OpticsInput object.

  • input_files -- Stores the input files tfs.

  • scale -- measured beta functions.

  • header_dict -- OrderedDict containing information about the analysis.

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

Returns:

TfsDataFrame containing actions and their errors.

Phase Advance

This module contains phase calculation functionality of optics_measurements. It provides functions to compute betatron phase advances and structures to store them.

omc3.optics_measurements.phase.calculate(meas_input: dict, input_files: dict, tunes, plane, no_errors=False) → Dict[str, Tuple[Dict[str, TfsDataFrame], TfsDataFrame]][source]

Calculate phases for ‘free’ and ‘uncompensated’ cases from the measurement files, and return a dictionary combining the results for each transverse plane.

Parameters:

  • meas_input (dict) -- OpticsInput object containing analysis settings from the command-line.

  • input_files (dict) -- InputFiles object containing frequency spectra files (linx/y).

  • tunes --

  • plane --

  • no_errors --

Returns:

A dictionary of the measured phase advances, with an entry for each horizontal plane. In said entry is a dictionary with the measured phase advances for ‘free’ and ‘uncompensated’ cases, as well as the location of the output TfsDataFrames for the phases.

Resonance Driving Terms

This module contains RDT calculations related functionality of optics_measurements. It provides functions to compute global resonance driving terms f_jklm.

omc3.optics_measurements.rdt.calculate(measure_input, input_files, tunes, phases, invariants, header)[source]
Parameters:

  • measure_input --

  • input_files --

  • tunes --

  • invariants --

  • header --

Returns:

omc3.optics_measurements.rdt.complex_secondary_lines(phase_adv, err_padv, sig1, sig2)[source]
Parameters:

  • phase_adv -- phase advances between two BPMs.

  • err_padv -- error on the phase advance between two BPMs.

  • sig1 -- Complex coefficients of a secondary lines at the first BPM of the pairs.

  • sig2 -- Complex coefficients of a secondary lines at the second BPM of the pairs.

Returns:

Tuple with amplitudes, phases err_amplitudes and err_phases of the complex signal.

omc3.optics_measurements.rdt.get_linearized_problem(invs, plane, rdt)[source]

2 * j * f_jklm * (powers of 2Jx and 2Jy) : f_jklm is later a parameter of a fit we use sqrt(2J): unit is sqrt(m).

Toolbox

This module contains helper functionality for optics_measurements. It provides functions to perform regularly used simple calculations.

omc3.optics_measurements.toolbox.ang_interval_check(ang)[source]

Returns ang wrapped into [-0.5, 0.5]

omc3.optics_measurements.toolbox.ang_sum(a, b)[source]

Returns a column containing the angular sum between angles a and b in [-0.5 , 0.5]

omc3.optics_measurements.toolbox.df_ang_diff(df, a_col, b_col)[source]

Returns a column containing the angular difference between angles a and b in [-0.5 , 0.5]

omc3.optics_measurements.toolbox.df_diff(df, a_col, b_col)[source]

Returns a column containing the difference between a_col and b_col

omc3.optics_measurements.toolbox.df_diff_with_err(df, a_col, b_col, a_err_col, b_err_col)[source]

Returns two columns containing the difference and the total errors of the given columns.

omc3.optics_measurements.toolbox.df_err_sum(df, a_err_col, b_err_col)[source]

Returns a column containing the root of the sum-of-squares of a_err_col and b_err_col

omc3.optics_measurements.toolbox.df_prod(df, a_col, b_col)[source]

Returns a column containing the product of a_col and b_col

omc3.optics_measurements.toolbox.df_prod_with_err(df, a_col, b_col, a_err_col, b_err_col)[source]

Returns two columns containing the product and the total errors of the given columns.

omc3.optics_measurements.toolbox.df_ratio(df, a_col, b_col)[source]

Returns a column containing the ratio between a_col and b_col

omc3.optics_measurements.toolbox.df_ratio_with_err(df, a_col, b_col, a_err_col, b_err_col)[source]

Returns two columns containing the ratio and the total errors of the given columns.

omc3.optics_measurements.toolbox.df_rel_diff(df, a_col, b_col)[source]

Returns a column containing the difference between a_col and b_col relative to b_col

omc3.optics_measurements.toolbox.df_rel_diff_with_err(df, a_col, b_col, a_err_col, b_err_col)[source]

Returns two columns containing the relative difference and the total errors of the given columns.

omc3.optics_measurements.toolbox.df_rel_err_sum(df, a_col, b_col, a_err_col, b_err_col)[source]

Returns a column containing the root of the relative sum-of-square of a_col/a_err_col and b_col/b_err_col

omc3.optics_measurements.toolbox.df_sum(df, a_col, b_col)[source]

Returns a column containing the sum of a_col and b_col

omc3.optics_measurements.toolbox.df_sum_with_err(df, a_col, b_col, a_err_col, b_err_col)[source]

Returns two columns containing the sum and the total errors of the given columns.

Tune

This module contains tune calculations functionality of optics_measurements. It provides functions to compute betatron tunes and structures to store them.

class omc3.optics_measurements.tune.TuneDict[source]

Data structure to hold tunes.

get_lambda(plane)[source]

Computes lambda compensation factor.

Parameters:

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

Returns:

lambda compensation factor (driven vs free motion).

phase_ac2bpm(df_idx_by_bpms: DataFrame, plane: str, accelerator)[source]

Returns the necessary values for the exciter compensation. See DOI: 10.1103/PhysRevSTAB.11.084002

Parameters:

  • df_idx_by_bpms (pandas.DataFrame) -- commonbpms (see GetLLM._get_commonbpms)

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

  • accelerator -- an Accelerator object.

Returns:

A Tuple consisting of four elements a, b, c, d.

  • a (string): name of the nearest BPM.

  • b (float): compensated phase advance between the exciter and the nearest BPM.

  • c (int): k of the nearest BPM.

  • d (string): name of the exciter element.