list_of_elements module

Define a list of Element, with some additional methods.

Two objects can have a ListOfElements as attribute:

  • Accelerator: holds all the Element of the linac.

  • Fault: it holds only a fraction of the linac Element. Beam will be propagated a huge number of times during optimisation process, so we recompute only the strict necessary.

Todo

Delete dat_content, which does the same thing as elts_n_cmds but less good

class ListOfElements(elts: list[Element], input_particle: ParticleInitialState, input_beam: InitialBeamParameters, tm_cumul_in: ndarray, files: dict[str, Path | str | list[list[str]]], first_init: bool = True)

Bases: list

Class holding the elements of a fraction or of the whole linac.

__init__(elts: list[Element], input_particle: ParticleInitialState, input_beam: InitialBeamParameters, tm_cumul_in: ndarray, files: dict[str, Path | str | list[list[str]]], first_init: bool = True) → None

Create the object, encompassing all the linac or only a fraction.

The first case is when you initialize an Accelerator and compute the baseline energy, phase, etc values. The second case is when you only recompute a fraction of the linac, which is part of the optimisation process.

Parameters:

  • elts (list[Element]) – List containing the element objects.

  • input_particle (ParticleInitialState) – An object to hold initial energy and phase of the particle at the entry of the first element/

  • input_beam (InitialBeamParameters) – An object to hold emittances, Twiss, sigma beam matrix, etc at the entry of the first element.

  • first_init (bool, optional) – To indicate if this a full linac or only a portion (fit process). The default is True.

  • files (dict[str, str | list[list[str]] | pathlib.Path]) –

    A dictionary to hold information on the source and output files/folders of the object. The keys are:

    • dat_file: absolute path to the .dat file

    • elts_n_cmds: list of objects representing dat content

    • accelerator_path: where calculation results for each BeamCalculator will be stored.

    • dat_content: list of list of str, holding content of the .dat.

property w_kin_in

Get kinetic energy at entry of first element of self.

property phi_abs_in

Get absolute phase at entry of first element of self.

property l_cav: list[FieldMap]

Easy access to the list of cavities.

property tunable_cavities: list[FieldMap]

All the elements that can be used for compensation.

For now, only FieldMap. But in the future… Who knows?

property tracewin_command: list[str]

Create the command to give proper initial parameters to TraceWin.

has(key: str) → bool

Tell if the required attribute is in this class.

get(*keys: str, to_numpy: bool = True, remove_first: bool = False, **kwargs: bool | str | Element | None) → Any

Shorthand to get attributes from this class or its attributes.

This method also looks into the first Element of self. If the desired key is in this Element, we recursively get key from every Element and concatenate the output.

Parameters:

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

  • to_numpy (bool, optional) – If you want the list output to be converted to a np.ndarray. The default is True.

  • remove_first (bool, optional) – If you want to remove the first item of every Element key. It the element is the first of the list, we do not remove its first item. It is useful when the last item of an element is the same as the first item of the next element. For example, z_abs. The default is False.

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

Returns:

out – Attribute(s) value(s).

Return type:

Any

_first_init() → None

Set structure, elements name, some indexes.

_set_element_indexes() → None

Set the element index.

force_reference_phases_to(new_reference_phase: str) → None

Change the reference phase of the cavities in self.

This method is called by the BeamCalculator. It is used after the first propagation of the beam in the full ListOfElements, to force every CavitySettings to use the reference phase specified by the beam_calculator entry of the .toml.

store_settings_in_dat(dat_file: Path, which_phase: Literal['phi_0_abs', 'phi_0_rel', 'phi_s', 'as_in_settings', 'as_in_original_dat'] = 'phi_0_abs', save: bool = True) → None

Update the dat file, save it if asked.

Parameters:

  • dat_file (pathlib.Path) – Where the output .dat should be saved.

  • which_phase (Literal['phi_0_abs', 'phi_0_rel', 'phi_s', ) – ‘as_in_settings’, ‘as_in_original_dat’] Which phase should be put in the output .dat.

  • save (bool, optional) – If the output file should be created. The default is True.

Note

LightWin rephases cavities if the first Element in self is not the first of the linac. This way, the beam enters each cavity with the intended phase in TraceWin (no effect if the phases are exported as relative phase).

Raises:

NotImplementedError – If which_phase is different from "phi_0_abs" or "phi_0_rel".

take(ids: int, id_nature: Literal['cavity']) → FieldMap
take(ids: Sequence[int], id_nature: Literal['cavity']) → list[FieldMap]
take(ids: int, id_nature: Literal['element']) → Element
take(ids: Sequence[int], id_nature: Literal['element']) → list[Element]
take(ids: str, id_nature: Literal['name']) → Element
take(ids: Sequence[str], id_nature: Literal['name']) → list[Element]
take(ids: Sequence[Sequence[int]] | Sequence[Sequence[str]], id_nature: Literal['cavity', 'element', 'name']) → list[Sequence[Element]]

Convert list of indexes or names to a list of Element.

pickle(pickler: MyPickler, path: Path | str | None = None) → Path

Pickle (save) the object.

This is useful for debug and temporary saves; do not use it for long time saving.

classmethod from_pickle(pickler: MyPickler, path: Path | str) → Self

Instantiate object from previously pickled file.

property files_info: dict

Return the files attribute.

Deprecated since version This: is just an alias to the files dict; files_info should not be used anymore.