core.list_of_elements.factory module

Define an object to create ListOfElements.

Its main goal is to initialize ListOfElements with the proper input synchronous particle and beam properties. whole_list_run() is called within the Accelerator and generate a full ListOfElements from scratch.

subset_list_run() is called within Fault and generates a ListOfElements that contains only a fraction of the linac.

Todo

Also handle .dst file in subset_list_run().

Todo

Maybe it will be necessary to handle cases where the synch particle is not perfectly on the axis?

Todo

Find a smart way to sublass ListOfElementsFactory according to the BeamCalculator… Loading field maps not necessary with TraceWin for example.

Todo

The elements_to_dump key should be in the configuration file

class ListOfElementsFactory(is_3d: bool, is_multipart: bool, freq_bunch_mhz: float, default_field_map_folder: Path, load_field_maps: bool = True, field_maps_in_3d: bool = False, load_cython_field_maps: bool = False, elements_to_dump: ABCMeta | tuple[ABCMeta, ...] = ())

Bases: object

Factory class to create list of elements from different contexts.

__init__(is_3d: bool, is_multipart: bool, freq_bunch_mhz: float, default_field_map_folder: Path, load_field_maps: bool = True, field_maps_in_3d: bool = False, load_cython_field_maps: bool = False, elements_to_dump: ABCMeta | tuple[ABCMeta, ...] = ())

Declare and create some mandatory factories.

Note

For now, we have only one input_beam parameters, we create only one ListOfElements. Hence we create in the most general way possible. We instantiate InitialBeamParametersFactory with is_3d=True and is_multipart=True because it will work with all the BeamCalculator objects – some phase-spaces may be created but never used though.

Parameters:

phi_s_definition (str, optional) – Definition for the synchronous phases that will be used. Allowed values are in :var:`util.synchronous_phases.SYNCHRONOUS_PHASE_FUNCTIONS`. The default is 'historical'.

_delta_phi_for_tracewin(phi_at_entry_of_compensation_zone: float) → float

Give new absolute phases for TraceWin.

In TraceWin, the absolute phase at the entrance of the compensation zone is 0, while it is not in the rest of the code. Hence we must rephase the cavities in the subset.

_get_initial_element(elts: list[Element], simulation_output: SimulationOutput) → tuple[Element | str, str]

Set the element from which we should take energy, phase, etc.

_shift_entry_phase(cavities: list[FieldMap], delta_phi: float) → None

Shift the entry phase in the given cavities.

This is mandatory for TraceWin solver, as the absolute phase at the entrance of the first element is always 0.0.

_subset_files_dictionary(elts: list[Element], files_from_full_list_of_elements: dict[str, Any], folder: Path | str = PosixPath('tmp'), dat_name: Path | str = PosixPath('tmp.dat')) → dict[str, Path | list[list[str]]]

Set the new .dat file containing only elements of elts.

_subset_input_particle(simulation_output: SimulationOutput, **kwargs: Any) → ParticleInitialState

Create input particle for subset of list of elements.

_whole_list_input_particle(w_kin: float, phi_abs: float, z_in: float, **kwargs: ndarray) → ParticleInitialState

Create a ParticleInitialState for full list of elts.

from_existing_list(elts: ListOfElements, *, instructions_to_insert: Collection[Instruction] = (), append_stem: str = '', which_phase: str = 'phi_0_rel') → ListOfElements

Create new list of elements, based on an exising one.

This method is used for beauty pass: we already have fixed the linac, but we want to add DIAG/ADJUST TraceWin commands to perform a second optimisation.

Todo

Maybe gather some things with the subset?

subset_list_run(elts: list[Element], simulation_output: SimulationOutput, files_from_full_list_of_elements: dict[str, Path | str | list[list[str]]]) → ListOfElements

Create a ListOfElements as subset of a previous one.

Factory function used during the fitting process, called by a Fault object. During this optimisation process, we compute the propagation of the beam only on the smallest possible subset of the linac.

It creates the proper ParticleInitialState and BeamParameters objects. In contrary to new_list_of_elements(), the BeamParameters must contain information on the transverse plane if beam propagation is performed with TraceWin.

Parameters:

  • elts (list[Element]) – A plain list containing the elements objects that the object should contain.

  • simulation_output (SimulationOutput) – Holds the results of the pre-existing list of elements.

  • files_from_full_list_of_elements (dict) – The ListOfElements.files from the full ListOfElements.

Returns:

list_of_elements – Contains all the elements that will be recomputed during the optimisation, as well as the proper particle and beam properties at its entry.

Return type:

ListOfElements

whole_list_run(dat_file: Path, accelerator_path: Path, instructions_to_insert: Collection[Instruction] = (), **kwargs: Any) → ListOfElements

Create a new ListOfElements, encompassing a full linac.

Factory function called from within the Accelerator object.

Parameters:

  • dat_file (Path) – Absolute path to the .dat file.

  • accelerator_path (Path) – Absolute path where results for each BeamCalculator will be stored.

  • instructions_to_insert (Collection[Instruction], optional) – Some elements or commands that are not present in the .dat file but that you want to add. The default is an empty tuple.

  • kwargs – Arguments to instantiate the input particle and beam properties.

Returns:

list_of_elements – Contains all the Elements of the linac, as well as the proper particle and beam properties at its entry.

Return type:

ListOfElements