.. _py-flow/LinExp:

**********************************************************
flow/LinExp
**********************************************************
.. default-domain:: py

.. py:currentmodule:: mod
.. cpp:namespace:: mod


.. _FlowLinExpAndConstraints-label:

Linear Expressions and Constraints
-------------------------------------

Linear expressions (:class:`FlowLinExp`) and constraints (:class:`FlowLinConstraint`)
can be implicitly created from variable specifiers and operators, meaning one rarely
need to instantiate them explicitly.
However creating the zero-expression might sometimes be useful (e.g., in a sum expression)
and can be done simply with the expression ``FlowLinExp()``.

A variable specifier is a representation of either a single ILP variable or a sum of ILP variables.
The addition, multiplication and division operators are overloaded for variable specifiers and
linear expressions such that expressions can be written in the natural manner.

The operators ``<=``, ``==`` and ``>=`` are overloaded on linear expressions to make the creation of
linear constraints easier. However, one argument to the operator must be a linear expression while
the other argument must be a number.

All variable specifiers are defined in module scope. See :ref:`flowCommon` for an overview of the specifiers.

.. class:: FlowVarSumVertex

    Represents the sum of all variables indicated by the given :attr:`id`.
    Can be indexed to retrieve a specifier for a single variable in the set.

    .. method:: __init__(id)

        Construct a variable specifier for a sum of variables associated with
        vertices in the underlying derivation graph.

        :param str id: The ID for the variable set to represent.
    .. method:: __str__()
    .. method:: __getitem__(x)

        Select the variable associated with the derivation graph vertex which represents the given object.
        When the resulting specifier is given to a flow model,
        if the given object is a vertex, then it must belong to the same derivation graph as the one
        underlying the model.
        If the given object is a graph, a vertex in the underlying derivation graph must exist
        which has the graph associated.

        :param x: a graph or vertex used to select a vertex in the underlying derivation graph.
        :type x: DGVertex or Graph
        :returns: a variable specifier for a single variable in the set represented by this object.
        :rtype: FlowVarVertex or FlowVarVertexGraph
    .. attribute:: id

        The ID for this specifier.

        :type: str
.. class:: FlowVarVertex

    Represents a variable associated with a single vertex in a derivation graph.
    .. method:: __init__(id, v)

        :param str id: The ID for the variable set to select variables from.
        :param DGVertex v: The vertex used to select a variable from the variable set.

    .. method:: __str__()
    .. attribute:: id

        The ID for the underlying set specifier.

        :type: str
    .. attribute:: vertex

        The graph used to index into the variable set.

        :type: DGVertex
.. class:: FlowVarVertexGraph

    Represents a variable associated with a single vertex in a derivation graph.
    This is done implicitly by a graph, and when this specifier is later given to a flow model
    a vertex with the graph associated must exist in the underlying derivation graph.
    .. method:: __init__(id, g)

        :param str id: The ID for the variable set to select variables from.
        :param Graph g: The graph used to select a variable from the variable set.

    .. method:: __str__()
    .. attribute:: id

        The ID for the underlying set specifier.

        :type: str
    .. attribute:: graph

        The graph used to index into the variable set.

        :type: Graph
.. class:: FlowVarSumEdge

    Represents the sum of all variables indicated by the given :attr:`id`.
    Can be indexed to retrieve a specifier for a single variable in the set.

    .. method:: __init__(id)

        Construct a variable specifier for a sum of variables associated with
        edges in the underlying derivation graph.

        :param str id: The ID for the variable set to represent.
    .. method:: __str__()
    .. method:: __getitem__(e)

        Select the variable associated with the derivation graph edge which represents the given object.
        When the resulting specifier is given to a flow model, the given edge must be long to the same
        derivation graph as the one underlying the model.

        :param DGHyperEdge e: an edge used to select a variable.
        :returns: a variable specifier for a single variable in the set represented by this object.
        :rtype: FlowVarEdge

    .. attribute:: id

        The ID for this specifier.

        :type: str
.. class:: FlowVarEdge

    Represents a variable associated with an edge in a derivation graph.
    .. method:: __init__(id, e)

        :param str id: The ID for the variable set to select variables from.
        :param DGHyperEdge e: The edge used to select a variable from the variable set.

    .. method:: __str__()
    .. attribute:: id

        The ID for the underlying set specifier.

        :type: str
    .. attribute:: edge

        The edge used to index into the variable set.

        :type: DGHyperEdge
.. class:: FlowVarSumCustom

    Represents the sum of all variables indicated by the given :attr:`id`.
    Can be indexed to retrieve a specifier for a single variable in the set.

    .. method:: __init__(id)

        Construct a variable specifier for a sum of custom variables.

        :param str id: The ID for the variable set to represent.
    .. method:: __str__()
    .. method:: __getitem__(id)

        Select the variable associated with the given name.
        When the resulting specifier is given to a flow model that variable must have been created
        in the specification in some way.

        :param str e: a name used to select a variable.
        :returns: a variable specifier for a single variable in the set represented by this object.
        :rtype: FlowVarCustom

    .. attribute:: id

        The ID for this specifier.

        :type: str
.. class:: FlowVarCustom

    Represents a custom variable.
    .. method:: __init__(id, name)

        :param str id: The ID for the variable set to select variables from.
        :param str name: The name used to select a variable from the variable set.

    .. method:: __str__()
    .. attribute:: id

        The ID for the underlying set specifier.

        :type: str
    .. attribute:: name

        The name used to index into the variable set.

        :type: str
.. class:: FlowVar

    Represents any variable specifier. They are all implicitly convertible to this type.
.. class:: FlowLinExp

    Represents a linear expresion over variable specifiers.

    The usual arithmetic operators are overloaded on variable specifiers and this class
    to automatically create expressions.
.. class:: FlowLinConstraint

    Represents a linear constraint with a :class:`FlowLinExp` on one side,
    and a constant on the other side.
    The operators ``<=``, ``==``, and ``>=`` are overloaded on linear expressions
    to automatically create constraints.