Add files using upload-large-folder tool

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/__init__.py

@@ -0,0 +1,5 @@
+from networkx.algorithms.assortativity.connectivity import *
+from networkx.algorithms.assortativity.correlation import *
+from networkx.algorithms.assortativity.mixing import *
+from networkx.algorithms.assortativity.neighbor_degree import *
+from networkx.algorithms.assortativity.pairs import *

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/connectivity.py

@@ -0,0 +1,122 @@
+from collections import defaultdict
+
+import networkx as nx
+
+__all__ = ["average_degree_connectivity"]
+
+
+@nx._dispatchable(edge_attrs="weight")
+def average_degree_connectivity(
+    G, source="in+out", target="in+out", nodes=None, weight=None
+):
+    r"""Compute the average degree connectivity of graph.
+
+    The average degree connectivity is the average nearest neighbor degree of
+    nodes with degree k. For weighted graphs, an analogous measure can
+    be computed using the weighted average neighbors degree defined in
+    [1]_, for a node `i`, as
+
+    .. math::
+
+        k_{nn,i}^{w} = \frac{1}{s_i} \sum_{j \in N(i)} w_{ij} k_j
+
+    where `s_i` is the weighted degree of node `i`,
+    `w_{ij}` is the weight of the edge that links `i` and `j`,
+    and `N(i)` are the neighbors of node `i`.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source :  "in"|"out"|"in+out" (default:"in+out")
+       Directed graphs only. Use "in"- or "out"-degree for source node.
+
+    target : "in"|"out"|"in+out" (default:"in+out"
+       Directed graphs only. Use "in"- or "out"-degree for target node.
+
+    nodes : list or iterable (optional)
+        Compute neighbor connectivity for these nodes. The default is all
+        nodes.
+
+    weight : string or None, optional (default=None)
+       The edge attribute that holds the numerical value used as a weight.
+       If None, then each edge has weight 1.
+
+    Returns
+    -------
+    d : dict
+       A dictionary keyed by degree k with the value of average connectivity.
+
+    Raises
+    ------
+    NetworkXError
+        If either `source` or `target` are not one of 'in',
+        'out', or 'in+out'.
+        If either `source` or `target` is passed for an undirected graph.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> G.edges[1, 2]["weight"] = 3
+    >>> nx.average_degree_connectivity(G)
+    {1: 2.0, 2: 1.5}
+    >>> nx.average_degree_connectivity(G, weight="weight")
+    {1: 2.0, 2: 1.75}
+
+    See Also
+    --------
+    average_neighbor_degree
+
+    References
+    ----------
+    .. [1] A. Barrat, M. Barthélemy, R. Pastor-Satorras, and A. Vespignani,
+       "The architecture of complex weighted networks".
+       PNAS 101 (11): 3747–3752 (2004).
+    """
+    # First, determine the type of neighbors and the type of degree to use.
+    if G.is_directed():
+        if source not in ("in", "out", "in+out"):
+            raise nx.NetworkXError('source must be one of "in", "out", or "in+out"')
+        if target not in ("in", "out", "in+out"):
+            raise nx.NetworkXError('target must be one of "in", "out", or "in+out"')
+        direction = {"out": G.out_degree, "in": G.in_degree, "in+out": G.degree}
+        neighbor_funcs = {
+            "out": G.successors,
+            "in": G.predecessors,
+            "in+out": G.neighbors,
+        }
+        source_degree = direction[source]
+        target_degree = direction[target]
+        neighbors = neighbor_funcs[source]
+        # `reverse` indicates whether to look at the in-edge when
+        # computing the weight of an edge.
+        reverse = source == "in"
+    else:
+        if source != "in+out" or target != "in+out":
+            raise nx.NetworkXError(
+                f"source and target arguments are only supported for directed graphs"
+            )
+        source_degree = G.degree
+        target_degree = G.degree
+        neighbors = G.neighbors
+        reverse = False
+    dsum = defaultdict(int)
+    dnorm = defaultdict(int)
+    # Check if `source_nodes` is actually a single node in the graph.
+    source_nodes = source_degree(nodes)
+    if nodes in G:
+        source_nodes = [(nodes, source_degree(nodes))]
+    for n, k in source_nodes:
+        nbrdeg = target_degree(neighbors(n))
+        if weight is None:
+            s = sum(d for n, d in nbrdeg)
+        else:  # weight nbr degree by weight of (n,nbr) edge
+            if reverse:
+                s = sum(G[nbr][n].get(weight, 1) * d for nbr, d in nbrdeg)
+            else:
+                s = sum(G[n][nbr].get(weight, 1) * d for nbr, d in nbrdeg)
+        dnorm[k] += source_degree(n, weight=weight)
+        dsum[k] += s
+
+    # normalize
+    return {k: avg if dnorm[k] == 0 else avg / dnorm[k] for k, avg in dsum.items()}

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/correlation.py

@@ -0,0 +1,302 @@
+"""Node assortativity coefficients and correlation measures."""
+
+import networkx as nx
+from networkx.algorithms.assortativity.mixing import (
+    attribute_mixing_matrix,
+    degree_mixing_matrix,
+)
+from networkx.algorithms.assortativity.pairs import node_degree_xy
+
+__all__ = [
+    "degree_pearson_correlation_coefficient",
+    "degree_assortativity_coefficient",
+    "attribute_assortativity_coefficient",
+    "numeric_assortativity_coefficient",
+]
+
+
+@nx._dispatchable(edge_attrs="weight")
+def degree_assortativity_coefficient(G, x="out", y="in", weight=None, nodes=None):
+    """Compute degree assortativity of graph.
+
+    Assortativity measures the similarity of connections
+    in the graph with respect to the node degree.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    x: string ('in','out')
+       The degree type for source node (directed graphs only).
+
+    y: string ('in','out')
+       The degree type for target node (directed graphs only).
+
+    weight: string or None, optional (default=None)
+       The edge attribute that holds the numerical value used
+       as a weight.  If None, then each edge has weight 1.
+       The degree is the sum of the edge weights adjacent to the node.
+
+    nodes: list or iterable (optional)
+        Compute degree assortativity only for nodes in container.
+        The default is all nodes.
+
+    Returns
+    -------
+    r : float
+       Assortativity of graph by degree.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> r = nx.degree_assortativity_coefficient(G)
+    >>> print(f"{r:3.1f}")
+    -0.5
+
+    See Also
+    --------
+    attribute_assortativity_coefficient
+    numeric_assortativity_coefficient
+    degree_mixing_dict
+    degree_mixing_matrix
+
+    Notes
+    -----
+    This computes Eq. (21) in Ref. [1]_ , where e is the joint
+    probability distribution (mixing matrix) of the degrees.  If G is
+    directed than the matrix e is the joint probability of the
+    user-specified degree type for the source and target.
+
+    References
+    ----------
+    .. [1] M. E. J. Newman, Mixing patterns in networks,
+       Physical Review E, 67 026126, 2003
+    .. [2] Foster, J.G., Foster, D.V., Grassberger, P. & Paczuski, M.
+       Edge direction and the structure of networks, PNAS 107, 10815-20 (2010).
+    """
+    if nodes is None:
+        nodes = G.nodes
+
+    degrees = None
+
+    if G.is_directed():
+        indeg = (
+            {d for _, d in G.in_degree(nodes, weight=weight)}
+            if "in" in (x, y)
+            else set()
+        )
+        outdeg = (
+            {d for _, d in G.out_degree(nodes, weight=weight)}
+            if "out" in (x, y)
+            else set()
+        )
+        degrees = set.union(indeg, outdeg)
+    else:
+        degrees = {d for _, d in G.degree(nodes, weight=weight)}
+
+    mapping = {d: i for i, d in enumerate(degrees)}
+    M = degree_mixing_matrix(G, x=x, y=y, nodes=nodes, weight=weight, mapping=mapping)
+
+    return _numeric_ac(M, mapping=mapping)
+
+
+@nx._dispatchable(edge_attrs="weight")
+def degree_pearson_correlation_coefficient(G, x="out", y="in", weight=None, nodes=None):
+    """Compute degree assortativity of graph.
+
+    Assortativity measures the similarity of connections
+    in the graph with respect to the node degree.
+
+    This is the same as degree_assortativity_coefficient but uses the
+    potentially faster scipy.stats.pearsonr function.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    x: string ('in','out')
+       The degree type for source node (directed graphs only).
+
+    y: string ('in','out')
+       The degree type for target node (directed graphs only).
+
+    weight: string or None, optional (default=None)
+       The edge attribute that holds the numerical value used
+       as a weight.  If None, then each edge has weight 1.
+       The degree is the sum of the edge weights adjacent to the node.
+
+    nodes: list or iterable (optional)
+        Compute pearson correlation of degrees only for specified nodes.
+        The default is all nodes.
+
+    Returns
+    -------
+    r : float
+       Assortativity of graph by degree.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> r = nx.degree_pearson_correlation_coefficient(G)
+    >>> print(f"{r:3.1f}")
+    -0.5
+
+    Notes
+    -----
+    This calls scipy.stats.pearsonr.
+
+    References
+    ----------
+    .. [1] M. E. J. Newman, Mixing patterns in networks
+           Physical Review E, 67 026126, 2003
+    .. [2] Foster, J.G., Foster, D.V., Grassberger, P. & Paczuski, M.
+       Edge direction and the structure of networks, PNAS 107, 10815-20 (2010).
+    """
+    import scipy as sp
+
+    xy = node_degree_xy(G, x=x, y=y, nodes=nodes, weight=weight)
+    x, y = zip(*xy)
+    return float(sp.stats.pearsonr(x, y)[0])
+
+
+@nx._dispatchable(node_attrs="attribute")
+def attribute_assortativity_coefficient(G, attribute, nodes=None):
+    """Compute assortativity for node attributes.
+
+    Assortativity measures the similarity of connections
+    in the graph with respect to the given attribute.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    attribute : string
+        Node attribute key
+
+    nodes: list or iterable (optional)
+        Compute attribute assortativity for nodes in container.
+        The default is all nodes.
+
+    Returns
+    -------
+    r: float
+       Assortativity of graph for given attribute
+
+    Examples
+    --------
+    >>> G = nx.Graph()
+    >>> G.add_nodes_from([0, 1], color="red")
+    >>> G.add_nodes_from([2, 3], color="blue")
+    >>> G.add_edges_from([(0, 1), (2, 3)])
+    >>> print(nx.attribute_assortativity_coefficient(G, "color"))
+    1.0
+
+    Notes
+    -----
+    This computes Eq. (2) in Ref. [1]_ , (trace(M)-sum(M^2))/(1-sum(M^2)),
+    where M is the joint probability distribution (mixing matrix)
+    of the specified attribute.
+
+    References
+    ----------
+    .. [1] M. E. J. Newman, Mixing patterns in networks,
+       Physical Review E, 67 026126, 2003
+    """
+    M = attribute_mixing_matrix(G, attribute, nodes)
+    return attribute_ac(M)
+
+
+@nx._dispatchable(node_attrs="attribute")
+def numeric_assortativity_coefficient(G, attribute, nodes=None):
+    """Compute assortativity for numerical node attributes.
+
+    Assortativity measures the similarity of connections
+    in the graph with respect to the given numeric attribute.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    attribute : string
+        Node attribute key.
+
+    nodes: list or iterable (optional)
+        Compute numeric assortativity only for attributes of nodes in
+        container. The default is all nodes.
+
+    Returns
+    -------
+    r: float
+       Assortativity of graph for given attribute
+
+    Examples
+    --------
+    >>> G = nx.Graph()
+    >>> G.add_nodes_from([0, 1], size=2)
+    >>> G.add_nodes_from([2, 3], size=3)
+    >>> G.add_edges_from([(0, 1), (2, 3)])
+    >>> print(nx.numeric_assortativity_coefficient(G, "size"))
+    1.0
+
+    Notes
+    -----
+    This computes Eq. (21) in Ref. [1]_ , which is the Pearson correlation
+    coefficient of the specified (scalar valued) attribute across edges.
+
+    References
+    ----------
+    .. [1] M. E. J. Newman, Mixing patterns in networks
+           Physical Review E, 67 026126, 2003
+    """
+    if nodes is None:
+        nodes = G.nodes
+    vals = {G.nodes[n][attribute] for n in nodes}
+    mapping = {d: i for i, d in enumerate(vals)}
+    M = attribute_mixing_matrix(G, attribute, nodes, mapping)
+    return _numeric_ac(M, mapping)
+
+
+def attribute_ac(M):
+    """Compute assortativity for attribute matrix M.
+
+    Parameters
+    ----------
+    M : numpy.ndarray
+        2D ndarray representing the attribute mixing matrix.
+
+    Notes
+    -----
+    This computes Eq. (2) in Ref. [1]_ , (trace(e)-sum(e^2))/(1-sum(e^2)),
+    where e is the joint probability distribution (mixing matrix)
+    of the specified attribute.
+
+    References
+    ----------
+    .. [1] M. E. J. Newman, Mixing patterns in networks,
+       Physical Review E, 67 026126, 2003
+    """
+    if M.sum() != 1.0:
+        M = M / M.sum()
+    s = (M @ M).sum()
+    t = M.trace()
+    r = (t - s) / (1 - s)
+    return float(r)
+
+
+def _numeric_ac(M, mapping):
+    # M is a 2D numpy array
+    # numeric assortativity coefficient, pearsonr
+    import numpy as np
+
+    if M.sum() != 1.0:
+        M = M / M.sum()
+    x = np.array(list(mapping.keys()))
+    y = x  # x and y have the same support
+    idx = list(mapping.values())
+    a = M.sum(axis=0)
+    b = M.sum(axis=1)
+    vara = (a[idx] * x**2).sum() - ((a[idx] * x).sum()) ** 2
+    varb = (b[idx] * y**2).sum() - ((b[idx] * y).sum()) ** 2
+    xy = np.outer(x, y)
+    ab = np.outer(a[idx], b[idx])
+    return float((xy * (M - ab)).sum() / np.sqrt(vara * varb))

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/mixing.py

@@ -0,0 +1,255 @@
+"""
+Mixing matrices for node attributes and degree.
+"""
+
+import networkx as nx
+from networkx.algorithms.assortativity.pairs import node_attribute_xy, node_degree_xy
+from networkx.utils import dict_to_numpy_array
+
+__all__ = [
+    "attribute_mixing_matrix",
+    "attribute_mixing_dict",
+    "degree_mixing_matrix",
+    "degree_mixing_dict",
+    "mixing_dict",
+]
+
+
+@nx._dispatchable(node_attrs="attribute")
+def attribute_mixing_dict(G, attribute, nodes=None, normalized=False):
+    """Returns dictionary representation of mixing matrix for attribute.
+
+    Parameters
+    ----------
+    G : graph
+       NetworkX graph object.
+
+    attribute : string
+       Node attribute key.
+
+    nodes: list or iterable (optional)
+        Unse nodes in container to build the dict. The default is all nodes.
+
+    normalized : bool (default=False)
+       Return counts if False or probabilities if True.
+
+    Examples
+    --------
+    >>> G = nx.Graph()
+    >>> G.add_nodes_from([0, 1], color="red")
+    >>> G.add_nodes_from([2, 3], color="blue")
+    >>> G.add_edge(1, 3)
+    >>> d = nx.attribute_mixing_dict(G, "color")
+    >>> print(d["red"]["blue"])
+    1
+    >>> print(d["blue"]["red"])  # d symmetric for undirected graphs
+    1
+
+    Returns
+    -------
+    d : dictionary
+       Counts or joint probability of occurrence of attribute pairs.
+    """
+    xy_iter = node_attribute_xy(G, attribute, nodes)
+    return mixing_dict(xy_iter, normalized=normalized)
+
+
+@nx._dispatchable(node_attrs="attribute")
+def attribute_mixing_matrix(G, attribute, nodes=None, mapping=None, normalized=True):
+    """Returns mixing matrix for attribute.
+
+    Parameters
+    ----------
+    G : graph
+       NetworkX graph object.
+
+    attribute : string
+       Node attribute key.
+
+    nodes: list or iterable (optional)
+        Use only nodes in container to build the matrix. The default is
+        all nodes.
+
+    mapping : dictionary, optional
+       Mapping from node attribute to integer index in matrix.
+       If not specified, an arbitrary ordering will be used.
+
+    normalized : bool (default=True)
+       Return counts if False or probabilities if True.
+
+    Returns
+    -------
+    m: numpy array
+       Counts or joint probability of occurrence of attribute pairs.
+
+    Notes
+    -----
+    If each node has a unique attribute value, the unnormalized mixing matrix
+    will be equal to the adjacency matrix. To get a denser mixing matrix,
+    the rounding can be performed to form groups of nodes with equal values.
+    For example, the exact height of persons in cm (180.79155222, 163.9080892,
+    163.30095355, 167.99016217, 168.21590163, ...) can be rounded to (180, 163,
+    163, 168, 168, ...).
+
+    Definitions of attribute mixing matrix vary on whether the matrix
+    should include rows for attribute values that don't arise. Here we
+    do not include such empty-rows. But you can force them to appear
+    by inputting a `mapping` that includes those values.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(3)
+    >>> gender = {0: "male", 1: "female", 2: "female"}
+    >>> nx.set_node_attributes(G, gender, "gender")
+    >>> mapping = {"male": 0, "female": 1}
+    >>> mix_mat = nx.attribute_mixing_matrix(G, "gender", mapping=mapping)
+    >>> mix_mat
+    array([[0.  , 0.25],
+           [0.25, 0.5 ]])
+    """
+    d = attribute_mixing_dict(G, attribute, nodes)
+    a = dict_to_numpy_array(d, mapping=mapping)
+    if normalized:
+        a = a / a.sum()
+    return a
+
+
+@nx._dispatchable(edge_attrs="weight")
+def degree_mixing_dict(G, x="out", y="in", weight=None, nodes=None, normalized=False):
+    """Returns dictionary representation of mixing matrix for degree.
+
+    Parameters
+    ----------
+    G : graph
+        NetworkX graph object.
+
+    x: string ('in','out')
+       The degree type for source node (directed graphs only).
+
+    y: string ('in','out')
+       The degree type for target node (directed graphs only).
+
+    weight: string or None, optional (default=None)
+       The edge attribute that holds the numerical value used
+       as a weight.  If None, then each edge has weight 1.
+       The degree is the sum of the edge weights adjacent to the node.
+
+    normalized : bool (default=False)
+        Return counts if False or probabilities if True.
+
+    Returns
+    -------
+    d: dictionary
+       Counts or joint probability of occurrence of degree pairs.
+    """
+    xy_iter = node_degree_xy(G, x=x, y=y, nodes=nodes, weight=weight)
+    return mixing_dict(xy_iter, normalized=normalized)
+
+
+@nx._dispatchable(edge_attrs="weight")
+def degree_mixing_matrix(
+    G, x="out", y="in", weight=None, nodes=None, normalized=True, mapping=None
+):
+    """Returns mixing matrix for attribute.
+
+    Parameters
+    ----------
+    G : graph
+       NetworkX graph object.
+
+    x: string ('in','out')
+       The degree type for source node (directed graphs only).
+
+    y: string ('in','out')
+       The degree type for target node (directed graphs only).
+
+    nodes: list or iterable (optional)
+        Build the matrix using only nodes in container.
+        The default is all nodes.
+
+    weight: string or None, optional (default=None)
+       The edge attribute that holds the numerical value used
+       as a weight.  If None, then each edge has weight 1.
+       The degree is the sum of the edge weights adjacent to the node.
+
+    normalized : bool (default=True)
+       Return counts if False or probabilities if True.
+
+    mapping : dictionary, optional
+       Mapping from node degree to integer index in matrix.
+       If not specified, an arbitrary ordering will be used.
+
+    Returns
+    -------
+    m: numpy array
+       Counts, or joint probability, of occurrence of node degree.
+
+    Notes
+    -----
+    Definitions of degree mixing matrix vary on whether the matrix
+    should include rows for degree values that don't arise. Here we
+    do not include such empty-rows. But you can force them to appear
+    by inputting a `mapping` that includes those values. See examples.
+
+    Examples
+    --------
+    >>> G = nx.star_graph(3)
+    >>> mix_mat = nx.degree_mixing_matrix(G)
+    >>> mix_mat
+    array([[0. , 0.5],
+           [0.5, 0. ]])
+
+    If you want every possible degree to appear as a row, even if no nodes
+    have that degree, use `mapping` as follows,
+
+    >>> max_degree = max(deg for n, deg in G.degree)
+    >>> mapping = {x: x for x in range(max_degree + 1)}  # identity mapping
+    >>> mix_mat = nx.degree_mixing_matrix(G, mapping=mapping)
+    >>> mix_mat
+    array([[0. , 0. , 0. , 0. ],
+           [0. , 0. , 0. , 0.5],
+           [0. , 0. , 0. , 0. ],
+           [0. , 0.5, 0. , 0. ]])
+    """
+    d = degree_mixing_dict(G, x=x, y=y, nodes=nodes, weight=weight)
+    a = dict_to_numpy_array(d, mapping=mapping)
+    if normalized:
+        a = a / a.sum()
+    return a
+
+
+def mixing_dict(xy, normalized=False):
+    """Returns a dictionary representation of mixing matrix.
+
+    Parameters
+    ----------
+    xy : list or container of two-tuples
+       Pairs of (x,y) items.
+
+    attribute : string
+       Node attribute key
+
+    normalized : bool (default=False)
+       Return counts if False or probabilities if True.
+
+    Returns
+    -------
+    d: dictionary
+       Counts or Joint probability of occurrence of values in xy.
+    """
+    d = {}
+    psum = 0.0
+    for x, y in xy:
+        if x not in d:
+            d[x] = {}
+        if y not in d:
+            d[y] = {}
+        v = d[x].get(y, 0)
+        d[x][y] = v + 1
+        psum += 1
+
+    if normalized:
+        for _, jdict in d.items():
+            for j in jdict:
+                jdict[j] /= psum
+    return d

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/neighbor_degree.py

@@ -0,0 +1,160 @@
+import networkx as nx
+
+__all__ = ["average_neighbor_degree"]
+
+
+@nx._dispatchable(edge_attrs="weight")
+def average_neighbor_degree(G, source="out", target="out", nodes=None, weight=None):
+    r"""Returns the average degree of the neighborhood of each node.
+
+    In an undirected graph, the neighborhood `N(i)` of node `i` contains the
+    nodes that are connected to `i` by an edge.
+
+    For directed graphs, `N(i)` is defined according to the parameter `source`:
+
+        - if source is 'in', then `N(i)` consists of predecessors of node `i`.
+        - if source is 'out', then `N(i)` consists of successors of node `i`.
+        - if source is 'in+out', then `N(i)` is both predecessors and successors.
+
+    The average neighborhood degree of a node `i` is
+
+    .. math::
+
+        k_{nn,i} = \frac{1}{|N(i)|} \sum_{j \in N(i)} k_j
+
+    where `N(i)` are the neighbors of node `i` and `k_j` is
+    the degree of node `j` which belongs to `N(i)`. For weighted
+    graphs, an analogous measure can be defined [1]_,
+
+    .. math::
+
+        k_{nn,i}^{w} = \frac{1}{s_i} \sum_{j \in N(i)} w_{ij} k_j
+
+    where `s_i` is the weighted degree of node `i`, `w_{ij}`
+    is the weight of the edge that links `i` and `j` and
+    `N(i)` are the neighbors of node `i`.
+
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : string ("in"|"out"|"in+out"), optional (default="out")
+       Directed graphs only.
+       Use "in"- or "out"-neighbors of source node.
+
+    target : string ("in"|"out"|"in+out"), optional (default="out")
+       Directed graphs only.
+       Use "in"- or "out"-degree for target node.
+
+    nodes : list or iterable, optional (default=G.nodes)
+        Compute neighbor degree only for specified nodes.
+
+    weight : string or None, optional (default=None)
+       The edge attribute that holds the numerical value used as a weight.
+       If None, then each edge has weight 1.
+
+    Returns
+    -------
+    d: dict
+       A dictionary keyed by node to the average degree of its neighbors.
+
+    Raises
+    ------
+    NetworkXError
+        If either `source` or `target` are not one of 'in', 'out', or 'in+out'.
+        If either `source` or `target` is passed for an undirected graph.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> G.edges[0, 1]["weight"] = 5
+    >>> G.edges[2, 3]["weight"] = 3
+
+    >>> nx.average_neighbor_degree(G)
+    {0: 2.0, 1: 1.5, 2: 1.5, 3: 2.0}
+    >>> nx.average_neighbor_degree(G, weight="weight")
+    {0: 2.0, 1: 1.1666666666666667, 2: 1.25, 3: 2.0}
+
+    >>> G = nx.DiGraph()
+    >>> nx.add_path(G, [0, 1, 2, 3])
+    >>> nx.average_neighbor_degree(G, source="in", target="in")
+    {0: 0.0, 1: 0.0, 2: 1.0, 3: 1.0}
+
+    >>> nx.average_neighbor_degree(G, source="out", target="out")
+    {0: 1.0, 1: 1.0, 2: 0.0, 3: 0.0}
+
+    See Also
+    --------
+    average_degree_connectivity
+
+    References
+    ----------
+    .. [1] A. Barrat, M. Barthélemy, R. Pastor-Satorras, and A. Vespignani,
+       "The architecture of complex weighted networks".
+       PNAS 101 (11): 3747–3752 (2004).
+    """
+    if G.is_directed():
+        if source == "in":
+            source_degree = G.in_degree
+        elif source == "out":
+            source_degree = G.out_degree
+        elif source == "in+out":
+            source_degree = G.degree
+        else:
+            raise nx.NetworkXError(
+                f"source argument {source} must be 'in', 'out' or 'in+out'"
+            )
+
+        if target == "in":
+            target_degree = G.in_degree
+        elif target == "out":
+            target_degree = G.out_degree
+        elif target == "in+out":
+            target_degree = G.degree
+        else:
+            raise nx.NetworkXError(
+                f"target argument {target} must be 'in', 'out' or 'in+out'"
+            )
+    else:
+        if source != "out" or target != "out":
+            raise nx.NetworkXError(
+                f"source and target arguments are only supported for directed graphs"
+            )
+        source_degree = target_degree = G.degree
+
+    # precompute target degrees -- should *not* be weighted degree
+    t_deg = dict(target_degree())
+
+    # Set up both predecessor and successor neighbor dicts leaving empty if not needed
+    G_P = G_S = {n: {} for n in G}
+    if G.is_directed():
+        # "in" or "in+out" cases: G_P contains predecessors
+        if "in" in source:
+            G_P = G.pred
+        # "out" or "in+out" cases: G_S contains successors
+        if "out" in source:
+            G_S = G.succ
+    else:
+        # undirected leave G_P empty but G_S is the adjacency
+        G_S = G.adj
+
+    # Main loop: Compute average degree of neighbors
+    avg = {}
+    for n, deg in source_degree(nodes, weight=weight):
+        # handle degree zero average
+        if deg == 0:
+            avg[n] = 0.0
+            continue
+
+        # we sum over both G_P and G_S, but one of the two is usually empty.
+        if weight is None:
+            avg[n] = (
+                sum(t_deg[nbr] for nbr in G_S[n]) + sum(t_deg[nbr] for nbr in G_P[n])
+            ) / deg
+        else:
+            avg[n] = (
+                sum(dd.get(weight, 1) * t_deg[nbr] for nbr, dd in G_S[n].items())
+                + sum(dd.get(weight, 1) * t_deg[nbr] for nbr, dd in G_P[n].items())
+            ) / deg
+    return avg

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/pairs.py

