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.

Todo

This absolute phase thing should be fixed now. Check this.

class TraceWin(executable, ini_path, base_kwargs, out_folder, default_field_map_folder, beam_kwargs, flag_phi_abs=False, cal_file=None, **kwargs)[source]

Bases: BeamCalculator

Hold a TraceWin beam calculator.

Parameters:

  • executable (pathlib.Path) – Path to the TraceWin executable.

  • ini_path (pathlib.Path) – Path to the .ini TraceWin file.

  • base_kwargs (dict[str, str | bool | int | None | float]) – TraceWin optional arguments. Override what is defined in .ini, but overriden by arguments from ListOfElements and SimulationOutput.

  • _tracewin_command (list[str] | None, optional) – Attribute to hold the value of the base command to call TraceWin.

  • out_folder (pathlib.Path | str) – Name of the results folder (not a complete path, just a folder name).

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

  • dat_file (pathlib.Path) – Base name for the .dat file. ??

  • default_field_map_folder (Path | str)

  • beam_kwargs (dict[str, Any])

  • flag_phi_abs (bool, default: False)

  • cal_file (Path | None, default: None)

  • kwargs (Any)

__init__(executable, ini_path, base_kwargs, out_folder, default_field_map_folder, beam_kwargs, flag_phi_abs=False, cal_file=None, **kwargs)[source]

Define some other useful methods, init variables.

Parameters:
_set_up_specific_factories()[source]

Set up the factories specific to the BeamCalculator.

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

Return type:

None

_tracewin_base_command(accelerator_path, **kwargs)[source]

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)

Parameters:

accelerator_path (Path)

Return type:

tuple[list[str], Path]

_tracewin_full_command(elts, set_of_cavity_settings, **kwargs)[source]

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.

Parameters:
Return type:

tuple[list[str], Path]

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

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, elts, use_a_copy_for_nominal_settings=True, **specific_kwargs)[source]

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

post_optimisation_run_with_this(optimized_cavity_settings, full_elts, **specific_kwargs)[source]

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

init_solver_parameters(accelerator)[source]

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 Envelope1D and Envelope3D, 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.

Parameters:

accelerator (Accelerator)

Return type:

None

property is_a_multiparticle_simulation: bool

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

property is_a_3d_simulation: bool

Tell if the simulation is in 3D.

_save_cavities_entry_phases(set_of_cavity_settings, cavities, simulation_output)[source]

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?

Parameters:
Return type:

None

_abc_impl = <_abc._abc_data object at 0x73dca83cf3c0>
_run_in_bash(command, output_command=True, output_error=False)[source]

Run given command in bash.

Parameters:

  • command (list[str])

  • output_command (bool, default: True)

  • output_error (bool, default: False)

Return type:

bool