design_space section

This section parametrizes how the design space will be defined:

• which variables are included,

• their limits and initial values,

• which constraints apply,

• and the limits of those constraints.

All these settings are passed down to DesignSpaceFactory.__init__() as design_space_kw.

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

Entry	Type	Description	Mandatory?	Allowed values
design_space_preset	str	What are the variables and constraints.	✅	(‘AbsPhaseAmplitude’, ‘AbsPhaseAmplitudeWithConstrainedSyncPhase’, ‘Everything’, ‘RelPhaseAmplitude’, ‘RelPhaseAmplitudeWithConstrainedSyncPhase’, ‘SyncPhaseAmplitude’, ‘UserDefined’, ‘abs_phase_amplitude’, ‘abs_phase_amplitude_with_constrained_sync_phase’, ‘everything’, ‘rel_phase_amplitude’, ‘rel_phase_amplitude_with_constrained_sync_phase’, ‘sync_phase_amplitude’, ‘user_defined’, ‘unconstrained’, ‘unconstrained_rel’, ‘constrained_sync_phase’, ‘sync_phase_as_variable’)
variable_names	list or tuple	What to use as variables if `` design_space_preset `` is set to `` “UserDefined” ``. In this case, this key is mandatory.	❌
constraint_names	list or tuple	What to use as constraints if `` design_space_preset `` is set to `` “UserDefined” ``.	❌
from_file	bool	If variable limits/constraints should be taken from a file.	✅
max_increase_sync_ phase_in_percent	float	Max relative increase of:math:phi_s wrt nominal in:unit:\%	✅
max_absolute_sync_ phase_in_deg	float	Max absolute:math:phi_s in:unit:deg	❌
min_absolute_sync_ phase_in_deg	float	Min absolute:math:phi_s in:unit:deg	❌
max_decrease_k_e_in_ percent	float	Max decrease of:math:k_e wrt nominal in:unit:\%	✅
max_increase_k_e_in_ percent	float	Max increase of:math:k_e wrt nominal in:unit:\%	✅
maximum_k_e_is_ calculated_wrt_ maximum_k_e_of_ section	bool	If max:math:k_e should be the same for all the cavities of the section	❌

Important

The design space defines which variables the optimizer explores. If your design_space_preset key is set to, for example, "abs_phase_amplitude", the optimization variables are the amplitude \(k_e\) and the absolute phase \(\phi_{0,\,\mathrm{abs}}\) of each compensating cavity. Consequently, the synchronous phase is not part of the variable set, and the following parameters will have no effect:

• max_absolute_sync_phase_in_deg

• min_absolute_sync_phase_in_deg

• max_increase_sync_phase_in_percent

To take these parameters into account, you should use the preset "sync_phase_amplitude". Please note that this option increases computation time, since LightWin must determine the physical phase \(\phi_0\) corresponding to the target synchronous phase \(\phi_s\). This value changes whenever the field amplitude or the beam energy at the cavity entrance changes.

When from_file is True, you must provide a path to a CSV file containing, for every element:

• the variables name as header,

• its initial value,

• and its limits.

If the problem is constrained, you must also provide a CSV file with, for every element, the limits of each constraint. This approach is useful when you want to fine-tune the optimisation, as you can manually edit the CSV – for example, to account for multipacting barriers in a problematic cavity.

To generate CSV files with the proper format, see examples/generate_design_space_files.py. You can also re-use following files in data/example:

• variables.csv

• variables_centered_around_solution.csv

• constraints.csv

Entry	Type	Description	Mandatory?	Allowed values
design_space_preset	str	What are the variables and constraints.	✅	(‘AbsPhaseAmplitude’, ‘AbsPhaseAmplitudeWithConstrainedSyncPhase’, ‘Everything’, ‘RelPhaseAmplitude’, ‘RelPhaseAmplitudeWithConstrainedSyncPhase’, ‘SyncPhaseAmplitude’, ‘UserDefined’, ‘abs_phase_amplitude’, ‘abs_phase_amplitude_with_constrained_sync_phase’, ‘everything’, ‘rel_phase_amplitude’, ‘rel_phase_amplitude_with_constrained_sync_phase’, ‘sync_phase_amplitude’, ‘user_defined’, ‘unconstrained’, ‘unconstrained_rel’, ‘constrained_sync_phase’, ‘sync_phase_as_variable’)
variable_names	list or tuple	What to use as variables if `` design_space_preset `` is set to `` “UserDefined” ``. In this case, this key is mandatory.	❌
constraint_names	list or tuple	What to use as constraints if `` design_space_preset `` is set to `` “UserDefined” ``.	❌
from_file	bool	If variable limits/constraints should be taken from a file.	✅
constraints_filepath	str or Path	Path to the CSV holding constraints. Mandatory if from_file is True.	❌
variables_filepath	str or Path	Path to the CSV holding variables. Mandatory if from_file is True.	✅

Under implementation

The design_space_preset = UserDefined will allow you to directly define variables and constraints from the TOML.

design_space_preset =  "UserDefined"
variable_names = ["phi_0_rel", "k_e"]
constraint_names = ["phi_s"]

List of allowed variables are listed in VARIABLES. List of allowed constraints are in CONSTRAINTS. As for now, the limits and initial values are set in the same way as before: from a file or using the max_absolute_sync_phase_in_deg etc keywords. I am still thinking on how to let user easily choose any variable, constraint, limits, etc.