alpar@209: /* -*- mode: C++; indent-tabs-mode: nil; -*- alpar@40: * alpar@209: * This file is a part of LEMON, a generic C++ optimization library. alpar@40: * alpar@40: * Copyright (C) 2003-2008 alpar@40: * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport alpar@40: * (Egervary Research Group on Combinatorial Optimization, EGRES). alpar@40: * alpar@40: * Permission to use, modify and distribute this software is granted alpar@40: * provided that this copyright notice appears in all copies. For alpar@40: * precise terms see the accompanying LICENSE file. alpar@40: * alpar@40: * This software is provided "AS IS" with no warranty of any kind, alpar@40: * express or implied, and with no claim as to its suitability for any alpar@40: * purpose. alpar@40: * alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup datas Data Structures kpeter@50: This group describes the several data structures implemented in LEMON. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup graphs Graph Structures alpar@40: @ingroup datas alpar@40: \brief Graph structures implemented in LEMON. alpar@40: alpar@209: The implementation of combinatorial algorithms heavily relies on alpar@209: efficient graph implementations. LEMON offers data structures which are alpar@209: planned to be easily used in an experimental phase of implementation studies, alpar@209: and thereafter the program code can be made efficient by small modifications. alpar@40: alpar@40: The most efficient implementation of diverse applications require the alpar@40: usage of different physical graph implementations. These differences alpar@40: appear in the size of graph we require to handle, memory or time usage alpar@40: limitations or in the set of operations through which the graph can be alpar@40: accessed. LEMON provides several physical graph structures to meet alpar@40: the diverging requirements of the possible users. In order to save on alpar@40: running time or on memory usage, some structures may fail to provide kpeter@83: some graph features like arc/edge or node deletion. alpar@40: alpar@209: Alteration of standard containers need a very limited number of alpar@209: operations, these together satisfy the everyday requirements. alpar@209: In the case of graph structures, different operations are needed which do alpar@209: not alter the physical graph, but gives another view. If some nodes or kpeter@83: arcs have to be hidden or the reverse oriented graph have to be used, then alpar@209: this is the case. It also may happen that in a flow implementation alpar@209: the residual graph can be accessed by another algorithm, or a node-set alpar@209: is to be shrunk for another algorithm. alpar@209: LEMON also provides a variety of graphs for these requirements called alpar@209: \ref graph_adaptors "graph adaptors". Adaptors cannot be used alone but only alpar@209: in conjunction with other graph representations. alpar@40: alpar@40: You are free to use the graph structure that fit your requirements alpar@40: the best, most graph algorithms and auxiliary data structures can be used kpeter@314: with any graph structure. kpeter@314: kpeter@314: See also: \ref graph_concepts "Graph Structure Concepts". alpar@40: */ alpar@40: alpar@40: /** kpeter@50: @defgroup semi_adaptors Semi-Adaptor Classes for Graphs alpar@40: @ingroup graphs alpar@40: \brief Graph types between real graphs and graph adaptors. alpar@40: kpeter@50: This group describes some graph types between real graphs and graph adaptors. alpar@209: These classes wrap graphs to give new functionality as the adaptors do it. kpeter@50: On the other hand they are not light-weight structures as the adaptors. alpar@40: */ alpar@40: alpar@40: /** alpar@209: @defgroup maps Maps alpar@40: @ingroup datas kpeter@50: \brief Map structures implemented in LEMON. alpar@40: kpeter@50: This group describes the map structures implemented in LEMON. kpeter@50: kpeter@314: LEMON provides several special purpose maps and map adaptors that e.g. combine alpar@40: new maps from existing ones. kpeter@314: kpeter@314: See also: \ref map_concepts "Map Concepts". alpar@40: */ alpar@40: alpar@40: /** alpar@209: @defgroup graph_maps Graph Maps alpar@40: @ingroup maps kpeter@83: \brief Special graph-related maps. alpar@40: kpeter@50: This group describes maps that are specifically designed to assign kpeter@83: values to the nodes and arcs of graphs. alpar@40: */ alpar@40: alpar@40: /** alpar@40: \defgroup map_adaptors Map Adaptors alpar@40: \ingroup maps alpar@40: \brief Tools to create new maps from existing ones alpar@40: kpeter@50: This group describes map adaptors that are used to create "implicit" kpeter@50: maps from other maps. alpar@40: kpeter@83: Most of them are \ref lemon::concepts::ReadMap "read-only maps". kpeter@83: They can make arithmetic and logical operations between one or two maps kpeter@83: (negation, shifting, addition, multiplication, logical 'and', 'or', kpeter@83: 'not' etc.) or e.g. convert a map to another one of different Value type. alpar@40: kpeter@50: The typical usage of this classes is passing implicit maps to alpar@40: algorithms. If a function type algorithm is called then the function alpar@40: type map adaptors can be used comfortable. For example let's see the kpeter@314: usage of map adaptors with the \c graphToEps() function. alpar@40: \code alpar@40: Color nodeColor(int deg) { alpar@40: if (deg >= 2) { alpar@40: return Color(0.5, 0.0, 0.5); alpar@40: } else if (deg == 1) { alpar@40: return Color(1.0, 0.5, 1.0); alpar@40: } else { alpar@40: return Color(0.0, 0.0, 0.0); alpar@40: } alpar@40: } alpar@209: kpeter@83: Digraph::NodeMap degree_map(graph); alpar@209: kpeter@314: graphToEps(graph, "graph.eps") alpar@40: .coords(coords).scaleToA4().undirected() kpeter@83: .nodeColors(composeMap(functorToMap(nodeColor), degree_map)) alpar@40: .run(); alpar@209: \endcode kpeter@83: The \c functorToMap() function makes an \c int to \c Color map from the kpeter@314: \c nodeColor() function. The \c composeMap() compose the \c degree_map kpeter@83: and the previously created map. The composed map is a proper function to kpeter@83: get the color of each node. alpar@40: alpar@40: The usage with class type algorithms is little bit harder. In this alpar@40: case the function type map adaptors can not be used, because the kpeter@50: function map adaptors give back temporary objects. alpar@40: \code kpeter@83: Digraph graph; kpeter@83: kpeter@83: typedef Digraph::ArcMap DoubleArcMap; kpeter@83: DoubleArcMap length(graph); kpeter@83: DoubleArcMap speed(graph); kpeter@83: kpeter@83: typedef DivMap TimeMap; alpar@40: TimeMap time(length, speed); alpar@209: kpeter@83: Dijkstra dijkstra(graph, time); alpar@40: dijkstra.run(source, target); alpar@40: \endcode kpeter@83: We have a length map and a maximum speed map on the arcs of a digraph. kpeter@83: The minimum time to pass the arc can be calculated as the division of kpeter@83: the two maps which can be done implicitly with the \c DivMap template alpar@40: class. We use the implicit minimum time map as the length map of the alpar@40: \c Dijkstra algorithm. alpar@40: */ alpar@40: alpar@40: /** alpar@209: @defgroup matrices Matrices alpar@40: @ingroup datas kpeter@50: \brief Two dimensional data storages implemented in LEMON. alpar@40: kpeter@50: This group describes two dimensional data storages implemented in LEMON. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup paths Path Structures alpar@40: @ingroup datas kpeter@318: \brief %Path structures implemented in LEMON. alpar@40: kpeter@50: This group describes the path structures implemented in LEMON. alpar@40: kpeter@50: LEMON provides flexible data structures to work with paths. kpeter@50: All of them have similar interfaces and they can be copied easily with kpeter@50: assignment operators and copy constructors. This makes it easy and alpar@40: efficient to have e.g. the Dijkstra algorithm to store its result in alpar@40: any kind of path structure. alpar@40: alpar@40: \sa lemon::concepts::Path alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup auxdat Auxiliary Data Structures alpar@40: @ingroup datas kpeter@50: \brief Auxiliary data structures implemented in LEMON. alpar@40: kpeter@50: This group describes some data structures implemented in LEMON in alpar@40: order to make it easier to implement combinatorial algorithms. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup algs Algorithms alpar@40: \brief This group describes the several algorithms alpar@40: implemented in LEMON. alpar@40: alpar@40: This group describes the several algorithms alpar@40: implemented in LEMON. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup search Graph Search alpar@40: @ingroup algs kpeter@50: \brief Common graph search algorithms. alpar@40: alpar@209: This group describes the common graph search algorithms like kpeter@314: Breadth-First Search (BFS) and Depth-First Search (DFS). alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup shortest_path Shortest Path Algorithms alpar@40: @ingroup algs kpeter@50: \brief Algorithms for finding shortest paths. alpar@40: kpeter@50: This group describes the algorithms for finding shortest paths in graphs. alpar@40: */ alpar@40: alpar@209: /** kpeter@314: @defgroup max_flow Maximum Flow Algorithms alpar@209: @ingroup algs kpeter@50: \brief Algorithms for finding maximum flows. alpar@40: alpar@40: This group describes the algorithms for finding maximum flows and alpar@40: feasible circulations. alpar@40: kpeter@50: The maximum flow problem is to find a flow between a single source and kpeter@50: a single target that is maximum. Formally, there is a \f$G=(V,A)\f$ alpar@40: directed graph, an \f$c_a:A\rightarrow\mathbf{R}^+_0\f$ capacity alpar@40: function and given \f$s, t \in V\f$ source and target node. The kpeter@50: maximum flow is the \f$f_a\f$ solution of the next optimization problem: alpar@40: alpar@40: \f[ 0 \le f_a \le c_a \f] alpar@210: \f[ \sum_{v\in\delta^{-}(u)}f_{vu}=\sum_{v\in\delta^{+}(u)}f_{uv} alpar@210: \qquad \forall u \in V \setminus \{s,t\}\f] alpar@40: \f[ \max \sum_{v\in\delta^{+}(s)}f_{uv} - \sum_{v\in\delta^{-}(s)}f_{vu}\f] alpar@40: kpeter@50: LEMON contains several algorithms for solving maximum flow problems: alpar@209: - \ref lemon::EdmondsKarp "Edmonds-Karp" alpar@40: - \ref lemon::Preflow "Goldberg's Preflow algorithm" kpeter@50: - \ref lemon::DinitzSleatorTarjan "Dinitz's blocking flow algorithm with dynamic trees" alpar@40: - \ref lemon::GoldbergTarjan "Preflow algorithm with dynamic trees" alpar@40: kpeter@50: In most cases the \ref lemon::Preflow "Preflow" algorithm provides the alpar@40: fastest method to compute the maximum flow. All impelementations kpeter@50: provides functions to query the minimum cut, which is the dual linear kpeter@50: programming problem of the maximum flow. alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup min_cost_flow Minimum Cost Flow Algorithms alpar@40: @ingroup algs alpar@40: kpeter@50: \brief Algorithms for finding minimum cost flows and circulations. alpar@40: alpar@40: This group describes the algorithms for finding minimum cost flows and alpar@209: circulations. alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup min_cut Minimum Cut Algorithms alpar@209: @ingroup algs alpar@40: kpeter@50: \brief Algorithms for finding minimum cut in graphs. alpar@40: alpar@40: This group describes the algorithms for finding minimum cut in graphs. alpar@40: alpar@40: The minimum cut problem is to find a non-empty and non-complete alpar@40: \f$X\f$ subset of the vertices with minimum overall capacity on alpar@40: outgoing arcs. Formally, there is \f$G=(V,A)\f$ directed graph, an alpar@40: \f$c_a:A\rightarrow\mathbf{R}^+_0\f$ capacity function. The minimum kpeter@50: cut is the \f$X\f$ solution of the next optimization problem: alpar@40: alpar@210: \f[ \min_{X \subset V, X\not\in \{\emptyset, V\}} alpar@210: \sum_{uv\in A, u\in X, v\not\in X}c_{uv}\f] alpar@40: kpeter@50: LEMON contains several algorithms related to minimum cut problems: alpar@40: kpeter@50: - \ref lemon::HaoOrlin "Hao-Orlin algorithm" to calculate minimum cut alpar@209: in directed graphs kpeter@50: - \ref lemon::NagamochiIbaraki "Nagamochi-Ibaraki algorithm" to alpar@40: calculate minimum cut in undirected graphs kpeter@50: - \ref lemon::GomoryHuTree "Gomory-Hu tree computation" to calculate all alpar@40: pairs minimum cut in undirected graphs alpar@40: alpar@40: If you want to find minimum cut just between two distinict nodes, alpar@40: please see the \ref max_flow "Maximum Flow page". alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup graph_prop Connectivity and Other Graph Properties alpar@40: @ingroup algs kpeter@50: \brief Algorithms for discovering the graph properties alpar@40: kpeter@50: This group describes the algorithms for discovering the graph properties kpeter@50: like connectivity, bipartiteness, euler property, simplicity etc. alpar@40: alpar@40: \image html edge_biconnected_components.png alpar@40: \image latex edge_biconnected_components.eps "bi-edge-connected components" width=\textwidth alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup planar Planarity Embedding and Drawing alpar@40: @ingroup algs kpeter@50: \brief Algorithms for planarity checking, embedding and drawing alpar@40: alpar@210: This group describes the algorithms for planarity checking, alpar@210: embedding and drawing. alpar@40: alpar@40: \image html planar.png alpar@40: \image latex planar.eps "Plane graph" width=\textwidth alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup matching Matching Algorithms alpar@40: @ingroup algs kpeter@50: \brief Algorithms for finding matchings in graphs and bipartite graphs. alpar@40: kpeter@50: This group contains algorithm objects and functions to calculate alpar@40: matchings in graphs and bipartite graphs. The general matching problem is kpeter@83: finding a subset of the arcs which does not shares common endpoints. alpar@209: alpar@40: There are several different algorithms for calculate matchings in alpar@40: graphs. The matching problems in bipartite graphs are generally alpar@40: easier than in general graphs. The goal of the matching optimization alpar@40: can be the finding maximum cardinality, maximum weight or minimum cost alpar@40: matching. The search can be constrained to find perfect or alpar@40: maximum cardinality matching. alpar@40: ladanyi@236: LEMON contains the next algorithms: alpar@209: - \ref lemon::MaxBipartiteMatching "MaxBipartiteMatching" Hopcroft-Karp alpar@209: augmenting path algorithm for calculate maximum cardinality matching in alpar@40: bipartite graphs alpar@209: - \ref lemon::PrBipartiteMatching "PrBipartiteMatching" Push-Relabel alpar@209: algorithm for calculate maximum cardinality matching in bipartite graphs alpar@209: - \ref lemon::MaxWeightedBipartiteMatching "MaxWeightedBipartiteMatching" alpar@209: Successive shortest path algorithm for calculate maximum weighted matching alpar@40: and maximum weighted bipartite matching in bipartite graph alpar@209: - \ref lemon::MinCostMaxBipartiteMatching "MinCostMaxBipartiteMatching" alpar@209: Successive shortest path algorithm for calculate minimum cost maximum alpar@40: matching in bipartite graph alpar@40: - \ref lemon::MaxMatching "MaxMatching" Edmond's blossom shrinking algorithm alpar@40: for calculate maximum cardinality matching in general graph alpar@40: - \ref lemon::MaxWeightedMatching "MaxWeightedMatching" Edmond's blossom alpar@40: shrinking algorithm for calculate maximum weighted matching in general alpar@40: graph alpar@40: - \ref lemon::MaxWeightedPerfectMatching "MaxWeightedPerfectMatching" alpar@40: Edmond's blossom shrinking algorithm for calculate maximum weighted alpar@40: perfect matching in general graph alpar@40: alpar@40: \image html bipartite_matching.png alpar@40: \image latex bipartite_matching.eps "Bipartite Matching" width=\textwidth alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup spantree Minimum Spanning Tree Algorithms alpar@40: @ingroup algs kpeter@50: \brief Algorithms for finding a minimum cost spanning tree in a graph. alpar@40: kpeter@50: This group describes the algorithms for finding a minimum cost spanning alpar@40: tree in a graph alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup auxalg Auxiliary Algorithms alpar@40: @ingroup algs kpeter@50: \brief Auxiliary algorithms implemented in LEMON. alpar@40: kpeter@50: This group describes some algorithms implemented in LEMON kpeter@50: in order to make it easier to implement complex algorithms. alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup approx Approximation Algorithms kpeter@314: @ingroup algs kpeter@50: \brief Approximation algorithms. alpar@40: kpeter@50: This group describes the approximation and heuristic algorithms kpeter@50: implemented in LEMON. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup gen_opt_group General Optimization Tools alpar@40: \brief This group describes some general optimization frameworks alpar@40: implemented in LEMON. alpar@40: alpar@40: This group describes some general optimization frameworks alpar@40: implemented in LEMON. alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup lp_group Lp and Mip Solvers alpar@40: @ingroup gen_opt_group alpar@40: \brief Lp and Mip solver interfaces for LEMON. alpar@40: alpar@40: This group describes Lp and Mip solver interfaces for LEMON. The alpar@40: various LP solvers could be used in the same manner with this alpar@40: interface. alpar@40: */ alpar@40: alpar@209: /** kpeter@314: @defgroup lp_utils Tools for Lp and Mip Solvers alpar@40: @ingroup lp_group kpeter@50: \brief Helper tools to the Lp and Mip solvers. alpar@40: alpar@40: This group adds some helper tools to general optimization framework alpar@40: implemented in LEMON. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup metah Metaheuristics alpar@40: @ingroup gen_opt_group alpar@40: \brief Metaheuristics for LEMON library. alpar@40: kpeter@50: This group describes some metaheuristic optimization tools. alpar@40: */ alpar@40: alpar@40: /** alpar@209: @defgroup utils Tools and Utilities kpeter@50: \brief Tools and utilities for programming in LEMON alpar@40: kpeter@50: Tools and utilities for programming in LEMON. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup gutils Basic Graph Utilities alpar@40: @ingroup utils kpeter@50: \brief Simple basic graph utilities. alpar@40: alpar@40: This group describes some simple basic graph utilities. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup misc Miscellaneous Tools alpar@40: @ingroup utils kpeter@50: \brief Tools for development, debugging and testing. kpeter@50: kpeter@50: This group describes several useful tools for development, alpar@40: debugging and testing. alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup timecount Time Measuring and Counting alpar@40: @ingroup misc kpeter@50: \brief Simple tools for measuring the performance of algorithms. kpeter@50: kpeter@50: This group describes simple tools for measuring the performance alpar@40: of algorithms. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup exceptions Exceptions alpar@40: @ingroup utils kpeter@50: \brief Exceptions defined in LEMON. kpeter@50: kpeter@50: This group describes the exceptions defined in LEMON. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup io_group Input-Output kpeter@50: \brief Graph Input-Output methods alpar@40: alpar@209: This group describes the tools for importing and exporting graphs kpeter@314: and graph related data. Now it supports the \ref lgf-format kpeter@314: "LEMON Graph Format", the \c DIMACS format and the encapsulated kpeter@314: postscript (EPS) format. alpar@40: */ alpar@40: alpar@40: /** kpeter@363: @defgroup lemon_io LEMON Graph Format alpar@40: @ingroup io_group kpeter@314: \brief Reading and writing LEMON Graph Format. alpar@40: alpar@210: This group describes methods for reading and writing ladanyi@236: \ref lgf-format "LEMON Graph Format". alpar@40: */ alpar@40: alpar@40: /** kpeter@314: @defgroup eps_io Postscript Exporting alpar@40: @ingroup io_group alpar@40: \brief General \c EPS drawer and graph exporter alpar@40: kpeter@50: This group describes general \c EPS drawing methods and special alpar@209: graph exporting tools. alpar@40: */ alpar@40: alpar@40: /** kpeter@403: @defgroup dimacs_group DIMACS format kpeter@403: @ingroup io_group kpeter@403: \brief Read and write files in DIMACS format kpeter@403: kpeter@403: Tools to read a digraph from or write it to a file in DIMACS format data. kpeter@403: */ kpeter@403: kpeter@403: /** kpeter@363: @defgroup nauty_group NAUTY Format kpeter@363: @ingroup io_group kpeter@363: \brief Read \e Nauty format kpeter@403: kpeter@363: Tool to read graphs from \e Nauty format data. kpeter@363: */ kpeter@363: kpeter@363: /** alpar@40: @defgroup concept Concepts alpar@40: \brief Skeleton classes and concept checking classes alpar@40: alpar@40: This group describes the data/algorithm skeletons and concept checking alpar@40: classes implemented in LEMON. alpar@40: alpar@40: The purpose of the classes in this group is fourfold. alpar@209: kpeter@318: - These classes contain the documentations of the %concepts. In order alpar@40: to avoid document multiplications, an implementation of a concept alpar@40: simply refers to the corresponding concept class. alpar@40: alpar@40: - These classes declare every functions, typedefs etc. an kpeter@318: implementation of the %concepts should provide, however completely alpar@40: without implementations and real data structures behind the alpar@40: interface. On the other hand they should provide nothing else. All alpar@40: the algorithms working on a data structure meeting a certain concept alpar@40: should compile with these classes. (Though it will not run properly, alpar@40: of course.) In this way it is easily to check if an algorithm alpar@40: doesn't use any extra feature of a certain implementation. alpar@40: alpar@40: - The concept descriptor classes also provide a checker class kpeter@50: that makes it possible to check whether a certain implementation of a alpar@40: concept indeed provides all the required features. alpar@40: alpar@40: - Finally, They can serve as a skeleton of a new implementation of a concept. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup graph_concepts Graph Structure Concepts alpar@40: @ingroup concept alpar@40: \brief Skeleton and concept checking classes for graph structures alpar@40: kpeter@50: This group describes the skeletons and concept checking classes of LEMON's alpar@40: graph structures and helper classes used to implement these. alpar@40: */ alpar@40: kpeter@314: /** kpeter@314: @defgroup map_concepts Map Concepts kpeter@314: @ingroup concept kpeter@314: \brief Skeleton and concept checking classes for maps kpeter@314: kpeter@314: This group describes the skeletons and concept checking classes of maps. alpar@40: */ alpar@40: alpar@40: /** alpar@40: \anchor demoprograms alpar@40: alpar@40: @defgroup demos Demo programs alpar@40: alpar@40: Some demo programs are listed here. Their full source codes can be found in alpar@40: the \c demo subdirectory of the source tree. alpar@40: alpar@41: It order to compile them, use --enable-demo configure option when alpar@41: build the library. alpar@40: */ alpar@40: alpar@40: /** alpar@40: @defgroup tools Standalone utility applications alpar@40: alpar@209: Some utility applications are listed here. alpar@40: alpar@40: The standard compilation procedure (./configure;make) will compile alpar@209: them, as well. alpar@40: */ alpar@40: