/* -*- C++ -*-

 *

 * This file is a part of LEMON, a generic C++ optimization library

 *

 * Copyright (C) 2003-2006

 * 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.

 *

 */

#ifndef LEMON_EDMONDS_KARP_H

#define LEMON_EDMONDS_KARP_H

/// \file

/// \ingroup flowalgs

/// \brief Implementation of the Edmonds-Karp algorithm.

#include <lemon/graph_adaptor.h>

#include <lemon/tolerance.h>

#include <lemon/bfs.h>

namespace lemon {

  /// \ingroup flowalgs

  /// \brief Edmonds-Karp algorithms class.

  ///

  /// This class provides an implementation of the \e Edmonds-Karp \e

  /// algorithm producing a flow of maximum value in a directed

  /// graph. The Edmonds-Karp algorithm is slower than the Preflow algorithm

  /// but it has an advantage of the step-by-step execution control with

  /// feasible flow solutions. The \e source node, the \e target node, the \e

  /// capacity of the edges and the \e starting \e flow value of the

  /// edges should be passed to the algorithm through the

  /// constructor.

  ///

  /// The time complexity of the algorithm is O(n * e^2) in worst case. 

  /// Always try the preflow algorithm instead of this if you does not

  /// have some additional reason than to compute the optimal flow which

  /// has O(n^3) time complexity.

  ///

  /// \param _Graph The directed graph type the algorithm runs on.

  /// \param _Number The number type of the capacities and the flow values.

  /// \param _CapacityMap The capacity map type.

  /// \param _FlowMap The flow map type.

  /// \param _Tolerance The tolerance class to handle computation problems.

  ///

  /// \author Balazs Dezso 

  template <typename _Graph, typename _Number,

	    typename _CapacityMap = typename _Graph::template EdgeMap<_Number>,

            typename _FlowMap = typename _Graph::template EdgeMap<_Number>,

	    typename _Tolerance = Tolerance<_Number> >

  class EdmondsKarp {

  public:

    /// \brief \ref Exception for the case when the source equals the target.

    ///

    /// \ref Exception for the case when the source equals the target.

    ///

    class InvalidArgument : public lemon::LogicError {

    public:

      virtual const char* exceptionName() const {

	return "lemon::EdmondsKarp::InvalidArgument";

      }

    };

    /// \brief The graph type the algorithm runs on. 

    typedef _Graph Graph;

    /// \brief The value type of the algorithms.

    typedef _Number Number;

    /// \brief The capacity map on the edges.

    typedef _CapacityMap CapacityMap;

    /// \brief The flow map on the edges.

    typedef _FlowMap FlowMap;

    /// \brief The tolerance used by the algorithm.

    typedef _Tolerance Tolerance;

    typedef ResGraphAdaptor<Graph, Number, CapacityMap, 

                            FlowMap, Tolerance> ResGraph;

  private:

    typedef typename Graph::Node Node;

    typedef typename Graph::Edge Edge;

    typedef typename Graph::NodeIt NodeIt;

    typedef typename Graph::EdgeIt EdgeIt;

    typedef typename Graph::InEdgeIt InEdgeIt;

    typedef typename Graph::OutEdgeIt OutEdgeIt;

  public:

    /// \brief The constructor of the class.

    ///

    /// The constructor of the class. 

    /// \param graph The directed graph the algorithm runs on. 

    /// \param source The source node.

    /// \param target The target node.

    /// \param capacity The capacity of the edges. 

    /// \param flow The flow of the edges. 

    /// \param tolerance Tolerance class.

    /// Except the graph, all of these parameters can be reset by

    /// calling \ref source, \ref target, \ref capacityMap and \ref

    /// flowMap, resp.

    EdmondsKarp(const Graph& graph, Node source, Node target,

                const CapacityMap& capacity, FlowMap& flow, 

                const Tolerance& tolerance = Tolerance())

      : _graph(graph), _capacity(capacity), _flow(flow), 

        _tolerance(tolerance), _resgraph(graph, capacity, flow, tolerance), 

        _source(source), _target(target) 

    {

      if (_source == _target) {

        throw InvalidArgument();

      }

    }

    /// \brief Initializes the algorithm

    /// 

    /// It sets the flow to empty flow.

    void init() {

      for (EdgeIt it(_graph); it != INVALID; ++it) {

        _flow.set(it, 0);

      }

      _value = 0;

    }

    /// \brief Initializes the algorithm

    /// 

    /// If the flow map initially flow this let the flow map

    /// unchanged but the flow value will be set by the flow

    /// on the outedges from the source.

    void flowInit() {

      _value = 0;

      for (OutEdgeIt jt(_graph, _source); jt != INVALID; ++jt) {

        _value += _flow[jt];

      }

      for (InEdgeIt jt(_graph, _source); jt != INVALID; ++jt) {

        _value -= _flow[jt];

      }

    }

    /// \brief Initializes the algorithm

    /// 

    /// If the flow map initially flow this let the flow map

    /// unchanged but the flow value will be set by the flow

    /// on the outedges from the source. It also checks that

    /// the flow map really contains a flow.

    /// \return %True when the flow map really a flow.

