Boost C++ Libraries

boost/graph/maximum_weighted_matching.hpp

//=======================================================================
// Copyright (c) 2018 Yi Ji
//
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt)
//
//=======================================================================

#ifndef BOOST_GRAPH_MAXIMUM_WEIGHTED_MATCHING_HPP
#define BOOST_GRAPH_MAXIMUM_WEIGHTED_MATCHING_HPP

#include <algorithm> // for std::iter_swap
#include <boost/shared_ptr.hpp>
#include <boost/make_shared.hpp>
#include <boost/graph/max_cardinality_matching.hpp>

namespace boost
{
    template <typename Graph, typename MateMap, typename VertexIndexMap>
    typename property_traits<typename property_map<Graph, edge_weight_t>::type>::value_type
    matching_weight_sum(const Graph& g, MateMap mate, VertexIndexMap vm)
    {
        typedef typename graph_traits<Graph>::vertex_iterator vertex_iterator_t;
        typedef typename graph_traits<Graph>::vertex_descriptor vertex_descriptor_t;
        typedef typename property_traits<typename property_map<Graph, edge_weight_t>::type>::value_type edge_property_t;
        
        edge_property_t weight_sum = 0;
        vertex_iterator_t vi, vi_end;
        
        for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
        {
            vertex_descriptor_t v = *vi;
            if (get(mate, v) != graph_traits<Graph>::null_vertex() && get(vm, v) < get(vm, get(mate,v)))
                weight_sum += get(edge_weight, g, edge(v,mate[v],g).first);
        }
        return weight_sum;
    }
    
    template <typename Graph, typename MateMap>
    inline typename property_traits<typename property_map<Graph, edge_weight_t>::type>::value_type
    matching_weight_sum(const Graph& g, MateMap mate)
    {
        return matching_weight_sum(g, mate, get(vertex_index,g));
    }
    
    template <typename Graph, typename MateMap, typename VertexIndexMap>
    class weighted_augmenting_path_finder
    {
    public:
        
        template <typename T>
        struct map_vertex_to_
        {
            typedef boost::iterator_property_map<typename std::vector<T>::iterator, VertexIndexMap> type;
        };
        typedef typename graph::detail::VERTEX_STATE vertex_state_t;
        typedef typename graph_traits<Graph>::vertex_iterator vertex_iterator_t;
        typedef typename graph_traits<Graph>::vertex_descriptor vertex_descriptor_t;
        typedef typename std::vector<vertex_descriptor_t>::const_iterator vertex_vec_iter_t;
        typedef typename graph_traits<Graph>::out_edge_iterator out_edge_iterator_t;
        typedef typename graph_traits<Graph>::edge_descriptor edge_descriptor_t;
        typedef typename graph_traits<Graph>::edge_iterator edge_iterator_t;
        typedef typename property_traits<typename property_map<Graph, edge_weight_t>::type>::value_type edge_property_t;
        typedef std::deque<vertex_descriptor_t> vertex_list_t;
        typedef std::vector<edge_descriptor_t> edge_list_t;
        typedef typename map_vertex_to_<vertex_descriptor_t>::type vertex_to_vertex_map_t;
        typedef typename map_vertex_to_<edge_property_t>::type vertex_to_weight_map_t;
        typedef typename map_vertex_to_<bool>::type vertex_to_bool_map_t;
        typedef typename map_vertex_to_<std::pair<vertex_descriptor_t, vertex_descriptor_t> >::type vertex_to_pair_map_t;
        typedef typename map_vertex_to_<std::pair<edge_descriptor_t, bool> >::type vertex_to_edge_map_t;
        typedef typename map_vertex_to_<vertex_to_edge_map_t>::type vertex_pair_to_edge_map_t;
        
        class blossom
        {
        public:
            
            typedef boost::shared_ptr<blossom> blossom_ptr_t;
            std::vector<blossom_ptr_t> sub_blossoms;
            edge_property_t dual_var;
            blossom_ptr_t father;

            blossom() : dual_var(0), father(blossom_ptr_t()) {}
            
            // get the base vertex of a blossom by recursively getting
            // its base sub-blossom, which is always the first one in
            // sub_blossoms because of how we create and maintain blossoms
            virtual vertex_descriptor_t get_base() const
            {
                const blossom* b = this;
                while (!b->sub_blossoms.empty())
                    b = b->sub_blossoms[0].get();
                return b->get_base();
            }
            
            // set a sub-blossom as a blossom's base by exchanging it
            // with its first sub-blossom
            void set_base(const blossom_ptr_t& sub)
            {
                for (blossom_iterator_t bi = sub_blossoms.begin(); bi != sub_blossoms.end(); ++bi)
                {
                    if (sub.get() == bi->get())
                    {
                        std::iter_swap(sub_blossoms.begin(), bi);
                        break;
                    }
                }
            }
            
            // get all vertices inside recursively
            virtual std::vector<vertex_descriptor_t> vertices() const
            {
                std::vector<vertex_descriptor_t> all_vertices;
                for (typename std::vector<blossom_ptr_t>::const_iterator bi = sub_blossoms.begin(); bi != sub_blossoms.end(); ++bi)
                {
                    std::vector<vertex_descriptor_t> some_vertices = (*bi)->vertices();
                    all_vertices.insert(all_vertices.end(), some_vertices.begin(), some_vertices.end());
                }
                return all_vertices;
            }
        };
        
        // a trivial_blossom only has one vertex and no sub-blossom;
        // for each vertex v, in_blossom[v] is the trivial_blossom that contains it directly
        class trivial_blossom : public blossom
        {
        public:
            trivial_blossom(vertex_descriptor_t v) : trivial_vertex(v) {}
            virtual vertex_descriptor_t get_base() const
            {
                return trivial_vertex;
            }
            
            virtual std::vector<vertex_descriptor_t> vertices() const
            {
                std::vector<vertex_descriptor_t> all_vertices;
                all_vertices.push_back(trivial_vertex);
                return all_vertices;
            }
            
        private:
            
            vertex_descriptor_t trivial_vertex;
        };
        
