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

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

  • kwargs (Any)

Return type:

None

_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 + self.id (+ 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(accelerator_id, elts, update_reference_phase=False, optimization_status='not started', **specific_kwargs)[source]

Run TraceWin.

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.

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

  • optimization_status (Literal['not started', 'in progress', 'finished'], default: 'not started')

Return type:

SimulationOutput

Returns:

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

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 is the same as calling the plain run() method.

Parameters:

  • accelerator_id (str) – Associated Accelerator.id. Looks like: 0000001_Solution.

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

  • optimization_status (Literal['not started', 'in progress', 'finished']) – To prevent errors interrupting simulation during optimization phases.

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, **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 0x7318fb466f80>
_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