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, default_field_map_folder, beam_kwargs, export_phase, flag_cython=False, **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'])
default_field_map_folder (Path | str)
beam_kwargs (BeamKwargs)
export_phase (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat'] | Literal['as_in_settings'])
flag_cython (bool, default: False)

_ids = count(0)

classmethod reset_ids()[source]

Reset the id counter.

Useful between tests.

Return type:: None

__init__(reference_phase_policy, default_field_map_folder, beam_kwargs, export_phase, flag_cython=False, **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.
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.
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']) – The type of phase you want to export for your FIELD_MAP.

Return type:

None

reference_phase_policy: Literal['phi_0_abs', 'phi_0_rel', 'phi_s', 'as_in_original_dat']: How reference phase of CavitySettings will be initialized.

id: str

Unique ID for this object. Obtained by prepending its order in the list of BeamCalculator to its class name. Typically: "0_Envelope1D" or "1_TraceWin". Note that this will also be the name of the directory where results will be saved. Typical project structure is:

YYYY.MM.DD_HHhmm_SSs_MILLIms/
├── 000000_ref
│   ├── 0_Envelope1D/
│   └── 1_TraceWin/
├── 000001
│   ├── 0_Envelope1D/
│   └── 1_TraceWin/
├── 000002
│   ├── 0_Envelope1D/
│   └── 1_TraceWin/
├── 000003
│   ├── 0_Envelope1D/
│   └── 1_TraceWin/
└── lightwin.log

_set_up_common_factories()[source]

Create the factories declared in __init__().

Note

Was used to set the ListOfElementsFactory. But now, every BeamCalculator instantiates it differently, so it is created in _set_up_specific_factories.

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.

Return type:: None

abstractmethod _set_up_specific_factories()[source]

Set up the factories specific to the BeamCalculator.

Return type:: None

run(accelerator_id, 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:

accelerator_id (str) – Associated Accelerator.id. Looks like: 0000001_Solution.
elts (ListOfElements) – List of elements in which the beam must be propagated.
update_reference_phase (bool, default: False) – 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.reference_phase_policy does not align with CavitySettings.reference.
kwargs – Other keyword arguments passed to run_with_this(). As for now, only used by TraceWin.

Return type:

SimulationOutput

Returns:

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

abstractmethod run_with_this(accelerator_id, set_of_cavity_settings, elts, optimization_status, **kwargs)[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:

accelerator_id (str) – Associated Accelerator.id. Looks like: 0000001_Solution.
set_of_cavity_settings (SetOfCavitySettings) – Holds the norms and phases of the compensating cavities.
elts (ListOfElements) – List of elements in which the beam should be propagated.
optimization_status (Literal['not started', 'in progress', 'finished']) – Only used by TraceWin, to prevent errors during optimization phase.

Return type:

SimulationOutput

Returns:

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

post_optimisation_run_with_this(accelerator_id, optimized_cavity_settings, full_elts, **kwargs)[source]

Run a simulation a simulation after optimization 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:

accelerator_id (str)
optimized_cavity_settings (SetOfCavitySettings)
full_elts (ListOfElements)

Return type:

SimulationOutput

abstractmethod init_solver_parameters(accelerator)[source]

Init some BeamCalculator solver parameters.

Parameters:: accelerator (Accelerator)
Return type:: None

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.

Todo

recompute_reference should be deprecated right? Its role is filled by the pickling.

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.

_actual_compute(accelerator, keep_settings=True, ref_simulation_output=None)[source]

Wrap the beam propagation of the accelerator.

Parameters:

accelerator (Accelerator)
keep_settings (bool, default: True)
ref_simulation_output (SimulationOutput | None, default: None)

Return type:

SimulationOutput

_get_already_calculated(accelerator)[source]

Get previously calculated object.

This method should be used when the Accelerator is an unpickled object.

Todo

Support when the order of BeamCalculator changed?

Parameters:: accelerator (Accelerator)
Return type:: SimulationOutput | None

property cavity_settings_factory: CavitySettingsFactory: Return the factory with a concise call.

_abc_impl = <_abc._abc_data object at 0x7318fb95d3c0>