wtf section

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

Selecting compensating cavities

k out of n method

Compensate the \(n\) failed cavities with \(k\times n\) closest cavities [SPK21, YRKT+22].

Entry	Type	Description	Mandatory?	Allowed values
failed	list	Index/name of failed cavities. Must be a list[list[int]] or list[list[str]].	✅
history_kwargs	dict	kwargs for the OptimizationHistory.	❌
id_nature	str	Indicates if failed is element index/cavity index/name, element or cavity or name.	✅	(‘element’, ‘cavity’, ‘name’)
objective_preset	str	Objectives for the optimisation algorithm.	✅	(‘EnergyMismatch’, ‘EnergyPhaseMismatch’, ‘EnergySeveralMismatches’, ‘EnergySyncPhaseMismatch’, ‘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’, ‘simulated_annealing’)
optimisation_ algorithm_kwargs	dict	Keyword arguments passed to the optimisation algorithm.	❌
strategy	str	How compensating cavities are selected.	✅	(‘k out of n’, ‘l neighboring lattices’, ‘global’, ‘global_downstream’, ‘manual’)
tie_politics	str	How to select the compensating elements when several are equidistant to the failure.	❌	(‘upstream first’, ‘downstream first’)
shift	int	Distance increase for downstream elements (shift < 0) or upstream elements (shift > 0). Used to have a window of compensating cavities which is not centered around the failed elements.	❌
k	int	Number of compensating cavities per failed cavity.	✅

l neighboring lattices method

Every fault will be compensated by l full lattices, direct neighbors of the errors [BBU14, PB22]. You must provide l. Non-failed cavities in the same lattice as the failure are also used.

Entry	Type	Description	Mandatory?	Allowed values
failed	list	Index/name of failed cavities. Must be a list[list[int]] or list[list[str]].	✅
history_kwargs	dict	kwargs for the OptimizationHistory.	❌
id_nature	str	Indicates if failed is element index/cavity index/name, element or cavity or name.	✅	(‘element’, ‘cavity’, ‘name’)
objective_preset	str	Objectives for the optimisation algorithm.	✅	(‘EnergyMismatch’, ‘EnergyPhaseMismatch’, ‘EnergySeveralMismatches’, ‘EnergySyncPhaseMismatch’, ‘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’, ‘simulated_annealing’)
optimisation_ algorithm_kwargs	dict	Keyword arguments passed to the optimisation algorithm.	❌
strategy	str	How compensating cavities are selected.	✅	(‘k out of n’, ‘l neighboring lattices’, ‘global’, ‘global_downstream’, ‘manual’)
tie_politics	str	How to select the compensating elements when several are equidistant to the failure.	❌	(‘upstream first’, ‘downstream first’)
shift	int	Distance increase for downstream elements (shift < 0) or upstream elements (shift > 0). Used to have a window of compensating cavities which is not centered around the failed elements.	❌
l	int	Number of compensating lattices per failed cavity.	✅
min_number_of_ cavities_in_lattice	int	Minimum number of compensating cavities in the lattice; when a lattice does not reach this number, we use it anyway for compensation, but we also take another lattice. Designed to remove the lattices that do not have any cavity.	❌

Manual association of failed / compensating cavities

If you want to manually associate each failed cavity with its compensating cavities:

Entry	Type	Description	Mandatory?	Allowed values
failed	list	Index/name of failed cavities. Must be a list[list[int]] or list[list[str]].	✅
history_kwargs	dict	kwargs for the OptimizationHistory.	❌
id_nature	str	Indicates if failed is element index/cavity index/name, element or cavity or name.	✅	(‘element’, ‘cavity’, ‘name’)
objective_preset	str	Objectives for the optimisation algorithm.	✅	(‘EnergyMismatch’, ‘EnergyPhaseMismatch’, ‘EnergySeveralMismatches’, ‘EnergySyncPhaseMismatch’, ‘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’, ‘simulated_annealing’)
optimisation_ algorithm_kwargs	dict	Keyword arguments passed to the optimisation algorithm.	❌
strategy	str	How compensating cavities are selected.	✅	(‘k out of n’, ‘l neighboring lattices’, ‘global’, ‘global_downstream’, ‘manual’)
failed	list	Index/name of failed cavities. Must be a list[list[list[int]]] or list[list[list[str]]].	✅
compensating_manual	list	Index/name of compensating cavities cavities. Must be a list[list[list[int]]] or list[list[list[str]]]. The number of:class:.FaultScenarios ( length of most outer list) must match failed. The number of groups of compensating cavities (second level) must match failed.	✅

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
]

Settings optimization problem

Optimisation objectives

The values for objective_preset are explained here:

Objectives preset	Corresponding keys
EnergyMismatch	'EnergyMismatch', 'rephased_ADS'
EnergyPhaseMismatch	'EnergyPhaseMismatch', 'simple_ADS'
EnergySeveralMismatches	'EnergySeveralMismatches'
EnergySyncPhaseMismatch	'EnergySyncPhaseMismatch', 'sync_phase_as_objective_ADS'
Spiral2	'experimental'

If you do not retrieve the beam absolute phase at the exit of the compensation zone (eg, if you use EnergyMismatch), you should probably rephase downstream cavities to keep RF/beam synchronicity. This is acheived by setting your beam_calculator.reference_phase_policy key to "phi_0_rel" or "phi_0_s". See also this notebook.

Note

You can subclass ObjectiveFactory to your liking, and pass the created object to run_simulation() directly.

config = process_config(toml_filepath, toml_keys)
fault_scenarios = run_simulation(
    config,
    objective_factory_class=MyObjectiveFactory,  # subclass of ObjectiveFactory
)

An example is provided in data/example/my_own_objectives.py.

Todo

Make it more explicit and easy to understand with a jupyter notebook.

Optimisation algorithms

Here are mappings of optimisation_algorithm key to actual OptimisationAlgorithm. Check the documentation of the optimisation algorithm you want to use, in particular if you want to tune it using optimisation_algorithm_kwargs key.

Optimisation algorithm	Corresponding keys
BayesianOptimizationLW	'bayesian_optimization', 'experimental'
DifferentialEvolution	'differential_evolution'
DownhillSimplex	'downhill_simplex', 'nelder_mead'
DownhillSimplexPenalty	'downhill_simplex_penalty', 'nelder_mead_penalty'
Explorator	'explorator'
LeastSquares	'least_squares'
LeastSquaresPenalty	'least_squares_penalty'
NSGA	'nsga'
SimulatedAnnealing	'simulated_annealing'