3.2.12.3. graph/Graph.hpp

3.2.12.3.1. 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 Graph, Rule, and Molecule Model for more details. See also graph/GraphInterface.hpp for the documentation for the graph interface for this class.

3.2.12.3.1.1. Synopsis

class graph::Graph::Aut
class graph::Graph::AutGroup
std::size_t getId() const
std::size_t numVertices() const
VertexRange vertices() const
std::size_t numEdges() const
EdgeRange edges() const
AutGroup aut(LabelSettings labelSettings) const
std::pair<std::string, std::string> print() const
std::pair<std::string, std::string> print(const Printer &first, const Printer &second) const
void printTermState() const
std::string getGMLString(bool withCoords = false) const
std::string printGML(bool withCoords = false) const
const std::string &getName() const
void setName(std::string name) const
const std::string &getSmiles() const
const std::string &getSmilesWithIds() const
const std::string &getGraphDFS() const
const std::string &getGraphDFSWithIds() const
const std::string &getLinearEncoding() const
bool getIsMolecule() const
double getEnergy() const
void cacheEnergy(double value) const
double getExactMass() const
unsigned int vLabelCount(const std::string &label) const
unsigned int eLabelCount(const std::string &label) const
std::size_t isomorphism(std::shared_ptr<Graph> codomain, std::size_t maxNumMatches, LabelSettings labelSettings) const
std::size_t monomorphism(std::shared_ptr<Graph> codomain, std::size_t maxNumMatches, LabelSettings labelSettings) const
void enumerateIsomorphisms(std::shared_ptr<Graph> codomain, std::shared_ptr<Function<bool(VertexMap<Graph, Graph>)>> callback, LabelSettings labelSettings) const
void enumerateMonomorphisms(std::shared_ptr<Graph> codomain, std::shared_ptr<Function<bool(VertexMap<Graph, Graph>)>> callback, LabelSettings labelSettings) const
std::shared_ptr<Graph> makePermutation() const
void setImage(std::shared_ptr<Function<std::string()>> image)
std::shared_ptr<Function<std::string()>> getImage() const
void setImageCommand(std::string cmd)
std::string getImageCommand() const
void instantiateStereo() const
Vertex getVertexFromExternalId(int id) const
int getMinExternalId() const
int getMaxExternalId() const
std::vector<std::pair<std::string, bool>> getLoadingWarnings() const
static std::shared_ptr<Graph> fromGMLString(const std::string &data, bool printStereoWarnings = true)
static std::shared_ptr<Graph> fromGMLFile(const std::string &file, bool printStereoWarnings = true)
std::vector<std::shared_ptr<Graph>> fromGMLStringMulti(const std::string &data, bool printStereoWarnings = true)
std::vector<std::shared_ptr<Graph>> fromGMLFileMulti(const std::string &file, bool printStereoWarnings = true)
static std::shared_ptr<Graph> fromDFS(const std::string &graphDFS)
static std::vector<std::shared_ptr<Graph>> fromDFSMulti(const std::string &graphDFS)
static std::shared_ptr<Graph> fromSMILES(const std::string &smiles)
static std::shared_ptr<Graph> fromSMILES(const std::string &smiles, bool allowAbstract, SmilesClassPolicy classPolicy, bool printStereoWarnings)
static std::vector<std::shared_ptr<Graph>> fromSMILESMulti(const std::string &smiles)
static std::vector<std::shared_ptr<Graph>> fromSMILESMulti(const std::string &smiles, bool allowAbstract, SmilesClassPolicy classPolicy, bool printStereoWarnings)
static std::shared_ptr<Graph> fromMOLString(const std::string &data, const MDLOptions &options)
static std::shared_ptr<Graph> fromMOLFile(const std::string &file, const MDLOptions &options)
static std::vector<std::shared_ptr<Graph>> fromMOLStringMulti(const std::string &data, const MDLOptions &options)
static std::vector<std::shared_ptr<Graph>> fromMOLFileMulti(const std::string &file, const MDLOptions &options)
static std::vector<std::shared_ptr<Graph>> fromSDString(const std::string &data, const MDLOptions &options)
static std::vector<std::shared_ptr<Graph>> fromSDFile(const std::string &file, const MDLOptions &options)
static std::vector<std::vector<std::shared_ptr<Graph>>> fromSDStringMulti(const std::string &data, const MDLOptions &options)
static std::vector<std::vector<std::shared_ptr<Graph>>> fromSDFileMulti(const std::string &file, const MDLOptions &options)
static std::shared_ptr<Graph> create(std::unique_ptr<lib::Graph::Single> g)
static std::shared_ptr<Graph> create(std::unique_ptr<lib::Graph::Single> g, std::map<int, std::size_t> externalToInternalIds, std::vector<std::pair<std::string, bool>> warnings)
class graph::Graph::Vertex
class graph::Graph::Edge
class graph::Graph::VertexIterator
class graph::Graph::VertexRange
class graph::Graph::EdgeIterator
class graph::Graph::EdgeRange
class graph::Graph::IncidentEdgeIterator
class graph::Graph::IncidentEdgeRange

