.. _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`` -------------------------------------------------------------------------------------------------------------------------------- .. py:class:: FlowVarSumVertex Represents the sum of all variables indicated by the given :py:attr:`id`. Can be indexed to retrieve a specifier for a single variable in the set. .. py:function:: __init__(self, 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. .. py:function:: __str__(self) .. py:function:: __getitem__(self, 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 .. py:attribute:: id The ID for this specifier. :type: str Class ``FlowVarVertex`` -------------------------------------------------------------------------------------------------------------------------------- .. py:class:: FlowVarVertex Represents a variable associated with a single vertex in a derivation graph. .. py:function:: __init__(self, 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. .. py:function:: __str__(self) .. py:attribute:: id The ID for the underlying set specifier. :type: str .. py:attribute:: vertex The graph used to index into the variable set. :type: DGVertex Class ``FlowVarVertexGraph`` -------------------------------------------------------------------------------------------------------------------------------- .. py: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. .. py:function:: __init__(self, 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. .. py:function:: __str__(self) .. py:attribute:: id The ID for the underlying set specifier. :type: str .. py:attribute:: graph The graph used to index into the variable set. :type: Graph Class ``FlowVarSumEdge`` -------------------------------------------------------------------------------------------------------------------------------- .. py:class:: FlowVarSumEdge Represents the sum of all variables indicated by the given :py:attr:`id`. Can be indexed to retrieve a specifier for a single variable in the set. .. py:function:: __init__(self, 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. .. py:function:: __str__(self) .. py:function:: __getitem__(self, 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 .. py:attribute:: id The ID for this specifier. :type: str Class ``FlowVarEdge`` -------------------------------------------------------------------------------------------------------------------------------- .. py:class:: FlowVarEdge Represents a variable associated with an edge in a derivation graph. .. py:function:: __init__(self, 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. .. py:function:: __str__(self) .. py:attribute:: id The ID for the underlying set specifier. :type: str .. py:attribute:: edge The edge used to index into the variable set. :type: DGHyperEdge Class ``FlowVarSumCustom`` -------------------------------------------------------------------------------------------------------------------------------- .. py:class:: FlowVarSumCustom Represents the sum of all variables indicated by the given :py:attr:`id`. Can be indexed to retrieve a specifier for a single variable in the set. .. py:function:: __init__(self, id) Construct a variable specifier for a sum of custom variables. :param str id: The ID for the variable set to represent. .. py:function:: __str__(self) .. py:function:: __getitem__(self, 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 .. py:attribute:: id The ID for this specifier. :type: str Class ``FlowVarCustom`` -------------------------------------------------------------------------------------------------------------------------------- .. py:class:: FlowVarCustom Represents a custom variable. .. py:function:: __init__(self, 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. .. py:function:: __str__(self) .. py:attribute:: id The ID for the underlying set specifier. :type: str .. py:attribute:: name The name used to index into the variable set. :type: str Class ``FlowVar`` -------------------------------------------------------------------------------------------------------------------------------- .. py:class:: FlowVar Represents any variable specifier. They are all implicitly convertible to this type. Class ``FlowLinExp`` -------------------------------------------------------------------------------------------------------------------------------- .. py: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`` -------------------------------------------------------------------------------------------------------------------------------- .. py:class:: FlowLinConstraint Represents a linear constraint with a :py:class:`FlowLinExp` on one side, and a constant on the other side. The operators ``<=``, ``==``, and ``>=`` are overloaded on linear expressions to automatically create constraints.