2.2.11.1. flow/Flow.hpp

2.2.11.1.1. Class flow::Flow

class flow::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 module is accessed using proxy objects accessible as public members in the main model object.

2.2.11.1.1.1. Synopsis

class MOD_DECL Flow : public std::enable_shared_from_this<Flow> {
private:
    Flow(std::unique_ptr<lib::HyperFlow::Flow> f, std::unique_ptr<lib::Flow::FlowBase> base);
public:
    ~Flow();
    MOD_DECL friend std::ostream &operator<<(std::ostream &s, const Flow &dgFlow);
    int getId() const;
    std::shared_ptr<dg::DG> getDG() const;
    lib::Flow::FlowBase &getBase();
    const lib::Flow::FlowBase &getBase() const;
    lib::HyperFlow::Flow &getFlow();
    const lib::HyperFlow::Flow &getFlow() const;
public:
    bool isSpecificationLocked() const;
    void listSpecification() const;
public:
    void addSource(dg::DG::Vertex v);
    void addSource(std::shared_ptr<graph::Graph> g);
    std::vector<dg::DG::Vertex> getSources() const;
    void addSink(dg::DG::Vertex v);
    void addSink(std::shared_ptr<graph::Graph> g);
    std::vector<dg::DG::Vertex> getSinks() const;
    void exclude(dg::DG::Vertex v);
    void exclude(std::shared_ptr<graph::Graph> g);
    std::vector<dg::DG::Vertex> getExcluded() const;
    void separateIOInternalTransit(dg::DG::Vertex v);
    void separateIOInternalTransit(std::shared_ptr<graph::Graph> g);
    std::vector<dg::DG::Vertex> getSeparatedIOInternalTransit() const;
    void setAllowHyperLoops(bool value);
    bool getAllowHyperLoops() const;
    void setAllowReversal(bool value);
    bool getAllowReversal() const;
    void setAllowIOReversal(bool value);
    bool getAllowIOReversal() const;
    void setRelaxed(bool value);
    bool getRelaxed() const;
    void setObjectiveFunction(LinExp func);
public: // user defined variables and constraints
    VarCustom addIntVariable(const std::string &name);
    void addConstraint(const LinConstraint &constraint);
public: // overall autocatalysis
    class OverallAutocatalysisProxy {
        friend class Flow;
        OverallAutocatalysisProxy(Flow &dgFlow);
    public:
        void enable();
        void setForceExistence(bool value);
        bool getForceExistence() const;
        void setStrictTransit(bool value);
        bool getStrictTransit() const;
        void setBFSExclusive(bool value);
        bool getBFSExclusive() const;
    private:
        Flow &dgFlow;
    };
    OverallAutocatalysisProxy overallAutocatalysis;
public: // overall catalysis
    class OverallCatalysisProxy {
        friend class Flow;
        OverallCatalysisProxy(Flow &dgFlow);
    public:
        void enable();
        void setForceExistence(bool value);
        bool getForceExistence() const;
        void setStrictTransit(bool value);
        bool getStrictTransit() const;
    private:
        Flow &dgFlow;
    };
    OverallCatalysisProxy overallCatalysis;
public: // solution definition
    void addEnumerationVar(Var var);
    std::vector<Var> getEnumerationVars() const;
    //// rst: .. function:: void addTransitEnumeration(dg::DG::Vertex v)
    //// rst:
    //// rst:        Add the transit edges of the vertex for solution enumeration.
    //// rst:
    //// rst:        :throws: :class:`LogicError` if `isSpecificationLocked()`.
    //// rst:         :throws: :class:`LogicError` if `!v`.
    //// rst:         :throws: :class:`LogicError` if  `v.getDG() != getDG()`.
    void addTransitEnumeration(dg::DG::Vertex v);
    //// rst: .. function:: void addTransitEnumeration(std::shared_ptr<graph::Graph> g)
    //// rst:
    //// rst:        Equivalent to calling `addTransitEnumeration(getDG()->findVertex(g))`.
    void addTransitEnumeration(std::shared_ptr<graph::Graph> g);
    //// rst: .. function:: std::vector<dg::DG::Vertex> getTransitEnumeration() const
    //// rst:
    //// rst:        Retrieve the list of vertices where the transit edges are used for solution enumeration.
    std::vector<dg::DG::Vertex> getTransitEnumeration() const;
    void setAbsGap(int absGap);
    boost::optional<int> getAbsGap();
public: // allowed both pre and post calculation
    SolutionRange findSolutions(int maxNumSolutions);
    SolutionRange findSolutions(int maxNumSolutions, int verbosity);
    SolutionRange findSolutions(int maxNumSolutions, int verbosity, int ilpVerbosity);
    std::string dump() const;
public: // post-calculation operations
    SolutionSet getOldSolutions() const;
    SolutionRange getSolutions() const;
    std::string printExpandedVertex(dg::DG::Vertex v) const;
    std::string printExpandedVertex(std::shared_ptr<graph::Graph> g) const;
    std::string printExpanded() const;
    std::string printEnumerationTree() const;
private:
    struct Pimpl;
    std::unique_ptr<Pimpl> p;
public:
    static std::shared_ptr<Flow> make(std::shared_ptr<dg::DG> dg_);
    static std::shared_ptr<Flow> make(std::shared_ptr<dg::DG> dg_, const std::string &ilpSolver);
    static std::shared_ptr<Flow> load(std::shared_ptr<dg::DG> dg_, const std::string &file);
    static std::shared_ptr<Flow> load(std::shared_ptr<dg::DG> dg_, const std::string &file,
                                      const std::string &ilpSolver, int verbosity);
    static std::shared_ptr<Flow> loadString(std::shared_ptr<dg::DG> dg_, const std::string &data);
    static std::shared_ptr<Flow> loadString(std::shared_ptr<dg::DG> dg_, const std::string &data,
                                            const std::string &ilpSolver, int verbosity);
};

