{
  "__type": "IngestedDoc",
  "__tag": 4010,
  "_content": {
    "Notes": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "This function implements the Hopcroft--Karp algorithm "
            },
            {
              "__type": "FootnoteReference",
              "__tag": 4066,
              "label": "1"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ". Its time complexity is "
            },
            {
              "__type": "InlineMath",
              "__tag": 4057,
              "value": "O(\\lvert E \\rvert \\sqrt{\\lvert V \\rvert})"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ", and its space complexity is linear in the number of rows. In practice, this asymmetry between rows and columns means that it can be more efficient to transpose the input if it contains more columns than rows."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "By Konig's theorem, the cardinality of the matching is also the number of vertices appearing in a minimum vertex cover of the graph."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Note that if the sparse representation contains explicit zeros, these are still counted as edges."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The implementation was changed in SciPy 1.4.0 to allow matching of general bipartite graphs, where previous versions would assume that a perfect matching existed. As such, code written against 1.4.0 will not necessarily work on older versions."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "If multiple valid solutions are possible, output may vary with SciPy and Python version."
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Warns": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Raises": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Yields": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Methods": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Returns": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Parameters",
          "__tag": 4026,
          "children": [
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "perm",
              "annotation": "ndarray",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "A matching of the vertices in one of the two partitions. Unmatched vertices are represented by a "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "-1"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " in the result."
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Summary": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Returns a matching of a bipartite graph whose cardinality is at least that of any given matching of the graph."
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Receives": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Warnings": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Attributes": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Parameters": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Parameters",
          "__tag": 4026,
          "children": [
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "graph",
              "annotation": "sparse array or matrix",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "Input sparse in CSR format whose rows represent one partition of the graph and whose columns represent the other partition. An edge between two vertices is indicated by the corresponding entry in the matrix existing in its sparse representation."
                    }
                  ]
                }
              ]
            },
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "perm_type",
              "annotation": "str, {'row', 'column'}",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "Which partition to return the matching in terms of: If "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "'row'"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": ", the function produces an array whose length is the number of columns in the input, and whose "
                    },
                    {
                      "__type": "InlineMath",
                      "__tag": 4057,
                      "value": "j"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "'th element is the row matched to the "
                    },
                    {
                      "__type": "InlineMath",
                      "__tag": 4057,
                      "value": "j"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "'th column. Conversely, if "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "perm_type"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " is "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "'column'"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": ", this returns the columns matched to each row."
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Extended Summary": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Other Parameters": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    }
  },
  "_ordered_sections": [
    "Summary",
    "Extended Summary",
    "Parameters",
    "Attributes",
    "Methods",
    "Returns",
    "Yields",
    "Receives",
    "Other Parameters",
    "Raises",
    "Warns",
    "Warnings",
    "Notes"
  ],
  "item_file": null,
  "item_line": null,
  "item_type": "cython_function_or_method",
  "aliases": [
    "scipy.sparse.csgraph.maximum_bipartite_matching"
  ],
  "example_section_data": {
    "__type": "Section",
    "__tag": 4015,
    "children": [
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "from scipy.sparse import csr_array\nfrom scipy.sparse.csgraph import maximum_bipartite_matching\n",
        "execution_status": "success"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nAs a simple example, consider a bipartite graph in which the partitions\ncontain 2 and 3 elements respectively. Suppose that one partition contains\nvertices labelled 0 and 1, and that the other partition contains vertices\nlabelled A, B, and C. Suppose that there are edges connecting 0 and C,\n1 and A, and 1 and B. This graph would then be represented by the following\nsparse array:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "graph = csr_array([[0, 0, 1], [1, 1, 0]])\n",
        "execution_status": "success"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nHere, the 1s could be anything, as long as they end up being stored as\nelements in the sparse array. We can now calculate maximum matchings as\nfollows:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "print(maximum_bipartite_matching(graph, perm_type='column'))\nprint(maximum_bipartite_matching(graph, perm_type='row'))\n",
        "execution_status": "success"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nThe first output tells us that 1 and 2 are matched with C and A\nrespectively, and the second output tells us that A, B, and C are matched\nwith 1, nothing, and 0 respectively.\n\nNote that explicit zeros are still converted to edges. This means that a\ndifferent way to represent the above graph is by using the CSR structure\ndirectly as follows:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "data = [0, 0, 0]\nindices = [2, 0, 1]\nindptr = [0, 1, 3]\ngraph = csr_array((data, indices, indptr))\nprint(maximum_bipartite_matching(graph, perm_type='column'))\nprint(maximum_bipartite_matching(graph, perm_type='row'))\n",
        "execution_status": "success"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nWhen one or both of the partitions are empty, the matching is empty as\nwell:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "graph = csr_array((2, 0))\nprint(maximum_bipartite_matching(graph, perm_type='column'))\nprint(maximum_bipartite_matching(graph, perm_type='row'))\n",
        "execution_status": "success"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nWhen the input array is square, and the graph is known to admit a perfect\nmatching, i.e. a matching with the property that every vertex in the graph\nbelongs to some edge in the matching, then one can view the output as the\npermutation of rows (or columns) turning the input array into one with the\nproperty that all diagonal elements are non-empty:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "a = [[0, 1, 2, 0], [1, 0, 0, 1], [2, 0, 0, 3], [0, 1, 3, 0]]\ngraph = csr_array(a)\nperm = maximum_bipartite_matching(graph, perm_type='row')\nprint(graph[perm].toarray())\n",
        "execution_status": "success"
      }
    ],
    "title": [],
    "level": 0,
    "target": null
  },
  "see_also": [],
  "signature": {
    "__type": "SignatureNode",
    "__tag": 4029,
    "kind": "function",
    "parameters": [
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "graph",
        "annotation": {
          "__type": "Empty",
          "__tag": 4031
        },
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": {
          "__type": "Empty",
          "__tag": 4031
        }
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "perm_type",
        "annotation": {
          "__type": "Empty",
          "__tag": 4031
        },
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "row"
      }
    ],
    "return_annotation": {
      "__type": "Empty",
      "__tag": 4031
    },
    "target_name": "maximum_bipartite_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. :doi:`10.1137/0202019`"
  ],
  "qa": "scipy.sparse.csgraph._matching:maximum_bipartite_matching",
  "arbitrary": [],
  "local_refs": [
    "graph",
    "perm",
    "perm_type"
  ]
}