    bool checkedFlowInit() {

      _value = 0;

      for (OutEdgeIt jt(_graph, _source); jt != INVALID; ++jt) {

        _value += _flow[jt];

      }

      for (InEdgeIt jt(_graph, _source); jt != INVALID; ++jt) {

        _value -= _flow[jt];

      }

      for (NodeIt it(_graph); it != INVALID; ++it) {

        if (it == _source || it == _target) continue;

        Number outFlow = 0;

        for (OutEdgeIt jt(_graph, it); jt != INVALID; ++jt) {

          outFlow += _flow[jt];

        }

        Number inFlow = 0;

        for (InEdgeIt jt(_graph, it); jt != INVALID; ++jt) {

          inFlow += _flow[jt];

        }

        if (_tolerance.different(outFlow, inFlow)) {

          return false;

        }

      }

      for (EdgeIt it(_graph); it != INVALID; ++it) {

        if (_tolerance.less(_flow[it], 0)) return false;

        if (_tolerance.less(_capacity[it], _flow[it])) return false;

      }

      return true;

    }

    /// \brief Augment the solution on an edge shortest path.

    /// 

    /// Augment the solution on an edge shortest path. It search an

    /// edge shortest path between the source and the target

    /// in the residual graph with the bfs algoritm.

    /// Then it increase the flow on this path with the minimal residual

    /// capacity on the path. If there is not such path it gives back

    /// false.

    /// \return %False when the augmenting is not success so the

    /// current flow is a feasible and optimal solution.

    bool augment() {

      typename Bfs<ResGraph>

      ::template DefDistMap<NullMap<Node, int> >

      ::Create bfs(_resgraph);

      NullMap<Node, int> distMap;

      bfs.distMap(distMap);

      bfs.init();

      bfs.addSource(_source);

      bfs.start(_target);

      if (!bfs.reached(_target)) {

        return false;

      }

      Number min = _resgraph.rescap(bfs.predEdge(_target));

      for (Node it = bfs.predNode(_target); it != _source; 

           it = bfs.predNode(it)) {

        if (min > _resgraph.rescap(bfs.predEdge(it))) {

          min = _resgraph.rescap(bfs.predEdge(it));

        }

      } 

      for (Node it = _target; it != _source; it = bfs.predNode(it)) {

        _resgraph.augment(bfs.predEdge(it), min);

      }

      _value += min;

      return true;

    }

    /// \brief Executes the algorithm

    ///

    /// It runs augmenting phases until the optimal solution is reached. 

    void start() {

      while (augment()) {}

    }

    /// \brief Gives back the current flow value.

    ///

    /// Gives back the current flow _value.

    Number flowValue() const {

      return _value;

    }

    /// \brief runs the algorithm.

    /// 

    /// It is just a shorthand for:

    /// \code 

    /// ek.init();

    /// ek.start();

    /// \endcode

    void run() {

      init();

      start();

    }

    /// \brief Returns a minimum value cut.

    ///

    /// Sets \c cut to the characteristic vector of a minimum value cut

    /// It simply calls the minMinCut member.

    /// \retval cut Write node bool map. 

    template <typename CutMap>

    void minCut(CutMap& cut) const {

      minMinCut(cut);

    }

    /// \brief Returns the inclusionwise minimum of the minimum value cuts.

    ///

    /// Sets \c cut to the characteristic vector of the minimum value cut

    /// which is inclusionwise minimum. It is computed by processing a

    /// bfs from the source node \c source in the residual graph.  

    /// \retval cut Write node bool map. 

    template <typename CutMap>

    void minMinCut(CutMap& cut) const {

      typename Bfs<ResGraph>

      ::template DefDistMap<NullMap<Node, int> >

      ::template DefProcessedMap<CutMap>

      ::Create bfs(_resgraph);

      NullMap<Node, int> distMap;

      bfs.distMap(distMap);

      bfs.processedMap(cut);

      bfs.run(_source);

    }

    /// \brief Returns the inclusionwise minimum of the minimum value cuts.

    ///

    /// Sets \c cut to the characteristic vector of the minimum value cut

    /// which is inclusionwise minimum. It is computed by processing a

    /// bfs from the source node \c source in the residual graph.  

    /// \retval cut Write node bool map. 

    template <typename CutMap>

    void maxMinCut(CutMap& cut) const {

      typedef RevGraphAdaptor<const ResGraph> RevGraph;

      RevGraph revgraph(_resgraph);

      typename Bfs<RevGraph>

      ::template DefDistMap<NullMap<Node, int> >

      ::template DefPredMap<NullMap<Node, Edge> >

      ::template DefProcessedMap<NotWriteMap<CutMap> >

      ::Create bfs(revgraph);

      NullMap<Node, int> distMap;

      bfs.distMap(distMap);

      NullMap<Node, Edge> predMap;

      bfs.predMap(predMap);

      NotWriteMap<CutMap> notcut(cut);

      bfs.processedMap(notcut);

      bfs.run(_target);

    }

    /// \brief Returns the source node.

    ///

    /// Returns the source node.

    /// 

    Node source() const { 

      return _source;

    }

    /// \brief Returns the target node.

    ///

    /// Returns the target node.

    /// 

    Node target() const { 

      return _target;

    }

    /// \brief Returns a reference to capacity map.

    ///

    /// Returns a reference to capacity map.

    /// 

    const CapacityMap &capacityMap() const { 

      return *_capacity;

    }

    /// \brief Returns a reference to flow map.

    ///

    /// Returns a reference to flow map.

    /// 

    const FlowMap &flowMap() const { 

      return *_flow;

    }

    /// \brief Returns the tolerance used by algorithm.

    ///

    /// Returns the tolerance used by algorithm.

    const Tolerance& tolerance() const {

      return tolerance;

    } 

  private:

    const Graph& _graph;

    const CapacityMap& _capacity;

    FlowMap& _flow;

    Tolerance _tolerance;

    ResGraph _resgraph;

    Node _source, _target;

    Number _value;

  };

}

#endif