source: lemon-tutorial/graphs.dox @ 47:c09d90659170

/* -*- mode: C++; indent-tabs-mode: nil; -*-
 *
 * This file is a part of LEMON, a generic C++ optimization library.
 *
 * Copyright (C) 2003-2010
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
 *
 * Permission to use, modify and distribute this software is granted
 * provided that this copyright notice appears in all copies. For
 * precise terms see the accompanying LICENSE file.
 *
 * This software is provided "AS IS" with no warranty of any kind,
 * express or implied, and with no claim as to its suitability for any
 * purpose.
 *
 */

namespace lemon {
/**
[PAGE]sec_graph_structures[PAGE] Graph Structures

The implementation of combinatorial algorithms heavily relies on
efficient graph structures. Diverse applications require the
usage of different physical graph storages.
Until now, we used two general graph structures, \ref ListDigraph
and \ref ListGraph. Apart from these types, LEMON also provides several
other classes for handling directed and undirected graphs to meet the
diverging requirements of the possible users. In order to save on running
time or on memory usage, some structures may fail to support some graph
features like node or arc/edge deletion.
You are free to use the graph structure that fit your requirements the best,
since most graph algorithms and auxiliary data structures can be used
with any of them.


[SEC]sec_graph_concepts[SEC] Graph Concepts

In LEMON, there are various graph types, which are rather different, but
they all conform to the corresponding \ref graph_concepts "graph concept",
which defines the common part of the graph interfaces.
The \ref concepts::Digraph "Digraph concept" describes the common interface
of directed graphs (without any sensible implementation), while
the \ref concepts::Graph "Graph concept" describes the undirected graphs.
A generic graph algorithm should only exploit the features of the
corresponding graph concept so that it could be applied to any graph
structure. (Such an algorithm should compile with the
\ref concepts::Digraph "Digraph" or \ref concepts::Graph "Graph" type,
but it will not run properly, of course.)

The graph %concepts define the member classes for the iterators and maps
along with some useful basic functions for obtaining the identifiers of
the items, the end nodes of the arcs (or edges) and their iterators,
etc.
An actual graph implementation may have various additional functionalities
according to its purpose.

Another advantage of this design is that you can write your own graph classes,
if you would like to.
As long as they provide the interface defined in one of the graph concepts,
all the LEMON algorithms and classes will work with them properly.


[SEC]sec_digraph_types[SEC] Directed Graph Structures

The already used \ref ListDigraph class is the most versatile directed
graph structure. As its name suggests, it is based on linked lists,
therefore iterating through its nodes and arcs is fast and it is quite
flexible. Apart from the general digraph functionalities, it
provides operations for adding and removing nodes and arcs, changing
the source or target node of an arc, and contracting and splitting nodes
or arcs.

\ref SmartDigraph is another general digraph implementation, which is
significantly more efficient (both in terms of space and time), but it
provides less functionality. For example, nodes and arcs cannot be
removed from it.

The \ref StaticDigraph structure is even more optimized for efficiency,
but it is completely static. It requires less space in memory and
provides faster item iteration than \ref ListDigraph and \ref
SmartDigraph, especially using \ref concepts::Digraph::OutArcIt
"OutArcIt" iterators, since its arcs are stored in an appropriate order.
However, it only provides \ref StaticDigraph::build() "build()" and
\ref \ref StaticDigraph::clear() "clear()" functions and does not
support any other modification of the digraph.
 
\ref FullDigraph is an efficient implementation of a directed full graph.
This structure is also completely static, so you can neither add nor delete
arcs or nodes, moreover, the class needs constant space in memory.


[SEC]sec_graph_types[SEC] Undirected Graph Structures

The general undirected graph classes, \ref ListGraph and \ref SmartGraph
have similar implementations as their directed variants.
Therefore, \ref SmartDigraph is more efficient, but \ref ListGraph provides
more functionality.

In addition to these general structures, LEMON also provides special purpose
undirected graph types for handling \ref FullGraph "full graphs",
\ref GridGraph "grid graphs" and \ref HypercubeGraph "hypercube graphs".
They all static structures, i.e. they do not allow distinct item additions
or deletions, the graph has to be built at once.

[TRAILER]
*/
}