3.2.12.3.1.2. Details

std::size_t getId() const
Returns:

the unique instance id among Graph objects.

std::size_t numVertices() const
Returns:

the number of vertices in the graph.

VertexRange vertices() const
Returns:

a range of all vertices in the graph.

std::size_t numEdges() const
Returns:

the number of edges in the graph.

EdgeRange edges() const
Returns:

a range of all edges in the graph.

AutGroup aut(LabelSettings labelSettings) const
Returns:

an object representing the automorphism group of the graph.

std::pair<std::string, std::string> print() const
std::pair<std::string, std::string> 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.

void printTermState() const

Print the term state for the graph.

std::string getGMLString(bool withCoords = false) const
Returns:

the GML representation of the graph, optionally with generated 2D coordinates.

Throws:

LogicError when coordinates are requested, but none can be generated.

std::string printGML(bool withCoords = false) const

Print the GML representation of the graph, optionally with generated 2D coordinates.

Returns:

the filename of the printed GML file.

Throws:

LogicError when coordinates are requested, but none can be generated.

const std::string &getName() const
void setName(std::string name) const

Access the name of the graph.

const std::string &getSmiles() const
Returns:

the canonical SMILES string of the graph, if it’s a molecule.

Throws:

LogicError if the graph is not a molecule.

const std::string &getSmilesWithIds() const
Returns:

the canonical SMILES string of the graph, that includes the internal vertex id as a class label on each atom, if it’s a molecule.

Throws:

LogicError if the graph is not a molecule.

const std::string &getGraphDFS() const
Returns:

a GraphDFS string of the graph.

const std::string &getGraphDFSWithIds() const
Returns:

a GraphDFS string of the graph, where each vertex have an explicit id, corresponding to its internal vertex id.

const std::string &getLinearEncoding() const
Returns:

the SMILES string if the graph is a molecule, otherwise the GraphDFS string.

bool getIsMolecule() const
Returns:

whether the graph models a molecule. See Molecule Encoding.

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 Graph::cacheEnergy().

void cacheEnergy(double value) const

If the graph models a molecule, sets the energy to a given value.

Throws:

LogicError if the graph is not a molecule.

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 \(\sum_a (mass(a) - mass(e)\cdot charge(a))\). If an atom has no specified isotope, then the most abundant is used.

Throws:

LogicError if it is not a molecule, including if some isotope has not been tabulated.

unsigned int vLabelCount(const std::string &label) const
Returns:

the number of vertices in the graph with the given label.

unsigned int eLabelCount(const std::string &label) const
Returns:

the number of edges in the graph with the given label.

