okstra 0.108.0 → 0.109.0

package/runtime/python/okstra_vendor/networkx/algorithms/communicability_alg.py

@@ -0,0 +1,163 @@
+"""
+Communicability.
+"""
+
+import networkx as nx
+from networkx.utils import not_implemented_for
+
+__all__ = ["communicability", "communicability_exp"]
+
+
+@not_implemented_for("directed")
+@not_implemented_for("multigraph")
+@nx._dispatchable
+def communicability(G):
+    r"""Returns communicability between all pairs of nodes in G.
+
+    The communicability between pairs of nodes in G is the sum of
+    walks of different lengths starting at node u and ending at node v.
+
+    Parameters
+    ----------
+    G: graph
+
+    Returns
+    -------
+    comm: dictionary of dictionaries
+        Dictionary of dictionaries keyed by nodes with communicability
+        as the value.
+
+    Raises
+    ------
+    NetworkXError
+       If the graph is not undirected and simple.
+
+    See Also
+    --------
+    communicability_exp:
+       Communicability between all pairs of nodes in G  using spectral
+       decomposition.
+    communicability_betweenness_centrality:
+       Communicability betweenness centrality for each node in G.
+
+    Notes
+    -----
+    This algorithm uses a spectral decomposition of the adjacency matrix.
+    Let G=(V,E) be a simple undirected graph.  Using the connection between
+    the powers  of the adjacency matrix and the number of walks in the graph,
+    the communicability  between nodes `u` and `v` based on the graph spectrum
+    is [1]_
+
+    .. math::
+        C(u,v)=\sum_{j=1}^{n}\phi_{j}(u)\phi_{j}(v)e^{\lambda_{j}},
+
+    where `\phi_{j}(u)` is the `u\rm{th}` element of the `j\rm{th}` orthonormal
+    eigenvector of the adjacency matrix associated with the eigenvalue
+    `\lambda_{j}`.
+
+    References
+    ----------
+    .. [1] Ernesto Estrada, Naomichi Hatano,
+       "Communicability in complex networks",
+       Phys. Rev. E 77, 036111 (2008).
+       https://arxiv.org/abs/0707.0756
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (1, 2), (1, 5), (5, 4), (2, 4), (2, 3), (4, 3), (3, 6)])
+    >>> c = nx.communicability(G)
+    """
+    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[A != 0.0] = 1
+    w, vec = np.linalg.eigh(A)
+    expw = np.exp(w)
+    mapping = dict(zip(nodelist, range(len(nodelist))))
+    c = {}
+    # computing communicabilities
+    for u in G:
+        c[u] = {}
+        for v in G:
+            s = 0
+            p = mapping[u]
+            q = mapping[v]
+            for j in range(len(nodelist)):
+                s += vec[:, j][p] * vec[:, j][q] * expw[j]
+            c[u][v] = float(s)
+    return c
+
+
+@not_implemented_for("directed")
+@not_implemented_for("multigraph")
+@nx._dispatchable
+def communicability_exp(G):
+    r"""Returns communicability between all pairs of nodes in G.
+
+    Communicability between pair of node (u,v) of node in G is the sum of
+    walks of different lengths starting at node u and ending at node v.
+
+    Parameters
+    ----------
+    G: graph
+
+    Returns
+    -------
+    comm: dictionary of dictionaries
+        Dictionary of dictionaries keyed by nodes with communicability
+        as the value.
+
+    Raises
+    ------
+    NetworkXError
+        If the graph is not undirected and simple.
+
+    See Also
+    --------
+    communicability:
+       Communicability between pairs of nodes in G.
+    communicability_betweenness_centrality:
+       Communicability betweenness centrality for each node in G.
+
+    Notes
+    -----
+    This algorithm uses matrix exponentiation of the adjacency matrix.
+
+    Let G=(V,E) be a simple undirected graph.  Using the connection between
+    the powers  of the adjacency matrix and the number of walks in the graph,
+    the communicability between nodes u and v is [1]_,
+
+    .. math::
+        C(u,v) = (e^A)_{uv},
+
+    where `A` is the adjacency matrix of G.
+
+    References
+    ----------
+    .. [1] Ernesto Estrada, Naomichi Hatano,
+       "Communicability in complex networks",
+       Phys. Rev. E 77, 036111 (2008).
+       https://arxiv.org/abs/0707.0756
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (1, 2), (1, 5), (5, 4), (2, 4), (2, 3), (4, 3), (3, 6)])
+    >>> c = nx.communicability_exp(G)
+    """
+    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
+    # communicability matrix
+    expA = sp.linalg.expm(A)
+    mapping = dict(zip(nodelist, range(len(nodelist))))
+    c = {}
+    for u in G:
+        c[u] = {}
+        for v in G:
+            c[u][v] = float(expA[mapping[u], mapping[v]])
+    return c

