Detuning

Detuning Calculations

Functions to calculate detuning and its corrections.

class ir_amplitude_detuning.detuning.calculations.Method(*values)

Methods to calculate the detuning corrections. Use cvxpy for the convex Problem solver, use the numpy method to calculate the corrections with the pseudo-inverse. auto selects between the two, depening whether of constraints are given or not.

ir_amplitude_detuning.detuning.calculations.calc_effective_detuning(optics: TwissPerBeam, values: pd.Series) → dict[int, pd.DataFrame]

Build a dataframe that calculates the detuning based on the given optics and corrector values individually for the given IPs and corrector fields.

The detuning is “effective” as it is calculated from the pre-simulated optics. In contrast, for an exact detuning calculation the corrector values would need to be individually set, detuning gathered per PTC and then and compared to the unset detuning values.

ir_amplitude_detuning.detuning.calculations.calculate_correction(target: Target, method: Method = auto) → pd.Series[float]

Calculates the values to power the detuning correctors by solving the equation system of the form

\[M_{\beta \text{-coefficients}} \times K_NL = V_\text{Detuning}\]

the contents of which as described in more detail in the Chapter 7.2.2 of [DillyThesis2024] , in particular Eq. (7.4). In addition, Constraints can be added to the correction equation system, which are respected when using the cvxpy.Problem solver (method cvxpy).

In fact, this function always calculates the values with the convex solver (cvxpy), as well as with the pseudo-inverse method (numpy), but only returns the results of the method specified in method. The cvxpy method has the advantage that the constraints are respected, the numpy method has the advantage that the uncertainties are propagated. The function returns a series of correctors and their settings in KNL values, with uncertainties if available.

In this function everything contributing to the left hand side of the equation system (i.e. the matrix M) is named m_*, while everything that contributes to the right hand side (i.e. the detuning values V, or similarly the constraint values) is named v_*.

Warning

The calculated magnet strength assumes that the magnet circuit is implemented with a positive sign, giving a positive field gradient, in beam 1 and - when the field is anti-symmetric - a negative sign in beam 4 and does not have any coefficients.

Parameters:

• target (Target) -- A Target object defining the target detuning and constraints.

• method (Method) -- The results of which method used to solve the equation system to be returned.

Returns:

A Series of circuit names and their settings in KNL values.

Return type:

pd.Series[float]

Equation System

This module contains the functions to generate the terms to calculate detuning, including feed-down, and uses them, together with the detuning targets, to build the equation system. These can then be solved to calculate corrections.

class ir_amplitude_detuning.detuning.equation_system.DetuningCorrectionEquationSystem(m: DataFrame, m_constr: DataFrame, v: Series, v_constr: Series, v_meas: Series)

Class to hold the equation system for detuning correction. The equation system is of the form

\[M_{\beta \text{-coefficients}} \times K_NL = V_\text{Detuning}\]

as described in the Chapter 7.2.2 of [DillyThesis2024].

m

Coefficient matrix

Type:

pd.DataFrame

v

Detuning vector

Type:

pd.Series

m_constr

Coefficient matrix for constraints

Type:

pd.DataFrame

v_constr

Detuning vector for constraints

Type:

pd.Series

v_meas

Detuning vector keeping uncertainties if given

Type:

pd.Series

append_all(other: DetuningCorrectionEquationSystem) → None

Append all matrices and vectors from another equation system.

append_series_to_constraints_matrix(series: Series) → None

Append a series as a new row to the m_constr matrix.

append_series_to_matrix(series: Series) → None

Append a series as a new row to the m matrix.

fillna() → None

Fill the NaN in the matrices with zeros.

set_constraint(name: str, value: float) → None

Set a value in the constraint values.

set_value(name: str, value: float | MeasureValue) → None

Set a value in the values and measurement values (with error if there).

ir_amplitude_detuning.detuning.equation_system.beam_symmetry_sign(beam: int) → int

Sign to be used for magnets whose fields are anti-symmetric under beam direction change,

e.g. K4(L) and K6(L) in beam 2 will have opposite sign compared to beam 1.

This is needed, as we calculate the detuning of each beam independently (hence the feed-down is calculated with the offset as seen from the beam itself), but have a common magnet (the corrector) to be powered, whose field might look different depending on from which side you go through it.

Warning

This assumes that the magnet powering (which is what we calculate) is implemented with a positive sign in beam 1 and - when the field is anti-symmetric - a negative sign in beam 4.

Parameters:

beam (int) -- Beam number

Returns:

1 or -1

Return type:

int

ir_amplitude_detuning.detuning.equation_system.build_detuning_correction_matrix(target: Target) → DetuningCorrectionEquationSystem