std::size_t isomorphism(std::shared_ptr<Graph> codomain, std::size_t maxNumMatches, LabelSettings labelSettings) const
std::size_t monomorphism(std::shared_ptr<Graph> 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.

void enumerateIsomorphisms(std::shared_ptr<Graph> codomain, std::shared_ptr<Function<bool(VertexMap<Graph, Graph>)>> callback, LabelSettings labelSettings) const
void enumerateMonomorphisms(std::shared_ptr<Graph> codomain, std::shared_ptr<Function<bool(VertexMap<Graph, Graph>)>> 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:
std::shared_ptr<Graph> makePermutation() const
Returns:

a graph isomorphic to this, but with the vertex indices randomly permuted.

void setImage(std::shared_ptr<Function<std::string()>> 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.

std::shared_ptr<Function<std::string()>> getImage() const
Returns:

the current custom depiction file 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.

std::string getImageCommand() const
Returns:

the current post-processing command.

void instantiateStereo() const

Make sure that stereo data is instantiated.

Throws:

StereoDeductionError if the data was not instantiated and deduction failed.

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.

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 getVertexFromExternalId(). If no such minimum and maximum exists, then 0 will be returned.

std::vector<std::pair<std::string, bool>> 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:

LogicError if the graph does not have data from external loading

static std::shared_ptr<Graph> fromGMLString(const std::string &data, bool printStereoWarnings = true)
static std::shared_ptr<Graph> fromGMLFile(const std::string &file, bool printStereoWarnings = true)
Parameters:

printStereoWarnings – whether to print warnings due to unhandled stereo information.

Returns:

a graph created from the given GML in a string or file. The graph must be connected. Use fromGMLStringMulti() or fromGMLFile() if it is not.

Throws:

InputError on bad input.

std::vector<std::shared_ptr<Graph>> fromGMLStringMulti(const std::string &data, bool printStereoWarnings = true)
std::vector<std::shared_ptr<Graph>> fromGMLFileMulti(const std::string &file, bool printStereoWarnings = true)
Parameters:

printStereoWarnings – whether to print warnings due to unhandled stereo information.

Returns:

a list of graphs, loaded from the given GML in a string or file. The graphs are the connected components of the graph specified in the data.

Throws:

InputError on bad input.

static std::shared_ptr<Graph> fromDFS(const std::string &graphDFS)
Returns:

a graph loaded from the given GraphDFS string. The graph must be connected. Use fromDFSMulti() if it is not.

Throws:

InputError on bad input.

static std::vector<std::shared_ptr<Graph>> fromDFSMulti(const std::string &graphDFS)
Returns:

a list of graphs loaded from the given GraphDFS string. The graphs are the connected components of the graph specified in the data.

Throws:

InputError on bad input.

static std::shared_ptr<Graph> fromSMILES(const std::string &smiles)
static std::shared_ptr<Graph> fromSMILES(const std::string &smiles, bool allowAbstract, SmilesClassPolicy classPolicy, bool printStereoWarnings)
Parameters:

  • printStereoWarnings – whether to print warnings due to unhandled stereo information. Defaults to true.

  • allowAbstract – whether abstract atoms, e.g., *, are allowed. Defaults to false.

  • classPolicy – which policy to use for class labels. Defaults to SmilesClassPolicy::NoneOnDuplicate.

Returns:

a graph representing a molecule, loaded from the given SMILES string. The graph must be connected. Use fromSMILESMulti() if it is not.

Throws:

InputError on bad input.

Throws:

InputError if classPolicy == SmilesClassPolicy::NoneOnDuplicate and a class label is duplicated.

static std::vector<std::shared_ptr<Graph>> fromSMILESMulti(const std::string &smiles)
static std::vector<std::shared_ptr<Graph>> fromSMILESMulti(const std::string &smiles, bool allowAbstract, SmilesClassPolicy classPolicy, bool printStereoWarnings)

See fromSMILES() for parameter and exception descriptions.

Returns:

a list of graphs representing molecules, loaded from the given SMILES string. The graphs are the connected components of the graph specified in the SMILES string.

static std::shared_ptr<Graph> fromMOLString(const std::string &data, const MDLOptions &options)
static std::shared_ptr<Graph> fromMOLFile(const std::string &file, const MDLOptions &options)
Returns:

a graph created from the given MOL data.

Throws:

InputError on bad input.

static std::vector<std::shared_ptr<Graph>> fromMOLStringMulti(const std::string &data, const MDLOptions &options)
static std::vector<std::shared_ptr<Graph>> fromMOLFileMulti(const std::string &file, const MDLOptions &options)

See fromMOLString() and fromMOLFile() for parameter and exception descriptions.

Returns:

a list of graphs representing molecules, loaded from the given string or file with MOL data. The graphs are the connected components of the graph specified in the data.

static std::vector<std::shared_ptr<Graph>> fromSDString(const std::string &data, const MDLOptions &options)
static std::vector<std::shared_ptr<Graph>> fromSDFile(const std::string &file, const MDLOptions &options)
Returns:

a list of graphs created from the given SD data.

Throws:

InputError on bad input.

static std::vector<std::vector<std::shared_ptr<Graph>>> fromSDStringMulti(const std::string &data, const MDLOptions &options)
static std::vector<std::vector<std::shared_ptr<Graph>>> fromSDFileMulti(const std::string &file, const MDLOptions &options)
Returns:

a list of lists of graphs created from the given SD data.

Throws:

InputError on bad input.

static std::shared_ptr<Graph> create(std::unique_ptr<lib::Graph::Single> g)
static std::shared_ptr<Graph> create(std::unique_ptr<lib::Graph::Single> g, std::map<int, std::size_t> externalToInternalIds, std::vector<std::pair<std::string, bool>> warnings)
Parameters:

  • externalToInternalIds – map from user-defined integers to the vertex indices of g. See also getVertexFromExternalId().

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