Simplify ElementHolder API: one accessor per element family (merge magnet/magnets, bpm/bpms, …) #468

Here is my proposal to simplify further the API to access elements after #430
@JeanLucPons @TeresiaOlsson @gupichon-soleil @gubaidulinvadim @kparasch

Context

Follow-up of #430 / #199. After #430 every element family has two accessors:

Before #430 the split made sense: the singular accessor looked up one element and the plural one looked up families. Since #430, the plural accessor can do almost everything the singular one does, so having both is redundant. It is also confusing: users have to remember singular vs plural, and some first thought one of them was a typo.
Results are also inconsistent:

sr.design["QF1E-C04"]          # Quadrupole
sr.design.magnet["QF1E-C04"]   # Quadrupole
sr.design.magnets["QF1E-C04"]  # MagnetArray with 1 element

Proposal

Keep one accessor per family, named after the type, in the singular: magnet, combined_function_magnet,
serialized_magnet, diagnostic.bpm. Remove the plural ones.

The accessor has a small, explicit set of methods. The method you call decides what comes back, not whether
the name is singular or plural:

m   = sr.design.magnet.get("QF1E-C04")          # -> Magnet: exactly one element, raises if unknown
fam = sr.design.magnet.get_array("QuadForTune") # -> MagnetArray: configured family, raises if unknown
fam = sr.design.magnet.QuadForTune              # -> MagnetArray: same, attribute + tab completion
all = sr.design.magnet.get_array()              # -> MagnetArray of every magnet (replaces .all())

sr.design.magnet["QF1E-C04"]                    # -> Magnet  (literal name, same as sr.design[...])
sr.design.magnet["QF1*"]                        # -> MagnetArray (wildcard / re: / list / ~)

Rules:

1. get(name) always returns one element, and get_array(name) / attribute access always return a configured array. This is the way we access element/arrays in pyAML code internally. Each has one precise return type, so static typing and IDE autocompletion stay accurate (this answers
   @JeanLucPons's concern about generic signatures).

2. [key] is the interactive shortcut: a literal name gives the element, a pattern gives a typed array. One rule everywhere.

3. Element names and family names live in separate namespaces (get/[] for elements, get_array/attribute for families), so they never clash.

4. The same get / get_array convention applies at the root of the holder. Today sr.design.get(name) returns an array (ElementHolder.get), while rf.get(name), tool.get(name) and diagnostic.get(name) already return a single element. The root is the odd one out, so we align it:

   sr.design.get("QF1E-C04")       # -> Element: exactly one element, raises if unknown
   sr.design.get_array("CELL08")   # -> ElementArray (or the most specific array type) by array name
   sr.design.get_array()           # -> ElementArray of every element (today: sr.design.get())

After this, get means "one element" and get_array means "an array" everywhere in the API.

The alternative proposal is to just use ["key"] for everything but I think the concern of @JeanLucPons are justified. At least internally, in the pyAML codebase, it's very good to have exact ways to get element/array separated.

Same problem one level down: strength vs strengths

The value accessors have the same singular/plural problem, and the plural is not used consistently:

A single CFM uses the plural but a serialized group uses the singular, and offset is singular but positions
is plural.

Proposal: use the same attribute name on an element and on an array. Whether get() returns a scalar or a vector depends on the object, not on the attribute name:

sr.design.magnet["QF1E-C04"].strength.get()  # scalar
sr.design.magnet["QF1*"].strength.get()      # vector, same attribute name

I think that what is done on the Element/Array level is enough to have a clear difference.

• BPMArray gains offset / tilt and BPM gains h / v, so the same code works on one BPM or on an array.

Implementation

These two topics can be covered in two sub-issues and their related PR.

We could merge GenericElementHolder and GenericArrayHolder (pyaml/common/holders/) into a single GenericHolder, and merge each XHolder/XsHolder pair in sub_holders.py into one class. Then update the internal callers (tuning tools: peer.magnets.get(...) → peer.magnet.get_array(...)), the tests, the examples/notebooks and the docs.
At the root, ElementHolder.get(name) returns self._get_element(name), and _get_array becomes the public get_array(name=None).