package/runtime/python/okstra_vendor/networkx/algorithms/community/__init__.py

@@ -0,0 +1,28 @@
+"""Functions for computing and measuring community structure.
+
+The ``community`` subpackage can be accessed by using :mod:`networkx.community`, then accessing the
+functions as attributes of ``community``. For example::
+
+    >>> import networkx as nx
+    >>> G = nx.barbell_graph(5, 1)
+    >>> communities_generator = nx.community.girvan_newman(G)
+    >>> top_level_communities = next(communities_generator)
+    >>> next_level_communities = next(communities_generator)
+    >>> sorted(map(sorted, next_level_communities))
+    [[0, 1, 2, 3, 4], [5], [6, 7, 8, 9, 10]]
+
+"""
+
+from networkx.algorithms.community.asyn_fluid import *
+from networkx.algorithms.community.bipartitions import *
+from networkx.algorithms.community.centrality import *
+from networkx.algorithms.community.divisive import *
+from networkx.algorithms.community.kclique import *
+from networkx.algorithms.community.label_propagation import *
+from networkx.algorithms.community.lukes import *
+from networkx.algorithms.community.modularity_max import *
+from networkx.algorithms.community.quality import *
+from networkx.algorithms.community.community_utils import *
+from networkx.algorithms.community.louvain import *
+from networkx.algorithms.community.leiden import *
+from networkx.algorithms.community.local import *

package/runtime/python/okstra_vendor/networkx/algorithms/community/asyn_fluid.py

