Configuration

Most of the configuration of LightWin is performed through a .toml configuration file, which should be given as argument to several objects initialisation. The configuration file is treated with the help of the tomllib module. It is processed by the process_config() function, which checks it’s validity and converts it to a dictionary.

Note

Configuration was previously set up thanks to a .ini file. This is now deprecated.

The name of every section is not important, as long as every section is correctly passed to process_config(). It is however recommended to use explicit names.

Example for the beam section

[beam_proton]     # this could be [bonjoure] or anything
e_rest_mev = 938.27203
q_adim = 1.0
e_mev = 20.0
f_bunch_mhz = 350.0
i_milli_a = 25.
sigma = [
   [ 1e-6, -2e-7, 0.0,   0.0,  0.0,   0.0],
   [-2e-7,  8e-7, 0.0,   0.0,  0.0,   0.0],
   [ 0.0,   0.0,  1e-6, -2e-7, 0.0,   0.0],
   [ 0.0,   0.0, -2e-7,  8e-7, 0.0,   0.0],
   [ 0.0,   0.0,  0.0,   0.0,  1e-6, -2e-7],
   [ 0.0,   0.0,  0.0,   0.0, -2e-7,  8e-7],
]

[beam_proton_no_space_charge]   # or [sdaflghsh] but it would be less explicit in my humble opinion
linac = my_ads
e_rest_mev = 938.27203
q_adim = 1.0
e_mev = 20.0
f_bunch_mhz = 350.0
i_milli_a = 0.0
sigma = [
   [ 1e-6, -2e-7, 0.0,   0.0,  0.0,   0.0],
   [-2e-7,  8e-7, 0.0,   0.0,  0.0,   0.0],
   [ 0.0,   0.0,  1e-6, -2e-7, 0.0,   0.0],
   [ 0.0,   0.0, -2e-7,  8e-7, 0.0,   0.0],
   [ 0.0,   0.0,  0.0,   0.0,  1e-6, -2e-7],
   [ 0.0,   0.0,  0.0,   0.0, -2e-7,  8e-7],
]

Note

In order to dynamically keep track of the options that are implemented, the Allowed values column of following tables contains a link to the variable storing the possible values, when relevant.

files section (mandatory)

This section is mandatory to initialize an Accelerator through the accelerator_factory() function. It must contain the key dat_file, which is the path to the linac structure file (same format as TraceWin).

Entry	Type	Description	Allowed values	Mandatory?
dat_file	path	Path to the .dat file		✅

See also: config.files and the `TraceWin compatibility note`_.

beam section (mandatory)

Here we define the main properties of the beam at the entrance of the linac. Note that with TraceWin, most of these properties are defined within it’s own .ini file. The units must be consistent with LightWin’s system of units, see also Units and conventions.

Entry	Type	Description	Allowed values	Mandatory?
e_rest_mev	float	Rest energy of particle in \(\mathrm{MeV}\)		✅
q_adim	float	Adimensioned charge of particle		✅
e_mev	float	Energy of particle at entrance in \(\mathrm{MeV}\)		✅
f_bunch_mev	float	Beam bunch frequency in \(\mathrm{MHz}\)		✅
i_milli_a	float	Beam current in \(\mathrm{mA}\)		❌
sigma	list of list of float	Input \(\sigma\) beam matrix in \(\mathrm{m}\); \(\mathrm{rad}\)		✅

Format for the sigma entry:

sigma = [
   [ 1e-6, -2e-7,  0e+0, 0e+0,  0e+0, 0e+0],
   [-2e-7,  8e-7,  0e+0, 0e+0,  0e+0, 0e+0],
   [ 0e+0,  0e+0, -2e-7, 8e-7,  0e+0, 0e+0],
   [ 0e+0,  0e+0, -2e-7, 8e-7,  0e+0, 0e+0],
   [ 0e+0,  0e+0,  0e+0, 0e+0, -2e-7, 8e-7],
   [ 0e+0,  0e+0,  0e+0, 0e+0, -2e-7, 8e-7]
 ]

beam_calculator section (mandatory)

Entry	Type	Description	Allowed values	Mandatory?
tool	str	Name of the tool	tools	✅

If the desired BeamCalculator is Envelope1D:

Entry	Type	Description	Allowed values	Mandatory?
flag_phi_abs	bool	Simulation realized in absolute phase?		✅
flag_cython	bool	Use Cython implementation?		✅
n_steps_per_cell	int	# of integration steps per cavity cell		✅
method	str	Integration method	methods	✅

Note that Envelope3D takes the same configuration entries, except flag_cython (not implemented yet) and method that must be 'RK4' ('leapgrog' not implemented yet).

If the desired BeamCalculator is TraceWin:

Entry	Type	Description	Allowed values	Mandatory?
machine_config_file	str	A .toml file with paths to the executables	existing relative (w.r.t lightwin.toml) or absolute paths	✅
machine_name	str	Name of machine	must be a key in the machine_config_file	❌
simulation_type	str	TraceWin solver	Must be an entry under your machine name in machine_config_file	✅
ini_path	path	Path to TraceWin’s .ini file		✅
hide	bool	To avoid TraceWin window	None	❌
partran	int	To force or not Partran tracking	1 or 0	❌
…		Every TraceWin command line option		❌

