flow/Flow¶

class mod.Flow¶

A 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.

__init__(dg, ilpSolver='default')¶

Creates a new flow model over the given derivation graph.

Parameters:

dg (DG) – the derivation graph to create the flow model for over.
ilpSolver (str) – the ILP solver to use. See getAvailableILPSolvers().

Raises:

LogicError if not dg.locked.

Raises:

LogicError if dg.numVertices is 0.

id¶

(Read-only) The unique instance id for the Flow object.

Type:: int

dg¶

(Read-only) The underlying derivation graph.

Type:: DG

specificationLocked¶

(Read-only) Whether the specification is locked for modifications.

Type:: bool

listSpecification()¶: List the specification.

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)).

Parameters:

v (DGVertex) – the vertex to add as source.
g (Graph) – a graph representing a vertex to be added as a source.

Raises:

LogicError if specificationLocked.

Raises:

LogicError if not v.

Raises:

LogicError if v does not belong to the underlying derivation graph.

Raises:

(the graph version) LogicError if it is not represented in the underlying DG.

sources¶

(Read-only) Retrieve the list of source vertices for the model.

Type:: list[DGVertex]

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)).

Parameters:

v (DGVertex) – the vertex to add as sink.
g (Graph) – a graph representing a vertex to be added as a sink.

Raises:

LogicError if specificationLocked.

Raises:

LogicError if not v.

Raises:

LogicError if v does not belong to the underlying derivation graph.

Raises:

(the graph version) LogicError if it is not represented in the underlying DG.

sinks¶

(Read-only) Retrieve the list of sink vertices for the model.

Type:: list[DGVertex]

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)).

Parameters:

v (DGVertex) – the vertex to exclude.
g (Graph) – a graph representing a vertex to be excluded.

Raises:

LogicError if specificationLocked.

Raises:

LogicError if not v.

Raises:

LogicError if v does not belong to the underlying derivation graph.

Raises:

(the graph version) LogicError if it is not represented in the underlying DG.

excluded¶

(Read-only) Retrieve the list of excluded vertices for the model.

Type:: list[DGVertex]

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)).

Parameters:

v (DGVertex) – the vertex to ensure the separation of transit edges for.
g (Graph) – a graph representing a vertex to ensure the separation of transit edges for.

Raises:

LogicError if specificationLocked.

Raises:

LogicError if not v.

Raises:

LogicError if v does not belong to the underlying derivation graph.

Raises:

(the graph version) LogicError if it is not represented in the underlying DG.

separatedIOInternalTransit¶

(Read-only) Retrieve the list of vertices where: 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]

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) LogicError if specificationLocked.
Note:: This setting may be changed when certain modules are enabled.

allowReversal¶

Controls whether or not flow may go through one edge and then directly afterwards the inverse edge.

Type:: bool
Raises:: (only set) LogicError if specificationLocked.
Note:: This setting may be modified when certain modules are enabled.

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) LogicError if specificationLocked.
Note:: This setting may be modified when certain modules are enabled.

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) LogicError if specificationLocked.

objectiveFunction¶

(Write-only) The objective function, which will be minimized (see Linear Expressions and Constraints).

Type:: FlowLinExp
Raises:: LogicError if specificationLocked.

addIntVariable(name)¶

Create a new custom integer variable with the given name.

Returns:: a handle to the variable. :rtype: FlowVarCustom
Raises:: LogicError if specificationLocked.
Raises:: LogicError if :var`name` is already in use.

customIntVariables¶

Returns:: a list of handles to the variables added with addIntVariable(). :type: list[FlowVarCustom]

addConstraint(c)¶

Parameters:: c (FlowLinConstraint) – the linear constraint to add to the model (see Linear Expressions and Constraints).
Raises:: LogicError if specificationLocked.

overallAutocatalysis¶

Access the overall autocatalysis module.

Type:: FlowOverallAutocatalysis

overallCatalysis¶

Access the overall catalysis module.

Type:: FlowOverallCatalysis

thermodynamics¶

Access the thermodynamics extension.

Type:: FlowThermodynamics

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.

Parameters:: var (FlowVar) – the variable specifier to add variables from.
Raises:: LogicError if specificationLocked.

enumerationVars¶

(Read-only) Retrieve the list variable specifiers used for enumeration.

Type:: list[FlowVar]

addTransitEnumeration(v)¶

addTransitEnumeration(g)

Add the transit edges of the vertex for solution enumeration. The version taking a graph as argument is equivalent to calling addTransitEnumeration(self.dg.findVertex(g)).

Parameters:

v (DGVertex) – the vertex to add transit edges for enumeration.
g (Graph) – a graph representing a vertex for which transit edges should be added..

Raises:

LogicError if specificationLocked.

Raises:

LogicError if not v.

Raises:

(the graph version) LogicError if it is not represented in the underlying DG.

transitEnumeration¶

(Read-only) Retrieve the list vertices where the transit edges are used for solution enumeration.

Type:: list[DGVertex]

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) LogicError if specificationLocked.

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.

Parameters:

maxNumSolutions (int) – the maximum number of solutions to find.
verbosity (int) – see flow::Flow::findSolutions().
ilpVerbosity (int) – see flow::Flow::findSolutions().