        typedef boost::shared_ptr<blossom> blossom_ptr_t;
        typedef typename std::vector<blossom_ptr_t>::iterator blossom_iterator_t;
        typedef typename map_vertex_to_<blossom_ptr_t>::type vertex_to_blossom_map_t;
        
        weighted_augmenting_path_finder(const Graph& arg_g, MateMap arg_mate, VertexIndexMap arg_vm) :
        g(arg_g),
        vm(arg_vm),
        null_edge(std::pair<edge_descriptor_t, bool>(num_edges(g) == 0 ? edge_descriptor_t() : *edges(g).first, false)),
        mate_vector(num_vertices(g)),
        label_S_vector(num_vertices(g), graph_traits<Graph>::null_vertex()),
        label_T_vector(num_vertices(g), graph_traits<Graph>::null_vertex()),
        outlet_vector(num_vertices(g), graph_traits<Graph>::null_vertex()),
        tau_idx_vector(num_vertices(g), graph_traits<Graph>::null_vertex()),
        dual_var_vector(std::vector<edge_property_t>(num_vertices(g), std::numeric_limits<edge_property_t>::min())),
        pi_vector(std::vector<edge_property_t>(num_vertices(g), std::numeric_limits<edge_property_t>::max())),
        gamma_vector(std::vector<edge_property_t>(num_vertices(g), std::numeric_limits<edge_property_t>::max())),
        tau_vector(std::vector<edge_property_t>(num_vertices(g), std::numeric_limits<edge_property_t>::max())),
        in_blossom_vector(num_vertices(g)),
        old_label_vector(num_vertices(g)),
        critical_edge_vectors(num_vertices(g), std::vector<std::pair<edge_descriptor_t, bool> >(num_vertices(g), null_edge)),
        
        mate(mate_vector.begin(), vm),
        label_S(label_S_vector.begin(), vm),
        label_T(label_T_vector.begin(), vm),
        outlet(outlet_vector.begin(), vm),
        tau_idx(tau_idx_vector.begin(), vm),
        dual_var(dual_var_vector.begin(), vm),
        pi(pi_vector.begin(), vm),
        gamma(gamma_vector.begin(), vm),
        tau(tau_vector.begin(), vm),
        in_blossom(in_blossom_vector.begin(), vm),
        old_label(old_label_vector.begin(), vm)
        {
            vertex_iterator_t vi, vi_end;
            edge_iterator_t ei, ei_end;
            
            edge_property_t max_weight = std::numeric_limits<edge_property_t>::min();
            for (boost::tie(ei,ei_end) = edges(g); ei != ei_end; ++ei)
                max_weight = std::max(max_weight, get(edge_weight, g, *ei));
            
            typename std::vector<std::vector<std::pair<edge_descriptor_t, bool> > >::iterator vei;
            
            for (boost::tie(vi,vi_end) = vertices(g), vei = critical_edge_vectors.begin(); vi != vi_end; ++vi, ++vei)
            {
                vertex_descriptor_t u = *vi;
                mate[u] = get(arg_mate, u);
                dual_var[u] = 2*max_weight;
                in_blossom[u] = boost::make_shared<trivial_blossom>(u);
                outlet[u] = u;
                critical_edge_vector.push_back(vertex_to_edge_map_t(vei->begin(), vm));
            }
            
            critical_edge = vertex_pair_to_edge_map_t(critical_edge_vector.begin(), vm);
            
            init();
        }
        
        // return the top blossom where v is contained inside
        blossom_ptr_t in_top_blossom(vertex_descriptor_t v) const
        {
            blossom_ptr_t b = in_blossom[v];
            while (b->father != blossom_ptr_t())
                b = b->father;
            return b;
        }
        
        // check if vertex v is in blossom b
        bool is_in_blossom(blossom_ptr_t b, vertex_descriptor_t v) const
        {
            if (v == graph_traits<Graph>::null_vertex())
                return false;
            blossom_ptr_t vb = in_blossom[v]->father;
            while (vb != blossom_ptr_t())
            {
                if (vb.get() == b.get())
                    return true;
                vb = vb->father;
            }
            return false;
        }
        
        // return the base vertex of the top blossom that contains v
        inline vertex_descriptor_t base_vertex(vertex_descriptor_t v) const
        {
            return in_top_blossom(v)->get_base();
        }
        
        // add an existed top blossom of base vertex v into new top
        // blossom b as its sub-blossom
        void add_sub_blossom(blossom_ptr_t b, vertex_descriptor_t v)
        {
            blossom_ptr_t sub = in_top_blossom(v);
            sub->father = b;
            b->sub_blossoms.push_back(sub);
            if (sub->sub_blossoms.empty())
                return;
            for (blossom_iterator_t bi = top_blossoms.begin(); bi != top_blossoms.end(); ++bi)
            {
                if (bi->get() == sub.get())
                {
                    top_blossoms.erase(bi);
                    break;
                }
            }
        }
        
        // when a top blossom is created or its base vertex getting an S-label,
        // add all edges incident to this blossom into even_edges
        void bloom(blossom_ptr_t b)
        {
            std::vector<vertex_descriptor_t> vertices_of_b = b->vertices();
            vertex_vec_iter_t vi;
            for (vi = vertices_of_b.begin(); vi != vertices_of_b.end(); ++vi)
            {
                out_edge_iterator_t oei, oei_end;
                for (boost::tie(oei,oei_end) = out_edges(*vi, g); oei != oei_end; ++oei)
                {
                    if (target(*oei,g) != *vi && mate[*vi] != target(*oei,g))
                        even_edges.push_back(*oei);
                }
            }
        }
        
        // assigning a T-label to a non S-vertex, along with outlet and updating pi value
        // if updated pi[v] equals zero, augment the matching from its mate vertex
        void put_T_label(vertex_descriptor_t v, vertex_descriptor_t T_label,
                         vertex_descriptor_t outlet_v, edge_property_t pi_v)
        {
            if (label_S[v] != graph_traits<Graph>::null_vertex())
                return;
            
            label_T[v] = T_label;
            outlet[v] = outlet_v;
            pi[v] = pi_v;
            
            vertex_descriptor_t v_mate = mate[v];
            if (pi[v] == 0)
            {
                label_T[v_mate] = graph_traits<Graph>::null_vertex();
                label_S[v_mate] = v;
                bloom(in_top_blossom(v_mate));
            }
        }
        