2.2.11.1.1.2. Details

int getId() const
Returns

the instance identifier for the object.

std::shared_ptr<dg::DG> getDG() const
Returns

the underlying derivation graph.

lib::HyperFlow::Flow &getFlow()
const lib::HyperFlow::Flow &getFlow() const
Returns

the internal data structures of the flow model.

bool isSpecificationLocked() const
Returns

whether the specification is locked for modifications.

void listSpecification() const

List the specification.

void addSource(dg::DG::Vertex v)

Add the vertex as a possible source.

Throws

LogicError if isSpecificationLocked().

Throws

LogicError if !v.

Throws

LogicError if v.getDG() != getDG().

void addSource(std::shared_ptr<graph::Graph> g)

Equivalent to calling addSource(getDG()->findVertex(g)).

std::vector<dg::DG::Vertex> getSources() const

Retrieve the list of source vertices for the model.

void addSink(dg::DG::Vertex v)

Add the vertex as a possible sink.

Throws

LogicError if isSpecificationLocked().

Throws

LogicError if !v.

Throws

LogicError if v.getDG() != getDG().

void addSink(std::shared_ptr<graph::Graph> g)

Equivalent to calling addSink(getDG()->findVertex(g)).

std::vector<dg::DG::Vertex> getSinks() const

Retrieve the list of sink vertices for the model.

void exclude(dg::DG::Vertex v)

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.

Throws

LogicError if isSpecificationLocked().

Throws

LogicError if !v.

Throws

LogicError if v.getDG() != getDG().

void exclude(std::shared_ptr<graph::Graph> g)

Equivalent to calling exclude(getDG()->findVertex(g)).

std::vector<dg::DG::Vertex> getExcluded() const

Retrieve the list of excluded vertices for the model.

void separateIOInternalTransit(dg::DG::Vertex v)

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.

Throws

LogicError if isSpecificationLocked().

Throws

LogicError if !v.

Throws

LogicError if v.getDG() != getDG().

void separateIOInternalTransit(std::shared_ptr<graph::Graph> g)

Equivalent to calling separateIOInternalTransit(getDG()->findVertex(g)).

std::vector<dg::DG::Vertex> getSeparatedIOInternalTransit() const
Returns

a list of vertices where separateIOInternalTransit() has been called. Note, this does not mean that other vertices do not have separated transit edges. For example, calling setAllowIOReversal(true) implies separation as well.

void setAllowHyperLoops(bool value)
bool getAllowHyperLoops() const

Control or query whether or not flow is allowed through loop hyperedges. I.e., hyperedges with identical source and target multisets.

Throws

(only set) LogicError if isSpecificationLocked().

Note

This setting may be changed when certain modules are enabled.

void setAllowReversal(bool value)
bool getAllowReversal() const

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

Throws

(only set) LogicError if isSpecificationLocked().

Note

This setting may be modified when certain modules are enabled.

void setAllowIOReversal(bool value)
bool getAllowIOReversal() const

Control or query whether or not flow may go through an input edge and directly afterwards through the corresponding output edge.

This implies that transit edges gets separated in all vertices, as if separateIOInternalTransit() was called on all of them.

Throws

(only set) LogicError if isSpecificationLocked().

Note

This setting may be modified when certain modules are enabled.

void setRelaxed(bool value)
bool getRelaxed() const

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.

Throws

(only set) LogicError if isSpecificationLocked().

void setObjectiveFunction(LinExp func)

Set the objective function used when finding solutions.

Throws

LogicError if isSpecificationLocked().

void addIntVariable(const std::string &name)

Create a new variable with the given name.

Returns

a handle to the variable.

Throws

LogicError if isSpecificationLocked().

Throws

LogicError if :cpp:var`name` is already in use.

void addConstraint(const LinConstraint &constraint)

Add the given linear constraint to the model.

Throws

LogicError if isSpecificationLocked().

OverallAutocatalysisProxy overallAutocatalysis

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

OverallCatalysisProxy overallCatalysis

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

