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: InputFiles, measure_input: DotDict, tune_dict: tune.TuneDict)[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: DotDict) → None[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: DotDict, input_files: InputFiles, 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: DotDict, tunes: TuneDict, phase_dict: PhaseDict, header_dict: dict[str, Any], plane: str) → tuple[tfs.TfsDataFrame, dict[str, Any]][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: DotDict, phase: pd.DataFrame, plane: str, meas_and_mdl_tunes: tuple[float, float]) → tuple[tfs.TfsDataFrame, str][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: DotDict, phase: pd.DataFrame, plane: str, meas_and_mdl_tunes: tuple[float, float]) → pd.DataFrame[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.

omc3.optics_measurements.crdt.calculate(measure_input: DotDict, input_files: InputFiles, invariants, header)[source]

Calculate the CRDT values.

omc3.optics_measurements.crdt.generic_dataframe(input_files: InputFiles, measure_input: DotDict, bpm_names: Sequence[str], dpp_value: int = 0)[source]

Generate a dataframe based on the MU-MDL columns from each measuement.

Data Models

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

class omc3.optics_measurements.data_models.InputFiles(files_to_analyse: Sequence[str | Path | tfs.TfsDataFrame], optics_opt: DotDict)[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 (if present).

Parameters:

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

dpp_frames_indices(plane: str, dpp_value: float | None)[source]

Return the indices of the frames that match the dpp.

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.

static 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: str, columns: ~collections.abc.Sequence[str], dpp_value: float | None = None, dpp_amp: bool = False, how: str = 'inner', dtype: ~numpy.dtype = <class 'numpy.float64'>) → DataFrame[source]

Constructs merged DataFrame from collected DataFrames in InputFiles, i.e. from the harpy output of the given measurements.

The input parameters to this function determine which data will be present in the joined frame: which plane to use, the columns to be included, a dpp_value filter (with tolerance from omc3.optics_measurements.dpp.DPP_TOLERANCE) and how to perform the merge.

You can also specify what dtype the resulting data will have, this should normally be float64.

The columns in the resulting Dataframe will be suffixed by __#, starting from 0 with increasing integers for each of the input files.

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.

  • dtype -- dtype of the merged DataFrame. Usually np.float64 should be used, but in case you have string- or complex- data you will need to set this accordingly or to None to avoid conversion.

Returns:

A merged TfsDataFrame from InputFiles.

omc3.optics_measurements.data_models.check_and_warn_about_offmomentum_data(input_files: InputFiles, plane: str, id_: str = None)[source]

A helper function to check if off-momentum data is present in the input files, but no dpp-value is given by the user.

See https://github.com/pylhc/omc3/issues/456 .

omc3.optics_measurements.data_models.filter_for_dpp(to_filter: dict[str, Sequence], input_files: InputFiles, dpp_value: float)[source]

Filter the given data for the given dpp-value.

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: DotDict, input_files: InputFiles, 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: DotDict, input_files: InputFiles, 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: DotDict, input_files: InputFiles, 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.append_amp_dpp(list_of_tfs: Sequence[tfs.TfsFile], dpp_values: Sequence[float])[source]

Add the dpp values to the DPP-header of the tfs files, if larger than the DPP-tolerance, otherwise set to zero. This is intended to the DPP value for on-momentum files to zero.

omc3.optics_measurements.dpp.append_dpp(list_of_tfs: Sequence[tfs.TfsFile], dpp_values: Sequence[float])[source]

Add the dpp values to the DPP-header of the tfs files.

omc3.optics_measurements.dpp.arrange_dpps(dpps: Sequence[float], tolerance: float = 0.0001)[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.

Todo

  • Put columns into the constants

omc3.optics_measurements.interaction_point.betastar_from_phase(meas_input: DotDict, phase_d: phase.PhaseDict) → pd.DataFrame[source]

Calculate beta* and l* from the phase advance of the IP-BPMs.

Parameters:

  • meas_input -- Measurement_input object.

  • phase_d -- PhaseDict output of the phasecalculation.

Returns:

A DataFrame with the beta* and l* as well as the phases used for the calculation as columns and the IP names as index.

omc3.optics_measurements.interaction_point.phase_to_betastar(lstar: float, phase: float, errphase: float) → tuple[float, float][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 (float) -- The distance between the BPMs and the IR.

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

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

Returns:

betastar and its error.

Return type:

tuple[float, float]

omc3.optics_measurements.interaction_point.write(df_ips: DataFrame, headers: dict[str, Any], output_dir: str | Path, plane: str)[source]

Write the interaction point data to disk. Empty DataFrames are skipped on write.

Parameters:

  • df_ips (pd.DataFrame) -- The interaction point data.

  • headers (dict[str, Any]) -- The headers for the tfs file.

  • output_dir (str|Path) -- The path to the output directory.

  • plane (str) -- The plane of the interaction point data.

Kick

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

omc3.optics_measurements.kick.calculate(measure_input: DotDict, input_files: InputFiles, 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.

class omc3.optics_measurements.phase.PhaseDict
omc3.optics_measurements.phase.calculate(meas_input: DotDict, input_files: InputFiles, tunes: TuneDict, plane: str, no_errors: bool = False) → tuple[dict[str, PhaseDict], list[pd.DataFrame]][source]

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

Parameters:

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

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

  • tunes (TuneDict) -- TuneDict contains measured tunes.

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

  • no_errors (bool) -- if True, measured errors shall not be propagated (only their spread).

Returns:

A tuple of a dictionary and a list of corresponding phase DataFrames. The dictionary contains the compensated and uncompensated results in PhaseDict form, i.e. a dictionary of DataFrames with the phase models, measured and errors. The list contains the DataFrames with the phase advances between BPMs and the total phase advances, for both compensated and uncompensated cases.

omc3.optics_measurements.phase.write(dfs: Sequence[pd.DataFrame], headers: Sequence[dict[str, Any]] | dict[str, Any], output: str | Path, plane: str)[source]

Write out the phase advance data into TFS-files.

omc3.optics_measurements.phase.write_special(meas_input: DotDict, phase_advances: pd.DataFrame, plane_tune: float, plane: str)[source]

Writes out the special phase advances, if any given by the accelerator class.

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: DotDict, input_files: InputFiles, tunes: TuneDict, phases: dict[str, PhaseDict], invariants: dict[str, pd.DataFrame], header: dict) → None[source]

Computes the RDTs for the given input files and settings up to the magnet order given in the inputs, and writes the results to file.

Parameters:

  • measure_input -- OpticsInput object containing analysis settings.

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

  • tunes -- TuneDict object mapping planes to tunes, as given by omc3.optics_measurements.tune.calculate().

  • phases

  • invariants (dict[str, pd.DataFrame]) -- dictionnary mapping planes to dataframes of actions/errors per kick, e.g. from omc3.optics_measurements.kick.calculate().

  • header -- headers to include to the written result files.

omc3.optics_measurements.rdt.complex_secondary_lines(phase_adv: ArrayLike[float], err_padv: ArrayLike[float], sig1: ArrayLike[complex], sig2: ArrayLike[complex])[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: dict[str, ndarray], plane: str, rdt: tuple[int, int, int, int])[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.