Update arrays documentation

Author: JeanLucPons

docs/modules/arrays.rst

@@ -1,11 +1,38 @@
-ARRAYS
+Arrays configuration
 ********
 
 .. automodule:: pyaml.arrays.array
     :members:
+    :exclude-members: model_config
+
+.. automodule:: pyaml.arrays.element
+    :members:
+    :exclude-members: model_config, ConfigModel
+
+.. automodule:: pyaml.arrays.bpm
+    :members:
+    :exclude-members: model_config, ConfigModel
 
 .. automodule:: pyaml.arrays.magnet
     :members:
+    :exclude-members: model_config, ConfigModel
+
+.. automodule:: pyaml.arrays.cfm_magnet
+    :members:
+    :exclude-members: model_config, ConfigModel
+
+
+Arrays usage
+********
+
+.. automodule:: pyaml.arrays.element_array
+    :members:
+
+.. automodule:: pyaml.arrays.bpm_array
+    :members:
 
 .. automodule:: pyaml.arrays.magnet_array
     :members:
+
+.. automodule:: pyaml.arrays.cfm_magnet_array
+    :members:

docs/modules/configuration.rst

@@ -21,9 +21,3 @@ Configuration
 
 .. automodule:: pyaml.configuration.csvmatrix
     :members:
-
-.. automodule:: pyaml.configuration.models
-    :members:
-
-.. automodule:: pyaml.configuration.config_exception
-    :members:

docs/modules/tuning_tools.rst

@@ -1,11 +1,11 @@
 Tuning tools
 ***************
 
-.. automodule:: pyaml.tuning_tools.LOCO.loco
+.. automodule:: pyaml.tuning_tools.tune
     :members:
 
-.. automodule:: pyaml.tuning_tools.SOFB.sofb
+.. automodule:: pyaml.tuning_tools.tune.loco
     :members:
 
-.. automodule:: pyaml.tuning_tools.TUNE.tune
+.. automodule:: pyaml.tuning_tools.SOFB.sofb
     :members:

pyaml/arrays/array.py

@@ -1,5 +1,5 @@
 """
-Magnet array configuration
+Array configuration
 """
 
 from pydantic import BaseModel, ConfigDict
@@ -10,17 +10,26 @@
 
 
 class ArrayConfigModel(BaseModel):
+    """
+    Base class for array confirguration
+
+    Parameters:
+    -----------
+    name: str
+        Family name
+    elements: list[str]
+        List of pyaml element names
+    """
+
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
 
     name: str
-    """Family name"""
     elements: list[str]
-    """List of pyaml element names"""
 
 
 class ArrayConfig(object):
     """
-    Class that implements configuration for access to arrays (families)
+    Base class that implements configuration for access to arrays (families)
     """
 
     def __init__(self, cfg: ArrayConfigModel):

pyaml/arrays/bpm.py

@@ -9,6 +9,20 @@ class ConfigModel(ArrayConfigModel): ...
 
 
 class BPM(ArrayConfig):
+    """
+    BPM array confirguration
+
+    Example
+    -------
+
+    A BPM array configuration can also be created by code using the following example::
+
+        from pyaml.arrays.bpm import BPM,ConfigModel as BPMArrayConfigModel
+        bpmArray = BPM(
+                     BPMArrayConfigModel(name="MyBPMs", elements=["bpm1","bpm2"])
+                   )
+    """
+
     def __init__(self, cfg: ArrayConfigModel):
         super().__init__(cfg)
 

pyaml/arrays/bpm_array.py

@@ -54,23 +54,30 @@ def set_aggregator(self, agg: DeviceAccessList):
 class BPMArray(ElementArray):
     """
     Class that implements access to a BPM array
+
+    Parameters
+    ----------
+    arrayName : str
+        Array name
+    bpms: list[BPM]
+        BPM list, all elements must be attached to the same instance of
+        either a Simulator or a ControlSystem.
+    use_aggregator : bool
+        Use aggregator to increase performance by using paralell
+        access to underlying devices.
+
+    Example
+    -------
+
+    An array can be retrieved from the configuration as in the following example::
+
+        sr = Accelerator.load("acc.yaml")
+        bpms = sr.design.get_bpms("BPMs")
+
+
     """
 
     def __init__(self, arrayName: str, bpms: list[BPM], use_aggregator=True):
-        """
-        Construct a BPM array
-
-        Parameters
-        ----------
-        arrayName : str
-            Array name
-        bpms: list[BPM]
-            BPM list, all elements must be attached to the same instance of
-            either a Simulator or a ControlSystem.
-        use_aggregator : bool
-            Use aggregator to increase performance by using paralell
-            access to underlying devices.
-        """
         super().__init__(arrayName, bpms, use_aggregator)
 
         self.__hvpos = RWBPMPosition(arrayName, bpms)
