4.1.11.2. hyperflow/Model¶

class hyperflow.Model¶

A Model object represents a flow model on a given derivation graph (see Hyperflow Model for details). A model consists of a set of modules with the base module modelling the edge flow and input/output flow. Each module is accessed using proxy objects accessible as attributes in the main model object.

__init__(dg, ilpSolver='default')¶

__init__(model)

Creates a new hyperflow model over the given derivation graph, or as a copy of an existing model.

Parameters:

dg (DG) – the derivation graph to create the flow model for over.
model (Model) – the other model to copy the specification from. The copy can be further modified afterwards.
ilpSolver (str) – the ILP solver to use. See getAvailableILPSolvers().

Raises:

LogicError if not dg.

Raises:

LogicError if not dg.locked.

Raises:

LogicError if dg.numVertices is 0.

Raises:

LogicError if not model.

id¶

(Read-only) The unique instance ID for the Model 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 textually to standard output.

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 (DG.Vertex) – 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[DG.Vertex]

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 (DG.Vertex) – 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[DG.Vertex]

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 modules 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 (DG.Vertex) – 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[DG.Vertex]

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 (DG.Vertex) – 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 to True implies separation as well.

Type:: list[DG.Vertex]

allowHyperLoops¶

Control or query whether 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 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 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 all features that rely on flows being integer will be disabled.

Type:: bool
Raises:: (only set) LogicError if specificationLocked.

objectiveFunction¶

(Write-only) The objective function, which will be minimized (see hyperflow/LinExp).

Type:: LinExp
Raises:: LogicError if specificationLocked.

addBoolVariable(name)¶

addIntVariable(name)¶

addFloatVariable(name)¶

Create a new custom boolean, integer, or floating point variable with the given name.

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

customBoolVariables¶

customIntVariables¶

customFloatVariables¶

Returns:: a list of handles to the variables added with addBoolVariable()/addIntVariable()/addFloatVariable().
Type:: list[VarCustom]

addConstraint(c)¶

Parameters:: c (LinConstraint) – the linear constraint to add to the model (see hyperflow/LinExp).
Raises:: LogicError if specificationLocked.

overallAutocatalysis¶

The access object for the overall autocatalysis module of the flow model.

Type:: OverallAutocatalysis

overallCatalysis¶

The access object for the overall catalysis module of the flow model.

Type:: OverallCatalysis

addEnumerationVar(var)¶

Add the variables specified by the given variable specifier for solution enumeration.

The default variables are edgeFlow, inFlow, and outFlow. These are removed the first time this function is called.

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

enumerationVars¶

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

Type:: list[Var]

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 (DG.Vertex) – 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[DG.Vertex]

absGap¶

The absolute gap in objective value between the optimal solution and the worst solution that can be enumerated. 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.

Calling with maxNumSolutions set to 0 will still lock the specification, but will create the internal model.

Parameters:

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

Returns:

a range of the newly found solutions.

Return type:

SolutionRange

Raises:

LogicError if maxNumSolutions is less than 0.

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, that can be loaded with load().

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 used literally, i.e., it is not prefixed according to the current script location as input filenames are.

Returns:

the filename with the dumped model.

Return type:

str

solutions¶

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

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

implementationView¶

(Read-only) A new view on the implementation of the hyperflow model.

Type:: ModelImplementationView
Throws:: 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 hyperflow::Model::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:

Model

Raises:

LogicError if not dg.

Raises:

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

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

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 hyperflow::Model::findSolutions().

Returns:

a flow model (possibly with solutions) corresponding to the model stored in the given string.

Return type:

Model

Raises:

LogicError if not dg.

Raises:

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

class hyperflow.Model.OverallAutocatalysis¶

This class provides access to the module for overall autocatalysis of a flow model.

enable()¶

Enable the extension. This will also set allowReversal and allowIOReversal to False.

Raises:: LogicError if specificationLocked.
Raises:: during model creation, LogicError if in relaxed mode.

isEnabled¶

Whether the module is enabled.

Type:: bool

forceExistence¶

Controls whether a solution must be overall autocatalytic.

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

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

bfsExclusive¶

Controls whether 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 specificationLocked.

class hyperflow.Model.OverallCatalysis¶

This class provides access to the module for overall catalysis of a flow model.

enable()¶

Enable the extension. This will also set allowReversal and allowIOReversal to False.

Raises:: LogicError if specificationLocked.
Raises:: during model creation, LogicError if in relaxed mode.

isEnabled¶

Whether the module is enabled.

Type:: bool

forceExistence¶

Controls whether a solution must be overall catalytic.

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

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