@@ -0,0 +1,127 @@
+"""Generators of x-y pairs of node data."""
+
+import networkx as nx
+
+__all__ = ["node_attribute_xy", "node_degree_xy"]
+
+
+@nx._dispatchable(node_attrs="attribute")
+def node_attribute_xy(G, attribute, nodes=None):
+    """Yields 2-tuples of node attribute values for all edges in `G`.
+
+    This generator yields, for each edge in `G` incident to a node in `nodes`,
+    a 2-tuple of form ``(attribute value,  attribute value)`` for the parameter
+    specified node-attribute.
+
+    Parameters
+    ----------
+    G: NetworkX graph
+
+    attribute: key
+        The node attribute key.
+
+    nodes: list or iterable (optional)
+        Use only edges that are incident to specified nodes.
+        The default is all nodes.
+
+    Yields
+    ------
+    (x, y): 2-tuple
+        Generates 2-tuple of (attribute, attribute) values.
+
+    Examples
+    --------
+    >>> G = nx.DiGraph()
+    >>> G.add_node(1, color="red")
+    >>> G.add_node(2, color="blue")
+    >>> G.add_node(3, color="green")
+    >>> G.add_edge(1, 2)
+    >>> list(nx.node_attribute_xy(G, "color"))
+    [('red', 'blue')]
+
+    Notes
+    -----
+    For undirected graphs, each edge is produced twice, once for each edge
+    representation (u, v) and (v, u), with the exception of self-loop edges
+    which only appear once.
+    """
+    if nodes is None:
+        nodes = set(G)
+    else:
+        nodes = set(nodes)
+    Gnodes = G.nodes
+    for u, nbrsdict in G.adjacency():
+        if u not in nodes:
+            continue
+        uattr = Gnodes[u].get(attribute, None)
+        if G.is_multigraph():
+            for v, keys in nbrsdict.items():
+                vattr = Gnodes[v].get(attribute, None)
+                for _ in keys:
+                    yield (uattr, vattr)
+        else:
+            for v in nbrsdict:
+                vattr = Gnodes[v].get(attribute, None)
+                yield (uattr, vattr)
+
+
+@nx._dispatchable(edge_attrs="weight")
+def node_degree_xy(G, x="out", y="in", weight=None, nodes=None):
+    """Yields 2-tuples of ``(degree, degree)`` values for edges in `G`.
+
+    This generator yields, for each edge in `G` incident to a node in `nodes`,
+    a 2-tuple of form ``(degree, degree)``. The node degrees are weighted
+    when a `weight` attribute is specified.
+
+    Parameters
+    ----------
+    G: NetworkX graph
+
+    x: string ('in','out')
+       The degree type for source node (directed graphs only).
+
+    y: string ('in','out')
+       The degree type for target node (directed graphs only).
+
+    weight: string or None, optional (default=None)
+       The edge attribute that holds the numerical value used
+       as a weight.  If None, then each edge has weight 1.
+       The degree is the sum of the edge weights adjacent to the node.
+
+    nodes: list or iterable (optional)
+        Use only edges that are adjacency to specified nodes.
+        The default is all nodes.
+
+    Yields
+    ------
+    (x, y): 2-tuple
+        Generates 2-tuple of (degree, degree) values.
+
+    Examples
+    --------
+    >>> G = nx.DiGraph()
+    >>> G.add_edge(1, 2)
+    >>> list(nx.node_degree_xy(G, x="out", y="in"))
+    [(1, 1)]
+    >>> list(nx.node_degree_xy(G, x="in", y="out"))
+    [(0, 0)]
+
+    Notes
+    -----
+    For undirected graphs, each edge is produced twice, once for each edge
+    representation (u, v) and (v, u), with the exception of self-loop edges
+    which only appear once.
+    """
+    nodes = set(G) if nodes is None else set(nodes)
+    if G.is_directed():
+        direction = {"out": G.out_degree, "in": G.in_degree}
+        xdeg = direction[x]
+        ydeg = direction[y]
+    else:
+        xdeg = ydeg = G.degree
+
+    for u, degu in xdeg(nodes, weight=weight):
+        # use G.edges to treat multigraphs correctly
+        neighbors = (nbr for _, nbr in G.edges(u) if nbr in nodes)
+        for _, degv in ydeg(neighbors, weight=weight):
+            yield degu, degv

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/base_test.py

@@ -0,0 +1,81 @@
+import networkx as nx
+
+
+class BaseTestAttributeMixing:
+    @classmethod
+    def setup_class(cls):
+        G = nx.Graph()
+        G.add_nodes_from([0, 1], fish="one")
+        G.add_nodes_from([2, 3], fish="two")
+        G.add_nodes_from([4], fish="red")
+        G.add_nodes_from([5], fish="blue")
+        G.add_edges_from([(0, 1), (2, 3), (0, 4), (2, 5)])
+        cls.G = G
+
+        D = nx.DiGraph()
+        D.add_nodes_from([0, 1], fish="one")
+        D.add_nodes_from([2, 3], fish="two")
+        D.add_nodes_from([4], fish="red")
+        D.add_nodes_from([5], fish="blue")
+        D.add_edges_from([(0, 1), (2, 3), (0, 4), (2, 5)])
+        cls.D = D
+
+        M = nx.MultiGraph()
+        M.add_nodes_from([0, 1], fish="one")
+        M.add_nodes_from([2, 3], fish="two")
+        M.add_nodes_from([4], fish="red")
+        M.add_nodes_from([5], fish="blue")
+        M.add_edges_from([(0, 1), (0, 1), (2, 3)])
+        cls.M = M
+
+        S = nx.Graph()
+        S.add_nodes_from([0, 1], fish="one")
+        S.add_nodes_from([2, 3], fish="two")
+        S.add_nodes_from([4], fish="red")
+        S.add_nodes_from([5], fish="blue")
+        S.add_edge(0, 0)
+        S.add_edge(2, 2)
+        cls.S = S
+
+        N = nx.Graph()
+        N.add_nodes_from([0, 1], margin=-2)
+        N.add_nodes_from([2, 3], margin=-2)
+        N.add_nodes_from([4], margin=-3)
+        N.add_nodes_from([5], margin=-4)
+        N.add_edges_from([(0, 1), (2, 3), (0, 4), (2, 5)])
+        cls.N = N
+
+        F = nx.Graph()
+        F.add_edges_from([(0, 3), (1, 3), (2, 3)], weight=0.5)
+        F.add_edge(0, 2, weight=1)
+        nx.set_node_attributes(F, dict(F.degree(weight="weight")), "margin")
+        cls.F = F
+
+        K = nx.Graph()
+        K.add_nodes_from([1, 2], margin=-1)
+        K.add_nodes_from([3], margin=1)
+        K.add_nodes_from([4], margin=2)
+        K.add_edges_from([(3, 4), (1, 2), (1, 3)])
+        cls.K = K
+
+
+class BaseTestDegreeMixing:
+    @classmethod
+    def setup_class(cls):
+        cls.P4 = nx.path_graph(4)
+        cls.D = nx.DiGraph()
+        cls.D.add_edges_from([(0, 2), (0, 3), (1, 3), (2, 3)])
+        cls.D2 = nx.DiGraph()
+        cls.D2.add_edges_from([(0, 3), (1, 0), (1, 2), (2, 4), (4, 1), (4, 3), (4, 2)])
+        cls.M = nx.MultiGraph()
+        nx.add_path(cls.M, range(4))
+        cls.M.add_edge(0, 1)
+        cls.S = nx.Graph()
+        cls.S.add_edges_from([(0, 0), (1, 1)])
+        cls.W = nx.Graph()
+        cls.W.add_edges_from([(0, 3), (1, 3), (2, 3)], weight=0.5)
+        cls.W.add_edge(0, 2, weight=1)
+        S1 = nx.star_graph(4)
+        S2 = nx.star_graph(4)
+        cls.DS = nx.disjoint_union(S1, S2)
+        cls.DS.add_edge(4, 5)

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/test_connectivity.py

@@ -0,0 +1,143 @@
+from itertools import permutations
+
+import pytest
+
+import networkx as nx
+
+
+class TestNeighborConnectivity:
+    def test_degree_p4(self):
+        G = nx.path_graph(4)
+        answer = {1: 2.0, 2: 1.5}
+        nd = nx.average_degree_connectivity(G)
+        assert nd == answer
+
+        D = G.to_directed()
+        answer = {2: 2.0, 4: 1.5}
+        nd = nx.average_degree_connectivity(D)
+        assert nd == answer
+
+        answer = {1: 2.0, 2: 1.5}
+        D = G.to_directed()
+        nd = nx.average_degree_connectivity(D, source="in", target="in")
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_degree_connectivity(D, source="in", target="in")
+        assert nd == answer
+
+    def test_degree_p4_weighted(self):
+        G = nx.path_graph(4)
+        G[1][2]["weight"] = 4
+        answer = {1: 2.0, 2: 1.8}
+        nd = nx.average_degree_connectivity(G, weight="weight")
+        assert nd == answer
+        answer = {1: 2.0, 2: 1.5}
+        nd = nx.average_degree_connectivity(G)
+        assert nd == answer
+
+        D = G.to_directed()
+        answer = {2: 2.0, 4: 1.8}
+        nd = nx.average_degree_connectivity(D, weight="weight")
+        assert nd == answer
+
+        answer = {1: 2.0, 2: 1.8}
+        D = G.to_directed()
+        nd = nx.average_degree_connectivity(
+            D, weight="weight", source="in", target="in"
+        )
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_degree_connectivity(
+            D, source="in", target="out", weight="weight"
+        )
+        assert nd == answer
+
+    def test_weight_keyword(self):
+        G = nx.path_graph(4)
+        G[1][2]["other"] = 4
+        answer = {1: 2.0, 2: 1.8}
+        nd = nx.average_degree_connectivity(G, weight="other")
+        assert nd == answer
+        answer = {1: 2.0, 2: 1.5}
+        nd = nx.average_degree_connectivity(G, weight=None)
+        assert nd == answer
+
+        D = G.to_directed()
+        answer = {2: 2.0, 4: 1.8}
+        nd = nx.average_degree_connectivity(D, weight="other")
+        assert nd == answer
+
+        answer = {1: 2.0, 2: 1.8}
+        D = G.to_directed()
+        nd = nx.average_degree_connectivity(D, weight="other", source="in", target="in")
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_degree_connectivity(D, weight="other", source="in", target="in")
+        assert nd == answer
+
+    def test_degree_barrat(self):
+        G = nx.star_graph(5)
+        G.add_edges_from([(5, 6), (5, 7), (5, 8), (5, 9)])
+        G[0][5]["weight"] = 5
+        nd = nx.average_degree_connectivity(G)[5]
+        assert nd == 1.8
+        nd = nx.average_degree_connectivity(G, weight="weight")[5]
+        assert nd == pytest.approx(3.222222, abs=1e-5)
+
+    def test_zero_deg(self):
+        G = nx.DiGraph()
+        G.add_edge(1, 2)
+        G.add_edge(1, 3)
+        G.add_edge(1, 4)
+        c = nx.average_degree_connectivity(G)
+        assert c == {1: 0, 3: 1}
+        c = nx.average_degree_connectivity(G, source="in", target="in")
+        assert c == {0: 0, 1: 0}
+        c = nx.average_degree_connectivity(G, source="in", target="out")
+        assert c == {0: 0, 1: 3}
+        c = nx.average_degree_connectivity(G, source="in", target="in+out")
+        assert c == {0: 0, 1: 3}
+        c = nx.average_degree_connectivity(G, source="out", target="out")
+        assert c == {0: 0, 3: 0}
+        c = nx.average_degree_connectivity(G, source="out", target="in")
+        assert c == {0: 0, 3: 1}
+        c = nx.average_degree_connectivity(G, source="out", target="in+out")
+        assert c == {0: 0, 3: 1}
+
+    def test_in_out_weight(self):
+        G = nx.DiGraph()
+        G.add_edge(1, 2, weight=1)
+        G.add_edge(1, 3, weight=1)
+        G.add_edge(3, 1, weight=1)
+        for s, t in permutations(["in", "out", "in+out"], 2):
+            c = nx.average_degree_connectivity(G, source=s, target=t)
+            cw = nx.average_degree_connectivity(G, source=s, target=t, weight="weight")
+            assert c == cw
+
+    def test_invalid_source(self):
+        with pytest.raises(nx.NetworkXError):
+            G = nx.DiGraph()
+            nx.average_degree_connectivity(G, source="bogus")
+
+    def test_invalid_target(self):
+        with pytest.raises(nx.NetworkXError):
+            G = nx.DiGraph()
+            nx.average_degree_connectivity(G, target="bogus")
+
+    def test_invalid_undirected_graph(self):
+        G = nx.Graph()
+        with pytest.raises(nx.NetworkXError):
+            nx.average_degree_connectivity(G, target="bogus")
+        with pytest.raises(nx.NetworkXError):
+            nx.average_degree_connectivity(G, source="bogus")
+
+    def test_single_node(self):
+        # TODO Is this really the intended behavior for providing a
+        # single node as the argument `nodes`? Shouldn't the function
+        # just return the connectivity value itself?
+        G = nx.trivial_graph()
+        conn = nx.average_degree_connectivity(G, nodes=0)
+        assert conn == {0: 0}

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/test_correlation.py

@@ -0,0 +1,123 @@
+import pytest
+
+np = pytest.importorskip("numpy")
+pytest.importorskip("scipy")
+
+
+import networkx as nx
+from networkx.algorithms.assortativity.correlation import attribute_ac
+
+from .base_test import BaseTestAttributeMixing, BaseTestDegreeMixing
+
+
+class TestDegreeMixingCorrelation(BaseTestDegreeMixing):
+    def test_degree_assortativity_undirected(self):
+        r = nx.degree_assortativity_coefficient(self.P4)
+        np.testing.assert_almost_equal(r, -1.0 / 2, decimal=4)
+
+    def test_degree_assortativity_node_kwargs(self):
+        G = nx.Graph()
+        edges = [(0, 1), (0, 3), (1, 2), (1, 3), (1, 4), (5, 9), (9, 0)]
+        G.add_edges_from(edges)
+        r = nx.degree_assortativity_coefficient(G, nodes=[1, 2, 4])
+        np.testing.assert_almost_equal(r, -1.0, decimal=4)
+
+    def test_degree_assortativity_directed(self):
+        r = nx.degree_assortativity_coefficient(self.D)
+        np.testing.assert_almost_equal(r, -0.57735, decimal=4)
+
+    def test_degree_assortativity_directed2(self):
+        """Test degree assortativity for a directed graph where the set of
+        in/out degree does not equal the total degree."""
+        r = nx.degree_assortativity_coefficient(self.D2)
+        np.testing.assert_almost_equal(r, 0.14852, decimal=4)
+
+    def test_degree_assortativity_multigraph(self):
+        r = nx.degree_assortativity_coefficient(self.M)
+        np.testing.assert_almost_equal(r, -1.0 / 7.0, decimal=4)
+
+    def test_degree_pearson_assortativity_undirected(self):
+        r = nx.degree_pearson_correlation_coefficient(self.P4)
+        np.testing.assert_almost_equal(r, -1.0 / 2, decimal=4)
+
+    def test_degree_pearson_assortativity_directed(self):
+        r = nx.degree_pearson_correlation_coefficient(self.D)
+        np.testing.assert_almost_equal(r, -0.57735, decimal=4)
+
+    def test_degree_pearson_assortativity_directed2(self):
+        """Test degree assortativity with Pearson for a directed graph where
+        the set of in/out degree does not equal the total degree."""
+        r = nx.degree_pearson_correlation_coefficient(self.D2)
+        np.testing.assert_almost_equal(r, 0.14852, decimal=4)
+
+    def test_degree_pearson_assortativity_multigraph(self):
+        r = nx.degree_pearson_correlation_coefficient(self.M)
+        np.testing.assert_almost_equal(r, -1.0 / 7.0, decimal=4)
+
+    def test_degree_assortativity_weighted(self):
+        r = nx.degree_assortativity_coefficient(self.W, weight="weight")
+        np.testing.assert_almost_equal(r, -0.1429, decimal=4)
+
+    def test_degree_assortativity_double_star(self):
+        r = nx.degree_assortativity_coefficient(self.DS)
+        np.testing.assert_almost_equal(r, -0.9339, decimal=4)
+
+
+class TestAttributeMixingCorrelation(BaseTestAttributeMixing):
+    def test_attribute_assortativity_undirected(self):
+        r = nx.attribute_assortativity_coefficient(self.G, "fish")
+        assert r == 6.0 / 22.0
+
+    def test_attribute_assortativity_directed(self):
+        r = nx.attribute_assortativity_coefficient(self.D, "fish")
+        assert r == 1.0 / 3.0
+
+    def test_attribute_assortativity_multigraph(self):
+        r = nx.attribute_assortativity_coefficient(self.M, "fish")
+        assert r == 1.0
+
+    def test_attribute_assortativity_coefficient(self):
+        # from "Mixing patterns in networks"
+        # fmt: off
+        a = np.array([[0.258, 0.016, 0.035, 0.013],
+                      [0.012, 0.157, 0.058, 0.019],
+                      [0.013, 0.023, 0.306, 0.035],
+                      [0.005, 0.007, 0.024, 0.016]])
+        # fmt: on
+        r = attribute_ac(a)
+        np.testing.assert_almost_equal(r, 0.623, decimal=3)
+
+    def test_attribute_assortativity_coefficient2(self):
+        # fmt: off
+        a = np.array([[0.18, 0.02, 0.01, 0.03],
+                      [0.02, 0.20, 0.03, 0.02],
+                      [0.01, 0.03, 0.16, 0.01],
+                      [0.03, 0.02, 0.01, 0.22]])
+        # fmt: on
+        r = attribute_ac(a)
+        np.testing.assert_almost_equal(r, 0.68, decimal=2)
+
+    def test_attribute_assortativity(self):
+        a = np.array([[50, 50, 0], [50, 50, 0], [0, 0, 2]])
+        r = attribute_ac(a)
+        np.testing.assert_almost_equal(r, 0.029, decimal=3)
+
+    def test_attribute_assortativity_negative(self):
+        r = nx.numeric_assortativity_coefficient(self.N, "margin")
+        np.testing.assert_almost_equal(r, -0.2903, decimal=4)
+
+    def test_assortativity_node_kwargs(self):
+        G = nx.Graph()
+        G.add_nodes_from([0, 1], size=2)
+        G.add_nodes_from([2, 3], size=3)
+        G.add_edges_from([(0, 1), (2, 3)])
+        r = nx.numeric_assortativity_coefficient(G, "size", nodes=[0, 3])
+        np.testing.assert_almost_equal(r, 1.0, decimal=4)
+
+    def test_attribute_assortativity_float(self):
+        r = nx.numeric_assortativity_coefficient(self.F, "margin")
+        np.testing.assert_almost_equal(r, -0.1429, decimal=4)
+
+    def test_attribute_assortativity_mixed(self):
+        r = nx.numeric_assortativity_coefficient(self.K, "margin")
+        np.testing.assert_almost_equal(r, 0.4340, decimal=4)

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/test_mixing.py

@@ -0,0 +1,176 @@
+import pytest
+
+np = pytest.importorskip("numpy")
+
+
+import networkx as nx
+
+from .base_test import BaseTestAttributeMixing, BaseTestDegreeMixing
+
+
+class TestDegreeMixingDict(BaseTestDegreeMixing):
+    def test_degree_mixing_dict_undirected(self):
+        d = nx.degree_mixing_dict(self.P4)
+        d_result = {1: {2: 2}, 2: {1: 2, 2: 2}}
+        assert d == d_result
+
+    def test_degree_mixing_dict_undirected_normalized(self):
+        d = nx.degree_mixing_dict(self.P4, normalized=True)
+        d_result = {1: {2: 1.0 / 3}, 2: {1: 1.0 / 3, 2: 1.0 / 3}}
+        assert d == d_result
+
+    def test_degree_mixing_dict_directed(self):
+        d = nx.degree_mixing_dict(self.D)
+        print(d)
+        d_result = {1: {3: 2}, 2: {1: 1, 3: 1}, 3: {}}
+        assert d == d_result
+
+    def test_degree_mixing_dict_multigraph(self):
+        d = nx.degree_mixing_dict(self.M)
+        d_result = {1: {2: 1}, 2: {1: 1, 3: 3}, 3: {2: 3}}
+        assert d == d_result
+
+    def test_degree_mixing_dict_weighted(self):
+        d = nx.degree_mixing_dict(self.W, weight="weight")
+        d_result = {0.5: {1.5: 1}, 1.5: {1.5: 6, 0.5: 1}}
+        assert d == d_result
+
+
+class TestDegreeMixingMatrix(BaseTestDegreeMixing):
+    def test_degree_mixing_matrix_undirected(self):
+        # fmt: off
+        a_result = np.array([[0, 2],
+                             [2, 2]]
+                            )
+        # fmt: on
+        a = nx.degree_mixing_matrix(self.P4, normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.P4)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_degree_mixing_matrix_directed(self):
+        # fmt: off
+        a_result = np.array([[0, 0, 2],
+                             [1, 0, 1],
+                             [0, 0, 0]]
+                            )
+        # fmt: on
+        a = nx.degree_mixing_matrix(self.D, normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.D)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_degree_mixing_matrix_multigraph(self):
+        # fmt: off
+        a_result = np.array([[0, 1, 0],
+                             [1, 0, 3],
+                             [0, 3, 0]]
+                            )
+        # fmt: on
+        a = nx.degree_mixing_matrix(self.M, normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.M)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_degree_mixing_matrix_selfloop(self):
+        # fmt: off
+        a_result = np.array([[2]])
+        # fmt: on
+        a = nx.degree_mixing_matrix(self.S, normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.S)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_degree_mixing_matrix_weighted(self):
+        a_result = np.array([[0.0, 1.0], [1.0, 6.0]])
+        a = nx.degree_mixing_matrix(self.W, weight="weight", normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.W, weight="weight")
+        np.testing.assert_equal(a, a_result / float(a_result.sum()))
+
+    def test_degree_mixing_matrix_mapping(self):
+        a_result = np.array([[6.0, 1.0], [1.0, 0.0]])
+        mapping = {0.5: 1, 1.5: 0}
+        a = nx.degree_mixing_matrix(
+            self.W, weight="weight", normalized=False, mapping=mapping
+        )
+        np.testing.assert_equal(a, a_result)
+
+
+class TestAttributeMixingDict(BaseTestAttributeMixing):
+    def test_attribute_mixing_dict_undirected(self):
+        d = nx.attribute_mixing_dict(self.G, "fish")
+        d_result = {
+            "one": {"one": 2, "red": 1},
+            "two": {"two": 2, "blue": 1},
+            "red": {"one": 1},
+            "blue": {"two": 1},
+        }
+        assert d == d_result
+
+    def test_attribute_mixing_dict_directed(self):
+        d = nx.attribute_mixing_dict(self.D, "fish")
+        d_result = {
+            "one": {"one": 1, "red": 1},
+            "two": {"two": 1, "blue": 1},
+            "red": {},
+            "blue": {},
+        }
+        assert d == d_result
+
+    def test_attribute_mixing_dict_multigraph(self):
+        d = nx.attribute_mixing_dict(self.M, "fish")
+        d_result = {"one": {"one": 4}, "two": {"two": 2}}
+        assert d == d_result
+
+
+class TestAttributeMixingMatrix(BaseTestAttributeMixing):
+    def test_attribute_mixing_matrix_undirected(self):
+        mapping = {"one": 0, "two": 1, "red": 2, "blue": 3}
+        a_result = np.array([[2, 0, 1, 0], [0, 2, 0, 1], [1, 0, 0, 0], [0, 1, 0, 0]])
+        a = nx.attribute_mixing_matrix(
+            self.G, "fish", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.G, "fish", mapping=mapping)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_attribute_mixing_matrix_directed(self):
+        mapping = {"one": 0, "two": 1, "red": 2, "blue": 3}
+        a_result = np.array([[1, 0, 1, 0], [0, 1, 0, 1], [0, 0, 0, 0], [0, 0, 0, 0]])
+        a = nx.attribute_mixing_matrix(
+            self.D, "fish", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.D, "fish", mapping=mapping)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_attribute_mixing_matrix_multigraph(self):
+        mapping = {"one": 0, "two": 1, "red": 2, "blue": 3}
+        a_result = np.array([[4, 0, 0, 0], [0, 2, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]])
+        a = nx.attribute_mixing_matrix(
+            self.M, "fish", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.M, "fish", mapping=mapping)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_attribute_mixing_matrix_negative(self):
+        mapping = {-2: 0, -3: 1, -4: 2}
+        a_result = np.array([[4.0, 1.0, 1.0], [1.0, 0.0, 0.0], [1.0, 0.0, 0.0]])
+        a = nx.attribute_mixing_matrix(
+            self.N, "margin", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.N, "margin", mapping=mapping)
+        np.testing.assert_equal(a, a_result / float(a_result.sum()))
+
+    def test_attribute_mixing_matrix_float(self):
+        mapping = {0.5: 1, 1.5: 0}
+        a_result = np.array([[6.0, 1.0], [1.0, 0.0]])
+        a = nx.attribute_mixing_matrix(
+            self.F, "margin", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.F, "margin", mapping=mapping)
+        np.testing.assert_equal(a, a_result / a_result.sum())

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/test_neighbor_degree.py

@@ -0,0 +1,108 @@
+import pytest
+
+import networkx as nx
+
+
+class TestAverageNeighbor:
+    def test_degree_p4(self):
+        G = nx.path_graph(4)
+        answer = {0: 2, 1: 1.5, 2: 1.5, 3: 2}
+        nd = nx.average_neighbor_degree(G)
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D)
+        assert nd == answer
+
+        D = nx.DiGraph(G.edges(data=True))
+        nd = nx.average_neighbor_degree(D)
+        assert nd == {0: 1, 1: 1, 2: 0, 3: 0}
+        nd = nx.average_neighbor_degree(D, "in", "out")
+        assert nd == {0: 0, 1: 1, 2: 1, 3: 1}
+        nd = nx.average_neighbor_degree(D, "out", "in")
+        assert nd == {0: 1, 1: 1, 2: 1, 3: 0}
+        nd = nx.average_neighbor_degree(D, "in", "in")
+        assert nd == {0: 0, 1: 0, 2: 1, 3: 1}
+
+    def test_degree_p4_weighted(self):
+        G = nx.path_graph(4)
+        G[1][2]["weight"] = 4
+        answer = {0: 2, 1: 1.8, 2: 1.8, 3: 2}
+        nd = nx.average_neighbor_degree(G, weight="weight")
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D, weight="weight")
+        assert nd == answer
+
+        D = nx.DiGraph(G.edges(data=True))
+        print(D.edges(data=True))
+        nd = nx.average_neighbor_degree(D, weight="weight")
+        assert nd == {0: 1, 1: 1, 2: 0, 3: 0}
+        nd = nx.average_neighbor_degree(D, "out", "out", weight="weight")
+        assert nd == {0: 1, 1: 1, 2: 0, 3: 0}
+        nd = nx.average_neighbor_degree(D, "in", "in", weight="weight")
+        assert nd == {0: 0, 1: 0, 2: 1, 3: 1}
+        nd = nx.average_neighbor_degree(D, "in", "out", weight="weight")
+        assert nd == {0: 0, 1: 1, 2: 1, 3: 1}
+        nd = nx.average_neighbor_degree(D, "out", "in", weight="weight")
+        assert nd == {0: 1, 1: 1, 2: 1, 3: 0}
+        nd = nx.average_neighbor_degree(D, source="in+out", weight="weight")
+        assert nd == {0: 1.0, 1: 1.0, 2: 0.8, 3: 1.0}
+        nd = nx.average_neighbor_degree(D, target="in+out", weight="weight")
+        assert nd == {0: 2.0, 1: 2.0, 2: 1.0, 3: 0.0}
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D, weight="weight")
+        assert nd == answer
+        nd = nx.average_neighbor_degree(D, source="out", target="out", weight="weight")
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D, source="in", target="in", weight="weight")
+        assert nd == answer
+
+    def test_degree_k4(self):
+        G = nx.complete_graph(4)
+        answer = {0: 3, 1: 3, 2: 3, 3: 3}
+        nd = nx.average_neighbor_degree(G)
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D)
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D)
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D, source="in", target="in")
+        assert nd == answer
+
+    def test_degree_k4_nodes(self):
+        G = nx.complete_graph(4)
+        answer = {1: 3.0, 2: 3.0}
+        nd = nx.average_neighbor_degree(G, nodes=[1, 2])
+        assert nd == answer
+
+    def test_degree_barrat(self):
+        G = nx.star_graph(5)
+        G.add_edges_from([(5, 6), (5, 7), (5, 8), (5, 9)])
+        G[0][5]["weight"] = 5
+        nd = nx.average_neighbor_degree(G)[5]
+        assert nd == 1.8
+        nd = nx.average_neighbor_degree(G, weight="weight")[5]
+        assert nd == pytest.approx(3.222222, abs=1e-5)
+
+    def test_error_invalid_source_target(self):
+        G = nx.path_graph(4)
+        with pytest.raises(nx.NetworkXError):
+            nx.average_neighbor_degree(G, "error")
+        with pytest.raises(nx.NetworkXError):
+            nx.average_neighbor_degree(G, "in", "error")
+        G = G.to_directed()
+        with pytest.raises(nx.NetworkXError):
+            nx.average_neighbor_degree(G, "error")
+        with pytest.raises(nx.NetworkXError):
+            nx.average_neighbor_degree(G, "in", "error")

.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/test_pairs.py

