sysloss.diagram
===============

.. py:module:: sysloss.diagram

.. autoapi-nested-parse::

   Power tree diagrams.

   Graphviz is used to render power tree diagrams in sysLoss.
   The diagrams can be customized with the full range of Graphviz attributes.



Functions
---------

.. autoapisummary::

   sysloss.diagram.get_conf
   sysloss.diagram.make_diag
   sysloss.diagram.make_hdiag


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

.. py:function:: get_conf() -> dict

   Get default Graphviz configuration.

   The Graphviz attributes used by sysLoss to format the diagram are returned in a dictionary.
   By modifying the attributes in the dictionary or adding new ones, the rendered diagram can
   be customized. The modified dict is passed as an argument to :py:meth:`sysloss.diagram.make_diag`.

   :returns: Default Graphviz configuration.
   :rtype: dict

   .. rubric:: Examples

   >>> my_conf = get_conf()
   >>> my_conf["graph"]["rankdir"] = 'LR' # use left-right orientation
   >>> make_diag(my_sys, config=my_conf)


.. py:function:: make_diag(sys: sysloss.system.System, *, fname: str = None, group: bool = True, config: dict = {})

   Create power tree diagram.

   The default diagram is rendered as a top-bottom diagram with components represented
   as light-grey, square boxes. Shapes and colors can be configured using an attribute dict.

   :param fname: Filename for output image. File extension defines image format.
   :type fname: str, optional
   :param group: Cluster components based on group names, by default True.
   :type group: bool, optional
   :param config: Graphviz configuration.
   :type config: dict, optional

   :returns: * *None* -- If filename is given.
             * *PIL.Image* -- If no filename is given

   .. rubric:: Examples

   >>> img = make_diag(my_sys)
   >>> make_diag(my_sys, fname="system.svg") # write to file
   >>> # add custom colors to components
   >>> my_conf = get_conf()
   >>> my_conf["node"]["Source"] = {"fillcolor":"coral"}
   >>> my_conf["node"]["Converter"] = {"fillcolor":"darkturquoise"}
   >>> my_conf["node"]["ILoad"] = {"fillcolor":"darkgoldenrod1"}
   >>> my_conf["node"]["RLoss"] = {"fillcolor":"deeppink"}
   >>> my_conf["node"]["LinReg"] = {"fillcolor":"darkorchid1"}
   >>> my_conf["node"]["PSwitch"] = {"fillcolor":"aquamarine"}
   >>> make_diag(my_sys, fname="system.svg", config=my_conf)


.. py:function:: make_hdiag(sys: sysloss.system.System, *, fname: str = None, group: bool = True, config: dict = {})

   Create power tree heat diagram.

   The system is first solved to find the losses in each component. If the system has load phases
   defined, the time-weighted loss is used in the diagram.
   The default diagram is rendered as a top-bottom diagram with components represented
   as gradient-colored, square boxes. Shapes and colors can be configured using an attribute dict,
   although component (node) colors will be overridden by gradient color.

   :param fname: Filename for output image. File extension defines image format.
   :type fname: str, optional
   :param group: Cluster components based on group names, by default True.
   :type group: bool, optional
   :param config: Graphviz configuration.
   :type config: dict, optional

   :returns: * *None* -- If filename is given.
             * *PIL.Image* -- If no filename is given

   .. rubric:: Examples

   >>> img = make_hdiag(my_sys)
   >>> make_hdiag(my_sys, fname="system.svg") # write to file