.. currentmodule:: halerium.core

===================
Details about links
===================

A :class:`~graph.Link` is a connection between two
:class:`~Entity`, two :class:`~Variable`, or two :class:`~StaticVariable` instances,
the ``source`` and the ``target``.
The linked target is then essentially a reference to the source.
So the values of the variables in target will all mimic the
values in the corresponding source variables.

Links are established by calling the :func:`halerium.core.link` function.

Linking rules
-------------

What can be the link scope?
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The scope in which the link is set has to be a :class:`~Graph`.
So every link belongs zu a (sub-)graph.

What entities can the link connect to?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The link can then only connect to entities or variables in its graph
(plus the inputs and outputs of its scope) and to the inputs and outputs
of child-graphs of its graph.
Furthermore sub-entities of allowed entities are also allowed.

What can be the link source?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The link source can be
 - an input (sub-)entity or variable of the graph (the scope of the link)
 - an output (sub-)entity or variable of a child graph of the graph
 - a free (sub-)entity or variable of the graph

A single entity or variable can be the source to an arbitrary amount of links.

What can be the link target?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The link target can be
 - an output (sub-)entity or variable of the graph (the scope of the link)
 - an input (sub-)entity or variable of a child graph of the graph
 - a free (sub-)entity or variable of the graph

An entity or variable can only be the target to one link.
Any link configuration which could result in a conflict of sources is
forbidden. For example an entity cannot be the target of a link if one of
its (sub-)entities or contained variables is already a target.

How links affect the numerics
-----------------------------

Graph operations trump links
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If the variable is modified from a graph scope,
the link has no effect on that variable

Links trump Entity and Variable operations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If the variable is modified from a entity or variable scope,
the modifications have no effect and the links stays active.

Example 1: ::

    with g:
        Graph("sg0")
        with sg0:
            with outputs:
                Entity("e")
                with e:
                    Variable("v")
                    Variable("w")
            outputs.e.v.mean = 0.
            outputs.e.w.mean = 0.
        Graph("sg1")
        with sg1:
            with inputs:
                Entity("e")
                with e:
                    Variable("v")
                    Variable("w")
                    w.mean = 11 # this is overwritten by the link
            inputs.e.v.mean = 12 # this overwrites the link
        link(sg0.outputs.e, sg1.inputs.e)

The link has no effect on ``g.sg1.inputs.v``, because ``g.sg1.inputs.v``
was modified from a graph scope. However, ``g.sg1.inputs.w``
is affected by the link, because it was only modified from within an entity
scope.

Example 2: ::

    with g:
    Graph("sg1")
    with sg1:
        with inputs:
            Entity("e")
            with e:
                Variable("v")
                Variable("w")
        inputs.e.v.mean = 12 # is immune to the link
    link(sg0.outputs.e, sg1.inputs.e)
    with g:
        with sg1:
            with inputs:
                with e:
                    w.mean = 11 # this has no effect since the link trumps it