@@ -0,0 +1,87 @@
+import networkx as nx
+
+from .base_test import BaseTestAttributeMixing, BaseTestDegreeMixing
+
+
+class TestAttributeMixingXY(BaseTestAttributeMixing):
+    def test_node_attribute_xy_undirected(self):
+        attrxy = sorted(nx.node_attribute_xy(self.G, "fish"))
+        attrxy_result = sorted(
+            [
+                ("one", "one"),
+                ("one", "one"),
+                ("two", "two"),
+                ("two", "two"),
+                ("one", "red"),
+                ("red", "one"),
+                ("blue", "two"),
+                ("two", "blue"),
+            ]
+        )
+        assert attrxy == attrxy_result
+
+    def test_node_attribute_xy_undirected_nodes(self):
+        attrxy = sorted(nx.node_attribute_xy(self.G, "fish", nodes=["one", "yellow"]))
+        attrxy_result = sorted([])
+        assert attrxy == attrxy_result
+
+    def test_node_attribute_xy_directed(self):
+        attrxy = sorted(nx.node_attribute_xy(self.D, "fish"))
+        attrxy_result = sorted(
+            [("one", "one"), ("two", "two"), ("one", "red"), ("two", "blue")]
+        )
+        assert attrxy == attrxy_result
+
+    def test_node_attribute_xy_multigraph(self):
+        attrxy = sorted(nx.node_attribute_xy(self.M, "fish"))
+        attrxy_result = [
+            ("one", "one"),
+            ("one", "one"),
+            ("one", "one"),
+            ("one", "one"),
+            ("two", "two"),
+            ("two", "two"),
+        ]
+        assert attrxy == attrxy_result
+
+    def test_node_attribute_xy_selfloop(self):
+        attrxy = sorted(nx.node_attribute_xy(self.S, "fish"))
+        attrxy_result = [("one", "one"), ("two", "two")]
+        assert attrxy == attrxy_result
+
+
+class TestDegreeMixingXY(BaseTestDegreeMixing):
+    def test_node_degree_xy_undirected(self):
+        xy = sorted(nx.node_degree_xy(self.P4))
+        xy_result = sorted([(1, 2), (2, 1), (2, 2), (2, 2), (1, 2), (2, 1)])
+        assert xy == xy_result
+
+    def test_node_degree_xy_undirected_nodes(self):
+        xy = sorted(nx.node_degree_xy(self.P4, nodes=[0, 1, -1]))
+        xy_result = sorted([(1, 2), (2, 1)])
+        assert xy == xy_result
+
+    def test_node_degree_xy_directed(self):
+        xy = sorted(nx.node_degree_xy(self.D))
+        xy_result = sorted([(2, 1), (2, 3), (1, 3), (1, 3)])
+        assert xy == xy_result
+
+    def test_node_degree_xy_multigraph(self):
+        xy = sorted(nx.node_degree_xy(self.M))
+        xy_result = sorted(
+            [(2, 3), (2, 3), (3, 2), (3, 2), (2, 3), (3, 2), (1, 2), (2, 1)]
+        )
+        assert xy == xy_result
+
+    def test_node_degree_xy_selfloop(self):
+        xy = sorted(nx.node_degree_xy(self.S))
+        xy_result = sorted([(2, 2), (2, 2)])
+        assert xy == xy_result
+
+    def test_node_degree_xy_weighted(self):
+        G = nx.Graph()
+        G.add_edge(1, 2, weight=7)
+        G.add_edge(2, 3, weight=10)
+        xy = sorted(nx.node_degree_xy(G, weight="weight"))
+        xy_result = sorted([(7, 17), (17, 10), (17, 7), (10, 17)])
+        assert xy == xy_result

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/betweenness.py

@@ -0,0 +1,436 @@
+"""Betweenness centrality measures."""
+
+from collections import deque
+from heapq import heappop, heappush
+from itertools import count
+
+import networkx as nx
+from networkx.algorithms.shortest_paths.weighted import _weight_function
+from networkx.utils import py_random_state
+from networkx.utils.decorators import not_implemented_for
+
+__all__ = ["betweenness_centrality", "edge_betweenness_centrality"]
+
+
+@py_random_state(5)
+@nx._dispatchable(edge_attrs="weight")
+def betweenness_centrality(
+    G, k=None, normalized=True, weight=None, endpoints=False, seed=None
+):
+    r"""Compute the shortest-path betweenness centrality for nodes.
+
+    Betweenness centrality of a node $v$ is the sum of the
+    fraction of all-pairs shortest paths that pass through $v$
+
+    .. math::
+
+       c_B(v) =\sum_{s,t \in V} \frac{\sigma(s, t|v)}{\sigma(s, t)}
+
+    where $V$ is the set of nodes, $\sigma(s, t)$ is the number of
+    shortest $(s, t)$-paths,  and $\sigma(s, t|v)$ is the number of
+    those paths  passing through some  node $v$ other than $s, t$.
+    If $s = t$, $\sigma(s, t) = 1$, and if $v \in {s, t}$,
+    $\sigma(s, t|v) = 0$ [2]_.
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph.
+
+    k : int, optional (default=None)
+      If k is not None use k node samples to estimate betweenness.
+      The value of k <= n where n is the number of nodes in the graph.
+      Higher values give better approximation.
+
+    normalized : bool, optional
+      If True the betweenness values are normalized by `2/((n-1)(n-2))`
+      for graphs, and `1/((n-1)(n-2))` for directed graphs where `n`
+      is the number of nodes in G.
+
+    weight : None or string, optional (default=None)
+      If None, all edge weights are considered equal.
+      Otherwise holds the name of the edge attribute used as weight.
+      Weights are used to calculate weighted shortest paths, so they are
+      interpreted as distances.
+
+    endpoints : bool, optional
+      If True include the endpoints in the shortest path counts.
+
+    seed : integer, random_state, or None (default)
+        Indicator of random number generation state.
+        See :ref:`Randomness<randomness>`.
+        Note that this is only used if k is not None.
+
+    Returns
+    -------
+    nodes : dictionary
+       Dictionary of nodes with betweenness centrality as the value.
+
+    See Also
+    --------
+    edge_betweenness_centrality
+    load_centrality
+
+    Notes
+    -----
+    The algorithm is from Ulrik Brandes [1]_.
+    See [4]_ for the original first published version and [2]_ for details on
+    algorithms for variations and related metrics.
+
+    For approximate betweenness calculations set k=#samples to use
+    k nodes ("pivots") to estimate the betweenness values. For an estimate
+    of the number of pivots needed see [3]_.
+
+    For weighted graphs the edge weights must be greater than zero.
+    Zero edge weights can produce an infinite number of equal length
+    paths between pairs of nodes.
+
+    The total number of paths between source and target is counted
+    differently for directed and undirected graphs. Directed paths
+    are easy to count. Undirected paths are tricky: should a path
+    from "u" to "v" count as 1 undirected path or as 2 directed paths?
+
+    For betweenness_centrality we report the number of undirected
+    paths when G is undirected.
+
+    For betweenness_centrality_subset the reporting is different.
+    If the source and target subsets are the same, then we want
+    to count undirected paths. But if the source and target subsets
+    differ -- for example, if sources is {0} and targets is {1},
+    then we are only counting the paths in one direction. They are
+    undirected paths but we are counting them in a directed way.
+    To count them as undirected paths, each should count as half a path.
+
+    This algorithm is not guaranteed to be correct if edge weights
+    are floating point numbers. As a workaround you can use integer
+    numbers by multiplying the relevant edge attributes by a convenient
+    constant factor (eg 100) and converting to integers.
+
+    References
+    ----------
+    .. [1] Ulrik Brandes:
+       A Faster Algorithm for Betweenness Centrality.
+       Journal of Mathematical Sociology 25(2):163-177, 2001.
+       https://doi.org/10.1080/0022250X.2001.9990249
+    .. [2] Ulrik Brandes:
+       On Variants of Shortest-Path Betweenness
+       Centrality and their Generic Computation.
+       Social Networks 30(2):136-145, 2008.
+       https://doi.org/10.1016/j.socnet.2007.11.001
+    .. [3] Ulrik Brandes and Christian Pich:
+       Centrality Estimation in Large Networks.
+       International Journal of Bifurcation and Chaos 17(7):2303-2318, 2007.
+       https://dx.doi.org/10.1142/S0218127407018403
+    .. [4] Linton C. Freeman:
+       A set of measures of centrality based on betweenness.
+       Sociometry 40: 35–41, 1977
+       https://doi.org/10.2307/3033543
+    """
+    betweenness = dict.fromkeys(G, 0.0)  # b[v]=0 for v in G
+    if k is None:
+        nodes = G
+    else:
+        nodes = seed.sample(list(G.nodes()), k)
+    for s in nodes:
+        # single source shortest paths
+        if weight is None:  # use BFS
+            S, P, sigma, _ = _single_source_shortest_path_basic(G, s)
+        else:  # use Dijkstra's algorithm
+            S, P, sigma, _ = _single_source_dijkstra_path_basic(G, s, weight)
+        # accumulation
+        if endpoints:
+            betweenness, _ = _accumulate_endpoints(betweenness, S, P, sigma, s)
+        else:
+            betweenness, _ = _accumulate_basic(betweenness, S, P, sigma, s)
+    # rescaling
+    betweenness = _rescale(
+        betweenness,
+        len(G),
+        normalized=normalized,
+        directed=G.is_directed(),
+        k=k,
+        endpoints=endpoints,
+    )
+    return betweenness
+
+
+@py_random_state(4)
+@nx._dispatchable(edge_attrs="weight")
+def edge_betweenness_centrality(G, k=None, normalized=True, weight=None, seed=None):
+    r"""Compute betweenness centrality for edges.
+
+    Betweenness centrality of an edge $e$ is the sum of the
+    fraction of all-pairs shortest paths that pass through $e$
+
+    .. math::
+
+       c_B(e) =\sum_{s,t \in V} \frac{\sigma(s, t|e)}{\sigma(s, t)}
+
+    where $V$ is the set of nodes, $\sigma(s, t)$ is the number of
+    shortest $(s, t)$-paths, and $\sigma(s, t|e)$ is the number of
+    those paths passing through edge $e$ [2]_.
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph.
+
+    k : int, optional (default=None)
+      If k is not None use k node samples to estimate betweenness.
+      The value of k <= n where n is the number of nodes in the graph.
+      Higher values give better approximation.
+
+    normalized : bool, optional
+      If True the betweenness values are normalized by $2/(n(n-1))$
+      for graphs, and $1/(n(n-1))$ for directed graphs where $n$
+      is the number of nodes in G.
+
+    weight : None or string, optional (default=None)
+      If None, all edge weights are considered equal.
+      Otherwise holds the name of the edge attribute used as weight.
+      Weights are used to calculate weighted shortest paths, so they are
+      interpreted as distances.
+
+    seed : integer, random_state, or None (default)
+        Indicator of random number generation state.
+        See :ref:`Randomness<randomness>`.
+        Note that this is only used if k is not None.
+
+    Returns
+    -------
+    edges : dictionary
+       Dictionary of edges with betweenness centrality as the value.
+
+    See Also
+    --------
+    betweenness_centrality
+    edge_load
+
+    Notes
+    -----
+    The algorithm is from Ulrik Brandes [1]_.
+
+    For weighted graphs the edge weights must be greater than zero.
+    Zero edge weights can produce an infinite number of equal length
+    paths between pairs of nodes.
+
+    References
+    ----------
+    .. [1]  A Faster Algorithm for Betweenness Centrality. Ulrik Brandes,
+       Journal of Mathematical Sociology 25(2):163-177, 2001.
+       https://doi.org/10.1080/0022250X.2001.9990249
+    .. [2] Ulrik Brandes: On Variants of Shortest-Path Betweenness
+       Centrality and their Generic Computation.
+       Social Networks 30(2):136-145, 2008.
+       https://doi.org/10.1016/j.socnet.2007.11.001
+    """
+    betweenness = dict.fromkeys(G, 0.0)  # b[v]=0 for v in G
+    # b[e]=0 for e in G.edges()
+    betweenness.update(dict.fromkeys(G.edges(), 0.0))
+    if k is None:
+        nodes = G
+    else:
+        nodes = seed.sample(list(G.nodes()), k)
+    for s in nodes:
+        # single source shortest paths
+        if weight is None:  # use BFS
+            S, P, sigma, _ = _single_source_shortest_path_basic(G, s)
+        else:  # use Dijkstra's algorithm
+            S, P, sigma, _ = _single_source_dijkstra_path_basic(G, s, weight)
+        # accumulation
+        betweenness = _accumulate_edges(betweenness, S, P, sigma, s)
+    # rescaling
+    for n in G:  # remove nodes to only return edges
+        del betweenness[n]
+    betweenness = _rescale_e(
+        betweenness, len(G), normalized=normalized, directed=G.is_directed()
+    )
+    if G.is_multigraph():
+        betweenness = _add_edge_keys(G, betweenness, weight=weight)
+    return betweenness
+
+
+# helpers for betweenness centrality
+
+
+def _single_source_shortest_path_basic(G, s):
+    S = []
+    P = {}
+    for v in G:
+        P[v] = []
+    sigma = dict.fromkeys(G, 0.0)  # sigma[v]=0 for v in G
+    D = {}
+    sigma[s] = 1.0
+    D[s] = 0
+    Q = deque([s])
+    while Q:  # use BFS to find shortest paths
+        v = Q.popleft()
+        S.append(v)
+        Dv = D[v]
+        sigmav = sigma[v]
+        for w in G[v]:
+            if w not in D:
+                Q.append(w)
+                D[w] = Dv + 1
+            if D[w] == Dv + 1:  # this is a shortest path, count paths
+                sigma[w] += sigmav
+                P[w].append(v)  # predecessors
+    return S, P, sigma, D
+
+
+def _single_source_dijkstra_path_basic(G, s, weight):
+    weight = _weight_function(G, weight)
+    # modified from Eppstein
+    S = []
+    P = {}
+    for v in G:
+        P[v] = []
+    sigma = dict.fromkeys(G, 0.0)  # sigma[v]=0 for v in G
+    D = {}
+    sigma[s] = 1.0
+    push = heappush
+    pop = heappop
+    seen = {s: 0}
+    c = count()
+    Q = []  # use Q as heap with (distance,node id) tuples
+    push(Q, (0, next(c), s, s))
+    while Q:
+        (dist, _, pred, v) = pop(Q)
+        if v in D:
+            continue  # already searched this node.
+        sigma[v] += sigma[pred]  # count paths
+        S.append(v)
+        D[v] = dist
+        for w, edgedata in G[v].items():
+            vw_dist = dist + weight(v, w, edgedata)
+            if w not in D and (w not in seen or vw_dist < seen[w]):
+                seen[w] = vw_dist
+                push(Q, (vw_dist, next(c), v, w))
+                sigma[w] = 0.0
+                P[w] = [v]
+            elif vw_dist == seen[w]:  # handle equal paths
+                sigma[w] += sigma[v]
+                P[w].append(v)
+    return S, P, sigma, D
+
+
+def _accumulate_basic(betweenness, S, P, sigma, s):
+    delta = dict.fromkeys(S, 0)
+    while S:
+        w = S.pop()
+        coeff = (1 + delta[w]) / sigma[w]
+        for v in P[w]:
+            delta[v] += sigma[v] * coeff
+        if w != s:
+            betweenness[w] += delta[w]
+    return betweenness, delta
+
+
+def _accumulate_endpoints(betweenness, S, P, sigma, s):
+    betweenness[s] += len(S) - 1
+    delta = dict.fromkeys(S, 0)
+    while S:
+        w = S.pop()
+        coeff = (1 + delta[w]) / sigma[w]
+        for v in P[w]:
+            delta[v] += sigma[v] * coeff
+        if w != s:
+            betweenness[w] += delta[w] + 1
+    return betweenness, delta
+
+
+def _accumulate_edges(betweenness, S, P, sigma, s):
+    delta = dict.fromkeys(S, 0)
+    while S:
+        w = S.pop()
+        coeff = (1 + delta[w]) / sigma[w]
+        for v in P[w]:
+            c = sigma[v] * coeff
+            if (v, w) not in betweenness:
+                betweenness[(w, v)] += c
+            else:
+                betweenness[(v, w)] += c
+            delta[v] += c
+        if w != s:
+            betweenness[w] += delta[w]
+    return betweenness
+
+
+def _rescale(betweenness, n, normalized, directed=False, k=None, endpoints=False):
+    if normalized:
+        if endpoints:
+            if n < 2:
+                scale = None  # no normalization
+            else:
+                # Scale factor should include endpoint nodes
+                scale = 1 / (n * (n - 1))
+        elif n <= 2:
+            scale = None  # no normalization b=0 for all nodes
+        else:
+            scale = 1 / ((n - 1) * (n - 2))
+    else:  # rescale by 2 for undirected graphs
+        if not directed:
+            scale = 0.5
+        else:
+            scale = None
+    if scale is not None:
+        if k is not None:
+            scale = scale * n / k
+        for v in betweenness:
+            betweenness[v] *= scale
+    return betweenness
+
+
+def _rescale_e(betweenness, n, normalized, directed=False, k=None):
+    if normalized:
+        if n <= 1:
+            scale = None  # no normalization b=0 for all nodes
+        else:
+            scale = 1 / (n * (n - 1))
+    else:  # rescale by 2 for undirected graphs
+        if not directed:
+            scale = 0.5
+        else:
+            scale = None
+    if scale is not None:
+        if k is not None:
+            scale = scale * n / k
+        for v in betweenness:
+            betweenness[v] *= scale
+    return betweenness
+
+
+@not_implemented_for("graph")
+def _add_edge_keys(G, betweenness, weight=None):
+    r"""Adds the corrected betweenness centrality (BC) values for multigraphs.
+
+    Parameters
+    ----------
+    G : NetworkX graph.
+
+    betweenness : dictionary
+        Dictionary mapping adjacent node tuples to betweenness centrality values.
+
+    weight : string or function
+        See `_weight_function` for details. Defaults to `None`.
+
+    Returns
+    -------
+    edges : dictionary
+        The parameter `betweenness` including edges with keys and their
+        betweenness centrality values.
+
+    The BC value is divided among edges of equal weight.
+    """
+    _weight = _weight_function(G, weight)
+
+    edge_bc = dict.fromkeys(G.edges, 0.0)
+    for u, v in betweenness:
+        d = G[u][v]
+        wt = _weight(u, v, d)
+        keys = [k for k in d if _weight(u, v, {k: d[k]}) == wt]
+        bc = betweenness[(u, v)] / len(keys)
+        for k in keys:
+            edge_bc[(u, v, k)] = bc
+
+    return edge_bc

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/closeness.py

@@ -0,0 +1,282 @@
+"""
+Closeness centrality measures.
+"""
+
+import functools
+
+import networkx as nx
+from networkx.exception import NetworkXError
+from networkx.utils.decorators import not_implemented_for
+
+__all__ = ["closeness_centrality", "incremental_closeness_centrality"]
+
+
+@nx._dispatchable(edge_attrs="distance")
+def closeness_centrality(G, u=None, distance=None, wf_improved=True):
+    r"""Compute closeness centrality for nodes.
+
+    Closeness centrality [1]_ of a node `u` is the reciprocal of the
+    average shortest path distance to `u` over all `n-1` reachable nodes.
+
+    .. math::
+
+        C(u) = \frac{n - 1}{\sum_{v=1}^{n-1} d(v, u)},
+
+    where `d(v, u)` is the shortest-path distance between `v` and `u`,
+    and `n-1` is the number of nodes reachable from `u`. Notice that the
+    closeness distance function computes the incoming distance to `u`
+    for directed graphs. To use outward distance, act on `G.reverse()`.
+
+    Notice that higher values of closeness indicate higher centrality.
+
+    Wasserman and Faust propose an improved formula for graphs with
+    more than one connected component. The result is "a ratio of the
+    fraction of actors in the group who are reachable, to the average
+    distance" from the reachable actors [2]_. You might think this
+    scale factor is inverted but it is not. As is, nodes from small
+    components receive a smaller closeness value. Letting `N` denote
+    the number of nodes in the graph,
+
+    .. math::
+
+        C_{WF}(u) = \frac{n-1}{N-1} \frac{n - 1}{\sum_{v=1}^{n-1} d(v, u)},
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph
+
+    u : node, optional
+      Return only the value for node u
+
+    distance : edge attribute key, optional (default=None)
+      Use the specified edge attribute as the edge distance in shortest
+      path calculations.  If `None` (the default) all edges have a distance of 1.
+      Absent edge attributes are assigned a distance of 1. Note that no check
+      is performed to ensure that edges have the provided attribute.
+
+    wf_improved : bool, optional (default=True)
+      If True, scale by the fraction of nodes reachable. This gives the
+      Wasserman and Faust improved formula. For single component graphs
+      it is the same as the original formula.
+
+    Returns
+    -------
+    nodes : dictionary
+      Dictionary of nodes with closeness centrality as the value.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2), (0, 3), (1, 2), (1, 3)])
+    >>> nx.closeness_centrality(G)
+    {0: 1.0, 1: 1.0, 2: 0.75, 3: 0.75}
+
+    See Also
+    --------
+    betweenness_centrality, load_centrality, eigenvector_centrality,
+    degree_centrality, incremental_closeness_centrality
+
+    Notes
+    -----
+    The closeness centrality is normalized to `(n-1)/(|G|-1)` where
+    `n` is the number of nodes in the connected part of graph
+    containing the node.  If the graph is not completely connected,
+    this algorithm computes the closeness centrality for each
+    connected part separately scaled by that parts size.
+
+    If the 'distance' keyword is set to an edge attribute key then the
+    shortest-path length will be computed using Dijkstra's algorithm with
+    that edge attribute as the edge weight.
+
+    The closeness centrality uses *inward* distance to a node, not outward.
+    If you want to use outword distances apply the function to `G.reverse()`
+
+    In NetworkX 2.2 and earlier a bug caused Dijkstra's algorithm to use the
+    outward distance rather than the inward distance. If you use a 'distance'
+    keyword and a DiGraph, your results will change between v2.2 and v2.3.
+
+    References
+    ----------
+    .. [1] Linton C. Freeman: Centrality in networks: I.
+       Conceptual clarification. Social Networks 1:215-239, 1979.
+       https://doi.org/10.1016/0378-8733(78)90021-7
+    .. [2] pg. 201 of Wasserman, S. and Faust, K.,
+       Social Network Analysis: Methods and Applications, 1994,
+       Cambridge University Press.
+    """
+    if G.is_directed():
+        G = G.reverse()  # create a reversed graph view
+
+    if distance is not None:
+        # use Dijkstra's algorithm with specified attribute as edge weight
+        path_length = functools.partial(
+            nx.single_source_dijkstra_path_length, weight=distance
+        )
+    else:
+        path_length = nx.single_source_shortest_path_length
+
+    if u is None:
+        nodes = G.nodes
+    else:
+        nodes = [u]
+    closeness_dict = {}
+    for n in nodes:
+        sp = path_length(G, n)
+        totsp = sum(sp.values())
+        len_G = len(G)
+        _closeness_centrality = 0.0
+        if totsp > 0.0 and len_G > 1:
+            _closeness_centrality = (len(sp) - 1.0) / totsp
+            # normalize to number of nodes-1 in connected part
+            if wf_improved:
+                s = (len(sp) - 1.0) / (len_G - 1)
+                _closeness_centrality *= s
+        closeness_dict[n] = _closeness_centrality
+    if u is not None:
+        return closeness_dict[u]
+    return closeness_dict
+
+
+@not_implemented_for("directed")
+@nx._dispatchable(mutates_input=True)
+def incremental_closeness_centrality(
+    G, edge, prev_cc=None, insertion=True, wf_improved=True
+):
+    r"""Incremental closeness centrality for nodes.
+
+    Compute closeness centrality for nodes using level-based work filtering
+    as described in Incremental Algorithms for Closeness Centrality by Sariyuce et al.
+
+    Level-based work filtering detects unnecessary updates to the closeness
+    centrality and filters them out.
+
+    ---
+    From "Incremental Algorithms for Closeness Centrality":
+
+    Theorem 1: Let :math:`G = (V, E)` be a graph and u and v be two vertices in V
+    such that there is no edge (u, v) in E. Let :math:`G' = (V, E \cup uv)`
+    Then :math:`cc[s] = cc'[s]` if and only if :math:`\left|dG(s, u) - dG(s, v)\right| \leq 1`.
+
+    Where :math:`dG(u, v)` denotes the length of the shortest path between
+    two vertices u, v in a graph G, cc[s] is the closeness centrality for a
+    vertex s in V, and cc'[s] is the closeness centrality for a
+    vertex s in V, with the (u, v) edge added.
+    ---
+
+    We use Theorem 1 to filter out updates when adding or removing an edge.
+    When adding an edge (u, v), we compute the shortest path lengths from all
+    other nodes to u and to v before the node is added. When removing an edge,
+    we compute the shortest path lengths after the edge is removed. Then we
+    apply Theorem 1 to use previously computed closeness centrality for nodes
+    where :math:`\left|dG(s, u) - dG(s, v)\right| \leq 1`. This works only for
+    undirected, unweighted graphs; the distance argument is not supported.
+
+    Closeness centrality [1]_ of a node `u` is the reciprocal of the
+    sum of the shortest path distances from `u` to all `n-1` other nodes.
+    Since the sum of distances depends on the number of nodes in the
+    graph, closeness is normalized by the sum of minimum possible
+    distances `n-1`.
+
+    .. math::
+
+        C(u) = \frac{n - 1}{\sum_{v=1}^{n-1} d(v, u)},
+
+    where `d(v, u)` is the shortest-path distance between `v` and `u`,
+    and `n` is the number of nodes in the graph.
+
+    Notice that higher values of closeness indicate higher centrality.
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph
+
+    edge : tuple
+      The modified edge (u, v) in the graph.
+
+    prev_cc : dictionary
+      The previous closeness centrality for all nodes in the graph.
+
+    insertion : bool, optional
+      If True (default) the edge was inserted, otherwise it was deleted from the graph.
+
+    wf_improved : bool, optional (default=True)
+      If True, scale by the fraction of nodes reachable. This gives the
+      Wasserman and Faust improved formula. For single component graphs
+      it is the same as the original formula.
+
+    Returns
+    -------
+    nodes : dictionary
+      Dictionary of nodes with closeness centrality as the value.
+
+    See Also
+    --------
+    betweenness_centrality, load_centrality, eigenvector_centrality,
+    degree_centrality, closeness_centrality
+
+    Notes
+    -----
+    The closeness centrality is normalized to `(n-1)/(|G|-1)` where
+    `n` is the number of nodes in the connected part of graph
+    containing the node.  If the graph is not completely connected,
+    this algorithm computes the closeness centrality for each
+    connected part separately.
+
+    References
+    ----------
+    .. [1] Freeman, L.C., 1979. Centrality in networks: I.
+       Conceptual clarification.  Social Networks 1, 215--239.
+       https://doi.org/10.1016/0378-8733(78)90021-7
+    .. [2] Sariyuce, A.E. ; Kaya, K. ; Saule, E. ; Catalyiirek, U.V. Incremental
+       Algorithms for Closeness Centrality. 2013 IEEE International Conference on Big Data
+       http://sariyuce.com/papers/bigdata13.pdf
+    """
+    if prev_cc is not None and set(prev_cc.keys()) != set(G.nodes()):
+        raise NetworkXError("prev_cc and G do not have the same nodes")
+
+    # Unpack edge
+    (u, v) = edge
+    path_length = nx.single_source_shortest_path_length
+
+    if insertion:
+        # For edge insertion, we want shortest paths before the edge is inserted
+        du = path_length(G, u)
+        dv = path_length(G, v)
+
+        G.add_edge(u, v)
+    else:
+        G.remove_edge(u, v)
+
+        # For edge removal, we want shortest paths after the edge is removed
+        du = path_length(G, u)
+        dv = path_length(G, v)
+
+    if prev_cc is None:
+        return nx.closeness_centrality(G)
+
+    nodes = G.nodes()
+    closeness_dict = {}
+    for n in nodes:
+        if n in du and n in dv and abs(du[n] - dv[n]) <= 1:
+            closeness_dict[n] = prev_cc[n]
+        else:
+            sp = path_length(G, n)
+            totsp = sum(sp.values())
+            len_G = len(G)
+            _closeness_centrality = 0.0
+            if totsp > 0.0 and len_G > 1:
+                _closeness_centrality = (len(sp) - 1.0) / totsp
+                # normalize to number of nodes-1 in connected part
+                if wf_improved:
+                    s = (len(sp) - 1.0) / (len_G - 1)
+                    _closeness_centrality *= s
+            closeness_dict[n] = _closeness_centrality
+
+    # Leave the graph as we found it
+    if insertion:
+        G.remove_edge(u, v)
+    else:
+        G.add_edge(u, v)
+
+    return closeness_dict

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/current_flow_betweenness_subset.py