        // get the missing T-label for a to-be-expanded base vertex
        // the missing T-label is the last vertex of the path from outlet[v] to v
        std::pair<vertex_descriptor_t, vertex_descriptor_t> missing_label(vertex_descriptor_t b_base)
        {
            vertex_descriptor_t missing_outlet = outlet[b_base];
            
            if (outlet[b_base] == b_base)
                return std::make_pair(graph_traits<Graph>::null_vertex(), missing_outlet);
            
            vertex_iterator_t vi, vi_end;
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
                old_label[*vi] = std::make_pair(label_T[*vi], outlet[*vi]);
            
            std::pair<vertex_descriptor_t, vertex_state_t> child(outlet[b_base], graph::detail::V_EVEN);
            blossom_ptr_t b = in_blossom[child.first];
            for (; b->father->father != blossom_ptr_t(); b = b->father);
            child.first = b->get_base();
            
            if (child.first == b_base)
                return std::make_pair(graph_traits<Graph>::null_vertex(), missing_outlet);
            
            while (true)
            {
                std::pair<vertex_descriptor_t, vertex_state_t> child_parent = parent(child, true);
                
                for (b = in_blossom[child_parent.first]; b->father->father != blossom_ptr_t(); b = b->father);
                missing_outlet = child_parent.first;
                child_parent.first = b->get_base();
                
                if (child_parent.first == b_base)
                    break;
                else
                    child = child_parent;
            }
            return std::make_pair(child.first, missing_outlet);
        }
        
        // expand a top blossom, put all its non-trivial sub-blossoms into top_blossoms
        blossom_iterator_t expand_blossom(blossom_iterator_t bi, std::vector<blossom_ptr_t>& new_ones)
        {
            blossom_ptr_t b = *bi;
            for (blossom_iterator_t i = b->sub_blossoms.begin(); i != b->sub_blossoms.end(); ++i)
            {
                blossom_ptr_t sub_blossom = *i;
                vertex_descriptor_t sub_base = sub_blossom->get_base();
                label_S[sub_base] = label_T[sub_base] = graph_traits<Graph>::null_vertex();
                outlet[sub_base] = sub_base;
                sub_blossom->father = blossom_ptr_t();
                // new top blossoms cannot be pushed back into top_blossoms immediately,
                // because push_back() may cause reallocation and then invalid iterators
                if (!sub_blossom->sub_blossoms.empty())
                    new_ones.push_back(sub_blossom);
            }
            return top_blossoms.erase(bi);
        }
        
        // when expanding a T-blossom with base v, it requires more operations:
        // supply the missing T-labels for new base vertices by picking the minimum tau from vertices of
        // each corresponding new top-blossoms; when label_T[v] is null or we have a smaller tau from
        // missing_label(v), replace T-label and outlet of v (but don't bloom v)
        blossom_iterator_t expand_T_blossom(blossom_iterator_t bi, std::vector<blossom_ptr_t>& new_ones)
        {
            blossom_ptr_t b = *bi;
            
            vertex_descriptor_t b_base = b->get_base();
            std::pair<vertex_descriptor_t, vertex_descriptor_t> T_and_outlet = missing_label(b_base);
            
            blossom_iterator_t next_bi = expand_blossom(bi, new_ones);
            
            for (blossom_iterator_t i = b->sub_blossoms.begin(); i != b->sub_blossoms.end(); ++i)
            {
                blossom_ptr_t sub_blossom = *i;
                vertex_descriptor_t sub_base = sub_blossom->get_base();
                vertex_descriptor_t min_tau_v = graph_traits<Graph>::null_vertex();
                edge_property_t min_tau = std::numeric_limits<edge_property_t>::max();
                
                std::vector<vertex_descriptor_t> sub_vertices = sub_blossom->vertices();
                for (vertex_vec_iter_t v = sub_vertices.begin(); v != sub_vertices.end(); ++v)
                {
                    if (tau[*v] < min_tau)
                    {
                        min_tau = tau[*v];
                        min_tau_v = *v;
                    }
                }
                
                if (min_tau < std::numeric_limits<edge_property_t>::max())
                    put_T_label(sub_base, tau_idx[min_tau_v], min_tau_v, tau[min_tau_v]);
            }
            
            if (label_T[b_base] == graph_traits<Graph>::null_vertex() || tau[old_label[b_base].second] < pi[b_base])
                boost::tie(label_T[b_base], outlet[b_base]) = T_and_outlet;
            
            return next_bi;
        }
        
        // when vertices v and w are matched to each other by augmenting,
        // we must set v/w as base vertex of any blossom who contains v/w and
        // is a sub-blossom of their lowest (smallest) common blossom
        void adjust_blossom(vertex_descriptor_t v, vertex_descriptor_t w)
        {
            blossom_ptr_t vb = in_blossom[v], wb = in_blossom[w], lowest_common_blossom;
            std::vector<blossom_ptr_t> v_ancestors, w_ancestors;
            
            while (vb->father != blossom_ptr_t())
            {
                v_ancestors.push_back(vb->father);
                vb = vb->father;
            }
            while (wb->father != blossom_ptr_t())
            {
                w_ancestors.push_back(wb->father);
                wb = wb->father;
            }
            
            typename std::vector<blossom_ptr_t>::reverse_iterator i, j;
            i = v_ancestors.rbegin();
            j = w_ancestors.rbegin();
            while (i != v_ancestors.rend() && j != w_ancestors.rend() && i->get() == j->get())
            {
                lowest_common_blossom = *i;
                ++i;++j;
            }
            
            vb = in_blossom[v];
            wb = in_blossom[w];
            while (vb->father != lowest_common_blossom)
            {
                vb->father->set_base(vb);
                vb = vb->father;
            }
            while (wb->father != lowest_common_blossom)
            {
                wb->father->set_base(wb);
                wb = wb->father;
            }
        }
        
