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, failed, all_elements, tie_politics, shift=0)[source]

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.

Return type:

tuple[int, int]

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, failure_index, shift)[source]

Give the distance penalty.

Note

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

Parameters:

  • index (int)

  • failure_index (int)

  • shift (int)

Return type:

int

sort_by_position(all_elements, failed, tie_politics='upstream first', shift=0)[source]

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.

Return type:

Sequence[TypeVar(T)]

remove_lists_with_less_than_n_elements(elements, minimum_size=1)[source]

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

Parameters:
Return type:

list[Sequence[TypeVar(T)]]

gather(failed_elements, fun_sort)[source]

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).

Return type:

tuple[list[list[TypeVar(T)]], list[list[TypeVar(T)]]]

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, desired_elements)[source]

Return collections of nested containing some desired_elements.

Example

nested_containing_desired(ListOfElements.by_lattice, failed_elements) will return lattices_with_a_failure

Parameters:
Return type:

list[Sequence[TypeVar(T)]]