Build the full linear equation system of the form M * circuits = detuning. In its current form, this builds for decapole (_b5) and dodecapole (_b6) circuits for the ips given in the detuning_data (which are the targets). Filtering needs to be done afterwards.

Parameters:

target (Target) -- The target to build the equation system for.

Returns:

The full equation system as object defined above for the given target, build from the individual equation systems for each target data.

Return type:

DetuningCorrectionEquationSystem

ir_amplitude_detuning.detuning.equation_system.build_detuning_correction_matrix_per_entry(target_data: TargetData) → DetuningCorrectionEquationSystem

Build a part of the full linear equation system of the form M * circuits = detuning, for the given TargetData.

Its building the equation system row-by-row, first for each detuning term, then for each constraint. Both beams are appended to the same system.

Parameters:

target_data (TargetData) -- The target to build the equation system for.

Returns:

The equation system as object defined above, but containing only the rows for the given target_data.

Return type:

DetuningCorrectionEquationSystem

ir_amplitude_detuning.detuning.equation_system.calculate_matrix_row(beam: int, twiss: DataFrame, correctors: Sequence[Corrector], term: FirstOrderTerm | SecondOrderTerm) → Series

Get one row of the full matrix for one beam and one detuning term. This is a wrapper to select the correct function depending on the order of the term. Feed-down to b4 is calculated as in Eq. (7.2) of [DillyThesis2024]

Parameters:

• beam (int) -- The beam to calculate the row for.

• twiss (pd.DataFrame) -- The twiss/optics of the beam.

• correctors (Correctors) -- The correctors to calculate the row for.

• term (DetuningTerm) -- The term to calculate the row for.

Returns:

The row of the matrix.

Return type:

pd.Series

ir_amplitude_detuning.detuning.equation_system.get_detuning_coeff(term: FirstOrderTerm | SecondOrderTerm, beta: dict[str, float]) → float

Get the coefficient for first and second order amplitude detuning, Eqs. (7.1) and (7.3) of [DillyThesis2024] respectively.

Parameters:

• term (str) -- ‘X20’, ‘Y02’, ‘X11’, ‘Y20’, ‘Y11’ or ‘X02’

• beta (dict[str, float]) -- Dictionary of planes (uppercase)and values.

Returns:

The detuning coefficient for the given term, calculated from the betas.

Return type:

float

Classes for Detuning

Classes used to hold and manipulate individual detuning (measurement) data.

class ir_amplitude_detuning.detuning.measurements.Constraints(X10: str | None = None, X01: str | None = None, Y10: str | None = None, Y01: str | None = None, X20: str | None = None, X11: str | None = None, X02: str | None = None, Y20: str | None = None, Y11: str | None = None, Y02: str | None = None, scale: float | None = None)

Class for holding detuning contraints. These are useful when trying to force a detuning term to have a specific sign, but not a specific value. Examples of this can be found in Fig. (7.1) of [DillyThesis2024].

Only set definitions are returned via __getitem__ or terms(), yet as they are used to build an equation system with minimization constraints, it is assumed that the values will only be used via the get_leq() method, which also applies the set scaling.

Only “>=” and “<=” are implemented. E.g. X10 = "<=0".

static all_terms(order: int | None = None) → tuple[str, ...]

Return all float-terms.

get_leq(item: str) → tuple[int, float]

Returns a tuple (sign, value) such that the given contraint is converted into a minimization constraint of the form sign * term <= value.

Examples

"<=4" returns (1, 4)

">=3" returns (-1, -3)

">=-2" returns (-1, 2)

Values are rescaled if scale is set.

Parameters:

item (str) -- term name, e.g. "X10".

terms() → Iterator[str]

Return names for all set terms as iterable.

class ir_amplitude_detuning.detuning.measurements.Detuning(X10: float | None = None, X01: float | None = None, Y10: float | None = None, Y01: float | None = None, X20: float | None = None, X11: float | None = None, X02: float | None = None, Y20: float | None = None, Y11: float | None = None, Y02: float | None = None, scale: float | None = None)

Class holding first and second order detuning values. Only set values are returned via __getitem__ or terms(). For convenience, the input values are scaled by the given scale parameter.

static all_terms(order: int | None = None) → tuple[str, ...]

Return all float-terms.

Parameters:

order (int) -- 1 or 2, for first and second order detuning terms respectively. Or None for all terms (Default: None).

apply_acdipole_correction() → Self

Correct for the influence of the AC-Dipole kick in measurement data.

See Eqs. (78) - (81) and Eqs. (94) - (99) in [DillyAmplitudeDetuning2023] and the derivations therein.

Returns:

The corrected detuning

Return type:

