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.

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

Bases: BeamCalculator

Hold a TraceWin beam calculator.

Parameters:
__init__(reference_phase_policy, out_folder, default_field_map_folder, beam_kwargs, export_phase, executable, ini_path, base_kwargs, cal_file=None, **kwargs)[source]

Define some other useful methods, init variables.

Todo

Check reference_phase_policy.

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.

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

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

  • ini_path (Path) – Path to the INI TraceWin file.

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

  • cal_file (Path | None, default: None) – Name of the results folder. Updated at every call of the init_solver_parameters() method, using Accelerator.accelerator_path and self.out_folder attributes.

  • kwargs (Any)

_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, 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.

  • specific_kwargs – TraceWin optional arguments. Overrides what is defined in base_kwargs and INI.

Return type:

SimulationOutput

Returns:

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

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, 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. The default is True.

Return type:

SimulationOutput

Returns:

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

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

SimulationOutput

Returns:

Necessary information on the run.

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.

_post_treat_cavity_setttings(set_of_cavity_settings, cavities, simulation_output)[source]

Store cavity settings in the appropriate CavitySettings.

Note

When we are under a fitting process, i.e. when set_of_cavity_settings is not None, we update the CavitySettings in the set_of_cavity_settings, not the ones in FieldMap.cavity_settings.

Parameters:
Return type:

None

_abc_impl = <_abc._abc_data object at 0x7feea8fae7c0>
_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