@@ -0,0 +1,227 @@
+"""Current-flow betweenness centrality measures for subsets of nodes."""
+
+import networkx as nx
+from networkx.algorithms.centrality.flow_matrix import flow_matrix_row
+from networkx.utils import not_implemented_for, reverse_cuthill_mckee_ordering
+
+__all__ = [
+    "current_flow_betweenness_centrality_subset",
+    "edge_current_flow_betweenness_centrality_subset",
+]
+
+
+@not_implemented_for("directed")
+@nx._dispatchable(edge_attrs="weight")
+def current_flow_betweenness_centrality_subset(
+    G, sources, targets, normalized=True, weight=None, dtype=float, solver="lu"
+):
+    r"""Compute current-flow betweenness centrality for subsets of nodes.
+
+    Current-flow betweenness centrality uses an electrical current
+    model for information spreading in contrast to betweenness
+    centrality which uses shortest paths.
+
+    Current-flow betweenness centrality is also known as
+    random-walk betweenness centrality [2]_.
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph
+
+    sources: list of nodes
+      Nodes to use as sources for current
+
+    targets: list of nodes
+      Nodes to use as sinks for current
+
+    normalized : bool, optional (default=True)
+      If True the betweenness values are normalized by b=b/(n-1)(n-2) where
+      n is the number of nodes in G.
+
+    weight : string or None, optional (default=None)
+      Key for edge data used as the edge weight.
+      If None, then use 1 as each edge weight.
+      The weight reflects the capacity or the strength of the
+      edge.
+
+    dtype: data type (float)
+      Default data type for internal matrices.
+      Set to np.float32 for lower memory consumption.
+
+    solver: string (default='lu')
+       Type of linear solver to use for computing the flow matrix.
+       Options are "full" (uses most memory), "lu" (recommended), and
+       "cg" (uses least memory).
+
+    Returns
+    -------
+    nodes : dictionary
+       Dictionary of nodes with betweenness centrality as the value.
+
+    See Also
+    --------
+    approximate_current_flow_betweenness_centrality
+    betweenness_centrality
+    edge_betweenness_centrality
+    edge_current_flow_betweenness_centrality
+
+    Notes
+    -----
+    Current-flow betweenness can be computed in $O(I(n-1)+mn \log n)$
+    time [1]_, where $I(n-1)$ is the time needed to compute the
+    inverse Laplacian.  For a full matrix this is $O(n^3)$ but using
+    sparse methods you can achieve $O(nm{\sqrt k})$ where $k$ is the
+    Laplacian matrix condition number.
+
+    The space required is $O(nw)$ where $w$ is the width of the sparse
+    Laplacian matrix.  Worse case is $w=n$ for $O(n^2)$.
+
+    If the edges have a 'weight' attribute they will be used as
+    weights in this algorithm.  Unspecified weights are set to 1.
+
+    References
+    ----------
+    .. [1] Centrality Measures Based on Current Flow.
+       Ulrik Brandes and Daniel Fleischer,
+       Proc. 22nd Symp. Theoretical Aspects of Computer Science (STACS '05).
+       LNCS 3404, pp. 533-544. Springer-Verlag, 2005.
+       https://doi.org/10.1007/978-3-540-31856-9_44
+
+    .. [2] A measure of betweenness centrality based on random walks,
+       M. E. J. Newman, Social Networks 27, 39-54 (2005).
+    """
+    import numpy as np
+
+    from networkx.utils import reverse_cuthill_mckee_ordering
+
+    if not nx.is_connected(G):
+        raise nx.NetworkXError("Graph not connected.")
+    N = G.number_of_nodes()
+    ordering = list(reverse_cuthill_mckee_ordering(G))
+    # make a copy with integer labels according to rcm ordering
+    # this could be done without a copy if we really wanted to
+    mapping = dict(zip(ordering, range(N)))
+    H = nx.relabel_nodes(G, mapping)
+    betweenness = dict.fromkeys(H, 0.0)  # b[n]=0 for n in H
+    for row, (s, t) in flow_matrix_row(H, weight=weight, dtype=dtype, solver=solver):
+        for ss in sources:
+            i = mapping[ss]
+            for tt in targets:
+                j = mapping[tt]
+                betweenness[s] += 0.5 * abs(row.item(i) - row.item(j))
+                betweenness[t] += 0.5 * abs(row.item(i) - row.item(j))
+    if normalized:
+        nb = (N - 1.0) * (N - 2.0)  # normalization factor
+    else:
+        nb = 2.0
+    for node in H:
+        betweenness[node] = betweenness[node] / nb + 1.0 / (2 - N)
+    return {ordering[node]: value for node, value in betweenness.items()}
+
+
+@not_implemented_for("directed")
+@nx._dispatchable(edge_attrs="weight")
+def edge_current_flow_betweenness_centrality_subset(
+    G, sources, targets, normalized=True, weight=None, dtype=float, solver="lu"
+):
+    r"""Compute current-flow betweenness centrality for edges using subsets
+    of nodes.
+
+    Current-flow betweenness centrality uses an electrical current
+    model for information spreading in contrast to betweenness
+    centrality which uses shortest paths.
+
+    Current-flow betweenness centrality is also known as
+    random-walk betweenness centrality [2]_.
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph
+
+    sources: list of nodes
+      Nodes to use as sources for current
+
+    targets: list of nodes
+      Nodes to use as sinks for current
+
+    normalized : bool, optional (default=True)
+      If True the betweenness values are normalized by b=b/(n-1)(n-2) where
+      n is the number of nodes in G.
+
+    weight : string or None, optional (default=None)
+      Key for edge data used as the edge weight.
+      If None, then use 1 as each edge weight.
+      The weight reflects the capacity or the strength of the
+      edge.
+
+    dtype: data type (float)
+      Default data type for internal matrices.
+      Set to np.float32 for lower memory consumption.
+
+    solver: string (default='lu')
+       Type of linear solver to use for computing the flow matrix.
+       Options are "full" (uses most memory), "lu" (recommended), and
+       "cg" (uses least memory).
+
+    Returns
+    -------
+    nodes : dict
+       Dictionary of edge tuples with betweenness centrality as the value.
+
+    See Also
+    --------
+    betweenness_centrality
+    edge_betweenness_centrality
+    current_flow_betweenness_centrality
+
+    Notes
+    -----
+    Current-flow betweenness can be computed in $O(I(n-1)+mn \log n)$
+    time [1]_, where $I(n-1)$ is the time needed to compute the
+    inverse Laplacian.  For a full matrix this is $O(n^3)$ but using
+    sparse methods you can achieve $O(nm{\sqrt k})$ where $k$ is the
+    Laplacian matrix condition number.
+
+    The space required is $O(nw)$ where $w$ is the width of the sparse
+    Laplacian matrix.  Worse case is $w=n$ for $O(n^2)$.
+
+    If the edges have a 'weight' attribute they will be used as
+    weights in this algorithm.  Unspecified weights are set to 1.
+
+    References
+    ----------
+    .. [1] Centrality Measures Based on Current Flow.
+       Ulrik Brandes and Daniel Fleischer,
+       Proc. 22nd Symp. Theoretical Aspects of Computer Science (STACS '05).
+       LNCS 3404, pp. 533-544. Springer-Verlag, 2005.
+       https://doi.org/10.1007/978-3-540-31856-9_44
+
+    .. [2] A measure of betweenness centrality based on random walks,
+       M. E. J. Newman, Social Networks 27, 39-54 (2005).
+    """
+    import numpy as np
+
+    if not nx.is_connected(G):
+        raise nx.NetworkXError("Graph not connected.")
+    N = G.number_of_nodes()
+    ordering = list(reverse_cuthill_mckee_ordering(G))
+    # make a copy with integer labels according to rcm ordering
+    # this could be done without a copy if we really wanted to
+    mapping = dict(zip(ordering, range(N)))
+    H = nx.relabel_nodes(G, mapping)
+    edges = (tuple(sorted((u, v))) for u, v in H.edges())
+    betweenness = dict.fromkeys(edges, 0.0)
+    if normalized:
+        nb = (N - 1.0) * (N - 2.0)  # normalization factor
+    else:
+        nb = 2.0
+    for row, (e) in flow_matrix_row(H, weight=weight, dtype=dtype, solver=solver):
+        for ss in sources:
+            i = mapping[ss]
+            for tt in targets:
+                j = mapping[tt]
+                betweenness[e] += 0.5 * abs(row.item(i) - row.item(j))
+        betweenness[e] /= nb
+    return {(ordering[s], ordering[t]): value for (s, t), value in betweenness.items()}

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/current_flow_closeness.py

@@ -0,0 +1,96 @@
+"""Current-flow closeness centrality measures."""
+
+import networkx as nx
+from networkx.algorithms.centrality.flow_matrix import (
+    CGInverseLaplacian,
+    FullInverseLaplacian,
+    SuperLUInverseLaplacian,
+)
+from networkx.utils import not_implemented_for, reverse_cuthill_mckee_ordering
+
+__all__ = ["current_flow_closeness_centrality", "information_centrality"]
+
+
+@not_implemented_for("directed")
+@nx._dispatchable(edge_attrs="weight")
+def current_flow_closeness_centrality(G, weight=None, dtype=float, solver="lu"):
+    """Compute current-flow closeness centrality for nodes.
+
+    Current-flow closeness centrality is variant of closeness
+    centrality based on effective resistance between nodes in
+    a network. This metric is also known as information centrality.
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph.
+
+    weight : None or string, optional (default=None)
+      If None, all edge weights are considered equal.
+      Otherwise holds the name of the edge attribute used as weight.
+      The weight reflects the capacity or the strength of the
+      edge.
+
+    dtype: data type (default=float)
+      Default data type for internal matrices.
+      Set to np.float32 for lower memory consumption.
+
+    solver: string (default='lu')
+       Type of linear solver to use for computing the flow matrix.
+       Options are "full" (uses most memory), "lu" (recommended), and
+       "cg" (uses least memory).
+
+    Returns
+    -------
+    nodes : dictionary
+       Dictionary of nodes with current flow closeness centrality as the value.
+
+    See Also
+    --------
+    closeness_centrality
+
+    Notes
+    -----
+    The algorithm is from Brandes [1]_.
+
+    See also [2]_ for the original definition of information centrality.
+
+    References
+    ----------
+    .. [1] Ulrik Brandes and Daniel Fleischer,
+       Centrality Measures Based on Current Flow.
+       Proc. 22nd Symp. Theoretical Aspects of Computer Science (STACS '05).
+       LNCS 3404, pp. 533-544. Springer-Verlag, 2005.
+       https://doi.org/10.1007/978-3-540-31856-9_44
+
+    .. [2] Karen Stephenson and Marvin Zelen:
+       Rethinking centrality: Methods and examples.
+       Social Networks 11(1):1-37, 1989.
+       https://doi.org/10.1016/0378-8733(89)90016-6
+    """
+    if not nx.is_connected(G):
+        raise nx.NetworkXError("Graph not connected.")
+    solvername = {
+        "full": FullInverseLaplacian,
+        "lu": SuperLUInverseLaplacian,
+        "cg": CGInverseLaplacian,
+    }
+    N = G.number_of_nodes()
+    ordering = list(reverse_cuthill_mckee_ordering(G))
+    # make a copy with integer labels according to rcm ordering
+    # this could be done without a copy if we really wanted to
+    H = nx.relabel_nodes(G, dict(zip(ordering, range(N))))
+    betweenness = dict.fromkeys(H, 0.0)  # b[n]=0 for n in H
+    N = H.number_of_nodes()
+    L = nx.laplacian_matrix(H, nodelist=range(N), weight=weight).asformat("csc")
+    L = L.astype(dtype)
+    C2 = solvername[solver](L, width=1, dtype=dtype)  # initialize solver
+    for v in H:
+        col = C2.get_row(v)
+        for w in H:
+            betweenness[v] += col.item(v) - 2 * col.item(w)
+            betweenness[w] += col.item(v)
+    return {ordering[node]: 1 / value for node, value in betweenness.items()}
+
+
+information_centrality = current_flow_closeness_centrality

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/eigenvector.py

@@ -0,0 +1,357 @@
+"""Functions for computing eigenvector centrality."""
+
+import math
+
+import networkx as nx
+from networkx.utils import not_implemented_for
+
+__all__ = ["eigenvector_centrality", "eigenvector_centrality_numpy"]
+
+
+@not_implemented_for("multigraph")
+@nx._dispatchable(edge_attrs="weight")
+def eigenvector_centrality(G, max_iter=100, tol=1.0e-6, nstart=None, weight=None):
+    r"""Compute the eigenvector centrality for the graph G.
+
+    Eigenvector centrality computes the centrality for a node by adding
+    the centrality of its predecessors. The centrality for node $i$ is the
+    $i$-th element of a left eigenvector associated with the eigenvalue $\lambda$
+    of maximum modulus that is positive. Such an eigenvector $x$ is
+    defined up to a multiplicative constant by the equation
+
+    .. math::
+
+         \lambda x^T = x^T A,
+
+    where $A$ is the adjacency matrix of the graph G. By definition of
+    row-column product, the equation above is equivalent to
+
+    .. math::
+
+        \lambda x_i = \sum_{j\to i}x_j.
+
+    That is, adding the eigenvector centralities of the predecessors of
+    $i$ one obtains the eigenvector centrality of $i$ multiplied by
+    $\lambda$. In the case of undirected graphs, $x$ also solves the familiar
+    right-eigenvector equation $Ax = \lambda x$.
+
+    By virtue of the Perron–Frobenius theorem [1]_, if G is strongly
+    connected there is a unique eigenvector $x$, and all its entries
+    are strictly positive.
+
+    If G is not strongly connected there might be several left
+    eigenvectors associated with $\lambda$, and some of their elements
+    might be zero.
+
+    Parameters
+    ----------
+    G : graph
+      A networkx graph.
+
+    max_iter : integer, optional (default=100)
+      Maximum number of power iterations.
+
+    tol : float, optional (default=1.0e-6)
+      Error tolerance (in Euclidean norm) used to check convergence in
+      power iteration.
+
+    nstart : dictionary, optional (default=None)
+      Starting value of power iteration for each node. Must have a nonzero
+      projection on the desired eigenvector for the power method to converge.
+      If None, this implementation uses an all-ones vector, which is a safe
+      choice.
+
+    weight : None or string, optional (default=None)
+      If None, all edge weights are considered equal. Otherwise holds the
+      name of the edge attribute used as weight. In this measure the
+      weight is interpreted as the connection strength.
+
+    Returns
+    -------
+    nodes : dictionary
+       Dictionary of nodes with eigenvector centrality as the value. The
+       associated vector has unit Euclidean norm and the values are
+       nonegative.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> centrality = nx.eigenvector_centrality(G)
+    >>> sorted((v, f"{c:0.2f}") for v, c in centrality.items())
+    [(0, '0.37'), (1, '0.60'), (2, '0.60'), (3, '0.37')]
+
+    Raises
+    ------
+    NetworkXPointlessConcept
+        If the graph G is the null graph.
+
+    NetworkXError
+        If each value in `nstart` is zero.
+
+    PowerIterationFailedConvergence
+        If the algorithm fails to converge to the specified tolerance
+        within the specified number of iterations of the power iteration
+        method.
+
+    See Also
+    --------
+    eigenvector_centrality_numpy
+    :func:`~networkx.algorithms.link_analysis.pagerank_alg.pagerank`
+    :func:`~networkx.algorithms.link_analysis.hits_alg.hits`
+
+    Notes
+    -----
+    Eigenvector centrality was introduced by Landau [2]_ for chess
+    tournaments. It was later rediscovered by Wei [3]_ and then
+    popularized by Kendall [4]_ in the context of sport ranking. Berge
+    introduced a general definition for graphs based on social connections
+    [5]_. Bonacich [6]_ reintroduced again eigenvector centrality and made
+    it popular in link analysis.
+
+    This function computes the left dominant eigenvector, which corresponds
+    to adding the centrality of predecessors: this is the usual approach.
+    To add the centrality of successors first reverse the graph with
+    ``G.reverse()``.
+
+    The implementation uses power iteration [7]_ to compute a dominant
+    eigenvector starting from the provided vector `nstart`. Convergence is
+    guaranteed as long as `nstart` has a nonzero projection on a dominant
+    eigenvector, which certainly happens using the default value.
+
+    The method stops when the change in the computed vector between two
+    iterations is smaller than an error tolerance of ``G.number_of_nodes()
+    * tol`` or after ``max_iter`` iterations, but in the second case it
+    raises an exception.
+
+    This implementation uses $(A + I)$ rather than the adjacency matrix
+    $A$ because the change preserves eigenvectors, but it shifts the
+    spectrum, thus guaranteeing convergence even for networks with
+    negative eigenvalues of maximum modulus.
+
+    References
+    ----------
+    .. [1] Abraham Berman and Robert J. Plemmons.
+       "Nonnegative Matrices in the Mathematical Sciences."
+       Classics in Applied Mathematics. SIAM, 1994.
+
+    .. [2] Edmund Landau.
+       "Zur relativen Wertbemessung der Turnierresultate."
+       Deutsches Wochenschach, 11:366–369, 1895.
+
+    .. [3] Teh-Hsing Wei.
+       "The Algebraic Foundations of Ranking Theory."
+       PhD thesis, University of Cambridge, 1952.
+
+    .. [4] Maurice G. Kendall.
+       "Further contributions to the theory of paired comparisons."
+       Biometrics, 11(1):43–62, 1955.
+       https://www.jstor.org/stable/3001479
+
+    .. [5] Claude Berge
+       "Théorie des graphes et ses applications."
+       Dunod, Paris, France, 1958.
+
+    .. [6] Phillip Bonacich.
+       "Technique for analyzing overlapping memberships."
+       Sociological Methodology, 4:176–185, 1972.
+       https://www.jstor.org/stable/270732
+
+    .. [7] Power iteration:: https://en.wikipedia.org/wiki/Power_iteration
+
+    """
+    if len(G) == 0:
+        raise nx.NetworkXPointlessConcept(
+            "cannot compute centrality for the null graph"
+        )
+    # If no initial vector is provided, start with the all-ones vector.
+    if nstart is None:
+        nstart = {v: 1 for v in G}
+    if all(v == 0 for v in nstart.values()):
+        raise nx.NetworkXError("initial vector cannot have all zero values")
+    # Normalize the initial vector so that each entry is in [0, 1]. This is
+    # guaranteed to never have a divide-by-zero error by the previous line.
+    nstart_sum = sum(nstart.values())
+    x = {k: v / nstart_sum for k, v in nstart.items()}
+    nnodes = G.number_of_nodes()
+    # make up to max_iter iterations
+    for _ in range(max_iter):
+        xlast = x
+        x = xlast.copy()  # Start with xlast times I to iterate with (A+I)
+        # do the multiplication y^T = x^T A (left eigenvector)
+        for n in x:
+            for nbr in G[n]:
+                w = G[n][nbr].get(weight, 1) if weight else 1
+                x[nbr] += xlast[n] * w
+        # Normalize the vector. The normalization denominator `norm`
+        # should never be zero by the Perron--Frobenius
+        # theorem. However, in case it is due to numerical error, we
+        # assume the norm to be one instead.
+        norm = math.hypot(*x.values()) or 1
+        x = {k: v / norm for k, v in x.items()}
+        # Check for convergence (in the L_1 norm).
+        if sum(abs(x[n] - xlast[n]) for n in x) < nnodes * tol:
+            return x
+    raise nx.PowerIterationFailedConvergence(max_iter)
+
+
+@nx._dispatchable(edge_attrs="weight")
+def eigenvector_centrality_numpy(G, weight=None, max_iter=50, tol=0):
+    r"""Compute the eigenvector centrality for the graph `G`.
+
+    Eigenvector centrality computes the centrality for a node by adding
+    the centrality of its predecessors. The centrality for node $i$ is the
+    $i$-th element of a left eigenvector associated with the eigenvalue $\lambda$
+    of maximum modulus that is positive. Such an eigenvector $x$ is
+    defined up to a multiplicative constant by the equation
+
+    .. math::
+
+         \lambda x^T = x^T A,
+
+    where $A$ is the adjacency matrix of the graph `G`. By definition of
+    row-column product, the equation above is equivalent to
+
+    .. math::
+
+        \lambda x_i = \sum_{j\to i}x_j.
+
+    That is, adding the eigenvector centralities of the predecessors of
+    $i$ one obtains the eigenvector centrality of $i$ multiplied by
+    $\lambda$. In the case of undirected graphs, $x$ also solves the familiar
+    right-eigenvector equation $Ax = \lambda x$.
+
+    By virtue of the Perron--Frobenius theorem [1]_, if `G` is (strongly)
+    connected, there is a unique eigenvector $x$, and all its entries
+    are strictly positive.
+
+    However, if `G` is not (strongly) connected, there might be several left
+    eigenvectors associated with $\lambda$, and some of their elements
+    might be zero.
+    Depending on the method used to choose eigenvectors, round-off error can affect
+    which of the infinitely many eigenvectors is reported.
+    This can lead to inconsistent results for the same graph,
+    which the underlying implementation is not robust to.
+    For this reason, only (strongly) connected graphs are accepted.
+
+    Parameters
+    ----------
+    G : graph
+        A connected NetworkX graph.
+
+    weight : None or string, optional (default=None)
+        If ``None``, all edge weights are considered equal. Otherwise holds the
+        name of the edge attribute used as weight. In this measure the
+        weight is interpreted as the connection strength.
+
+    max_iter : integer, optional (default=50)
+        Maximum number of Arnoldi update iterations allowed.
+
+    tol : float, optional (default=0)
+        Relative accuracy for eigenvalues (stopping criterion).
+        The default value of 0 implies machine precision.
+
+    Returns
+    -------
+    nodes : dict of nodes
+        Dictionary of nodes with eigenvector centrality as the value. The
+        associated vector has unit Euclidean norm and the values are
+        nonnegative.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> centrality = nx.eigenvector_centrality_numpy(G)
+    >>> print([f"{node} {centrality[node]:0.2f}" for node in centrality])
+    ['0 0.37', '1 0.60', '2 0.60', '3 0.37']
+
+    Raises
+    ------
+    NetworkXPointlessConcept
+        If the graph `G` is the null graph.
+
+    ArpackNoConvergence
+        When the requested convergence is not obtained. The currently
+        converged eigenvalues and eigenvectors can be found as
+        eigenvalues and eigenvectors attributes of the exception object.
+
+    AmbiguousSolution
+        If `G` is not connected.
+
+    See Also
+    --------
+    :func:`scipy.sparse.linalg.eigs`
+    eigenvector_centrality
+    :func:`~networkx.algorithms.link_analysis.pagerank_alg.pagerank`
+    :func:`~networkx.algorithms.link_analysis.hits_alg.hits`
+
+    Notes
+    -----
+    Eigenvector centrality was introduced by Landau [2]_ for chess
+    tournaments. It was later rediscovered by Wei [3]_ and then
+    popularized by Kendall [4]_ in the context of sport ranking. Berge
+    introduced a general definition for graphs based on social connections
+    [5]_. Bonacich [6]_ reintroduced again eigenvector centrality and made
+    it popular in link analysis.
+
+    This function computes the left dominant eigenvector, which corresponds
+    to adding the centrality of predecessors: this is the usual approach.
+    To add the centrality of successors first reverse the graph with
+    ``G.reverse()``.
+
+    This implementation uses the
+    :func:`SciPy sparse eigenvalue solver<scipy.sparse.linalg.eigs>` (ARPACK)
+    to find the largest eigenvalue/eigenvector pair using Arnoldi iterations
+    [7]_.
+
+    References
+    ----------
+    .. [1] Abraham Berman and Robert J. Plemmons.
+       "Nonnegative Matrices in the Mathematical Sciences".
+       Classics in Applied Mathematics. SIAM, 1994.
+
+    .. [2] Edmund Landau.
+       "Zur relativen Wertbemessung der Turnierresultate".
+       Deutsches Wochenschach, 11:366--369, 1895.
+
+    .. [3] Teh-Hsing Wei.
+       "The Algebraic Foundations of Ranking Theory".
+       PhD thesis, University of Cambridge, 1952.
+
+    .. [4] Maurice G. Kendall.
+       "Further contributions to the theory of paired comparisons".
+       Biometrics, 11(1):43--62, 1955.
+       https://www.jstor.org/stable/3001479
+
+    .. [5] Claude Berge.
+       "Théorie des graphes et ses applications".
+       Dunod, Paris, France, 1958.
+
+    .. [6] Phillip Bonacich.
+       "Technique for analyzing overlapping memberships".
+       Sociological Methodology, 4:176--185, 1972.
+       https://www.jstor.org/stable/270732
+
+    .. [7] Arnoldi, W. E. (1951).
+       "The principle of minimized iterations in the solution of the matrix eigenvalue problem".
+       Quarterly of Applied Mathematics. 9 (1): 17--29.
+       https://doi.org/10.1090/qam/42792
+    """
+    import numpy as np
+    import scipy as sp
+
+    if len(G) == 0:
+        raise nx.NetworkXPointlessConcept(
+            "cannot compute centrality for the null graph"
+        )
+    connected = nx.is_strongly_connected(G) if G.is_directed() else nx.is_connected(G)
+    if not connected:  # See gh-6888.
+        raise nx.AmbiguousSolution(
+            "`eigenvector_centrality_numpy` does not give consistent results for disconnected graphs"
+        )
+    M = nx.to_scipy_sparse_array(G, nodelist=list(G), weight=weight, dtype=float)
+    _, eigenvector = sp.sparse.linalg.eigs(
+        M.T, k=1, which="LR", maxiter=max_iter, tol=tol
+    )
+    largest = eigenvector.flatten().real
+    norm = np.sign(largest.sum()) * sp.linalg.norm(largest)
+    return dict(zip(G, (largest / norm).tolist()))

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/flow_matrix.py

@@ -0,0 +1,130 @@
+# Helpers for current-flow betweenness and current-flow closeness
+# Lazy computations for inverse Laplacian and flow-matrix rows.
+import networkx as nx
+
+
+@nx._dispatchable(edge_attrs="weight")
+def flow_matrix_row(G, weight=None, dtype=float, solver="lu"):
+    # Generate a row of the current-flow matrix
+    import numpy as np
+
+    solvername = {
+        "full": FullInverseLaplacian,
+        "lu": SuperLUInverseLaplacian,
+        "cg": CGInverseLaplacian,
+    }
+    n = G.number_of_nodes()
+    L = nx.laplacian_matrix(G, nodelist=range(n), weight=weight).asformat("csc")
+    L = L.astype(dtype)
+    C = solvername[solver](L, dtype=dtype)  # initialize solver
+    w = C.w  # w is the Laplacian matrix width
+    # row-by-row flow matrix
+    for u, v in sorted(sorted((u, v)) for u, v in G.edges()):
+        B = np.zeros(w, dtype=dtype)
+        c = G[u][v].get(weight, 1.0)
+        B[u % w] = c
+        B[v % w] = -c
+        # get only the rows needed in the inverse laplacian
+        # and multiply to get the flow matrix row
+        row = B @ C.get_rows(u, v)
+        yield row, (u, v)
+
+
+# Class to compute the inverse laplacian only for specified rows
+# Allows computation of the current-flow matrix without storing entire
+# inverse laplacian matrix
+class InverseLaplacian:
+    def __init__(self, L, width=None, dtype=None):
+        global np
+        import numpy as np
+
+        (n, n) = L.shape
+        self.dtype = dtype
+        self.n = n
+        if width is None:
+            self.w = self.width(L)
+        else:
+            self.w = width
+        self.C = np.zeros((self.w, n), dtype=dtype)
+        self.L1 = L[1:, 1:]
+        self.init_solver(L)
+
+    def init_solver(self, L):
+        pass
+
+    def solve(self, r):
+        raise nx.NetworkXError("Implement solver")
+
+    def solve_inverse(self, r):
+        raise nx.NetworkXError("Implement solver")
+
+    def get_rows(self, r1, r2):
+        for r in range(r1, r2 + 1):
+            self.C[r % self.w, 1:] = self.solve_inverse(r)
+        return self.C
+
+    def get_row(self, r):
+        self.C[r % self.w, 1:] = self.solve_inverse(r)
+        return self.C[r % self.w]
+
+    def width(self, L):
+        m = 0
+        for i, row in enumerate(L):
+            w = 0
+            y = np.nonzero(row)[-1]
+            if len(y) > 0:
+                v = y - i
+                w = v.max() - v.min() + 1
+                m = max(w, m)
+        return m
+
+
+class FullInverseLaplacian(InverseLaplacian):
+    def init_solver(self, L):
+        self.IL = np.zeros(L.shape, dtype=self.dtype)
+        self.IL[1:, 1:] = np.linalg.inv(self.L1.todense())
+
+    def solve(self, rhs):
+        s = np.zeros(rhs.shape, dtype=self.dtype)
+        s = self.IL @ rhs
+        return s
+
+    def solve_inverse(self, r):
+        return self.IL[r, 1:]
+
+
+class SuperLUInverseLaplacian(InverseLaplacian):
+    def init_solver(self, L):
+        import scipy as sp
+
+        self.lusolve = sp.sparse.linalg.factorized(self.L1.tocsc())
+
+    def solve_inverse(self, r):
+        rhs = np.zeros(self.n, dtype=self.dtype)
+        rhs[r] = 1
+        return self.lusolve(rhs[1:])
+
+    def solve(self, rhs):
+        s = np.zeros(rhs.shape, dtype=self.dtype)
+        s[1:] = self.lusolve(rhs[1:])
+        return s
+
+
+class CGInverseLaplacian(InverseLaplacian):
+    def init_solver(self, L):
+        global sp
+        import scipy as sp
+
+        ilu = sp.sparse.linalg.spilu(self.L1.tocsc())
+        n = self.n - 1
+        self.M = sp.sparse.linalg.LinearOperator(shape=(n, n), matvec=ilu.solve)
+
+    def solve(self, rhs):
+        s = np.zeros(rhs.shape, dtype=self.dtype)
+        s[1:] = sp.sparse.linalg.cg(self.L1, rhs[1:], M=self.M, atol=0)[0]
+        return s
+
+    def solve_inverse(self, r):
+        rhs = np.zeros(self.n, self.dtype)
+        rhs[r] = 1
+        return sp.sparse.linalg.cg(self.L1, rhs[1:], M=self.M, atol=0)[0]

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/group.py