Detuning

merge_first_order_crossterm() → Self

Merge the cross-terms in the first order detuning into a single term X01, to avoid too much weight when fitting.

Returns:

The merged detuning

Return type:

Detuning

terms() → Iterator[str]

Return names for all set terms.

class ir_amplitude_detuning.detuning.measurements.DetuningMeasurement(X10: MeasureValue = None, X01: MeasureValue = None, Y10: MeasureValue = None, Y01: MeasureValue = None, X20: MeasureValue = None, X11: MeasureValue = None, X02: MeasureValue = None, Y20: MeasureValue = None, Y11: MeasureValue = None, Y02: MeasureValue = None, scale: float | None = None)

Class holding first and second order detuning measurement values (i.e. with error).

classmethod from_detuning(detuning) → Self

Create a DetuningMeasurement from a Detuning object, with zero errors.

get_detuning() → Detuning

Returns a Detuning object with the values (no errors) of this measurement.

class ir_amplitude_detuning.detuning.measurements.MeasureValue(value: float = 0.0, error: float = 0.0)

Class to hold a value with its error and do basic arithmetics.

Parameters:

• value (float) -- value of the measurement

• error (float) -- error of the measurement, treated as standard deviation

static mean(measurements: Sequence[MeasureValue])

Returns mean of the measurements.

static rms(measurements: Sequence[MeasureValue])

Returns rms of values and errors.

static weighted_mean(measurements: Sequence[MeasureValue])

Returns a mean weighted proportionally to the errors.

static weighted_rms(measurements: Sequence[MeasureValue])

Returns weighted rms of values and errors.

Correction Targets

Classes used to define correction targets. Each Target will be used to calcualate the correction, i.e. transformed into a single detuning equation system.

To accurately correct for different detuning contributions from the errors and crossing in each IP (or combination of IPs), each Target contains a list of TargetData, which defines the measured detuning and constraints for each machine configuration. These are used to build the rows of the equation system, with a single TargetData defining multiple rows, depending on the amount of beams and detuning components given.

This allows for a combined “local”, targeting the detunning stemming from a single IP, and “global”, correcting for the combined detuning in the machine, correction if needed.

class ir_amplitude_detuning.detuning.targets.Target(name: str, data: Sequence[TargetData])

Class to hold correction Target information, which can be used to construct a single equation system, calculating a combined correction optimizing for all TargetData definitions.

Parameters:

• name (str) -- Name of the Target

• data (Sequence[TargetData]) -- Data for the Target

class ir_amplitude_detuning.detuning.targets.TargetData(correctors: Correctors, optics: dict[int, tfs.TfsDataFrame], detuning: dict[int, Detuning], constraints: dict[int, Constraints] | None = None, label: str | None = None)

Class to hold the detunig data of a Target.

The TargetData is used to build multiple lines in an equation system, for each beam and each detuning/constraint component.

Parameters:

• correctors (Correctors) -- List of correctors to be used for optimizing the detuning/constraints.

• detuning (dict[int, Detuning]) -- Dictionary defining the detuning for each beam.

• optics (dict[int, tfs.TfsDataFrame]) -- Dictionary defining the optics for each beam.

• constraints (dict[int, Constraints] | None) -- Dictionary defining the constraints for each beam.

• label (str | None) -- Optional label for the TargetData, e.g. to identify different machine configurations. This is used internally to label different equation system rows, so should be unique per Target.

Detuning Terms

This module contains the definitions of how the detuning terms are represented in this code and in string outputs (TFS columns, logging, etc.). This follows the PTC-output convention ANH[XY] ORDER1 ORDER2 ORDER3 ORDER4, reduced to the plane of the tune (X or Y) and the order of the first two derivatives ( 2Jx and 2Jy respectively).

This representation is chosen over the LaTeX shorthand “Qxx” to have compact and same-length strings that are still readable.

class ir_amplitude_detuning.detuning.terms.FirstOrderTerm(*values)

class ir_amplitude_detuning.detuning.terms.SecondOrderTerm(*values)

ir_amplitude_detuning.detuning.terms.detuning_term_to_planes(term: FirstOrderTerm | SecondOrderTerm) → tuple[str, str]

Get the tune and action planes given detuning term.

Parameters:

term (str) -- Detuning term, e.g. “X02”

Returns:

(tune, action), e.g. (“x”, “yy”)

Return type:

tuple[str, str]

ir_amplitude_detuning.detuning.terms.get_order(term: FirstOrderTerm | SecondOrderTerm) → int

Get the order of the detuning, e.g. from X11 -> order 2, Y10 -> order 1.

Parameters:

term (str) -- Detuning Term, e.g. “X11”