passagemath-graphs 10.6.1rc1__cp310-cp310-musllinux_1_2_aarch64.whl

sage/graphs/partial_cube.py

@@ -0,0 +1,459 @@
+# sage_setup: distribution = sagemath-graphs
+r"""
+Partial cubes
+
+The code in this module that recognizes partial cubes is originally
+from the PADS library by David Eppstein, which is available at
+http://www.ics.uci.edu/~eppstein/PADS/ under the MIT license. It has a
+quadratic runtime and has been described in [Epp2008]_.
+
+For more information on partial cubes, see the :wikipedia:`Partial cube`.
+
+Recognition algorithm
+---------------------
+
+Definitions
+^^^^^^^^^^^
+
+A **partial cube** is an isometric subgraph `G` of a
+:meth:`~sage.graphs.graph_generators.GraphGenerators.CubeGraph` (of
+possibly high dimension). Consequently, the vertices of `G` can be
+labelled with binary sequences in such a way that the distance between
+two vertices `u,v\in G` is the Hamming distance between their labels.
+
+**Tokens** and their **action**: in the terminology of
+[Epp2008]_, a token represents a transition of the form:
+
+    *switch the `k`-th bit of the binary string from 0 to 1*
+
+Each token can be matched with a 'reversed' token that performs the
+same switch in the opposite direction. Alternatively, a token can be
+seen as a set of disjoint (directed) edges of `G`, corresponding to
+the transitions. When a vertex `v\in G` is the source of such an edge,
+it is said that the token *acts* on `v`.
+
+Observations
+^^^^^^^^^^^^
+
+**Shortest paths**: in a hypercube, a shortest path between two
+vertices uses each token at most once. Furthermore, it cannot use both
+a token and it reverse.
+
+**Cycles**: a cycle in a partial cube is necessarily even, as
+hypercubes are bipartite. If an edge `e` of a cycle `C` belongs to a
+token `T`, then the edge opposite to `e` in `C` belongs to the reverse
+of `T`.
+
+**Incident edges**: all `2d_G(v)` arcs incident to a given vertex
+belong to as many different tokens.
+
+Algorithm
+^^^^^^^^^
+
+**Labeling**: Iteratively, the algorithm selects a vertex `v\in G`,
+which is naturally associated to `2d(v)` tokens. It then performs a
+breadth-first search from `v`, applying the previous observation on
+cycles to attribute a token to some of the edges it meets. None of the
+edges whose token remains undecided after this step can belong to one
+of those `2d(v)` tokens, by virtue of the observation on shortest
+paths.
+
+The labeled edges can then be simplified (contracted) if the previous
+step did not lead to a contradiction, and the procedure is applied
+again until the graph is contracted to a single vertex and all edges
+are labeled.
+
+A partial cube is correctly labeled at this step, but some other
+graphs can also satisfy the procedure.
+
+**Checking the labeling**: once all tokens are defined and the
+vertices are labeled with a binary string, we check that they define
+an isometric subgraph of the hypercube. To ensure that the distance
+`d(v_0,u)` is what we expect for any vertex `u`, it is sufficient to
+find, for any vertex `u`, a neighbor `n_u` of `u` whose Hamming
+distance with `v_0` is strictly less than the Hamming distance between
+`u` and `v_0`. Here is the algorithm used to check the labeling:
+
+* For an initial vertex `v`, run a BFS starting from `v`, and
+  associate to every other vertex `u` a token that brings `u` closer
+  to `v`. This yields shortest paths from every vertex to `v`.
+
+* Assuming that the information is computed (and correct) for `v`, it
+  is easy to update it for a neighbor `v'` of `v`. Indeed, if we write
+  `T` the token that turns `v` into `v'`, only the vertices which were
+  associated with the reverse of `T` need to select a new neighbour. All
+  others can remain as they were previously.
+
+  With this second observation, one can efficiently check that the
+  distance between all pairs of vertices are what they should be. In
+  the implementation, the sequence of the sources `(v, v', ...)` is
+  given by a depth-first search.
+
+Functions
+---------
+"""
+
+
+def breadth_first_level_search(G, start):
+    r"""
+    Generate a sequence of dictionaries, each mapping the vertices at
+    distance ``i`` from ``start`` to the set of their neighbours at
+    distance ``i+1``.
+
+    Originally written by D. Eppstein for the PADS library
+    (http://www.ics.uci.edu/~eppstein/PADS/).
+
+    INPUT:
+
+    - ``G`` -- a graph to perform the search on
+
+    - ``start`` -- vertex or list of vertices from which to start the traversal
+
+    EXAMPLES::
+
+        sage: H = digraphs.DeBruijn(3,2)                                                # needs sage.combinat
+        sage: list(sage.graphs.partial_cube.breadth_first_level_search(H, '00'))        # needs sage.combinat
+        [{'00': {'01', '02'}},
+         {'01': {'10', '11', '12'}, '02': {'20', '21', '22'}},
+         {'10': set(),
+          '11': set(),
+          '12': set(),
+          '20': set(),
+          '21': set(),
+          '22': set()}]
+    """
+    neighbors = G.neighbor_out_iterator
+    visited = set()
+    if isinstance(start, list):
+        currentLevel = start
+    else:
+        currentLevel = [start]
+    while currentLevel:
+        visited.update(currentLevel)
+        nextLevel = set()
+        levelGraph = {v: set() for v in currentLevel}
+        for v in currentLevel:
+            for w in neighbors(v):
+                if w not in visited:
+                    levelGraph[v].add(w)
+                    nextLevel.add(w)
+        yield levelGraph
+        currentLevel = nextLevel
+
+
+def depth_first_traversal(G, start):
+    r"""
+    Generate a sequence of triples (v,w,edgetype) for DFS of graph G.
+
+    Originally written by D. Eppstein for the PADS library
+    (http://www.ics.uci.edu/~eppstein/PADS/).
+
+    INPUT:
+
+    - ``G`` -- a graph to perform the search on
+
+    - ``start`` -- vertex or list of vertices from which to start the traversal
+
+    OUTPUT:
+
+    - a generator of triples ``(v,w,edgetype)``, where ``edgetype`` is ``True``
+      if the algorithm is progressing via the edge ``vw``, or ``False`` if the
+      algorithm is backtracking via the edge ``wv``.
+
+    EXAMPLES::
+
+        sage: H = digraphs.DeBruijn(3,2)                                                # needs sage.combinat
+        sage: t = list(sage.graphs.partial_cube.depth_first_traversal(H, '00'))         # needs sage.combinat
+        sage: len(t)                                                                    # needs sage.combinat
+        16
+    """
+    neighbors = G.neighbor_out_iterator
+    seen = set()
+    if not isinstance(start, list):
+        start = [start]
+
+    for v in start:
+        if v in seen:
+            continue
+        seen.add(v)
+        stack = [(v, neighbors(v))]
+        while stack:
+            parent, children = stack[-1]
+            try:
+                child = next(children)
+                if child not in seen:
+                    yield (parent, child, True)
+                    seen.add(child)
+                    stack.append((child, neighbors(child)))
+            except StopIteration:
+                stack.pop()
+                if stack:
+                    yield (stack[-1][0], parent, False)
+
+
+def is_partial_cube(G, certificate=False):
+    r"""
+    Test whether the given graph is a partial cube.
+
+    A partial cube is a graph that can be isometrically embedded into a
+    hypercube, i.e., its vertices can be labelled with (0,1)-vectors of some
+    fixed length such that the distance between any two vertices in the graph
+    equals the Hamming distance of their labels.
+
+    Originally written by D. Eppstein for the PADS library
+    (http://www.ics.uci.edu/~eppstein/PADS/), see also
+    [Epp2008]_.  The algorithm runs in `O(n^2)` time, where `n`
+    is the number of vertices. See the documentation of
+    :mod:`~sage.graphs.partial_cube` for an overview of the algorithm.
+
+    INPUT:
+
+    - ``certificate`` -- boolean (default: ``False``); this function returns
+      ``True`` or ``False`` according to the graph, when ``certificate =
+      False``. When ``certificate = True`` and the graph is a partial cube, the
+      function returns ``(True, mapping)``, where ``mapping`` is an isometric
+      mapping of the vertices of the graph to the vertices of a hypercube
+      ((0, 1)-strings of a fixed length). When ``certificate = True`` and the
+      graph is not a partial cube, ``(False, None)`` is returned.
+
+    EXAMPLES:
+
+    The Petersen graph is not a partial cube::
+
+        sage: g = graphs.PetersenGraph()
+        sage: g.is_partial_cube()
+        False
+
+    All prisms are partial cubes::
+
+        sage: g = graphs.CycleGraph(10).cartesian_product(graphs.CompleteGraph(2))
+        sage: g.is_partial_cube()
+        True
+
+    TESTS:
+
+    The returned mapping is an isometric embedding into a hypercube::
+
+        sage: g = graphs.DesarguesGraph()
+        sage: _, m = g.is_partial_cube(certificate=True)
+        sage: m # random
+        {0: '00000',
+         1: '00001',
+         2: '00011',
+         3: '01011',
+         4: '11011',
+         5: '11111',
+         6: '11110',
+         7: '11100',
+         8: '10100',
+         9: '00100',
+         10: '01000',
+         11: '10001',
+         12: '00111',
+         13: '01010',
+         14: '11001',
+         15: '10111',
+         16: '01110',
+         17: '11000',
+         18: '10101',
+         19: '00110'}
+        sage: all(all(g.distance(u, v) == len([i for i in range(len(m[u])) if m[u][i] != m[v][i]]) for v in m) for u in m)
+        True
+
+    A graph without vertices is trivially a partial cube::
+
+        sage: Graph().is_partial_cube(certificate=True)
+        (True, {})
+    """
+    G._scream_if_not_simple()
+
+    if not G.order():
+        if certificate:
+            return (True, {})
+        else:
+            return True
+
+    if certificate:
+        fail = (False, None)
+    else:
+        fail = False
+
+    if not G.is_connected():
+        return fail
+    n = G.order()
+
+    # Initial sanity check: are there few enough edges?
+    # Needed so that we don't try to use union-find on a dense
+    # graph and incur superquadratic runtimes.
+    if 1 << (2 * G.size() // n) > n:
+        return fail
+
+    # Check for bipartiteness.
+    # This ensures also that each contraction will be bipartite.
+    if not G.is_bipartite():
+        return fail
+
+    # Set up data structures for algorithm:
+    # - contracted: contracted graph at current stage of algorithm
+    # - unionfind: union find data structure representing known edge equivalences
+    # - available: limit on number of remaining available labels
+    from sage.graphs.digraph import DiGraph
+    from sage.graphs.graph import Graph
+    from sage.sets.disjoint_set import DisjointSet
+    contracted = DiGraph({v: {w: (v, w) for w in G[v]} for v in G})
+    unionfind = DisjointSet(contracted.edges(sort=True, labels=False))
+    available = n - 1
+
+    # Main contraction loop in place of the original algorithm's recursion
+    while contracted.order() > 1:
+        # Find max degree vertex in contracted, and update label limit
+        deg, root = max([(contracted.out_degree(v), v) for v in contracted], key=lambda x: x[0])
+        if deg > available:
+            return fail
+        available -= deg
+
+        # Set up bitvectors on vertices
+        bitvec = {v: 0 for v in contracted}
+        neighbors = {}
+        for i, neighbor in enumerate(contracted[root]):
+            bitvec[neighbor] = 1 << i
+            neighbors[1 << i] = neighbor
+
+        # Breadth first search to propagate bitvectors to the rest of the graph
+        for level in breadth_first_level_search(contracted, root):
+            for v in level:
+                for w in level[v]:
+                    bitvec[w] |= bitvec[v]
+
+        # Make graph of labeled edges and union them together
+        labeled = Graph([contracted.vertices(sort=False), []])
+        for v, w in contracted.edge_iterator(labels=False):
+            diff = bitvec[v] ^ bitvec[w]
+            if not diff or not bitvec[w] & ~bitvec[v]:
+                continue    # zero edge or wrong direction
+            if diff not in neighbors:
+                return fail
+            neighbor = neighbors[diff]
+            unionfind.union(contracted.edge_label(v, w),
+                            contracted.edge_label(root, neighbor))
+            unionfind.union(contracted.edge_label(w, v),
+                            contracted.edge_label(neighbor, root))
+            labeled.add_edge(v, w)
+
+        # Map vertices to components of labeled-edge graph
+        component = {}
+        for i, SCC in enumerate(labeled.connected_components(sort=False)):
+            for v in SCC:
+                component[v] = i
+
+        # generate new compressed subgraph
+        newgraph = DiGraph()
+        for v, w, t in contracted.edge_iterator():
+            if bitvec[v] == bitvec[w]:
+                vi = component[v]
+                wi = component[w]
+                if vi == wi:
+                    return fail
+                if newgraph.has_edge(vi, wi):
+                    unionfind.union(newgraph.edge_label(vi, wi), t)
+                else:
+                    newgraph.add_edge(vi, wi, t)
+        contracted = newgraph
+
+    # Make a digraph with edges labeled by the equivalence classes in unionfind
+    g = DiGraph({v: {w: unionfind.find((v, w)) for w in G[v]} for v in G})
+
+    # Associates to a vertex the token that acts on it, and check that
+    # no two edges on a single vertex have the same label
+    action = {}
+    for v in g:
+        action[v] = set(t for _, _, t in g.edge_iterator(v))
+        if len(action[v]) != g.out_degree(v):
+            return fail
+
+    # Associate every token to its reverse
+    reverse = {}
+    for v, w, t in g.edge_iterator():
+        rt = g.edge_label(w, v)
+        reverse[t] = rt
+        reverse[rt] = t
+
+    current = initialState = next(g.vertex_iterator())
+
+    # A token T is said to be 'active' for a vertex u if it takes u
+    # one step closer to the source in terms of distance. The 'source'
+    # is initially 'initialState'. See the module's documentation for
+    # more explanations.
+
+    # Find list of tokens that lead to the initial state
+    activeTokens = set()
+    for level in breadth_first_level_search(g, initialState):
+        for v in level:
+            for w in level[v]:
+                activeTokens.add(g.edge_label(w, v))
+    for t in activeTokens:
+        if reverse[t] in activeTokens:
+            return fail
+    activeTokens = list(activeTokens)
+
+    # Rest of data structure: point from states to list and list to states
+    state_to_active_token = {v: -1 for v in g}
+    token_to_states = [[] for _ in activeTokens]  # (i.e. vertices on which each token acts)
+
+    def scan(v):
+        """
+        Find the next token that is effective for v.
+        """
+        a = next(i for i in range(state_to_active_token[v] + 1, len(activeTokens))
+                 if activeTokens[i] is not None and activeTokens[i] in action[v])
+        state_to_active_token[v] = a
+        token_to_states[a].append(v)
+
+    # Initialize isometric embedding into a hypercube
+    if certificate:
+        dim = 0
+        tokmap = {}
+        for t in reverse:
+            if t not in tokmap:
+                tokmap[t] = tokmap[reverse[t]] = 1 << dim
+                dim += 1
+        embed = {initialState: 0}
+
+    # Set initial active states
+    for v in g:
+        if v != current:
+            try:
+                scan(v)
+            except StopIteration:
+                return fail
+
+    # Traverse the graph, maintaining active tokens
+    for prev, current, fwd in depth_first_traversal(g, initialState):
+        if not fwd:
+            prev, current = current, prev
+        elif certificate:
+            embed[current] = embed[prev] ^ tokmap[g.edge_label(prev, current)]
+
+        # Add token to end of list, point to it from old state
+        activeTokens.append(g.edge_label(prev, current))
+        state_to_active_token[prev] = len(activeTokens) - 1
+        token_to_states.append([prev])
+
+        # Deactivate reverse token, find new token for its states
+        #
+        # (the 'active' token of 'current' is necessarily the label of
+        #  (current, previous))
+        activeTokens[state_to_active_token[current]] = None
+        for v in token_to_states[state_to_active_token[current]]:
+            if v != current:
+                try:
+                    scan(v)
+                except StopIteration:
+                    return fail
+
+    # All checks passed, return the result
+    if certificate:
+        format = "{0:0%db}" % dim
+        return (True, {v: format.format(l) for v, l in embed.items()})
+    else:
+        return True