From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/digraph_utils.xml | 452 +++++++++++++++++++---------------- 1 file changed, 250 insertions(+), 202 deletions(-) (limited to 'lib/stdlib/doc/src/digraph_utils.xml') 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 @@ digraph_utils Hans Bolinder - nobody + - nobody - no + + 2001-08-27 PA1 - digraph_utils.sgml + digraph_utils.xml digraph_utils - Algorithms for Directed Graphs + Algorithms for directed graphs. -

The digraph_utils module implements some algorithms - based on depth-first traversal of directed graphs. See the - digraph module for basic functions on directed graphs. -

-

A directed graph (or - just "digraph") is a pair (V, E) of a finite set V of - vertices and a finite set E - of directed edges (or just - "edges"). The set of edges E is a subset of V × V - (the Cartesian product of V with itself). -

-

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 - labeled digraph, and the information attached to a - vertex or an edge is called a - label.

-

An edge e = (v, w) is said - to emanate from vertex v and - to be incident on vertex w. - If there is an edge emanating from v and incident on w, then w is - said to be - an out-neighbour of v, - and v is said to be - an in-neighbour of w. - A path 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 length of the path P is k-1. - P is a cycle if the length of P - is not zero and v[1] = v[k]. - A loop is a cycle of length one. - An acyclic digraph is - a digraph that has no cycles. -

+

This module provides algorithms based on depth-first traversal of + directed graphs. For basic functions on directed graphs, see the + digraph(3) module.

-

A depth-first - traversal 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. -

-

A partial ordering of - a set S is a transitive, antisymmetric and reflexive relation - between the objects of S. The problem - of topological sorting 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 digraph 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. -

-

A subgraph G' of G is a - digraph whose vertices and edges form subsets of the vertices - and edges of G. G' is maximal with respect to a - property P if all other subgraphs that include the vertices of - G' do not have the property P. A strongly connected - component is a maximal subgraph such that there is a path - between each pair of vertices. A connected component is a - maximal subgraph such that there is a path between each pair of - vertices, considering all edges undirected. An arborescence is an acyclic - digraph with a vertex V, the root, such that there is a unique - path from V to every other vertex of G. A tree is an acyclic non-empty digraph - such that there is a unique path between every pair of vertices, - considering all edges undirected.

+ + +

A directed graph (or just + "digraph") is a pair (V, E) of a finite set V of + vertices and a finite set E of + directed edges (or just "edges"). + The set of edges E is a subset of V × V (the + Cartesian product of V with itself).

+ + +

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 labeled digraph, and the + information attached to a vertex or an edge is called a + label.

+ + +

An edge e = (v, w) is said to + emanate from vertex v and to + be incident on vertex w.

+ + +

If an edge is emanating from v and incident on w, then w is + said to be an + out-neighbor of v, and v is said to be an + in-neighbor of w.

+ + +

A path 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 length of path P is + k-1.

+ + +

Path P is a cycle if the + length of P is not zero and v[1] = v[k].

+ + +

A loop is a cycle of length + one.

+ + +

An acyclic digraph + is a digraph without cycles.

+ + +

A depth-first + traversal 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.

+ + +

A partial ordering + of a set S is a transitive, antisymmetric, and reflexive relation + between the objects of S.

+ + +

The problem of + topological sorting 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 digraph 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.

+ + +

A subgraph G' of G is a + digraph whose vertices and edges form subsets of the vertices + and edges of G.

+ + +

G' is maximal with respect to a property P if all other + subgraphs that include the vertices of G' do not have property P.

+ + +

A strongly connected + component is a maximal subgraph such that there is a path + between each pair of vertices.

+ + +

A connected component + is a maximal subgraph such that there is a path between each pair of + vertices, considering all edges undirected.

+ + +

An arborescence is an + acyclic digraph with a vertex V, the + root, such that there is a unique + path from V to every other vertex of G.

+ + +

A tree is an acyclic non-empty + digraph such that there is a unique path between every pair of + vertices, considering all edges undirected.

+ + @@ -125,237 +157,253 @@ Check if a digraph is an arborescence. -

Returns {yes, Root} if Root is - the root of the arborescence - Digraph, no otherwise. -

+

Returns {yes, Root} if Root + is the root of the arborescence + Digraph, otherwise no.

 + Return the components of a digraph. -

Returns a list - of connected components. - Each component is represented by its +

Returns a list + of connected components.. + 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 - Digraph occurs in exactly one component. -

+ components are arbitrary. Each vertex of digraph + Digraph occurs in exactly one component.

 + Return a condensed graph of a digraph. -

Creates a digraph where the vertices are - the strongly connected - components of Digraph as returned by - strong_components/1. 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 emanating from x - and incident on y, then - an edge emanating from X and incident on Y is created. -

+

Creates a digraph where the vertices are + the strongly connected + components of Digraph as returned by + + strong_components/1. + 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 emanating from x + and incident on y, then + an edge emanating from X and incident on Y is created.

The created digraph has the same type as Digraph. - All vertices and edges have the - default label []. -

-

Each and every cycle is - included in some strongly connected component, which implies - that there always exists - a topological ordering of the - created digraph.

+ All vertices and edges have the + default label [].

+

Each cycle is + included in some strongly connected component, which implies that + a topological ordering of the + created digraph always exists.

 + Return the cyclic strong components of a digraph. -

Returns a list of strongly - connected components. - Each strongly component is represented +

Returns a list of strongly + connected components. 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 cycle in - Digraph are returned, otherwise the returned list is - equal to that returned by strong_components/1. -