@@ -0,0 +1,787 @@
+"""Group centrality measures."""
+
+from copy import deepcopy
+
+import networkx as nx
+from networkx.algorithms.centrality.betweenness import (
+    _accumulate_endpoints,
+    _single_source_dijkstra_path_basic,
+    _single_source_shortest_path_basic,
+)
+from networkx.utils.decorators import not_implemented_for
+
+__all__ = [
+    "group_betweenness_centrality",
+    "group_closeness_centrality",
+    "group_degree_centrality",
+    "group_in_degree_centrality",
+    "group_out_degree_centrality",
+    "prominent_group",
+]
+
+
+@nx._dispatchable(edge_attrs="weight")
+def group_betweenness_centrality(G, C, normalized=True, weight=None, endpoints=False):
+    r"""Compute the group betweenness centrality for a group of nodes.
+
+    Group betweenness centrality of a group of nodes $C$ is the sum of the
+    fraction of all-pairs shortest paths that pass through any vertex in $C$
+
+    .. math::
+
+       c_B(v) =\sum_{s,t \in V} \frac{\sigma(s, t|v)}{\sigma(s, t)}
+
+    where $V$ is the set of nodes, $\sigma(s, t)$ is the number of
+    shortest $(s, t)$-paths, and $\sigma(s, t|C)$ is the number of
+    those paths passing through some node in group $C$. Note that
+    $(s, t)$ are not members of the group ($V-C$ is the set of nodes
+    in $V$ that are not in $C$).
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph.
+
+    C : list or set or list of lists or list of sets
+      A group or a list of groups containing nodes which belong to G, for which group betweenness
+      centrality is to be calculated.
+
+    normalized : bool, optional (default=True)
+      If True, group betweenness is normalized by `1/((|V|-|C|)(|V|-|C|-1))`
+      where `|V|` is the number of nodes in G and `|C|` is the number of nodes in C.
+
+    weight : None or string, optional (default=None)
+      If None, all edge weights are considered equal.
+      Otherwise holds the name of the edge attribute used as weight.
+      The weight of an edge is treated as the length or distance between the two sides.
+
+    endpoints : bool, optional (default=False)
+      If True include the endpoints in the shortest path counts.
+
+    Raises
+    ------
+    NodeNotFound
+       If node(s) in C are not present in G.
+
+    Returns
+    -------
+    betweenness : list of floats or float
+       If C is a single group then return a float. If C is a list with
+       several groups then return a list of group betweenness centralities.
+
+    See Also
+    --------
+    betweenness_centrality
+
+    Notes
+    -----
+    Group betweenness centrality is described in [1]_ and its importance discussed in [3]_.
+    The initial implementation of the algorithm is mentioned in [2]_. This function uses
+    an improved algorithm presented in [4]_.
+
+    The number of nodes in the group must be a maximum of n - 2 where `n`
+    is the total number of nodes in the graph.
+
+    For weighted graphs the edge weights must be greater than zero.
+    Zero edge weights can produce an infinite number of equal length
+    paths between pairs of nodes.
+
+    The total number of paths between source and target is counted
+    differently for directed and undirected graphs. Directed paths
+    between "u" and "v" are counted as two possible paths (one each
+    direction) while undirected paths between "u" and "v" are counted
+    as one path. Said another way, the sum in the expression above is
+    over all ``s != t`` for directed graphs and for ``s < t`` for undirected graphs.
+
+
+    References
+    ----------
+    .. [1] M G Everett and S P Borgatti:
+       The Centrality of Groups and Classes.
+       Journal of Mathematical Sociology. 23(3): 181-201. 1999.
+       http://www.analytictech.com/borgatti/group_centrality.htm
+    .. [2] Ulrik Brandes:
+       On Variants of Shortest-Path Betweenness
+       Centrality and their Generic Computation.
+       Social Networks 30(2):136-145, 2008.
+       http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.72.9610&rep=rep1&type=pdf
+    .. [3] Sourav Medya et. al.:
+       Group Centrality Maximization via Network Design.
+       SIAM International Conference on Data Mining, SDM 2018, 126–134.
+       https://sites.cs.ucsb.edu/~arlei/pubs/sdm18.pdf
+    .. [4] Rami Puzis, Yuval Elovici, and Shlomi Dolev.
+       "Fast algorithm for successive computation of group betweenness centrality."
+       https://journals.aps.org/pre/pdf/10.1103/PhysRevE.76.056709
+
+    """
+    GBC = []  # initialize betweenness
+    list_of_groups = True
+    #  check weather C contains one or many groups
+    if any(el in G for el in C):
+        C = [C]
+        list_of_groups = False
+    set_v = {node for group in C for node in group}
+    if set_v - G.nodes:  # element(s) of C not in G
+        raise nx.NodeNotFound(f"The node(s) {set_v - G.nodes} are in C but not in G.")
+
+    # pre-processing
+    PB, sigma, D = _group_preprocessing(G, set_v, weight)
+
+    # the algorithm for each group
+    for group in C:
+        group = set(group)  # set of nodes in group
+        # initialize the matrices of the sigma and the PB
+        GBC_group = 0
+        sigma_m = deepcopy(sigma)
+        PB_m = deepcopy(PB)
+        sigma_m_v = deepcopy(sigma_m)
+        PB_m_v = deepcopy(PB_m)
+        for v in group:
+            GBC_group += PB_m[v][v]
+            for x in group:
+                for y in group:
+                    dxvy = 0
+                    dxyv = 0
+                    dvxy = 0
+                    if not (
+                        sigma_m[x][y] == 0 or sigma_m[x][v] == 0 or sigma_m[v][y] == 0
+                    ):
+                        if D[x][v] == D[x][y] + D[y][v]:
+                            dxyv = sigma_m[x][y] * sigma_m[y][v] / sigma_m[x][v]
+                        if D[x][y] == D[x][v] + D[v][y]:
+                            dxvy = sigma_m[x][v] * sigma_m[v][y] / sigma_m[x][y]
+                        if D[v][y] == D[v][x] + D[x][y]:
+                            dvxy = sigma_m[v][x] * sigma[x][y] / sigma[v][y]
+                    sigma_m_v[x][y] = sigma_m[x][y] * (1 - dxvy)
+                    PB_m_v[x][y] = PB_m[x][y] - PB_m[x][y] * dxvy
+                    if y != v:
+                        PB_m_v[x][y] -= PB_m[x][v] * dxyv
+                    if x != v:
+                        PB_m_v[x][y] -= PB_m[v][y] * dvxy
+            sigma_m, sigma_m_v = sigma_m_v, sigma_m
+            PB_m, PB_m_v = PB_m_v, PB_m
+
+        # endpoints
+        v, c = len(G), len(group)
+        if not endpoints:
+            scale = 0
+            # if the graph is connected then subtract the endpoints from
+            # the count for all the nodes in the graph. else count how many
+            # nodes are connected to the group's nodes and subtract that.
+            if nx.is_directed(G):
+                if nx.is_strongly_connected(G):
+                    scale = c * (2 * v - c - 1)
+            elif nx.is_connected(G):
+                scale = c * (2 * v - c - 1)
+            if scale == 0:
+                for group_node1 in group:
+                    for node in D[group_node1]:
+                        if node != group_node1:
+                            if node in group:
+                                scale += 1
+                            else:
+                                scale += 2
+            GBC_group -= scale
+
+        # normalized
+        if normalized:
+            scale = 1 / ((v - c) * (v - c - 1))
+            GBC_group *= scale
+
+        # If undirected than count only the undirected edges
+        elif not G.is_directed():
+            GBC_group /= 2
+
+        GBC.append(GBC_group)
+    if list_of_groups:
+        return GBC
+    return GBC[0]
+
+
+def _group_preprocessing(G, set_v, weight):
+    sigma = {}
+    delta = {}
+    D = {}
+    betweenness = dict.fromkeys(G, 0)
+    for s in G:
+        if weight is None:  # use BFS
+            S, P, sigma[s], D[s] = _single_source_shortest_path_basic(G, s)
+        else:  # use Dijkstra's algorithm
+            S, P, sigma[s], D[s] = _single_source_dijkstra_path_basic(G, s, weight)
+        betweenness, delta[s] = _accumulate_endpoints(betweenness, S, P, sigma[s], s)
+        for i in delta[s]:  # add the paths from s to i and rescale sigma
+            if s != i:
+                delta[s][i] += 1
+            if weight is not None:
+                sigma[s][i] = sigma[s][i] / 2
+    # building the path betweenness matrix only for nodes that appear in the group
+    PB = dict.fromkeys(G)
+    for group_node1 in set_v:
+        PB[group_node1] = dict.fromkeys(G, 0.0)
+        for group_node2 in set_v:
+            if group_node2 not in D[group_node1]:
+                continue
+            for node in G:
+                # if node is connected to the two group nodes than continue
+                if group_node2 in D[node] and group_node1 in D[node]:
+                    if (
+                        D[node][group_node2]
+                        == D[node][group_node1] + D[group_node1][group_node2]
+                    ):
+                        PB[group_node1][group_node2] += (
+                            delta[node][group_node2]
+                            * sigma[node][group_node1]
+                            * sigma[group_node1][group_node2]
+                            / sigma[node][group_node2]
+                        )
+    return PB, sigma, D
+
+
+@nx._dispatchable(edge_attrs="weight")
+def prominent_group(
+    G, k, weight=None, C=None, endpoints=False, normalized=True, greedy=False
+):
+    r"""Find the prominent group of size $k$ in graph $G$. The prominence of the
+    group is evaluated by the group betweenness centrality.
+
+    Group betweenness centrality of a group of nodes $C$ is the sum of the
+    fraction of all-pairs shortest paths that pass through any vertex in $C$
+
+    .. math::
+
+       c_B(v) =\sum_{s,t \in V} \frac{\sigma(s, t|v)}{\sigma(s, t)}
+
+    where $V$ is the set of nodes, $\sigma(s, t)$ is the number of
+    shortest $(s, t)$-paths, and $\sigma(s, t|C)$ is the number of
+    those paths passing through some node in group $C$. Note that
+    $(s, t)$ are not members of the group ($V-C$ is the set of nodes
+    in $V$ that are not in $C$).
+
+    Parameters
+    ----------
+    G : graph
+       A NetworkX graph.
+
+    k : int
+       The number of nodes in the group.
+
+    normalized : bool, optional (default=True)
+       If True, group betweenness is normalized by ``1/((|V|-|C|)(|V|-|C|-1))``
+       where ``|V|`` is the number of nodes in G and ``|C|`` is the number of
+       nodes in C.
+
+    weight : None or string, optional (default=None)
+       If None, all edge weights are considered equal.
+       Otherwise holds the name of the edge attribute used as weight.
+       The weight of an edge is treated as the length or distance between the two sides.
+
+    endpoints : bool, optional (default=False)
+       If True include the endpoints in the shortest path counts.
+
+    C : list or set, optional (default=None)
+       list of nodes which won't be candidates of the prominent group.
+
+    greedy : bool, optional (default=False)
+       Using a naive greedy algorithm in order to find non-optimal prominent
+       group. For scale free networks the results are negligibly below the optimal
+       results.
+
+    Raises
+    ------
+    NodeNotFound
+       If node(s) in C are not present in G.
+
+    Returns
+    -------
+    max_GBC : float
+       The group betweenness centrality of the prominent group.
+
+    max_group : list
+        The list of nodes in the prominent group.
+
+    See Also
+    --------
+    betweenness_centrality, group_betweenness_centrality
+
+    Notes
+    -----
+    Group betweenness centrality is described in [1]_ and its importance discussed in [3]_.
+    The algorithm is described in [2]_ and is based on techniques mentioned in [4]_.
+
+    The number of nodes in the group must be a maximum of ``n - 2`` where ``n``
+    is the total number of nodes in the graph.
+
+    For weighted graphs the edge weights must be greater than zero.
+    Zero edge weights can produce an infinite number of equal length
+    paths between pairs of nodes.
+
+    The total number of paths between source and target is counted
+    differently for directed and undirected graphs. Directed paths
+    between "u" and "v" are counted as two possible paths (one each
+    direction) while undirected paths between "u" and "v" are counted
+    as one path. Said another way, the sum in the expression above is
+    over all ``s != t`` for directed graphs and for ``s < t`` for undirected graphs.
+
+    References
+    ----------
+    .. [1] M G Everett and S P Borgatti:
+       The Centrality of Groups and Classes.
+       Journal of Mathematical Sociology. 23(3): 181-201. 1999.
+       http://www.analytictech.com/borgatti/group_centrality.htm
+    .. [2] Rami Puzis, Yuval Elovici, and Shlomi Dolev:
+       "Finding the Most Prominent Group in Complex Networks"
+       AI communications 20(4): 287-296, 2007.
+       https://www.researchgate.net/profile/Rami_Puzis2/publication/220308855
+    .. [3] Sourav Medya et. al.:
+       Group Centrality Maximization via Network Design.
+       SIAM International Conference on Data Mining, SDM 2018, 126–134.
+       https://sites.cs.ucsb.edu/~arlei/pubs/sdm18.pdf
+    .. [4] Rami Puzis, Yuval Elovici, and Shlomi Dolev.
+       "Fast algorithm for successive computation of group betweenness centrality."
+       https://journals.aps.org/pre/pdf/10.1103/PhysRevE.76.056709
+    """
+    import numpy as np
+    import pandas as pd
+
+    if C is not None:
+        C = set(C)
+        if C - G.nodes:  # element(s) of C not in G
+            raise nx.NodeNotFound(f"The node(s) {C - G.nodes} are in C but not in G.")
+        nodes = list(G.nodes - C)
+    else:
+        nodes = list(G.nodes)
+    DF_tree = nx.Graph()
+    DF_tree.__networkx_cache__ = None  # Disable caching
+    PB, sigma, D = _group_preprocessing(G, nodes, weight)
+    betweenness = pd.DataFrame.from_dict(PB)
+    if C is not None:
+        for node in C:
+            # remove from the betweenness all the nodes not part of the group
+            betweenness.drop(index=node, inplace=True)
+            betweenness.drop(columns=node, inplace=True)
+    CL = [node for _, node in sorted(zip(np.diag(betweenness), nodes), reverse=True)]
+    max_GBC = 0
+    max_group = []
+    DF_tree.add_node(
+        1,
+        CL=CL,
+        betweenness=betweenness,
+        GBC=0,
+        GM=[],
+        sigma=sigma,
+        cont=dict(zip(nodes, np.diag(betweenness))),
+    )
+
+    # the algorithm
+    DF_tree.nodes[1]["heu"] = 0
+    for i in range(k):
+        DF_tree.nodes[1]["heu"] += DF_tree.nodes[1]["cont"][DF_tree.nodes[1]["CL"][i]]
+    max_GBC, DF_tree, max_group = _dfbnb(
+        G, k, DF_tree, max_GBC, 1, D, max_group, nodes, greedy
+    )
+
+    v = len(G)
+    if not endpoints:
+        scale = 0
+        # if the graph is connected then subtract the endpoints from
+        # the count for all the nodes in the graph. else count how many
+        # nodes are connected to the group's nodes and subtract that.
+        if nx.is_directed(G):
+            if nx.is_strongly_connected(G):
+                scale = k * (2 * v - k - 1)
+        elif nx.is_connected(G):
+            scale = k * (2 * v - k - 1)
+        if scale == 0:
+            for group_node1 in max_group:
+                for node in D[group_node1]:
+                    if node != group_node1:
+                        if node in max_group:
+                            scale += 1
+                        else:
+                            scale += 2
+        max_GBC -= scale
+
+    # normalized
+    if normalized:
+        scale = 1 / ((v - k) * (v - k - 1))
+        max_GBC *= scale
+
+    # If undirected then count only the undirected edges
+    elif not G.is_directed():
+        max_GBC /= 2
+    max_GBC = float(f"{max_GBC:.2f}")
+    return max_GBC, max_group
+
+
+def _dfbnb(G, k, DF_tree, max_GBC, root, D, max_group, nodes, greedy):
+    # stopping condition - if we found a group of size k and with higher GBC then prune
+    if len(DF_tree.nodes[root]["GM"]) == k and DF_tree.nodes[root]["GBC"] > max_GBC:
+        return DF_tree.nodes[root]["GBC"], DF_tree, DF_tree.nodes[root]["GM"]
+    # stopping condition - if the size of group members equal to k or there are less than
+    # k - |GM| in the candidate list or the heuristic function plus the GBC is below the
+    # maximal GBC found then prune
+    if (
+        len(DF_tree.nodes[root]["GM"]) == k
+        or len(DF_tree.nodes[root]["CL"]) <= k - len(DF_tree.nodes[root]["GM"])
+        or DF_tree.nodes[root]["GBC"] + DF_tree.nodes[root]["heu"] <= max_GBC
+    ):
+        return max_GBC, DF_tree, max_group
+
+    # finding the heuristic of both children
+    node_p, node_m, DF_tree = _heuristic(k, root, DF_tree, D, nodes, greedy)
+
+    # finding the child with the bigger heuristic + GBC and expand
+    # that node first if greedy then only expand the plus node
+    if greedy:
+        max_GBC, DF_tree, max_group = _dfbnb(
+            G, k, DF_tree, max_GBC, node_p, D, max_group, nodes, greedy
+        )
+
+    elif (
+        DF_tree.nodes[node_p]["GBC"] + DF_tree.nodes[node_p]["heu"]
+        > DF_tree.nodes[node_m]["GBC"] + DF_tree.nodes[node_m]["heu"]
+    ):
+        max_GBC, DF_tree, max_group = _dfbnb(
+            G, k, DF_tree, max_GBC, node_p, D, max_group, nodes, greedy
+        )
+        max_GBC, DF_tree, max_group = _dfbnb(
+            G, k, DF_tree, max_GBC, node_m, D, max_group, nodes, greedy
+        )
+    else:
+        max_GBC, DF_tree, max_group = _dfbnb(
+            G, k, DF_tree, max_GBC, node_m, D, max_group, nodes, greedy
+        )
+        max_GBC, DF_tree, max_group = _dfbnb(
+            G, k, DF_tree, max_GBC, node_p, D, max_group, nodes, greedy
+        )
+    return max_GBC, DF_tree, max_group
+
+
+def _heuristic(k, root, DF_tree, D, nodes, greedy):
+    import numpy as np
+
+    # This helper function add two nodes to DF_tree - one left son and the
+    # other right son, finds their heuristic, CL, GBC, and GM
+    node_p = DF_tree.number_of_nodes() + 1
+    node_m = DF_tree.number_of_nodes() + 2
+    added_node = DF_tree.nodes[root]["CL"][0]
+
+    # adding the plus node
+    DF_tree.add_nodes_from([(node_p, deepcopy(DF_tree.nodes[root]))])
+    DF_tree.nodes[node_p]["GM"].append(added_node)
+    DF_tree.nodes[node_p]["GBC"] += DF_tree.nodes[node_p]["cont"][added_node]
+    root_node = DF_tree.nodes[root]
+    for x in nodes:
+        for y in nodes:
+            dxvy = 0
+            dxyv = 0
+            dvxy = 0
+            if not (
+                root_node["sigma"][x][y] == 0
+                or root_node["sigma"][x][added_node] == 0
+                or root_node["sigma"][added_node][y] == 0
+            ):
+                if D[x][added_node] == D[x][y] + D[y][added_node]:
+                    dxyv = (
+                        root_node["sigma"][x][y]
+                        * root_node["sigma"][y][added_node]
+                        / root_node["sigma"][x][added_node]
+                    )
+                if D[x][y] == D[x][added_node] + D[added_node][y]:
+                    dxvy = (
+                        root_node["sigma"][x][added_node]
+                        * root_node["sigma"][added_node][y]
+                        / root_node["sigma"][x][y]
+                    )
+                if D[added_node][y] == D[added_node][x] + D[x][y]:
+                    dvxy = (
+                        root_node["sigma"][added_node][x]
+                        * root_node["sigma"][x][y]
+                        / root_node["sigma"][added_node][y]
+                    )
+            DF_tree.nodes[node_p]["sigma"][x][y] = root_node["sigma"][x][y] * (1 - dxvy)
+            DF_tree.nodes[node_p]["betweenness"].loc[y, x] = (
+                root_node["betweenness"][x][y] - root_node["betweenness"][x][y] * dxvy
+            )
+            if y != added_node:
+                DF_tree.nodes[node_p]["betweenness"].loc[y, x] -= (
+                    root_node["betweenness"][x][added_node] * dxyv
+                )
+            if x != added_node:
+                DF_tree.nodes[node_p]["betweenness"].loc[y, x] -= (
+                    root_node["betweenness"][added_node][y] * dvxy
+                )
+
+    DF_tree.nodes[node_p]["CL"] = [
+        node
+        for _, node in sorted(
+            zip(np.diag(DF_tree.nodes[node_p]["betweenness"]), nodes), reverse=True
+        )
+        if node not in DF_tree.nodes[node_p]["GM"]
+    ]
+    DF_tree.nodes[node_p]["cont"] = dict(
+        zip(nodes, np.diag(DF_tree.nodes[node_p]["betweenness"]))
+    )
+    DF_tree.nodes[node_p]["heu"] = 0
+    for i in range(k - len(DF_tree.nodes[node_p]["GM"])):
+        DF_tree.nodes[node_p]["heu"] += DF_tree.nodes[node_p]["cont"][
+            DF_tree.nodes[node_p]["CL"][i]
+        ]
+
+    # adding the minus node - don't insert the first node in the CL to GM
+    # Insert minus node only if isn't greedy type algorithm
+    if not greedy:
+        DF_tree.add_nodes_from([(node_m, deepcopy(DF_tree.nodes[root]))])
+        DF_tree.nodes[node_m]["CL"].pop(0)
+        DF_tree.nodes[node_m]["cont"].pop(added_node)
+        DF_tree.nodes[node_m]["heu"] = 0
+        for i in range(k - len(DF_tree.nodes[node_m]["GM"])):
+            DF_tree.nodes[node_m]["heu"] += DF_tree.nodes[node_m]["cont"][
+                DF_tree.nodes[node_m]["CL"][i]
+            ]
+    else:
+        node_m = None
+
+    return node_p, node_m, DF_tree
+
+
+@nx._dispatchable(edge_attrs="weight")
+def group_closeness_centrality(G, S, weight=None):
+    r"""Compute the group closeness centrality for a group of nodes.
+
+    Group closeness centrality of a group of nodes $S$ is a measure
+    of how close the group is to the other nodes in the graph.
+
+    .. math::
+
+       c_{close}(S) = \frac{|V-S|}{\sum_{v \in V-S} d_{S, v}}
+
+       d_{S, v} = min_{u \in S} (d_{u, v})
+
+    where $V$ is the set of nodes, $d_{S, v}$ is the distance of
+    the group $S$ from $v$ defined as above. ($V-S$ is the set of nodes
+    in $V$ that are not in $S$).
+
+    Parameters
+    ----------
+    G : graph
+       A NetworkX graph.
+
+    S : list or set
+       S is a group of nodes which belong to G, for which group closeness
+       centrality is to be calculated.
+
+    weight : None or string, optional (default=None)
+       If None, all edge weights are considered equal.
+       Otherwise holds the name of the edge attribute used as weight.
+       The weight of an edge is treated as the length or distance between the two sides.
+
+    Raises
+    ------
+    NodeNotFound
+       If node(s) in S are not present in G.
+
+    Returns
+    -------
+    closeness : float
+       Group closeness centrality of the group S.
+
+    See Also
+    --------
+    closeness_centrality
+
+    Notes
+    -----
+    The measure was introduced in [1]_.
+    The formula implemented here is described in [2]_.
+
+    Higher values of closeness indicate greater centrality.
+
+    It is assumed that 1 / 0 is 0 (required in the case of directed graphs,
+    or when a shortest path length is 0).
+
+    The number of nodes in the group must be a maximum of n - 1 where `n`
+    is the total number of nodes in the graph.
+
+    For directed graphs, the incoming distance is utilized here. To use the
+    outward distance, act on `G.reverse()`.
+
+    For weighted graphs the edge weights must be greater than zero.
+    Zero edge weights can produce an infinite number of equal length
+    paths between pairs of nodes.
+
+    References
+    ----------
+    .. [1] M G Everett and S P Borgatti:
+       The Centrality of Groups and Classes.
+       Journal of Mathematical Sociology. 23(3): 181-201. 1999.
+       http://www.analytictech.com/borgatti/group_centrality.htm
+    .. [2] J. Zhao et. al.:
+       Measuring and Maximizing Group Closeness Centrality over
+       Disk Resident Graphs.
+       WWWConference Proceedings, 2014. 689-694.
+       https://doi.org/10.1145/2567948.2579356
+    """
+    if G.is_directed():
+        G = G.reverse()  # reverse view
+    closeness = 0  # initialize to 0
+    V = set(G)  # set of nodes in G
+    S = set(S)  # set of nodes in group S
+    V_S = V - S  # set of nodes in V but not S
+    shortest_path_lengths = nx.multi_source_dijkstra_path_length(G, S, weight=weight)
+    # accumulation
+    for v in V_S:
+        try:
+            closeness += shortest_path_lengths[v]
+        except KeyError:  # no path exists
+            closeness += 0
+    try:
+        closeness = len(V_S) / closeness
+    except ZeroDivisionError:  # 1 / 0 assumed as 0
+        closeness = 0
+    return closeness
+
+
+@nx._dispatchable
+def group_degree_centrality(G, S):
+    """Compute the group degree centrality for a group of nodes.
+
+    Group degree centrality of a group of nodes $S$ is the fraction
+    of non-group members connected to group members.
+
+    Parameters
+    ----------
+    G : graph
+       A NetworkX graph.
+
+    S : list or set
+       S is a group of nodes which belong to G, for which group degree
+       centrality is to be calculated.
+
+    Raises
+    ------
+    NetworkXError
+       If node(s) in S are not in G.
+
+    Returns
+    -------
+    centrality : float
+       Group degree centrality of the group S.
+
+    See Also
+    --------
+    degree_centrality
+    group_in_degree_centrality
+    group_out_degree_centrality
+
+    Notes
+    -----
+    The measure was introduced in [1]_.
+
+    The number of nodes in the group must be a maximum of n - 1 where `n`
+    is the total number of nodes in the graph.
+
+    References
+    ----------
+    .. [1] M G Everett and S P Borgatti:
+       The Centrality of Groups and Classes.
+       Journal of Mathematical Sociology. 23(3): 181-201. 1999.
+       http://www.analytictech.com/borgatti/group_centrality.htm
+    """
+    centrality = len(set().union(*[set(G.neighbors(i)) for i in S]) - set(S))
+    centrality /= len(G.nodes()) - len(S)
+    return centrality
+
+
+@not_implemented_for("undirected")
+@nx._dispatchable
+def group_in_degree_centrality(G, S):
+    """Compute the group in-degree centrality for a group of nodes.
+
+    Group in-degree centrality of a group of nodes $S$ is the fraction
+    of non-group members connected to group members by incoming edges.
+
+    Parameters
+    ----------
+    G : graph
+       A NetworkX graph.
+
+    S : list or set
+       S is a group of nodes which belong to G, for which group in-degree
+       centrality is to be calculated.
+
+    Returns
+    -------
+    centrality : float
+       Group in-degree centrality of the group S.
+
+    Raises
+    ------
+    NetworkXNotImplemented
+       If G is undirected.
+
+    NodeNotFound
+       If node(s) in S are not in G.
+
+    See Also
+    --------
+    degree_centrality
+    group_degree_centrality
+    group_out_degree_centrality
+
+    Notes
+    -----
+    The number of nodes in the group must be a maximum of n - 1 where `n`
+    is the total number of nodes in the graph.
+
+    `G.neighbors(i)` gives nodes with an outward edge from i, in a DiGraph,
+    so for group in-degree centrality, the reverse graph is used.
+    """
+    return group_degree_centrality(G.reverse(), S)
+
+
+@not_implemented_for("undirected")
+@nx._dispatchable
+def group_out_degree_centrality(G, S):
+    """Compute the group out-degree centrality for a group of nodes.
+
+    Group out-degree centrality of a group of nodes $S$ is the fraction
+    of non-group members connected to group members by outgoing edges.
+
+    Parameters
+    ----------
+    G : graph
+       A NetworkX graph.
+
+    S : list or set
+       S is a group of nodes which belong to G, for which group in-degree
+       centrality is to be calculated.
+
+    Returns
+    -------
+    centrality : float
+       Group out-degree centrality of the group S.
+
+    Raises
+    ------
+    NetworkXNotImplemented
+       If G is undirected.
+
+    NodeNotFound
+       If node(s) in S are not in G.
+
+    See Also
+    --------
+    degree_centrality
+    group_degree_centrality
+    group_in_degree_centrality
+
+    Notes
+    -----
+    The number of nodes in the group must be a maximum of n - 1 where `n`
+    is the total number of nodes in the graph.
+
+    `G.neighbors(i)` gives nodes with an outward edge from i, in a DiGraph,
+    so for group out-degree centrality, the graph itself is used.
+    """
+    return group_degree_centrality(G, S)

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/katz.py

