Utilities

Common Utilities

This module contains common utilities for use in other modules.

class ir_amplitude_detuning.utilities.common.BeamDict

Dictionary with beam number as keys, where beam 2 and 4 are interchangeable. Also implements basic arithmetic operations, to be applied to all beams.

classmethod from_dict(d: dict[int, Any], default: callable = None)

Create a BeamDict from a regular dict, setting a default factory for missing keys.

class ir_amplitude_detuning.utilities.common.Container

Convenience wrapper to inherit directly, instead of using a metaclass.

class ir_amplitude_detuning.utilities.common.ContainerMeta

MetaClass to store data in class attributes. Minimal implementation to make this usable as a ‘Mapping’, i.e. dict-like.

class ir_amplitude_detuning.utilities.common.StrEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enum with string representation.

Note

Can possibly be removed in Python 3.11 as it is implemented there as enum.StrEnum. But beware, that "value" in StrEnum raises TypeError until Python 3.12, workaround is "value" in list(StrEnum) or to try StrEnum(value).

ir_amplitude_detuning.utilities.common.to_loop(iterable: Iterable[Any]) → list[Iterable[int]]

Get a list to loop over.

If there is only one entry, the return list will only have this entry wrapped in a list. If there are multiple entry, the first element will be a list of all entries combined, and then single-element lists containing one entry each.

Parameters:

iterable (Iterable[Any]) -- List to loop over

Returns:

List of lists of elements

Return type:

list[Iterable[int]]

Constants

Constants used throught the package.

Correctors

Utilities for working with Correctors, implemented to make the code more machine-independent, as you should be able to easily add new corrector definitions for a new machine.

class ir_amplitude_detuning.utilities.correctors.Corrector(field: FieldComponent, length: float, magnet: str, circuit: str, ip: int | None = None, madx_type: str | None = None)

Class to hold corrector information.

Parameters:

• field -- magnetic field component shorthand (e.g. ‘b5’ or ‘b6’)

• length -- length of the corrector in m

• magnet -- MAD-X magnet name, e.g. “MCTX.3L1”

• circuit -- MAD-X circuit name, e.g. “kctx3.l1”

• ip -- IP the corrector is located at (for filtering if only certain IPs are corrected)

• madx_type -- MAD-X magnet type, e.g. “MCTX”

class ir_amplitude_detuning.utilities.correctors.CorrectorMask(field: FieldComponent, length: float, magnet_pattern: str, circuit_pattern: str, madx_type: str | None = None)

Class to hold corrector templates to be filled in with IP and side.

Parameters:

• field -- magnetic field component shorthand (e.g. ‘b5’ or ‘b6’)

• length -- length of the corrector in m

• magnet_pattern -- MAD-X magnet name pattern, e.g. “MCTX.3{side}{ip}”

• circuit_pattern -- MAD-X circuit name pattern, e.g. “kctx3.{side}{ip}”

• ip

• madx_type -- MAD-X magnet type, e.g. “MCTX”

class ir_amplitude_detuning.utilities.correctors.FieldComponent(*values)

Fields for which detuning calculations are implemented.

ir_amplitude_detuning.utilities.correctors.fill_corrector_masks(corrector_masks: Sequence[CorrectorMask | Corrector], ips: Sequence[int], sides: Sequence[str] = 'LR') → Sequence[Corrector]

Fill the corrector masks with the ips and sides.

Parameters:

• corrector_masks (Sequence[CorrectorMask | Corrector]) -- list of corrector masks or correctors.

• ips (Sequence[int]) -- list of ips.

• sides (Sequence[str]) -- list of sides.

Returns:

sorted list of correctors

Return type:

list[Corrector]

ir_amplitude_detuning.utilities.correctors.get_fields(correctors: Sequence[Corrector]) → list[FieldComponent]

Get all field components available for correction by the correctors.

Parameters:

correctors (Correctors) -- list of correctors

Returns:

sorted list of uniqe field components

Return type:

list[FieldComponent]

Latex Utilities

Utilities to convert data to latex, useful for plotting and copy-pasting into reports.

ir_amplitude_detuning.utilities.latex.dqd2j(tune: str, action: str) → str

Latex representation of detuning term (in the shorthand version, used in my thesis/paper, jdilly).

Examples

dqd2j(“x”, “y”, 2) -> “Q_{x,yy}” dqd2j(“x”, “xy”) -> “Q_{x,xy}” dqd2j(“y”, “x”) -> “Q_{y,x}”

Parameters:

• tune -- “x” or “y”

• action -- “x” or “y”

• power -- integer power, default 1

ir_amplitude_detuning.utilities.latex.exp_m(e_power: int, m_power: int) → str

Latex representation of unit 10^power m^inv. Example: exp_m(3, -1) -> “cdot 10^{3};$m$^{-1}”.

Parameters:

• e_power -- integer power of 10

• m_power -- integer power of m

ir_amplitude_detuning.utilities.latex.partial_dqd2j(tune: str, action: str) → str

Latex representation of detuning term. .. admonition:: Examples

partial_dqdj(“x”, “yy”) -> “partial^{2}_{y}Q_{x}”. partial_dqdj(“x”, “xy”) -> “partial_{x}partial_{y}Q_{x}”. partial_dqdj(“y”, “x”) -> “partial_{x}Q_{y}”.

Parameters:

• tune -- “x” or “y”

• action -- “x” or “y”

• power -- integer power, default 1

ir_amplitude_detuning.utilities.latex.print_correction_and_error_as_latex(values: Sequence[MeasureValue], correctors: Sequence[str], exponent: float | None = None) → None

Print the correction values with errors as latex table snippet.

Parameters:

• values -- List of MeasureValue with the correction values

• correctors -- List of corrector names, same length as values

• exponent (float, optional) -- Exponent of 10 for the unit of the values.

ir_amplitude_detuning.utilities.latex.term2dqdj(term: FirstOrderTerm | SecondOrderTerm) → str

Wrapper to get the latex representation of a detuning term as in the shorthand.

Parameters:

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

ir_amplitude_detuning.utilities.latex.term2partial_dqdj(term: FirstOrderTerm | SecondOrderTerm) → str

Wrapper to get the latex representation of a detuning term with partial derivatives.

Parameters:

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

ir_amplitude_detuning.utilities.latex.unit_exp_m(e_power: int, m_power: int) → str

Latex representation of unit 10^power m^inv. Example: unit_exp_m(3, -1) -> “; [10^{3};$m$^{-1}]”.

Parameters:

• e_power -- integer power of 10

• m_power -- integer power of m

ir_amplitude_detuning.utilities.latex.ylabel_from_detuning_term(detuning_term: FirstOrderTerm | SecondOrderTerm, exponent: float = None) → str

Get the latex representation of a detuning term with partial derivatives to be used as y-label of a plot.

Parameters:

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

• exponent (float, optional) -- Exponent of 10 to be included in the latex representation.

Logging

Provides a basic logging setup for the package.

ir_amplitude_detuning.utilities.logging.log_setup(**kwargs)

Set up a basic logger.