+ Digraph are returned, otherwise the returned + list is equal to that returned by + + strong_components/1.

 + Check if a digraph is acyclic. -

Returns true if and only if the digraph - Digraph is acyclic.

+

Returns true if and only if digraph + Digraph is + acyclic.

 + Check if a digraph is an arborescence. -

Returns true if and only if the digraph +

Returns true if and only if digraph Digraph is an arborescence.

 + Check if a digraph is a tree. -

Returns true if and only if the digraph +

Returns true if and only if digraph Digraph is - a tree.

+ a tree.

 + - Return the vertices of a digraph included in some loop. + Return the vertices of a digraph included in some loop. + -

Returns a list of all vertices of Digraph that are - included in some loop.

+

Returns a list of all vertices of Digraph that + are included in some loop.

 + - Return the vertices of a digraph in post-order. + Return the vertices of a digraph in postorder. -

Returns all vertices of the digraph Digraph. The - order is given by - a depth-first - traversal of the digraph, collecting visited +

Returns all vertices of digraph Digraph. + The order is given by + a depth-first + traversal 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. -

+ placed before the subsequently visited vertices.

 + - Return the vertices of a digraph in pre-order. + Return the vertices of a digraph in preorder. -

Returns all vertices of the digraph Digraph. The - order is given by - a depth-first - traversal of the digraph, collecting visited - vertices in pre-order.

+

Returns all vertices of digraph Digraph. + The order is given by + a depth-first + traversal of the digraph, collecting visited + vertices in preorder.

 + - Return the vertices reachable from some vertices of a digraph. + Return the vertices reachable from some vertices of a digraph. +

Returns an unsorted list of digraph vertices such that for - each vertex in the list, there is - a path in Digraph from some + each vertex in the list, there is a + path in Digraph + from some vertex of Vertices to the vertex. In particular, - since paths may have length zero, the vertices of - Vertices are included in the returned list. -

+ as paths can have length zero, the vertices of + Vertices are included in the returned list.

 + - Return the neighbours reachable from some vertices of a digraph. + Return the neighbors reachable from some vertices of a + digraph.

Returns an unsorted list of digraph vertices such that for - each vertex in the list, there is - a path in Digraph of length + each vertex in the list, there is a + path in Digraph + of length one or more from some vertex of Vertices to the - vertex. As a consequence, only those vertices - of Vertices that are included in - some cycle are returned. -

+ vertex. As a consequence, only those vertices + of Vertices that are included in + some cycle are returned.

 + - Return the vertices that reach some vertices of a digraph. + Return the vertices that reach some vertices of a digraph. +

Returns an unsorted list of digraph vertices such that for - each vertex in the list, there is - a path from the vertex to some - vertex of Vertices. In particular, since paths may have - length zero, the vertices of Vertices are included in - the returned list. -

+ each vertex in the list, there is + a path from the vertex to some + vertex of Vertices. In particular, as paths + can have length zero, the vertices of Vertices + are included in the returned list.

 + - Return the neighbours that reach some vertices of a digraph. + Return the neighbors that reach some vertices of a digraph. +

Returns an unsorted list of digraph vertices such that for - each vertex in the list, there is - a path of length one or more - from the vertex to some vertex of Vertices. As a consequence, - only those vertices of Vertices that are included in - some cycle are returned. -

+ each vertex in the list, there is + a path of length one or more + from the vertex to some vertex of Vertices. + Therefore only those vertices of Vertices + that are included + in some cycle are returned.

 + Return the strong components of a digraph. -

Returns a list of strongly - connected components. - Each strongly component is represented +

Returns a list of strongly + connected components. + 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 Digraph occurs in exactly one strong component. -

+

+ Return a subgraph of a digraph. -

Creates a maximal subgraph of Digraph having +

Creates a maximal subgraph + of Digraph having as vertices those vertices of Digraph that are - mentioned in Vertices. -

-

If the value of the option type is inherit, - which is the default, then the type of Digraph is used + mentioned in Vertices.

+

If the value of option type is inherit, which is + the default, the type of Digraph is used for the subgraph as well. Otherwise the option value of type - is used as argument to digraph:new/1. -

-

If the value of the option keep_labels is true, - which is the default, then - the labels of vertices and edges - of Digraph are used for the subgraph as well. If the value - is false, then the default label, [], is used - for the subgraph's vertices and edges. -

-

subgraph(Digraph, Vertices) is equivalent to - subgraph(Digraph, Vertices, []). -

-

There will be a badarg exception if any of the arguments - are invalid. -

+ is used as argument to + digraph:new/1.

+

If the value of option keep_labels is true, + which is the default, + the labels of vertices and edges + of Digraph are used for the subgraph as well. If + the value is false, default label [] is used + for the vertices and edges of the subgroup.

+

subgraph(Digraph, Vertices) is + equivalent to + subgraph(Digraph, Vertices, []).

+

If any of the arguments are invalid, a badarg exception is + raised.

 + - Return a topological sorting of the vertices of a digraph. + Return a topological sorting of the vertices of a digraph. + -

Returns a topological - ordering of the vertices of the digraph - Digraph if such an ordering exists, false - otherwise. For each vertex in the returned list, there are - no out-neighbours - that occur earlier in the list.

+

Returns a topological + ordering of the vertices of digraph + Digraph if such an ordering exists, otherwise + false. For each vertex in the returned list, + no out-neighbors + occur earlier in the list.
See Also -

digraph(3)

+

digraph(3)

-- cgit v1.2.3