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(reference_phase_policy, out_folder, default_field_map_folder, beam_kwargs, flag_cython=False, export_phase='as_in_settings', **kwargs)[source]

Bases: ABC

Store a beam dynamics solver and its results.

Parameters:

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

  • out_folder (Path | str)

  • default_field_map_folder (Path | str)

  • beam_kwargs (BeamKwargs)

  • flag_cython (bool, default: False)

  • export_phase (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat'] | Literal['as_in_settings'], default: 'as_in_settings')

_ids = count(0)
__init__(reference_phase_policy, out_folder, default_field_map_folder, beam_kwargs, flag_cython=False, export_phase='as_in_settings', **kwargs)[source]

Set id, some generic parameters such as results folders.

Parameters:

  • reference_phase_policy (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat']) – How reference phase of CavitySettings will be initialized.

  • 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.

  • flag_cython (bool, default: False) – If the beam calculator involves loading cython field maps. The default is False.

  • beam_kwargs (BeamKwargs) – The config dictionary holding all the initial beam properties.

  • export_phase (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat'] | Literal['as_in_settings'], default: 'as_in_settings') – The type of phase you want to export for your FIELD_MAP. The default is "as_in_settings", which should be the same phases as in the original DAT file.

reference_phase_policy: Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat']

How reference phase of CavitySettings will be initialized.

_set_up_common_factories()[source]

Create the factories declared in __init__(). :rtype: None

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

Set up the factories specific to the BeamCalculator.

Return type:

None

run(elts, update_reference_phase=False, **kwargs)[source]

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:
Return type:

SimulationOutput

Returns:

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

abstract run_with_this(set_of_cavity_settings, elts, use_a_copy_for_nominal_settings=True)[source]

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, default: True) – 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.

Return type:

SimulationOutput

Returns:

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

abstract post_optimisation_run_with_this(optimized_cavity_settings, full_elts, **kwargs)[source]

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.

Parameters:
Return type:

SimulationOutput

abstract init_solver_parameters(accelerator)[source]

Init some BeamCalculator solver parameters.

Parameters:

accelerator (Accelerator)

Return type:

None

_generate_simulation_output(*args, **kwargs)[source]

Transform the output of run to a SimulationOutput.

Return type:

SimulationOutput

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

Give the reference phase.

Todo

Handle "as_in_original_dat".

abstract property is_a_multiparticle_simulation: bool

Tell if the simulation is a multiparticle simulation.

abstract property is_a_3d_simulation: bool

Tell if the simulation is in 3D.

compute(accelerator, keep_settings=True, recompute_reference=True, output_time=True, ref_simulation_output=None)[source]

Wrap full process to compute propagation of beam in accelerator.

Parameters:

  • accelerator (Accelerator) – Accelerator under study.

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

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

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

  • ref_simulation_output (SimulationOutput | None, default: None) – For calculation of mismatch factors. Skipped by default.

Return type:

SimulationOutput

Returns:

Object holding simulation results.

property cavity_settings_factory: CavitySettingsFactory

Return the factory with a concise call.

_abc_impl = <_abc._abc_data object at 0x75e517596d80>