helper module

Define helper function to ease lists manipulation in strategy.

Note

If you are unsure about how a function works, check out the implementation of the tests in LightWin/tests/test_failure/test_helper.py.

_distance_to_ref(element: T, failed: Sequence, all_elements: Sequence, tie_politics: Literal['upstream first', 'downstream first'], shift: int = 0) → tuple[int, int]

Give distance between element and closest of failed.

Parameters:

  • element (T) – First object from which you want distance. Often, an Element of a lattice that will potentially be used for compensation.

  • failed (Sequence[T]) – Second object or list of object from which you want distance. Often, a list of failed Element or a list of lattices with a fault.

  • all_elements (Sequence[T]) – All the elements/lattices/sections.

  • tie_politics (Literal["upstream first", "downstream first"]) – When two elements have the same position, will you want to have the upstream or the downstream first?

  • shift (int, optional) – 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. The default is 0.

Returns:

  • lowest_distance (int) – Index-distance between element and closest element of failed. Will be used as a primary sorting key.

  • index (int) – Index of element. Will be used as a secondary index key, to sort ties in distance.

_penalty(index: int, failure_index: int, shift: int) → int

Give the distance penalty.

Note

If shift > 0, upstream elements are penalized. If shift < 0, downstream elements are penalized.

sort_by_position(all_elements: Sequence, failed: Sequence, tie_politics: Literal['upstream first', 'downstream first'] = 'upstream first', shift: int = 0) → Sequence

Sort given list by how far its elements are from elements[idx].

We go across every element in all_elements and get their index-distance to the closest element of failed. We sort all_elements by this distance. When there is a tie, we put the more upstream or the more downstream cavity first according to tie_politics.

Parameters:

  • failed (Sequence[T]) – Second object or list of object from which you want distance. Often, a list of failed Element or a list of lattices with a fault.

  • all_elements (Sequence[T]) – All the elements/lattices/sections.

  • tie_politics (Literal["upstream first", "downstream first"]) – When two elements have the same position, will you want to have the upstream or the downstream first?

  • shift (int, optional) – 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. Useful when upstream cavities have more important power margins, or when you want more downstream cavities because a full cryomodule is down. The default is 0.

remove_lists_with_less_than_n_elements(elements: list[Sequence], minimum_size: int = 1) → list[Sequence]

Return a list where objects have a minimum length of minimum_size.

gather(failed_elements: list[T], fun_sort: Callable[[Sequence | Sequence[Sequence]], list[T]]) → tuple[list[list[T]], list[list[T]]]

Gather faults to be fixed together and associated compensating cav.

Parameters:

  • failed_elements (list[T]) – Holds ungathered failed cavities.

  • fun_sort (Callable[[Sequence[T] | Sequence[Sequence[T]]], list[T]]) – Takes in a list or a list of list of failed cavities, returns the list or list of list of altered cavities (failed + compensating).

Returns:

  • failed_gathered (list[list[T]]) – Failures, gathered by faults that require the same compensating cavities.

  • compensating_gathered (list[list[T]]) – Corresponding compensating cavities.

nested_containing_desired(nested: Collection[Sequence], desired_elements: Collection) → list[Sequence]

Return collections of nested containing some desired_elements.

Example

nested_containing_desired(ListOfElements.by_lattice, failed_elements) will return lattices_with_a_failure