cavity_settings module

Store cavity settings that can change during an optimisation.

Note

As for now, FieldMap is the only Element to have its properties in a dedicated object.

Todo

Similar to synchronous phase, allow for V_cav to be “master” instead of k_e.

See also

Field

TRANSF_MAT_FUNC_WRAPPER_T

A function that takes in the kinetic energy, the relative entry phase, the cavity settings, other kwargs, and returns a dict containing propagation info in the element.

alias of Callable[[float, float, CavitySettings, dict[str, Any]], dict[str, Any]]

class CavityVars(k_e, phi, status, reference)

Bases: NamedTuple

Regroup main cavity settings variables.

Parameters:

• k_e (float)

• phi (float)

• status (Literal['compensate (in progress)', 'compensate (not ok)', 'compensate (ok)', 'failed', 'nominal', 'rephased (in progress)', 'rephased (ok)'])

• reference (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'])

k_e: float

Alias for field number 0

phi: float

Alias for field number 1

status: Literal['compensate (in progress)', 'compensate (not ok)', 'compensate (ok)', 'failed', 'nominal', 'rephased (in progress)', 'rephased (ok)']

Alias for field number 2

reference: Literal['phi_0_abs', 'phi_0_rel', 'phi_s']

Alias for field number 3

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}

_fields = ('k_e', 'phi', 'status', 'reference')

classmethod _make(iterable)

Make a new CavityVars object from a sequence or iterable

_replace(**kwds)

Return a new CavityVars object replacing specified fields with new values

exception MissingAttributeError

Bases: RuntimeError

Raised when a phase cannot be calculated because of missing info.

class CavitySettings(k_e, phi, reference, status, freq_bunch_mhz, freq_cavity_mhz=None, transf_mat_func_wrappers=None, phi_s_funcs=None, field=None)

Bases: object

Hold the cavity parameters that can vary during optimisation.

Todo

Which syntax for when I want to compute the value of a property but not return it? Maybe a _ = self.phi_0_abs? Maybe this case should not appear here, appart for when I debug.

Note

In this routine, all phases are defined in radian and are rf phases.

Todo

Determine if status should be kept here or in the field map.

Todo

For TraceWin solver, I will also need the field map index.

Parameters:

• k_e (float)

• phi (float)

