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_filecontent, which does the same thing as elts_n_cmds but less good

class FilesInfo[source]

Bases: TypedDict

Keep information on the loaded dat file.

dat_file: Path
dat_filecontent: list[DatLine]
accelerator_path: Path
elts_n_cmds: list[Instruction]
class ListOfElements(elts, input_particle, input_beam, tm_cumul_in, files, first_init=True)[source]

Bases: list

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

Parameters:
__init__(elts, input_particle, input_beam, tm_cumul_in, files, first_init=True)[source]

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, default: True) – To indicate if this a full linac or only a portion (fit process).

  • files (FilesInfo) –

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

    • 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_filecontent: list of list of str, holding content of the DAT.

  • tm_cumul_in (ndarray)

Return type:

None

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.

cavities(superposed='unpack')[source]

Give the list of cavities, with special treatment for superposed.

Parameters:

superposed (Literal['unpack', 'remove', 'keep'], default: 'unpack') –

How superposed field maps should be treated.

Return type:

list[FieldMap]

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)[source]

Tell if the required attribute is in this class.

Parameters:

key (str)

Return type:

bool

get(*keys, to_numpy=True, none_to_nan=False, remove_first=False, **kwargs)[source]

Get attributes from this class or its contained elements.

If the desired attribute belongs to GETTABLE_ELT or GETTABLE_FIELD_MAP, we concatenate the value of every element in a single list.

