wgTdZddlZddlZddlZddlmZddlm Z gdZ e dZ ejddZejddZd Zd Zejdd ZeZejd ddZy)a'Provides functions for computing maximum cardinality matchings and minimum weight full matchings in a bipartite graph. If you don't care about the particular implementation of the maximum matching algorithm, simply use the :func:`maximum_matching`. If you do care, you can import one of the named maximum matching algorithms directly. For example, to find a maximum matching in the complete bipartite graph with two vertices on the left and three vertices on the right: >>> G = nx.complete_bipartite_graph(2, 3) >>> left, right = nx.bipartite.sets(G) >>> list(left) [0, 1] >>> list(right) [2, 3, 4] >>> nx.bipartite.maximum_matching(G) {0: 2, 1: 3, 2: 0, 3: 1} The dictionary returned by :func:`maximum_matching` includes a mapping for vertices in both the left and right vertex sets. Similarly, :func:`minimum_weight_full_matching` produces, for a complete weighted bipartite graph, a matching whose cardinality is the cardinality of the smaller of the two partitions, and for which the sum of the weights of the edges included in the matching is minimal. N)sets)biadjacency_matrix)maximum_matchinghopcroft_karp_matchingeppstein_matchingto_vertex_coverminimum_weight_full_matchinginfcZ  fd} fdt|\ } Dcic]}|dc} |Dcic]}|dc} itj d}|r# D]} | |s|dz }|r# jDcic] \}}| || c}} jDcic] \}}| || c}} t t j j jScc}wcc}wcc}}wcc}}w)aReturns the maximum cardinality matching of the bipartite graph `G`. A matching is a set of edges that do not share any nodes. A maximum cardinality matching is a matching with the most edges possible. It is not always unique. Finding a matching in a bipartite graph can be treated as a networkx flow problem. The functions ``hopcroft_karp_matching`` and ``maximum_matching`` are aliases of the same function. Parameters ---------- G : NetworkX graph Undirected bipartite graph top_nodes : container of nodes Container with all nodes in one bipartite node set. If not supplied it will be computed. But if more than one solution exists an exception will be raised. Returns ------- matches : dictionary The matching is returned as a dictionary, `matches`, such that ``matches[v] == w`` if node `v` is matched to node `w`. Unmatched nodes do not occur as a key in `matches`. Raises ------ AmbiguousSolution Raised if the input bipartite graph is disconnected and no container with all nodes in one bipartite set is provided. When determining the nodes in each bipartite set more than one valid solution is possible if the input graph is disconnected. Notes ----- This function is implemented with the `Hopcroft--Karp matching algorithm `_ for bipartite graphs. See :mod:`bipartite documentation ` for further details on how bipartite graphs are handled in NetworkX. See Also -------- maximum_matching hopcroft_karp_matching eppstein_matching References ---------- .. [1] John E. Hopcroft and Richard M. Karp. "An n^{5 / 2} Algorithm for Maximum Matchings in Bipartite Graphs" In: **SIAM Journal of Computing** 2.4 (1973), pp. 225--231. . c:D]'}|d|<j|t|<)td<rYj}|dkr;|D]3}|tus|dz|<j|5rYdtuS)Nr)appendINFINITYpopleft)vuG distancesleft leftmatchesqueue rightmatchess k/home/mcse/projects/flask/flask-venv/lib/python3.12/site-packages/networkx/algorithms/bipartite/matching.pybreadth_first_searchz4hopcroft_karp_matching..breadth_first_searchs (A1~% !  Q' !  ( # $ A|io-16A a1X=5>q\A5E ,q/2 \!_56h..c|=|D]+}||dzk(s|s!||<||<yt|<yy)Nr TF)r)rrrdepth_first_searchrrrs rrz2hopcroft_karp_matching..depth_first_searchsg =qT $\!_-11AA),q/:*+ Q)* A#  $ $IaLrNrr )bipartite_sets collectionsdequeitemsdict itertoolschain) r top_nodesrrightrnum_matched_pairskrrrrrrs ` @@@@@@rrr:s.J//"  !I.KD%$()q1d7)K%*+AtG+LI    E   +A1~%%a(%*% +  %0$5$5$7IDAq1=1a4IK%1%7%7%9KTQQ]AqDKL   1 1 3\5G5G5IJ KK1*+JKs" D D! D!,D! D'D'c t||\}}tj|j|}i |D]}||D] }| vs| |< i g |Dcic]}| c} D]} |= t }|r si}|D]2}||D](}| vs|j |gj |*4g}|D]<}|| |<| vr|j || |<, j |>|r s s jD] }| |<  S fd D] } | cc}w)aReturns the maximum cardinality matching of the bipartite graph `G`. Parameters ---------- G : NetworkX graph Undirected bipartite graph top_nodes : container Container with all nodes in one bipartite node set. If not supplied it will be computed. But if more than one solution exists an exception will be raised. Returns ------- matches : dictionary The matching is returned as a dictionary, `matching`, such that ``matching[v] == w`` if node `v` is matched to node `w`. Unmatched nodes do not occur as a key in `matching`. Raises ------ AmbiguousSolution Raised if the input bipartite graph is disconnected and no container with all nodes in one bipartite set is provided. When determining the nodes in each bipartite set more than one valid solution is possible if the input graph is disconnected. Notes ----- This function is implemented with David Eppstein's version of the algorithm Hopcroft--Karp algorithm (see :func:`hopcroft_karp_matching`), which originally appeared in the `Python Algorithms and Data Structures library (PADS) `_. See :mod:`bipartite documentation ` for further details on how bipartite graphs are handled in NetworkX. See Also -------- hopcroft_karp_matching c|vrAj|}|D]+}|vsj|}|us |s&||<yy)NTF)pop) rLrpumatchingpredpredsrecurse unmatcheds rr1z"eppstein_matching..recurse5sXEzIIaL(ADy!XXa[?gbk*+HQK#' ( r)rnxDiGraphedgeslist setdefaultrcopy)rr%rr&rrlayernewLayerkeyr.r/r0r1r2s @@@@@rrrsd!I.KD% 1774=!AH 1 A     &'(9 ( "AXa[! "T IH =1=A~ ++Ar299!<= =E (#A;a=LL!-()D!%$$Q'  (I 8 }} .*-#' .O   A AJ Y )s EcHdfd }||dxs ||dS)aReturns True if and only if the vertex `v` is connected to one of the target vertices by an alternating path in `G`. An *alternating path* is a path in which every other edge is in the specified maximum matching (and the remaining edges in the path are not in the matching). An alternating path may have matched edges in the even positions or in the odd positions, as long as the edges alternate between 'matched' and 'unmatched'. `G` is an undirected bipartite NetworkX graph. `v` is a vertex in `G`. `matched_edges` is a set of edges present in a maximum matching in `G`. `unmatched_edges` is a set of edges not present in a maximum matching in `G`. `targets` is a set of vertices. Tc`t}|rdnd}|t ||fg}|rj|d\}}}|dzr n } t|} | |vrE|| f|vs| |f|vr9| vry|j| |j | t | |dzf|rjy#t $r|j YwxYw)atReturns True if and only if `u` is connected to one of the targets by an alternating path. `u` is a vertex in the graph `G`. If `along_matched` is True, this step of the depth-first search will continue only through edges in the given matching. Otherwise, it will continue only through edges *not* in the given matching. rr TF)setiternextaddr StopIterationr+)r along_matchedvisited initial_depthstackparentchildrendepth valid_edgeschildr matched_edgestargetsunmatched_edgess r_alternating_dfsz;_is_connected_by_alternating_path.._alternating_dfs[s%+ T!A$Z/0&+Bi #FHe+019-/K X'+5%K9W G+#' E* eT!E(^UQY%GH!   sB4BB-,B-)rEF)T)rrrNrPrOrQs` ``` r!_is_connected_by_alternating_pathrSDs1.D AT 2 6F 7rc f|jDchc]\}}t||f}}}|Dchc] }t|}}|jDchc]\}}t||f|vs||f}}}|Dchc]}||vst |||||r|c}Scc}}wcc}wcc}}wcc}w)aReturns the set of vertices that are connected to one of the target vertices by an alternating path in `G` or are themselves a target. An *alternating path* is a path in which every other edge is in the specified maximum matching (and the remaining edges in the path are not in the matching). An alternating path may have matched edges in the even positions or in the odd positions, as long as the edges alternate between 'matched' and 'unmatched'. `G` is an undirected bipartite NetworkX graph. `matching` is a dictionary representing a maximum matching in `G`, as returned by, for example, :func:`maximum_matching`. `targets` is a set of vertices. )r! frozensettupler5rS) rr.rOrr edge_setsedgerNrPs r_connected_by_alternating_pathsrYs,08~~/?@tq!Aq6"@I@-67TU4[7M7WWYAq)QF*;9*LAO   < , q-'    A7 sBB#B(1B(>B.ct||\}}t|t|z }||z}t|||}||z ||zzS)aReturns the minimum vertex cover corresponding to the given maximum matching of the bipartite graph `G`. Parameters ---------- G : NetworkX graph Undirected bipartite graph matching : dictionary A dictionary whose keys are vertices in `G` and whose values are the distinct neighbors comprising the maximum matching for `G`, as returned by, for example, :func:`maximum_matching`. The dictionary *must* represent the maximum matching. top_nodes : container Container with all nodes in one bipartite node set. If not supplied it will be computed. But if more than one solution exists an exception will be raised. Returns ------- vertex_cover : :class:`set` The minimum vertex cover in `G`. Raises ------ AmbiguousSolution Raised if the input bipartite graph is disconnected and no container with all nodes in one bipartite set is provided. When determining the nodes in each bipartite set more than one valid solution is possible if the input graph is disconnected. Notes ----- This function is implemented using the procedure guaranteed by `Konig's theorem `_, which proves an equivalence between a maximum matching and a minimum vertex cover in bipartite graphs. Since a minimum vertex cover is the complement of a maximum independent set for any graph, one can compute the maximum independent set of a bipartite graph this way: >>> G = nx.complete_bipartite_graph(2, 3) >>> matching = nx.bipartite.maximum_matching(G) >>> vertex_cover = nx.bipartite.to_vertex_cover(G, matching) >>> independent_set = set(G) - vertex_cover >>> print(list(independent_set)) [2, 3, 4] See :mod:`bipartite documentation ` for further details on how bipartite graphs are handled in NetworkX. )rr@rY)rr.r%r,Runmatched_verticesUZs rrrsW~ !Y 'DAqQ#h-/QA (8Q7A Ea!e rweight) edge_attrsc4ddl}ddl}tjj ||\}}t |}t |}t ||||d} |j| j|j} | j| | j| jf<|jj| } t| D cic]\} } || || }} } |j!|j#D cic]\} } | |  c} } |Scc} } wcc} } w)uReturns a minimum weight full matching of the bipartite graph `G`. Let :math:`G = ((U, V), E)` be a weighted bipartite graph with real weights :math:`w : E \to \mathbb{R}`. This function then produces a matching :math:`M \subseteq E` with cardinality .. math:: \lvert M \rvert = \min(\lvert U \rvert, \lvert V \rvert), which minimizes the sum of the weights of the edges included in the matching, :math:`\sum_{e \in M} w(e)`, or raises an error if no such matching exists. When :math:`\lvert U \rvert = \lvert V \rvert`, this is commonly referred to as a perfect matching; here, since we allow :math:`\lvert U \rvert` and :math:`\lvert V \rvert` to differ, we follow Karp [1]_ and refer to the matching as *full*. Parameters ---------- G : NetworkX graph Undirected bipartite graph top_nodes : container Container with all nodes in one bipartite node set. If not supplied it will be computed. weight : string, optional (default='weight') The edge data key used to provide each value in the matrix. If None, then each edge has weight 1. Returns ------- matches : dictionary The matching is returned as a dictionary, `matches`, such that ``matches[v] == w`` if node `v` is matched to node `w`. Unmatched nodes do not occur as a key in `matches`. Raises ------ ValueError Raised if no full matching exists. ImportError Raised if SciPy is not available. Notes ----- The problem of determining a minimum weight full matching is also known as the rectangular linear assignment problem. This implementation defers the calculation of the assignment to SciPy. References ---------- .. [1] Richard Manning Karp: An algorithm to Solve the m x n Assignment Problem in Expected Time O(mn log n). Networks, 10(2):143–152, 1980. rNcoo) row_order column_orderr_format)numpyscipyr3 bipartiterr6rfullshaper datarowcoloptimizelinear_sum_assignmentzipupdater!)rr%r_npsprr&r]Vweights_sparseweights left_matchesrrds rr r sD,,##Ay1KD% T A U A( QQveNggn**BFF3G6D6I6IGN   2 2 23;;44W=L #\ 2311qt3A3HHqwwy )tq!ad )* H 4*s D7 D )N)Nr_)__doc__rr#networkxr3networkx.algorithms.bipartiterr$networkx.algorithms.bipartite.matrixr__all__floatr _dispatchablerrrSrYrrr rRrrrs:@C  <{L{L|GGT;|#LGGZ*X&T 'T r