path: root/lib/stdlib/doc/src/digraph_utils.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2000</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions 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,&nbsp;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&nbsp;&times;&nbsp;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&nbsp;=&nbsp;(v,&nbsp;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,&nbsp;E) is a non-empty sequence
      v[1],&nbsp;v[2],&nbsp;...,&nbsp;v[k] of vertices in V such that
      there is an edge (v[i],v[i+1]) in E for
      1&nbsp;&lt;=&nbsp;i&nbsp;&lt;&nbsp;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&nbsp;=&nbsp;(V,&nbsp;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>

  <datatypes>
    <datatype>
      <name>digraph()</name>
      <desc><p><marker id="type-digraph"/>
        A digraph as returned by <c>digraph:new/0,1</c>.</p></desc>
    </datatype>
  </datatypes>
  <funcs>
    <func>
      <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>
      </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
          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>
      </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>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>
      </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
          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>
      </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>
      </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
          <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
          <c><anno>Digraph</anno></c> is
	  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>
      <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>
      </desc>
    </func>
    <func>
      <name name="postorder" arity="1"/>
      <fsummary>Return the vertices of a digraph in post-order.</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 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 name="preorder" arity="1"/>
      <fsummary>Return the vertices of a digraph in pre-order.</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>
      </desc>
    </func>
    <func>
      <name name="reachable" arity="2"/>
      <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
          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>
      </desc>
    </func>
    <func>
      <name name="reachable_neighbours" arity="2"/>
      <fsummary>Return the neighbours 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
          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>
      </desc>
    </func>
    <func>
      <name name="reaching" arity="2"/>
      <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>
      </desc>
    </func>
    <func>
      <name name="reaching_neighbours" arity="2"/>
      <fsummary>Return the neighbours 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>
      </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
          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 strong component.
          </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
          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
          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>
      </desc>
    </func>
    <func>
      <name name="topsort" arity="1"/>
      <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>
      </desc>
    </func>
  </funcs>

  <section>
    <title>See Also</title>
    <p><seealso marker="digraph">digraph(3)</seealso></p>
  </section>
</erlref>