scipy 1.16.2__cp313-cp313t-win_arm64.whl

scipy/optimize/_qap.py

@@ -0,0 +1,760 @@
+import numpy as np
+import operator
+import warnings
+import numbers
+from . import (linear_sum_assignment, OptimizeResult)
+from ._optimize import _check_unknown_options
+
+from scipy._lib._util import check_random_state
+import itertools
+
+QUADRATIC_ASSIGNMENT_METHODS = ['faq', '2opt']
+
+
+def quadratic_assignment(A, B, method="faq", options=None):
+    r"""
+    Approximates solution to the quadratic assignment problem and
+    the graph matching problem.
+
+    Quadratic assignment solves problems of the following form:
+
+    .. math::
+
+        \min_P & \ {\ \text{trace}(A^T P B P^T)}\\
+        \mbox{s.t. } & {P \ \epsilon \ \mathcal{P}}\\
+
+    where :math:`\mathcal{P}` is the set of all permutation matrices,
+    and :math:`A` and :math:`B` are square matrices.
+
+    Graph matching tries to *maximize* the same objective function.
+    This algorithm can be thought of as finding the alignment of the
+    nodes of two graphs that minimizes the number of induced edge
+    disagreements, or, in the case of weighted graphs, the sum of squared
+    edge weight differences.
+
+    Note that the quadratic assignment problem is NP-hard. The results given
+    here are approximations and are not guaranteed to be optimal.
+
+
+    Parameters
+    ----------
+    A : 2-D array, square
+        The square matrix :math:`A` in the objective function above.
+
+    B : 2-D array, square
+        The square matrix :math:`B` in the objective function above.
+
+    method :  str in {'faq', '2opt'} (default: 'faq')
+        The algorithm used to solve the problem.
+        :ref:`'faq' <optimize.qap-faq>` (default) and
+        :ref:`'2opt' <optimize.qap-2opt>` are available.
+
+    options : dict, optional
+        A dictionary of solver options. All solvers support the following:
+
+        maximize : bool (default: False)
+            Maximizes the objective function if ``True``.
+
+        partial_match : 2-D array of integers, optional (default: None)
+            Fixes part of the matching. Also known as a "seed" [2]_.
+
+            Each row of `partial_match` specifies a pair of matched nodes:
+            node ``partial_match[i, 0]`` of `A` is matched to node
+            ``partial_match[i, 1]`` of `B`. The array has shape ``(m, 2)``,
+            where ``m`` is not greater than the number of nodes, :math:`n`.
+
+        rng : `numpy.random.Generator`, optional
+            Pseudorandom number generator state. When `rng` is None, a new
+            `numpy.random.Generator` is created using entropy from the
+            operating system. Types other than `numpy.random.Generator` are
+            passed to `numpy.random.default_rng` to instantiate a ``Generator``.
+
+            .. versionchanged:: 1.15.0
+                As part of the `SPEC-007 <https://scientific-python.org/specs/spec-0007/>`_
+                transition from use of `numpy.random.RandomState` to
+                `numpy.random.Generator` is occurring. Supplying
+                `np.random.RandomState` to this function will now emit a
+                `DeprecationWarning`. In SciPy 1.17 its use will raise an exception.
+                In addition relying on global state using `np.random.seed`
+                will emit a `FutureWarning`. In SciPy 1.17 the global random number
+                generator will no longer be used.
+                Use of an int-like seed will raise a `FutureWarning`, in SciPy 1.17 it
+                will be normalized via `np.random.default_rng` rather than
+                `np.random.RandomState`.
+
+        For method-specific options, see
+        :func:`show_options('quadratic_assignment') <show_options>`.
+
+    Returns
+    -------
+    res : OptimizeResult
+        `OptimizeResult` containing the following fields.
+
+        col_ind : 1-D array
+            Column indices corresponding to the best permutation found of the
+            nodes of `B`.
+        fun : float
+            The objective value of the solution.
+        nit : int
+            The number of iterations performed during optimization.
+
+    Notes
+    -----
+    The default method :ref:`'faq' <optimize.qap-faq>` uses the Fast
+    Approximate QAP algorithm [1]_; it typically offers the best combination of
+    speed and accuracy.
+    Method :ref:`'2opt' <optimize.qap-2opt>` can be computationally expensive,
+    but may be a useful alternative, or it can be used to refine the solution
+    returned by another method.
+
+    References
+    ----------
+    .. [1] J.T. Vogelstein, J.M. Conroy, V. Lyzinski, L.J. Podrazik,
+           S.G. Kratzer, E.T. Harley, D.E. Fishkind, R.J. Vogelstein, and
+           C.E. Priebe, "Fast approximate quadratic programming for graph
+           matching," PLOS one, vol. 10, no. 4, p. e0121002, 2015,
+           :doi:`10.1371/journal.pone.0121002`
+
+    .. [2] D. Fishkind, S. Adali, H. Patsolic, L. Meng, D. Singh, V. Lyzinski,
+           C. Priebe, "Seeded graph matching", Pattern Recognit. 87 (2019):
+           203-215, :doi:`10.1016/j.patcog.2018.09.014`
+
+    .. [3] "2-opt," Wikipedia.
+           https://en.wikipedia.org/wiki/2-opt
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scipy.optimize import quadratic_assignment
+    >>> rng = np.random.default_rng()
+    >>> A = np.array([[0, 80, 150, 170], [80, 0, 130, 100],
+    ...               [150, 130, 0, 120], [170, 100, 120, 0]])
+    >>> B = np.array([[0, 5, 2, 7], [0, 0, 3, 8],
+    ...               [0, 0, 0, 3], [0, 0, 0, 0]])
+    >>> res = quadratic_assignment(A, B, options={'rng': rng})
+    >>> print(res)
+         fun: 3260
+     col_ind: [0 3 2 1]
+         nit: 9
+
+    The see the relationship between the returned ``col_ind`` and ``fun``,
+    use ``col_ind`` to form the best permutation matrix found, then evaluate
+    the objective function :math:`f(P) = trace(A^T P B P^T )`.
+
+    >>> perm = res['col_ind']
+    >>> P = np.eye(len(A), dtype=int)[perm]
+    >>> fun = np.trace(A.T @ P @ B @ P.T)
+    >>> print(fun)
+    3260
+
+    Alternatively, to avoid constructing the permutation matrix explicitly,
+    directly permute the rows and columns of the distance matrix.
+
+    >>> fun = np.trace(A.T @ B[perm][:, perm])
+    >>> print(fun)
+    3260
+
+    Although not guaranteed in general, ``quadratic_assignment`` happens to
+    have found the globally optimal solution.
+
+    >>> from itertools import permutations
+    >>> perm_opt, fun_opt = None, np.inf
+    >>> for perm in permutations([0, 1, 2, 3]):
+    ...     perm = np.array(perm)
+    ...     fun = np.trace(A.T @ B[perm][:, perm])
+    ...     if fun < fun_opt:
+    ...         fun_opt, perm_opt = fun, perm
+    >>> print(np.array_equal(perm_opt, res['col_ind']))
+    True
+
+    Here is an example for which the default method,
+    :ref:`'faq' <optimize.qap-faq>`, does not find the global optimum.
+
+    >>> A = np.array([[0, 5, 8, 6], [5, 0, 5, 1],
+    ...               [8, 5, 0, 2], [6, 1, 2, 0]])
+    >>> B = np.array([[0, 1, 8, 4], [1, 0, 5, 2],
+    ...               [8, 5, 0, 5], [4, 2, 5, 0]])
+    >>> res = quadratic_assignment(A, B, options={'rng': rng})
+    >>> print(res)
+         fun: 178
+     col_ind: [1 0 3 2]
+         nit: 13
+
+    If accuracy is important, consider using  :ref:`'2opt' <optimize.qap-2opt>`
+    to refine the solution.
+
+    >>> guess = np.array([np.arange(len(A)), res.col_ind]).T
+    >>> res = quadratic_assignment(A, B, method="2opt",
+    ...     options = {'rng': rng, 'partial_guess': guess})
+    >>> print(res)
+         fun: 176
+     col_ind: [1 2 3 0]
+         nit: 17
+
+    """
+
+    if options is None:
+        options = {}
+
+    method = method.lower()
+    methods = {"faq": _quadratic_assignment_faq,
+               "2opt": _quadratic_assignment_2opt}
+    if method not in methods:
+        raise ValueError(f"method {method} must be in {methods}.")
+
+    _spec007_transition(options.get("rng", None))
+    res = methods[method](A, B, **options)
+    return res
+
+
+def _spec007_transition(rng):
+    if isinstance(rng, np.random.RandomState):
+        warnings.warn(
+            "Use of `RandomState` with `quadratic_assignment` is deprecated"
+            " and will result in an exception in SciPy 1.17",
+            DeprecationWarning,
+            stacklevel=2
+        )
+    if ((rng is None or rng is np.random) and
+            np.random.mtrand._rand._bit_generator._seed_seq is None):
+        warnings.warn(
+            "The NumPy global RNG was seeded by calling `np.random.seed`."
+            " From SciPy 1.17, this function will no longer use the global RNG.",
+            FutureWarning,
+            stacklevel=2
+        )
+    if isinstance(rng, numbers.Integral | np.integer):
+        warnings.warn(
+            "The behavior when the rng option is an integer is changing: the value"
+            " will be normalized using np.random.default_rng beginning in SciPy 1.17,"
+            " and the resulting Generator will be used to generate random numbers.",
+            FutureWarning,
+            stacklevel=2
+        )
+
+
+def _calc_score(A, B, perm):
+    # equivalent to objective function but avoids matmul
+    return np.sum(A * B[perm][:, perm])
+
+
+def _common_input_validation(A, B, partial_match):
+    A = np.atleast_2d(A)
+    B = np.atleast_2d(B)
+
+    if partial_match is None:
+        partial_match = np.array([[], []]).T
+    partial_match = np.atleast_2d(partial_match).astype(int)
+
+    msg = None
+    if A.shape[0] != A.shape[1]:
+        msg = "`A` must be square"
+    elif B.shape[0] != B.shape[1]:
+        msg = "`B` must be square"
+    elif A.ndim != 2 or B.ndim != 2:
+        msg = "`A` and `B` must have exactly two dimensions"
+    elif A.shape != B.shape:
+        msg = "`A` and `B` matrices must be of equal size"
+    elif partial_match.shape[0] > A.shape[0]:
+        msg = "`partial_match` can have only as many seeds as there are nodes"
+    elif partial_match.shape[1] != 2:
+        msg = "`partial_match` must have two columns"
+    elif partial_match.ndim != 2:
+        msg = "`partial_match` must have exactly two dimensions"
+    elif (partial_match < 0).any():
+        msg = "`partial_match` must contain only positive indices"
+    elif (partial_match >= len(A)).any():
+        msg = "`partial_match` entries must be less than number of nodes"
+    elif (not len(set(partial_match[:, 0])) == len(partial_match[:, 0]) or
+          not len(set(partial_match[:, 1])) == len(partial_match[:, 1])):
+        msg = "`partial_match` column entries must be unique"
+
+    if msg is not None:
+        raise ValueError(msg)
+
+    return A, B, partial_match
+
+
+def _quadratic_assignment_faq(A, B,
+                              maximize=False, partial_match=None, rng=None,
+                              P0="barycenter", shuffle_input=False, maxiter=30,
+                              tol=0.03, **unknown_options):
+    r"""Solve the quadratic assignment problem (approximately).
+
+    This function solves the Quadratic Assignment Problem (QAP) and the
+    Graph Matching Problem (GMP) using the Fast Approximate QAP Algorithm
+    (FAQ) [1]_.
+
+    Quadratic assignment solves problems of the following form:
+
+    .. math::
+
+        \min_P & \ {\ \text{trace}(A^T P B P^T)}\\
+        \mbox{s.t. } & {P \ \epsilon \ \mathcal{P}}\\
+
+    where :math:`\mathcal{P}` is the set of all permutation matrices,
+    and :math:`A` and :math:`B` are square matrices.
+
+    Graph matching tries to *maximize* the same objective function.
+    This algorithm can be thought of as finding the alignment of the
+    nodes of two graphs that minimizes the number of induced edge
+    disagreements, or, in the case of weighted graphs, the sum of squared
+    edge weight differences.
+
+    Note that the quadratic assignment problem is NP-hard. The results given
+    here are approximations and are not guaranteed to be optimal.
+
+    Parameters
+    ----------
+    A : 2-D array, square
+        The square matrix :math:`A` in the objective function above.
+    B : 2-D array, square
+        The square matrix :math:`B` in the objective function above.
+    method :  str in {'faq', '2opt'} (default: 'faq')
+        The algorithm used to solve the problem. This is the method-specific
+        documentation for 'faq'.
+        :ref:`'2opt' <optimize.qap-2opt>` is also available.
+
+    Options
+    -------
+    maximize : bool (default: False)
+        Maximizes the objective function if ``True``.
+    partial_match : 2-D array of integers, optional (default: None)
+        Fixes part of the matching. Also known as a "seed" [2]_.
+
+        Each row of `partial_match` specifies a pair of matched nodes:
+        node ``partial_match[i, 0]`` of `A` is matched to node
+        ``partial_match[i, 1]`` of `B`. The array has shape ``(m, 2)``, where
+        ``m`` is not greater than the number of nodes, :math:`n`.
+
+    rng : {None, int, `numpy.random.Generator`}, optional
+        Pseudorandom number generator state. See `quadratic_assignment` for details.
+    P0 : 2-D array, "barycenter", or "randomized" (default: "barycenter")
+        Initial position. Must be a doubly-stochastic matrix [3]_.
+
+        If the initial position is an array, it must be a doubly stochastic
+        matrix of size :math:`m' \times m'` where :math:`m' = n - m`.
+
+        If ``"barycenter"`` (default), the initial position is the barycenter
+        of the Birkhoff polytope (the space of doubly stochastic matrices).
+        This is a :math:`m' \times m'` matrix with all entries equal to
+        :math:`1 / m'`.
+
+        If ``"randomized"`` the initial search position is
+        :math:`P_0 = (J + K) / 2`, where :math:`J` is the barycenter and
+        :math:`K` is a random doubly stochastic matrix.
+    shuffle_input : bool (default: False)
+        Set to `True` to resolve degenerate gradients randomly. For
+        non-degenerate gradients this option has no effect.
+    maxiter : int, positive (default: 30)
+        Integer specifying the max number of Frank-Wolfe iterations performed.
+    tol : float (default: 0.03)
+        Tolerance for termination. Frank-Wolfe iteration terminates when
+        :math:`\frac{||P_{i}-P_{i+1}||_F}{\sqrt{m'}} \leq tol`,
+        where :math:`i` is the iteration number.
+
+    Returns
+    -------
+    res : OptimizeResult
+        `OptimizeResult` containing the following fields.
+
+        col_ind : 1-D array
+            Column indices corresponding to the best permutation found of the
+            nodes of `B`.
+        fun : float
+            The objective value of the solution.
+        nit : int
+            The number of Frank-Wolfe iterations performed.
+
+    Notes
+    -----
+    The algorithm may be sensitive to the initial permutation matrix (or
+    search "position") due to the possibility of several local minima
+    within the feasible region. A barycenter initialization is more likely to
+    result in a better solution than a single random initialization. However,
+    calling ``quadratic_assignment`` several times with different random
+    initializations may result in a better optimum at the cost of longer
+    total execution time.
+
+    Examples
+    --------
+    As mentioned above, a barycenter initialization often results in a better
+    solution than a single random initialization.
+
+    >>> from scipy.optimize import quadratic_assignment
+    >>> import numpy as np
+    >>> rng = np.random.default_rng()
+    >>> n = 15
+    >>> A = rng.random((n, n))
+    >>> B = rng.random((n, n))
+    >>> options = {"rng": rng}
+    >>> res = quadratic_assignment(A, B, options=options)  # FAQ is default method
+    >>> print(res.fun)
+    47.797048706380636  # may vary
+
+    >>> options = {"rng": rng, "P0": "randomized"}  # use randomized initialization
+    >>> res = quadratic_assignment(A, B, options=options)
+    >>> print(res.fun)
+    47.37287069769966 # may vary
+
+    However, consider running from several randomized initializations and
+    keeping the best result.
+
+    >>> res = min([quadratic_assignment(A, B, options=options)
+    ...            for i in range(30)], key=lambda x: x.fun)
+    >>> print(res.fun)
+    46.55974835248574 # may vary
+
+    The '2-opt' method can be used to attempt to refine the results.
+
+    >>> options = {"partial_guess": np.array([np.arange(n), res.col_ind]).T, "rng": rng}
+    >>> res = quadratic_assignment(A, B, method="2opt", options=options)
+    >>> print(res.fun)
+    46.55974835248574 # may vary
+
+    References
+    ----------
+    .. [1] J.T. Vogelstein, J.M. Conroy, V. Lyzinski, L.J. Podrazik,
+           S.G. Kratzer, E.T. Harley, D.E. Fishkind, R.J. Vogelstein, and
+           C.E. Priebe, "Fast approximate quadratic programming for graph
+           matching," PLOS one, vol. 10, no. 4, p. e0121002, 2015,
+           :doi:`10.1371/journal.pone.0121002`
+
+    .. [2] D. Fishkind, S. Adali, H. Patsolic, L. Meng, D. Singh, V. Lyzinski,
+           C. Priebe, "Seeded graph matching", Pattern Recognit. 87 (2019):
+           203-215, :doi:`10.1016/j.patcog.2018.09.014`
+
+    .. [3] "Doubly stochastic Matrix," Wikipedia.
+           https://en.wikipedia.org/wiki/Doubly_stochastic_matrix
+
+    """
+
+    _check_unknown_options(unknown_options)
+
+    maxiter = operator.index(maxiter)
+
+    # ValueError check
+    A, B, partial_match = _common_input_validation(A, B, partial_match)
+
+    msg = None
+    if isinstance(P0, str) and P0 not in {'barycenter', 'randomized'}:
+        msg = "Invalid 'P0' parameter string"
+    elif maxiter <= 0:
+        msg = "'maxiter' must be a positive integer"
+    elif tol <= 0:
+        msg = "'tol' must be a positive float"
+    if msg is not None:
+        raise ValueError(msg)
+
+    rng = check_random_state(rng)
+    n = len(A)  # number of vertices in graphs
+    n_seeds = len(partial_match)  # number of seeds
+    n_unseed = n - n_seeds
+
+    # [1] Algorithm 1 Line 1 - choose initialization
+    if not isinstance(P0, str):
+        P0 = np.atleast_2d(P0)
+        if P0.shape != (n_unseed, n_unseed):
+            msg = "`P0` matrix must have shape m' x m', where m'=n-m"
+        elif ((P0 < 0).any() or not np.allclose(np.sum(P0, axis=0), 1)
+              or not np.allclose(np.sum(P0, axis=1), 1)):
+            msg = "`P0` matrix must be doubly stochastic"
+        if msg is not None:
+            raise ValueError(msg)
+    elif P0 == 'barycenter':
+        P0 = np.ones((n_unseed, n_unseed)) / n_unseed
+    elif P0 == 'randomized':
+        J = np.ones((n_unseed, n_unseed)) / n_unseed
+        # generate a nxn matrix where each entry is a random number [0, 1]
+        # would use rand, but Generators don't have it
+        # would use random, but old mtrand.RandomStates don't have it
+        K = _doubly_stochastic(rng.uniform(size=(n_unseed, n_unseed)))
+        P0 = (J + K) / 2
+
+    # check trivial cases
+    if n == 0 or n_seeds == n:
+        score = _calc_score(A, B, partial_match[:, 1])
+        res = {"col_ind": partial_match[:, 1], "fun": score, "nit": 0}
+        return OptimizeResult(res)
+
+    obj_func_scalar = 1
+    if maximize:
+        obj_func_scalar = -1
+
+    nonseed_B = np.setdiff1d(range(n), partial_match[:, 1])
+    if shuffle_input:
+        nonseed_B = rng.permutation(nonseed_B)
+
+    nonseed_A = np.setdiff1d(range(n), partial_match[:, 0])
+    perm_A = np.concatenate([partial_match[:, 0], nonseed_A])
+    perm_B = np.concatenate([partial_match[:, 1], nonseed_B])
+
+    # definitions according to Seeded Graph Matching [2].
+    A11, A12, A21, A22 = _split_matrix(A[perm_A][:, perm_A], n_seeds)
+    B11, B12, B21, B22 = _split_matrix(B[perm_B][:, perm_B], n_seeds)
+    const_sum = A21 @ B21.T + A12.T @ B12
+
+    P = P0
+    # [1] Algorithm 1 Line 2 - loop while stopping criteria not met
+    for n_iter in range(1, maxiter+1):
+        # [1] Algorithm 1 Line 3 - compute the gradient of f(P) = -tr(APB^tP^t)
+        grad_fp = (const_sum + A22 @ P @ B22.T + A22.T @ P @ B22)
+        # [1] Algorithm 1 Line 4 - get direction Q by solving Eq. 8
+        _, cols = linear_sum_assignment(grad_fp, maximize=maximize)
+        Q = np.eye(n_unseed)[cols]
+
+        # [1] Algorithm 1 Line 5 - compute the step size
+        # Noting that e.g. trace(Ax) = trace(A)*x, expand and re-collect
+        # terms as ax**2 + bx + c. c does not affect location of minimum
+        # and can be ignored. Also, note that trace(A@B) = (A.T*B).sum();
+        # apply where possible for efficiency.
+        R = P - Q
+        b21 = ((R.T @ A21) * B21).sum()
+        b12 = ((R.T @ A12.T) * B12.T).sum()
+        AR22 = A22.T @ R
+        BR22 = B22 @ R.T
+        b22a = (AR22 * B22.T[cols]).sum()
+        b22b = (A22 * BR22[cols]).sum()
+        a = (AR22.T * BR22).sum()
+        b = b21 + b12 + b22a + b22b
+        # critical point of ax^2 + bx + c is at x = -d/(2*e)
+        # if a * obj_func_scalar > 0, it is a minimum
+        # if minimum is not in [0, 1], only endpoints need to be considered
+        if a*obj_func_scalar > 0 and 0 <= -b/(2*a) <= 1:
+            alpha = -b/(2*a)
+        else:
+            alpha = np.argmin([0, (b + a)*obj_func_scalar])
+
+        # [1] Algorithm 1 Line 6 - Update P
+        P_i1 = alpha * P + (1 - alpha) * Q
+        if np.linalg.norm(P - P_i1) / np.sqrt(n_unseed) < tol:
+            P = P_i1
+            break
+        P = P_i1
+    # [1] Algorithm 1 Line 7 - end main loop
+
+    # [1] Algorithm 1 Line 8 - project onto the set of permutation matrices
+    _, col = linear_sum_assignment(P, maximize=True)
+    perm = np.concatenate((np.arange(n_seeds), col + n_seeds))
+
+    unshuffled_perm = np.zeros(n, dtype=int)
+    unshuffled_perm[perm_A] = perm_B[perm]
+
+    score = _calc_score(A, B, unshuffled_perm)
+    res = {"col_ind": unshuffled_perm, "fun": score, "nit": n_iter}
+    return OptimizeResult(res)
+
+
+def _split_matrix(X, n):
+    # definitions according to Seeded Graph Matching [2].
+    upper, lower = X[:n], X[n:]
+    return upper[:, :n], upper[:, n:], lower[:, :n], lower[:, n:]
+
+
+def _doubly_stochastic(P, tol=1e-3):
+    # Adapted from @btaba implementation
+    # https://github.com/btaba/sinkhorn_knopp
+    # of Sinkhorn-Knopp algorithm
+    # https://projecteuclid.org/euclid.pjm/1102992505
+
+    max_iter = 1000
+    c = 1 / P.sum(axis=0)
+    r = 1 / (P @ c)
+    P_eps = P
+
+    for it in range(max_iter):
+        if ((np.abs(P_eps.sum(axis=1) - 1) < tol).all() and
+                (np.abs(P_eps.sum(axis=0) - 1) < tol).all()):
+            # All column/row sums ~= 1 within threshold
+            break
+
+        c = 1 / (r @ P)
+        r = 1 / (P @ c)
+        P_eps = r[:, None] * P * c
+
+    return P_eps
+
+
+def _quadratic_assignment_2opt(A, B, maximize=False, rng=None,
+                               partial_match=None,
+                               partial_guess=None,
+                               **unknown_options):
+    r"""Solve the quadratic assignment problem (approximately).
+
+    This function solves the Quadratic Assignment Problem (QAP) and the
+    Graph Matching Problem (GMP) using the 2-opt algorithm [1]_.
+
+    Quadratic assignment solves problems of the following form:
+
+    .. math::
+
+        \min_P & \ {\ \text{trace}(A^T P B P^T)}\\
+        \mbox{s.t. } & {P \ \epsilon \ \mathcal{P}}\\
+
+    where :math:`\mathcal{P}` is the set of all permutation matrices,
+    and :math:`A` and :math:`B` are square matrices.
+
+    Graph matching tries to *maximize* the same objective function.
+    This algorithm can be thought of as finding the alignment of the
+    nodes of two graphs that minimizes the number of induced edge
+    disagreements, or, in the case of weighted graphs, the sum of squared
+    edge weight differences.
+
+    Note that the quadratic assignment problem is NP-hard. The results given
+    here are approximations and are not guaranteed to be optimal.
+
+    Parameters
+    ----------
+    A : 2-D array, square
+        The square matrix :math:`A` in the objective function above.
+    B : 2-D array, square
+        The square matrix :math:`B` in the objective function above.
+    method :  str in {'faq', '2opt'} (default: 'faq')
+        The algorithm used to solve the problem. This is the method-specific
+        documentation for '2opt'.
+        :ref:`'faq' <optimize.qap-faq>` is also available.
+
+    Options
+    -------
+    maximize : bool (default: False)
+        Maximizes the objective function if ``True``.
+    rng : {None, int, `numpy.random.Generator`}, optional
+        Pseudorandom number generator state. See `quadratic_assignment` for details.
+    partial_match : 2-D array of integers, optional (default: None)
+        Fixes part of the matching. Also known as a "seed" [2]_.
+
+        Each row of `partial_match` specifies a pair of matched nodes: node
+        ``partial_match[i, 0]`` of `A` is matched to node
+        ``partial_match[i, 1]`` of `B`. The array has shape ``(m, 2)``,
+        where ``m`` is not greater than the number of nodes, :math:`n`.
+
+        .. note::
+             `partial_match` must be sorted by the first column.
+
+    partial_guess : 2-D array of integers, optional (default: None)
+        A guess for the matching between the two matrices. Unlike
+        `partial_match`, `partial_guess` does not fix the indices; they are
+        still free to be optimized.
+
+        Each row of `partial_guess` specifies a pair of matched nodes: node
+        ``partial_guess[i, 0]`` of `A` is matched to node
+        ``partial_guess[i, 1]`` of `B`. The array has shape ``(m, 2)``,
+        where ``m`` is not greater than the number of nodes, :math:`n`.
+
+        .. note::
+                `partial_guess` must be sorted by the first column.
+
+    Returns
+    -------
+    res : OptimizeResult
+        `OptimizeResult` containing the following fields.
+
+        col_ind : 1-D array
+            Column indices corresponding to the best permutation found of the
+            nodes of `B`.
+        fun : float
+            The objective value of the solution.
+        nit : int
+            The number of iterations performed during optimization.
+
+    Notes
+    -----
+    This is a greedy algorithm that works similarly to bubble sort: beginning
+    with an initial permutation, it iteratively swaps pairs of indices to
+    improve the objective function until no such improvements are possible.
+
+    References
+    ----------
+    .. [1] "2-opt," Wikipedia.
+           https://en.wikipedia.org/wiki/2-opt
+
+    .. [2] D. Fishkind, S. Adali, H. Patsolic, L. Meng, D. Singh, V. Lyzinski,
+           C. Priebe, "Seeded graph matching", Pattern Recognit. 87 (2019):
+           203-215, https://doi.org/10.1016/j.patcog.2018.09.014
+
+    """
+    _check_unknown_options(unknown_options)
+    rng = check_random_state(rng)
+    A, B, partial_match = _common_input_validation(A, B, partial_match)
+
+    N = len(A)
+    # check trivial cases
+    if N == 0 or partial_match.shape[0] == N:
+        score = _calc_score(A, B, partial_match[:, 1])
+        res = {"col_ind": partial_match[:, 1], "fun": score, "nit": 0}
+        return OptimizeResult(res)
+
+    if partial_guess is None:
+        partial_guess = np.array([[], []]).T
+    partial_guess = np.atleast_2d(partial_guess).astype(int)
+
+    msg = None
+    if partial_guess.shape[0] > A.shape[0]:
+        msg = ("`partial_guess` can have only as "
+               "many entries as there are nodes")
+    elif partial_guess.shape[1] != 2:
+        msg = "`partial_guess` must have two columns"
+    elif partial_guess.ndim != 2:
+        msg = "`partial_guess` must have exactly two dimensions"
+    elif (partial_guess < 0).any():
+        msg = "`partial_guess` must contain only positive indices"
+    elif (partial_guess >= len(A)).any():
+        msg = "`partial_guess` entries must be less than number of nodes"
+    elif (not len(set(partial_guess[:, 0])) == len(partial_guess[:, 0]) or
+          not len(set(partial_guess[:, 1])) == len(partial_guess[:, 1])):
+        msg = "`partial_guess` column entries must be unique"
+    if msg is not None:
+        raise ValueError(msg)
+
+    fixed_rows = None
+    if partial_match.size or partial_guess.size:
+        # use partial_match and partial_guess for initial permutation,
+        # but randomly permute the rest.
+        guess_rows = np.zeros(N, dtype=bool)
+        guess_cols = np.zeros(N, dtype=bool)
+        fixed_rows = np.zeros(N, dtype=bool)
+        fixed_cols = np.zeros(N, dtype=bool)
+        perm = np.zeros(N, dtype=int)
+
+        rg, cg = partial_guess.T
+        guess_rows[rg] = True
+        guess_cols[cg] = True
+        perm[guess_rows] = cg
+
+        # match overrides guess
+        rf, cf = partial_match.T
+        fixed_rows[rf] = True
+        fixed_cols[cf] = True
+        perm[fixed_rows] = cf
+
+        random_rows = ~fixed_rows & ~guess_rows
+        random_cols = ~fixed_cols & ~guess_cols
+        perm[random_rows] = rng.permutation(np.arange(N)[random_cols])
+    else:
+        perm = rng.permutation(np.arange(N))
+
+    best_score = _calc_score(A, B, perm)
+
+    i_free = np.arange(N)
+    if fixed_rows is not None:
+        i_free = i_free[~fixed_rows]
+
+    better = operator.gt if maximize else operator.lt
+    n_iter = 0
+    done = False
+    while not done:
+        # equivalent to nested for loops i in range(N), j in range(i, N)
+        for i, j in itertools.combinations_with_replacement(i_free, 2):
+            n_iter += 1
+            perm[i], perm[j] = perm[j], perm[i]
+            score = _calc_score(A, B, perm)
+            if better(score, best_score):
+                best_score = score
+                break
+            # faster to swap back than to create a new list every time
+            perm[i], perm[j] = perm[j], perm[i]
+        else:  # no swaps made
+            done = True
+
+    res = {"col_ind": perm, "fun": best_score, "nit": n_iter}
+    return OptimizeResult(res)