bluemira.base.components
========================

.. py:module:: bluemira.base.components

.. autoapi-nested-parse::

   Module containing the base Component class.



Attributes
----------

.. autoapisummary::

   bluemira.base.components.ComponentT


Classes
-------

.. autoapisummary::

   bluemira.base.components.Component
   bluemira.base.components.PhysicalComponent
   bluemira.base.components.MagneticComponent


Functions
---------

.. autoapisummary::

   bluemira.base.components.get_properties_from_components


Module Contents
---------------

.. py:data:: ComponentT

.. py:class:: Component(name: str, parent: ComponentT | None = None, children: list[ComponentT] | None = None)

   Bases: :py:obj:`anytree.NodeMixin`, :py:obj:`bluemira.display.plotter.Plottable`, :py:obj:`bluemira.display.displayer.DisplayableCAD`

   .. autoapi-inheritance-diagram:: bluemira.base.components.Component
      :parts: 1
      :private-bases:


   The Component is the fundamental building block for a bluemira reactor design. It
   encodes the way that the corresponding part of the reactor will be built, along with
   any other derived properties that relate to that component.

   Components define a tree structure, based on the parent and children properties. This
   allows the nodes on that tree to be passed around within bluemira so that
   operations can be performed on the child branches of that structure.

   For example, a reactor design including just a TFCoilSystem may look as below:

   .. digraph:: base_component_tree

     "FusionPowerPlant" -> "TFCoilSystem" -> {"TFWindingPack" "TFCasing"}

   A Component cannot be used directly - only subclasses should be instantiated.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: parent
      :value: None


      Parent Node.

      On set, the node is detached from any previous parent node and attached
      to the new node.

      >>> from anytree import Node, RenderTree
      >>> udo = Node("Udo")
      >>> marc = Node("Marc")
      >>> lian = Node("Lian", parent=marc)
      >>> print(RenderTree(udo))
      Node('/Udo')
      >>> print(RenderTree(marc))
      Node('/Marc')
      └── Node('/Marc/Lian')

      **Attach**

      >>> marc.parent = udo
      >>> print(RenderTree(udo))
      Node('/Udo')
      └── Node('/Udo/Marc')
          └── Node('/Udo/Marc/Lian')

      **Detach**

      To make a node to a root node, just set this attribute to `None`.

      >>> marc.is_root
      False
      >>> marc.parent = None
      >>> marc.is_root
      True


   .. py:method:: __repr__() -> str

      The string representation of the instance.

      :returns: The name of the instance and its class name.



   .. py:method:: filter_components(names: collections.abc.Iterable[str], component_filter: collections.abc.Callable[[ComponentT], bool] | None = None)

      Removes all components from the tree, starting at this component,
      that are siblings of each component specified in `names`
      and that aren't in `names` themselves.

      :param names: The list of names of each component to search for.
      :param component_filter: A callable to filter Components from the Component tree,
                               returning True keeps the node False removes it

      .. rubric:: Notes

      This function mutates components in the subtree



   .. py:method:: tree() -> str

      Get the tree of descendants of this instance.

      :returns: The tree of descendants of this instance as a string.



   .. py:method:: copy(parent: ComponentT | None = None) -> ComponentT

      Copies this component and its children (recursively)
      and sets `parent` as this copy's parent.
      This only creates copies of each Component,
      the shape and material instances (for a PhysicalComponent for ex.)
      are shared (i.e. are the same instance).

      :param parent: The component to set as the copy's parent

      :rtype: The copied component

      .. rubric:: Notes

      This function should be overridden by implementors



   .. py:method:: copy_children(parent: ComponentT) -> list[ComponentT]

      Copies this component's children (recursively)
      and sets `parent` as the copied children's parent.

      :param parent: The component to set as the copied children's parent

      :rtype: The copied children components

      .. rubric:: Notes

      This function should *not* be overridden by implementors



   .. py:method:: get_component(name: str, *, first: bool = True, full_tree: bool = False) -> ComponentT | tuple[ComponentT] | None

      Find the components with the specified name.

      :param name: The name of the component to search for.
      :param first: If True, only the first element is returned, by default True.
      :param full_tree: If True, searches the tree from the root, else searches from this node, by
                        default False.

      :returns: * *The first component of the search if first is True, else all components*
                * *matching the search.*

      .. rubric:: Notes

      This function is just a wrapper of the anytree.search.findall
      function.



   .. py:method:: get_component_properties(properties: collections.abc.Sequence[str] | str, *, first: bool = True, full_tree: bool = False) -> tuple[list[Any]] | list[Any] | Any

      Get properties from a component

      :param properties: properties to extract from component tree
      :param first: If True, only the first element is returned, by default True.
      :param full_tree: If True, searches the tree from the root, else searches from this node, by
                        default False.

      :returns: * *If multiple properties specified returns a tuple of the list of properties,*
                * *otherwise returns a list of the property.*
                * *If only one node has the property returns the value(s).*

      .. rubric:: Notes

      This function is just a wrapper of the anytree.search.findall or find
      functions.



   .. py:method:: _get_thing(filter_: collections.abc.Callable[[ComponentT], bool] | None, *, first: bool, full_tree: bool) -> ComponentT | tuple[ComponentT] | None


   .. py:method:: add_child(child: Component)

      Add a single child to this node

      :param child: The child to be added

      :raises ComponentError: Child already in tree



   .. py:method:: add_children(children: ComponentT | list[ComponentT] | None, *, merge_trees: bool = False)

      Add multiple children to this node

      :param children: The children to be added

      :rtype: This component.

      :raises ComponentError: Duplicate entries



   .. py:method:: prune_child(name: str)

      Remove the child with the given name, and all its children.



