hTSrSSKrSSKrSSKrSSKJr SSKJ r /SQr \ "S5r \RSSj5r\RSSj5rS rS r\RSS j5r\r\R"S S 9SSj5rg)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_matchinginfc^^^^ ^ ^ ^ UUU U U U 4SjnUUUU U 4Sjm[TU5um nT Vs0sHoDS_M snm UVs0sHoDS_M snm 0m[R"5m SnU"5(a3T HnT UbM T"U5(dMUS- nM! U"5(aM3T R5VVs0sH updUcM Xd_M snnm T R5VVs0sH updUcM Xd_M snnm [ [ R "T R5T R555$s snfs snfs snnfs snnf)a Returns 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. . cb>TH*nTUcSTU'TRU5 M![TU'M, [TS'T(adTR5nTUTS:a?TUH6nTTU[LdMTUS-TTU'TRTU5 M8 T(aMdTS[L$)Nr)appendINFINITYpopleft)vuG distancesleft leftmatchesqueue rightmatchess X/var/www/html/env/lib/python3.13/site-packages/networkx/algorithms/bipartite/matching.pybreadth_first_search4hopcroft_karp_matching..breadth_first_searchsA1~% !  Q' !  # $ A|io-1A a1X=5>q\A5E ,q/2 \!_5eh..c>UbFTUH3nTTUTUS-:XdMT"TU5(dM)UTU'UTU' g [TU'gg)Nr TF)r)rrrdepth_first_searchrrrs rr2hopcroft_karp_matching..depth_first_searchse =qT\!_-11AA),q/::*+ Q)* A#  $IaLrNrr )bipartite_sets collectionsdequeitemsdict itertoolschain) r top_nodesrrightrnum_matched_pairskrrrrrrs ` @@@@@@rrr:s:J//"  !I.KD%$()Dqd7D)K%*+UtGU+LI    E  A1~%%a((%*%  %0$5$5$7I$7DA1414$7IK%1%7%7%9K%9TQQDAD%9KL   1 1 3\5G5G5IJ KK1*+JKs# D: D?= E E' E 4E c^ ^ ^ ^ ^ [X5up#[R"URU55n0m UHnXHnUT ;dM UT U' M M 0m /m UVs0sHoDT _M snm T H nT T U M [ T 5nU(aT (d0nUH7nXH,nUT ;dM UR U/5R U5 M. M9 /nUH?nXuT U'UT ;aUR T U5 UT T U'M.T R U5 MA U(a T (dMT (d!T R5H nUT T U'M T $U U U U U 4Sjm T H nT "U5 M GMs snf)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>UT;aLTRU5nUH5nUT;dM TRU5nUTLdT"U5(dM0UTU' g g)NTF)pop) rLrpumatchingpredpredsrecurse unmatcheds rr3"eppstein_matching..recurse5sUEzIIaLADy!XXa[?gbkk*+HQK#'  r)r nxDiGraphedgeslist setdefaultrcopy)rr'rr(rrlayernewLayerkeyr0r1r2r3r4s @@@@@rrrsd!.KD 1774=!AH A    &'(a9 a(AXa[!T IHA~ ++Ar299!<E#;a=LL!-()D!%$$Q' II 8 }}*-#''O  A AJY )s% E8cJ^^^^SUUUU4SjjnU"USS9=(d U"USS9$)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>[5nU(aSOSnU[T U5U4/nU(ayUSupVnUS-(aT OT n[U5n X;aIXY4U;dX4U;a;U T ;agURU 5 UR U [T U 5US-45 U(aMyg![ a UR 5 N&f=f)aDReturns 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_dfs;_is_connected_by_alternating_path.._alternating_dfs[s%+ T!A$Z/0&+Bi #Fe+019-/K X'+5%K9W G+#' E* eT!E(^UQY%GHe!   s$B*,4B**CC)rHF)T)rrrQrSrRrTs` ``` r!_is_connected_by_alternating_pathrWDs1.D AT 2 6F 7rc UR5VVs1sHup4[X445iM nnnUVs1sHn[U5iM nnUR5VVs1sHup4[X445U;dMX44iM nnnUVs1sHnXB;d[ XXxU5(dMUiM sn$s snnfs snfs snnfs snf)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# frozensettupler8rW) rr0rRrr edge_setsedgerQrSs r_connected_by_alternating_pathsr]s,08~~/?@/?tqA6"/?I@-67YTU4[YM7WWY&6A)QF*;9*LY  A < , -'    A7 s"B-B3B87B8B>$B>c|[X5up4[U5[U5- nXS-n[XU5nX7- XG--$)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. )r rCr])rr0r'r.Runmatched_verticesUZs rrrsK~ ! 'DAQ#h-/A (Q7A Eae rweight) edge_attrsc&SSKnSSKn[RR X5upV[ U5n[ U5n[ XXSS9n URU RUR5n U RXRU R4'URRU 5n [U 6V V s0sH upX|X_M nn n UR!UR#5V V s0sHupX_M sn n 5 U$s sn n fs sn n f)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_orderrcformat)numpyscipyr6 bipartiterr9rfullshaper datarowcoloptimizelinear_sum_assignmentzipupdater#)rr'rcnpsprr(raVweights_sparseweights left_matchesrrds rr r sD,,##A1KD T A U A( QeNggn**BFF3G6D6I6IG   2 2 23;;44W=L #\ 23 2qt 2A3HHqwwy )ytqady )* H 4*s ;D/D )N)Nrc)__doc__r!r%networkxr6networkx.algorithms.bipartiterr $networkx.algorithms.bipartite.matrixr__all__floatr _dispatchablerrrWr]rrr rVrrrs:@C  <{L{L|GGT;|#LGGZ*X&T 'T r