doc/groups.dox
changeset 478 5a1e9fdcfd3a
parent 463 88ed40ad0d4f
parent 474 fbd6e04acf44
child 606 c5fd2d996909
child 656 e6927fe719e6
     1.1 --- a/doc/groups.dox	Thu Jan 08 17:19:26 2009 +0000
     1.2 +++ b/doc/groups.dox	Sun Jan 11 15:09:53 2009 +0000
     1.3 @@ -62,18 +62,20 @@
     1.4  */
     1.5  
     1.6  /**
     1.7 -@defgroup graph_adaptors Adaptor Classes for graphs
     1.8 +@defgroup graph_adaptors Adaptor Classes for Graphs
     1.9  @ingroup graphs
    1.10 -\brief This group contains several adaptor classes for digraphs and graphs
    1.11 +\brief Adaptor classes for digraphs and graphs
    1.12 +
    1.13 +This group contains several useful adaptor classes for digraphs and graphs.
    1.14  
    1.15  The main parts of LEMON are the different graph structures, generic
    1.16 -graph algorithms, graph concepts which couple these, and graph
    1.17 +graph algorithms, graph concepts, which couple them, and graph
    1.18  adaptors. While the previous notions are more or less clear, the
    1.19  latter one needs further explanation. Graph adaptors are graph classes
    1.20  which serve for considering graph structures in different ways.
    1.21  
    1.22  A short example makes this much clearer.  Suppose that we have an
    1.23 -instance \c g of a directed graph type say ListDigraph and an algorithm
    1.24 +instance \c g of a directed graph type, say ListDigraph and an algorithm
    1.25  \code
    1.26  template <typename Digraph>
    1.27  int algorithm(const Digraph&);
    1.28 @@ -81,13 +83,13 @@
    1.29  is needed to run on the reverse oriented graph.  It may be expensive
    1.30  (in time or in memory usage) to copy \c g with the reversed
    1.31  arcs.  In this case, an adaptor class is used, which (according
    1.32 -to LEMON digraph concepts) works as a digraph.  The adaptor uses the
    1.33 -original digraph structure and digraph operations when methods of the
    1.34 -reversed oriented graph are called.  This means that the adaptor have
    1.35 -minor memory usage, and do not perform sophisticated algorithmic
    1.36 +to LEMON \ref concepts::Digraph "digraph concepts") works as a digraph.
    1.37 +The adaptor uses the original digraph structure and digraph operations when
    1.38 +methods of the reversed oriented graph are called.  This means that the adaptor
    1.39 +have minor memory usage, and do not perform sophisticated algorithmic
    1.40  actions.  The purpose of it is to give a tool for the cases when a
    1.41  graph have to be used in a specific alteration.  If this alteration is
    1.42 -obtained by a usual construction like filtering the arc-set or
    1.43 +obtained by a usual construction like filtering the node or the arc set or
    1.44  considering a new orientation, then an adaptor is worthwhile to use.
    1.45  To come back to the reverse oriented graph, in this situation
    1.46  \code
    1.47 @@ -96,39 +98,40 @@
    1.48  template class can be used. The code looks as follows
    1.49  \code
    1.50  ListDigraph g;
    1.51 -ReverseDigraph<ListGraph> rg(g);
    1.52 +ReverseDigraph<ListDigraph> rg(g);
    1.53  int result = algorithm(rg);
    1.54  \endcode
    1.55 -After running the algorithm, the original graph \c g is untouched.
    1.56 -This techniques gives rise to an elegant code, and based on stable
    1.57 +During running the algorithm, the original digraph \c g is untouched.
    1.58 +This techniques give rise to an elegant code, and based on stable
    1.59  graph adaptors, complex algorithms can be implemented easily.
    1.60  
    1.61 -In flow, circulation and bipartite matching problems, the residual
    1.62 +In flow, circulation and matching problems, the residual
    1.63  graph is of particular importance. Combining an adaptor implementing
    1.64 -this, shortest path algorithms and minimum mean cycle algorithms,
    1.65 +this with shortest path algorithms or minimum mean cycle algorithms,
    1.66  a range of weighted and cardinality optimization algorithms can be
    1.67  obtained. For other examples, the interested user is referred to the
    1.68  detailed documentation of particular adaptors.
    1.69  
    1.70  The behavior of graph adaptors can be very different. Some of them keep
    1.71  capabilities of the original graph while in other cases this would be
    1.72 -meaningless. This means that the concepts that they are models of depend
    1.73 -on the graph adaptor, and the wrapped graph(s).
    1.74 -If an arc of \c rg is deleted, this is carried out by deleting the
    1.75 -corresponding arc of \c g, thus the adaptor modifies the original graph.
    1.76 +meaningless. This means that the concepts that they meet depend
    1.77 +on the graph adaptor, and the wrapped graph.
    1.78 +For example, if an arc of a reversed digraph is deleted, this is carried
    1.79 +out by deleting the corresponding arc of the original digraph, thus the
    1.80 +adaptor modifies the original digraph.
    1.81 +However in case of a residual digraph, this operation has no sense.
    1.82  
    1.83 -But for a residual graph, this operation has no sense.
    1.84  Let us stand one more example here to simplify your work.
    1.85 -RevGraphAdaptor has constructor
    1.86 +ReverseDigraph has constructor
    1.87  \code
    1.88  ReverseDigraph(Digraph& digraph);
    1.89  \endcode
    1.90 -This means that in a situation, when a <tt>const ListDigraph&</tt>
    1.91 +This means that in a situation, when a <tt>const %ListDigraph&</tt>
    1.92  reference to a graph is given, then it have to be instantiated with
    1.93 -<tt>Digraph=const ListDigraph</tt>.
    1.94 +<tt>Digraph=const %ListDigraph</tt>.
    1.95  \code
    1.96  int algorithm1(const ListDigraph& g) {
    1.97 -  RevGraphAdaptor<const ListDigraph> rg(g);
    1.98 +  ReverseDigraph<const ListDigraph> rg(g);
    1.99    return algorithm2(rg);
   1.100  }
   1.101  \endcode