diff options
Diffstat (limited to 'lib/stdlib/doc/src/digraph_utils.xml')
| -rw-r--r-- | lib/stdlib/doc/src/digraph_utils.xml | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/digraph_utils.xml b/lib/stdlib/doc/src/digraph_utils.xml new file mode 100644 index 0000000000..4b137456b3 --- /dev/null +++ b/lib/stdlib/doc/src/digraph_utils.xml @@ -0,0 +1,426 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2000</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>digraph_utils</title> + <prepared>Hans Bolinder</prepared> + <responsible>nobody</responsible> + <docno></docno> + <approved>nobody</approved> + <checked>no</checked> + <date>2001-08-27</date> + <rev>PA1</rev> + <file>digraph_utils.sgml</file> + </header> + <module>digraph_utils</module> + <modulesummary>Algorithms for Directed Graphs</modulesummary> + <description> + <p>The <c>digraph_utils</c> module implements some algorithms + based on depth-first traversal of directed graphs. See the + <c>digraph</c> module for basic functions on directed graphs. + </p> + <p>A <marker id="digraph"></marker><em>directed graph</em> (or + just "digraph") is a pair (V, E) of a finite set V of + <marker id="vertex"></marker><em>vertices</em> and a finite set E + of <marker id="edge"></marker><em>directed edges</em> (or just + "edges"). The set of edges E is a subset of V × V + (the Cartesian product of V with itself). + </p> + <p>Digraphs can be annotated with additional information. Such + information may be attached to the vertices and to the edges of + the digraph. A digraph which has been annotated is called a + <em>labeled digraph</em>, and the information attached to a + vertex or an edge is called a <marker id="label"></marker> + <em>label</em>.</p> + <p>An edge e = (v, w) is said + to <marker id="emanate"></marker><em>emanate</em> from vertex v and + to be <marker id="incident"></marker><em>incident</em> on vertex w. + If there is an edge emanating from v and incident on w, then w is + said to be + an <marker id="out_neighbour"></marker><em>out-neighbour</em> of v, + and v is said to be + an <marker id="in_neighbour"></marker><em>in-neighbour</em> of w. + A <marker id="path"></marker><em>path</em> P from v[1] to v[k] in a + digraph (V, E) is a non-empty sequence + v[1], v[2], ..., v[k] of vertices in V such that + there is an edge (v[i],v[i+1]) in E for + 1 <= i < k. + The <marker id="length"></marker><em>length</em> of the path P is k-1. + P is a <marker id="cycle"></marker><em>cycle</em> if the length of P + is not zero and v[1] = v[k]. + A <marker id="loop"></marker><em>loop</em> is a cycle of length one. + An <marker id="acyclic_digraph"></marker><em>acyclic digraph</em> is + a digraph that has no cycles. + </p> + + <p>A <marker id="depth_first_traversal"></marker> <em>depth-first + traversal</em> of a directed digraph can be viewed as a process + that visits all vertices of the digraph. Initially, all vertices + are marked as unvisited. The traversal starts with an + arbitrarily chosen vertex, which is marked as visited, and + follows an edge to an unmarked vertex, marking that vertex. The + search then proceeds from that vertex in the same fashion, until + there is no edge leading to an unvisited vertex. At that point + the process backtracks, and the traversal continues as long as + there are unexamined edges. If there remain unvisited vertices + when all edges from the first vertex have been examined, some + hitherto unvisited vertex is chosen, and the process is + repeated. + </p> + <p>A <marker id="partial_ordering"></marker><em>partial ordering</em> of + a set S is a transitive, antisymmetric and reflexive relation + between the objects of S. The problem + of <marker id="topsort"></marker><em>topological sorting</em> is to + find a total + ordering of S that is a superset of the partial ordering. A + digraph G = (V, E) is equivalent to a relation E + on V (we neglect the fact that the version of directed graphs + implemented in the <c>digraph</c> module allows multiple edges + between vertices). If the digraph has no cycles of length two or + more, then the reflexive and transitive closure of E is a + partial ordering. + </p> + <p>A <marker id="subgraph"></marker><em>subgraph</em> G' of G is a + digraph whose vertices and edges form subsets of the vertices + and edges of G. G' is <em>maximal</em> with respect to a + property P if all other subgraphs that include the vertices of + G' do not have the property P. A <marker + id="strong_components"></marker> <em>strongly connected + component</em> is a maximal subgraph such that there is a path + between each pair of vertices. A <marker + id="components"></marker><em>connected component</em> is a + maximal subgraph such that there is a path between each pair of + vertices, considering all edges undirected. An <marker + id="arborescence"></marker><em>arborescence</em> is an acyclic + digraph with a vertex V, the <marker + id="root"></marker><em>root</em>, such that there is a unique + path from V to every other vertex of G. A <marker + id="tree"></marker><em>tree</em> is an acyclic non-empty digraph + such that there is a unique path between every pair of vertices, + considering all edges undirected.</p> + </description> + + <funcs> + <func> + <name>arborescence_root(Digraph) -> no | {yes, Root}</name> + <fsummary>Check if a digraph is an arborescence.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Root = vertex()</v> + </type> + <desc> + + <p>Returns <c>{yes, Root}</c> if <c>Root</c> is + the <seealso marker="#root">root</seealso> of the arborescence + <c>Digraph</c>, <c>no</c> otherwise. + </p> + </desc> + </func> + <func> + <name>components(Digraph) -> [Component]</name> + <fsummary>Return the components of a digraph.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Component = [vertex()]</v> + </type> + <desc> + <p>Returns a list + of <seealso marker="#components">connected components</seealso>. + Each component is represented by its + vertices. The order of the vertices and the order of the + components are arbitrary. Each vertex of the digraph + <c>Digraph</c> occurs in exactly one component. + </p> + </desc> + </func> + <func> + <name>condensation(Digraph) -> CondensedDigraph</name> + <fsummary>Return a condensed graph of a digraph.</fsummary> + <type> + <v>Digraph = CondensedDigraph = digraph()</v> + </type> + <desc> + <p>Creates a digraph where the vertices are + the <seealso marker="#strong_components">strongly connected + components</seealso> of <c>Digraph</c> as returned by + <c>strong_components/1</c>. If X and Y are strongly + connected components, and there exist vertices x and y in X + and Y respectively such that there is an + edge <seealso marker="#emanate">emanating</seealso> from x + and <seealso marker="#incident">incident</seealso> on y, then + an edge emanating from X and incident on Y is created. + </p> + <p>The created digraph has the same type as <c>Digraph</c>. + All vertices and edges have the + default <seealso marker="#label">label</seealso> <c>[]</c>. + </p> + <p>Each and every <seealso marker="#cycle">cycle</seealso> is + included in some strongly connected component, which implies + that there always exists + a <seealso marker="#topsort">topological ordering</seealso> of the + created digraph.</p> + </desc> + </func> + <func> + <name>cyclic_strong_components(Digraph) -> [StrongComponent]</name> + <fsummary>Return the cyclic strong components of a digraph.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>StrongComponent = [vertex()]</v> + </type> + <desc> + <p>Returns a list of <seealso marker="#strong_components">strongly + connected components</seealso>. + Each strongly component is represented + by its vertices. The order of the vertices and the order of + the components are arbitrary. Only vertices that are + included in some <seealso marker="#cycle">cycle</seealso> in + <c>Digraph</c> are returned, otherwise the returned list is + equal to that returned by <c>strong_components/1</c>. + </p> + </desc> + </func> + <func> + <name>is_acyclic(Digraph) -> bool()</name> + <fsummary>Check if a digraph is acyclic.</fsummary> + <type> + <v>Digraph = digraph()</v> + </type> + <desc> + <p>Returns <c>true</c> if and only if the digraph + <c>Digraph</c> is <seealso marker="#acyclic_digraph">acyclic</seealso>.</p> + </desc> + </func> + <func> + <name>is_arborescence(Digraph) -> bool()</name> + <fsummary>Check if a digraph is an arborescence.</fsummary> + <type> + <v>Digraph = digraph()</v> + </type> + <desc> + <p>Returns <c>true</c> if and only if the digraph + <c>Digraph</c> is + an <seealso marker="#arborescence">arborescence</seealso>.</p> + </desc> + </func> + <func> + <name>is_tree(Digraph) -> bool()</name> + <fsummary>Check if a digraph is a tree.</fsummary> + <type> + <v>Digraph = digraph()</v> + </type> + <desc> + <p>Returns <c>true</c> if and only if the digraph + <c>Digraph</c> is + a <seealso marker="#tree">tree</seealso>.</p> + </desc> + </func> + <func> + <name>loop_vertices(Digraph) -> Vertices</name> + <fsummary>Return the vertices of a digraph included in some loop.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Vertices = [vertex()]</v> + </type> + <desc> + <p>Returns a list of all vertices of <c>Digraph</c> that are + included in some <seealso marker="#loop">loop</seealso>.</p> + </desc> + </func> + <func> + <name>postorder(Digraph) -> Vertices</name> + <fsummary>Return the vertices of a digraph in post-order.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Vertices = [vertex()]</v> + </type> + <desc> + <p>Returns all vertices of the digraph <c>Digraph</c>. The + order is given by + a <seealso marker="#depth_first_traversal">depth-first + traversal</seealso> of the digraph, collecting visited + vertices in postorder. More precisely, the vertices visited + while searching from an arbitrarily chosen vertex are + collected in postorder, and all those collected vertices are + placed before the subsequently visited vertices. + </p> + </desc> + </func> + <func> + <name>preorder(Digraph) -> Vertices</name> + <fsummary>Return the vertices of a digraph in pre-order.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Vertices = [vertex()]</v> + </type> + <desc> + <p>Returns all vertices of the digraph <c>Digraph</c>. The + order is given by + a <seealso marker="#depth_first_traversal">depth-first + traversal</seealso> of the digraph, collecting visited + vertices in pre-order.</p> + </desc> + </func> + <func> + <name>reachable(Vertices, Digraph) -> Vertices</name> + <fsummary>Return the vertices reachable from some vertices of a digraph.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Vertices = [vertex()]</v> + </type> + <desc> + <p>Returns an unsorted list of digraph vertices such that for + each vertex in the list, there is + a <seealso marker="#path">path</seealso> in <c>Digraph</c> from some + vertex of <c>Vertices</c> to the vertex. In particular, + since paths may have length zero, the vertices of + <c>Vertices</c> are included in the returned list. + </p> + </desc> + </func> + <func> + <name>reachable_neighbours(Vertices, Digraph) -> Vertices</name> + <fsummary>Return the neighbours reachable from some vertices of a digraph.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Vertices = [vertex()]</v> + </type> + <desc> + <p>Returns an unsorted list of digraph vertices such that for + each vertex in the list, there is + a <seealso marker="#path">path</seealso> in <c>Digraph</c> of length + one or more from some vertex of <c>Vertices</c> to the + vertex. As a consequence, only those vertices + of <c>Vertices</c> that are included in + some <seealso marker="#cycle">cycle</seealso> are returned. + </p> + </desc> + </func> + <func> + <name>reaching(Vertices, Digraph) -> Vertices</name> + <fsummary>Return the vertices that reach some vertices of a digraph.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Vertices = [vertex()]</v> + </type> + <desc> + <p>Returns an unsorted list of digraph vertices such that for + each vertex in the list, there is + a <seealso marker="#path">path</seealso> from the vertex to some + vertex of <c>Vertices</c>. In particular, since paths may have + length zero, the vertices of <c>Vertices</c> are included in + the returned list. + </p> + </desc> + </func> + <func> + <name>reaching_neighbours(Vertices, Digraph) -> Vertices</name> + <fsummary>Return the neighbours that reach some vertices of a digraph.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Vertices = [vertex()]</v> + </type> + <desc> + <p>Returns an unsorted list of digraph vertices such that for + each vertex in the list, there is + a <seealso marker="#path">path</seealso> of length one or more + from the vertex to some vertex of <c>Vertices</c>. As a consequence, + only those vertices of <c>Vertices</c> that are included in + some <seealso marker="#cycle">cycle</seealso> are returned. + </p> + </desc> + </func> + <func> + <name>strong_components(Digraph) -> [StrongComponent]</name> + <fsummary>Return the strong components of a digraph.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>StrongComponent = [vertex()]</v> + </type> + <desc> + <p>Returns a list of <seealso marker="#strong_components">strongly + connected components</seealso>. + Each strongly component is represented + by its vertices. The order of the vertices and the order of + the components are arbitrary. Each vertex of the digraph + <c>Digraph</c> occurs in exactly one strong component. + </p> + </desc> + </func> + <func> + <name>subgraph(Digraph, Vertices [, Options]) -> Subgraph</name> + <fsummary>Return a subgraph of a digraph.</fsummary> + <type> + <v>Digraph = Subgraph = digraph()</v> + <v>Options = [{type, SubgraphType}, {keep_labels, bool()}]</v> + <v>SubgraphType = inherit | type()</v> + <v>Vertices = [vertex()]</v> + </type> + <desc> + <p>Creates a maximal <seealso marker="#subgraph">subgraph</seealso> of <c>Digraph</c> having + as vertices those vertices of <c>Digraph</c> that are + mentioned in <c>Vertices</c>. + </p> + <p>If the value of the option <c>type</c> is <c>inherit</c>, + which is the default, then the type of <c>Digraph</c> is used + for the subgraph as well. Otherwise the option value of <c>type</c> + is used as argument to <c>digraph:new/1</c>. + </p> + <p>If the value of the option <c>keep_labels</c> is <c>true</c>, + which is the default, then + the <seealso marker="#label">labels</seealso> of vertices and edges + of <c>Digraph</c> are used for the subgraph as well. If the value + is <c>false</c>, then the default label, <c>[]</c>, is used + for the subgraph's vertices and edges. + </p> + <p><c>subgraph(Digraph, Vertices)</c> is equivalent to + <c>subgraph(Digraph, Vertices, [])</c>. + </p> + <p>There will be a <c>badarg</c> exception if any of the arguments + are invalid. + </p> + </desc> + </func> + <func> + <name>topsort(Digraph) -> Vertices | false</name> + <fsummary>Return a topological sorting of the vertices of a digraph.</fsummary> + <type> + <v>Digraph = digraph()</v> + <v>Vertices = [vertex()]</v> + </type> + <desc> + <p>Returns a <seealso marker="#topsort">topological + ordering</seealso> of the vertices of the digraph + <c>Digraph</c> if such an ordering exists, <c>false</c> + otherwise. For each vertex in the returned list, there are + no <seealso marker="#out_neighbour">out-neighbours</seealso> + that occur earlier in the list.</p> + </desc> + </func> + </funcs> + + <section> + <title>See Also</title> + <p><seealso marker="digraph">digraph(3)</seealso></p> + </section> +</erlref> + |