• reference (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'])

• status (Literal['compensate (in progress)', 'compensate (not ok)', 'compensate (ok)', 'failed', 'nominal', 'rephased (in progress)', 'rephased (ok)'])

• freq_bunch_mhz (float)

• freq_cavity_mhz (float | None, default: None)

• transf_mat_func_wrappers (dict[str, Callable[[float, float, CavitySettings, dict[str, Any]], dict[str, Any]]] | None, default: None)

• phi_s_funcs (dict[str, Callable[[Any], tuple[float, float]]] | None, default: None)

• field (Field | None, default: None)

__init__(k_e, phi, reference, status, freq_bunch_mhz, freq_cavity_mhz=None, transf_mat_func_wrappers=None, phi_s_funcs=None, field=None)

Instantiate the object.

Parameters:

• k_e (float) – Amplitude of the electric field.

• phi (float) – Input phase in radians. Must be absolute or relative entry phase, or synchronous phase.

• reference (Literal['phi_0_abs', 'phi_0_rel', 'phi_s']) – Name of the phase used for reference. When a particle enters the cavity, this is the phase that is not recomputed.

• status (Literal['compensate (in progress)', 'compensate (not ok)', 'compensate (ok)', 'failed', 'nominal', 'rephased (in progress)', 'rephased (ok)']) – Cavity status.

• freq_bunch_mhz (float) – Bunch frequency in \(\mathrm{MHz}\).

• freq_cavity_mhz (float | None, default: None) – Frequency of the cavity in \(\mathrm{MHz}\). The default is None, which happens when the ListOfElements is under creation and we did not process the FREQ commands yet. transf_mat_func_wrappers : A dictionary which keys are the different BeamCalculator ids, and values are corresponding functions to compute propagation of the beam.

• phi_s_funcs (dict[str, Callable[[Any], tuple[float, float]]] | None, default: None) – A dictionary which keys are the different BeamCalculator ids, and values are corresponding functions to compute synchronous phase and accelerating voltage from the ouput of corresponding transf_mat_func_wrapper.

• field (Field | None, default: None) – Holds the parameters that are geometry-specific, such as interpolated field maps.

• transf_mat_func_wrappers (dict[str, Callable[[float, float, CavitySettings, dict[str, Any]], dict[str, Any]]] | None, default: None)

Return type:

None

_transf_mat_func_wrappers: dict[str, TRANSF_MAT_FUNC_WRAPPER_T]

All functions that can be used to compute beam propagation in current field map

_phi_s_funcs: dict[str, PHI_S_FUNC_T]

All functions that can be used to compute synchronous phase and accelerating field in current field map

_transf_mat_func_wrapper: TRANSF_MAT_FUNC_WRAPPER_T

The function to use with current solver to compute beam propagation

_phi_s_func: PHI_S_FUNC_T

The function to use with current solver to compute synchronous phase and accelerating field

classmethod copy(base, cavity_vars=None)

Create cavity settings, based on base.

Parameters:

• base (Self) – The reference CavitySettings. A priori, this is the nominal settings.

• cavity_vars (CavityVars | None, default: None) – Amplitude, phase, status and reference to override the ones in base. Provided during optimization process.

Returns:

A new CavitySettings with modified amplitude and phase.

Return type:

Self

property w_kin: float

__str__()

Print out the different phases/k_e, and which one is the reference.

Note

None means that the phase was not calculated.

Return type:

str

_attr_to_str(attr_name, to_deg=True)

Give the attribute as string.

Parameters:

• attr_name (str)

• to_deg (bool, default: True)

Return type:

str

has(key)

Tell if the required attribute is in this class.

Parameters:

key (str)

Return type:

bool

get(*keys, to_deg=False, **kwargs)

Get attributes from this class or its nested members.

Parameters:

• *keys (Literal['acceptance_energy', 'acceptance_phi', 'field', 'freq_cavity_mhz', 'k_e', 'omega_0_rf', 'phi_ref', 'phi_rf', 'phi_s', 'reference', 'rf_field', 'status', 'v_cav_mv'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']) – Name of the desired attributes.

• to_deg (bool, default: False) – Wether keys with "phi" in their name should be multiplied by \(360 / 2\pi\).

• **kwargs (Any) – Other arguments passed to recursive getter.

Return type:

Any

Returns:

Attribute(s) value(s).

_check_consistency_of_status_and_reference()

Perform some tests on status and reference.

1. We check that if the cavity is rephased, its reference phase is not \(phi_{0,\,\mathrm{abs}}\)

2. If the cavity is broken, we check that its reference phase is not synchronous because it is not defined.

Return type:

None

set_bunch_to_rf_freq_func(freq_cavity_mhz=None)

Set the rf frequency, and methods to switch between freq definitions.

This method is called a first time at the instantiation of self; it will be called once again if a Freq command is found.

Parameters:

freq_cavity_mhz (float | None, default: None) – Frequency in the cavity in \(\mathrm{MHz}\). If it is not provided, we set it to the bunch frequency.

Return type:

None

property reference: Literal['phi_0_abs', 'phi_0_rel', 'phi_s']

Say what is the reference phase.

Equivalents of reference in TraceWin’s FIELD_MAP

LightWin’s reference	TraceWin
'phi_0_rel'	P = 0
'phi_0_abs'	P = 1
'phi_s'	SET_SYNC_PHASE

set_reference(reference, phi_ref=None, ensure_can_be_calculated=True)

Change the reference phase.

Parameters:

• reference (Literal['phi_0_abs', 'phi_0_rel', 'phi_s']) – The name of the new reference.

• phi_ref (float | None, default: None) – The new value for the reference phase in \(\mathrm{rad}\). Remember that when the value of the reference phase is updated, all other phases are invalidated.

• ensure_can_be_calculated (bool, default: True) – To check that the new reference phase is already set or can be calculated.

Raises:

MissingAttributeError – When ensure_can_be_calculated = True and the new reference phase cannot be calculated.

Return type:

None

property phi_ref: float

Give the reference phase.

_delete_non_reference_phases()

Reset the phases that are not the reference to None.

Return type:

None

property status: Literal['compensate (in progress)', 'compensate (not ok)', 'compensate (ok)', 'failed', 'nominal', 'rephased (in progress)', 'rephased (ok)']

Give the status of the cavity under study.

• STATUS_T

• STATUS_T

property phi_0_abs: float

Get the absolute entry phase, compute if necessary.

property phi_0_rel: float

Get the relative entry phase, compute it if necessary.

property phi_s: float

Get the synchronous phase, and compute it if necessary.

Note

It is mandatory for the calculation of this quantity to compute propagation of the particle in the cavity.

See also

set_cavity_parameters_methods

set_cavity_parameters_methods(solver_id, transf_mat_function_wrapper, phi_s_func=None)

Set the generic methods to compute beam propagation, cavity params.

This function is called within two contexts.

• When initializing the BeamCalculator specific parameters (ElementBeamCalculatorParameters).

• When re-initalizing the ElementBeamCalculatorParameters because the status of the cavity changed, and in particular when it switches to 'failed'. In this case, the _phi_s_func is not altered.

Parameters:

• solver_id (str) – The name of the solver for which functions must be changed.

• transf_mat_function_wrapper (Callable) – A function that compute the propagation of the beam.

• phi_s_func (Callable[[Any], tuple[float, float]] | None, default: None) – A function that takes in the output of transf_mat_function_wrapper and returns the accelerating voltage in \(\mathrm{MV}\) and the synchronous phase in \(rad\). The default is None, which happens when we break the cavity and only the transf_mat_function_wrapper needs to be updated. In this case, the synchronous phase function is left unchanged.

Return type:

None

See also

set_cavity_parameters_arguments

Return type:

None

Parameters:

• solver_id (str)

• transf_mat_function_wrapper (Callable)

• phi_s_func (Callable[[Any], tuple[float, float]] | None)

set_cavity_parameters_arguments(solver_id, w_kin, **kwargs)

Adapt the cavity parameters methods to beam with w_kin.

This function must be called:

• When the kinetic energy at the entrance of the cavity is changed (like this occurs during optimisation process)

• When the synchronous phase must be calculated with another solver.

Parameters:

• solver_id (str) – Name of the solver that will compute \(V_\mathrm{cav}\) and \(\phi_s\).

• w_kin (float) – Kinetic energy of the synchronous particle at the entry of the cavity.

• kwargs – Other keyword arguments that will be passed to the function that will compute propagation of the beam in the FieldMap. Note that you should check that phi_0_rel key is removed in your BeamCalculator, to avoid a clash in the _phi_0_rel_to_cavity_parameters function.

Return type:

None

See also

set_cavity_parameters_methods

Return type:

None

Parameters:

• solver_id (str)

• w_kin (float)

_phi_0_rel_to_cavity_parameters(phi_0_rel)

Compute cavity parameters based on relative entry phase.

Parameters:

phi_0_rel (float) – Relative entry phase in radians.

Return type:

tuple[float, float]

Returns:

A tuple containing (V_cav, phi_s).

Raises:

MissingAttributeError – If the transfer matrix function or phi_s function is not set.

_residual_func(phi_0_rel, phi_s)

Calculate the squared difference between target and computed phi_s.

Parameters:

• phi_0_rel (float) – Relative entry phase in radians.

• phi_s (float) – Target synchronous phase in radians.

Return type:

float

Returns:

The squared difference between the target and computed phi_s.

_phi_s_to_phi_0_rel(phi_s)

Find the relative entry phase that yields the target sync phase.

Parameters:

phi_s (float) – Target synchronous phase in radians.

Return type:

float

Returns:

Relative entry phase in radians that achieves the target phi_s.

Raises:

RuntimeError – If the optimization fails to find a solution.

property v_cav_mv: float | None

Get the accelerating voltage, and compute it if necessary.

Note

It is mandatory for the calculation of this quantity to compute propagation of the particle in the cavity.

See also

set_cavity_parameters_methods

property phi_rf: float

Get the rf phase of synch particle at entrance of cavity.

property phi_bunch: float

Return the entry phase of the synchronous particle (bunch ref).

shift_phi_bunch(delta_phi_bunch, check_positive=False)

Shift the synchronous particle entry phase by delta_phi_bunch.

This is mandatory when the reference phase is changed. In particular, it is the case when studying a sub-list of elements with TraceWin. With this solver, the entry phase in the first element of the sub-ListOfElements is always 0.0, even if is not the first element of the linac.

Parameters:

• delta_phi_bunch (float) – Phase difference between the new first element of the linac and the previous first element of the linac.

• check_positive (bool)

Return type:

None

Examples

>>> phi_in_1st_element = 0.0
>>> phi_in_20th_element = 55.0
>>> 25th_element: FieldMap
>>> 25th_element.cavity_settings.shift_phi_bunch(
>>> ... phi_in_20th_element - phi_in_1st_element
>>> )  # now phi_0_abs and phi_0_rel are properly understood

Parameters:

• check_positive (bool, default: False)

• delta_phi_bunch (float)

Return type:

None

property acceptance_phi: float | None

Get the phase acceptance.

property acceptance_energy: float | None

Get the energy acceptance.

plot()

Plot the profile of the electric field.

Return type:

None