okstra 0.130.3 → 0.131.0

package/runtime/python/okstra_vendor/networkx/generators/joint_degree_seq.py

@@ -1,664 +0,0 @@
-"""Generate graphs with a given joint degree and directed joint degree"""
-
-import networkx as nx
-from networkx.utils import py_random_state
-
-__all__ = [
-    "is_valid_joint_degree",
-    "is_valid_directed_joint_degree",
-    "joint_degree_graph",
-    "directed_joint_degree_graph",
-]
-
-
-@nx._dispatchable(graphs=None)
-def is_valid_joint_degree(joint_degrees):
-    """Checks whether the given joint degree dictionary is realizable.
-
-    A *joint degree dictionary* is a dictionary of dictionaries, in
-    which entry ``joint_degrees[k][l]`` is an integer representing the
-    number of edges joining nodes of degree *k* with nodes of degree
-    *l*. Such a dictionary is realizable as a simple graph if and only
-    if the following conditions are satisfied.
-
-    - each entry must be an integer,
-    - the total number of nodes of degree *k*, computed by
-      ``sum(joint_degrees[k].values()) / k``, must be an integer,
-    - the total number of edges joining nodes of degree *k* with
-      nodes of degree *l* cannot exceed the total number of possible edges,
-    - each diagonal entry ``joint_degrees[k][k]`` must be even (this is
-      a convention assumed by the :func:`joint_degree_graph` function).
-
-
-    Parameters
-    ----------
-    joint_degrees :  dictionary of dictionary of integers
-        A joint degree dictionary in which entry ``joint_degrees[k][l]``
-        is the number of edges joining nodes of degree *k* with nodes of
-        degree *l*.
-
-    Returns
-    -------
-    bool
-        Whether the given joint degree dictionary is realizable as a
-        simple graph.
-
-    References
-    ----------
-    .. [1] M. Gjoka, M. Kurant, A. Markopoulou, "2.5K Graphs: from Sampling
-       to Generation", IEEE Infocom, 2013.
-    .. [2] I. Stanton, A. Pinar, "Constructing and sampling graphs with a
-       prescribed joint degree distribution", Journal of Experimental
-       Algorithmics, 2012.
-    """
-
-    degree_count = {}
-    for k in joint_degrees:
-        if k > 0:
-            k_size = sum(joint_degrees[k].values()) / k
-            if not k_size.is_integer():
-                return False
-            degree_count[k] = k_size
-
-    for k in joint_degrees:
-        for l in joint_degrees[k]:
-            if not float(joint_degrees[k][l]).is_integer():
-                return False
-
-            if (k != l) and (joint_degrees[k][l] > degree_count[k] * degree_count[l]):
-                return False
-            elif k == l:
-                if joint_degrees[k][k] > degree_count[k] * (degree_count[k] - 1):
-                    return False
-                if joint_degrees[k][k] % 2 != 0:
-                    return False
-
-    # if all above conditions have been satisfied then the input
-    # joint degree is realizable as a simple graph.
-    return True
-
-
-def _neighbor_switch(G, w, unsat, h_node_residual, avoid_node_id=None):
-    """Releases one free stub for ``w``, while preserving joint degree in G.
-
-    Parameters
-    ----------
-    G : NetworkX graph
-        Graph in which the neighbor switch will take place.
-    w : integer
-        Node id for which we will execute this neighbor switch.
-    unsat : set of integers
-        Set of unsaturated node ids that have the same degree as w.
-    h_node_residual: dictionary of integers
-        Keeps track of the remaining stubs  for a given node.
-    avoid_node_id: integer
-        Node id to avoid when selecting w_prime.
-
-    Notes
-    -----
-    First, it selects *w_prime*, an  unsaturated node that has the same degree
-    as ``w``. Second, it selects *switch_node*, a neighbor node of ``w`` that
-    is not  connected to *w_prime*. Then it executes an edge swap i.e. removes
-    (``w``,*switch_node*) and adds (*w_prime*,*switch_node*). Gjoka et. al. [1]
-    prove that such an edge swap is always possible.
-
-    References
-    ----------
-    .. [1] M. Gjoka, B. Tillman, A. Markopoulou, "Construction of Simple
-       Graphs with a Target Joint Degree Matrix and Beyond", IEEE Infocom, '15
-    """
-
-    if (avoid_node_id is None) or (h_node_residual[avoid_node_id] > 1):
-        # select unsaturated node w_prime that has the same degree as w
-        w_prime = next(iter(unsat))
-    else:
-        # assume that the node pair (v,w) has been selected for connection. if
-        # - neighbor_switch is called for node w,
-        # - nodes v and w have the same degree,
-        # - node v=avoid_node_id has only one stub left,
-        # then prevent v=avoid_node_id from being selected as w_prime.
-
-        iter_var = iter(unsat)
-        while True:
-            w_prime = next(iter_var)
-            if w_prime != avoid_node_id:
-                break
-
-    # select switch_node, a neighbor of w, that is not connected to w_prime
-    w_prime_neighbs = G[w_prime]  # slightly faster declaring this variable
-    for v in G[w]:
-        if (v not in w_prime_neighbs) and (v != w_prime):
-            switch_node = v
-            break
-
-    # remove edge (w,switch_node), add edge (w_prime,switch_node) and update
-    # data structures
-    G.remove_edge(w, switch_node)
-    G.add_edge(w_prime, switch_node)
-    h_node_residual[w] += 1
-    h_node_residual[w_prime] -= 1
-    if h_node_residual[w_prime] == 0:
-        unsat.remove(w_prime)
-
-
-@py_random_state(1)
-@nx._dispatchable(graphs=None, returns_graph=True)
-def joint_degree_graph(joint_degrees, seed=None):
-    """Generates a random simple graph with the given joint degree dictionary.
-
-    Parameters
-    ----------
-    joint_degrees :  dictionary of dictionary of integers
-        A joint degree dictionary in which entry ``joint_degrees[k][l]`` is the
-        number of edges joining nodes of degree *k* with nodes of degree *l*.
-    seed : integer, random_state, or None (default)
-        Indicator of random number generation state.
-        See :ref:`Randomness<randomness>`.
-
-    Returns
-    -------
-    G : Graph
-        A graph with the specified joint degree dictionary.
-
-    Raises
-    ------
-    NetworkXError
-        If *joint_degrees* dictionary is not realizable.
-
-    Notes
-    -----
-    In each iteration of the "while loop" the algorithm picks two disconnected
-    nodes *v* and *w*, of degree *k* and *l* correspondingly,  for which
-    ``joint_degrees[k][l]`` has not reached its target yet. It then adds
-    edge (*v*, *w*) and increases the number of edges in graph G by one.
-
-    The intelligence of the algorithm lies in the fact that  it is always
-    possible to add an edge between such disconnected nodes *v* and *w*,
-    even if one or both nodes do not have free stubs. That is made possible by
-    executing a "neighbor switch", an edge rewiring move that releases
-    a free stub while keeping the joint degree of G the same.
-
-    The algorithm continues for E (number of edges) iterations of
-    the "while loop", at the which point all entries of the given
-    ``joint_degrees[k][l]`` have reached their target values and the
-    construction is complete.
-
-    References
-    ----------
-    ..  [1] M. Gjoka, B. Tillman, A. Markopoulou, "Construction of Simple
-        Graphs with a Target Joint Degree Matrix and Beyond", IEEE Infocom, '15
-
-    Examples
-    --------
-    >>> joint_degrees = {
-    ...     1: {4: 1},
-    ...     2: {2: 2, 3: 2, 4: 2},
-    ...     3: {2: 2, 4: 1},
-    ...     4: {1: 1, 2: 2, 3: 1},
-    ... }
-    >>> G = nx.joint_degree_graph(joint_degrees)
-    >>>
-    """
-
-    if not is_valid_joint_degree(joint_degrees):
-        msg = "Input joint degree dict not realizable as a simple graph"
-        raise nx.NetworkXError(msg)
-
-    # compute degree count from joint_degrees
-    degree_count = {k: sum(l.values()) // k for k, l in joint_degrees.items() if k > 0}
-
-    # start with empty N-node graph
-    N = sum(degree_count.values())
-    G = nx.empty_graph(N)
-
-    # for a given degree group, keep the list of all node ids
-    h_degree_nodelist = {}
-
-    # for a given node, keep track of the remaining stubs
-    h_node_residual = {}
-
-    # populate h_degree_nodelist and h_node_residual
-    nodeid = 0
-    for degree, num_nodes in degree_count.items():
-        h_degree_nodelist[degree] = range(nodeid, nodeid + num_nodes)
-        for v in h_degree_nodelist[degree]:
-            h_node_residual[v] = degree
-        nodeid += int(num_nodes)
-
-    # iterate over every degree pair (k,l) and add the number of edges given
-    # for each pair
-    for k in joint_degrees:
-        for l in joint_degrees[k]:
-            # n_edges_add is the number of edges to add for the
-            # degree pair (k,l)
-            n_edges_add = joint_degrees[k][l]
-
-            if (n_edges_add > 0) and (k >= l):
-                # number of nodes with degree k and l
-                k_size = degree_count[k]
-                l_size = degree_count[l]
-
-                # k_nodes and l_nodes consist of all nodes of degree k and l
-                k_nodes = h_degree_nodelist[k]
-                l_nodes = h_degree_nodelist[l]
-
-                # k_unsat and l_unsat consist of nodes of degree k and l that
-                # are unsaturated (nodes that have at least 1 available stub)
-                k_unsat = {v for v in k_nodes if h_node_residual[v] > 0}
-
-                if k != l:
-                    l_unsat = {w for w in l_nodes if h_node_residual[w] > 0}
-                else:
-                    l_unsat = k_unsat
-                    n_edges_add = joint_degrees[k][l] // 2
-
-                while n_edges_add > 0:
-                    # randomly pick nodes v and w that have degrees k and l
-                    v = k_nodes[seed.randrange(k_size)]
-                    w = l_nodes[seed.randrange(l_size)]
-
-                    # if nodes v and w are disconnected then attempt to connect
-                    if not G.has_edge(v, w) and (v != w):
-                        # if node v has no free stubs then do neighbor switch
-                        if h_node_residual[v] == 0:
-                            _neighbor_switch(G, v, k_unsat, h_node_residual)
-
-                        # if node w has no free stubs then do neighbor switch
-                        if h_node_residual[w] == 0:
-                            if k != l:
-                                _neighbor_switch(G, w, l_unsat, h_node_residual)
-                            else:
-                                _neighbor_switch(
-                                    G, w, l_unsat, h_node_residual, avoid_node_id=v
-                                )
-
-                        # add edge (v, w) and update data structures
-                        G.add_edge(v, w)
-                        h_node_residual[v] -= 1
-                        h_node_residual[w] -= 1
-                        n_edges_add -= 1
-
-                        if h_node_residual[v] == 0:
-                            k_unsat.discard(v)
-                        if h_node_residual[w] == 0:
-                            l_unsat.discard(w)
-    return G
-
-
-@nx._dispatchable(graphs=None)
-def is_valid_directed_joint_degree(in_degrees, out_degrees, nkk):
-    """Checks whether the given directed joint degree input is realizable
-
-    Parameters
-    ----------
-    in_degrees :  list of integers
-        in degree sequence contains the in degrees of nodes.
-    out_degrees : list of integers
-        out degree sequence contains the out degrees of nodes.
-    nkk  :  dictionary of dictionary of integers
-        directed joint degree dictionary. for nodes of out degree k (first
-        level of dict) and nodes of in degree l (second level of dict)
-        describes the number of edges.
-
-    Returns
-    -------
-    boolean
-        returns true if given input is realizable, else returns false.
-
-    Notes
-    -----
-    Here is the list of conditions that the inputs (in/out degree sequences,
-    nkk) need to satisfy for simple directed graph realizability:
-
-    - Condition 0: in_degrees and out_degrees have the same length
-    - Condition 1: nkk[k][l]  is integer for all k,l
-    - Condition 2: sum(nkk[k])/k = number of nodes with partition id k, is an
-                   integer and matching degree sequence
-    - Condition 3: number of edges and non-chords between k and l cannot exceed
-                   maximum possible number of edges
-
-
-    References
-    ----------
-    [1] B. Tillman, A. Markopoulou, C. T. Butts & M. Gjoka,
-        "Construction of Directed 2K Graphs". In Proc. of KDD 2017.
-    """
-    V = {}  # number of nodes with in/out degree.
-    forbidden = {}
-    if len(in_degrees) != len(out_degrees):
-        return False
-
-    for idx in range(len(in_degrees)):
-        i = in_degrees[idx]
-        o = out_degrees[idx]
-        V[(i, 0)] = V.get((i, 0), 0) + 1
-        V[(o, 1)] = V.get((o, 1), 0) + 1
-
-        forbidden[(o, i)] = forbidden.get((o, i), 0) + 1
-
-    S = {}  # number of edges going from in/out degree nodes.
-    for k in nkk:
-        for l in nkk[k]:
-            val = nkk[k][l]
-            if not float(val).is_integer():  # condition 1
-                return False
-
-            if val > 0:
-                S[(k, 1)] = S.get((k, 1), 0) + val
-                S[(l, 0)] = S.get((l, 0), 0) + val
-                # condition 3
-                if val + forbidden.get((k, l), 0) > V[(k, 1)] * V[(l, 0)]:
-                    return False
-
-    return all(S[s] / s[0] == V[s] for s in S)
-
-
-def _directed_neighbor_switch(
-    G, w, unsat, h_node_residual_out, chords, h_partition_in, partition
-):
-    """Releases one free stub for node w, while preserving joint degree in G.
-
-    Parameters
-    ----------
-    G : networkx directed graph
-        graph within which the edge swap will take place.
-    w : integer
-        node id for which we need to perform a neighbor switch.
-    unsat: set of integers
-        set of node ids that have the same degree as w and are unsaturated.
-    h_node_residual_out: dict of integers
-        for a given node, keeps track of the remaining stubs to be added.
-    chords: set of tuples
-        keeps track of available positions to add edges.
-    h_partition_in: dict of integers
-        for a given node, keeps track of its partition id (in degree).
-    partition: integer
-        partition id to check if chords have to be updated.
-
-    Notes
-    -----
-    First, it selects node w_prime that (1) has the same degree as w and
-    (2) is unsaturated. Then, it selects node v, a neighbor of w, that is
-    not connected to w_prime and does an edge swap i.e. removes (w,v) and
-    adds (w_prime,v). If neighbor switch is not possible for w using
-    w_prime and v, then return w_prime; in [1] it's proven that
-    such unsaturated nodes can be used.
-
-    References
-    ----------
-    [1] B. Tillman, A. Markopoulou, C. T. Butts & M. Gjoka,
-        "Construction of Directed 2K Graphs". In Proc. of KDD 2017.
-    """
-    w_prime = unsat.pop()
-    unsat.add(w_prime)
-    # select node t, a neighbor of w, that is not connected to w_prime
-    w_neighbs = list(G.successors(w))
-    # slightly faster declaring this variable
-    w_prime_neighbs = list(G.successors(w_prime))
-
-    for v in w_neighbs:
-        if (v not in w_prime_neighbs) and w_prime != v:
-            # removes (w,v), add (w_prime,v)  and update data structures
-            G.remove_edge(w, v)
-            G.add_edge(w_prime, v)
-
-            if h_partition_in[v] == partition:
-                chords.add((w, v))
-                chords.discard((w_prime, v))
-
-            h_node_residual_out[w] += 1
-            h_node_residual_out[w_prime] -= 1
-            if h_node_residual_out[w_prime] == 0:
-                unsat.remove(w_prime)
-            return None
-
-    # If neighbor switch didn't work, use unsaturated node
-    return w_prime
-
-
-def _directed_neighbor_switch_rev(
-    G, w, unsat, h_node_residual_in, chords, h_partition_out, partition
-):
-    """The reverse of directed_neighbor_switch.
-
-    Parameters
-    ----------
-    G : networkx directed graph
-        graph within which the edge swap will take place.
-    w : integer
-        node id for which we need to perform a neighbor switch.
-    unsat: set of integers
-        set of node ids that have the same degree as w and are unsaturated.
-    h_node_residual_in: dict of integers
-        for a given node, keeps track of the remaining stubs to be added.
-    chords: set of tuples
-        keeps track of available positions to add edges.
-    h_partition_out: dict of integers
-        for a given node, keeps track of its partition id (out degree).
-    partition: integer
-        partition id to check if chords have to be updated.
-
-    Notes
-    -----
-    Same operation as directed_neighbor_switch except it handles this operation
-    for incoming edges instead of outgoing.
-    """
-    w_prime = unsat.pop()
-    unsat.add(w_prime)
-    # slightly faster declaring these as variables.
-    w_neighbs = list(G.predecessors(w))
-    w_prime_neighbs = list(G.predecessors(w_prime))
-    # select node v, a neighbor of w, that is not connected to w_prime.
-    for v in w_neighbs:
-        if (v not in w_prime_neighbs) and w_prime != v:
-            # removes (v,w), add (v,w_prime) and update data structures.
-            G.remove_edge(v, w)
-            G.add_edge(v, w_prime)
-            if h_partition_out[v] == partition:
-                chords.add((v, w))
-                chords.discard((v, w_prime))
-
-            h_node_residual_in[w] += 1
-            h_node_residual_in[w_prime] -= 1
-            if h_node_residual_in[w_prime] == 0:
-                unsat.remove(w_prime)
-            return None
-
-    # If neighbor switch didn't work, use the unsaturated node.
-    return w_prime
-
-
-@py_random_state(3)
-@nx._dispatchable(graphs=None, returns_graph=True)
-def directed_joint_degree_graph(in_degrees, out_degrees, nkk, seed=None):
-    """Generates a random simple directed graph with the joint degree.
-
-    Parameters
-    ----------
-    degree_seq :  list of tuples (of size 3)
-        degree sequence contains tuples of nodes with node id, in degree and
-        out degree.
-    nkk  :  dictionary of dictionary of integers
-        directed joint degree dictionary, for nodes of out degree k (first
-        level of dict) and nodes of in degree l (second level of dict)
-        describes the number of edges.
-    seed : hashable object, optional
-        Seed for random number generator.
-
-    Returns
-    -------
-    G : Graph
-        A directed graph with the specified inputs.
-
-    Raises
-    ------
-    NetworkXError
-        If degree_seq and nkk are not realizable as a simple directed graph.
-
-
-    Notes
-    -----
-    Similarly to the undirected version:
-    In each iteration of the "while loop" the algorithm picks two disconnected
-    nodes v and w, of degree k and l correspondingly,  for which nkk[k][l] has
-    not reached its target yet i.e. (for given k,l): n_edges_add < nkk[k][l].
-    It then adds edge (v,w) and always increases the number of edges in graph G
-    by one.
-
-    The intelligence of the algorithm lies in the fact that  it is always
-    possible to add an edge between disconnected nodes v and w, for which
-    nkk[degree(v)][degree(w)] has not reached its target, even if one or both
-    nodes do not have free stubs. If either node v or w does not have a free
-    stub, we perform a "neighbor switch", an edge rewiring move that releases a
-    free stub while keeping nkk the same.
-
-    The difference for the directed version lies in the fact that neighbor
-    switches might not be able to rewire, but in these cases unsaturated nodes
-    can be reassigned to use instead, see [1] for detailed description and
-    proofs.
-
-    The algorithm continues for E (number of edges in the graph) iterations of
-    the "while loop", at which point all entries of the given nkk[k][l] have
-    reached their target values and the construction is complete.
-
-    References
-    ----------
-    [1] B. Tillman, A. Markopoulou, C. T. Butts & M. Gjoka,
-        "Construction of Directed 2K Graphs". In Proc. of KDD 2017.
-
-    Examples
-    --------
-    >>> in_degrees = [0, 1, 1, 2]
-    >>> out_degrees = [1, 1, 1, 1]
-    >>> nkk = {1: {1: 2, 2: 2}}
-    >>> G = nx.directed_joint_degree_graph(in_degrees, out_degrees, nkk)
-    >>>
-    """
-    if not is_valid_directed_joint_degree(in_degrees, out_degrees, nkk):
-        msg = "Input is not realizable as a simple graph"
-        raise nx.NetworkXError(msg)
-
-    # start with an empty directed graph.
-    G = nx.DiGraph()
-
-    # for a given group, keep the list of all node ids.
-    h_degree_nodelist_in = {}
-    h_degree_nodelist_out = {}
-    # for a given group, keep the list of all unsaturated node ids.
-    h_degree_nodelist_in_unsat = {}
-    h_degree_nodelist_out_unsat = {}
-    # for a given node, keep track of the remaining stubs to be added.
-    h_node_residual_out = {}
-    h_node_residual_in = {}
-    # for a given node, keep track of the partition id.
-    h_partition_out = {}
-    h_partition_in = {}
-    # keep track of non-chords between pairs of partition ids.
-    non_chords = {}
-
-    # populate data structures
-    for idx, i in enumerate(in_degrees):
-        idx = int(idx)
-        if i > 0:
-            h_degree_nodelist_in.setdefault(i, [])
-            h_degree_nodelist_in_unsat.setdefault(i, set())
-            h_degree_nodelist_in[i].append(idx)
-            h_degree_nodelist_in_unsat[i].add(idx)
-            h_node_residual_in[idx] = i
-            h_partition_in[idx] = i
-
-    for idx, o in enumerate(out_degrees):
-        o = out_degrees[idx]
-        non_chords[(o, in_degrees[idx])] = non_chords.get((o, in_degrees[idx]), 0) + 1
-        idx = int(idx)
-        if o > 0:
-            h_degree_nodelist_out.setdefault(o, [])
-            h_degree_nodelist_out_unsat.setdefault(o, set())
-            h_degree_nodelist_out[o].append(idx)
-            h_degree_nodelist_out_unsat[o].add(idx)
-            h_node_residual_out[idx] = o
-            h_partition_out[idx] = o
-
-        G.add_node(idx)
-
-    nk_in = {}
-    nk_out = {}
-    for p in h_degree_nodelist_in:
-        nk_in[p] = len(h_degree_nodelist_in[p])
-    for p in h_degree_nodelist_out:
-        nk_out[p] = len(h_degree_nodelist_out[p])
-
-    # iterate over every degree pair (k,l) and add the number of edges given
-    # for each pair.
-    for k in nkk:
-        for l in nkk[k]:
-            n_edges_add = nkk[k][l]
-
-            if n_edges_add > 0:
-                # chords contains a random set of potential edges.
-                chords = set()
-
-                k_len = nk_out[k]
-                l_len = nk_in[l]
-                chords_sample = seed.sample(
-                    range(k_len * l_len), n_edges_add + non_chords.get((k, l), 0)
-                )
-
-                num = 0
-                while len(chords) < n_edges_add:
-                    i = h_degree_nodelist_out[k][chords_sample[num] % k_len]
-                    j = h_degree_nodelist_in[l][chords_sample[num] // k_len]
-                    num += 1
-                    if i != j:
-                        chords.add((i, j))
-
-                # k_unsat and l_unsat consist of nodes of in/out degree k and l
-                # that are unsaturated i.e. those nodes that have at least one
-                # available stub
-                k_unsat = h_degree_nodelist_out_unsat[k]
-                l_unsat = h_degree_nodelist_in_unsat[l]
-
-                while n_edges_add > 0:
-                    v, w = chords.pop()
-                    chords.add((v, w))
-
-                    # if node v has no free stubs then do neighbor switch.
-                    if h_node_residual_out[v] == 0:
-                        _v = _directed_neighbor_switch(
-                            G,
-                            v,
-                            k_unsat,
-                            h_node_residual_out,
-                            chords,
-                            h_partition_in,
-                            l,
-                        )
-                        if _v is not None:
-                            v = _v
-
-                    # if node w has no free stubs then do neighbor switch.
-                    if h_node_residual_in[w] == 0:
-                        _w = _directed_neighbor_switch_rev(
-                            G,
-                            w,
-                            l_unsat,
-                            h_node_residual_in,
-                            chords,
-                            h_partition_out,
-                            k,
-                        )
-                        if _w is not None:
-                            w = _w
-
-                    # add edge (v,w) and update data structures.
-                    G.add_edge(v, w)
-                    h_node_residual_out[v] -= 1
-                    h_node_residual_in[w] -= 1
-                    n_edges_add -= 1
-                    chords.discard((v, w))
-
-                    if h_node_residual_out[v] == 0:
-                        k_unsat.discard(v)
-                    if h_node_residual_in[w] == 0:
-                        l_unsat.discard(w)
-    return G