.. py:class:: PhysicalComponent(name: str, shape: bluemira.geometry.base.BluemiraGeoT, material: matproplib.material.Material | None = None, parent: ComponentT | None = None, children: list[ComponentT] | None = None)

   Bases: :py:obj:`Component`

   .. autoapi-inheritance-diagram:: bluemira.base.components.PhysicalComponent
      :parts: 1
      :private-bases:


   A physical component. It includes shape and materials.

   :param name: Name of the PhysicalComponent
   :param shape: Geometry of the PhysicalComponent
   :param material: Material of the PhysicalComponent
   :param parent: Parent of the PhysicalComponent
   :param children: Children of the PhysicalComponent


   .. py:attribute:: _shape


   .. py:attribute:: _material
      :value: None



   .. py:method:: copy(parent: ComponentT | None = None) -> ComponentT

      Copies this component and its children (recursively)
      and sets `parent` as this copy's parent.
      This only creates copies of each Component,
      the shape and material instances (for a PhysicalComponent for ex.)
      are shared (i.e. are the same instance).

      :param parent: The component to set as the copy's parent

      :returns: The copied component
      :rtype: self_copy



   .. py:property:: shape
      :type: bluemira.geometry.base.BluemiraGeoT


      The geometric shape of the Component.


   .. py:property:: material
      :type: matproplib.material.Material | None


      The material that the Component is built from.


.. py:class:: MagneticComponent(name: str, shape: bluemira.geometry.base.BluemiraGeoT, material: matproplib.material.Material | None = None, conductor: Any = None, parent: ComponentT | None = None, children: list[ComponentT] | None = None)

   Bases: :py:obj:`PhysicalComponent`

   .. autoapi-inheritance-diagram:: bluemira.base.components.MagneticComponent
      :parts: 1
      :private-bases:


   A magnetic component. It includes a shape, a material, and a source conductor.


   .. py:property:: conductor

      The conductor used by current-carrying filaments.


   .. py:method:: copy(parent: ComponentT | None = None) -> ComponentT

      Copies this component and its children (recursively)
      and sets `parent` as this copy's parent.
      This only creates copies of each Component,
      the shape and material instances (for a PhysicalComponent for ex.)
      are shared (i.e. are the same instance).

      :param parent: The component to set as the copy's parent

      :returns: The copied component
      :rtype: self_copy



.. py:function:: get_properties_from_components(comps: ComponentT | collections.abc.Iterable[ComponentT], properties: str | collections.abc.Sequence[str], *, extract: bool = True) -> tuple[list[Any], Ellipsis] | list[Any] | Any

   Get properties from Components

   :param comps: A component or list of components
   :param properties: properties to collect

   :returns: If multiple properties specified returns a tuple of the list of properties,
             otherwise returns a list of the property.
             If only one node has the property returns the value(s).
   :rtype: property_lists