diff options
Diffstat (limited to 'lib/stdlib/doc/src/digraph_utils.xml')
| -rw-r--r-- | lib/stdlib/doc/src/digraph_utils.xml | 452 |
1 files changed, 250 insertions, 202 deletions
diff --git a/lib/stdlib/doc/src/digraph_utils.xml b/lib/stdlib/doc/src/digraph_utils.xml index e481711c50..cb316e5b93 100644 --- a/lib/stdlib/doc/src/digraph_utils.xml +++ b/lib/stdlib/doc/src/digraph_utils.xml @@ -24,100 +24,132 @@ <title>digraph_utils</title> <prepared>Hans Bolinder</prepared> - <responsible>nobody</responsible> + <responsible></responsible> <docno></docno> - <approved>nobody</approved> - <checked>no</checked> + <approved></approved> + <checked></checked> <date>2001-08-27</date> <rev>PA1</rev> - <file>digraph_utils.sgml</file> + <file>digraph_utils.xml</file> </header> <module>digraph_utils</module> - <modulesummary>Algorithms for Directed Graphs</modulesummary> + <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>This module provides algorithms based on depth-first traversal of + directed graphs. For basic functions on directed graphs, see the + <seealso marker="digraph"><c>digraph(3)</c></seealso> module.</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> + <list type="bulleted"> + <item> + <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> + </item> + <item> + <p>Digraphs can be annotated with more information. Such information + can be attached to the vertices and to the edges of the digraph. An + annotated digraph 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> + </item> + <item> + <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.</p> + </item> + <item> + <p>If an edge is emanating from v and incident on w, then w is + said to be an <marker id="out_neighbour"></marker> + <em>out-neighbor</em> of v, and v is said to be an + <marker id="in_neighbour"></marker><em>in-neighbor</em> of w.</p> + </item> + <item> + <p>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.</p> + </item> + <item> + <p>The <marker id="length"></marker><em>length</em> of path P is + k-1.</p> + </item> + <item> + <p>Path P is a <marker id="cycle"></marker><em>cycle</em> if the + length of P is not zero and v[1] = v[k].</p> + </item> + <item> + <p>A <marker id="loop"></marker><em>loop</em> is a cycle of length + one.</p> + </item> + <item> + <p>An <marker id="acyclic_digraph"></marker><em>acyclic digraph</em> + is a digraph without cycles.</p> + </item> + <item> + <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 unvisited vertices remain + when all edges from the first vertex have been examined, some + so far unvisited vertex is chosen, and the process is repeated.</p> + </item> + <item> + <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.</p> + </item> + <item> + <p>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 that the version of directed graphs + provided by the <c>digraph</c> module allows multiple edges + between vertices). If the digraph has no cycles of length two or + more, the reflexive and transitive closure of E is a + partial ordering.</p> + </item> + <item> + <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.</p> + </item> + <item> + <p>G' is <em>maximal</em> with respect to a property P if all other + subgraphs that include the vertices of G' do not have property P.</p> + </item> + <item> + <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.</p> + </item> + <item> + <p>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.</p> + </item> + <item> + <p>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.</p> + </item> + <item> + <p>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> + </item> + </list> </description> <funcs> @@ -125,237 +157,253 @@ <name name="arborescence_root" arity="1"/> <fsummary>Check if a digraph is an arborescence.</fsummary> <desc> - <p>Returns <c>{yes, <anno>Root</anno>}</c> if <c><anno>Root</anno></c> is - the <seealso marker="#root">root</seealso> of the arborescence - <c><anno>Digraph</anno></c>, <c>no</c> otherwise. - </p> + <p>Returns <c>{yes, <anno>Root</anno>}</c> if <c><anno>Root</anno></c> + is the <seealso marker="#root">root</seealso> of the arborescence + <c><anno>Digraph</anno></c>, otherwise <c>no</c>.</p> </desc> </func> + <func> <name name="components" arity="1"/> <fsummary>Return the components of a digraph.</fsummary> <desc> - <p>Returns a list - of <seealso marker="#components">connected components</seealso>. - Each component is represented by its + <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><anno>Digraph</anno></c> occurs in exactly one component. - </p> + components are arbitrary. Each vertex of digraph + <c><anno>Digraph</anno></c> occurs in exactly one component.</p> </desc> </func> + <func> <name name="condensation" arity="1"/> <fsummary>Return a condensed graph of a digraph.</fsummary> <desc> - <p>Creates a digraph where the vertices are - the <seealso marker="#strong_components">strongly connected - components</seealso> of <c><anno>Digraph</anno></c> as returned by - <c>strong_components/1</c>. If X and Y are two different 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>Creates a digraph where the vertices are + the <seealso marker="#strong_components">strongly connected + components</seealso> of <c><anno>Digraph</anno></c> as returned by + <seealso marker="#strong_components/1"> + <c>strong_components/1</c></seealso>. + If X and Y are two different strongly + connected components, and vertices x and y exist 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><anno>Digraph</anno></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> + All vertices and edges have the + default <seealso marker="#label">label</seealso> <c>[]</c>.</p> + <p>Each <seealso marker="#cycle">cycle</seealso> is + included in some strongly connected component, which implies that + a <seealso marker="#topsort">topological ordering</seealso> of the + created digraph always exists.</p> </desc> </func> + <func> <name name="cyclic_strong_components" arity="1"/> <fsummary>Return the cyclic strong components of a digraph.</fsummary> <desc> - <p>Returns a list of <seealso marker="#strong_components">strongly - connected components</seealso>. - Each strongly component is represented + <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><anno>Digraph</anno></c> are returned, otherwise the returned list is - equal to that returned by <c>strong_components/1</c>. - </p> + <c><anno>Digraph</anno></c> are returned, otherwise the returned + list is equal to that returned by + <seealso marker="#strong_components/1"> + <c>strong_components/1</c></seealso>.</p> </desc> </func> + <func> <name name="is_acyclic" arity="1"/> <fsummary>Check if a digraph is acyclic.</fsummary> <desc> - <p>Returns <c>true</c> if and only if the digraph - <c><anno>Digraph</anno></c> is <seealso marker="#acyclic_digraph">acyclic</seealso>.</p> + <p>Returns <c>true</c> if and only if digraph + <c><anno>Digraph</anno></c> is + <seealso marker="#acyclic_digraph">acyclic</seealso>.</p> </desc> </func> + <func> <name name="is_arborescence" arity="1"/> <fsummary>Check if a digraph is an arborescence.</fsummary> <desc> - <p>Returns <c>true</c> if and only if the digraph + <p>Returns <c>true</c> if and only if digraph <c><anno>Digraph</anno></c> is an <seealso marker="#arborescence">arborescence</seealso>.</p> </desc> </func> + <func> <name name="is_tree" arity="1"/> <fsummary>Check if a digraph is a tree.</fsummary> <desc> - <p>Returns <c>true</c> if and only if the digraph + <p>Returns <c>true</c> if and only if digraph <c><anno>Digraph</anno></c> is - a <seealso marker="#tree">tree</seealso>.</p> + a <seealso marker="#tree">tree</seealso>.</p> </desc> </func> + <func> <name name="loop_vertices" arity="1"/> - <fsummary>Return the vertices of a digraph included in some loop.</fsummary> + <fsummary>Return the vertices of a digraph included in some loop. + </fsummary> <desc> - <p>Returns a list of all vertices of <c><anno>Digraph</anno></c> that are - included in some <seealso marker="#loop">loop</seealso>.</p> + <p>Returns a list of all vertices of <c><anno>Digraph</anno></c> that + are included in some <seealso marker="#loop">loop</seealso>.</p> </desc> </func> + <func> <name name="postorder" arity="1"/> - <fsummary>Return the vertices of a digraph in post-order.</fsummary> + <fsummary>Return the vertices of a digraph in postorder.</fsummary> <desc> - <p>Returns all vertices of the digraph <c><anno>Digraph</anno></c>. The - order is given by - a <seealso marker="#depth_first_traversal">depth-first - traversal</seealso> of the digraph, collecting visited + <p>Returns all vertices of digraph <c><anno>Digraph</anno></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> + placed before the subsequently visited vertices.</p> </desc> </func> + <func> <name name="preorder" arity="1"/> - <fsummary>Return the vertices of a digraph in pre-order.</fsummary> + <fsummary>Return the vertices of a digraph in preorder.</fsummary> <desc> - <p>Returns all vertices of the digraph <c><anno>Digraph</anno></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> + <p>Returns all vertices of digraph <c><anno>Digraph</anno></c>. + The order is given by + a <seealso marker="#depth_first_traversal">depth-first + traversal</seealso> of the digraph, collecting visited + vertices in preorder.</p> </desc> </func> + <func> <name name="reachable" arity="2"/> - <fsummary>Return the vertices reachable from some vertices of a digraph.</fsummary> + <fsummary>Return the vertices reachable from some vertices of a digraph. + </fsummary> <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><anno>Digraph</anno></c> from some + each vertex in the list, there is a + <seealso marker="#path">path</seealso> in <c><anno>Digraph</anno></c> + from some vertex of <c><anno>Vertices</anno></c> to the vertex. In particular, - since paths may have length zero, the vertices of - <c><anno>Vertices</anno></c> are included in the returned list. - </p> + as paths can have length zero, the vertices of + <c><anno>Vertices</anno></c> are included in the returned list.</p> </desc> </func> + <func> <name name="reachable_neighbours" arity="2"/> - <fsummary>Return the neighbours reachable from some vertices of a digraph.</fsummary> + <fsummary>Return the neighbors reachable from some vertices of a + digraph.</fsummary> <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><anno>Digraph</anno></c> of length + each vertex in the list, there is a + <seealso marker="#path">path</seealso> in <c><anno>Digraph</anno></c> + of length one or more from some vertex of <c><anno>Vertices</anno></c> to the - vertex. As a consequence, only those vertices - of <c><anno>Vertices</anno></c> that are included in - some <seealso marker="#cycle">cycle</seealso> are returned. - </p> + vertex. As a consequence, only those vertices + of <c><anno>Vertices</anno></c> that are included in + some <seealso marker="#cycle">cycle</seealso> are returned.</p> </desc> </func> + <func> <name name="reaching" arity="2"/> - <fsummary>Return the vertices that reach some vertices of a digraph.</fsummary> + <fsummary>Return the vertices that reach some vertices of a digraph. + </fsummary> <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><anno>Vertices</anno></c>. In particular, since paths may have - length zero, the vertices of <c><anno>Vertices</anno></c> are included in - the returned list. - </p> + each vertex in the list, there is + a <seealso marker="#path">path</seealso> from the vertex to some + vertex of <c><anno>Vertices</anno></c>. In particular, as paths + can have length zero, the vertices of <c><anno>Vertices</anno></c> + are included in the returned list.</p> </desc> </func> + <func> <name name="reaching_neighbours" arity="2"/> - <fsummary>Return the neighbours that reach some vertices of a digraph.</fsummary> + <fsummary>Return the neighbors that reach some vertices of a digraph. + </fsummary> <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><anno>Vertices</anno></c>. As a consequence, - only those vertices of <c><anno>Vertices</anno></c> that are included in - some <seealso marker="#cycle">cycle</seealso> are returned. - </p> + 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><anno>Vertices</anno></c>. + Therefore only those vertices of <c><anno>Vertices</anno></c> + that are included + in some <seealso marker="#cycle">cycle</seealso> are returned.</p> </desc> </func> + <func> <name name="strong_components" arity="1"/> <fsummary>Return the strong components of a digraph.</fsummary> <desc> - <p>Returns a list of <seealso marker="#strong_components">strongly - connected components</seealso>. - Each strongly component is represented + <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 + the components are arbitrary. Each vertex of digraph <c><anno>Digraph</anno></c> occurs in exactly one strong component. - </p> + </p> </desc> </func> + <func> <name name="subgraph" arity="2"/> <name name="subgraph" arity="3"/> <fsummary>Return a subgraph of a digraph.</fsummary> <desc> - <p>Creates a maximal <seealso marker="#subgraph">subgraph</seealso> of <c>Digraph</c> having + <p>Creates a maximal <seealso marker="#subgraph">subgraph</seealso> + of <c>Digraph</c> having as vertices those vertices of <c><anno>Digraph</anno></c> that are - mentioned in <c><anno>Vertices</anno></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><anno>Digraph</anno></c> is used + mentioned in <c><anno>Vertices</anno></c>.</p> + <p>If the value of option <c>type</c> is <c>inherit</c>, which is + the default, the type of <c><anno>Digraph</anno></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><anno>Digraph</anno></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(<anno>Digraph</anno>, <anno>Vertices</anno>)</c> is equivalent to - <c>subgraph(<anno>Digraph</anno>, <anno>Vertices</anno>, [])</c>. - </p> - <p>There will be a <c>badarg</c> exception if any of the arguments - are invalid. - </p> + is used as argument to + <seealso marker="digraph:new/1"><c>digraph:new/1</c></seealso>.</p> + <p>If the value of option <c>keep_labels</c> is <c>true</c>, + which is the default, + the <seealso marker="#label">labels</seealso> of vertices and edges + of <c><anno>Digraph</anno></c> are used for the subgraph as well. If + the value is <c>false</c>, default label <c>[]</c> is used + for the vertices and edges of the subgroup.</p> + <p><c>subgraph(<anno>Digraph</anno>, <anno>Vertices</anno>)</c> is + equivalent to + <c>subgraph(<anno>Digraph</anno>, <anno>Vertices</anno>, [])</c>.</p> + <p>If any of the arguments are invalid, a <c>badarg</c> exception is + raised.</p> </desc> </func> + <func> <name name="topsort" arity="1"/> - <fsummary>Return a topological sorting of the vertices of a digraph.</fsummary> + <fsummary>Return a topological sorting of the vertices of a digraph. + </fsummary> <desc> - <p>Returns a <seealso marker="#topsort">topological - ordering</seealso> of the vertices of the digraph - <c><anno>Digraph</anno></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> + <p>Returns a <seealso marker="#topsort">topological + ordering</seealso> of the vertices of digraph + <c><anno>Digraph</anno></c> if such an ordering exists, otherwise + <c>false</c>. For each vertex in the returned list, + no <seealso marker="#out_neighbour">out-neighbors</seealso> + occur earlier in the list.</p> </desc> </func> </funcs> <section> <title>See Also</title> - <p><seealso marker="digraph">digraph(3)</seealso></p> + <p><seealso marker="digraph"><c>digraph(3)</c></seealso></p> </section> </erlref> |