.. _py-flow/Flow: ********************************************************** flow/Flow ********************************************************** .. default-domain:: py .. py:currentmodule:: mod .. cpp:namespace:: mod .. class:: Flow A :class:`Flow` object represents a flow model on a given derivation graph. A model consists of a set of modules with the base module modelling the edge flow and input/output flow. Each modules is accessed using proxy objects accessible as attributes in the main model object. .. method:: __init__(dg, ilpSolver="default") Creates a new flow model over the given derivation graph. :param DG dg: the derivation graph to create the flow model for over. :param str ilpSolver: the ILP solver to use. See :func:`getAvailableILPSolvers`. :throws: :class:`LogicError` if not ``dg.locked``. .. attribute:: id (Read-only) The unique instance id for the :class:`Flow` object. :type: int .. attribute:: dg (Read-only) The underlying derivation graph. :type: DG .. attribute:: specificationLocked (Read-only) Whether the specification is locked for modifications. :type: bool .. method:: listSpecification() List the specification. .. method:: addSource(v) addSource(g) Add a vertex as a possible source. The version taking a graph as argument is equivalent to calling ``addSource(self.dg.findVertex(g))``. :param DGVertex v: the vertex to add as source. :param Graph g: a graph representing a vertex to be added as a source. :raises: :class:`LogicError` if `specificationLocked`. :raises: :class:`LogicError` if ``not v``. :raises: :class:`LogicError` if ``v`` does not belong to the underlying derivation graph. :raises: (the graph version) :class:`LogicError` if it is not represented in the underlying DG. .. attribute:: sources (Read-only) Retrieve the list of source vertices for the model. :type: list[DGVertex] .. method:: addSink(v) addSink(g) Add a vertex as a possible sink. The version taking a graph as argument is equivalent to calling ``addSink(self.dg.findVertex(g))``. :param DGVertex v: the vertex to add as sink. :param Graph g: a graph representing a vertex to be added as a sink. :raises: :class:`LogicError` if `specificationLocked`. :raises: :class:`LogicError` if ``not v``. :raises: :class:`LogicError` if ``v`` does not belong to the underlying derivation graph. :raises: (the graph version) :class:`LogicError` if it is not represented in the underlying DG. .. attribute:: sinks (Read-only) Retrieve the list of sink vertices for the model. :type: list[DGVertex] .. method:: exclude(v) exclude(g) Exclude the vertex and all its incident edges from the model. This will not only add a constraint to disallow flow through this vertex, but will make some algorithms in various models pretend the vertex and incident edges were never part of the model in the first place. The version taking a graph as argument is equivalent to calling ``exclude(self.dg.findVertex(g))``. :param DGVertex v: the vertex to exclude. :param Graph g: a graph representing a vertex to be excluded. :raises: :class:`LogicError` if `specificationLocked`. :raises: :class:`LogicError` if ``not v``. :raises: :class:`LogicError` if ``v`` does not belong to the underlying derivation graph. :raises: (the graph version) :class:`LogicError` if it is not represented in the underlying DG. .. attribute:: excluded (Read-only) Retrieve the list of excluded vertices for the model. :type: list[DGVertex] .. method:: separateIOInternalTransit(v) separateIOInternalTransit(g) Ensure that the expanded vertex of `v` has transit edges such that flow going from the input edge or to the output edge can be distinguished from flow going from the network and back to the network. The vertex expansion is lazy, and thus calling this function is necessary in order to, e.g., access the corresponding ``transitInternal`` variable. The version taking a graph as argument is equivalent to calling ``separateIOInternalTransit(self.dg.findVertex(g))``. :param DGVertex v: the vertex to ensure the separation of transit edges for. :param Graph g: a graph representing a vertex to ensure the separation of transit edges for. :raises: :class:`LogicError` if `specificationLocked`. :raises: :class:`LogicError` if ``not v``. :raises: :class:`LogicError` if ``v`` does not belong to the underlying derivation graph. :raises: (the graph version) :class:`LogicError` if it is not represented in the underlying DG. .. attribute:: separatedIOInternalTransit (Read-only) Retrieve the list of vertices where :meth:`separateIOInternalTransit` has been called. Note, this does not mean that other vertices do not have separated transit edges. For example, setting ``allowIOReversal = True`` implies separation as well. :type: list[DGVertex] .. attribute:: allowHyperLoops Control or query whether or not flow is allowed through loop edges. I.e., hyperedges with identical source and target multisets. :type: bool :raises: (only set) :class:`LogicError` if `specificationLocked`. :note: This setting may be changed when certain modules are enabled. .. attribute:: allowReversal Controls whether or not flow may go through one edge and then directly afterwards the inverse edge. :type: bool :raises: (only set) :class:`LogicError` if `specificationLocked`. :note: This setting may be modified when certain modules are enabled. .. attribute:: allowIOReversal Controls whether or not flow may go through an input edge and directly afterwards through the corresponding output edge. :type: bool :raises: (only set) :class:`LogicError` if `specificationLocked`. :note: This setting may be modified when certain modules are enabled. .. attribute:: relaxed Controls whether the core flow variables are integer or continuous. The default is ``False``, meaning integer. Using the relaxed model significantly changes the meaning of solutions, and many features may break. :type: bool :raises: (only set) :class:`LogicError` if `specificationLocked`. .. attribute:: objectiveFunction (Write-only) The objective function, which will be minimized (see :ref:`FlowLinExpAndConstraints-label`). :type: FlowLinExp :raises: :class:`LogicError` if `specificationLocked`. .. method:: addIntVariable(name) Create a new variable with the given name. :returns: a handle to the variable. :raises: :class:`LogicError` if `specificationLocked`. :raises: :class:`LogicError` if :var`name` is already in use. .. method:: addConstraint(c) :param FlowLinConstraint c: the linear constraint to add to the model (see :ref:`FlowLinExpAndConstraints-label`). :raises: :class:`LogicError` if `specificationLocked`. .. attribute:: overallAutocatalysis Access the overall autocatalysis module. :type: FlowOverallAutocatalysis .. attribute:: overallCatalysis Access the overall catalysis module. :type: FlowOverallCatalysis .. py:attribute:: thermodynamics Access the thermodynamics extension. :type: :class:`FlowThermodynamics` .. method:: addEnumerationVar(var) Add the variables specified by the given variable specifier for solution enumeration. The default variables are ``edge``, ``inFlow``, and ``outFlow``. These are removed the first time this function is called. :param FlowVar var: the variable specifier to add variables from. :raises: :class:`LogicError` if `specificationLocked`. .. attribute:: enumerationVars (Read-only) Retrieve the list variable specifiers used for enumeration. :type: list[Graph] .. attribute:: absGap The absolute gap in objective value between the optimal solution and the worst solution. As default there is no constraint on this gap. Set to ``None``, or a negative value, to reset to this unconstrained state. :type: int or None :throws: (only set) :class:`LogicError` if `specificationLocked`. .. method:: findSolutions(*, maxNumSolutions=1, verbosity=1, ilpVerbosity=1) Find the next up to ``maxNumSolutions`` best solutions. This may be called multiple times to find additional solutions in an incremental fashion. After the first call the specification will be locked, i.e., `specificationLocked` will be ``True``. :param int maxNumSolutions: the maximum number of solutions to find. :param int verbosity: see :cpp:func:`flow::Flow::findSolutions`. :param int ilpVerbosity: see :cpp:func:`flow::Flow::findSolutions`. :returns: a range of the newly found solutions. :rtype: FlowSolutionRange :raises: :class:`LogicError` if ``maxNumSolutions`` is less than 1. :raises: :class:`LogicError` the first time it is called, if an enabled module can not create its model. See the documentation for each module. .. method:: dump() dump(filename) Dump all model settings and all solutions found to a file. This file can be loaded in again. :param str filename: the name of the file to save the dump to. If non is given an auto-generated name in the ``out/`` folder is used. If an empty string is given, it is treated as if non is given. .. note:: The filename is being used literally, i.e., it is not being prefixed according to the current script location as input filenames are. :returns: the filename with the dumped model. :rtype: str .. attribute:: solutionsOld (Read-only) After solving, this is all the found solutions. :type: FlowSolutionSet .. attribute:: solutions (Read-only) A range of the solutions found so far. :type: FlowSolutionRange :raises: :class:`LogicError` if not `specificationLocked`. .. method:: printExpandedVertex(v) printExpandedVertex(g) Print the expanded flow network for an explicitly given vertex or a vertex indicated by a given graph. The graph version is equivalent to calling ``self.printExpandedVertex(self.dg.findVertex(g))``. :returns: the name of the PDF-file which will be created in post-processing. :raises: :class:`LogicError` if not `specificationLocked`. :raises: (the vertex version) :class:`LogicError` if ``not v``. :raises: (the graph version) :class:`LogicError` if it is not represented in the underlying DG. .. method:: printExpanded() Print the complete expanded derivation graph. :returns: the name of the PDF-file which will be created in post-processing. :raises: :class:`LogicError` if not `specificationLocked`. .. method:: printEnumerationTree() Print the search tree generated by the solution enumeration. :returns: the name of the generated file. :raises: :class:`LogicError` if not `specificationLocked`. .. staticmethod:: load(dg, f, ilpSolver="default", verbosity=1, listModel=True) :param DG dg: the derivation graph which the dumped flow model is build upon. :param f: name of the file with the model to be loaded. :type f: str or CWDPath :param str ilpSolver: the ILP solver to use. See :func:`getAvailableILPSolvers`. :param int verbosity: see :cpp:func:`flow::Flow::findSolutions`. :param bool listModel: list the model after loading the specification, but before loading solutions. :returns: a flow model (possibly with solutions) corresponding to the model stored in the given file. The given derivation graph must match the derivation graph originally used to create the dump. :rtype: Flow :raises: :class:`InputError` on bad data or if the given derivation graph does not match the data. .. staticmethod:: loadString(dg, s, ilpSolver="default", verbosity=1, listModel=True) :param DG dg: the derivation graph which the dumped flow model is build upon. :param str s: the string with the dump data to be loaded. :param str ilpSolver: the ILP solver to use. See :func:`getAvailableILPSolvers`. :param int verbosity: see :cpp:func:`flow::Flow::findSolutions`. :param bool listModel: list the model after loading the specification, but before loading solutions. :returns: a flow model (possibly with solutions) corresponding to the model stored in the given string. :rtype: Flow :raises: :class:`InputError` on bad data or if the given derivation graph does not match the data. .. class:: FlowOverallAutocatalysis .. method:: enable() Enable the extension. This will also enable the transit extension and configure it to disallow direct flow through inverse edges, both internal and input/output. :raises: :class:`LogicError` if `Flow.isSpecificationLocked`. :raises: during model creation, :class:`LogicError` if in relaxed mode. .. attribute:: forceExistence Controls whether or not a solution must be overall autocatalytic. :type: bool :raises: :class:`LogicError` if the module is not enabled. :raises: (only set) :class:`LogicError` if `Flow.isSpecificationLocked`. .. attribute:: strictTransit Controls whether transit flow in overall autocatalytic vertices is restricted or not. :type: bool :raises: :class:`LogicError` if the module is not enabled. :raises: (only set) :class:`LogicError` if `Flow.isSpecificationLocked`. .. attribute:: bfsExclusive Controls whether or not vertices must be exclusively overall autocatalytic, as determined by breadth-first marking. :type: bool :raises: :class:`LogicError` if the module is not enabled. :raises: (only set) :class:`LogicError` if `Flow.isSpecificationLocked`. .. class:: FlowOverallCatalysis .. method:: enable() Enable the extension. This will also enable the transit extension and configure it to disallow direct flow through inverse edges, both internal and input/output. :raises: :class:`LogicError` if `Flow.isSpecificationLocked`. :raises: during model creation, :class:`LogicError` if in relaxed mode. .. attribute:: forceExistence Controls whether or not a solution must be overall catalytic. :type: bool :raises: :class:`LogicError` if the module is not enabled. :raises: (only set) :class:`LogicError` if `Flow.isSpecificationLocked`. .. attribute:: strictTransit Controls whether transit flow in overall catalytic vertices is restricted or not. :type: bool :raises: :class:`LogicError` if the module is not enabled. :raises: (only set) :class:`LogicError` if `Flow.isSpecificationLocked`. .. py:class:: FlowThermodynamics .. method:: enable() Enable the extension. :raises: :class:`LogicError` if `Flow.isSpecificationLocked`. :raises: during model creation, :class:`LogicError` if in relaxed mode. :raises: during model creation, :class:`LogicError` if a non-excluded vertex has no energy bounds. .. attribute:: temperature The temperature, in Kelvin, used in the constraints. :type: float :raises: :class:`LogicError` if the module is not enabled. :raises: (only set) :class:`LogicError` if `Flow.isSpecificationLocked`. .. method:: setEnergyBounds(v, min, max) setEnergyBounds(g, min, max) Set the bounds for the energy estimate of the given vertex. The module assumes that stable compounds have energy values less than 0. :param DGVertex v: the vertex to set the bounds for. :param Graph g: a graph representing a vertex to set the bounds for. :param float min: the minimum energy estimate, in kcal/mol. :param float min: the maximum energy estimate, in kcal/mol. :raises: :class:`LogicError` if `specificationLocked`. :raises: :class:`LogicError` if ``not v``. :raises: :class:`LogicError` if ``v`` does not belong to the underlying derivation graph. :raises: (the graph version) :class:`LogicError` if it is not represented in the underlying DG. :raises: :class:`LogicError` if ``min`` is not a finite number. :raises: :class:`LogicError` if ``max`` is not a finite number greater than or equal to ``min``. .. method:: getEnergyBounds(v) getEnergyBounds(g) :param DGVertex v: the vertex to get the bounds for. :param Graph g: a graph representing a vertex to get the bounds for. :returns: the minimum and maximum bound on the energy estimate for this vertex. :rtype: tuple[float, float] :raises: :class:`LogicError` if `specificationLocked`. :raises: :class:`LogicError` if ``not v``. :raises: :class:`LogicError` if ``v`` does not belong to the underlying derivation graph. :raises: (the graph version) :class:`LogicError` if it is not represented in the underlying DG. :raises: :class:`LogicError` if no bound has been set for this vertex.