        // every edge weight is multiplied by 4 to ensure integer weights
        // throughout the algorithm if all input weights are integers
        inline edge_property_t slack(const edge_descriptor_t& e) const
        {
            vertex_descriptor_t v, w;
            v = source(e, g);
            w = target(e, g);
            return dual_var[v] + dual_var[w] - 4*get(edge_weight, g, e);
        }
        
        // backtrace one step on vertex v along the augmenting path
        // by its labels and its vertex state;
        // boolean parameter "use_old" means whether we are updating labels,
        // if we are, then we use old labels to backtrace and also we
        // don't jump to its base vertex when we reach an odd vertex
        std::pair<vertex_descriptor_t, vertex_state_t> parent(std::pair<vertex_descriptor_t, vertex_state_t> v,
                                                              bool use_old = false) const
        {
            if (v.second == graph::detail::V_EVEN)
            {
                // a paranoid check: label_S shoule be the same as mate in backtracing
                if (label_S[v.first] == graph_traits<Graph>::null_vertex())
                    label_S[v.first] = mate[v.first];
                return std::make_pair(label_S[v.first], graph::detail::V_ODD);
            }
            else if (v.second == graph::detail::V_ODD)
            {
                vertex_descriptor_t w = use_old ? old_label[v.first].first : base_vertex(label_T[v.first]);
                return std::make_pair(w, graph::detail::V_EVEN);
            }
            return std::make_pair(v.first, graph::detail::V_UNREACHED);
        }
        
        // backtrace from vertices v and w to their free (unmatched) ancesters,
        // return the nearest common ancestor (null_vertex if none) of v and w
        vertex_descriptor_t nearest_common_ancestor(vertex_descriptor_t v, vertex_descriptor_t w,
                                                    vertex_descriptor_t& v_free_ancestor,
                                                    vertex_descriptor_t& w_free_ancestor) const
        {
            std::pair<vertex_descriptor_t, vertex_state_t> v_up(v, graph::detail::V_EVEN);
            std::pair<vertex_descriptor_t, vertex_state_t> w_up(w, graph::detail::V_EVEN);
            vertex_descriptor_t nca;
            nca = w_free_ancestor = v_free_ancestor = graph_traits<Graph>::null_vertex();
            
            std::vector<bool> ancestor_of_w_vector(num_vertices(g), false);
            std::vector<bool> ancestor_of_v_vector(num_vertices(g), false);
            vertex_to_bool_map_t ancestor_of_w(ancestor_of_w_vector.begin(), vm);
            vertex_to_bool_map_t ancestor_of_v(ancestor_of_v_vector.begin(), vm);
            
            while (nca == graph_traits<Graph>::null_vertex() &&
                   (v_free_ancestor == graph_traits<Graph>::null_vertex() ||
                    w_free_ancestor == graph_traits<Graph>::null_vertex()))
            {
                ancestor_of_w[w_up.first] = true;
                ancestor_of_v[v_up.first] = true;
                
                if (w_free_ancestor == graph_traits<Graph>::null_vertex())
                    w_up = parent(w_up);
                if (v_free_ancestor == graph_traits<Graph>::null_vertex())
                    v_up = parent(v_up);
                
                if (mate[v_up.first] == graph_traits<Graph>::null_vertex())
                    v_free_ancestor = v_up.first;
                if (mate[w_up.first] == graph_traits<Graph>::null_vertex())
                    w_free_ancestor = w_up.first;
                
                if (ancestor_of_w[v_up.first] == true || v_up.first == w_up.first)
                    nca = v_up.first;
                else if (ancestor_of_v[w_up.first] == true)
                    nca = w_up.first;
                else if (v_free_ancestor == w_free_ancestor &&
                         v_free_ancestor != graph_traits<Graph>::null_vertex())
                    nca = v_up.first;
            }
            
            return nca;
        }
        
        // when a new top blossom b is created by connecting (v, w), we add sub-blossoms into
        // b along backtracing from v_prime and w_prime to stop_vertex (the base vertex);
        // also, we set labels and outlet for each base vertex we pass by
        void make_blossom(blossom_ptr_t b, vertex_descriptor_t w_prime,
                          vertex_descriptor_t v_prime, vertex_descriptor_t stop_vertex)
        {
            std::pair<vertex_descriptor_t, vertex_state_t> u(v_prime, graph::detail::V_ODD);
            std::pair<vertex_descriptor_t, vertex_state_t> u_up(w_prime, graph::detail::V_EVEN);
            
            for (; u_up.first != stop_vertex; u = u_up, u_up = parent(u))
            {
                if (u_up.second == graph::detail::V_EVEN)
                {
                    if (!in_top_blossom(u_up.first)->sub_blossoms.empty())
                        outlet[u_up.first] = label_T[u.first];
                    label_T[u_up.first] = outlet[u.first];
                }
                else if (u_up.second == graph::detail::V_ODD)
                    label_S[u_up.first] = u.first;
                
                add_sub_blossom(b, u_up.first);
            }
        }
        
        // the design of recursively expanding augmenting path in (reversed_)retrieve_augmenting_path
        // functions is inspired by same functions in max_cardinality_matching.hpp;
        // except that in weighted matching, we use "outlet" vertices instead of "bridge" vertex pairs:
        // if blossom b is the smallest non-trivial blossom that contains its base vertex v, then
        // v and outlet[v] are where augmenting path enters and leaves b
        void retrieve_augmenting_path(vertex_descriptor_t v, vertex_descriptor_t w, vertex_state_t v_state)
        {
            if (v == w)
                aug_path.push_back(v);
            else if (v_state == graph::detail::V_EVEN)
            {
                aug_path.push_back(v);
                retrieve_augmenting_path(label_S[v], w, graph::detail::V_ODD);
            }
            else if (v_state == graph::detail::V_ODD)
            {
                if (outlet[v] == v)
                    aug_path.push_back(v);
                else
                    reversed_retrieve_augmenting_path(outlet[v], v, graph::detail::V_EVEN);
                retrieve_augmenting_path(label_T[v], w, graph::detail::V_EVEN);
            }
        }
        
