rename tree -> children and sequence -> arangement (#96)

Author: felix-andreas

apace/classes.py

@@ -242,53 +242,53 @@ class Lattice(Base):
     """Defines the order of elements in the accelerator.
 
     :param str name: Name of the lattice.
-    :param tree: Nested tree of elements and lattices.
-    :type tree: Tuple[Union[Element, Lattice]]
+    :param children: List of elements and sub-lattices.
+    :type children: List[Union[Element, Lattice]]
     :param str info: Additional information about the lattice.
     """
 
-    def __init__(self, name, tree, info=""):
+    def __init__(self, name, children, info=""):
         super().__init__(name, length=0, info=info)
         self._length_needs_update = True
         self.length_changed: Signal = Signal()
         """Gets emitted when the length of lattice changes."""
         self.length_changed.connect(self._on_length_changed)
 
-        self._tree = tree
-        for obj in set(tree):
+        self._children = children
+        for obj in set(children):
             obj.parent_lattices.add(self)
 
         self._objects = {}
         self._elements = set()
         self._sub_lattices = set()
-        self._arrangement = []
+        self._sequence = []
         self._indices = {}
-        self._init_tree_properties()
+        self._init_properties()
 
         self.element_changed: Signal = Signal()
         """Gets emitted when an attribute of an element within this lattice changes."""
         self.element_changed.connect(self._on_element_changed)
 
-        self.n_elements = len(self.arrangement)
+        self.n_elements = len(self.sequence)
         """The number of elements within this lattice."""
 
     @staticmethod
-    def traverse_tree(tree) -> Iterator[Base]:
-        "Returns iterator which traverses all nodes of the lattice tree."
-        for obj in tree:
+    def traverse_children(children) -> Iterator[Base]:
+        "Returns iterator which traverses all children of a lattice."
+        for obj in children:
             yield obj
             if isinstance(obj, Lattice):
-                yield from Lattice.traverse_tree(obj.tree)
+                yield from Lattice.traverse_children(obj.children)
 
-    def _init_tree_properties(self):
-        """A recursive helper function to initialize the tree properties."""
-        arrangement = self._arrangement
+    def _init_properties(self):
+        """A recursive helper function to initialize the properties."""
+        sequence = self._sequence
         indices = self._indices
         elements = self._elements
         sub_lattices = self._sub_lattices
         objects = self._objects
         index = 0
-        for obj in Lattice.traverse_tree(self.tree):
+        for obj in Lattice.traverse_children(self.children):
             value = objects.get(obj.name)
             if value is None:
                 objects[obj.name] = obj
@@ -303,20 +303,20 @@ def _init_tree_properties(self):
             if isinstance(obj, Lattice):
                 sub_lattices.add(obj)
             else:
-                arrangement.append(obj)
+                sequence.append(obj)
                 elements.add(obj)
                 index += 1
 
     def __getitem__(self, key):
         if isinstance(key, str):
             return self._objects[key]
         elif isinstance(key, (int, slice)):
-            return self.arrangement[key]
+            return self.sequence[key]
         elif isinstance(key, Base):
             return self.indices[Base]
 
     def __del__(self):
-        for obj in self.tree:
+        for obj in self.children:
             obj.parent_lattices.discard(self)
 
     @property
@@ -330,7 +330,7 @@ def update_length(self):
         """Manually update the Length of the lattice (m)."""
         # TODO: can numpy be used to avoid rounding errors?
         #       sum = (a + b) + (c + d)
-        self._length = sum(obj.length for obj in self.tree)
+        self._length = sum(obj.length for obj in self.children)
         self._length_needs_update = False
 
     def _on_length_changed(self):
@@ -346,19 +346,19 @@ def _on_element_changed(self, element, attribute):
             lattice.element_changed(element, attribute)
 
     @property
-    def tree(self) -> List[Base]:
-        """List of elements and sub-lattices in physical order."""
-        return self._tree
+    def children(self) -> List[Base]:
+        """List of direct children (elements or sub-lattices) in physical order."""
+        return self._children
 
     @property
-    def arrangement(self) -> List[Element]:
-        """List of elements in physical order. (Flattend :attr:`tree`)"""
-        return self._arrangement
+    def sequence(self) -> List[Element]:
+        """List of elements in physical order. (Flattend :attr:`children`)"""
+        return self._sequence
 
     @property
     def indices(self) -> Dict[Element, List[float]]:
         """A dict which contains the a `List` of indices for each element.
-        Can be thought of as inverse of arrangement. Sub-lattices are associated with
+        Can be thought of as inverse of sequence. Sub-lattices are associated with
         the list of indices of their first element."""
         return self._indices
 
@@ -385,7 +385,7 @@ def print_tree(self):
     def _print_tree(obj, prefix=""):
         string = f"{obj.name}\n"
         if isinstance(obj, Lattice):
-            *others, last = obj.tree
+            *others, last = obj.children
             for child in others:
                 string += f"{prefix}├─── {Lattice._print_tree(child, prefix + '│   ')}"
             string += f"{prefix}└─── {Lattice._print_tree(last, prefix + '    ')}"
@@ -434,10 +434,10 @@ def as_dict(self):
 
         # TODO: make sure lattices are sorted
         lattices_dict = {
-            lattice.name: [obj.name for obj in lattice.tree]
+            lattice.name: [obj.name for obj in lattice.children]
             for lattice in self.sub_lattices
         }
-        lattices_dict[self.name] = [obj.name for obj in self.tree]
+        lattices_dict[self.name] = [obj.name for obj in self.children]
 
         return dict(
             version="2.0",

apace/matrixmethod.py

@@ -138,7 +138,7 @@ def n_steps(self) -> int:
 
     def update_n_steps(self):
         """Manually update the total number of kicks."""
-        self._n_steps = sum(map(self.get_steps, self.lattice.arrangement))
+        self._n_steps = sum(map(self.get_steps, self.lattice.sequence))
         self._n_steps_needs_update = False
 
     def _on_n_steps_changed(self):
@@ -155,7 +155,7 @@ def update_element_indices(self):
         """Manually update the indices of each element."""
         self._element_indices.clear()
         start = 0
-        for element in self.lattice.arrangement:
+        for element in self.lattice.sequence:
             end = start + self.get_steps(element)
             tmp = list(range(start, end))
             try:

apace/plot.py

@@ -78,10 +78,10 @@ def draw_elements(
         plt.hlines(y0, x_min, x_max, color="black", linewidth=1)
     ax.set_ylim(y_min, y_max)
 
-    arrangement = lattice.arrangement
+    sequence = lattice.sequence
     position = start = end = 0
     sign = 1
-    for element, next_element in zip_longest(arrangement, arrangement[1:]):
+    for element, next_element in zip_longest(sequence, sequence[1:]):
         position += element.length
         if element is next_element or position <= x_min:
             continue
@@ -130,7 +130,7 @@ def draw_sub_lattices(
     location: str = "bottom",
 ):
     x_min, x_max = ax.get_xlim()
-    length_gen = [0.0, *(obj.length for obj in lattice.tree)]
+    length_gen = [0.0, *(obj.length for obj in lattice.children)]
     position_list = np.add.accumulate(length_gen)
     i_min = np.searchsorted(position_list, x_min)
     i_max = np.searchsorted(position_list, x_max)
@@ -151,7 +151,7 @@ def draw_sub_lattices(
 
         ax.set_ylim(y_min, y_max)
         start = end = 0
-        for obj in lattice.tree:
+        for obj in lattice.children:
             end += obj.length
             if not isinstance(obj, Lattice) or start >= x_max or end <= x_min:
                 continue
@@ -343,7 +343,7 @@ def __init__(
                 if isinstance(section, (str, Base)):
                     obj = self.lattice[section] if isinstance(section, str) else section
                     index = self.lattice.indices[obj][0]
-                    x_min = sum(obj.length for obj in self.lattice.arrangement[:index])
+                    x_min = sum(obj.length for obj in self.lattice.sequence[:index])
                     x_max = x_min + obj.length
                 else:
                     x_min, x_max = section
@@ -406,9 +406,9 @@ def floor_plan(
     end = np.zeros(2)
     x_min = y_min = 0
     x_max = y_max = 0
-    arrangement = lattice.arrangement
+    sequence = lattice.sequence
     sign = 1
-    for element, next_element in zip_longest(arrangement, arrangement[1:]):
+    for element, next_element in zip_longest(sequence, sequence[1:]):
         length = element.length
         if isinstance(element, Drift):
             color = Color.BLACK

apace/tracking_integration.py

@@ -52,7 +52,7 @@ def track(self, initial_distribution, step_size=0.01):
 
         end = 0
         i = 0
-        for element in self.lattice.arrangement:
+        for element in self.lattice.sequence:
             end += element.length
             while s[i] < end:
                 step_size_arg = min(step_size, end - s[0])

docs/guide.rst

@@ -116,14 +116,14 @@ Its length should be 16 times the length of the :code:`dba_cell`::
    >>> dba_ring.length
    192.0
 
-The Base Tree
+Direct children
 ---------------
 
-The structure which defines the order of elements in our DBA ring can be thought of as a `Tree <https://wikipedia.org/wiki/Tree_structure>`_, where :code:`dba_ring` is the root, the :code:`dba_cell` objects are the nodes and the :code:`bend`, :code:`drift` and :code:`quad` elements are the leafes. The attribute which stores the order of objects within a lattice is therefore called :attr:`~Lattice.tree`. Try to output the tree for the :code:`dba_ring` and :code:`dba_cell` objects::
+The structure which defines the order of elements in our DBA ring can be thought of as a `Tree <https://wikipedia.org/wiki/Tree_structure>`_, where :code:`dba_ring` is the root, the :code:`dba_cell` objects are the nodes and the :code:`bend`, :code:`drift` and :code:`quad` elements are the leafes. The attribute which stores the order of objects within a lattice is called :attr:`~Lattice.chilldren`. Try to pritn the children for the :code:`dba_ring` and :code:`dba_cell` objects::
 
-   >>> dba_ring.tree
+   >>> dba_ring.children
    [DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL, DBA_CELL]
-   >>> dba_cell.tree
+   >>> dba_cell.children
    [Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift]
 
 
@@ -149,23 +149,23 @@ This can be also visualized by calling the :meth:`Lattice.print_tree` method::
        ├─── Dipole
        └─── Drift
 
-As a nested structure is not always convenient to work with, there are three other representations of :attr:`~Lattice.tree` (internally called :code:`tree_properties`):
+As a nested structure is not always convenient to work with, there are three other representations of the nested :attr:`~Lattice.children` attribute:
 
-#. The :attr:`~Lattice.lattice` attribute
+#. The :attr:`~Lattice.sequence` attribute
 
-   To loop over the exact arrangement of objects there is the :attr:`Lattice.lattice` attribute, which is a list of :class:`~Element` objects. It can be thought of a flattened version of the tree. The :attr:`~Lattice.lattice` attribute can be used in regular Python :code:`for ... in` loops::
+   To loop over the exact sequence of objects there is the :attr:`Lattice.sequence` attribute, which is a list of :class:`~Element` objects. It can be thought of a flattened version of :attr:`~Lattice.children`. The :attr:`~Lattice.sequence` attribute can be used in regular Python :code:`for ... in` loops::
 
-      >>> sum(element.length for element in dba_ring.lattice)
+      >>> sum(element.length for element in dba_ring.sequence)
       192
 
-   As the :code:`dba_cell` does not contain any other lattices, the :attr:`~Lattice.lattice` and :attr:`~Lattice.tree` attributes should be equal::
+   As the :code:`dba_cell` does not contain any other lattices, the :attr:`~Lattice.sequence` and :attr:`~Lattice.children` attributes should be equal::
 
-      >>> dba_cell.tree == dba_cell.arrangement
+      >>> dba_cell.children == dba_cell.sequence
       True
 
-   On the other hand, the :attr:`~Lattice.lattice` attribute of the :code:`dba_ring` should look different then its :attr:`~Lattice.tree`::
+   On the other hand, the :attr:`~Lattice.sequence` attribute of the :code:`dba_ring` should look different then its :attr:`~Lattice.children`::
 
-      >>> dba_ring.arrangement
+      >>> dba_ring.sequence
       [Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift, Drift, Dipole, Drift, Quadrupole, Drift, Dipole, Drift]
 
 
@@ -192,7 +192,7 @@ As a nested structure is not always convenient to work with, there are three oth
 
 #. The :attr:`~Lattice.sub_lattices` attribute
 
-    This attribute is equivalent to the :attr:`~Lattice.elements` attribute but for lattices. It contains all lattices within a given lattice, including grandchildren, great grandchildren, etc.
+    This attribute is equivalent to the :attr:`~Lattice.elements` attribute but for lattices. It contains all sub-lattices within a given lattice, including grandchildren, great grandchildren, etc.
     The :attr:`~Lattice.sub_lattices` attribute should be empty for the :code:`dba_cell` as it does not contain any other lattices::
 
       >>> dba_cell.sub_lattices
@@ -201,11 +201,7 @@ As a nested structure is not always convenient to work with, there are three oth
 Adding and Removing Objects
 ---------------------------
 
-As adding and removing objects from the :attr:`~Lattice.tree` significantly increased the
-code complextetiy, it was decided that :attr:`~Lattice.tree` cannont be altered after the
-:class:`Lattice` was created. If you needed to add/remove an object just create a new
-:class:`Lattice` object or initially add an :class:`Element` with length zero, which can
-be altered when needed.
+As adding and removing objects from the :attr:`~Lattice.children` significantly increased the code complextetiy, so it was decided that :attr:`~Lattice.children` cannont be altered after a :class:`Lattice` instance was created. If you needed to add/remove an object just create a new :class:`Lattice` instance or add an :class:`Element` with length zero, which can be altered when needed.
 
 Load and Save Lattice Files
 ---------------------------
@@ -289,7 +285,6 @@ Signals and Events
 
 As we have already seen in the :ref:`parent-lattices` section, the :attr:`~Lattice.length` of of a :class:`Lattice` gets updated whenever the length of one of its :class:`Element` objects changes. The same happens for the transfer matrices of  the :class:`Twiss` object. This is not only convenient - as one does not have to call an :func:`update` function every time an attribute changes - but is also more efficient, because apace has internal knowledge about which elements have changed and can accordingly only update the transfer matrices which have actually changed.
 
-
 This is achieved by a so called `Observer Pattern <https://wikipedia.org/wiki/Observer_pattern>`_, where an **subject** emits an **event** to all its **observers**  whenever its state changes.
 
 These events are implemented by the :class:`Signal` class. A callback can be connected to a given :class:`Signal` through the :meth:`~Signal.connect` method. Calling an instance of the :class:`Signal` will have the same effect as calling all connected callbacks.

examples/fodo_twiss.py

@@ -23,7 +23,7 @@
 
 print(
     f"Overview of {fodo_ring.name}",
-    f"Num of elements: {len(fodo_ring.arrangement)}",
+    f"Num of elements: {len(fodo_ring.sequence)}",
     f"Lattice Length : {fodo_ring.length}",
     f"Cell Length    : {fodo_cell.length}",
     sep="\n",