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

RfField, Field

class CavitySettings(k_e, phi, reference, status, freq_bunch_mhz, freq_cavity_mhz=None, transf_mat_func_wrappers=None, phi_s_funcs=None, rf_field=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] | None, default: None)

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

• rf_field (RfField | 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, rf_field=None, field=None)

Instantiate the object.

Parameters:

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

• phi (float) – Input phase. 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)']) – A value in ALLOWED_STATUS.

• freq_bunch_mhz (float) – Bunch frequency in MHz.

• freq_cavity_mhz (float | None, default: None) – Frequency of the cavity in 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 (dict[str, Callable] | None, default: None) – A dictionary which keys are the different BeamCalculator ids, and values are corresponding functions to compute propagation of the beam. The default is None, in which case attribute is not set.

• phi_s_funcs (dict[str, Callable] | 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. The default is None, in which case attribute is not set.

• field (Field | None, default: None) – Holds the constant parameters, such as interpolated field maps.

• rf_field (RfField | None, default: None)

__str__()

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

Note

None means that the phase was not calculated.

classmethod from_other_cavity_settings(other, reference=None)

Create settings with same settings as provided.

Parameters:

• other (Self)

• reference (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | None, default: None)

Return type:

Self

classmethod from_optimisation_algorithm(base, k_e, phi, status, reference=None)

Create settings based on base with different k_e, phi_0.

Parameters:

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

• k_e (float) – New field amplitude.

• phi (float) – New reference phase. Its nature is defined by reference.

• status (Literal['compensate (in progress)', 'compensate (not ok)', 'compensate (ok)', 'failed', 'nominal', 'rephased (in progress)', 'rephased (ok)']) – Status of the created settings.

• reference (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | None, default: None) – The phase used as a reference.

Returns:

A new CavitySettings with modified amplitude and phase.

Return type:

Self

_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)

Shorthand to get attributes from this class or its attributes.

Parameters:

• *keys (Literal['field', 'freq_cavity_mhz', 'k_e', 'omega_0_rf', 'phi_ref', 'phi_rf', 'phi_s_func', 'reference', 'rf_field', 'status', 'v_cav_mv', 'w_kin'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['e_spat', 'n_cell', 'n_z', 'starting_position', 'section_idx']) – Name of the desired attributes.

• **kwargs (bool | str | None) – Other arguments passed to recursive getter.

• to_deg (bool, default: False)

Returns:

out – Attribute(s) value(s).

Return type:

Any

_check_consistency_of_status_and_reference()

Perform some tests on status and reference. :rtype: None

Todo

Maybe not necessary to raise an error when there is a mismatch.

set_bunch_to_rf_freq_func(freq_cavity_mhz)

Use cavity frequency to set a bunch -> rf freq function.

This method is called by the Freq.

Parameters:

freq_cavity_mhz (float) – Frequency in the cavity in MHz.

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

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.

property phi_0_abs: float | None

Get the absolute entry phase, compute if necessary.

property phi_0_rel: float | None

Get the relative entry phase, compute it if necessary.

property phi_s: float | None

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 | None, default: None) – A function that takes in the ouptut of transf_mat_function_wrapper and return the accelerating voltage in 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

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

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.

Returns:

A tuple containing (V_cav, phi_s).

Return type:

tuple[float, float]

Raises:

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

residue_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_target – Target synchronous phase in radians.

• phi_s (float)

Returns:

The squared difference between the target and computed phi_s.

Return type:

float

phi_s_to_phi_0_rel(phi_s)

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

Parameters:

phi_s (float) – Target synchronous phase in radians.

Returns:

Relative entry phase in radians that achieves the target phi_s.

Return type:

float

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.

Return type:

None

Examples

>>> phi_in_1st_element = 0.
>>> phi_in_20th_element = 55.
>>> 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)

_get_valid_func(obj, func_name, solver_id)

Get the function in func_name for solver_id.

Parameters:

• obj (object)

• func_name (str)

• solver_id (str)

Return type:

Callable