@@ -0,0 +1,331 @@
+"""Katz centrality."""
+
+import math
+
+import networkx as nx
+from networkx.utils import not_implemented_for
+
+__all__ = ["katz_centrality", "katz_centrality_numpy"]
+
+
+@not_implemented_for("multigraph")
+@nx._dispatchable(edge_attrs="weight")
+def katz_centrality(
+    G,
+    alpha=0.1,
+    beta=1.0,
+    max_iter=1000,
+    tol=1.0e-6,
+    nstart=None,
+    normalized=True,
+    weight=None,
+):
+    r"""Compute the Katz centrality for the nodes of the graph G.
+
+    Katz centrality computes the centrality for a node based on the centrality
+    of its neighbors. It is a generalization of the eigenvector centrality. The
+    Katz centrality for node $i$ is
+
+    .. math::
+
+        x_i = \alpha \sum_{j} A_{ij} x_j + \beta,
+
+    where $A$ is the adjacency matrix of graph G with eigenvalues $\lambda$.
+
+    The parameter $\beta$ controls the initial centrality and
+
+    .. math::
+
+        \alpha < \frac{1}{\lambda_{\max}}.
+
+    Katz centrality computes the relative influence of a node within a
+    network by measuring the number of the immediate neighbors (first
+    degree nodes) and also all other nodes in the network that connect
+    to the node under consideration through these immediate neighbors.
+
+    Extra weight can be provided to immediate neighbors through the
+    parameter $\beta$.  Connections made with distant neighbors
+    are, however, penalized by an attenuation factor $\alpha$ which
+    should be strictly less than the inverse largest eigenvalue of the
+    adjacency matrix in order for the Katz centrality to be computed
+    correctly. More information is provided in [1]_.
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph.
+
+    alpha : float, optional (default=0.1)
+      Attenuation factor
+
+    beta : scalar or dictionary, optional (default=1.0)
+      Weight attributed to the immediate neighborhood. If not a scalar, the
+      dictionary must have a value for every node.
+
+    max_iter : integer, optional (default=1000)
+      Maximum number of iterations in power method.
+
+    tol : float, optional (default=1.0e-6)
+      Error tolerance used to check convergence in power method iteration.
+
+    nstart : dictionary, optional
+      Starting value of Katz iteration for each node.
+
+    normalized : bool, optional (default=True)
+      If True normalize the resulting values.
+
+    weight : None or string, optional (default=None)
+      If None, all edge weights are considered equal.
+      Otherwise holds the name of the edge attribute used as weight.
+      In this measure the weight is interpreted as the connection strength.
+
+    Returns
+    -------
+    nodes : dictionary
+       Dictionary of nodes with Katz centrality as the value.
+
+    Raises
+    ------
+    NetworkXError
+       If the parameter `beta` is not a scalar but lacks a value for at least
+       one node
+
+    PowerIterationFailedConvergence
+        If the algorithm fails to converge to the specified tolerance
+        within the specified number of iterations of the power iteration
+        method.
+
+    Examples
+    --------
+    >>> import math
+    >>> G = nx.path_graph(4)
+    >>> phi = (1 + math.sqrt(5)) / 2.0  # largest eigenvalue of adj matrix
+    >>> centrality = nx.katz_centrality(G, 1 / phi - 0.01)
+    >>> for n, c in sorted(centrality.items()):
+    ...     print(f"{n} {c:.2f}")
+    0 0.37
+    1 0.60
+    2 0.60
+    3 0.37
+
+    See Also
+    --------
+    katz_centrality_numpy
+    eigenvector_centrality
+    eigenvector_centrality_numpy
+    :func:`~networkx.algorithms.link_analysis.pagerank_alg.pagerank`
+    :func:`~networkx.algorithms.link_analysis.hits_alg.hits`
+
+    Notes
+    -----
+    Katz centrality was introduced by [2]_.
+
+    This algorithm it uses the power method to find the eigenvector
+    corresponding to the largest eigenvalue of the adjacency matrix of ``G``.
+    The parameter ``alpha`` should be strictly less than the inverse of largest
+    eigenvalue of the adjacency matrix for the algorithm to converge.
+    You can use ``max(nx.adjacency_spectrum(G))`` to get $\lambda_{\max}$ the largest
+    eigenvalue of the adjacency matrix.
+    The iteration will stop after ``max_iter`` iterations or an error tolerance of
+    ``number_of_nodes(G) * tol`` has been reached.
+
+    For strongly connected graphs, as $\alpha \to 1/\lambda_{\max}$, and $\beta > 0$,
+    Katz centrality approaches the results for eigenvector centrality.
+
+    For directed graphs this finds "left" eigenvectors which corresponds
+    to the in-edges in the graph. For out-edges Katz centrality,
+    first reverse the graph with ``G.reverse()``.
+
+    References
+    ----------
+    .. [1] Mark E. J. Newman:
+       Networks: An Introduction.
+       Oxford University Press, USA, 2010, p. 720.
+    .. [2] Leo Katz:
+       A New Status Index Derived from Sociometric Index.
+       Psychometrika 18(1):39–43, 1953
+       https://link.springer.com/content/pdf/10.1007/BF02289026.pdf
+    """
+    if len(G) == 0:
+        return {}
+
+    nnodes = G.number_of_nodes()
+
+    if nstart is None:
+        # choose starting vector with entries of 0
+        x = {n: 0 for n in G}
+    else:
+        x = nstart
+
+    try:
+        b = dict.fromkeys(G, float(beta))
+    except (TypeError, ValueError, AttributeError) as err:
+        b = beta
+        if set(beta) != set(G):
+            raise nx.NetworkXError(
+                "beta dictionary must have a value for every node"
+            ) from err
+
+    # make up to max_iter iterations
+    for _ in range(max_iter):
+        xlast = x
+        x = dict.fromkeys(xlast, 0)
+        # do the multiplication y^T = Alpha * x^T A + Beta
+        for n in x:
+            for nbr in G[n]:
+                x[nbr] += xlast[n] * G[n][nbr].get(weight, 1)
+        for n in x:
+            x[n] = alpha * x[n] + b[n]
+
+        # check convergence
+        error = sum(abs(x[n] - xlast[n]) for n in x)
+        if error < nnodes * tol:
+            if normalized:
+                # normalize vector
+                try:
+                    s = 1.0 / math.hypot(*x.values())
+                except ZeroDivisionError:
+                    s = 1.0
+            else:
+                s = 1
+            for n in x:
+                x[n] *= s
+            return x
+    raise nx.PowerIterationFailedConvergence(max_iter)
+
+
+@not_implemented_for("multigraph")
+@nx._dispatchable(edge_attrs="weight")
+def katz_centrality_numpy(G, alpha=0.1, beta=1.0, normalized=True, weight=None):
+    r"""Compute the Katz centrality for the graph G.
+
+    Katz centrality computes the centrality for a node based on the centrality
+    of its neighbors. It is a generalization of the eigenvector centrality. The
+    Katz centrality for node $i$ is
+
+    .. math::
+
+        x_i = \alpha \sum_{j} A_{ij} x_j + \beta,
+
+    where $A$ is the adjacency matrix of graph G with eigenvalues $\lambda$.
+
+    The parameter $\beta$ controls the initial centrality and
+
+    .. math::
+
+        \alpha < \frac{1}{\lambda_{\max}}.
+
+    Katz centrality computes the relative influence of a node within a
+    network by measuring the number of the immediate neighbors (first
+    degree nodes) and also all other nodes in the network that connect
+    to the node under consideration through these immediate neighbors.
+
+    Extra weight can be provided to immediate neighbors through the
+    parameter $\beta$.  Connections made with distant neighbors
+    are, however, penalized by an attenuation factor $\alpha$ which
+    should be strictly less than the inverse largest eigenvalue of the
+    adjacency matrix in order for the Katz centrality to be computed
+    correctly. More information is provided in [1]_.
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph
+
+    alpha : float
+      Attenuation factor
+
+    beta : scalar or dictionary, optional (default=1.0)
+      Weight attributed to the immediate neighborhood. If not a scalar the
+      dictionary must have an value for every node.
+
+    normalized : bool
+      If True normalize the resulting values.
+
+    weight : None or string, optional
+      If None, all edge weights are considered equal.
+      Otherwise holds the name of the edge attribute used as weight.
+      In this measure the weight is interpreted as the connection strength.
+
+    Returns
+    -------
+    nodes : dictionary
+       Dictionary of nodes with Katz centrality as the value.
+
+    Raises
+    ------
+    NetworkXError
+       If the parameter `beta` is not a scalar but lacks a value for at least
+       one node
+
+    Examples
+    --------
+    >>> import math
+    >>> G = nx.path_graph(4)
+    >>> phi = (1 + math.sqrt(5)) / 2.0  # largest eigenvalue of adj matrix
+    >>> centrality = nx.katz_centrality_numpy(G, 1 / phi)
+    >>> for n, c in sorted(centrality.items()):
+    ...     print(f"{n} {c:.2f}")
+    0 0.37
+    1 0.60
+    2 0.60
+    3 0.37
+
+    See Also
+    --------
+    katz_centrality
+    eigenvector_centrality_numpy
+    eigenvector_centrality
+    :func:`~networkx.algorithms.link_analysis.pagerank_alg.pagerank`
+    :func:`~networkx.algorithms.link_analysis.hits_alg.hits`
+
+    Notes
+    -----
+    Katz centrality was introduced by [2]_.
+
+    This algorithm uses a direct linear solver to solve the above equation.
+    The parameter ``alpha`` should be strictly less than the inverse of largest
+    eigenvalue of the adjacency matrix for there to be a solution.
+    You can use ``max(nx.adjacency_spectrum(G))`` to get $\lambda_{\max}$ the largest
+    eigenvalue of the adjacency matrix.
+
+    For strongly connected graphs, as $\alpha \to 1/\lambda_{\max}$, and $\beta > 0$,
+    Katz centrality approaches the results for eigenvector centrality.
+
+    For directed graphs this finds "left" eigenvectors which corresponds
+    to the in-edges in the graph. For out-edges Katz centrality,
+    first reverse the graph with ``G.reverse()``.
+
+    References
+    ----------
+    .. [1] Mark E. J. Newman:
+       Networks: An Introduction.
+       Oxford University Press, USA, 2010, p. 173.
+    .. [2] Leo Katz:
+       A New Status Index Derived from Sociometric Index.
+       Psychometrika 18(1):39–43, 1953
+       https://link.springer.com/content/pdf/10.1007/BF02289026.pdf
+    """
+    import numpy as np
+
+    if len(G) == 0:
+        return {}
+    try:
+        nodelist = beta.keys()
+        if set(nodelist) != set(G):
+            raise nx.NetworkXError("beta dictionary must have a value for every node")
+        b = np.array(list(beta.values()), dtype=float)
+    except AttributeError:
+        nodelist = list(G)
+        try:
+            b = np.ones((len(nodelist), 1)) * beta
+        except (TypeError, ValueError, AttributeError) as err:
+            raise nx.NetworkXError("beta must be a number") from err
+
+    A = nx.adjacency_matrix(G, nodelist=nodelist, weight=weight).todense().T
+    n = A.shape[0]
+    centrality = np.linalg.solve(np.eye(n, n) - (alpha * A), b).squeeze()
+
+    # Normalize: rely on truediv to cast to float, then tolist to make Python numbers
+    norm = np.sign(sum(centrality)) * np.linalg.norm(centrality) if normalized else 1
+    return dict(zip(nodelist, (centrality / norm).tolist()))

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/percolation.py

@@ -0,0 +1,128 @@
+"""Percolation centrality measures."""
+
+import networkx as nx
+from networkx.algorithms.centrality.betweenness import (
+    _single_source_dijkstra_path_basic as dijkstra,
+)
+from networkx.algorithms.centrality.betweenness import (
+    _single_source_shortest_path_basic as shortest_path,
+)
+
+__all__ = ["percolation_centrality"]
+
+
+@nx._dispatchable(node_attrs="attribute", edge_attrs="weight")
+def percolation_centrality(G, attribute="percolation", states=None, weight=None):
+    r"""Compute the percolation centrality for nodes.
+
+    Percolation centrality of a node $v$, at a given time, is defined
+    as the proportion of ‘percolated paths’ that go through that node.
+
+    This measure quantifies relative impact of nodes based on their
+    topological connectivity, as well as their percolation states.
+
+    Percolation states of nodes are used to depict network percolation
+    scenarios (such as during infection transmission in a social network
+    of individuals, spreading of computer viruses on computer networks, or
+    transmission of disease over a network of towns) over time. In this
+    measure usually the percolation state is expressed as a decimal
+    between 0.0 and 1.0.
+
+    When all nodes are in the same percolated state this measure is
+    equivalent to betweenness centrality.
+
+    Parameters
+    ----------
+    G : graph
+      A NetworkX graph.
+
+    attribute : None or string, optional (default='percolation')
+      Name of the node attribute to use for percolation state, used
+      if `states` is None. If a node does not set the attribute the
+      state of that node will be set to the default value of 1.
+      If all nodes do not have the attribute all nodes will be set to
+      1 and the centrality measure will be equivalent to betweenness centrality.
+
+    states : None or dict, optional (default=None)
+      Specify percolation states for the nodes, nodes as keys states
+      as values.
+
+    weight : None or string, optional (default=None)
+      If None, all edge weights are considered equal.
+      Otherwise holds the name of the edge attribute used as weight.
+      The weight of an edge is treated as the length or distance between the two sides.
+
+
+    Returns
+    -------
+    nodes : dictionary
+       Dictionary of nodes with percolation centrality as the value.
+
+    See Also
+    --------
+    betweenness_centrality
+
+    Notes
+    -----
+    The algorithm is from Mahendra Piraveenan, Mikhail Prokopenko, and
+    Liaquat Hossain [1]_
+    Pair dependencies are calculated and accumulated using [2]_
+
+    For weighted graphs the edge weights must be greater than zero.
+    Zero edge weights can produce an infinite number of equal length
+    paths between pairs of nodes.
+
+    References
+    ----------
+    .. [1] Mahendra Piraveenan, Mikhail Prokopenko, Liaquat Hossain
+       Percolation Centrality: Quantifying Graph-Theoretic Impact of Nodes
+       during Percolation in Networks
+       http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0053095
+    .. [2] Ulrik Brandes:
+       A Faster Algorithm for Betweenness Centrality.
+       Journal of Mathematical Sociology 25(2):163-177, 2001.
+       https://doi.org/10.1080/0022250X.2001.9990249
+    """
+    percolation = dict.fromkeys(G, 0.0)  # b[v]=0 for v in G
+
+    nodes = G
+
+    if states is None:
+        states = nx.get_node_attributes(nodes, attribute, default=1)
+
+    # sum of all percolation states
+    p_sigma_x_t = 0.0
+    for v in states.values():
+        p_sigma_x_t += v
+
+    for s in nodes:
+        # single source shortest paths
+        if weight is None:  # use BFS
+            S, P, sigma, _ = shortest_path(G, s)
+        else:  # use Dijkstra's algorithm
+            S, P, sigma, _ = dijkstra(G, s, weight)
+        # accumulation
+        percolation = _accumulate_percolation(
+            percolation, S, P, sigma, s, states, p_sigma_x_t
+        )
+
+    n = len(G)
+
+    for v in percolation:
+        percolation[v] *= 1 / (n - 2)
+
+    return percolation
+
+
+def _accumulate_percolation(percolation, S, P, sigma, s, states, p_sigma_x_t):
+    delta = dict.fromkeys(S, 0)
+    while S:
+        w = S.pop()
+        coeff = (1 + delta[w]) / sigma[w]
+        for v in P[w]:
+            delta[v] += sigma[v] * coeff
+        if w != s:
+            # percolation weight
+            pw_s_w = states[s] / (p_sigma_x_t - states[w])
+            percolation[w] += delta[w] * pw_s_w
+    return percolation

.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/subgraph_alg.py

@@ -0,0 +1,340 @@
+"""
+Subraph centrality and communicability betweenness.
+"""
+
+import networkx as nx
+from networkx.utils import not_implemented_for
+
+__all__ = [
+    "subgraph_centrality_exp",
+    "subgraph_centrality",
+    "communicability_betweenness_centrality",
+    "estrada_index",
+]
+
+
+@not_implemented_for("directed")
+@not_implemented_for("multigraph")
+@nx._dispatchable
+def subgraph_centrality_exp(G):
+    r"""Returns the subgraph centrality for each node of G.
+
+    Subgraph centrality  of a node `n` is the sum of weighted closed
+    walks of all lengths starting and ending at node `n`. The weights
+    decrease with path length. Each closed walk is associated with a
+    connected subgraph ([1]_).
+
+    Parameters
+    ----------
+    G: graph
+
+    Returns
+    -------
+    nodes:dictionary
+        Dictionary of nodes with subgraph centrality as the value.
+
+    Raises
+    ------
+    NetworkXError
+        If the graph is not undirected and simple.
+
+    See Also
+    --------
+    subgraph_centrality:
+        Alternative algorithm of the subgraph centrality for each node of G.
+
+    Notes
+    -----
+    This version of the algorithm exponentiates the adjacency matrix.
+
+    The subgraph centrality of a node `u` in G can be found using
+    the matrix exponential of the adjacency matrix of G [1]_,
+
+    .. math::
+
+        SC(u)=(e^A)_{uu} .
+
+    References
+    ----------
+    .. [1] Ernesto Estrada, Juan A. Rodriguez-Velazquez,
+       "Subgraph centrality in complex networks",
+       Physical Review E 71, 056103 (2005).
+       https://arxiv.org/abs/cond-mat/0504730
+
+    Examples
+    --------
+    (Example from [1]_)
+    >>> G = nx.Graph(
+    ...     [
+    ...         (1, 2),
+    ...         (1, 5),
+    ...         (1, 8),
+    ...         (2, 3),
+    ...         (2, 8),
+    ...         (3, 4),
+    ...         (3, 6),
+    ...         (4, 5),
+    ...         (4, 7),
+    ...         (5, 6),
+    ...         (6, 7),
+    ...         (7, 8),
+    ...     ]
+    ... )
+    >>> sc = nx.subgraph_centrality_exp(G)
+    >>> print([f"{node} {sc[node]:0.2f}" for node in sorted(sc)])
+    ['1 3.90', '2 3.90', '3 3.64', '4 3.71', '5 3.64', '6 3.71', '7 3.64', '8 3.90']
+    """
+    # alternative implementation that calculates the matrix exponential
+    import scipy as sp
+
+    nodelist = list(G)  # ordering of nodes in matrix
+    A = nx.to_numpy_array(G, nodelist)
+    # convert to 0-1 matrix
+    A[A != 0.0] = 1
+    expA = sp.linalg.expm(A)
+    # convert diagonal to dictionary keyed by node
+    sc = dict(zip(nodelist, map(float, expA.diagonal())))
+    return sc
+
+
+@not_implemented_for("directed")
+@not_implemented_for("multigraph")
+@nx._dispatchable
+def subgraph_centrality(G):
+    r"""Returns subgraph centrality for each node in G.
+
+    Subgraph centrality  of a node `n` is the sum of weighted closed
+    walks of all lengths starting and ending at node `n`. The weights
+    decrease with path length. Each closed walk is associated with a
+    connected subgraph ([1]_).
+
+    Parameters
+    ----------
+    G: graph
+
+    Returns
+    -------
+    nodes : dictionary
+       Dictionary of nodes with subgraph centrality as the value.
+
+    Raises
+    ------
+    NetworkXError
+       If the graph is not undirected and simple.
+
+    See Also
+    --------
+    subgraph_centrality_exp:
+        Alternative algorithm of the subgraph centrality for each node of G.
+
+    Notes
+    -----
+    This version of the algorithm computes eigenvalues and eigenvectors
+    of the adjacency matrix.
+
+    Subgraph centrality of a node `u` in G can be found using
+    a spectral decomposition of the adjacency matrix [1]_,
+
+    .. math::
+
+       SC(u)=\sum_{j=1}^{N}(v_{j}^{u})^2 e^{\lambda_{j}},
+
+    where `v_j` is an eigenvector of the adjacency matrix `A` of G
+    corresponding to the eigenvalue `\lambda_j`.
+
+    Examples
+    --------
+    (Example from [1]_)
+    >>> G = nx.Graph(
+    ...     [
+    ...         (1, 2),
+    ...         (1, 5),
+    ...         (1, 8),
+    ...         (2, 3),
+    ...         (2, 8),
+    ...         (3, 4),
+    ...         (3, 6),
+    ...         (4, 5),
+    ...         (4, 7),
+    ...         (5, 6),
+    ...         (6, 7),
+    ...         (7, 8),
+    ...     ]
+    ... )
+    >>> sc = nx.subgraph_centrality(G)
+    >>> print([f"{node} {sc[node]:0.2f}" for node in sorted(sc)])
+    ['1 3.90', '2 3.90', '3 3.64', '4 3.71', '5 3.64', '6 3.71', '7 3.64', '8 3.90']
+
+    References
+    ----------
+    .. [1] Ernesto Estrada, Juan A. Rodriguez-Velazquez,
+       "Subgraph centrality in complex networks",
+       Physical Review E 71, 056103 (2005).
+       https://arxiv.org/abs/cond-mat/0504730
+
+    """
+    import numpy as np
+
+    nodelist = list(G)  # ordering of nodes in matrix
+    A = nx.to_numpy_array(G, nodelist)
+    # convert to 0-1 matrix
+    A[np.nonzero(A)] = 1
+    w, v = np.linalg.eigh(A)
+    vsquare = np.array(v) ** 2
+    expw = np.exp(w)
+    xg = vsquare @ expw
+    # convert vector dictionary keyed by node
+    sc = dict(zip(nodelist, map(float, xg)))
+    return sc
+
+
+@not_implemented_for("directed")
+@not_implemented_for("multigraph")
+@nx._dispatchable
+def communicability_betweenness_centrality(G):
+    r"""Returns subgraph communicability for all pairs of nodes in G.
+
+    Communicability betweenness measure makes use of the number of walks
+    connecting every pair of nodes as the basis of a betweenness centrality
+    measure.
+
+    Parameters
+    ----------
+    G: graph
+
+    Returns
+    -------
+    nodes : dictionary
+        Dictionary of nodes with communicability betweenness as the value.
+
+    Raises
+    ------
+    NetworkXError
+        If the graph is not undirected and simple.
+
+    Notes
+    -----
+    Let `G=(V,E)` be a simple undirected graph with `n` nodes and `m` edges,
+    and `A` denote the adjacency matrix of `G`.
+
+    Let `G(r)=(V,E(r))` be the graph resulting from
+    removing all edges connected to node `r` but not the node itself.
+
+    The adjacency matrix for `G(r)` is `A+E(r)`,  where `E(r)` has nonzeros
+    only in row and column `r`.
+
+    The subraph betweenness of a node `r`  is [1]_
+
+    .. math::
+
+         \omega_{r} = \frac{1}{C}\sum_{p}\sum_{q}\frac{G_{prq}}{G_{pq}},
+         p\neq q, q\neq r,
+
+    where
+    `G_{prq}=(e^{A}_{pq} - (e^{A+E(r)})_{pq}`  is the number of walks
+    involving node r,
+    `G_{pq}=(e^{A})_{pq}` is the number of closed walks starting
+    at node `p` and ending at node `q`,
+    and `C=(n-1)^{2}-(n-1)` is a normalization factor equal to the
+    number of terms in the sum.
+
+    The resulting `\omega_{r}` takes values between zero and one.
+    The lower bound cannot be attained for a connected
+    graph, and the upper bound is attained in the star graph.
+
+    References
+    ----------
+    .. [1] Ernesto Estrada, Desmond J. Higham, Naomichi Hatano,
+       "Communicability Betweenness in Complex Networks"
+       Physica A 388 (2009) 764-774.
+       https://arxiv.org/abs/0905.4102
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (1, 2), (1, 5), (5, 4), (2, 4), (2, 3), (4, 3), (3, 6)])
+    >>> cbc = nx.communicability_betweenness_centrality(G)
+    >>> print([f"{node} {cbc[node]:0.2f}" for node in sorted(cbc)])
+    ['0 0.03', '1 0.45', '2 0.51', '3 0.45', '4 0.40', '5 0.19', '6 0.03']
+    """
+    import numpy as np
+    import scipy as sp
+
+    nodelist = list(G)  # ordering of nodes in matrix
+    n = len(nodelist)
+    A = nx.to_numpy_array(G, nodelist)
+    # convert to 0-1 matrix
+    A[np.nonzero(A)] = 1
+    expA = sp.linalg.expm(A)
+    mapping = dict(zip(nodelist, range(n)))
+    cbc = {}
+    for v in G:
+        # remove row and col of node v
+        i = mapping[v]
+        row = A[i, :].copy()
+        col = A[:, i].copy()
+        A[i, :] = 0
+        A[:, i] = 0
+        B = (expA - sp.linalg.expm(A)) / expA
+        # sum with row/col of node v and diag set to zero
+        B[i, :] = 0
+        B[:, i] = 0
+        B -= np.diag(np.diag(B))
+        cbc[v] = float(B.sum())
+        # put row and col back
+        A[i, :] = row
+        A[:, i] = col
+    # rescale when more than two nodes
+    order = len(cbc)
+    if order > 2:
+        scale = 1.0 / ((order - 1.0) ** 2 - (order - 1.0))
+        cbc = {node: value * scale for node, value in cbc.items()}
+    return cbc
+
+
+@nx._dispatchable
+def estrada_index(G):
+    r"""Returns the Estrada index of a the graph G.
+
+    The Estrada Index is a topological index of folding or 3D "compactness" ([1]_).
+
+    Parameters
+    ----------
+    G: graph
+
+    Returns
+    -------
+    estrada index: float
+
+    Raises
+    ------
+    NetworkXError
+        If the graph is not undirected and simple.
+
+    Notes
+    -----
+    Let `G=(V,E)` be a simple undirected graph with `n` nodes  and let
+    `\lambda_{1}\leq\lambda_{2}\leq\cdots\lambda_{n}`
+    be a non-increasing ordering of the eigenvalues of its adjacency
+    matrix `A`. The Estrada index is ([1]_, [2]_)
+
+    .. math::
+        EE(G)=\sum_{j=1}^n e^{\lambda _j}.
+
+    References
+    ----------
+    .. [1] E. Estrada, "Characterization of 3D molecular structure",
+       Chem. Phys. Lett. 319, 713 (2000).
+       https://doi.org/10.1016/S0009-2614(00)00158-5
+    .. [2] José Antonio de la Peñaa, Ivan Gutman, Juan Rada,
+       "Estimating the Estrada index",
+       Linear Algebra and its Applications. 427, 1 (2007).
+       https://doi.org/10.1016/j.laa.2007.06.020
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (1, 2), (1, 5), (5, 4), (2, 4), (2, 3), (4, 3), (3, 6)])
+    >>> ei = nx.estrada_index(G)
+    >>> print(f"{ei:0.5}")
+    20.55
+    """
+    return sum(subgraph_centrality(G).values())

.venv/lib/python3.11/site-packages/networkx/algorithms/coloring/__init__.py

@@ -0,0 +1,4 @@
+from networkx.algorithms.coloring.greedy_coloring import *
+from networkx.algorithms.coloring.equitable_coloring import equitable_color
+
+__all__ = ["greedy_color", "equitable_color"]

.venv/lib/python3.11/site-packages/networkx/algorithms/coloring/equitable_coloring.py

