core.elements.field_maps.cavity_settings module

Store cavity settings that can change during an optimisation.

Note

As for now, FieldMap is the only object 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

NewRfField

ALLOWED_REFERENCES = ('phi_0_abs', 'phi_0_rel', 'phi_s')
ALLOWED_STATUS = ('nominal', 'rephased (in progress)', 'rephased (ok)', 'failed', 'compensate (in progress)', 'compensate (ok)', 'compensate (not ok)')
class CavitySettings(k_e: float, phi: float, reference: Literal['phi_0_abs', 'phi_0_rel', 'phi_s'], status: Literal['nominal', 'rephased (in progress)', 'rephased (ok)', 'failed', 'compensate (in progress)', 'compensate (ok)', 'compensate (not ok)'], freq_bunch_mhz: float, freq_cavity_mhz: float | None = None, transf_mat_func_wrappers: dict[str, Callable] | None = None, phi_s_funcs: dict[str, Callable] | None = 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.

__init__(k_e: float, phi: float, reference: Literal['phi_0_abs', 'phi_0_rel', 'phi_s'], status: Literal['nominal', 'rephased (in progress)', 'rephased (ok)', 'failed', 'compensate (in progress)', 'compensate (ok)', 'compensate (not ok)'], freq_bunch_mhz: float, freq_cavity_mhz: float | None = None, transf_mat_func_wrappers: dict[str, Callable] | None = None, phi_s_funcs: dict[str, Callable] | None = None) → 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 (REFERENCE_T) – Name of the phase used for reference. When a particle enters the cavity, this is the phase that is not recomputed.

  • status (STATUS_T) – A value in :var:`ALLOWED_STATUS`.

  • freq_bunch_mhz (float) – Bunch frequency in MHz.

  • freq_cavity_mhz (float | None, optional) – 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, optional) – 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, optional) – 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.

_attr_to_str(attr_name: str, to_deg: bool = True) → str

Give the attribute as string.

_check_consistency_of_status_and_reference() → None

Perform some tests on status and reference.

Todo

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

_delete_non_reference_phases() → None

Reset the phases that are not the reference to None.

classmethod from_optimisation_algorithm(base: Self, k_e: float, phi: float, status: Literal['nominal', 'rephased (in progress)', 'rephased (ok)', 'failed', 'compensate (in progress)', 'compensate (ok)', 'compensate (not ok)'], reference: Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | None = None) → Self

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 ({"compensate (in progress)", "compensate (ok)", "compensate (not ok)"}) – Status of the created settings.

  • reference ({"phi_0_rel", "phi_0_abs", "phi_s"}) – The phase used as a reference.

Returns:

A new CavitySettings with modified amplitude and phase.

Return type:

Self

classmethod from_other_cavity_settings(other: Self, reference: Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | None = None) → Self

Create settings with same settings as provided.

get(*keys: str, to_deg: bool = False, **kwargs: bool | str | None) → Any

Shorthand to get attributes from this class or its attributes.

Parameters:

  • *keys (str) – Name of the desired attributes.

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

Returns:

out – Attribute(s) value(s).

Return type:

Any

has(key: str) → bool

Tell if the required attribute is in this class.

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_bunch: float

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

property phi_ref: float

Give the reference phase.

property phi_rf: float

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

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

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_bunch_to_rf_freq_func(freq_cavity_mhz: float) → None

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.

set_cavity_parameters_arguments(solver_id: str, w_kin: float, **kwargs) → None

Adapt the cavity parameters methods to beam with w_kin.

This function must be called every time the kinetic energy at the entrance of the cavity is changed (like this occurs during optimisation process) or 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 should be removed in your BeamCalculator, to avoid a clash in the phi_0_rel_to_cavity_parameters().

See also

set_cavity_parameters_methods

set_cavity_parameters_methods(solver_id: str, transf_mat_function_wrapper: Callable, phi_s_func: Callable | None = None) → None

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

This function is called within two contexts:

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, optional) – 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.

See also

set_cavity_parameters_arguments

shift_phi_bunch(delta_phi_bunch: float, check_positive: bool = False) → None

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.

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
property status: Literal['nominal', 'rephased (in progress)', 'rephased (ok)', 'failed', 'compensate (in progress)', 'compensate (ok)', 'compensate (not ok)']

Give the status of the cavity under study.

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

_get_valid_func(obj: object, func_name: str, solver_id: str) → Callable

Get the function in func_name for solver_id.