@@ -86,20 +93,20 @@ def __init__(self, arrayName: str, bpms: list[BPM], use_aggregator=True):
     @property
     def positions(self) -> RWBPMPosition:
         """
-        Give access to bpm posttions of each bpm of this array
+        Returns position of each bpm of this array
         """
         return self.__hvpos
 
     @property
     def h(self) -> RWBPMSinglePosition:
         """
-        Give access to bpm H posttions of each bpm of this array
+        Returns horizontal position of each bpm of this array
         """
         return self.__hpos
 
     @property
     def v(self) -> RWBPMSinglePosition:
         """
-        Give access to bpm V posttions of each bpm of this array
+        Returns vertical position of each bpm of this array
         """
         return self.__vpos

pyaml/arrays/cfm_magnet.py

@@ -9,6 +9,22 @@ class ConfigModel(ArrayConfigModel): ...
 
 
 class CombinedFunctionMagnet(ArrayConfig):
+    """
+    Combined function magnet array confirguration
+
+    Example
+    -------
+
+    A magnet array configuration can also be created by code using
+    the following example::
+
+        from pyaml.arrays.cfm_magnet import CombinedFunctionMagnet
+        from pyaml.arrays.cfm_magnet import ConfigModel as CFMagnetConfigModel
+        magArray = CombinedFunctionMagnet(
+                     CFMagnetConfigModel(name="myCFM", elements=["mag1","mag2"])
+                   )
+    """
+
     def __init__(self, cfg: ArrayConfigModel):
         super().__init__(cfg)
 

pyaml/arrays/cfm_magnet_array.py

@@ -80,7 +80,18 @@ def unit(self) -> list[str]:
 
 class CombinedFunctionMagnetArray(ElementArray):
     """
-    Class that implements access to a magnet array
+    Class that implements access to a combined function magnet array
+
+    Parameters
+    ----------
+    arrayName : str
+        Array name
+    magnets: list[Magnet]
+        Magnet list, all elements must be attached to the same instance of
+        either a Simulator or a ControlSystem.
+    use_aggregator : bool
+        Use aggregator to increase performance by using paralell
+        access to underlying devices.
     """
 
     def __init__(
@@ -89,20 +100,6 @@ def __init__(
         magnets: list[CombinedFunctionMagnet],
         use_aggregator=False,
     ):
-        """
-        Construct a magnet array
-
-        Parameters
-        ----------
-        arrayName : str
-            Array name
-        magnets: list[Magnet]
-            Magnet list, all elements must be attached to the same instance of
-            either a Simulator or a ControlSystem.
-        use_aggregator : bool
-            Use aggregator to increase performance by using paralell
-            access to underlying devices.
-        """
         super().__init__(arrayName, magnets, use_aggregator)
 
         self.__rwstrengths = RWMagnetStrengths(arrayName, magnets)

pyaml/arrays/element.py

@@ -9,6 +9,23 @@ class ConfigModel(ArrayConfigModel): ...
 
 
 class Element(ArrayConfig):
+    """
+    Element array confirguration
+
+    Example
+    -------
+
+    An element array configuration can also be created by code using
+    the following example::
+
+        from pyaml.arrays.element import Element,ConfigModel as ElementArrayConfigModel
+        elemArray = Element(
+                      ElementArrayConfigModel(name="MyArray", elements=["elt1","elt2"])
+                    )
+
+
+    """
+
     def __init__(self, cfg: ArrayConfigModel):
         super().__init__(cfg)
 

pyaml/arrays/element_array.py

@@ -10,24 +10,30 @@
 
 class ElementArray(list[Element]):
     """
-    Class that implements access to a element array
+    Class that implements access to an element array
+
+    Parameters
+    ----------
+    arrayName : str
+        Array name
+    elements: list[Element]
+        Element list, all elements must be attached to the same instance of
+        either a Simulator or a ControlSystem.
+    use_aggregator : bool
+        Use aggregator to increase performance by using paralell
+        access to underlying devices.
+
+    Example
+    -------
+
+    An array can be retrieved from the configuration as in the following example::
+
+        sr = Accelerator.load("acc.yaml")
+        elts = sr.design.get_elemens("QuadForTune")
+
     """
 
     def __init__(self, arrayName: str, elements: list[Element], use_aggregator=True):
-        """
-        Construct an element array
-
-        Parameters
-        ----------
-        arrayName : str
-            Array name
-        elements: list[Element]
-            Element list, all elements must be attached to the same instance of
-            either a Simulator or a ControlSystem.
-        use_aggregator : bool
-            Use aggregator to increase performance by using paralell
-            access to underlying devices.
-        """
         super().__init__(i for i in elements)
         self.__name = arrayName
         if len(elements) > 0:
@@ -47,9 +53,15 @@ def get_peer(self):
         return self.__peer
 
     def get_name(self) -> str:
+        """
+        Returns the array name
+        """
         return self.__name
 
     def names(self) -> list[str]:
+        """
+        Returns the element names
+        """
         return [e.get_name() for e in self]
 
     def __create_array(self, arrName: str, eltType: type, elements: list):