feat: add generic ElementHolder collection access

[gupichon]

• Return an element or None for exact-name lookups
• Support typed wildcard selections, slices and insertion-order indexing
• Add get() and [:] access to all registered elements
• Reuse array type inference for selections
• Document the API with NumPy docstrings and readable test examples

[GamelinAl]

I tried to look a bit a the code a did some tests. Here is what I found:

1. The __repr__ needs to be fixed, right now it does not output the name and output the full lattice

Not linked to this MR, but it makes things difficult.

main: Simulator(name='design', lattice='sr/lattices/ebs.mat', mat_key=None, linker=None, description=None)
now:  Simulator(ring=Lattice([...thousands of elements...]), description=None, lattice='...', mat_key=None)

2. Looking up a wrong name gives None istead of an error:

quad = sr.design["blabla"]
quad?
>>> Type:        NoneType
String form: None
Docstring:   <no docstring>

3. get methods () return list an not arrays:
   For example:

type(sr.design.get_all_elements())
>>> list

The same is true for other get_XXXs methods.
But maybe this needs to go now because we can use sr.design[:], I would think it's better to have one way to do this.

4. magnets[:] and magnets["QD"] works but return ElementArray instead of MagnetArray

type(sr.design.magnets[":"])
>>> pyaml.arrays.element_array.ElementArray

5. Similar bug with using subset of magnet arrays

magnets.get()        -> MagnetArray     ✅
magnets.get()[:]     -> ElementArray    ❌ should be MagnetArray
magnets.get()['S*']  -> ElementArray    ❌ should be MagnetArray

6. The ElementHolder.get method has changed and take no argument

cell1 = sr.design.get("Cell1")
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[24], line 1
----> 1 cell1 = sr.design.get("Cell1")

TypeError: ElementHolder.get() takes 1 positional argument but 2 were given

So I don't know how to access an user defined array

---

Probably some of the tests should use mixed type arrays to catch this type of bugs.

[JeanLucPons]

Point 1 2 3 6 are normal, it is a work in progress not already done as mentioned in the initial issue.
4 and 5 are clear bugs (or there are unexpeted elements in arrays)...

[gupichon]

I'm not sure why the documentation pipeline is failing. I suspect it's related to the release build on Read the Docs.

[gupichon]

Point 1 2 3 6 are normal, it is a work in progress not already done as mentioned in the initial issue. 4 and 5 are clear bugs (or there are unexpeted elements in arrays)...

Yes, I will open a separate issue for the element array type inference.

[gupichon]

Point 1 2 3 6 are normal, it is a work in progress not already done as mentioned in the initial issue. 4 and 5 are clear bugs (or there are unexpeted elements in arrays)...

Regarding point 2: should we raise an error if an unknown value is passed for direct access?
When using an fnmatch pattern, an empty array is returned. To stay consistent, I chose to return None for direct access, but I can raise an exception instead if you prefer. @JeanLucPons @GamelinAl

[gupichon]

4. magnets[:] and magnets["Q_D_"] works but return ElementArray instead of MagnetArray

type(sr.design.magnets[":"])
>>> pyaml.arrays.element_array.ElementArray

Because of the quotes here, you're looking for an element named ":", which results in an empty, generic array. The correct syntax is type(sr.design.magnets[:]), but as @JeanLucPons mentioned, this doesn't work yet.

[GamelinAl]

Point 1 2 3 6 are normal, it is a work in progress not already done as mentioned in the initial issue. 4 and 5 are clear bugs (or there are unexpeted elements in arrays)...

Regarding point 2: should we raise an error if an unknown value is passed for direct access? When using an fnmatch pattern, an empty array is returned. To stay consistent, I chose to return None for direct access, but I can raise an exception instead if you prefer. @JeanLucPons @GamelinAl

I would say it's better to raise an error.

[gupichon]

I would say it's better to raise an error.

Ok, I would like to do this in a future issue to also update ElementArray accordingly.