.. _cpp-graph/Graph: ********************************************************** graph/Graph.hpp ********************************************************** .. default-domain:: cpp .. default-role:: cpp:expr .. py:currentmodule:: mod .. cpp:namespace:: mod Class ``graph::Graph`` -------------------------------------------------------------------------------------------------------------------------------- .. class:: graph::Graph This class models an undirected graph with labels on vertices and edges, without loops and without parallel edges. See :ref:`graph-model` for more details. See also :ref:`cpp-graph/GraphInterface` for the documentation for the graph interface for this class. Synopsis ^^^^^^^^ .. alias:: graph::Graph :maxdepth: 2 :noroot: Details ^^^^^^^ .. cpp:namespace-push:: graph::Graph .. function:: std::size_t getId() const :returns: the unique instance id among :class:`Graph` objects. .. function:: std::size_t numVertices() const :returns: the number of vertices in the graph. .. function:: VertexRange vertices() const :returns: a range of all vertices in the graph. .. function:: std::size_t numEdges() const :returns: the number of edges in the graph. .. function:: EdgeRange edges() const :returns: a range of all edges in the graph. .. function:: AutGroup aut(LabelSettings labelSettings) const :returns: an object representing the automorphism group of the graph. .. function:: std::pair print() const std::pair print(const Printer &first, const Printer &second) const Print the graph, using either the default options or the options in `first` and `second`. If `first` and `second` are the same, only one depiction will be made. :returns: a pair of names for the PDF-files that will be compiled in post-processing. If `first` and `second` are the same, the two file prefixes are equal. .. function:: void printTermState() const Print the term state for the graph. .. function:: std::string getGMLString(bool withCoords = false) const :returns: the :ref:`GML ` representation of the graph, optionally with generated 2D coordinates. :throws: :any:`LogicError` when coordinates are requested, but none can be generated. .. function:: std::string printGML(bool withCoords = false) const Print the :ref:`GML ` representation of the graph, optionally with generated 2D coordinates. :returns: the filename of the printed GML file. :throws: :any:`LogicError` when coordinates are requested, but none can be generated. .. function:: const std::string &getName() const void setName(std::string name) const Access the name of the graph. .. function:: const std::string &getSmiles() const :returns: the canonical :ref:`SMILES string ` of the graph, if it's a molecule. :throws: :any:`LogicError` if the graph is not a molecule. .. function:: const std::string &getSmilesWithIds() const :returns: the canonical :ref:`SMILES string ` of the graph, that includes the internal vertex id as a class label on each atom, if it's a molecule. :throws: :any:`LogicError` if the graph is not a molecule. .. function:: const std::string &getGraphDFS() const :returns: a :ref:`GraphDFS ` string of the graph. .. function:: const std::string &getGraphDFSWithIds() const :returns: a :ref:`GraphDFS ` string of the graph, where each vertex have an explicit id, corresponding to its internal vertex id. .. function:: const std::string &getLinearEncoding() const :returns: the :ref:`SMILES ` string if the graph is a molecule, otherwise the :ref:`GraphDFS ` string. .. function:: bool getIsMolecule() const :returns: whether the graph models a molecule. See :ref:`mol-enc`. .. function:: double getEnergy() const :returns: some energy value if the graph is a molecule. The energy is calculated using Open Babel, unless already calculated or cached by :cpp:func:`Graph::cacheEnergy`. .. function:: void cacheEnergy(double value) const If the graph models a molecule, sets the energy to a given value. :throws: :class:`LogicError` if the graph is not a molecule. .. function:: double getExactMass() const :returns: the exact mass of the graph, if it is a molecule. It is the sum of the exact mass of each atom, with the mass of electrons subtracted corresponding to the integer charge. That is, the mass is :math:`\sum_a (mass(a) - mass(e)\cdot charge(a))`. If an atom has no specified isotope, then the most abundant is used. :throws: :class:`LogicError` if it is not a molecule, including if some isotope has not been tabulated. .. function:: unsigned int vLabelCount(const std::string &label) const :returns: the number of vertices in the graph with the given label. .. function:: unsigned int eLabelCount(const std::string &label) const :returns: the number of edges in the graph with the given label. .. function:: std::size_t isomorphism(std::shared_ptr codomain, std::size_t maxNumMatches, LabelSettings labelSettings) const std::size_t monomorphism(std::shared_ptr codomain, std::size_t maxNumMatches, LabelSettings labelSettings) const :returns: the number of isomorphisms/monomorphisms found from this graph to `codomain`, but at most `maxNumMatches`. :throws LogicError: if `codomain` is null. .. function:: void enumerateIsomorphisms(std::shared_ptr codomain, \ std::shared_ptr)>> callback, \ LabelSettings labelSettings) const void enumerateMonomorphisms(std::shared_ptr codomain, \ std::shared_ptr)>> callback, \ LabelSettings labelSettings) const Perform (sub)structure search of this graph into the given codomain graph. Whenever a match is found, the corresponding isomorphism/monomorphism is copied into a vertex map and the given callback is invoked with it. The return value from the callback determines whether to continue the search or not. :throws LogicError: if `codomain` is null. :throws LogicError: if `callback` is null. .. function:: std::shared_ptr makePermutation() const :returns: a graph isomorphic to this, but with the vertex indices randomly permuted. .. note: Currently, permuting stereo-information is not supported, and the resulting graphs thus have any stereo-information stripped. .. function:: void setImage(std::shared_ptr> image) Set a custom depiction for the graph. The depiction file used will be the string returned by the given function, with ``.pdf`` appended. The function will only be called once. Give `nullptr` to use auto-generated depiction. .. function:: std::shared_ptr > getImage() const :returns: the current custom depiction file function. .. function:: void setImageCommand(std::string cmd) Set a command to be run in post-processing if a custom depiction is set. The command is only run once. .. function:: std::string getImageCommand() const :returns: the current post-processing command. .. function:: void instantiateStereo() const Make sure that stereo data is instantiated. :throws: `StereoDeductionError` if the data was not instantiated and deduction failed. .. function:: Vertex getVertexFromExternalId(int id) const If the graph was not loaded from an external data format, then this function always return a null descriptor. If the graph was loaded from a SMILES string, but *any* class label was not unique, then the function always return a null descriptor. .. note:: In general there is no correlation between external and internal ids. :returns: the vertex descriptor for the given external id. The descriptor is null if the external id was not used. .. function:: int getMinExternalId() const int getMaxExternalId() const If the graph was not loaded from an external data format, then these functions always return 0. Otherwise, return the minimum/maximum external id from which non-null vertices can be obtained from :cpp:func:`getVertexFromExternalId`. If no such minimum and maximum exists, then 0 will be returned. .. function:: std::vector> getLoadingWarnings() const :returns: the list of warnings stored when the graph was created from an external format. Each entry is a message and then an indicator of whether the warning was printed before construction (``true``), or was a silenced warning (``false``). :throws: :class:`LogicError` if the graph does not have data from external loading .. function:: static std::shared_ptr fromGMLString(const std::string &data, bool printStereoWarnings = true) static std::shared_ptr fromGMLFile(const std::string &file, bool printStereoWarnings = true) :param printStereoWarnings: whether to print warnings due to unhandled stereo information. :returns: a graph created from the given :ref:`GML ` in a string or file. The graph must be connected. Use :func:`fromGMLStringMulti` or :func:`fromGMLFile` if it is not. :throws: :class:`InputError` on bad input. .. function:: std::vector> fromGMLStringMulti(const std::string &data, bool printStereoWarnings = true) std::vector> fromGMLFileMulti(const std::string &file, bool printStereoWarnings = true) :param printStereoWarnings: whether to print warnings due to unhandled stereo information. :returns: a list of graphs, loaded from the given :ref:`GML ` in a string or file. The graphs are the connected components of the graph specified in the data. :throws: :class:`InputError` on bad input. .. function:: static std::shared_ptr fromDFS(const std::string &graphDFS) :returns: a graph loaded from the given :ref:`GraphDFS ` string. The graph must be connected. Use :func:`fromDFSMulti` if it is not. :throws: :class:`InputError` on bad input. .. function:: static std::vector> fromDFSMulti(const std::string &graphDFS) :returns: a list of graphs loaded from the given :ref:`GraphDFS ` string. The graphs are the connected components of the graph specified in the data. :throws: :class:`InputError` on bad input. .. function:: static std::shared_ptr fromSMILES(const std::string &smiles) static std::shared_ptr fromSMILES(const std::string &smiles, bool allowAbstract, \ SmilesClassPolicy classPolicy, bool printStereoWarnings) :param printStereoWarnings: whether to print warnings due to unhandled stereo information. Defaults to `true`. :param allowAbstract: whether abstract atoms, e.g., ``*``, are allowed. Defaults to `false`. :param classPolicy: which policy to use for class labels. Defaults to `SmilesClassPolicy::NoneOnDuplicate`. :returns: a graph representing a molecule, loaded from the given :ref:`SMILES ` string. The graph must be connected. Use :func:`fromSMILESMulti` if it is not. :throws: :class:`InputError` on bad input. :throws: :class:`InputError` if `classPolicy == SmilesClassPolicy::NoneOnDuplicate` and a class label is duplicated. .. function:: static std::vector> fromSMILESMulti(const std::string &smiles) static std::vector> fromSMILESMulti(const std::string &smiles, bool allowAbstract, \ SmilesClassPolicy classPolicy, bool printStereoWarnings) See :func:`fromSMILES` for parameter and exception descriptions. :returns: a list of graphs representing molecules, loaded from the given :ref:`SMILES ` string. The graphs are the connected components of the graph specified in the SMILES string. .. function:: static std::shared_ptr fromMOLString(const std::string &data, const MDLOptions &options) static std::shared_ptr fromMOLFile(const std::string &file, const MDLOptions &options) :returns: a graph created from the given :ref:`MOL ` data. :throws: :class:`InputError` on bad input. .. function:: static std::vector> fromMOLStringMulti(const std::string &data, const MDLOptions &options) static std::vector> fromMOLFileMulti(const std::string &file, const MDLOptions &options) See :func:`fromMOLString` and :func:`fromMOLFile` for parameter and exception descriptions. :returns: a list of graphs representing molecules, loaded from the given string or file with :ref:`MOL ` data. The graphs are the connected components of the graph specified in the data. .. function:: static std::vector> fromSDString(const std::string &data, const MDLOptions &options) static std::vector> fromSDFile(const std::string &file, const MDLOptions &options) :returns: a list of graphs created from the given :ref:`SD ` data. :throws: :class:`InputError` on bad input. .. function:: static std::vector>> fromSDStringMulti(const std::string &data, const MDLOptions &options) static std::vector>> fromSDFileMulti(const std::string &file, const MDLOptions &options) :returns: a list of lists of graphs created from the given :ref:`SD ` data. :throws: :class:`InputError` on bad input. .. function:: static std::shared_ptr create(std::unique_ptr g) static std::shared_ptr create(std::unique_ptr g, \ std::map externalToInternalIds, \ std::vector> warnings) :param externalToInternalIds: map from user-defined integers to the vertex indices of ``g``. See also :cpp:func:`getVertexFromExternalId`. :param warnings: a list of warning messages to store. The second component is supposed to indicate whether the warning was printed before construction (``true``), or was a silenced warning (``false``). See also :cpp:func:`getLoadingWarnings`. :returns: a graph wrapping the given internal graph object. The second version instantiates a structure holding the given data created from an external data source. .. cpp:namespace-pop::