@@ -0,0 +1,505 @@
+"""
+Equitable coloring of graphs with bounded degree.
+"""
+
+from collections import defaultdict
+
+import networkx as nx
+
+__all__ = ["equitable_color"]
+
+
+@nx._dispatchable
+def is_coloring(G, coloring):
+    """Determine if the coloring is a valid coloring for the graph G."""
+    # Verify that the coloring is valid.
+    return all(coloring[s] != coloring[d] for s, d in G.edges)
+
+
+@nx._dispatchable
+def is_equitable(G, coloring, num_colors=None):
+    """Determines if the coloring is valid and equitable for the graph G."""
+
+    if not is_coloring(G, coloring):
+        return False
+
+    # Verify whether it is equitable.
+    color_set_size = defaultdict(int)
+    for color in coloring.values():
+        color_set_size[color] += 1
+
+    if num_colors is not None:
+        for color in range(num_colors):
+            if color not in color_set_size:
+                # These colors do not have any vertices attached to them.
+                color_set_size[color] = 0
+
+    # If there are more than 2 distinct values, the coloring cannot be equitable
+    all_set_sizes = set(color_set_size.values())
+    if len(all_set_sizes) == 0 and num_colors is None:  # Was an empty graph
+        return True
+    elif len(all_set_sizes) == 1:
+        return True
+    elif len(all_set_sizes) == 2:
+        a, b = list(all_set_sizes)
+        return abs(a - b) <= 1
+    else:  # len(all_set_sizes) > 2:
+        return False
+
+
+def make_C_from_F(F):
+    C = defaultdict(list)
+    for node, color in F.items():
+        C[color].append(node)
+
+    return C
+
+
+def make_N_from_L_C(L, C):
+    nodes = L.keys()
+    colors = C.keys()
+    return {
+        (node, color): sum(1 for v in L[node] if v in C[color])
+        for node in nodes
+        for color in colors
+    }
+
+
+def make_H_from_C_N(C, N):
+    return {
+        (c1, c2): sum(1 for node in C[c1] if N[(node, c2)] == 0) for c1 in C for c2 in C
+    }
+
+
+def change_color(u, X, Y, N, H, F, C, L):
+    """Change the color of 'u' from X to Y and update N, H, F, C."""
+    assert F[u] == X and X != Y
+
+    # Change the class of 'u' from X to Y
+    F[u] = Y
+
+    for k in C:
+        # 'u' witnesses an edge from k -> Y instead of from k -> X now.
+        if N[u, k] == 0:
+            H[(X, k)] -= 1
+            H[(Y, k)] += 1
+
+    for v in L[u]:
+        # 'v' has lost a neighbor in X and gained one in Y
+        N[(v, X)] -= 1
+        N[(v, Y)] += 1
+
+        if N[(v, X)] == 0:
+            # 'v' witnesses F[v] -> X
+            H[(F[v], X)] += 1
+
+        if N[(v, Y)] == 1:
+            # 'v' no longer witnesses F[v] -> Y
+            H[(F[v], Y)] -= 1
+
+    C[X].remove(u)
+    C[Y].append(u)
+
+
+def move_witnesses(src_color, dst_color, N, H, F, C, T_cal, L):
+    """Move witness along a path from src_color to dst_color."""
+    X = src_color
+    while X != dst_color:
+        Y = T_cal[X]
+        # Move _any_ witness from X to Y = T_cal[X]
+        w = next(x for x in C[X] if N[(x, Y)] == 0)
+        change_color(w, X, Y, N=N, H=H, F=F, C=C, L=L)
+        X = Y
+
+
+@nx._dispatchable(mutates_input=True)
+def pad_graph(G, num_colors):
+    """Add a disconnected complete clique K_p such that the number of nodes in
+    the graph becomes a multiple of `num_colors`.
+
+    Assumes that the graph's nodes are labelled using integers.
+
+    Returns the number of nodes with each color.
+    """
+
+    n_ = len(G)
+    r = num_colors - 1
+
+    # Ensure that the number of nodes in G is a multiple of (r + 1)
+    s = n_ // (r + 1)
+    if n_ != s * (r + 1):
+        p = (r + 1) - n_ % (r + 1)
+        s += 1
+
+        # Complete graph K_p between (imaginary) nodes [n_, ... , n_ + p]
+        K = nx.relabel_nodes(nx.complete_graph(p), {idx: idx + n_ for idx in range(p)})
+        G.add_edges_from(K.edges)
+
+    return s
+
+
+def procedure_P(V_minus, V_plus, N, H, F, C, L, excluded_colors=None):
+    """Procedure P as described in the paper."""
+
+    if excluded_colors is None:
+        excluded_colors = set()
+
+    A_cal = set()
+    T_cal = {}
+    R_cal = []
+
+    # BFS to determine A_cal, i.e. colors reachable from V-
+    reachable = [V_minus]
+    marked = set(reachable)
+    idx = 0
+
+    while idx < len(reachable):
+        pop = reachable[idx]
+        idx += 1
+
+        A_cal.add(pop)
+        R_cal.append(pop)
+
+        # TODO: Checking whether a color has been visited can be made faster by
+        # using a look-up table instead of testing for membership in a set by a
+        # logarithmic factor.
+        next_layer = []
+        for k in C:
+            if (
+                H[(k, pop)] > 0
+                and k not in A_cal
+                and k not in excluded_colors
+                and k not in marked
+            ):
+                next_layer.append(k)
+
+        for dst in next_layer:
+            # Record that `dst` can reach `pop`
+            T_cal[dst] = pop
+
+        marked.update(next_layer)
+        reachable.extend(next_layer)
+
+    # Variables for the algorithm
+    b = len(C) - len(A_cal)
+
+    if V_plus in A_cal:
+        # Easy case: V+ is in A_cal
+        # Move one node from V+ to V- using T_cal to find the parents.
+        move_witnesses(V_plus, V_minus, N=N, H=H, F=F, C=C, T_cal=T_cal, L=L)
+    else:
+        # If there is a solo edge, we can resolve the situation by
+        # moving witnesses from B to A, making G[A] equitable and then
+        # recursively balancing G[B - w] with a different V_minus and
+        # but the same V_plus.
+
+        A_0 = set()
+        A_cal_0 = set()
+        num_terminal_sets_found = 0
+        made_equitable = False
+
+        for W_1 in R_cal[::-1]:
+            for v in C[W_1]:
+                X = None
+
+                for U in C:
+                    if N[(v, U)] == 0 and U in A_cal and U != W_1:
+                        X = U
+
+                # v does not witness an edge in H[A_cal]
+                if X is None:
+                    continue
+
+                for U in C:
+                    # Note: Departing from the paper here.
+                    if N[(v, U)] >= 1 and U not in A_cal:
+                        X_prime = U
+                        w = v
+
+                        try:
+                            # Finding the solo neighbor of w in X_prime
+                            y = next(
+                                node
+                                for node in L[w]
+                                if F[node] == X_prime and N[(node, W_1)] == 1
+                            )
+                        except StopIteration:
+                            pass
+                        else:
+                            W = W_1
+
+                            # Move w from W to X, now X has one extra node.
+                            change_color(w, W, X, N=N, H=H, F=F, C=C, L=L)
+
+                            # Move witness from X to V_minus, making the coloring
+                            # equitable.
+                            move_witnesses(
+                                src_color=X,
+                                dst_color=V_minus,
+                                N=N,
+                                H=H,
+                                F=F,
+                                C=C,
+                                T_cal=T_cal,
+                                L=L,
+                            )
+
+                            # Move y from X_prime to W, making W the correct size.
+                            change_color(y, X_prime, W, N=N, H=H, F=F, C=C, L=L)
+
+                            # Then call the procedure on G[B - y]
+                            procedure_P(
+                                V_minus=X_prime,
+                                V_plus=V_plus,
+                                N=N,
+                                H=H,
+                                C=C,
+                                F=F,
+                                L=L,
+                                excluded_colors=excluded_colors.union(A_cal),
+                            )
+                            made_equitable = True
+                            break
+
+                if made_equitable:
+                    break
+            else:
+                # No node in W_1 was found such that
+                # it had a solo-neighbor.
+                A_cal_0.add(W_1)
+                A_0.update(C[W_1])
+                num_terminal_sets_found += 1
+
+            if num_terminal_sets_found == b:
+                # Otherwise, construct the maximal independent set and find
+                # a pair of z_1, z_2 as in Case II.
+
+                # BFS to determine B_cal': the set of colors reachable from V+
+                B_cal_prime = set()
+                T_cal_prime = {}
+
+                reachable = [V_plus]
+                marked = set(reachable)
+                idx = 0
+                while idx < len(reachable):
+                    pop = reachable[idx]
+                    idx += 1
+
+                    B_cal_prime.add(pop)
+
+                    # No need to check for excluded_colors here because
+                    # they only exclude colors from A_cal
+                    next_layer = [
+                        k
+                        for k in C
+                        if H[(pop, k)] > 0 and k not in B_cal_prime and k not in marked
+                    ]
+
+                    for dst in next_layer:
+                        T_cal_prime[pop] = dst
+
+                    marked.update(next_layer)
+                    reachable.extend(next_layer)
+
+                # Construct the independent set of G[B']
+                I_set = set()
+                I_covered = set()
+                W_covering = {}
+
+                B_prime = [node for k in B_cal_prime for node in C[k]]
+
+                # Add the nodes in V_plus to I first.
+                for z in C[V_plus] + B_prime:
+                    if z in I_covered or F[z] not in B_cal_prime:
+                        continue
+
+                    I_set.add(z)
+                    I_covered.add(z)
+                    I_covered.update(list(L[z]))
+
+                    for w in L[z]:
+                        if F[w] in A_cal_0 and N[(z, F[w])] == 1:
+                            if w not in W_covering:
+                                W_covering[w] = z
+                            else:
+                                # Found z1, z2 which have the same solo
+                                # neighbor in some W
+                                z_1 = W_covering[w]
+                                # z_2 = z
+
+                                Z = F[z_1]
+                                W = F[w]
+
+                                # shift nodes along W, V-
+                                move_witnesses(
+                                    W, V_minus, N=N, H=H, F=F, C=C, T_cal=T_cal, L=L
+                                )
+
+                                # shift nodes along V+ to Z
+                                move_witnesses(
+                                    V_plus,
+                                    Z,
+                                    N=N,
+                                    H=H,
+                                    F=F,
+                                    C=C,
+                                    T_cal=T_cal_prime,
+                                    L=L,
+                                )
+
+                                # change color of z_1 to W
+                                change_color(z_1, Z, W, N=N, H=H, F=F, C=C, L=L)
+
+                                # change color of w to some color in B_cal
+                                W_plus = next(
+                                    k for k in C if N[(w, k)] == 0 and k not in A_cal
+                                )
+                                change_color(w, W, W_plus, N=N, H=H, F=F, C=C, L=L)
+
+                                # recurse with G[B \cup W*]
+                                excluded_colors.update(
+                                    [k for k in C if k != W and k not in B_cal_prime]
+                                )
+                                procedure_P(
+                                    V_minus=W,
+                                    V_plus=W_plus,
+                                    N=N,
+                                    H=H,
+                                    C=C,
+                                    F=F,
+                                    L=L,
+                                    excluded_colors=excluded_colors,
+                                )
+
+                                made_equitable = True
+                                break
+
+                    if made_equitable:
+                        break
+                else:
+                    assert False, (
+                        "Must find a w which is the solo neighbor "
+                        "of two vertices in B_cal_prime."
+                    )
+
+            if made_equitable:
+                break
+
+
+@nx._dispatchable
+def equitable_color(G, num_colors):
+    """Provides an equitable coloring for nodes of `G`.
+
+    Attempts to color a graph using `num_colors` colors, where no neighbors of
+    a node can have same color as the node itself and the number of nodes with
+    each color differ by at most 1. `num_colors` must be greater than the
+    maximum degree of `G`. The algorithm is described in [1]_ and has
+    complexity O(num_colors * n**2).
+
+    Parameters
+    ----------
+    G : networkX graph
+       The nodes of this graph will be colored.
+
+    num_colors : number of colors to use
+       This number must be at least one more than the maximum degree of nodes
+       in the graph.
+
+    Returns
+    -------
+    A dictionary with keys representing nodes and values representing
+    corresponding coloring.
+
+    Examples
+    --------
+    >>> G = nx.cycle_graph(4)
+    >>> nx.coloring.equitable_color(G, num_colors=3)  # doctest: +SKIP
+    {0: 2, 1: 1, 2: 2, 3: 0}
+
+    Raises
+    ------
+    NetworkXAlgorithmError
+        If `num_colors` is not at least the maximum degree of the graph `G`
+
+    References
+    ----------
+    .. [1] Kierstead, H. A., Kostochka, A. V., Mydlarz, M., & Szemerédi, E.
+        (2010). A fast algorithm for equitable coloring. Combinatorica, 30(2),
+        217-224.
+    """
+
+    # Map nodes to integers for simplicity later.
+    nodes_to_int = {}
+    int_to_nodes = {}
+
+    for idx, node in enumerate(G.nodes):
+        nodes_to_int[node] = idx
+        int_to_nodes[idx] = node
+
+    G = nx.relabel_nodes(G, nodes_to_int, copy=True)
+
+    # Basic graph statistics and sanity check.
+    if len(G.nodes) > 0:
+        r_ = max(G.degree(node) for node in G.nodes)
+    else:
+        r_ = 0
+
+    if r_ >= num_colors:
+        raise nx.NetworkXAlgorithmError(
+            f"Graph has maximum degree {r_}, needs "
+            f"{r_ + 1} (> {num_colors}) colors for guaranteed coloring."
+        )
+
+    # Ensure that the number of nodes in G is a multiple of (r + 1)
+    pad_graph(G, num_colors)
+
+    # Starting the algorithm.
+    # L = {node: list(G.neighbors(node)) for node in G.nodes}
+    L_ = {node: [] for node in G.nodes}
+
+    # Arbitrary equitable allocation of colors to nodes.
+    F = {node: idx % num_colors for idx, node in enumerate(G.nodes)}
+
+    C = make_C_from_F(F)
+
+    # The neighborhood is empty initially.
+    N = make_N_from_L_C(L_, C)
+
+    # Currently all nodes witness all edges.
+    H = make_H_from_C_N(C, N)
+
+    # Start of algorithm.
+    edges_seen = set()
+
+    for u in sorted(G.nodes):
+        for v in sorted(G.neighbors(u)):
+            # Do not double count edges if (v, u) has already been seen.
+            if (v, u) in edges_seen:
+                continue
+
+            edges_seen.add((u, v))
+
+            L_[u].append(v)
+            L_[v].append(u)
+
+            N[(u, F[v])] += 1
+            N[(v, F[u])] += 1
+
+            if F[u] != F[v]:
+                # Were 'u' and 'v' witnesses for F[u] -> F[v] or F[v] -> F[u]?
+                if N[(u, F[v])] == 1:
+                    H[F[u], F[v]] -= 1  # u cannot witness an edge between F[u], F[v]
+
+                if N[(v, F[u])] == 1:
+                    H[F[v], F[u]] -= 1  # v cannot witness an edge between F[v], F[u]
+
+        if N[(u, F[u])] != 0:
+            # Find the first color where 'u' does not have any neighbors.
+            Y = next(k for k in C if N[(u, k)] == 0)
+            X = F[u]
+            change_color(u, X, Y, N=N, H=H, F=F, C=C, L=L_)
+
+            # Procedure P
+            procedure_P(V_minus=X, V_plus=Y, N=N, H=H, F=F, C=C, L=L_)
+
+    return {int_to_nodes[x]: F[x] for x in int_to_nodes}

.venv/lib/python3.11/site-packages/networkx/algorithms/coloring/greedy_coloring.py

@@ -0,0 +1,565 @@
+"""
+Greedy graph coloring using various strategies.
+"""
+
+import itertools
+from collections import defaultdict, deque
+
+import networkx as nx
+from networkx.utils import arbitrary_element, py_random_state
+
+__all__ = [
+    "greedy_color",
+    "strategy_connected_sequential",
+    "strategy_connected_sequential_bfs",
+    "strategy_connected_sequential_dfs",
+    "strategy_independent_set",
+    "strategy_largest_first",
+    "strategy_random_sequential",
+    "strategy_saturation_largest_first",
+    "strategy_smallest_last",
+]
+
+
+def strategy_largest_first(G, colors):
+    """Returns a list of the nodes of ``G`` in decreasing order by
+    degree.
+
+    ``G`` is a NetworkX graph. ``colors`` is ignored.
+
+    """
+    return sorted(G, key=G.degree, reverse=True)
+
+
+@py_random_state(2)
+def strategy_random_sequential(G, colors, seed=None):
+    """Returns a random permutation of the nodes of ``G`` as a list.
+
+    ``G`` is a NetworkX graph. ``colors`` is ignored.
+
+    seed : integer, random_state, or None (default)
+        Indicator of random number generation state.
+        See :ref:`Randomness<randomness>`.
+    """
+    nodes = list(G)
+    seed.shuffle(nodes)
+    return nodes
+
+
+def strategy_smallest_last(G, colors):
+    """Returns a deque of the nodes of ``G``, "smallest" last.
+
+    Specifically, the degrees of each node are tracked in a bucket queue.
+    From this, the node of minimum degree is repeatedly popped from the
+    graph, updating its neighbors' degrees.
+
+    ``G`` is a NetworkX graph. ``colors`` is ignored.
+
+    This implementation of the strategy runs in $O(n + m)$ time
+    (ignoring polylogarithmic factors), where $n$ is the number of nodes
+    and $m$ is the number of edges.
+
+    This strategy is related to :func:`strategy_independent_set`: if we
+    interpret each node removed as an independent set of size one, then
+    this strategy chooses an independent set of size one instead of a
+    maximal independent set.
+
+    """
+    H = G.copy()
+    result = deque()
+
+    # Build initial degree list (i.e. the bucket queue data structure)
+    degrees = defaultdict(set)  # set(), for fast random-access removals
+    lbound = float("inf")
+    for node, d in H.degree():
+        degrees[d].add(node)
+        lbound = min(lbound, d)  # Lower bound on min-degree.
+
+    def find_min_degree():
+        # Save time by starting the iterator at `lbound`, not 0.
+        # The value that we find will be our new `lbound`, which we set later.
+        return next(d for d in itertools.count(lbound) if d in degrees)
+
+    for _ in G:
+        # Pop a min-degree node and add it to the list.
+        min_degree = find_min_degree()
+        u = degrees[min_degree].pop()
+        if not degrees[min_degree]:  # Clean up the degree list.
+            del degrees[min_degree]
+        result.appendleft(u)
+
+        # Update degrees of removed node's neighbors.
+        for v in H[u]:
+            degree = H.degree(v)
+            degrees[degree].remove(v)
+            if not degrees[degree]:  # Clean up the degree list.
+                del degrees[degree]
+            degrees[degree - 1].add(v)
+
+        # Finally, remove the node.
+        H.remove_node(u)
+        lbound = min_degree - 1  # Subtract 1 in case of tied neighbors.
+
+    return result
+
+
+def _maximal_independent_set(G):
+    """Returns a maximal independent set of nodes in ``G`` by repeatedly
+    choosing an independent node of minimum degree (with respect to the
+    subgraph of unchosen nodes).
+
+    """
+    result = set()
+    remaining = set(G)
+    while remaining:
+        G = G.subgraph(remaining)
+        v = min(remaining, key=G.degree)
+        result.add(v)
+        remaining -= set(G[v]) | {v}
+    return result
+
+
+def strategy_independent_set(G, colors):
+    """Uses a greedy independent set removal strategy to determine the
+    colors.
+
+    This function updates ``colors`` **in-place** and return ``None``,
+    unlike the other strategy functions in this module.
+
+    This algorithm repeatedly finds and removes a maximal independent
+    set, assigning each node in the set an unused color.
+
+    ``G`` is a NetworkX graph.
+
+    This strategy is related to :func:`strategy_smallest_last`: in that
+    strategy, an independent set of size one is chosen at each step
+    instead of a maximal independent set.
+
+    """
+    remaining_nodes = set(G)
+    while len(remaining_nodes) > 0:
+        nodes = _maximal_independent_set(G.subgraph(remaining_nodes))
+        remaining_nodes -= nodes
+        yield from nodes
+
+
+def strategy_connected_sequential_bfs(G, colors):
+    """Returns an iterable over nodes in ``G`` in the order given by a
+    breadth-first traversal.
+
+    The generated sequence has the property that for each node except
+    the first, at least one neighbor appeared earlier in the sequence.
+
+    ``G`` is a NetworkX graph. ``colors`` is ignored.
+
+    """
+    return strategy_connected_sequential(G, colors, "bfs")
+
+
+def strategy_connected_sequential_dfs(G, colors):
+    """Returns an iterable over nodes in ``G`` in the order given by a
+    depth-first traversal.
+
+    The generated sequence has the property that for each node except
+    the first, at least one neighbor appeared earlier in the sequence.
+
+    ``G`` is a NetworkX graph. ``colors`` is ignored.
+
+    """
+    return strategy_connected_sequential(G, colors, "dfs")
+
+
+def strategy_connected_sequential(G, colors, traversal="bfs"):
+    """Returns an iterable over nodes in ``G`` in the order given by a
+    breadth-first or depth-first traversal.
+
+    ``traversal`` must be one of the strings ``'dfs'`` or ``'bfs'``,
+    representing depth-first traversal or breadth-first traversal,
+    respectively.
+
+    The generated sequence has the property that for each node except
+    the first, at least one neighbor appeared earlier in the sequence.
+
+    ``G`` is a NetworkX graph. ``colors`` is ignored.
+
+    """
+    if traversal == "bfs":
+        traverse = nx.bfs_edges
+    elif traversal == "dfs":
+        traverse = nx.dfs_edges
+    else:
+        raise nx.NetworkXError(
+            "Please specify one of the strings 'bfs' or"
+            " 'dfs' for connected sequential ordering"
+        )
+    for component in nx.connected_components(G):
+        source = arbitrary_element(component)
+        # Yield the source node, then all the nodes in the specified
+        # traversal order.
+        yield source
+        for _, end in traverse(G.subgraph(component), source):
+            yield end
+
+
+def strategy_saturation_largest_first(G, colors):
+    """Iterates over all the nodes of ``G`` in "saturation order" (also
+    known as "DSATUR").
+
+    ``G`` is a NetworkX graph. ``colors`` is a dictionary mapping nodes of
+    ``G`` to colors, for those nodes that have already been colored.
+
+    """
+    distinct_colors = {v: set() for v in G}
+
+    # Add the node color assignments given in colors to the
+    # distinct colors set for each neighbor of that node
+    for node, color in colors.items():
+        for neighbor in G[node]:
+            distinct_colors[neighbor].add(color)
+
+    # Check that the color assignments in colors are valid
+    # i.e. no neighboring nodes have the same color
+    if len(colors) >= 2:
+        for node, color in colors.items():
+            if color in distinct_colors[node]:
+                raise nx.NetworkXError("Neighboring nodes must have different colors")
+
+    # If 0 nodes have been colored, simply choose the node of highest degree.
+    if not colors:
+        node = max(G, key=G.degree)
+        yield node
+        # Add the color 0 to the distinct colors set for each
+        # neighbor of that node.
+        for v in G[node]:
+            distinct_colors[v].add(0)
+
+    while len(G) != len(colors):
+        # Update the distinct color sets for the neighbors.
+        for node, color in colors.items():
+            for neighbor in G[node]:
+                distinct_colors[neighbor].add(color)
+
+        # Compute the maximum saturation and the set of nodes that
+        # achieve that saturation.
+        saturation = {v: len(c) for v, c in distinct_colors.items() if v not in colors}
+        # Yield the node with the highest saturation, and break ties by
+        # degree.
+        node = max(saturation, key=lambda v: (saturation[v], G.degree(v)))
+        yield node
+
+
+#: Dictionary mapping name of a strategy as a string to the strategy function.
+STRATEGIES = {
+    "largest_first": strategy_largest_first,
+    "random_sequential": strategy_random_sequential,
+    "smallest_last": strategy_smallest_last,
+    "independent_set": strategy_independent_set,
+    "connected_sequential_bfs": strategy_connected_sequential_bfs,
+    "connected_sequential_dfs": strategy_connected_sequential_dfs,
+    "connected_sequential": strategy_connected_sequential,
+    "saturation_largest_first": strategy_saturation_largest_first,
+    "DSATUR": strategy_saturation_largest_first,
+}
+
+
+@nx._dispatchable
+def greedy_color(G, strategy="largest_first", interchange=False):
+    """Color a graph using various strategies of greedy graph coloring.
+
+    Attempts to color a graph using as few colors as possible, where no
+    neighbors of a node can have same color as the node itself. The
+    given strategy determines the order in which nodes are colored.
+
+    The strategies are described in [1]_, and smallest-last is based on
+    [2]_.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    strategy : string or function(G, colors)
+       A function (or a string representing a function) that provides
+       the coloring strategy, by returning nodes in the ordering they
+       should be colored. ``G`` is the graph, and ``colors`` is a
+       dictionary of the currently assigned colors, keyed by nodes. The
+       function must return an iterable over all the nodes in ``G``.
+
+       If the strategy function is an iterator generator (that is, a
+       function with ``yield`` statements), keep in mind that the
+       ``colors`` dictionary will be updated after each ``yield``, since
+       this function chooses colors greedily.
+
+       If ``strategy`` is a string, it must be one of the following,
+       each of which represents one of the built-in strategy functions.
+
+       * ``'largest_first'``
+       * ``'random_sequential'``
+       * ``'smallest_last'``
+       * ``'independent_set'``
+       * ``'connected_sequential_bfs'``
+       * ``'connected_sequential_dfs'``
+       * ``'connected_sequential'`` (alias for the previous strategy)
+       * ``'saturation_largest_first'``
+       * ``'DSATUR'`` (alias for the previous strategy)
+
+    interchange: bool
+       Will use the color interchange algorithm described by [3]_ if set
+       to ``True``.
+
+       Note that ``saturation_largest_first`` and ``independent_set``
+       do not work with interchange. Furthermore, if you use
+       interchange with your own strategy function, you cannot rely
+       on the values in the ``colors`` argument.
+
+    Returns
+    -------
+    A dictionary with keys representing nodes and values representing
+    corresponding coloring.
+
+    Examples
+    --------
+    >>> G = nx.cycle_graph(4)
+    >>> d = nx.coloring.greedy_color(G, strategy="largest_first")
+    >>> d in [{0: 0, 1: 1, 2: 0, 3: 1}, {0: 1, 1: 0, 2: 1, 3: 0}]
+    True
+
+    Raises
+    ------
+    NetworkXPointlessConcept
+        If ``strategy`` is ``saturation_largest_first`` or
+        ``independent_set`` and ``interchange`` is ``True``.
+
+    References
+    ----------
+    .. [1] Adrian Kosowski, and Krzysztof Manuszewski,
+       Classical Coloring of Graphs, Graph Colorings, 2-19, 2004.
+       ISBN 0-8218-3458-4.
+    .. [2] David W. Matula, and Leland L. Beck, "Smallest-last
+       ordering and clustering and graph coloring algorithms." *J. ACM* 30,
+       3 (July 1983), 417–427. <https://doi.org/10.1145/2402.322385>
+    .. [3] Maciej M. Sysło, Narsingh Deo, Janusz S. Kowalik,
+       Discrete Optimization Algorithms with Pascal Programs, 415-424, 1983.
+       ISBN 0-486-45353-7.
+
+    """
+    if len(G) == 0:
+        return {}
+    # Determine the strategy provided by the caller.
+    strategy = STRATEGIES.get(strategy, strategy)
+    if not callable(strategy):
+        raise nx.NetworkXError(
+            f"strategy must be callable or a valid string. {strategy} not valid."
+        )
+    # Perform some validation on the arguments before executing any
+    # strategy functions.
+    if interchange:
+        if strategy is strategy_independent_set:
+            msg = "interchange cannot be used with independent_set"
+            raise nx.NetworkXPointlessConcept(msg)
+        if strategy is strategy_saturation_largest_first:
+            msg = "interchange cannot be used with" " saturation_largest_first"
+            raise nx.NetworkXPointlessConcept(msg)
+    colors = {}
+    nodes = strategy(G, colors)
+    if interchange:
+        return _greedy_coloring_with_interchange(G, nodes)
+    for u in nodes:
+        # Set to keep track of colors of neighbors
+        nbr_colors = {colors[v] for v in G[u] if v in colors}
+        # Find the first unused color.
+        for color in itertools.count():
+            if color not in nbr_colors:
+                break
+        # Assign the new color to the current node.
+        colors[u] = color
+    return colors
+
+
+# Tools for coloring with interchanges
+class _Node:
+    __slots__ = ["node_id", "color", "adj_list", "adj_color"]
+
+    def __init__(self, node_id, n):
+        self.node_id = node_id
+        self.color = -1
+        self.adj_list = None
+        self.adj_color = [None for _ in range(n)]
+
+    def __repr__(self):
+        return (
+            f"Node_id: {self.node_id}, Color: {self.color}, "
+            f"Adj_list: ({self.adj_list}), adj_color: ({self.adj_color})"
+        )
+
+    def assign_color(self, adj_entry, color):
+        adj_entry.col_prev = None
+        adj_entry.col_next = self.adj_color[color]
+        self.adj_color[color] = adj_entry
+        if adj_entry.col_next is not None:
+            adj_entry.col_next.col_prev = adj_entry
+
+    def clear_color(self, adj_entry, color):
+        if adj_entry.col_prev is None:
+            self.adj_color[color] = adj_entry.col_next
+        else:
+            adj_entry.col_prev.col_next = adj_entry.col_next
+        if adj_entry.col_next is not None:
+            adj_entry.col_next.col_prev = adj_entry.col_prev
+
+    def iter_neighbors(self):
+        adj_node = self.adj_list
+        while adj_node is not None:
+            yield adj_node
+            adj_node = adj_node.next
+
+    def iter_neighbors_color(self, color):
+        adj_color_node = self.adj_color[color]
+        while adj_color_node is not None:
+            yield adj_color_node.node_id
+            adj_color_node = adj_color_node.col_next
+
+
+class _AdjEntry:
+    __slots__ = ["node_id", "next", "mate", "col_next", "col_prev"]
+
+    def __init__(self, node_id):
+        self.node_id = node_id
+        self.next = None
+        self.mate = None
+        self.col_next = None
+        self.col_prev = None
+
+    def __repr__(self):
+        col_next = None if self.col_next is None else self.col_next.node_id
+        col_prev = None if self.col_prev is None else self.col_prev.node_id
+        return (
+            f"Node_id: {self.node_id}, Next: ({self.next}), "
+            f"Mate: ({self.mate.node_id}), "
+            f"col_next: ({col_next}), col_prev: ({col_prev})"
+        )
+
+
+def _greedy_coloring_with_interchange(G, nodes):
+    """Return a coloring for `original_graph` using interchange approach
+
+    This procedure is an adaption of the algorithm described by [1]_,
+    and is an implementation of coloring with interchange. Please be
+    advised, that the datastructures used are rather complex because
+    they are optimized to minimize the time spent identifying
+    subcomponents of the graph, which are possible candidates for color
+    interchange.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        The graph to be colored
+
+    nodes : list
+        nodes ordered using the strategy of choice
+
+    Returns
+    -------
+    dict :
+        A dictionary keyed by node to a color value
+
+    References
+    ----------
+    .. [1] Maciej M. Syslo, Narsingh Deo, Janusz S. Kowalik,
+       Discrete Optimization Algorithms with Pascal Programs, 415-424, 1983.
+       ISBN 0-486-45353-7.
+    """
+    n = len(G)
+
+    graph = {node: _Node(node, n) for node in G}
+
+    for node1, node2 in G.edges():
+        adj_entry1 = _AdjEntry(node2)
+        adj_entry2 = _AdjEntry(node1)
+        adj_entry1.mate = adj_entry2
+        adj_entry2.mate = adj_entry1
+        node1_head = graph[node1].adj_list
+        adj_entry1.next = node1_head
+        graph[node1].adj_list = adj_entry1
+        node2_head = graph[node2].adj_list
+        adj_entry2.next = node2_head
+        graph[node2].adj_list = adj_entry2
+
+    k = 0
+    for node in nodes:
+        # Find the smallest possible, unused color
+        neighbors = graph[node].iter_neighbors()
+        col_used = {graph[adj_node.node_id].color for adj_node in neighbors}
+        col_used.discard(-1)
+        k1 = next(itertools.dropwhile(lambda x: x in col_used, itertools.count()))
+
+        # k1 is now the lowest available color
+        if k1 > k:
+            connected = True
+            visited = set()
+            col1 = -1
+            col2 = -1
+            while connected and col1 < k:
+                col1 += 1
+                neighbor_cols = graph[node].iter_neighbors_color(col1)
+                col1_adj = list(neighbor_cols)
+
+                col2 = col1
+                while connected and col2 < k:
+                    col2 += 1
+                    visited = set(col1_adj)
+                    frontier = list(col1_adj)
+                    i = 0
+                    while i < len(frontier):
+                        search_node = frontier[i]
+                        i += 1
+                        col_opp = col2 if graph[search_node].color == col1 else col1
+                        neighbor_cols = graph[search_node].iter_neighbors_color(col_opp)
+
+                        for neighbor in neighbor_cols:
+                            if neighbor not in visited:
+                                visited.add(neighbor)
+                                frontier.append(neighbor)
+
+                    # Search if node is not adj to any col2 vertex
+                    connected = (
+                        len(
+                            visited.intersection(graph[node].iter_neighbors_color(col2))
+                        )
+                        > 0
+                    )
+
+            # If connected is false then we can swap !!!
+            if not connected:
+                # Update all the nodes in the component
+                for search_node in visited:
+                    graph[search_node].color = (
+                        col2 if graph[search_node].color == col1 else col1
+                    )
+                    col2_adj = graph[search_node].adj_color[col2]
+                    graph[search_node].adj_color[col2] = graph[search_node].adj_color[
+                        col1
+                    ]
+                    graph[search_node].adj_color[col1] = col2_adj
+
+                # Update all the neighboring nodes
+                for search_node in visited:
+                    col = graph[search_node].color
+                    col_opp = col1 if col == col2 else col2
+                    for adj_node in graph[search_node].iter_neighbors():
+                        if graph[adj_node.node_id].color != col_opp:
+                            # Direct reference to entry
+                            adj_mate = adj_node.mate
+                            graph[adj_node.node_id].clear_color(adj_mate, col_opp)
+                            graph[adj_node.node_id].assign_color(adj_mate, col)
+                k1 = col1
+
+        # We can color this node color k1
+        graph[node].color = k1
+        k = max(k1, k)
+
+        # Update the neighbors of this node
+        for adj_node in graph[node].iter_neighbors():
+            adj_mate = adj_node.mate
+            graph[adj_node.node_id].assign_color(adj_mate, k1)
+
+    return {node.node_id: node.color for node in graph.values()}