Returns:

a range of the newly found solutions.

Return type:

FlowSolutionRange

Raises:

LogicError if maxNumSolutions is less than 1.

Raises:

LogicError the first time it is called, if an enabled module can not create its model. See the documentation for each module.

dump()¶

dump(filename)

Dump all model settings and all solutions found to a file. This file can be loaded in again.

Parameters:

filename (str) –

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.

Return type:

str

solutionsOld¶

(Read-only) After solving, this is all the found solutions.

Type:: FlowSolutionSet

solutions¶

(Read-only) A range of the solutions found so far.

Type:: FlowSolutionRange
Raises:: LogicError if not specificationLocked.

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:: LogicError if not specificationLocked.
Raises:: (the vertex version) LogicError if not v.
Raises:: (the graph version) LogicError if it is not represented in the underlying DG.

printExpanded()¶

Print the complete expanded derivation graph.

Returns:: the name of the PDF-file which will be created in post-processing.
Raises:: LogicError if not specificationLocked.

printEnumerationTree()¶

Print the search tree generated by the solution enumeration.

Returns:: the name of the generated file.
Raises:: LogicError if not specificationLocked.

static load(dg, f, ilpSolver='default', verbosity=1)¶

Parameters:

dg (DG) – the derivation graph which the dumped flow model is build upon.
f (str or CWDPath) – name of the file with the model to be loaded.
ilpSolver (str) – the ILP solver to use. See getAvailableILPSolvers().
verbosity (int) – see flow::Flow::findSolutions().

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.

Return type:

Flow

Raises:

InputError on bad data or if the given derivation graph does not match the data.

static loadString(dg, s, ilpSolver='default', verbosity=1, listModel=True)¶

Parameters:

dg (DG) – the derivation graph which the dumped flow model is build upon.
s (str) – the string with the dump data to be loaded.
ilpSolver (str) – the ILP solver to use. See getAvailableILPSolvers().
verbosity (int) – see flow::Flow::findSolutions().
listModel (bool) – 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.

Return type:

Flow

Raises:

InputError on bad data or if the given derivation graph does not match the data.

class mod.FlowOverallAutocatalysis¶

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:: LogicError if Flow.isSpecificationLocked.
Raises:: during model creation, LogicError if in relaxed mode.

forceExistence¶

Controls whether or not a solution must be overall autocatalytic.

Type:: bool
Raises:: LogicError if the module is not enabled.
Raises:: (only set) LogicError if Flow.isSpecificationLocked.

strictTransit¶

Controls whether transit flow in overall autocatalytic vertices is restricted or not.

Type:: bool
Raises:: LogicError if the module is not enabled.
Raises:: (only set) LogicError if Flow.isSpecificationLocked.

bfsExclusive¶

Controls whether or not vertices must be exclusively overall autocatalytic, as determined by breadth-first marking.

Type:: bool
Raises:: LogicError if the module is not enabled.
Raises:: (only set) LogicError if Flow.isSpecificationLocked.

class mod.FlowOverallCatalysis¶

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:: LogicError if Flow.isSpecificationLocked.
Raises:: during model creation, LogicError if in relaxed mode.

forceExistence¶

Controls whether or not a solution must be overall catalytic.

Type:: bool
Raises:: LogicError if the module is not enabled.
Raises:: (only set) LogicError if Flow.isSpecificationLocked.

strictTransit¶

Controls whether transit flow in overall catalytic vertices is restricted or not.

Type:: bool
Raises:: LogicError if the module is not enabled.
Raises:: (only set) LogicError if Flow.isSpecificationLocked.

class mod.FlowThermodynamics¶

enable()¶

Enable the extension.

Raises:: LogicError if Flow.isSpecificationLocked.
Raises:: during model creation, LogicError if in relaxed mode.
Raises:: during model creation, LogicError if a non-excluded vertex has no energy bounds.

temperature¶

The temperature, in Kelvin, used in the constraints.

Type:: float
Raises:: LogicError if the module is not enabled.
Raises:: (only set) LogicError if Flow.isSpecificationLocked.

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.

Parameters:

v (DGVertex) – the vertex to set the bounds for.
g (Graph) – a graph representing a vertex to set the bounds for.
min (float) – the minimum energy estimate, in kcal/mol.
min – the maximum energy estimate, in kcal/mol.

Raises:

LogicError if specificationLocked.

Raises:

LogicError if not v.

Raises:

LogicError if v does not belong to the underlying derivation graph.

Raises:

(the graph version) LogicError if it is not represented in the underlying DG.

Raises:

LogicError if min is not a finite number.

Raises:

LogicError if max is not a finite number greater than or equal to min.

getEnergyBounds(v)¶

getEnergyBounds(g)

Parameters:

v (DGVertex) – the vertex to get the bounds for.
g (Graph) – a graph representing a vertex to get the bounds for.

Returns:

the minimum and maximum bound on the energy estimate for this vertex.

Return type:

tuple[float, float]

Raises:

LogicError if specificationLocked.

Raises:

LogicError if not v.

Raises:

LogicError if v does not belong to the underlying derivation graph.

Raises:

(the graph version) LogicError if it is not represented in the underlying DG.

Raises:

LogicError if no bound has been set for this vertex.