        void reversed_retrieve_augmenting_path(vertex_descriptor_t v, vertex_descriptor_t w, vertex_state_t v_state)
        {
            if (v == w)
                aug_path.push_back(v);
            else if (v_state == graph::detail::V_EVEN)
            {
                reversed_retrieve_augmenting_path(label_S[v], w, graph::detail::V_ODD);
                aug_path.push_back(v);
            }
            else if (v_state == graph::detail::V_ODD)
            {
                reversed_retrieve_augmenting_path(label_T[v], w, graph::detail::V_EVEN);
                if (outlet[v] != v)
                    retrieve_augmenting_path(outlet[v], v, graph::detail::V_EVEN);
                else
                    aug_path.push_back(v);
            }
        }
        
        // correct labels for vertices in the augmenting path
        void relabel(vertex_descriptor_t v)
        {
            blossom_ptr_t b = in_blossom[v]->father;
            
            if (!is_in_blossom(b, mate[v]))
            { // if v is a new base vertex
                std::pair<vertex_descriptor_t, vertex_state_t> u(v, graph::detail::V_EVEN);
                while (label_S[u.first] != u.first && is_in_blossom(b, label_S[u.first]))
                    u = parent(u, true);
                
                vertex_descriptor_t old_base = u.first;
                if (label_S[old_base] != old_base)
                { // if old base is not exposed
                    label_T[v] = label_S[old_base];
                    outlet[v] = old_base;
                }
                else
                { // if old base is exposed then new label_T[v] is not in b,
                    // we must (i) make b2 the smallest blossom containing v but not as base vertex
                    // (ii) backtrace from b2's new base vertex to b
                    label_T[v] = graph_traits<Graph>::null_vertex();
                    for (b = b->father; b != blossom_ptr_t() && b->get_base() == v; b = b->father);
                    if (b != blossom_ptr_t())
                    {
                        u = std::make_pair(b->get_base(), graph::detail::V_ODD);
                        while (!is_in_blossom(in_blossom[v]->father, old_label[u.first].first))
                            u = parent(u, true);
                        label_T[v] = u.first;
                        outlet[v] = old_label[u.first].first;
                    }
                }
            }
            else if (label_S[v] == v || !is_in_blossom(b, label_S[v]))
            { // if v is an old base vertex
                // let u be the new base vertex; backtrace from u's old T-label
                std::pair<vertex_descriptor_t, vertex_state_t> u(b->get_base(), graph::detail::V_ODD);
                while (old_label[u.first].first != graph_traits<Graph>::null_vertex() && old_label[u.first].first != v)
                    u = parent(u, true);
                label_T[v] = old_label[u.first].second;
                outlet[v] = v;
            }
            else // if v is neither a new nor an old base vertex
                label_T[v] = label_S[v];
        }
        
        void augmenting(vertex_descriptor_t v, vertex_descriptor_t v_free_ancestor,
                        vertex_descriptor_t w, vertex_descriptor_t w_free_ancestor)
        {
            vertex_iterator_t vi, vi_end;
            
            // retrieve the augmenting path and put it in aug_path
            reversed_retrieve_augmenting_path(v, v_free_ancestor, graph::detail::V_EVEN);
            retrieve_augmenting_path(w, w_free_ancestor, graph::detail::V_EVEN);
            
            // augment the matching along aug_path
            vertex_descriptor_t a, b;
            vertex_list_t reversed_aug_path;
            while (!aug_path.empty())
            {
                a = aug_path.front();
                aug_path.pop_front();
                reversed_aug_path.push_back(a);
                b = aug_path.front();
                aug_path.pop_front();
                reversed_aug_path.push_back(b);
                
                mate[a] = b;
                mate[b] = a;
                
                // reset base vertex for every blossom in augment path
                adjust_blossom(a, b);
            }
            
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
                old_label[*vi] = std::make_pair(label_T[*vi], outlet[*vi]);
            
            // correct labels for in-blossom vertices along aug_path
            while (!reversed_aug_path.empty())
            {
                a = reversed_aug_path.front();
                reversed_aug_path.pop_front();
                
                if (in_blossom[a]->father != blossom_ptr_t())
                    relabel(a);
            }
            
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
            {
                vertex_descriptor_t u = *vi;
                if (mate[u] != graph_traits<Graph>::null_vertex())
                    label_S[u] = mate[u];
            }
            
            // expand blossoms with zero dual variables
            std::vector<blossom_ptr_t> new_top_blossoms;
            for (blossom_iterator_t bi = top_blossoms.begin(); bi != top_blossoms.end();)
            {
                if ((*bi)->dual_var <= 0)
                    bi = expand_blossom(bi, new_top_blossoms);
                else
                    ++bi;
            }
            top_blossoms.insert(top_blossoms.end(), new_top_blossoms.begin(), new_top_blossoms.end());
            init();
        }
        
