Common configuration keys

Below are listed the configuration keys commonly used in the the [wtf] section, independently of the chosen failure-compensation strategy.

Entry	Type	Description	Mandatory?	Allowed values
automatic_study	str or NoneType	Automatically generate the list of failed cavities to avoid manually typing all the cavities identifiers in systematic studies.	❌	(‘single cavity failures’, ‘cryomodule failures’)
failed	list	Identifies list of failed cavities. This is typically a list of list of cavity identifiers (2D), but it can be a 1D list for automatic studies and it must be a 3D array if strategy is set to 'manual'.	✅
history_kwargs	dict	kwargs for the OptimizationHistory.	❌
id_nature	str	Indicates if failed is name of element (s), index of element (s), index of cavities. It can also be the index (es) of one or severalsection (s), or of one or several lattice (s).	✅	(‘cavity’, ‘element’, ‘lattice’, ‘name’, ‘section’)
index_offset	int	Specify whether user-provided cavity indices are 0-based or 1-based. Set 0 if the first cavity has index 0 ( Python-style, default). Set 1 if the first cavity has index 1 (human-friendly). This affects how the failed and compensating_manual lists interpret integer indices.	❌	(0, 1)
objective_preset	str	Objectives for the optimisation algorithm.	✅	(‘CorrectorAtExit’, ‘EnergyMismatch’, ‘EnergyPhaseMismatch’, ‘EnergySeveralMismatches’, ‘EnergySyncPhaseMismatch’, ‘RegularEnvelope’, ‘experimental’, ‘rephased_ADS’, ‘simple_ADS’, ‘sync_phase_as_objective_ADS’)
optimisation_ algorithm	str	Name of optimisation algorithm.	✅	(‘bayesian_optimization’, ‘differential_evolution’, ‘downhill_simplex’, ‘downhill_simplex_penalty’, ‘experimental’, ‘explorator’, ‘least_squares’, ‘least_squares_penalty’, ‘nelder_mead’, ‘nelder_mead_penalty’, ‘NSGA-III’, ‘NSGA-III Multi-threaded’, ‘simulated_annealing’)
optimisation_ algorithm_kwargs	dict	Keyword arguments passed to the optimisation algorithm.	❌
strategy	str	How compensating cavities are selected.	✅	(‘corrector at exit’, ‘global’, ‘global_downstream’, ‘k out of n’, ‘l neighboring lattices’, ‘manual’)

Choice of failed cavities

General case

The failed cavities are selected using the failed keyword. This is typically a 2D list identifying groups of simultaneously failed cavities. Each inner list represents one FaultScenario.

Example

failed = [
   ["FM50"],
   ["FM60", "FM61"],
   ["FM50", "FM60", "FM61"],
]
id_nature = "name"

The above example defines three FaultScenarios:

1. The cavity named FM50 is broken.

2. The cavities FM60 and FM61 are broken.

3. The cavities FM50, FM60 and FM61 are broken.

id_nature controls how cavity identifiers are interpreted (names, cavity indices, element indices…). The above example could also be written:

failed = [
   [49],
   [59, 60],
   [49, 59, 60],
]
id_nature = "cavity"

Note

Indexes start at 0 by default. Hence, a cavity numbered \(i\) by the user corresponds to index i - 1 internally. If you set index_offset = 1, the same cavity will use index i, which may feel more natural for users.

Automatic studies

The automatic_study configuration key saves you the hassle of having to manually type all the cavity names when performing systematic studies. Concretely, it expand failed into all individual FaultScenario used in a systematic study. Two modes are available:

• "single cavity failures": study all single cavity failures in failed.

• "cryomodule failures": study all cryomodule failures.

When automatic_study is set, failed should be a 1D list.

Examples

Study all single failures of the first five lattices:

automatic_study = "single cavity failures"
failed = [0, 1, 2, 3, 4]
id_nature = "lattice"

Study all cryomodule failures in the first three sections:

automatic_study = "cryomodule failures"
failed = [0, 1, 2]
id_nature = "section"

Manual association of failed/compensating cavities

If you want to manually associate each failed cavity to its compensating cavities, failed must be a 3D list:

• first dimension: FaultScenarios

• second dimension: groups of failed cavities (Faults)

• third dimension: cavity identifiers in each group.

See also

The specific documentation for strategy = "manual".

Attribution of compensating cavities to every fault

The association of failed cavities with their compensating cavities is done with the strategy key. The functions that assign compensating cavities to each failed cavity are listed below.

Strategy function	Corresponding keyword
corrector_at_exit()	'corrector at exit'
global_compensation()	'global'
global_downstream()	'global_downstream'
k_out_of_n()	'k out of n'
l_neighboring_lattices()	'l neighboring lattices'
manual()	'manual'

Every strategy requires user to set specific parameters, as listed below.