strategy module

Define the function related to the strategy key of wtf.

In particular, it answers the question: Given this set of faults, which compensating cavities will be used?

Note

In order to add a compensation strategy, you must add it to the STRATEGIES_MAPPING dict.

failed_and_compensating(elts, failed, id_nature, strategy, compensating_manual=None, **wtf)[source]

Determine the compensating cavities for every failure.

Parameters:

elts (ListOfElements) – Contains the failed linac.
failed (Sequence[int] | list[str] | Sequence[Sequence[int]] | list[list[str]]) – Identify the failed cavities.
id_nature (Literal['cavity', 'element', 'lattice', 'name', 'section']) – Nature of information stored in failed.
strategy (Literal['corrector at exit', 'global downstream', 'global', 'k out of n', 'l neighboring lattices', 'manual']) – Compensation strategy.
compensating_gathered – Associates every group of failed cavities in failed with a group of compensating cavities; both must hold a list of list of cavity identifier.
wtf (Any) – Other keyword arguments passed to the actual strategy function.
compensating_manual (Sequence[Sequence[int]] | list[list[str]] | None, default: None)

Return type:

tuple[list[list[FieldMap]], list[list[FieldMap]]]

Returns:

failed_gathered – Failed cavities; cavities that will be compensated together are gathered.
compensating_gathered – Same size as failed_gathered. Associates every group of failed cavities to a group of compensating cavities.

k_out_of_n(elements, failed_elements, *, k, tie_politics='upstream first', shift=0, remove_failed=False, **kwargs)[source]

Return k compensating cavities per failed in elts_of_interest.

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

Note

T can represent a Element, or a list of Element. Returned type/data structure will be the same as what was given in arguments. This function is hereby also used by l_neighboring_lattices() which gives in lattices.

Parameters:

elements (Sequence[TypeVar(T)]) – All the tunable elements/lattices/sections.
failed_elements (Sequence[TypeVar(T)]) – Failed cavities/lattice.
k (int) – Number of compensating cavity per failure.
tie_politics (Literal['upstream first', 'downstream first'], default: 'upstream first') – When two elements have the same position, will you want to have the upstream or the downstream first?
shift (int, default: 0) – 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.
remove_failed (bool, default: False)

Return type:

list[TypeVar(T)]

Returns:

Contains all the altered elements/lattices. The \(n\) first are failed, the \(k \times n\) following are compensating.

l_neighboring_lattices(elements_gathered_by_lattice, failed_elements, *, l, tie_politics='upstream first', shift=0, remove_failed=False, min_number_of_cavities_in_lattice=1, **kwargs)[source]

Select full lattices neighboring the failed cavities.

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.

Parameters:

elements_by_lattice – Tunable elements sorted by lattice.
failed_elements (Sequence[TypeVar(T)]) – Failed cavities/lattice.
l (int) – Number of compensating lattice per failure.
tie_politics (Literal['upstream first', 'downstream first'], default: 'upstream first') – When two elements have the same position, will you want to have the upstream or the downstream first?
shift (int, default: 0) – 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.
remove_failed (bool, default: False) – To remove the failed lattices from the output.
min_number_of_cavities_in_lattice (int, default: 1) – If a lattice has less than this number of functional cavities, we look for another lattice. This is designed to removed lattices which have no cavities. Note that lattices that have some functional cavities but not enough will be used for compensation anyway.
elements_gathered_by_lattice (Sequence[Sequence[TypeVar(T)]])

Return type:

list[TypeVar(T)]

Returns:

Contains all the altered cavities.

manual(failed_cavities, compensating_cavities)[source]

Associate failed with compensating cavities.

Parameters:

failed_cavities (Sequence[list[FieldMap]])
compensating_cavities (list[list[FieldMap]] | Any)

Return type:

tuple[list[list[FieldMap]], list[list[FieldMap]]]

global_compensation(elements, failed_elements, *, remove_failed=False, **kwargs)[source]

Give all the cavities of the linac.

Parameters:

elements (Sequence[TypeVar(T)]) – All the tunable elements.
failed_elements (Sequence[TypeVar(T)]) – Failed cavities.
remove_failed (bool, default: False)

Return type:

list[TypeVar(T)]

Returns:

Contains all the altered elements.

global_downstream(elements, failed_elements, *, remove_failed=False, **kwargs)[source]

Give all the cavities of the linac after the first failed cavity.

Parameters:

elements (Sequence[TypeVar(T)]) – All tunable the elements.
failed_elements (Sequence[TypeVar(T)]) – Failed cavities.
remove_failed (bool, default: False)

Return type:

list[TypeVar(T)]

Returns:

Contains all the altered elements.

corrector_at_exit(elements, failed_elements, *, n_compensating, n_correctors, tie_politics='downstream first', shift=0, remove_failed=False, include_correctors=False, **kwargs)[source]

Return k out of n cavities, plus additional cavities at exit.

The idea behind this strategy is the following:

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.
- reference_phase_policy = "phi_s" is the best choice to preserve longitudinal acceptance along the linac.
Give an ultimate energy boost to the beam with the last n_correctors cavities.
- The ObjectiveFactory must set different objectives at the linac exit than at the compensation zone(s) exit.

This method is inspired by Shishlo and Peters who tested it on SNS superconducting linac [SP22]; they used n_compensating = 0, which is currently not supported by LightWin. It also showed very promising results on the SPIRAL2 superconducting linac [PBDK+24].

Parameters:

elements (Sequence[int] | list[str]) – All the tunable elements/lattices/sections.
failed_elements (Sequence[int] | list[str]) – Failed cavities/lattice.
n_compensating (int) – Number of compensating cavity per failure; this is the k of the k out of n method.
n_correctors (int) – Number of corrector cavities at the exit of the linac.
tie_politics (Literal['upstream first', 'downstream first'], default: 'downstream first') – When two elements have the same position, will you want to have the upstream or the downstream first?
shift (int, default: 0) – 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.
include_correctors (bool, default: False) – If corrector cavities should be included in returned list. If this function is called within gather(), set it to False. As all failed cavities of the linac would require these compensating cavities, it would mess up with the failures gathering. Current workaround is to add correctors manually after the gather() call, in failed_and_compensating().
remove_failed (bool)

Return type:

Sequence[int] | list[str]

Returns:

Contains all the altered elements. The \(n\) first are failed, the \(n_\mathrm{compensating} \times n\) following are compensating, the last \(n_\mathrm{correctors}\) are correctors.