        // create a new blossom and set labels for vertices inside
        void blossoming(vertex_descriptor_t v, vertex_descriptor_t v_prime,
                        vertex_descriptor_t w, vertex_descriptor_t w_prime,
                        vertex_descriptor_t nca)
        {
            vertex_iterator_t vi, vi_end;
            
            std::vector<bool> is_old_base_vector(num_vertices(g));
            vertex_to_bool_map_t is_old_base(is_old_base_vector.begin(), vm);
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
            {
                if (*vi == base_vertex(*vi))
                    is_old_base[*vi] = true;
            }
            
            blossom_ptr_t b = boost::make_shared<blossom>();
            add_sub_blossom(b, nca);
            
            label_T[w_prime] = v;
            label_T[v_prime] = w;
            outlet[w_prime] = w;
            outlet[v_prime] = v;
            
            make_blossom(b, w_prime, v_prime, nca);
            make_blossom(b, v_prime, w_prime, nca);
            
            label_T[nca] = graph_traits<Graph>::null_vertex();
            outlet[nca] = nca;
            
            top_blossoms.push_back(b);
            bloom(b);
            
            // set gamma[b_base] = min_slack{critical_edge(b_base, other_base)} where each critical edge
            // is updated before, by argmin{slack(old_bases_in_b, other_base)};
            vertex_vec_iter_t i, j;
            std::vector<vertex_descriptor_t> b_vertices = b->vertices(), old_base_in_b, other_base;
            vertex_descriptor_t b_base = b->get_base();
            for (i = b_vertices.begin(); i != b_vertices.end(); ++i)
            {
                if (is_old_base[*i])
                    old_base_in_b.push_back(*i);
            }
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
            {
                if (*vi != b_base && *vi == base_vertex(*vi))
                    other_base.push_back(*vi);
            }
            for (i = other_base.begin(); i != other_base.end(); ++i)
            {
                edge_property_t min_slack = std::numeric_limits<edge_property_t>::max();
                std::pair<edge_descriptor_t, bool> b_vi = null_edge;
                for (j = old_base_in_b.begin(); j != old_base_in_b.end(); ++j)
                {
                    if (critical_edge[*j][*i] != null_edge && min_slack > slack(critical_edge[*j][*i].first))
                    {
                        min_slack = slack(critical_edge[*j][*i].first);
                        b_vi = critical_edge[*j][*i];
                    }
                }
                critical_edge[b_base][*i] = critical_edge[*i][b_base] = b_vi;
            }
            gamma[b_base] = std::numeric_limits<edge_property_t>::max();
            for (i = other_base.begin(); i != other_base.end(); ++i)
            {
                if (critical_edge[b_base][*i] != null_edge)
                    gamma[b_base] = std::min(gamma[b_base], slack(critical_edge[b_base][*i].first));
            }
        }
        
        void init()
        {
            even_edges.clear();
            
            vertex_iterator_t vi, vi_end;
            typename std::vector<std::vector<std::pair<edge_descriptor_t, bool> > >::iterator vei;
            
            for (boost::tie(vi,vi_end) = vertices(g), vei = critical_edge_vectors.begin(); vi != vi_end; ++vi, ++vei)
            {
                vertex_descriptor_t u = *vi;
                out_edge_iterator_t ei, ei_end;
                
                gamma[u] = tau[u] = pi[u] = std::numeric_limits<edge_property_t>::max();
                std::fill(vei->begin(), vei->end(), null_edge);
                
                if (base_vertex(u) != u)
                    continue;
                
                label_S[u] = label_T[u] = graph_traits<Graph>::null_vertex();
                outlet[u] = u;
                
                if (mate[u] == graph_traits<Graph>::null_vertex())
                {
                    label_S[u] = u;
                    bloom(in_top_blossom(u));
                }
            }
        }
        
        bool augment_matching()
        {
            vertex_descriptor_t v, w, w_free_ancestor, v_free_ancestor;
            v = w = w_free_ancestor = v_free_ancestor = graph_traits<Graph>::null_vertex();
            bool found_alternating_path = false;
            
            // note that we only use edges of zero slack value for augmenting
            while (!even_edges.empty() && !found_alternating_path)
            {
                // search for augmenting paths depth-first
                edge_descriptor_t current_edge = even_edges.back();
                even_edges.pop_back();
                
                v = source(current_edge, g);
                w = target(current_edge, g);
                
                vertex_descriptor_t v_prime = base_vertex(v);
                vertex_descriptor_t w_prime = base_vertex(w);
                
                // w_prime == v_prime implies that we get an edge that has been shrunk into a blossom
                if (v_prime == w_prime)
                    continue;
                
                // a paranoid check
                if (label_S[v_prime] == graph_traits<Graph>::null_vertex())
                {
                    std::swap(v_prime, w_prime);
                    std::swap(v, w);
                }
                
                // w_prime may be unlabeled or have a T-label; replace the existed T-label if the edge slack
                // is smaller than current pi[w_prime] and update it. Note that a T-label is "deserved" only when pi equals zero.
                // also update tau and tau_idx so that tau_idx becomes T-label when a T-blossom is expanded
                if (label_S[w_prime] == graph_traits<Graph>::null_vertex())
                {
                    if (slack(current_edge) < pi[w_prime])
                        put_T_label(w_prime, v, w, slack(current_edge));
                    if (slack(current_edge) < tau[w])
                    {
                        if (in_blossom[w]->father == blossom_ptr_t() || label_T[w_prime] == v ||
                            label_T[w_prime] == graph_traits<Graph>::null_vertex() ||
                            nearest_common_ancestor(v_prime, label_T[w_prime],
                                                    v_free_ancestor, w_free_ancestor) == graph_traits<Graph>::null_vertex())
                        {
                            tau[w] = slack(current_edge);
                            tau_idx[w] = v;
                        }
                    }
                }
                
                else
                {
                    if (slack(current_edge) > 0)
                    {
                        // update gamma and critical_edges when we have a smaller edge slack
                        gamma[v_prime] = std::min(gamma[v_prime], slack(current_edge));
                        gamma[w_prime] = std::min(gamma[w_prime], slack(current_edge));
                        if (critical_edge[v_prime][w_prime] == null_edge ||
                            slack(critical_edge[v_prime][w_prime].first) > slack(current_edge))
                        {
                            critical_edge[v_prime][w_prime] = std::pair<edge_descriptor_t, bool>(current_edge, true);
                            critical_edge[w_prime][v_prime] = std::pair<edge_descriptor_t, bool>(current_edge, true);
                        }
                        continue;
                    }
                    else if (slack(current_edge) == 0)
                    {
                        // if nca is null_vertex then we have an augmenting path; otherwise we have
                        // a new top blossom with nca as its base vertex
                        vertex_descriptor_t nca = nearest_common_ancestor(v_prime, w_prime, v_free_ancestor, w_free_ancestor);
                        
                        if (nca == graph_traits<Graph>::null_vertex())
                            found_alternating_path = true; //to break out of the loop
                        else
                            blossoming(v, v_prime, w, w_prime, nca);
                    }
                }
            }
            
            if (!found_alternating_path)
                return false;
            
            augmenting(v, v_free_ancestor, w, w_free_ancestor);
            return true;
        }
        
