.. _py-dg/DG: ********************************************************** dg/DG ********************************************************** .. default-domain:: py .. py:currentmodule:: mod .. cpp:namespace:: mod .. class:: DG The derivation graph class. A derivation graph is a directed multi-hypergraph :math:`\mathcal{H} = (V, E)`. Each hyperedge :math:`e\in E` is thus an ordered pair :math:`(e^+, e^-)` of multisets of vertices, the sources and the targets. Each vertex is annotated with a graph, and each hyperedge is annotated with list of transformation rules. A derivation graph is constructed incrementally using a :class:`DGBuilder` obtained from the :meth:`build()` function. When the obtained builder is destructed the derivation graph becomes locked and can no longer be modified. .. method:: __init__(*, labelSettings=LabelSettings(LabelType.String, LabelRelation.Isomorphism), \ graphDatabase=[], \ graphPolicy=IsomorphismPolicy.Check) Create an empty unlocked derivation graph object. :param LabelSettings labelSettings: defines which category the derivation graph object works in. All morphism calculations (monomorphism and isomorphism) are thus defined by the :class:`LabelType`, while the :class:`LabelRelation` is used for for monomorphism enumeration. :param graphDatabase: an initial graph database. Any subsequently added or constructed graph for this object will be checked for isomorphism against the graph database. :type graphDatabase: list[Graph] :param IsomorphismPolicy graphPolicy: the policy for how the graphs of ``graphDatabase`` are checked for isomorphism against each other initially. Only use ``IsomorphismPolicy.TrustMe`` if you are absolutely sure that the graphs are unique up to isomorphism. :raises: :class:`LogicError` if ``graphPolicy == IsomorphismPolicy.Check`` and two graphs in ``graphDatabase`` are different objects but represents isomorphic graphs. :raises: :class:`LogicError` if there is a ``None`` in ``graphDatabase``. .. attribute:: id The unique instance id among all :class:`DG` objects. :type: int .. attribute:: labelSettings (Read-only) The label settings for the derivation graph. :type: LabelSettings .. attribute:: hasActiveBuilder (Read-only) Whether :meth:`build` has been called and the returned :class:`DGBuilder` is still active. :type: bool .. attribute:: locked (Read-only) Whether the derivation graph is locked or not. :type: bool .. attribute:: numVertices (Read-only) The number of vertices in the derivation graph. :type: int :raises: :class:`LogicError` if neither ``hasActiveBuilder`` nor ``isLocked``. .. attribute:: vertices (Read-only) An iterable of all vertices in the derivation graph. :type: DGVertexRange :raises: :class:`LogicError` if neither ``hasActiveBuilder`` nor ``isLocked``. .. attribute:: numEdges (Read-only) The number of hyperedges in the derivation graph. :type: int :raises: :class:`LogicError` if neither ``hasActiveBuilder`` nor ``isLocked``. .. attribute:: edges (Read-only) An iterable of all hyperedges in the derivation graph. :type: DGEdgeRange :raises: :class:`LogicError` if neither ``hasActiveBuilder`` nor ``isLocked``. .. method:: findVertex(g) :param Graph g: the graph to find a vertex which has it associated. :returns: a vertex descriptor for which the given graph is associated, or a null descriptor if no such vertex exists. :rtype: DGVertex :raises: :class:`LogicError` if neither ``hasActiveBuilder`` nor ``isLocked``. :raises: :class:`LogicError` if ``g`` is ``None``. .. method:: findEdge(sources, targets) findEdge(sourceGraphs, targetGraphs) :param sources: the list of source vertices the resulting hyperedge must have. :type sources: list[DGVertex] :param targets: the list of targets vertices the resulting hyperedge must have. :type targets: list[DGVertex] :param sourceGraphs: the list of graphs that must be associated with the source vertices the resulting hyperedge must have. :type sourceGraphs: list[Graph] :param targetGraphs: the list of graphs that must be associated with the targets vertices the resulting hyperedge must have. :type targetGraphs: list[Graph] :returns: a hyperedge with the given sources and targets. If no such hyperedge exists in the derivation graph then a null edge is returned. In the second version, the graphs are put through :meth:`findVertex` first. :rtype: DGHyperEdge :raises: :class:`LogicError` if a vertex descriptor is null, or does not belong to the derivation graph. :raises: :class:`LogicError` if neither ``hasActiveBuilder`` nor ``isLocked``. .. method:: build() :returns: an RAII-style object which can be used to construct the derivation graph. It can be used as a context manager in a ``with``-statement (see the documentation of :class:`DGBuilder`). :rtype: DGBuilder :raises: :class:`LogicError` if the DG already has an active builder (see :attr:`hasActiveBuilder`). :raises: :class:`LogicError` if the DG is locked (see :attr:`locked`). .. attribute:: graphDatabase All graphs known to the derivation graph. :type: list[Graph] .. attribute:: products The subset of the vertex graphs which were discovered by the calculation. :type: list[Graph] .. method:: print(printer=DGPrinter(), data=None) Print the derivation graph in style of a hypergraph. The appearance and structure of the visualisation can optionally be configured by giving a DG printer and/or data object. :param DGPrinter printer: the printer to use governing the appearance. :param DGPrintData data: the extra data to use encoding the structure of the graph. :returns: the name of the PDF-file that will be compiled in post-processing and the name of the coordinate tex-file used. :rtype: tuple[str, str] .. method:: printNonHyper() Print the derivation graph in style of a digraph, where each edge represents a hyperedge. Each vertex in the depiction then represents a multiset of vertices in the hypergraph. :returns: the name of the PDF-file that will be compiled in post-processing. :rtype: str .. method:: dump() dump(filename) Exports the derivation graph to a file, including associated graphs and rules. Use :meth:`load` or :meth:`DGBuilder.load` to import the derivation graph again. :param str 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. .. note:: The filename is being used literally, i.e., it is not being prefixed according to the current script location as input filenames are. :returns: the filename of the exported derivation graph. :rtype: str :raises: :class:`LogicError` if the DG is not :attr:`locked`. :raises: :class:`LogicError` if the target file can not be opened. .. method:: listStats() Lists various statistics for the derivation graph. :raises: :class:`LogicError` if the DG has not been calculated. .. staticmethod:: load(graphDatabase, ruleDatabase, f, graphPolicy=IsomorphismPolicy.Check, verbosity=2) Load a derivation graph dump as a locked object. Use :func:`DGBuilder.load` to load a dump into a derivation graph under construction. This is done roughly by making a :class:`DG` with the given `graphDatabase` and `graphPolicy`. The label settings are retrieved from the dump file. Vertices with graphs and hyperedges with rules are then added from the dump. Any graph in the dump which is isomorphic to a given graph is replaced by the given graph. The same procedure is done for the rules. If a graph/rule is not found in the given lists, a new object is instantiated and used. In the end the derivation graph is locked. .. note:: If the dump to be loaded was made by version 0.10 or earlier, it does not contain the full rules but only the rule name. It is then crucial that the names of the given rules match with those used to create the dump in the first place. See :cpp:func:`dg::DG::load` for an explanation of the verbosity levels. :param graphDatabase: A list of graphs that will be given as graph database to :func:`__init__`. :type graphDatabase: list[Graph] :param ruleDatabase: A list of rules used as explained above. :type ruleDatabase: list[Rule] :param f: a DG dump file to load. :type f: str or CWDPath :param IsomorphismPolicy graphPolicy: the policy that will be given as graph policy to :func:`__init__`. :returns: the loaded derivation graph. :rtype: DG :raises: the same exceptions :func:`__init__` raises related to ``graphDatabase`` and ``graphPolicy``. :raises: :class:`LogicError` if there is a ``None`` in ``ruleDatabase``. :raises: :class:`InputError` if the file can not be opened or its content is bad. .. method:: diffDGs(dg1, dg2) Compare two derivation graphs and lists the difference. This is not a general isomorphism check; two vertices are equal if they have the same graph attached. Edges are equal if the head and tail sets are equal and if the attached rule is the same. :param dg1: the first derivation graph. :type dg1: :class:`DG` :param dg2: the second derivation graph. :type dg2: :class:`DG`