beam_calculation.beam_calculator module

Define a base class for beam propagation computing tools.

The base class BeamCalculator, allows to compute the propagation of the beam in a ListOfElements, possibly with a specific SetOfCavitySettings (optimisation process). It should return a SimulationOutput.

Todo

Precise that BeamParametersFactory and TransferMatrixFactory are mandatory.

class BeamCalculator(flag_phi_abs: bool, out_folder: Path | str, default_field_map_folder: Path | str)

Bases: ABC

Store a beam dynamics solver and its results.

__init__(flag_phi_abs: bool, out_folder: Path | str, default_field_map_folder: Path | str) → None

Set id, some generic parameters such as results folders.

Parameters:

  • flag_phi_abs (bool) – If the entry phase of the cavities \(\phi_0\) are absolute or relative. See the examples for an illustration of what it implies.

  • out_folder (Path | str) – Name of the folder where results should be stored, for each Accelerator under study. This is the name of a folder, not a full path.

  • default_field_map_folder (Path | str) – Where to look for field map files by default.

_abc_impl = <_abc._abc_data object>
_generate_simulation_output(*args, **kwargs) → SimulationOutput

Transform the output of run to a SimulationOutput.

_ids = count(0)
_set_up_common_factories() → None

Create the factories declared in __post_init__().

Todo

default_field_map_folder has a wrong default value. Should take path to the .dat file, that is not known at this point. Maybe handle this directly in the InstructionsFactory or whatever.

abstract _set_up_specific_factories() → None

Set up the factories specific to the BeamCalculator.

property cavity_settings_factory: CavitySettingsFactory

Return the factory with a concise call.

compute(accelerator: Accelerator, keep_settings: bool = True, recompute_reference: bool = True, output_time: bool = True, ref_simulation_output: SimulationOutput | None = None) → SimulationOutput

Wrap full process to compute propagation of beam in accelerator.

Parameters:

  • accelerator (Accelerator) – Accelerator under study.

  • keep_settings (bool, optional) – If settings/simulation output should be saved. The default is True.

  • recompute_reference (bool, optional) – If results should be taken from a file instead of recomputing everything each time. The default is True.

  • output_time (bool, optional) – To print in log the time the calculation took. The default is True.

  • ref_simulation_output (SimulationOutput | None, optional) – For calculation of mismatch factors. The default is None, in which case the calculation is simply skipped.

Returns:

simulation_output – Object holding simulation results.

Return type:

SimulationOutput

abstract init_solver_parameters(accelerator: Accelerator) → None

Init some BeamCalculator solver parameters.

abstract property is_a_3d_simulation: bool

Tell if the simulation is in 3D.

abstract property is_a_multiparticle_simulation: bool

Tell if the simulation is a multiparticle simulation.

abstract post_optimisation_run_with_this(optimized_cavity_settings: SetOfCavitySettings, full_elts: ListOfElements, **kwargs) → SimulationOutput

Run a simulation a simulation after optimisation is over.

With Envelope1D, it just calls the classic run_with_this(). But with TraceWin, we need to update the optimized_cavity_settings as running an optimisation run on a fraction of the linac is pretty different from running a simulation on the whole linac.

property reference_phase: Literal['phi_0_abs', 'phi_0_rel', 'phi_s']

Give the reference phase.

Todo

Handle reference synchronous phase.

run(elts: ListOfElements, update_reference_phase: bool = False, **kwargs) → SimulationOutput

Perform a simulation with default settings.

Todo

update_reference_phase is currently unused, because it is not useful once the propagation has been calculated. So… should I keep it? Maybe it can be useful in post_optimisation_run_with_this, or in scripts to convert the phase between the different references, or when I want to save the .dat?

Parameters:

  • elts (ListOfElements) – List of elements in which the beam must be propagated.

  • update_reference_phase (bool, optional) – To change the reference phase of cavities when it is different from the one asked in the .toml. To use after the first calculation, if BeamCalculator.flag_phi_abs does not correspond to CavitySettings.reference. The default is False.

  • kwargs – Other keyword arguments passed to run_with_this(). As for now, only used by TraceWin.

Returns:

simulation_output – Holds energy, phase, transfer matrices (among others) packed into a single object.

Return type:

SimulationOutput

abstract run_with_this(set_of_cavity_settings: SetOfCavitySettings | None, elts: ListOfElements, use_a_copy_for_nominal_settings: bool = True) → SimulationOutput

Perform a simulation with new cavity settings.

Calling it with set_of_cavity_settings = None shall be the same as calling the plain run method.

Parameters:

  • set_of_cavity_settings (SetOfCavitySettings | None) – Holds the norms and phases of the compensating cavities.

  • elts (ListOfElements) – List of elements in which the beam should be propagated.

  • use_a_copy_for_nominal_settings (bool, optional) – To copy the nominal CavitySettings and avoid altering their nominal counterpart. Set it to True during optimisation, to False when you want to keep the current settings. The default is True.

Returns:

simulation_output – Holds energy, phase, transfer matrices (among others) packed into a single object.

Return type:

SimulationOutput