        // slack the vertex and blossom dual variables when there is no augmenting path found
        // according to the primal-dual method
        bool adjust_dual()
        {
            edge_property_t delta1, delta2, delta3, delta4, delta;
            delta1 = delta2 = delta3 = delta4 = std::numeric_limits<edge_property_t>::max();
            
            vertex_iterator_t vi, vi_end;
            
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
            {
                delta1 = std::min(delta1, dual_var[*vi]);
                delta4 = pi[*vi] > 0 ? std::min(delta4, pi[*vi]) : delta4;
                if (*vi == base_vertex(*vi))
                    delta3 = std::min(delta3, gamma[*vi]/2);
            }
            
            for (blossom_iterator_t bi = top_blossoms.begin(); bi != top_blossoms.end(); ++bi)
            {
                vertex_descriptor_t b_base = (*bi)->get_base();
                if (label_T[b_base] != graph_traits<Graph>::null_vertex() && pi[b_base] == 0)
                    delta2 = std::min(delta2, (*bi)->dual_var/2);
            }
            
            delta = std::min(std::min(delta1, delta2), std::min(delta3, delta4));
            
            // start updating dual variables, note that the order is important
            
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
            {
                vertex_descriptor_t v = *vi, v_prime = base_vertex(v);
                
                if (label_S[v_prime] != graph_traits<Graph>::null_vertex())
                    dual_var[v] -= delta;
                else if (label_T[v_prime] != graph_traits<Graph>::null_vertex() && pi[v_prime] == 0)
                    dual_var[v] += delta;
                
                if (v == v_prime)
                    gamma[v] -= 2*delta;
            }
            
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
            {
                vertex_descriptor_t v_prime = base_vertex(*vi);
                if (pi[v_prime] > 0)
                    tau[*vi] -= delta;
            }
            
            for (blossom_iterator_t bi = top_blossoms.begin(); bi != top_blossoms.end(); ++bi)
            {
                vertex_descriptor_t b_base = (*bi)->get_base();
                if (label_T[b_base] != graph_traits<Graph>::null_vertex() && pi[b_base] == 0)
                    (*bi)->dual_var -= 2*delta;
                if (label_S[b_base] != graph_traits<Graph>::null_vertex())
                    (*bi)->dual_var += 2*delta;
            }
            
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
            {
                vertex_descriptor_t v = *vi;
                if (pi[v] > 0)
                    pi[v] -= delta;
                
                // when some T-vertices have zero pi value, bloom their mates so that matching can be further augmented
                if (label_T[v] != graph_traits<Graph>::null_vertex() && pi[v] == 0)
                    put_T_label(v, label_T[v], outlet[v], pi[v]);
            }
            
            
            // optimal solution reached, halt
            if (delta == delta1)
                return false;
            
            // expand odd blossoms with zero dual variables and zero pi value of their base vertices
            if (delta == delta2 && delta != delta3)
            {
                std::vector<blossom_ptr_t> new_top_blossoms;
                for (blossom_iterator_t bi = top_blossoms.begin(); bi != top_blossoms.end();)
                {
                    const blossom_ptr_t b = *bi;
                    vertex_descriptor_t b_base = b->get_base();
                    if (b->dual_var == 0 && label_T[b_base] != graph_traits<Graph>::null_vertex() && pi[b_base] == 0)
                        bi = expand_T_blossom(bi, new_top_blossoms);
                    else
                        ++bi;
                }
                top_blossoms.insert(top_blossoms.end(), new_top_blossoms.begin(), new_top_blossoms.end());
            }
            
            while (true)
            {
                // find a zero-slack critical edge (v, w) of zero gamma values
                std::pair<edge_descriptor_t, bool> best_edge = null_edge;
                std::vector<vertex_descriptor_t> base_nodes;
                for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
                {
                    if (*vi == base_vertex(*vi))
                        base_nodes.push_back(*vi);
                }
                for (vertex_vec_iter_t i = base_nodes.begin(); i != base_nodes.end(); ++i)
                {
                    if (gamma[*i] == 0)
                    {
                        for (vertex_vec_iter_t j = base_nodes.begin(); j != base_nodes.end(); ++j)
                        {
                            if (critical_edge[*i][*j] != null_edge && slack(critical_edge[*i][*j].first) == 0)
                                best_edge = critical_edge[*i][*j];
                        }
                    }
                }
                
                // if not found, continue finding other augment matching
                if (best_edge == null_edge)
                {
                    bool augmented = augment_matching();
                    return augmented || delta != delta1;
                }
                // if found, determine either augmenting or blossoming
                vertex_descriptor_t v = source(best_edge.first, g), w = target(best_edge.first, g);
                vertex_descriptor_t v_prime = base_vertex(v), w_prime = base_vertex(w), v_free_ancestor, w_free_ancestor;
                vertex_descriptor_t nca = nearest_common_ancestor(v_prime, w_prime, v_free_ancestor, w_free_ancestor);
                if (nca == graph_traits<Graph>::null_vertex())
                {
                    augmenting(v, v_free_ancestor, w, w_free_ancestor);
                    return true;
                }
                else
                    blossoming(v, v_prime, w, w_prime, nca);
            }
            
            return false;
        }
        
        template <typename PropertyMap>
        void get_current_matching(PropertyMap pm)
        {
            vertex_iterator_t vi, vi_end;
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
                put(pm, *vi, mate[*vi]);
        }
        
    private:
        
        const Graph& g;
        VertexIndexMap vm;
        const std::pair<edge_descriptor_t, bool> null_edge;
        