.venv/lib/python3.11/site-packages/networkx/algorithms/coloring/tests/test_coloring.py

@@ -0,0 +1,863 @@
+"""Greedy coloring test suite."""
+
+import itertools
+
+import pytest
+
+import networkx as nx
+
+is_coloring = nx.algorithms.coloring.equitable_coloring.is_coloring
+is_equitable = nx.algorithms.coloring.equitable_coloring.is_equitable
+
+
+ALL_STRATEGIES = [
+    "largest_first",
+    "random_sequential",
+    "smallest_last",
+    "independent_set",
+    "connected_sequential_bfs",
+    "connected_sequential_dfs",
+    "connected_sequential",
+    "saturation_largest_first",
+    "DSATUR",
+]
+
+# List of strategies where interchange=True results in an error
+INTERCHANGE_INVALID = ["independent_set", "saturation_largest_first", "DSATUR"]
+
+
+class TestColoring:
+    def test_basic_cases(self):
+        def check_basic_case(graph_func, n_nodes, strategy, interchange):
+            graph = graph_func()
+            coloring = nx.coloring.greedy_color(
+                graph, strategy=strategy, interchange=interchange
+            )
+            assert verify_length(coloring, n_nodes)
+            assert verify_coloring(graph, coloring)
+
+        for graph_func, n_nodes in BASIC_TEST_CASES.items():
+            for interchange in [True, False]:
+                for strategy in ALL_STRATEGIES:
+                    check_basic_case(graph_func, n_nodes, strategy, False)
+                    if strategy not in INTERCHANGE_INVALID:
+                        check_basic_case(graph_func, n_nodes, strategy, True)
+
+    def test_special_cases(self):
+        def check_special_case(strategy, graph_func, interchange, colors):
+            graph = graph_func()
+            coloring = nx.coloring.greedy_color(
+                graph, strategy=strategy, interchange=interchange
+            )
+            if not hasattr(colors, "__len__"):
+                colors = [colors]
+            assert any(verify_length(coloring, n_colors) for n_colors in colors)
+            assert verify_coloring(graph, coloring)
+
+        for strategy, arglist in SPECIAL_TEST_CASES.items():
+            for args in arglist:
+                check_special_case(strategy, args[0], args[1], args[2])
+
+    def test_interchange_invalid(self):
+        graph = one_node_graph()
+        for strategy in INTERCHANGE_INVALID:
+            pytest.raises(
+                nx.NetworkXPointlessConcept,
+                nx.coloring.greedy_color,
+                graph,
+                strategy=strategy,
+                interchange=True,
+            )
+
+    def test_bad_inputs(self):
+        graph = one_node_graph()
+        pytest.raises(
+            nx.NetworkXError,
+            nx.coloring.greedy_color,
+            graph,
+            strategy="invalid strategy",
+        )
+
+    def test_strategy_as_function(self):
+        graph = lf_shc()
+        colors_1 = nx.coloring.greedy_color(graph, "largest_first")
+        colors_2 = nx.coloring.greedy_color(graph, nx.coloring.strategy_largest_first)
+        assert colors_1 == colors_2
+
+    def test_seed_argument(self):
+        graph = lf_shc()
+        rs = nx.coloring.strategy_random_sequential
+        c1 = nx.coloring.greedy_color(graph, lambda g, c: rs(g, c, seed=1))
+        for u, v in graph.edges:
+            assert c1[u] != c1[v]
+
+    def test_is_coloring(self):
+        G = nx.Graph()
+        G.add_edges_from([(0, 1), (1, 2)])
+        coloring = {0: 0, 1: 1, 2: 0}
+        assert is_coloring(G, coloring)
+
+        coloring[0] = 1
+        assert not is_coloring(G, coloring)
+        assert not is_equitable(G, coloring)
+
+    def test_is_equitable(self):
+        G = nx.Graph()
+        G.add_edges_from([(0, 1), (1, 2)])
+        coloring = {0: 0, 1: 1, 2: 0}
+        assert is_equitable(G, coloring)
+
+        G.add_edges_from([(2, 3), (2, 4), (2, 5)])
+        coloring[3] = 1
+        coloring[4] = 1
+        coloring[5] = 1
+        assert is_coloring(G, coloring)
+        assert not is_equitable(G, coloring)
+
+    def test_num_colors(self):
+        G = nx.Graph()
+        G.add_edges_from([(0, 1), (0, 2), (0, 3)])
+        pytest.raises(nx.NetworkXAlgorithmError, nx.coloring.equitable_color, G, 2)
+
+    def test_equitable_color(self):
+        G = nx.fast_gnp_random_graph(n=10, p=0.2, seed=42)
+        coloring = nx.coloring.equitable_color(G, max_degree(G) + 1)
+        assert is_equitable(G, coloring)
+
+    def test_equitable_color_empty(self):
+        G = nx.empty_graph()
+        coloring = nx.coloring.equitable_color(G, max_degree(G) + 1)
+        assert is_equitable(G, coloring)
+
+    def test_equitable_color_large(self):
+        G = nx.fast_gnp_random_graph(100, 0.1, seed=42)
+        coloring = nx.coloring.equitable_color(G, max_degree(G) + 1)
+        assert is_equitable(G, coloring, num_colors=max_degree(G) + 1)
+
+    def test_case_V_plus_not_in_A_cal(self):
+        # Hand crafted case to avoid the easy case.
+        L = {
+            0: [2, 5],
+            1: [3, 4],
+            2: [0, 8],
+            3: [1, 7],
+            4: [1, 6],
+            5: [0, 6],
+            6: [4, 5],
+            7: [3],
+            8: [2],
+        }
+
+        F = {
+            # Color 0
+            0: 0,
+            1: 0,
+            # Color 1
+            2: 1,
+            3: 1,
+            4: 1,
+            5: 1,
+            # Color 2
+            6: 2,
+            7: 2,
+            8: 2,
+        }
+
+        C = nx.algorithms.coloring.equitable_coloring.make_C_from_F(F)
+        N = nx.algorithms.coloring.equitable_coloring.make_N_from_L_C(L, C)
+        H = nx.algorithms.coloring.equitable_coloring.make_H_from_C_N(C, N)
+
+        nx.algorithms.coloring.equitable_coloring.procedure_P(
+            V_minus=0, V_plus=1, N=N, H=H, F=F, C=C, L=L
+        )
+        check_state(L=L, N=N, H=H, F=F, C=C)
+
+    def test_cast_no_solo(self):
+        L = {
+            0: [8, 9],
+            1: [10, 11],
+            2: [8],
+            3: [9],
+            4: [10, 11],
+            5: [8],
+            6: [9],
+            7: [10, 11],
+            8: [0, 2, 5],
+            9: [0, 3, 6],
+            10: [1, 4, 7],
+            11: [1, 4, 7],
+        }
+
+        F = {0: 0, 1: 0, 2: 2, 3: 2, 4: 2, 5: 3, 6: 3, 7: 3, 8: 1, 9: 1, 10: 1, 11: 1}
+
+        C = nx.algorithms.coloring.equitable_coloring.make_C_from_F(F)
+        N = nx.algorithms.coloring.equitable_coloring.make_N_from_L_C(L, C)
+        H = nx.algorithms.coloring.equitable_coloring.make_H_from_C_N(C, N)
+
+        nx.algorithms.coloring.equitable_coloring.procedure_P(
+            V_minus=0, V_plus=1, N=N, H=H, F=F, C=C, L=L
+        )
+        check_state(L=L, N=N, H=H, F=F, C=C)
+
+    def test_hard_prob(self):
+        # Tests for two levels of recursion.
+        num_colors, s = 5, 5
+
+        G = nx.Graph()
+        G.add_edges_from(
+            [
+                (0, 10),
+                (0, 11),
+                (0, 12),
+                (0, 23),
+                (10, 4),
+                (10, 9),
+                (10, 20),
+                (11, 4),
+                (11, 8),
+                (11, 16),
+                (12, 9),
+                (12, 22),
+                (12, 23),
+                (23, 7),
+                (1, 17),
+                (1, 18),
+                (1, 19),
+                (1, 24),
+                (17, 5),
+                (17, 13),
+                (17, 22),
+                (18, 5),
+                (19, 5),
+                (19, 6),
+                (19, 8),
+                (24, 7),
+                (24, 16),
+                (2, 4),
+                (2, 13),
+                (2, 14),
+                (2, 15),
+                (4, 6),
+                (13, 5),
+                (13, 21),
+                (14, 6),
+                (14, 15),
+                (15, 6),
+                (15, 21),
+                (3, 16),
+                (3, 20),
+                (3, 21),
+                (3, 22),
+                (16, 8),
+                (20, 8),
+                (21, 9),
+                (22, 7),
+            ]
+        )
+        F = {node: node // s for node in range(num_colors * s)}
+        F[s - 1] = num_colors - 1
+
+        params = make_params_from_graph(G=G, F=F)
+
+        nx.algorithms.coloring.equitable_coloring.procedure_P(
+            V_minus=0, V_plus=num_colors - 1, **params
+        )
+        check_state(**params)
+
+    def test_hardest_prob(self):
+        # Tests for two levels of recursion.
+        num_colors, s = 10, 4
+
+        G = nx.Graph()
+        G.add_edges_from(
+            [
+                (0, 19),
+                (0, 24),
+                (0, 29),
+                (0, 30),
+                (0, 35),
+                (19, 3),
+                (19, 7),
+                (19, 9),
+                (19, 15),
+                (19, 21),
+                (19, 24),
+                (19, 30),
+                (19, 38),
+                (24, 5),
+                (24, 11),
+                (24, 13),
+                (24, 20),
+                (24, 30),
+                (24, 37),
+                (24, 38),
+                (29, 6),
+                (29, 10),
+                (29, 13),
+                (29, 15),
+                (29, 16),
+                (29, 17),
+                (29, 20),
+                (29, 26),
+                (30, 6),
+                (30, 10),
+                (30, 15),
+                (30, 22),
+                (30, 23),
+                (30, 39),
+                (35, 6),
+                (35, 9),
+                (35, 14),
+                (35, 18),
+                (35, 22),
+                (35, 23),
+                (35, 25),
+                (35, 27),
+                (1, 20),
+                (1, 26),
+                (1, 31),
+                (1, 34),
+                (1, 38),
+                (20, 4),
+                (20, 8),
+                (20, 14),
+                (20, 18),
+                (20, 28),
+                (20, 33),
+                (26, 7),
+                (26, 10),
+                (26, 14),
+                (26, 18),
+                (26, 21),
+                (26, 32),
+                (26, 39),
+                (31, 5),
+                (31, 8),
+                (31, 13),
+                (31, 16),
+                (31, 17),
+                (31, 21),
+                (31, 25),
+                (31, 27),
+                (34, 7),
+                (34, 8),
+                (34, 13),
+                (34, 18),
+                (34, 22),
+                (34, 23),
+                (34, 25),
+                (34, 27),
+                (38, 4),
+                (38, 9),
+                (38, 12),
+                (38, 14),
+                (38, 21),
+                (38, 27),
+                (2, 3),
+                (2, 18),
+                (2, 21),
+                (2, 28),
+                (2, 32),
+                (2, 33),
+                (2, 36),
+                (2, 37),
+                (2, 39),
+                (3, 5),
+                (3, 9),
+                (3, 13),
+                (3, 22),
+                (3, 23),
+                (3, 25),
+                (3, 27),
+                (18, 6),
+                (18, 11),
+                (18, 15),
+                (18, 39),
+                (21, 4),
+                (21, 10),
+                (21, 14),
+                (21, 36),
+                (28, 6),
+                (28, 10),
+                (28, 14),
+                (28, 16),
+                (28, 17),
+                (28, 25),
+                (28, 27),
+                (32, 5),
+                (32, 10),
+                (32, 12),
+                (32, 16),
+                (32, 17),
+                (32, 22),
+                (32, 23),
+                (33, 7),
+                (33, 10),
+                (33, 12),
+                (33, 16),
+                (33, 17),
+                (33, 25),
+                (33, 27),
+                (36, 5),
+                (36, 8),
+                (36, 15),
+                (36, 16),
+                (36, 17),
+                (36, 25),
+                (36, 27),
+                (37, 5),
+                (37, 11),
+                (37, 15),
+                (37, 16),
+                (37, 17),
+                (37, 22),
+                (37, 23),
+                (39, 7),
+                (39, 8),
+                (39, 15),
+                (39, 22),
+                (39, 23),
+            ]
+        )
+        F = {node: node // s for node in range(num_colors * s)}
+        F[s - 1] = num_colors - 1  # V- = 0, V+ = num_colors - 1
+
+        params = make_params_from_graph(G=G, F=F)
+
+        nx.algorithms.coloring.equitable_coloring.procedure_P(
+            V_minus=0, V_plus=num_colors - 1, **params
+        )
+        check_state(**params)
+
+    def test_strategy_saturation_largest_first(self):
+        def color_remaining_nodes(
+            G,
+            colored_nodes,
+            full_color_assignment=None,
+            nodes_to_add_between_calls=1,
+        ):
+            color_assignments = []
+            aux_colored_nodes = colored_nodes.copy()
+
+            node_iterator = nx.algorithms.coloring.greedy_coloring.strategy_saturation_largest_first(
+                G, aux_colored_nodes
+            )
+
+            for u in node_iterator:
+                # Set to keep track of colors of neighbors
+                nbr_colors = {
+                    aux_colored_nodes[v] for v in G[u] if v in aux_colored_nodes
+                }
+                # Find the first unused color.
+                for color in itertools.count():
+                    if color not in nbr_colors:
+                        break
+                aux_colored_nodes[u] = color
+                color_assignments.append((u, color))
+
+                # Color nodes between iterations
+                for i in range(nodes_to_add_between_calls - 1):
+                    if not len(color_assignments) + len(colored_nodes) >= len(
+                        full_color_assignment
+                    ):
+                        full_color_assignment_node, color = full_color_assignment[
+                            len(color_assignments) + len(colored_nodes)
+                        ]
+
+                        # Assign the new color to the current node.
+                        aux_colored_nodes[full_color_assignment_node] = color
+                        color_assignments.append((full_color_assignment_node, color))
+
+            return color_assignments, aux_colored_nodes
+
+        for G, _, _ in SPECIAL_TEST_CASES["saturation_largest_first"]:
+            G = G()
+
+            # Check that function still works when nodes are colored between iterations
+            for nodes_to_add_between_calls in range(1, 5):
+                # Get a full color assignment, (including the order in which nodes were colored)
+                colored_nodes = {}
+                full_color_assignment, full_colored_nodes = color_remaining_nodes(
+                    G, colored_nodes
+                )
+
+                # For each node in the color assignment, add it to colored_nodes and re-run the function
+                for ind, (node, color) in enumerate(full_color_assignment):
+                    colored_nodes[node] = color
+
+                    (
+                        partial_color_assignment,
+                        partial_colored_nodes,
+                    ) = color_remaining_nodes(
+                        G,
+                        colored_nodes,
+                        full_color_assignment=full_color_assignment,
+                        nodes_to_add_between_calls=nodes_to_add_between_calls,
+                    )
+
+                    # Check that the color assignment and order of remaining nodes are the same
+                    assert full_color_assignment[ind + 1 :] == partial_color_assignment
+                    assert full_colored_nodes == partial_colored_nodes
+
+
+#  ############################  Utility functions ############################
+def verify_coloring(graph, coloring):
+    for node in graph.nodes():
+        if node not in coloring:
+            return False
+
+        color = coloring[node]
+        for neighbor in graph.neighbors(node):
+            if coloring[neighbor] == color:
+                return False
+
+    return True
+
+
+def verify_length(coloring, expected):
+    coloring = dict_to_sets(coloring)
+    return len(coloring) == expected
+
+
+def dict_to_sets(colors):
+    if len(colors) == 0:
+        return []
+
+    k = max(colors.values()) + 1
+    sets = [set() for _ in range(k)]
+
+    for node, color in colors.items():
+        sets[color].add(node)
+
+    return sets
+
+
+#  ############################  Graph Generation ############################
+
+
+def empty_graph():
+    return nx.Graph()
+
+
+def one_node_graph():
+    graph = nx.Graph()
+    graph.add_nodes_from([1])
+    return graph
+
+
+def two_node_graph():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2])
+    graph.add_edges_from([(1, 2)])
+    return graph
+
+
+def three_node_clique():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3])
+    graph.add_edges_from([(1, 2), (1, 3), (2, 3)])
+    return graph
+
+
+def disconnected():
+    graph = nx.Graph()
+    graph.add_edges_from([(1, 2), (2, 3), (4, 5), (5, 6)])
+    return graph
+
+
+def rs_shc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4])
+    graph.add_edges_from([(1, 2), (2, 3), (3, 4)])
+    return graph
+
+
+def slf_shc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6, 7])
+    graph.add_edges_from(
+        [(1, 2), (1, 5), (1, 6), (2, 3), (2, 7), (3, 4), (3, 7), (4, 5), (4, 6), (5, 6)]
+    )
+    return graph
+
+
+def slf_hc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6, 7, 8])
+    graph.add_edges_from(
+        [
+            (1, 2),
+            (1, 3),
+            (1, 4),
+            (1, 5),
+            (2, 3),
+            (2, 4),
+            (2, 6),
+            (5, 7),
+            (5, 8),
+            (6, 7),
+            (6, 8),
+            (7, 8),
+        ]
+    )
+    return graph
+
+
+def lf_shc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6])
+    graph.add_edges_from([(6, 1), (1, 4), (4, 3), (3, 2), (2, 5)])
+    return graph
+
+
+def lf_hc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6, 7])
+    graph.add_edges_from(
+        [
+            (1, 7),
+            (1, 6),
+            (1, 3),
+            (1, 4),
+            (7, 2),
+            (2, 6),
+            (2, 3),
+            (2, 5),
+            (5, 3),
+            (5, 4),
+            (4, 3),
+        ]
+    )
+    return graph
+
+
+def sl_shc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6])
+    graph.add_edges_from(
+        [(1, 2), (1, 3), (2, 3), (1, 4), (2, 5), (3, 6), (4, 5), (4, 6), (5, 6)]
+    )
+    return graph
+
+
+def sl_hc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6, 7, 8])
+    graph.add_edges_from(
+        [
+            (1, 2),
+            (1, 3),
+            (1, 5),
+            (1, 7),
+            (2, 3),
+            (2, 4),
+            (2, 8),
+            (8, 4),
+            (8, 6),
+            (8, 7),
+            (7, 5),
+            (7, 6),
+            (3, 4),
+            (4, 6),
+            (6, 5),
+            (5, 3),
+        ]
+    )
+    return graph
+
+
+def gis_shc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4])
+    graph.add_edges_from([(1, 2), (2, 3), (3, 4)])
+    return graph
+
+
+def gis_hc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6])
+    graph.add_edges_from([(1, 5), (2, 5), (3, 6), (4, 6), (5, 6)])
+    return graph
+
+
+def cs_shc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5])
+    graph.add_edges_from([(1, 2), (1, 5), (2, 3), (2, 4), (2, 5), (3, 4), (4, 5)])
+    return graph
+
+
+def rsi_shc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6])
+    graph.add_edges_from(
+        [(1, 2), (1, 5), (1, 6), (2, 3), (3, 4), (4, 5), (4, 6), (5, 6)]
+    )
+    return graph
+
+
+def lfi_shc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6, 7])
+    graph.add_edges_from(
+        [(1, 2), (1, 5), (1, 6), (2, 3), (2, 7), (3, 4), (3, 7), (4, 5), (4, 6), (5, 6)]
+    )
+    return graph
+
+
+def lfi_hc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6, 7, 8, 9])
+    graph.add_edges_from(
+        [
+            (1, 2),
+            (1, 5),
+            (1, 6),
+            (1, 7),
+            (2, 3),
+            (2, 8),
+            (2, 9),
+            (3, 4),
+            (3, 8),
+            (3, 9),
+            (4, 5),
+            (4, 6),
+            (4, 7),
+            (5, 6),
+        ]
+    )
+    return graph
+
+
+def sli_shc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6, 7])
+    graph.add_edges_from(
+        [
+            (1, 2),
+            (1, 3),
+            (1, 5),
+            (1, 7),
+            (2, 3),
+            (2, 6),
+            (3, 4),
+            (4, 5),
+            (4, 6),
+            (5, 7),
+            (6, 7),
+        ]
+    )
+    return graph
+
+
+def sli_hc():
+    graph = nx.Graph()
+    graph.add_nodes_from([1, 2, 3, 4, 5, 6, 7, 8, 9])
+    graph.add_edges_from(
+        [
+            (1, 2),
+            (1, 3),
+            (1, 4),
+            (1, 5),
+            (2, 3),
+            (2, 7),
+            (2, 8),
+            (2, 9),
+            (3, 6),
+            (3, 7),
+            (3, 9),
+            (4, 5),
+            (4, 6),
+            (4, 8),
+            (4, 9),
+            (5, 6),
+            (5, 7),
+            (5, 8),
+            (6, 7),
+            (6, 9),
+            (7, 8),
+            (8, 9),
+        ]
+    )
+    return graph
+
+
+# --------------------------------------------------------------------------
+# Basic tests for all strategies
+# For each basic graph function, specify the number of expected colors.
+BASIC_TEST_CASES = {
+    empty_graph: 0,
+    one_node_graph: 1,
+    two_node_graph: 2,
+    disconnected: 2,
+    three_node_clique: 3,
+}
+
+
+# --------------------------------------------------------------------------
+# Special test cases. Each strategy has a list of tuples of the form
+# (graph function, interchange, valid # of colors)
+SPECIAL_TEST_CASES = {
+    "random_sequential": [
+        (rs_shc, False, (2, 3)),
+        (rs_shc, True, 2),
+        (rsi_shc, True, (3, 4)),
+    ],
+    "saturation_largest_first": [(slf_shc, False, (3, 4)), (slf_hc, False, 4)],
+    "largest_first": [
+        (lf_shc, False, (2, 3)),
+        (lf_hc, False, 4),
+        (lf_shc, True, 2),
+        (lf_hc, True, 3),
+        (lfi_shc, True, (3, 4)),
+        (lfi_hc, True, 4),
+    ],
+    "smallest_last": [
+        (sl_shc, False, (3, 4)),
+        (sl_hc, False, 5),
+        (sl_shc, True, 3),
+        (sl_hc, True, 4),
+        (sli_shc, True, (3, 4)),
+        (sli_hc, True, 5),
+    ],
+    "independent_set": [(gis_shc, False, (2, 3)), (gis_hc, False, 3)],
+    "connected_sequential": [(cs_shc, False, (3, 4)), (cs_shc, True, 3)],
+    "connected_sequential_dfs": [(cs_shc, False, (3, 4))],
+}
+
+
+# --------------------------------------------------------------------------
+# Helper functions to test
+# (graph function, interchange, valid # of colors)
+
+
+def check_state(L, N, H, F, C):
+    s = len(C[0])
+    num_colors = len(C.keys())
+
+    assert all(u in L[v] for u in L for v in L[u])
+    assert all(F[u] != F[v] for u in L for v in L[u])
+    assert all(len(L[u]) < num_colors for u in L)
+    assert all(len(C[x]) == s for x in C)
+    assert all(H[(c1, c2)] >= 0 for c1 in C for c2 in C)
+    assert all(N[(u, F[u])] == 0 for u in F)
+
+
+def max_degree(G):
+    """Get the maximum degree of any node in G."""
+    return max(G.degree(node) for node in G.nodes) if len(G.nodes) > 0 else 0
+
+
+def make_params_from_graph(G, F):
+    """Returns {N, L, H, C} from the given graph."""
+    num_nodes = len(G)
+    L = {u: [] for u in range(num_nodes)}
+    for u, v in G.edges:
+        L[u].append(v)
+        L[v].append(u)
+
+    C = nx.algorithms.coloring.equitable_coloring.make_C_from_F(F)
+    N = nx.algorithms.coloring.equitable_coloring.make_N_from_L_C(L, C)
+    H = nx.algorithms.coloring.equitable_coloring.make_H_from_C_N(C, N)
+
+    return {"N": N, "F": F, "C": C, "H": H, "L": L}

.venv/lib/python3.11/site-packages/networkx/algorithms/shortest_paths/__init__.py

@@ -0,0 +1,5 @@
+from networkx.algorithms.shortest_paths.generic import *
+from networkx.algorithms.shortest_paths.unweighted import *
+from networkx.algorithms.shortest_paths.weighted import *
+from networkx.algorithms.shortest_paths.astar import *
+from networkx.algorithms.shortest_paths.dense import *