@@ -0,0 +1,153 @@
+"""Asynchronous Fluid Communities algorithm for community detection."""
+
+from collections import Counter
+
+import networkx as nx
+from networkx.algorithms.components import is_connected
+from networkx.exception import NetworkXError
+from networkx.utils import groups, not_implemented_for, py_random_state
+
+__all__ = ["asyn_fluidc"]
+
+
+@not_implemented_for("directed")
+@not_implemented_for("multigraph")
+@py_random_state(3)
+@nx._dispatchable
+def asyn_fluidc(G, k, max_iter=100, seed=None):
+    """Returns communities in `G` as detected by Fluid Communities algorithm.
+
+    The asynchronous fluid communities algorithm is described in
+    [1]_. The algorithm is based on the simple idea of fluids interacting
+    in an environment, expanding and pushing each other. Its initialization is
+    random, so found communities may vary on different executions.
+
+    The algorithm proceeds as follows. First each of the initial k communities
+    is initialized in a random vertex in the graph. Then the algorithm iterates
+    over all vertices in a random order, updating the community of each vertex
+    based on its own community and the communities of its neighbors. This
+    process is performed several times until convergence.
+    At all times, each community has a total density of 1, which is equally
+    distributed among the vertices it contains. If a vertex changes of
+    community, vertex densities of affected communities are adjusted
+    immediately. When a complete iteration over all vertices is done, such that
+    no vertex changes the community it belongs to, the algorithm has converged
+    and returns.
+
+    This is the original version of the algorithm described in [1]_.
+    Unfortunately, it does not support weighted graphs yet.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        Graph must be simple and undirected.
+
+    k : integer
+        The number of communities to be found.
+
+    max_iter : integer
+        The number of maximum iterations allowed. By default 100.
+
+    seed : integer, random_state, or None (default)
+        Indicator of random number generation state.
+        See :ref:`Randomness<randomness>`.
+
+    Returns
+    -------
+    communities : iterable
+        Iterable of communities given as sets of nodes.
+
+    Notes
+    -----
+    k variable is not an optional argument.
+
+    References
+    ----------
+    .. [1] Parés F., Garcia-Gasulla D. et al. "Fluid Communities: A
+       Competitive and Highly Scalable Community Detection Algorithm".
+       [https://arxiv.org/pdf/1703.09307.pdf].
+    """
+    # Initial checks
+    if not isinstance(k, int):
+        raise NetworkXError("k must be an integer.")
+    if not k > 0:
+        raise NetworkXError("k must be greater than 0.")
+    if not is_connected(G):
+        raise NetworkXError("Fluid Communities require connected Graphs.")
+    if len(G) < k:
+        raise NetworkXError("k cannot be bigger than the number of nodes.")
+    if max_iter <= 0:
+        msg = f"{max_iter=} must be greater than 0"
+        raise ValueError(msg)
+    # Initialization
+    max_density = 1.0
+    vertices = list(G)
+    seed.shuffle(vertices)
+    communities = {n: i for i, n in enumerate(vertices[:k])}
+    density = {}
+    com_to_numvertices = {}
+    for vertex in communities:
+        com_to_numvertices[communities[vertex]] = 1
+        density[communities[vertex]] = max_density
+    # Set up control variables and start iterating
+    iter_count = 0
+    cont = True
+    while cont and iter_count < max_iter:
+        cont = False
+        iter_count += 1
+        # Loop over all vertices in graph in a random order
+        vertices = list(G)
+        seed.shuffle(vertices)
+        for vertex in vertices:
+            # Updating rule
+            com_counter = Counter()
+            # Take into account self vertex community
+            try:
+                com_counter.update({communities[vertex]: density[communities[vertex]]})
+            except KeyError:
+                pass
+            # Gather neighbor vertex communities
+            for v in G[vertex]:
+                try:
+                    com_counter.update({communities[v]: density[communities[v]]})
+                except KeyError:
+                    continue
+            # Check which is the community with highest density
+            new_com = -1
+            if len(com_counter.keys()) > 0:
+                max_freq = max(com_counter.values())
+                best_communities = [
+                    com
+                    for com, freq in com_counter.items()
+                    if (max_freq - freq) < 0.0001
+                ]
+                # If actual vertex com in best communities, it is preserved
+                try:
+                    if communities[vertex] in best_communities:
+                        new_com = communities[vertex]
+                except KeyError:
+                    pass
+
+                # If vertex community changes...
+                if new_com == -1:
+                    # Set flag of non-convergence
+                    cont = True
+                    # Randomly chose a new community from candidates
+                    new_com = seed.choice(best_communities)
+                    # Update previous community status
+                    try:
+                        com_to_numvertices[communities[vertex]] -= 1
+                        density[communities[vertex]] = (
+                            max_density / com_to_numvertices[communities[vertex]]
+                        )
+                    except KeyError:
+                        pass
+                    # Update new community status
+                    communities[vertex] = new_com
+                    com_to_numvertices[communities[vertex]] += 1
+                    density[communities[vertex]] = (
+                        max_density / com_to_numvertices[communities[vertex]]
+                    )
+    # If maximum iterations reached --> output actual results
+    # Return results by grouping communities as list of vertices
+    return iter(groups(communities).values())

package/runtime/python/okstra_vendor/networkx/algorithms/community/bipartitions.py

