Add Set-Like Operations to `ElementArray`

[gupichon]

##Description, motivation and use case

Description

Introduce native set-like operations on ElementArray (and derived array classes) using Python operators:

• & → intersection
• | → union (unique, stable order)
• + → alias of union
• - → difference

Additionally, implement automatic result typing based on the resulting element types.

---

Motivationand use case

In pyAML, array selections are frequently combined to build meaningful subsets of the machine.

For example:

cell1 = sr.live.get_elements("C01")        # ElementArray (mixed types)
sextupoles = sr.live.get_magnets("SEXT")   # MagnetArray

cell1_sext = cell1 & sextupoles

Here:

• cell1 is an ElementArray containing various element types.
• sextupoles is a MagnetArray.
• The intersection keeps only sextupole magnets located in cell 1.
• The result should be automatically typed as a MagnetArray.

Currently, this requires manual filtering logic. Native operator support would make this natural and expressive.

---

Proposed Behavior

Supported Operators

Operator	Meaning	Description
a & b	Intersection	Elements common to both arrays
a | b	Union	Unique elements, stable order
a + b	Union	Alias of |
a - b	Difference	Elements in a but not in b

Equality Semantics

Elements should be compared based on their name (element.get_name()), not instance identity.

This ensures predictable behavior even if elements originate from different instantiations.

---

Auto-Typing of Result

The resulting array should be automatically typed:

• If all remaining elements share the same concrete type, return the corresponding specialized array (e.g., MagnetArray, BPMArray).
• If elements are mixed types, return a generic ElementArray.
• If the result is empty, return an empty list (preserving current internal behavior).

Example:

cell1 = sr.live.get_elements("C01")        # ElementArray
sextupoles = sr.live.get_magnets("SEXT")   # MagnetArray

cell1_sext = cell1 & sextupoles
type(cell1_sext).__name__  # -> "MagnetArray"

---

Peer Consistency

Operations should raise an exception if arrays are attached to different peers (e.g., design vs live).

Example:

design_cell1 & live_cell1  # should raise

---

Benefits

• Makes selection composition expressive and natural
• Reduces boilerplate filtering code
• Encourages a declarative style for machine subsets
• Improves usability for both scripting and notebook workflows

---

Implementation Notes

• Add operator overloads in ElementArray

• Reuse existing internal array factory mechanism for result typing

• Ensure stable order in union

• Add unit tests covering:

  • Intersection
  • Union
  • Difference
  • Mixed types fallback
  • Peer mismatch error

[gupichon]

@GamelinAl I believe this need is still relevant?

[GamelinAl]

Yes, it's still relevant.

In fact, this feature can be used to implement another feature which was described in the user interface specification document, the access via a tuple (cell, number) or a list of tuple (cell, number) like it was done in matlab MML.

Just to recall the pseudo-code we had in the user interface specification document:

import pyaml
sr_ml = pyaml.Pyaml('sr.yaml')
sr = sr_ml.design
sr.quad # print string representation
>> ElementArray('QF.1','QD.2','OCT.1','QF.3','QD.4')
sr.quad[:2] # return an ElementArray with the 1st two elements
>> ElementArray('QF.1','QD.2')
sr.quad[3] # get 3rd element
>> CombinedFunctionMagnet(name='OCT.1', quad_strength=3.4, hardware_name='AN01-AR/EM/OCT.1', control_mode='design')
sr.quad[(False, True, False, True, False)] # using a bool array
>> ElementArray('QD.2','QD.4')
sr.quad((2,2)) # return 2nd quad of 2nd cell using cell_num format
>> Quadrupole(name='QF.4', strength=12.8, hardware_name='AN02-AR/EM/QP.4', control_mode='design')
sr.quad([(1,1),(2,2)]) # using a list of cell_num
>> ElementArray('QF.1','QD.4')

This feature may need another issue when this is implemented but I still described shortly what I have in mind in case it can impact the implementation of this one.

We can have the cells array as (non mandatory) default array defined in the configuration. If the cells array are defined in the config file, then the shortcut notation (cell, number) is available and can simply be implemented as:

sr.quadrupoles # The array which contains all quads in the storage ring
sr.cell2 # The array which contains all elements in cell 2
sr.quadrupoles((2,3)) # returns  (cell2 & quadrupoles)[3] i.e. third element in cell 2 

[gupichon]

The concept of cells is not implemented yet, and it indeed requires a separate issue.
It also requires defining how it should be declared in the configuration files. Other mechanisms will be put in place to achieve what you describe.