wtf section

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

Selecting compensating cavities

Compensating cavities are selected according to the strategy keyword; actual functions mapping failures with failed cavities are listed here:

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.

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.	✅	(‘CorrectorAtExit’, ‘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’, ‘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’)
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.	✅	(‘CorrectorAtExit’, ‘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’, ‘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’)
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.	❌

Corrector at exit method

Use n_compensating cavities around the failure to shape the beam and propagate it without losses. Rephase downstream cavities to keep the beam as intact as possible. Give an ultimate energy boost to the beam with the last n_correctors cavities.

This method is very similar to the one used at SNS [SP22]. In this paper however, there are no compensating cavities around the failure.

Important

This method was designed to to work with:

1. reference_phase_policy = "phi_s". This way, cavities downstream of a failure are rephased to preserve synchronous phase and hence acceptance.

2. strategy = "corrector at exit". This tells the failed_and_compensating() called at initialization of FaultScenario to add n_correctors cavities at the end of the linac to retrieve energy.

LightWin will not verify that these keys are properly set.

Todo

Automatically check validity of reference_phase_policy and consistency of strategy/objective_preset.

Warning

Setting n_compensating = 0 in the [wtf] section of the TOML configuration file will raise an error, as LightWin currently does not handle optimization problem without compensating elements.

Todo

Handle optimization problems without compensating cavities. - Skip creation of associated Fault? - Other solution?

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.	✅	(‘CorrectorAtExit’, ‘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’, ‘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’)
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.	❌
n_compensating	int	Number of compensating cavities around every failure. They are used to shape the beam without retrieving nominal energy, so that it can propagate up to the `` correctors `` without losses. Currently, you must set at least 1 compensating cavity to avoid errors.	✅
n_correctors	int	Number of compensating cavities at the exit of the linac. They are used to retrieve nominal energy. Not affected by the `` shift `` keyword.	✅

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.	✅	(‘CorrectorAtExit’, ‘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’, ‘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’)
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
]

Global, global downstream compensation

Use either all cavities of the linac, or all cavities downstream of the failure. These methods require a very large number of compensating cavities and therefore significant numerical resources. As a result, they are only lightly tested.

Settings optimization problem

Optimisation objectives

The values for objective_preset are explained here:

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

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'
SimulatedAnnealing	'simulated_annealing'