Coupling

Functions to estimate coupling from twiss dataframes and different methods to calculate the closest tune approach from the calculated coupling RDTs.

optics_functions.coupling.check_resonance_relation(df: DataFrame, to_nan: bool = False) → DataFrame[source]

Checks that |F1001| >= |F1010|. If desired, sets the invalid points to NaN. This is only used for checking in the closest_tune_approach() function, but can be invoked by the user with to_nan = True and the resulting DataFrame can then be passed to closest_tune_approach().

Parameters:

  • df (DataFrame) -- Dataframe containing the coupling columns.

  • to_nan (bool) -- If true, sets values where |F1001| <= |F1010| to NaN.

Returns:

A copy of the input data frame, with or without NaNs.

optics_functions.coupling.closest_tune_approach(df: TfsDataFrame, qx: float | None = None, qy: float | None = None, method: str = 'teapot') → TfsDataFrame[source]

Calculates the closest tune approach from coupling resonances.

A complex F1001 column is assumed to be present in the DataFrame. This can be calculated by rdts() coupling_from_rdts() or coupling_from_cmatrix(). If F1010 is also present it is used, otherwise it is assumed 0.

The closest tune approach is calculated by means of Eq. (27) in [CalagaBetatronCoupling2005] (method=”teapot” or “calaga”) by default, or approximated by Eq. (1) in [PerssonImprovedControlCoupling2014] (method=”franchi”), Eq. (27) in [CalagaBetatronCoupling2005] with the Franchi appoximation (method=”teapot_franchi”), Eq. (2) in [PerssonImprovedControlCoupling2014] (method=”persson”), the latter without the exp(i(Qx-Qy)s/R) term (method=”persson_alt”), Eq. (14) in [HoydalsvikEvaluationOfTheClosestTuneApproach2021] (method=”hoydalsvik”), or the latter without the exp(i(Qx-Qy)s/R) term (method=”hoydalsvik_alt”).

For “persson[_alt]” and “hoydalsvik[_alt]” methods, also MUX and MUY columns are needed in the DataFrame as well as LENGTH (of the machine) and S column for the “persson” and “hoydalsvik” methods.

Parameters:

  • df (TfsDataFrame) -- Twiss Dataframe, needs to have complex-valued F1001 column.

  • qx (float) -- Tune in X-Plane (if not given, header df.Q1 is assumed present).

  • qy (float) -- Tune in Y-Plane (if not given, header df.Q2 is assumed present).

  • method (str) -- Which method to use for evaluation. Choices: “calaga”, “teapot”, “franchi”, “teapot_franchi”, “persson”, “persson_alt”, “hoydalsvik” or “hoydalsvik_alt”.

Returns:

A new TfsDataFrame with a closest tune approach (DELTAQMIN) column. The value is real for “calaga”, “teapot”, “teapot_franchi” and “franchi” methods. The actual closest tune approach value is the absolute value of the mean of this column.

optics_functions.coupling.coupling_via_cmatrix(df: DataFrame, complex_columns: bool = True, output: Sequence[str] = ('rdts', 'gamma', 'cmatrix')) → DataFrame[source]

Calculates C matrix then Coupling and Gamma from it. See [CalagaBetatronCoupling2005] .

Parameters:

  • df (DataFrame) -- Twiss Dataframe

  • complex_columns (bool) -- Output complex values in single column of type complex. If False, split complex columns into two real-valued columns.

  • output (Sequence[str]) -- Combination of ‘rdts’, ‘gamma’ and ‘cmatrix’. Specifies which parameters one wants to output.

Returns:

New TfsDataFrame with columns as specified in ‘output’.

optics_functions.coupling.coupling_via_rdts(df: TfsDataFrame, complex_columns: bool = True, **kwargs) → TfsDataFrame[source]

Returns the coupling terms.

Warning

This function changes sign of the real part of the RDTs compared to [FranchiAnalyticFormulas2017] to be consistent with the RDT calculations from [CalagaBetatronCoupling2005] .

Parameters:

  • df (TfsDataFrame) -- Twiss Dataframe.

  • complex_columns (bool) -- Output complex values in single column of type complex. If False, split complex columns into two real-valued columns.

Keyword Arguments:

**kwargs -- Remaining arguments from rdts() i.e. qx, qy, feeddown, loop_phases and hamiltionian_terms.

Returns:

A new TfsDataFrame with Coupling Columns.

optics_functions.coupling.rmatrix_from_coupling(df: DataFrame, complex_columns: bool = True) → DataFrame[source]

Calculates the R-matrix from a DataFrame containing the coupling columns as well as alpha and beta columns. This is the inverse of optics_functions.coupling.coupling_via_cmatrix(). See [CalagaBetatronCoupling2005] .

Parameters:

  • df (DataFrame) -- Twiss Dataframe.

  • complex_columns (bool) -- Tells the function if the coupling input columns are complex-valued or split into real and imaginary parts.

Returns:

A new DataFrame containing the R-columns.