void addEnumerationVar(Var 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.

Throws

LogicError if isSpecificationLocked().

std::vector<Var> getEnumerationVars() const

Retrieve the list of variable specifiers used for solution enumeration.

void setAbsGap(int absGap)

Set the absolute gap in objective value between the optimal solution and the worst solution. As default there is no constraint on this gap. Pass a negative number to reset to this unconstrained state.

Throws

LogicError if isSpecificationLocked().

boost::optional<int> getAbsGap()
Returns

the absolution gap in objective value.

SolutionRange findSolutions(int maxNumSolutions)
SolutionRange findSolutions(int maxNumSolutions, int verbosity)
SolutionRange findSolutions(int maxNumSolutions, int verbosity, int ilpVerbosity)

Find the next up to maxNumSolutions best solutions.

This may be call multiple times to find additional solutions in an incremental fashion. After the first call the specification will be locked, i.e., isSpecificationLocked() will return true.

Parameters

  • verbosity –

    controls the amount of information printed during solution enumeration, defaults to 1:

    • 0: print no information, and cap ilpVerbosity to 0.

    • 1: print status updates periodically, and cap ilpVerbosity to 1.

    • 2: print debug information.

  • verbosity –

    controls the amount of information printed by the underlying ILP solver, defaults to 1:

    • 0: print no information.

    • 1: print default information for the first solution only.

    • 2: print default information when finding a solution.

Returns

a range of the newly found solutions.

Throws

LogicError if maxNumSolutions is less than 1.

std::string dump() const

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

Returns

the filename with the dumped model.

SolutionSet getOldSolutions() const
Returns

the found solutions for the model.

Throws

LogicError if calculation has not been done.

SolutionRange getSolutions() const
Returns

a range of the solutions found so far.

Throws

LogicError if isSpecificationLocked().

std::string printExpandedVertex(dg::DG::Vertex v) const

Print the expanded flow network for the given vertex.

Returns

the name of the PDF-file which will be created in post-processing.

Throws

LogicError if !isSpecificationLocked().

Throws

LogicError if !v.

Throws

LogicError if v.getDG() != getDG().

std::string printExpandedVertex(std::shared_ptr<graph::Graph> g) const

Equivalent to calling printExpandedVertex(getDG()->findVertex(g)).

std::string printExpanded() const

Print the complete expanded derivation graph.

Returns

the name of the PDF-file which will be created in post-processing.

Throws

LogicError if !isSpecificationLocked().

std::string printEnumerationTree() const

Print the search tree generated by the solution enumeration.

Returns

the name of the generated file.

Throws

LogicError if !isSpecificationLocked().

static std::shared_ptr<Flow> make(std::shared_ptr<dg::DG> dg_)
static std::shared_ptr<Flow> make(std::shared_ptr<dg::DG> dg_, const std::string &ilpSolver)
Parameters

ilpSolver – defaults to default. See getAvailableILPSolvers().

Returns

a new flow model over the given derivation graph.

Throws

LogicError if !dg->isLocked().

static std::shared_ptr<Flow> load(std::shared_ptr<dg::DG> dg_, const std::string &file)
static std::shared_ptr<Flow> load(std::shared_ptr<dg::DG> dg_, const std::string &file, const std::string &ilpSolver, int verbosity)
Parameters
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.

Throws

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

static std::shared_ptr<Flow> loadString(std::shared_ptr<dg::DG> dg_, const std::string &data)
static std::shared_ptr<Flow> loadString(std::shared_ptr<dg::DG> dg_, const std::string &data, const std::string &ilpSolver, int verbosity)
Parameters
Returns

a flow model (possibly with solutions) corresponding to the model stored in the given string. The given derivation graph must match the derivation graph originally used to create the dump.

Throws

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

2.2.11.1.2. Class flow::Flow::OverallAutocatalysisProxy

class flow::Flow::OverallAutocatalysisProxy

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

void enable()

Enable the module. This will automatically call setAllowReversal(false) and setAllowIOReversal(false).

Throws

LogicError if isSpecificationLocked().

void setForceExistence(bool value)
bool getForceExistence() const

Control or query whether or not a solution must be overall autocatalytic.

Throws

LogicError if the module is not enabled.

Throws

(only set) LogicError if isSpecificationLocked().

void setStrictTransit(bool value)
bool getStrictTransit() const

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

Throws

LogicError if the module is not enabled.

Throws

(only set) LogicError if isSpecificationLocked().

void setBFSExclusive(bool value)
bool getBFSExclusive() const

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

Throws

LogicError if the module is not enabled.

Throws

(only set) LogicError if isSpecificationLocked().

2.2.11.1.3. Class flow::Flow::OverallCatalysisProxy

class flow::Flow::OverallCatalysisProxy

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

void enable()

Enable the module. This will automatically call setAllowReversal(false) and setAllowIOReversal(false).

Throws

LogicError if isSpecificationLocked().

void setForceExistence(bool value)
bool getForceExistence() const

Control or query whether or not a solution must be overall catalytic.

Throws

LogicError if the module is not enabled.

Throws

(only set) LogicError if isSpecificationLocked().

void setStrictTransit(bool value)
bool getStrictTransit() const

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

Throws

LogicError if the module is not enabled.

Throws

(only set) LogicError if isSpecificationLocked().