.. _flow_control-loop:

Loop
----

The ``Loop`` node allows collections of nodes to be run as a ``for`` or
``while`` loop. This node is essentially a sheet within a sheet, with ``Tunnel``
terminals that are used to control the passing of data between the two sheets.

To create a new tunnel, right click on the boarder of the node, and select
``New tunnel``.

.. figure:: ./images/loop_new_tunnel.png
   :align: center
   :scale: 75 %

There are four types of ``Tunnel`` terminals. To change the type of the
terminal, right click on the terminal and select which one you would like
from the menu. The four types of ``Tunnel`` terminals on the left side of the
node are:

*  ``Pass through`` - Provides the value passed from the parent sheet to the
   child sheet without modification.
*  ``Indexed`` - Tries to index the value passed from the parent sheet with the
   current loop count.
*  ``Indexed (array)`` - Same as the ``Indexed``, but specific for numpy arrays.
*  ``Shift`` - Provides the value passed from the parent sheet on the first loop
   (:math:`i=0`), then provides the value passed to the left side of the
   terminal on subsequent iterations

.. figure:: ./images/loop_tunnel_types.png
   :align: center
   :scale: 75 %

On the right side of the node, the terminals are similar:

*  ``Pass through`` - Provides the value passed from the child sheet to the
   parent sheet without modification.
*  ``Indexed`` - Appends values passed from the child sheet into a list, which
   is provided to the parent sheet.
*  ``Indexed (array)`` - Same as the ``Indexed``, but converts the list of
   values to a numpy array (``numpy.asarray()``)
*  ``Shift`` - The value provided on the right side is used on the left side
   when the loop iteration is greater than 0.


For loop
++++++++

If one of the ``Tunnel`` terminals on the left side of the loop node is an
``Indexed`` or ``Indexed (array)``, then the loop is automatically executed
as a for loop. If there are multiple ``Indexed`` or ``Indexed (array)``
terminals on the left side of the node, then the loop will continue until the
end of the shortest value provided to one of the ``Indexed`` or
``Indexed (array)`` terminals is reached.

For example, if two ranges are provided to two ``Indexed`` terminals, one with
a length of 10 and the other with a length of 25, the loop will only iterate
10 times (:math:`i=9`).

.. figure:: ./images/for_loop.png
   :align: center
   :scale: 75 %

While Loop
++++++++++

The same loop structure will operate as a while loop if there are no ``Indexed``
or ``Indexed (array)`` terminals on the left side of the node. However, there
must be a ``Stop`` node inside the loop node to tall the while loop when to
stop. Be careful that you don't end up with an endless loop!

.. figure:: ./images/while_loop.png
   :align: center
   :scale: 75 %

.. note::

   You can have a for loop with a stop node inside. The loop will continue until
   either the ``Stop`` node is triggered or the end of the  ``Indexed``
   or ``Indexed (array)`` value is reached.

   .. figure:: ./images/for_loop_stop.png
      :align: center
      :scale: 75 %