Parameters:

  • *keys (Literal['accelerator_path', 'dat_file', 'dat_filecontent', 'elts_n_cmds', 'files', 'input_beam', 'input_particle', 'tm_cumul_in'] | Literal['aperture_flag', 'field_map_filename', 'field_map_folder', 'geometry'] | Literal['dat_idx', 'elt_idx', 'idx', 'idx_in_lattice', 'lattice', 'length_m', 'name', 'nature', 'section'] | Literal['abs_mesh', 'd_z', 'n_steps', 'rel_mesh', 's_in', 's_out', 'transf_mat_function'] | 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'] | Literal['beta', 'gamma', 'phi_abs', 'synchronous', 'w_kin', 'z_in'] | Literal['e_mev', 'e_rest_mev', 'f_bunch_mhz', 'i_milli_a', 'q_adim', 'sigma', 'inv_e_rest_mev', 'gamma_init', 'omega_0_bunch', 'lambda_bunch', 'q_over_m', 'm_over_q'] | Literal['alpha_phiw', 'beta_phiw', 'envelope_energy_phiw', 'envelope_pos_phiw', 'eps_phiw', 'eps_no_normalization_phiw', 'eps_normalized_phiw', 'gamma_phiw', 'sigma_phiw', 'twiss_phiw', 'alpha_phiw99', 'beta_phiw99', 'envelope_energy_phiw99', 'envelope_pos_phiw99', 'eps_phiw99', 'eps_no_normalization_phiw99', 'eps_normalized_phiw99', 'gamma_phiw99', 'sigma_phiw99', 'twiss_phiw99', 'alpha_t', 'beta_t', 'envelope_energy_t', 'envelope_pos_t', 'eps_t', 'eps_no_normalization_t', 'eps_normalized_t', 'gamma_t', 'sigma_t', 'twiss_t', 'alpha_x', 'beta_x', 'envelope_energy_x', 'envelope_pos_x', 'eps_x', 'eps_no_normalization_x', 'eps_normalized_x', 'gamma_x', 'sigma_x', 'twiss_x', 'alpha_x99', 'beta_x99', 'envelope_energy_x99', 'envelope_pos_x99', 'eps_x99', 'eps_no_normalization_x99', 'eps_normalized_x99', 'gamma_x99', 'sigma_x99', 'twiss_x99', 'alpha_y', 'beta_y', 'envelope_energy_y', 'envelope_pos_y', 'eps_y', 'eps_no_normalization_y', 'eps_normalized_y', 'gamma_y', 'sigma_y', 'twiss_y', 'alpha_y99', 'beta_y99', 'envelope_energy_y99', 'envelope_pos_y99', 'eps_y99', 'eps_no_normalization_y99', 'eps_normalized_y99', 'gamma_y99', 'sigma_y99', 'twiss_y99', 'alpha_z', 'beta_z', 'envelope_energy_z', 'envelope_pos_z', 'eps_z', 'eps_no_normalization_z', 'eps_normalized_z', 'gamma_z', 'sigma_z', 'twiss_z', 'alpha_zdelta', 'beta_zdelta', 'envelope_energy_zdelta', 'envelope_pos_zdelta', 'eps_zdelta', 'eps_no_normalization_zdelta', 'eps_normalized_zdelta', 'gamma_zdelta', 'sigma_zdelta', 'twiss_zdelta'] | Literal['alpha', 'beta', 'beta_kin', 'envelope_energy', 'envelope_pos', 'eps', 'eps_no_normalization', 'eps_normalized', 'gamma', 'gamma_kin', 'sigma', 'twiss', 'z_abs'] | Literal['phiw', 'phiw99', 't', 'x', 'x99', 'y', 'y99', 'z', 'zdelta']) – Names of the desired attributes.

  • to_numpy (bool, default: True) – Convert list outputs to NumPy arrays.

  • none_to_nan (bool, default: False) – Replace None values with np.nan.

  • remove_first (bool, default: False) – Remove the first item of each element’s attribute except for the first element itself.

  • **kwargs (Any) – Passed to recursive getter or Element.get().

Returns:

A single value or tuple of values.

Return type:

Any

_first_init()[source]

Set structure, elements name, some indexes.

Return type:

None

_set_element_indexes()[source]

Set the element index.

Return type:

None

force_reference_phases_to(reference)[source]

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.

Parameters:

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

Return type:

None

store_settings_in_dat(dat_file, exported_phase, save=True)[source]

Update the DAT file, save it if asked.

This method is called several times:

  • Once per Fault (only the compensation zone is saved).

  • When all the Fault were dealt with.

It is also called by Accelerator.keep() method.

Parameters:

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

  • export_phase – Which phase should be put in the output DAT file.

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

  • exported_phase (Literal['phi_0_abs', 'phi_0_rel', 'phi_s', 'as_in_original_dat', 'as_in_settings'])

Return type:

None

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 "as_in_original_dat".

Parameters:

  • exported_phase (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat'] | Literal['as_in_settings'])

  • dat_file (Path)

  • save (bool)

Return type:

None

take(ids, id_nature)[source]
Overloads:

  • self, ids (int), id_nature (Literal[‘cavity’]) → FieldMap

  • self, ids (Sequence[int]), id_nature (Literal[‘cavity’]) → list[FieldMap]

  • self, ids (Sequence[Sequence[int]]), id_nature (Literal[‘cavity’]) → list[list[FieldMap]]

  • self, ids (int), id_nature (Literal[‘element’]) → Element

  • self, ids (Sequence[int]), id_nature (Literal[‘element’]) → list[Element]

  • self, ids (Sequence[Sequence[int]]), id_nature (Literal[‘element’]) → list[list[Element]]

  • self, ids (str), id_nature (Literal[‘name’]) → Element

  • self, ids (list[str]), id_nature (Literal[‘name’]) → list[Element]

  • self, ids (list[list[str]]), id_nature (Literal[‘name’]) → list[list[Element]]

  • self, ids (int), id_nature (Literal[‘section’, ‘lattice’]) → list[Element]

  • self, ids (Sequence[int]), id_nature (Literal[‘section’, ‘lattice’]) → list[list[Element]]

Parameters:
Return type:

Element | list[Element] | list[list[Element]] | FieldMap | list[FieldMap] | list[list[FieldMap]]

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

Parameters:
Return type:

Element | list[Element] | list[list[Element]] | FieldMap | list[FieldMap] | list[list[FieldMap]]

pickle(pickler, path=None)[source]

Pickle (save) the object.

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

Parameters:
Return type:

Path

classmethod from_pickle(pickler, path)[source]

Instantiate object from previously pickled file.

Parameters:
Return type:

Self

property files_info: FilesInfo

Return the files attribute.

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

generate_element_to_index_func(solver_id)[source]

Create the func to easily get data at proper mesh index.

Parameters:

solver_id (str) – Name of the solver, to identify and take the proper ElementBeamCalculatorParameters.

Return type:

ELEMENT_TO_INDEX_T

sumup_cavities(elts, filter=None)[source]

Extract main cavities information.

Parameters:
Return type:

DataFrame