Check TraceWin’s documentation for the list of command line arguments. Note that you also need to create a configuration file that will define the path to the TraceWin executables. See data/examples/machine_config_file.toml for an example.

Todo

List of allowed tracewin arguments in doc

Todo

There are doublons between doc in config.beam_calculator and here. Maybe keep in module, but make the format better.

The [beam_calculator_post] follows the same format. It is used to store a second BeamCalculator. This is mainly useful for defining a more precise – but more time-consuming – beam dynamics tool, for example to check your compensation settings.

plots section (mandatory)

This section defines what quantities will be plotted at the end of the simulation.

Entry	Type	Description	Allowed values	Mandatory?
energy	bool	Plot evolution of kinetic energy?		❌
phase	bool	Plot evolution of absolute phase?		❌
cav	bool	Plot cavity parameters?		❌
emittance	bool	Plot evolution of emittance?		❌
twiss	bool	Plot Twiss parameters?		❌
envelopes	bool	Plot envelopes?		❌
transfer matrices	bool	Plot transfer matrix components?		❌

Warning

Plot of transfer matrix currently not working.

wtf section

wtf stands for what to fit. This section parametrizes the failed cavities, as well as how they are fixed.

Entry	Type	Description	Allowed values	Mandatory?
optimisation_algorithm	str	Name of optimisation algorithm	algorithms	✅
strategy	str	How compensating cavities are selected	strategies	✅
id_nature	str	Indicates if failed is element index/cavity index/name	element or cavity or name	✅
failed	list[list[int]] | list[list[str]]	Index of failed cavities		✅
objective_preset	str	Objectives for the optimisation algorithm	objective_presets	✅
optimisation_algorithm_kwargs	dict	Keyword arguments passed to the actual optimisation method		❌

Each strategy entry requires specific additional arguments. As an example, with the k out of n method, you need to give LightWin k, the number of compensating cavities per failed cavity. The specific documentation can be found in failures.strategy.

You can type the index of failed cavities on several lines if you want to study several fault scenarios at once.

Example

# Indexes are cavity indexes
idx = cavity
failed = [
   [0, 1],       # First simulation first cryomodule is down
   [0],          # Second simulation only first cavity is down
   [1, 45]       # Third simulation second and 46th cavity are down
]

optimisation.design_space section

This section parametrizes how the design space will be set, i.e. what are the variables, their limits and initial values, and what are the constraints and their limits. If you have any doubt, know that all these settings are passed down to DesignSpaceFactory.__init__() as design_space_kw.

There are two ways to define the design space limits and initial values; the first is to let LightWin calculate it from the nominal settings of the linac. This approach is easier to use for the first runs.

Entry	Type	Description	Allowed values	Mandatory?
from_file	bool	If files should be used	False	✅
design_space_preset	str	What variables/constraints should be used	DESIGN_SPACE_FACTORY_PRESETS	✅
max_increase_sync_phase_in_percent	float	Max relative increase of \(\phi_s\) wrt nominal in \(\mathrm{\%}\)		✅
max_absolute_sync_phase_in_deg	float	Max absolute \(\phi_s\) in \(\mathrm{deg}\)	default 0.	❌
min_absolute_sync_phase_in_deg	float	Min absolute \(\phi_s\) in \(\mathrm{deg}\)	default 90.	❌
max_decrease_k_e_in_percent	float	Max decrease of \(k_e\) wrt nominal in \(\mathrm{\%}\)		✅
max_increase_k_e_in_percent	float	Max increase of \(k_e\) wrt nominal in \(\mathrm{\%}\)		✅
maximum_k_e_is_calculated_wrt_maximum_k_e_of_section	bool	If max \(k_e\) should be the same for the whole section	default False	❌

When from_file is True, you must provide a path to a .csv file containing, for every element, every variable, its initial value and limits. If the problem is constrained, you must also provide a .csv with, for every element, the limits of every constraint. This approach is more useful when you want to fine-tune the optimisation, as you can manually edit the .csv, for example to take into account the specific multipacting barriers of a rogue cavity. To generate the .csv files with the proper format, look at examples/generate_design_space_files.py.

Entry	Type	Description	Allowed values	Mandatory?
from_file	bool	If files should be used	True	✅
design_space_preset	str	What variables/constraints should be used	DESIGN_SPACE_FACTORY_PRESETS	✅
variables_filepath	str	Path to the .csv holding variables		✅
constraints_filepath	str	Path to the .csv holding constraints		❌

Ultimately, these settings will be passed down to DesignSpaceFactory.

evaluators section

This section is used to defined FaultScenarioSimulationOutputEvaluator objects. They are used to evaluate the absolute or relative quality of compensation settings.

Entry	Type	Description	Allowed values	Mandatory?
beam_calc_post	str	Name of the desired evaluators	evaluators	❌

Note

There is also a SimulationOutputEvaluator object that is used internally by LightWin to determine if a Fault was correctly fixed.