@@ -0,0 +1,354 @@
+"""Functions for splitting a network into two communities (finding a bipartition)."""
+
+import random
+from copy import deepcopy
+from itertools import count
+
+import networkx as nx
+
+__all__ = [
+    "kernighan_lin_bisection",
+    "spectral_modularity_bipartition",
+    "greedy_node_swap_bipartition",
+]
+
+
+def _kernighan_lin_sweep(edge_info, side):
+    """
+    This is a modified form of Kernighan-Lin, which moves single nodes at a
+    time, alternating between sides to keep the bisection balanced.  We keep
+    two min-heaps of swap costs to make optimal-next-move selection fast.
+    """
+    heap0, heap1 = cost_heaps = nx.utils.BinaryHeap(), nx.utils.BinaryHeap()
+    # we use heap methods insert, pop, and get
+    for u, nbrs in edge_info.items():
+        cost_u = sum(wt if side[v] else -wt for v, wt in nbrs.items())
+        if side[u]:
+            heap1.insert(u, cost_u)
+        else:
+            heap0.insert(u, -cost_u)
+
+    def _update_heap_values(node):
+        side_node = side[node]
+        for nbr, wt in edge_info[node].items():
+            side_nbr = side[nbr]
+            if side_nbr == side_node:
+                wt = -wt
+            heap_nbr = cost_heaps[side_nbr]
+            if nbr in heap_nbr:
+                cost_nbr = heap_nbr.get(nbr) + 2 * wt
+                # allow_increase lets us update a value already on the heap
+                heap_nbr.insert(nbr, cost_nbr, allow_increase=True)
+
+    i = 0
+    totcost = 0
+    while heap0 and heap1:
+        u, cost_u = heap0.pop()
+        _update_heap_values(u)
+        v, cost_v = heap1.pop()
+        _update_heap_values(v)
+        totcost += cost_u + cost_v
+        i += 1
+        yield totcost, i, (u, v)
+
+
+@nx.utils.not_implemented_for("directed")
+@nx.utils.py_random_state(4)
+@nx._dispatchable(edge_attrs="weight")
+def kernighan_lin_bisection(G, partition=None, max_iter=10, weight="weight", seed=None):
+    """Partition a graph into two blocks using the Kernighan–Lin algorithm.
+
+    This algorithm partitions a network into two sets by iteratively
+    swapping pairs of nodes to reduce the edge cut between the two sets.  The
+    pairs are chosen according to a modified form of Kernighan-Lin [1]_, which
+    moves nodes individually, alternating between sides to keep the bisection
+    balanced.
+
+    Kernighan-Lin is an approximate algorithm for maximal modularity bisection.
+    In [2]_ they suggest that fine-tuned improvements can be made using
+    greedy node swapping, (see `greedy_node_swap_bipartition`).
+    The improvements are typically only a few percent of the modularity value.
+    But they claim that can make a difference between a good and excellent method.
+    This function does not perform any improvements. But you can do that yourself.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        Graph must be undirected.
+
+    partition : tuple
+        Pair of iterables containing an initial partition. If not
+        specified, a random balanced partition is used.
+
+    max_iter : int
+        Maximum number of times to attempt swaps to find an
+        improvement before giving up.
+
+    weight : string or function (default: "weight")
+        If this is a string, then edge weights will be accessed via the
+        edge attribute with this key (that is, the weight of the edge
+        joining `u` to `v` will be ``G.edges[u, v][weight]``). If no
+        such edge attribute exists, the weight of the edge is assumed to
+        be one.
+
+        If this is a function, the weight of an edge is the value
+        returned by the function. The function must accept exactly three
+        positional arguments: the two endpoints of an edge and the
+        dictionary of edge attributes for that edge. The function must
+        return a number or None to indicate a hidden edge.
+
+    seed : integer, random_state, or None (default)
+        Indicator of random number generation state.
+        See :ref:`Randomness<randomness>`.
+        Only used if partition is None
+
+    Returns
+    -------
+    partition : tuple
+        A pair of sets of nodes representing the bipartition.
+
+    Raises
+    ------
+    NetworkXError
+        If `partition` is not a valid partition of the nodes of the graph.
+
+    References
+    ----------
+    .. [1] Kernighan, B. W.; Lin, Shen (1970).
+       "An efficient heuristic procedure for partitioning graphs."
+       *Bell Systems Technical Journal* 49: 291--307.
+       Oxford University Press 2011.
+    .. [2] M. E. J. Newman,
+       "Modularity and community structure in networks",
+       PNAS, 103 (23), p. 8577-8582,
+       https://doi.org/10.1073/pnas.0601602103
+
+    """
+    nodes = list(G)
+
+    if partition is None:
+        seed.shuffle(nodes)
+        mid = len(nodes) // 2
+        A, B = nodes[:mid], nodes[mid:]
+    else:
+        try:
+            A, B = partition
+        except (TypeError, ValueError) as err:
+            raise nx.NetworkXError("partition must be two sets") from err
+        if not nx.community.is_partition(G, [A, B]):
+            raise nx.NetworkXError("partition invalid")
+
+    side = {node: (node in A) for node in nodes}
+
+    # ruff: noqa: E731   skips check for no lambda functions
+    # Using shortest_paths _weight_function with sum instead of min on multiedges
+    if callable(weight):
+        sum_weight = weight
+    elif G.is_multigraph():
+        sum_weight = lambda u, v, d: sum(dd.get(weight, 1) for dd in d.values())
+    else:
+        sum_weight = lambda u, v, d: d.get(weight, 1)
+
+    edge_info = {
+        u: {v: wt for v, d in nbrs.items() if (wt := sum_weight(u, v, d)) is not None}
+        for u, nbrs in G._adj.items()
+    }
+
+    for i in range(max_iter):
+        costs = list(_kernighan_lin_sweep(edge_info, side))
+        # find out how many edges to update: min_i
+        min_cost, min_i, _ = min(costs)
+        if min_cost >= 0:
+            break
+
+        for _, _, (u, v) in costs[:min_i]:
+            side[u] = 1
+            side[v] = 0
+
+    part1 = {u for u, s in side.items() if s == 0}
+    part2 = {u for u, s in side.items() if s == 1}
+    return part1, part2
+
+
+@nx.utils.not_implemented_for("directed")
+@nx.utils.not_implemented_for("multigraph")
+def spectral_modularity_bipartition(G):
+    r"""Return a bipartition of the nodes based on the spectrum of the
+    modularity matrix of the graph.
+
+    This method calculates the eigenvector associated with the second
+    largest eigenvalue of the modularity matrix, where the modularity
+    matrix *B* is defined by
+
+    ..math::
+
+        B_{i j} = A_{i j} - \frac{k_i k_j}{2 m},
+
+    where *A* is the adjacency matrix, `k_i` is the degree of node *i*,
+    and *m* is the number of edges in the graph. Nodes whose
+    corresponding values in the eigenvector are negative are placed in
+    one block, nodes whose values are nonnegative are placed in another
+    block.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    Returns
+    -------
+    C : tuple
+        Pair of communities as two sets of nodes of ``G``, partitioned
+        according to second largest eigenvalue of the modularity matrix.
+
+    Examples
+    --------
+    >>> G = nx.karate_club_graph()
+    >>> MrHi, Officer = nx.community.spectral_modularity_bipartition(G)
+    >>> MrHi, Officer = sorted([sorted(MrHi), sorted(Officer)])
+    >>> MrHi
+    [0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, 13, 16, 17, 19, 21]
+    >>> Officer
+    [8, 9, 14, 15, 18, 20, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33]
+
+    References
+    ----------
+    .. [1] M. E. J. Newman *Networks: An Introduction*, pages 373--378
+       Oxford University Press 2011.
+    .. [2] M. E. J. Newman,
+       "Modularity and community structure in networks",
+       PNAS, 103 (23), p. 8577-8582,
+       https://doi.org/10.1073/pnas.0601602103
+
+    """
+    import numpy as np
+
+    B = nx.linalg.modularity_matrix(G)
+    eigenvalues, eigenvectors = np.linalg.eig(B)
+    index = np.argsort(eigenvalues)[-1]
+    v2 = zip(np.real(eigenvectors[:, index]), G)
+    left, right = set(), set()
+    for u, n in v2:
+        if u < 0:
+            left.add(n)
+        else:
+            right.add(n)
+    return left, right
+
+
+@nx.utils.not_implemented_for("multigraph")
+def greedy_node_swap_bipartition(G, *, init_split=None, max_iter=10):
+    """Split the nodes into two communities based on greedy
+    modularity maximization.
+
+    The algorithm works by selecting a node to change communities which
+    will maximize the modularity. The swap is made and the community
+    structure with the highest modularity is kept.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    init_split : 2-tuple of sets of nodes
+        Pair of sets of nodes in ``G`` providing an initial bipartition
+        for the algorithm. If not specified, a random balanced partition
+        is used. If this pair of sets is not a partition of the nodes of `G`,
+        :exc:`NetworkXException` is raised.
+
+    max_iter : int
+      Maximum number of iterations of attempting swaps to find an improvement.
+
+    Returns
+    -------
+    max_split : 2-tuple of sets of nodes
+        Pair of sets of nodes of ``G``, partitioned according to a
+        node swap greedy modularity maximization algorithm.
+
+    Raises
+    ------
+    NetworkXError
+      if init_split is not a valid partition of the
+      graph into two communities or if G is a MultiGraph
+
+    Examples
+    --------
+    >>> G = nx.barbell_graph(3, 0)
+    >>> left, right = nx.community.greedy_node_swap_bipartition(G)
+    >>> # Sort the communities so the nodes appear in increasing order.
+    >>> left, right = sorted([sorted(left), sorted(right)])
+    >>> sorted(left)
+    [0, 1, 2]
+    >>> sorted(right)
+    [3, 4, 5]
+
+    Notes
+    -----
+    This function is not implemented for multigraphs.
+
+    References
+    ----------
+    .. [1] M. E. J. Newman "Networks: An Introduction", pages 373--375.
+       Oxford University Press 2011.
+
+    """
+    if init_split is None:
+        m1 = len(G) // 2
+        m2 = len(G) - m1
+        some_nodes = set(random.sample(list(G), m1))
+        other_nodes = {n for n in G if n not in some_nodes}
+        best_split_so_far = (some_nodes, other_nodes)
+    else:
+        if not nx.community.is_partition(G, init_split):
+            raise nx.NetworkXError("init_split is not a partition of G")
+        if not len(init_split) == 2:
+            raise nx.NetworkXError("init_split must be a bipartition")
+        best_split_so_far = deepcopy(init_split)
+
+    best_mod = nx.community.modularity(G, best_split_so_far)
+
+    max_split, max_mod = best_split_so_far, best_mod
+    its = 0
+    m = G.number_of_edges()
+    G_degree = dict(G.degree)
+
+    while max_mod >= best_mod and its < max_iter:
+        best_split_so_far = max_split
+        best_mod = max_mod
+        next_split = deepcopy(max_split)
+        next_mod = max_mod
+        nodes = set(G)
+        while nodes:
+            max_swap = -1
+            max_node = None
+            max_node_comm = None
+            left, right = next_split
+            leftd = sum(G_degree[n] for n in left)
+            rightd = sum(G_degree[n] for n in right)
+            for n in nodes:
+                if n in left:
+                    in_comm, out_comm = left, right
+                    in_deg, out_deg = leftd, rightd
+                else:
+                    in_comm, out_comm = right, left
+                    in_deg, out_deg = rightd, leftd
+
+                d_eii = -len(G[n].keys() & in_comm) / m
+                d_ejj = len(G[n].keys() & out_comm) / m
+                deg = G_degree[n]
+                d_sum_ai = (deg / (2 * m**2)) * (in_deg - out_deg - deg)
+                swap_change = d_eii + d_ejj + d_sum_ai
+
+                if swap_change > max_swap:
+                    max_swap = swap_change
+                    max_node = n
+                    max_node_comm = in_comm
+                    non_max_node_comm = out_comm
+            # swap the node from one comm to the other
+            max_node_comm.remove(max_node)
+            non_max_node_comm.add(max_node)
+            next_mod += max_swap
+            # deepcopy next_split each time it reaches a high (might go lower later)
+            if next_mod > max_mod:
+                max_split, max_mod = deepcopy(next_split), next_mod
+            nodes.remove(max_node)
+        its += 1
+    return best_split_so_far