.. _cpp-hyperflow/Model: ********************************************************** hyperflow/Model.hpp ********************************************************** .. default-domain:: cpp .. default-role:: cpp:texpr .. py:currentmodule:: mod .. cpp:namespace:: mod Class ``hyperflow::Model`` -------------------------------------------------------------------------------------------------------------------------------- .. class:: hyperflow::Model A :class:`Model` object represents a hyperflow 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. Synopsis ^^^^^^^^ .. alias:: hyperflow::Model :maxdepth: 2 :noroot: Details ^^^^^^^ .. cpp:namespace-push:: hyperflow::Model .. function:: int getId() const :returns: the unique instance ID for the object. .. function:: std::shared_ptr getDG() const :returns: the underlying derivation graph. .. function:: bool isSpecificationLocked() const :returns: whether the specification is locked for modifications. .. function:: void listSpecification() const List the specification textually to standard output. .. function:: void addSource(dg::DG::Vertex v) Add the vertex as a possible source. :throws: :class:`LogicError` if `isSpecificationLocked()`. :throws: :class:`LogicError` if `!v`. :throws: :class:`LogicError` if `v.getDG() != getDG()`. .. function:: void addSource(std::shared_ptr g) Equivalent to calling `addSource(getDG()->findVertex(g))`. .. function:: std::vector getSources() const Retrieve the list of source vertices for the model. .. function:: void addSink(dg::DG::Vertex v) Add the vertex as a possible sink. :throws: :class:`LogicError` if `isSpecificationLocked()`. :throws: :class:`LogicError` if `!v`. :throws: :class:`LogicError` if `v.getDG() != getDG()`. .. function:: void addSink(std::shared_ptr g) Equivalent to calling `addSink(getDG()->findVertex(g))`. .. function:: std::vector getSinks() const Retrieve the list of sink vertices for the model. .. function:: 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 modules pretend the vertex and incident edges were never part of the model in the first place. :throws: :class:`LogicError` if `isSpecificationLocked()`. :throws: :class:`LogicError` if `!v`. :throws: :class:`LogicError` if `v.getDG() != getDG()`. .. function:: void exclude(std::shared_ptr g) Equivalent to calling `exclude(getDG()->findVertex(g))`. .. function:: std::vector getExcluded() const Retrieve the list of excluded vertices for the model. .. function:: 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: :class:`LogicError` if `isSpecificationLocked()`. :throws: :class:`LogicError` if `!v`. :throws: :class:`LogicError` if `v.getDG() != getDG()`. .. function:: void separateIOInternalTransit(std::shared_ptr g) Equivalent to calling `separateIOInternalTransit(getDG()->findVertex(g))`. .. function:: std::vector getSeparatedIOInternalTransit() const :returns: a list of vertices where :cpp:func:`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. .. function:: void setAllowHyperLoops(bool value) bool getAllowHyperLoops() const Control or query whether flow is allowed through loop hyperedges. I.e., hyperedges with identical source and target multisets. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. :note: This setting may be changed when certain modules are enabled. .. function:: void setAllowReversal(bool value) bool getAllowReversal() const Control or query whether flow may go through one edge and then directly afterwards the inverse edge. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. :note: This setting may be modified when certain modules are enabled. .. function:: void setAllowIOReversal(bool value) bool getAllowIOReversal() const Control or query whether 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 :cpp:func:`separateIOInternalTransit` was called on all of them. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. :note: This setting may be modified when certain modules are enabled. .. function:: 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 all features that rely on flows being integer will be disabled. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. .. function:: void setObjectiveFunction(LinExp func) Set the objective function used when finding solutions. :throws: :class:`LogicError` if `isSpecificationLocked()`. .. function:: void addBoolVariable(const std::string &name) void addIntVariable(const std::string &name) void addFloatVariable(const std::string &name) Create a new custom boolean, integer, or floating point variable with the given name. :returns: a handle to the variable. :throws: :class:`LogicError` if `isSpecificationLocked()`. :throws: :class:`LogicError` if :cpp:var`name` is already in use. .. function:: std::vector getCustomBoolVariables() const std::vector getCustomIntVariables() const std::vector getCustomFloatVariables() const :returns: a list of handles to the variables added with :func:`addBoolVariable`/:func:`addIntVariable`/:func:`addFloatVariable`. .. function:: void addConstraint(const LinConstraint &constraint) Add the given linear constraint to the model. :throws: :class:`LogicError` if `isSpecificationLocked()`. .. member:: OverallAutocatalysis overallAutocatalysis The access object for the :ref:`overall autocatalysis module ` of the flow model. .. member:: OverallCatalysis overallCatalysis The access object for the :ref:`overall catalysis module ` of the flow model. .. member:: Thermodynamics thermodynamics The access object for the :ref:`thermodynamics module ` of the flow model. .. function:: void addEnumerationVar(Var var) Add the variables specified by the given variable specifier for solution enumeration. The default variables are :var:`vars::edgeFlow`, :var:`vars::inFlow`, and :var:`vars::outFlow`. These are removed the first time this function is called. :throws: :class:`LogicError` if `isSpecificationLocked()`. .. function:: std::vector getEnumerationVars() const Retrieve the list of variable specifiers used for solution enumeration. .. function:: void addTransitEnumeration(dg::DG::Vertex v) Add the transit edges of the vertex for solution enumeration. :throws: :class:`LogicError` if `isSpecificationLocked()`. :throws: :class:`LogicError` if `!v`. :throws: :class:`LogicError` if `v.getDG() != getDG()`. .. function:: void addTransitEnumeration(std::shared_ptr g) Equivalent to calling `addTransitEnumeration(getDG()->findVertex(g))`. .. function:: std::vector getTransitEnumeration() const Retrieve the list of vertices where the transit edges are used for solution enumeration. .. function:: 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: :class:`LogicError` if `isSpecificationLocked()`. .. function:: std::optional getAbsGap() :returns: the absolution gap in objective value. .. function:: SolutionRange findSolutions(int maxNumSolutions) SolutionRange findSolutions(int maxNumSolutions, int verbosity) SolutionRange findSolutions(int maxNumSolutions, int verbosity, int ilpVerbosity) Find the next up to :var:`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., `isSpecificationLocked()` will return `true`. Calling with `maxNumSolutions` set to 0 will still lock the specification, but will create the internal model. :param verbosity: controls the amount of information printed during solution enumeration, defaults to 1: - 0: print no information, and cap `ilpVerbosity` to 0, no matter the given value. - 1: print status updates periodically. - 2: print debug information. :param ilpVerbosity: 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: :class:`LogicError` if :var:`maxNumSolutions` is less than 0. :throws: :class:`LogicError` the first time it is called, if an enabled module can not create its model. See the documentation for each module. .. function:: std::string dump() const std::string dump(const std::string &filename) const Dump all model settings and all solutions found to a file. This file can be loaded in again. :param 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. :returns: the filename with the dumped model. .. function:: SolutionRange getSolutions() const :returns: a range of the solutions found so far. :throws: :class:`LogicError` if `isSpecificationLocked()`. .. function:: 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: :class:`LogicError` if `!isSpecificationLocked()`. :throws: :class:`LogicError` if `!v`. :throws: :class:`LogicError` if `v.getDG() != getDG()`. .. function:: std::string printExpandedVertex(std::shared_ptr g) const Equivalent to calling `printExpandedVertex(getDG()->findVertex(g))`. .. function:: 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: :class:`LogicError` if `!isSpecificationLocked()`. .. function:: std::string printEnumerationTree() const Print the search tree generated by the solution enumeration. :returns: the name of the generated file. :throws: :class:`LogicError` if `!isSpecificationLocked()`. .. function:: static std::shared_ptr make(std::shared_ptr dg_) static std::shared_ptr make(std::shared_ptr dg_, const std::string &ilpSolver) :param ilpSolver: defaults to ``default``. See :cpp:func:`getAvailableILPSolvers`. :returns: a new flow model over the given derivation graph. :throws: :class:`LogicError` if `!dg`. :throws: :class:`LogicError` if `!dg->isLocked()`. :throws: :class:`LogicError` if `dg->numVertices() == 0`. .. function:: static std::shared_ptr copy(std::shared_ptr other) :param other: a model to copy the specification from. :returns: a new flow model starting with a copy of the specification from `other`. The returned model is not locked. :throws: :class:`LogicError` if `!other`. .. function:: static std::shared_ptr load(std::shared_ptr dg_, const std::string &file) static std::shared_ptr load(std::shared_ptr dg_, const std::string &file, \ const std::string &ilpSolver, int verbosity) :param ilpSolver: defaults to ``default``. See :cpp:func:`getAvailableILPSolvers`. Its value only matters if further solutions are enumerated after the model has been loaded. :param verbosity: see :func:`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. :throws: :class:`LogicError` if `!dg`. :throws: :class:`InputError` on bad data or if the given derivation graph does not match the data. .. function:: static std::shared_ptr loadString(std::shared_ptr dg_, const std::string &data) static std::shared_ptr loadString(std::shared_ptr dg_, const std::string &data, \ const std::string &ilpSolver, int verbosity) :param ilpSolver: defaults to ``default``. See :cpp:func:`getAvailableILPSolvers`. Its value only matters if further solutions are enumerated after the model has been loaded. :param verbosity: see :func:`findSolutions`. :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: :class:`LogicError` if `!dg`. :throws: :class:`InputError` on bad data or if the given derivation graph does not match the data. .. cpp:namespace-pop:: Class ``hyperflow::Model::OverallAutocatalysis`` --------------------------------------------------------------- .. class:: hyperflow::Model::OverallAutocatalysis This class provides access to the module for :ref:`overall autocatalysis ` of a flow model. .. function:: void enable() Enable the module. This will automatically call `setAllowReversal(false)` and `setAllowIOReversal(false)`. :throws: :class:`LogicError` if `isSpecificationLocked()`. :throws: during model creation, :class:`LogicError` if in relaxed mode. .. function:: bool isEnabled() :returns: whether the module is enabled. .. function:: void setForceExistence(bool value) bool getForceExistence() const Control or query whether a solution must be overall autocatalytic. :throws: :class:`LogicError` if the module is not enabled. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. .. function:: void setStrictTransit(bool value) bool getStrictTransit() const Control or query whether transit flow in overall autocatalytic vertices is restricted or not. :throws: :class:`LogicError` if the module is not enabled. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. .. function:: void setBFSExclusive(bool value) bool getBFSExclusive() const Control or query whether vertices must be exclusively overall autocatalytic, as determined by breadth-first marking. :throws: :class:`LogicError` if the module is not enabled. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. Class ``hyperflow::Model::OverallCatalysis`` --------------------------------------------------------------- .. class:: hyperflow::Model::OverallCatalysis This class provides access to the module for :ref:`overall catalysis ` of a flow model. .. function:: void enable() Enable the module. This will automatically call `setAllowReversal(false)` and `setAllowIOReversal(false)`. :throws: :class:`LogicError` if `isSpecificationLocked()`. :throws: during model creation, :class:`LogicError` if in relaxed mode. .. function:: bool isEnabled() :returns: whether the module is enabled. .. function:: void setForceExistence(bool value) bool getForceExistence() const Control or query whether a solution must be overall catalytic. :throws: :class:`LogicError` if the module is not enabled. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. .. function:: void setStrictTransit(bool value) bool getStrictTransit() const Control or query whether transit flow in overall catalytic vertices is restricted or not. :throws: :class:`LogicError` if the module is not enabled. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. Class ``hyperflow::Model::Thermodynamics`` --------------------------------------------------------------- .. class:: hyperflow::Model::Thermodynamics This class provides access to the module for :ref:`thermodynamics module ` of a flow model. .. function:: void enable() Enable the module. :throws: :class:`LogicError` if `isSpecificationLocked()`. :throws: during model creation, :class:`LogicError` if in relaxed mode. :throws: during model creation, :class:`LogicError` if a non-excluded vertex has no energy bounds. .. function:: bool isEnabled() :returns: whether the module is enabled. .. function:: void setTemperature(double value) double getTemperature() const Control or query the temperature, in Kelvin, used in the constraints. :throws: :class:`LogicError` if the module is not enabled. :throws: (only set) :class:`LogicError` if `value` is not a finite non-negative number. :throws: (only set) :class:`LogicError` if `isSpecificationLocked()`. .. function:: void setEnergyBounds(dg::DG::Vertex v, double min, double max) Set the bounds for the energy estimate, in kcal/mol, of the given vertex. The module assumes that stable compounds have energy values less than 0, i.e., a high-energy compound has a more negative energy than a low-energy compound, and the `max` must thus be less than the `min`. :throws: :class:`LogicError` if `isSpecificationLocked()`. :throws: :class:`LogicError` if `!v`. :throws: :class:`LogicError` if `v.getDG() != getDG()`. :throws: :class:`LogicError` if `min` is not a finite non-positive number. :throws: :class:`LogicError` if `max` is not a finite non-positive number less than or equal to `min`. .. function:: void setEnergyBounds(std::shared_ptr g, double min, double max) Equivalent to calling `setEnergyBounds(getDG()->findVertex(g), min, max)`. .. function:: std::pair getEnergyBounds(dg::DG::Vertex v) const :returns: the minimum and maximum bound on the energy estimate for this vertex. :throws: :class:`LogicError` if no bound has been set for this vertex. .. function:: std::pair getEnergyBounds(std::shared_ptr g) const Equivalent to calling `getEnergyBounds(getDG()->findVertex(g))`.