.. _py-hyperflow/LinExp:

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

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


.. _FlowLinExpAndConstraints-label:


This part describes variable specifiers, linear expressions, and linear constraints.
See :ref:`flowCommon-varSpecLinExp` for a higher-level description of these entities.

Linear expressions (:class:`hyperflow.LinExp`) and constraints (:class:`hyperflow.LinConstraint`)
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 ``hyperflow.LinExp()``.

A variable specifier is a representation of either a single variable or a sum of 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:: hyperflow.VarSumVertex

    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:: __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: DG.Vertex or Graph
        :returns: a variable specifier for a single variable in the set represented by this object.
        :rtype: VarVertex or VarVertexGraph
    .. attribute:: id

        The ID for this specifier.

        :type: str
.. class:: hyperflow.VarVertex

    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 DG.Vertex v: The vertex used to select a variable from the variable set.

    .. attribute:: id

        The ID for the underlying set specifier.

        :type: str
    .. attribute:: vertex

        The graph used to index into the variable set.

        :type: DG.Vertex
.. class:: hyperflow.VarVertexGraph

    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.

    .. 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:: hyperflow.VarSumEdge

    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:: __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 DG.HyperEdge e: an edge used to select a variable.
        :returns: a variable specifier for a single variable in the set represented by this object.
        :rtype: VarEdge

    .. attribute:: id

        The ID for this specifier.

        :type: str
.. class:: hyperflow.VarEdge

    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 DG.HyperEdge e: The edge used to select a variable from the variable set.

    .. attribute:: id

        The ID for the underlying set specifier.

        :type: str
    .. attribute:: edge

        The edge used to index into the variable set.

        :type: DG.HyperEdge
.. class:: hyperflow.VarSumCustom

    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:: __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: VarCustom

    .. attribute:: id

        The ID for this specifier.

        :type: str
.. class:: hyperflow.VarCustom

    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.

    .. 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:: hyperflow.Var

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

.. class:: hyperflow.LinExp

    Represents a linear expression over variable specifiers.

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

.. class:: hyperflow.LinConstraint

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

Pre-defined Variable Specifiers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Each of the variable specifiers are defined in the submodule ``hyperflow.vars``,
and then import in the root module, so they are directly accessible.

Base Model
""""""""""

.. data:: hyperflow.vars.inFlow
          inFlow

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.outFlow
          outFlow

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.isInUsed
          isInUsed

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.isOutUsed
          isOutUsed

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.isInLessOut
          isInLessOut

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.isInGreaterOut
          isInGreaterOut

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.isInOutZero
          isInOutZero

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.vertexFlow
          vertexFlow

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.isVertexUsed
          isVertexUsed

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.transitInternalFlow
          transitInternalFlow

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.edgeFlow
          edgeFlow

    :type: hyperflow.VarSumEdge
.. data:: hyperflow.vars.isEdgeUsed
          isEdgeUsed

    :type: hyperflow.VarSumEdge
.. data:: hyperflow.vars.isBothReverseUsed
          isBothReverseUsed

    :type: hyperflow.VarSumEdge

OverallCatalysis
""""""""""""""""

.. data:: hyperflow.vars.isOverallCata
          isOverallCata

    :type: hyperflow.VarSumVertex

OverallAutocatalysis
""""""""""""""""""""

.. data:: hyperflow.vars.isOverallAutocata
          isOverallAutocata

    :type: hyperflow.VarSumVertex

Thermodynamics
""""""""""""""

.. data:: hyperflow.vars.energy
          energy

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.logConcentration
          logConcentration

    :type: hyperflow.VarSumVertex
.. data:: hyperflow.vars.deltaEnergy
          deltaEnergy

    :type: hyperflow.VarSumEdge