beam_calculation.tracewin.tracewin module

Define a BeamCalculator that will call TraceWin from cmd line.

It inherits from BeamCalculator base class. It solves the motion of the particles in envelope or multipart, in 3D. In contrary to Envelope1D solver, it is not a real solver but an interface with TraceWin which must be installed on your machine.

Warning

For now, TraceWin behavior with relative phases is undetermined. You should ensure that you are working with absolute phases, i.e. that last argument of FIELD_MAP commands is 1. You can run a simulation with Envelope1D solver and flag_phi_abs= True. The .dat file created in the 000001_ref folder should be the original .dat but converted to absolute phases.

class TraceWin(executable: Path, ini_path: Path, base_kwargs: dict[str, str | int | float | bool | None], out_folder: Path | str, default_field_map_folder: Path | str, flag_phi_abs: bool = False, cal_file: Path | None = None)

Bases: BeamCalculator

Hold a TraceWin beam calculator.

executable

Path to the TraceWin executable.

Type:

str

ini_path

Path to the .ini TraceWin file.

Type:

str

base_kwargs

TraceWin optional arguments. Override what is defined in .ini, but overriden by arguments from ListOfElements and SimulationOutput.

Type:

dict[str, str | bool | int | None | float]

_tracewin_command

Attribute to hold the value of the base command to call TraceWin.

Type:

list[str] | None, optional

id

Complete name of the solver.

Type:

str

out_folder

Name of the results folder (not a complete path, just a folder name).

Type:

str

load_results

Function to call to get the output results.

Type:

Callable

path_cal

Name of the results folder. Updated at every call of the init_solver_parameters() method, using Accelerator.accelerator_path and self.out_folder attributes.

Type:

str

dat_file

Base name for the .dat file. ??

__init__(executable: Path, ini_path: Path, base_kwargs: dict[str, str | int | float | bool | None], out_folder: Path | str, default_field_map_folder: Path | str, flag_phi_abs: bool = False, cal_file: Path | None = None) → None

Define some other useful methods, init variables.

_abc_impl = <_abc._abc_data object>
_save_cavities_entry_phases(set_of_cavity_settings: SetOfCavitySettings | None, cavities: Sequence[FieldMap], simulation_output: SimulationOutput) → None

Store the synchronous particle entry phase.

This quantity is required to switch between the different definitions of the phase. Note that, with Envelope1D and Envelope3D', it is done during the propagation of the beam, in the ``for elt in elts` loop.

Todo

Maybe I should also store the synchronous phase?

_set_up_specific_factories() → None

Set up the factories specific to the BeamCalculator.

This method is called in the super().__post_init__(), hence it appears only in the base BeamCalculator.

_tracewin_base_command(accelerator_path: Path, **kwargs) → tuple[list[str], Path]

Define the ‘base’ command for TraceWin.

This part of the command is the same for every ListOfElements and every Fault. It sets the TraceWin executable, the .ini file. It also defines base_kwargs, which should be the same for every calculation. Finally, it sets path_cal. But this path is more ListOfElements dependent… Accelerator.accelerator_path + out_folder

(+ fault_optimisation_tmp_folder)

_tracewin_full_command(elts: ListOfElements, set_of_cavity_settings: SetOfCavitySettings | None, **kwargs) → tuple[list[str], Path]

Set the full TraceWin command.

It contains the ‘base’ command, which includes every argument that is common to every calculation with this BeamCalculator: path to .ini file, to executable…

It contains the ListOfElements command: path to the .dat file, initial energy and beam properties.

It can contain some SetOfCavitySettings commands: ele arguments to modify some cavities tuning.

init_solver_parameters(accelerator: Accelerator) → None

Set the path_cal variable.

We also set the _tracewin_command attribute to None, as it must be updated when path_cal changes.

Note

In contrary to Element1D and Element3D, this routine does not set parameters for the BeamCalculator. As a matter of a fact, TraceWin is a standalone code and does not need out solver parameters. However, if we want to save the meshing used by TraceWin, we will have to use the ElementTraceWinParametersFactory later.

property is_a_3d_simulation: bool

Tell if the simulation is in 3D.

property is_a_multiparticle_simulation: bool

Tell if you should buy Bitcoins now or wait a few months.

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

Run TraceWin with optimized cavity settings.

After the optimisation, we want to re-run TraceWin with the new settings. However, we need to tell it that the linac is bigger than during the optimisation. Concretely, it means:

  • rephasing the cavities in the compensation zone

  • updating the index n of the cavities in the ele[n][v] command.

Note that at this point, the .dat has not been updated yet.

Parameters:
Returns:

simulation_output – Necessary information on the run.

Return type:

SimulationOutput

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

Run TraceWin.

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.

  • specific_kwargs (dict) – TraceWin optional arguments. Overrides what is defined in base_kwargs and .ini.

Returns:

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

Return type:

SimulationOutput

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

Perform a simulation with new cavity settings.

Calling it with set_of_cavity_settings = None is the same as calling the plain run() method.

Parameters:

  • set_of_cavity_settings (SetOfCavitySettings | None) – The new cavity settings to try. If it is None, then the cavity settings are taken from the FieldMap objects.

  • 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

_run_in_bash(command: list[str], output_command: bool = True, output_error: bool = False) → bool

Run given command in bash.