        // storage for the property maps below
        std::vector<vertex_descriptor_t> mate_vector;
        std::vector<vertex_descriptor_t> label_S_vector, label_T_vector;
        std::vector<vertex_descriptor_t> outlet_vector;
        std::vector<vertex_descriptor_t> tau_idx_vector;
        std::vector<edge_property_t> dual_var_vector;
        std::vector<edge_property_t> pi_vector, gamma_vector, tau_vector;
        std::vector<blossom_ptr_t> in_blossom_vector;
        std::vector<std::pair<vertex_descriptor_t, vertex_descriptor_t> > old_label_vector;
        std::vector<vertex_to_edge_map_t> critical_edge_vector;
        std::vector<std::vector<std::pair<edge_descriptor_t, bool> > > critical_edge_vectors;
        
        // iterator property maps
        vertex_to_vertex_map_t mate;
        vertex_to_vertex_map_t label_S; // v has an S-label -> v can be an even vertex, label_S[v] is its mate
        vertex_to_vertex_map_t label_T; // v has a T-label -> v can be an odd vertex, label_T[v] is its predecessor in aug_path
        vertex_to_vertex_map_t outlet;
        vertex_to_vertex_map_t tau_idx;
        vertex_to_weight_map_t dual_var;
        vertex_to_weight_map_t pi, gamma, tau;
        vertex_to_blossom_map_t in_blossom; // map any vertex v to the trivial blossom containing v
        vertex_to_pair_map_t old_label; // <old T-label, old outlet> before relabeling or expanding T-blossoms
        vertex_pair_to_edge_map_t critical_edge; // an not matched edge (v, w) is critical if v and w belongs to different S-blossoms
        
        vertex_list_t aug_path;
        edge_list_t even_edges;
        std::vector<blossom_ptr_t> top_blossoms;
        
    };
    
    template <typename Graph, typename MateMap, typename VertexIndexMap>
    void maximum_weighted_matching(const Graph& g, MateMap mate, VertexIndexMap vm)
    {
        empty_matching<Graph, MateMap>::find_matching(g, mate);
        weighted_augmenting_path_finder<Graph, MateMap, VertexIndexMap> augmentor(g, mate, vm);
        
        // can have |V| times augmenting at most
        for (std::size_t t = 0; t < num_vertices(g); ++t)
        {
            bool augmented = false;
            while (!augmented)
            {
                augmented = augmentor.augment_matching();
                if (!augmented)
                {
                    // halt if adjusting dual variables can't bring potential augment
                    if (!augmentor.adjust_dual())
                        break;
                }
            }
            if (!augmented)
                break;
        }
        
        augmentor.get_current_matching(mate);
    }
    
    template <typename Graph, typename MateMap>
    inline void maximum_weighted_matching(const Graph& g, MateMap mate)
    {
        maximum_weighted_matching(g, mate, get(vertex_index,g));
    }
    
    // brute-force matcher searches all possible combinations of matched edges to get the maximum weighted matching
    // which can be used for testing on small graphs (within dozens vertices)
    template <typename Graph, typename MateMap, typename VertexIndexMap>
    class brute_force_matching
    {
    public:
        
        typedef typename graph_traits<Graph>::vertex_descriptor vertex_descriptor_t;
        typedef typename graph_traits<Graph>::vertex_iterator vertex_iterator_t;
        typedef typename std::vector<vertex_descriptor_t>::iterator vertex_vec_iter_t;
        typedef typename graph_traits<Graph>::edge_iterator edge_iterator_t;
        typedef boost::iterator_property_map<vertex_vec_iter_t, VertexIndexMap> vertex_to_vertex_map_t;
        
        brute_force_matching(const Graph& arg_g, MateMap arg_mate, VertexIndexMap arg_vm) :
        g(arg_g),
        vm(arg_vm),
        mate_vector(num_vertices(g)),
        best_mate_vector(num_vertices(g)),
        mate(mate_vector.begin(), vm),
        best_mate(best_mate_vector.begin(), vm)
        {
            vertex_iterator_t vi,vi_end;
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
                best_mate[*vi] = mate[*vi] = get(arg_mate, *vi);
        }
        
        template <typename PropertyMap>
        void find_matching(PropertyMap pm)
        {
            edge_iterator_t ei;
            boost::tie(ei, ei_end) = edges(g);
            select_edge(ei);
            
            vertex_iterator_t vi,vi_end;
            for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
                put(pm, *vi, best_mate[*vi]);
        }
        
    private:
        
        const Graph& g;
        VertexIndexMap vm;
        std::vector<vertex_descriptor_t> mate_vector, best_mate_vector;
        vertex_to_vertex_map_t mate, best_mate;
        edge_iterator_t ei_end;
        
        void select_edge(edge_iterator_t ei)
        {
            if (ei == ei_end)
            {
                if (matching_weight_sum(g, mate) > matching_weight_sum(g, best_mate))
                {
                    vertex_iterator_t vi, vi_end;
                    for (boost::tie(vi,vi_end) = vertices(g); vi != vi_end; ++vi)
                        best_mate[*vi] = mate[*vi];
                }
                return;
            }
            
            vertex_descriptor_t v, w;
            v = source(*ei, g);
            w = target(*ei, g);
            
            select_edge(++ei);
            
            if (mate[v] == graph_traits<Graph>::null_vertex() &&
                mate[w] == graph_traits<Graph>::null_vertex())
            {
                mate[v] = w;
                mate[w] = v;
                select_edge(ei);
                mate[v] = mate[w] = graph_traits<Graph>::null_vertex();
            }
        }
        
    };
    
    template <typename Graph, typename MateMap, typename VertexIndexMap>
    void brute_force_maximum_weighted_matching(const Graph& g, MateMap mate, VertexIndexMap vm)
    {
        empty_matching<Graph, MateMap>::find_matching(g, mate);
        brute_force_matching<Graph, MateMap, VertexIndexMap> brute_force_matcher(g, mate, vm);
        brute_force_matcher.find_matching(mate);
    }
    
    template <typename Graph, typename MateMap>
    inline void brute_force_maximum_weighted_matching(const Graph& g, MateMap mate)
    {
        brute_force_maximum_weighted_matching(g, mate, get(vertex_index, g));
    }
    
}

#endif