passagemath-graphs 10.6.1rc1__cp310-cp310-musllinux_1_2_aarch64.whl

sage/graphs/base/overview.py

@@ -0,0 +1,85 @@
+# sage_setup: distribution = sagemath-graphs
+r"""
+Overview of (di)graph data structures
+
+This module contains no code, and describes Sage's data structures for graphs
+and digraphs. They can be used directly at Cython/C level, or through the
+:class:`Graph` and :class:`DiGraph` classes (except one)
+
+Data structures
+---------------
+
+Four data structures are natively available for (di)graphs in Sage:
+
+- :mod:`~sage.graphs.base.sparse_graph` (default) -- for sparse (di)graphs, with
+  a `\log(n)` edge test, and easy enumeration of neighbors. It is the most
+  general-purpose data structure, though it can have a high memory cost in
+  practice.
+
+  - Supports: Addition/removal of edges/vertices, multiple edges, edge labels
+    and loops.
+
+- :mod:`~sage.graphs.base.dense_graph` -- for dense (di)graphs, with a `O(1)`
+  edge test, and slow enumeration of neighbors.
+
+  - Supports: addition/removal of edges/vertices, and loops.
+  - Does not support: multiple edges and edge labels.
+
+- :mod:`~sage.graphs.base.static_sparse_graph` -- for sparse (di)graphs and very
+  intensive computations (at C-level). It is faster than
+  :mod:`~sage.graphs.base.sparse_graph` in practice and *much* lighter in
+  memory.
+
+  - Supports: multiple edges, edge labels and loops
+  - Does not support: addition/removal of edges/vertices.
+
+- :mod:`~sage.graphs.base.static_dense_graph` -- for dense (di)graphs and very
+  intensive computations (at C-level). It is mostly a wrapper over bitsets.
+
+  - Supports: addition/removal of edges/vertices, and loops.
+  - Does not support: multiple edges and edge labels.
+
+For more information, see the data structures' respective pages.
+
+The backends
+------------
+
+The :class:`Graph` and :class:`DiGraph` objects delegate the storage of vertices
+and edges to other objects: the :mod:`graph backends
+<sage.graphs.base.graph_backends>`::
+
+    sage: Graph()._backend
+    <sage.graphs.base.sparse_graph.SparseGraphBackend object at ...>
+
+A (di)graph backend is a simpler (di)graph class having only the most elementary
+methods (e.g.: add/remove vertices/edges). Its vertices can be arbitrary
+hashable objects.
+
+The only backend available in Sage is
+:class:`~sage.graphs.base.c_graph.CGraphBackend`.
+
+CGraph and CGraphBackend
+------------------------
+
+:class:`~sage.graphs.base.c_graph.CGraphBackend` is the backend of all native
+data structures that can be used by :class:`Graph` and :class:`DiGraph`. It is
+extended by:
+
+- :class:`~sage.graphs.base.dense_graph.DenseGraphBackend`
+- :class:`~sage.graphs.base.sparse_graph.SparseGraphBackend`
+- :class:`~sage.graphs.base.static_sparse_backend.StaticSparseBackend`
+
+While a :class:`~sage.graphs.base.c_graph.CGraphBackend` deals with arbitrary
+(hashable) vertices, it contains a ``._cg`` attribute of type
+:class:`~sage.graphs.base.c_graph.CGraph` which only deals with integer
+vertices.
+
+The :class:`~sage.graphs.base.c_graph.CGraph` data structures available in Sage
+are:
+
+- :class:`~sage.graphs.base.dense_graph.DenseGraph`
+- :class:`~sage.graphs.base.sparse_graph.SparseGraph`
+- :class:`~sage.graphs.base.static_sparse_backend.StaticSparseCGraph`
+
+See the :mod:`~sage.graphs.base.c_graph` module for more information.
+"""

sage/graphs/base/sparse_graph.pxd

@@ -0,0 +1,90 @@
+# sage_setup: distribution = sagemath-graphs
+# ****************************************************************************
+#       Copyright (C) 2008-2009 Robert L. Miller <rlmillster@gmail.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+from sage.graphs.base.c_graph cimport CGraph, CGraphBackend
+cimport cython
+
+cdef struct SparseGraphLLNode:
+    int label
+    int number
+    SparseGraphLLNode *next
+
+cdef struct SparseGraphBTNode:
+    int vertex
+    int number
+    SparseGraphLLNode *labels
+    SparseGraphBTNode *left
+    SparseGraphBTNode *right
+
+
+@cython.final
+cdef class SparseGraph(CGraph):
+    cdef int hash_length
+    cdef int hash_mask
+    cdef SparseGraphBTNode **vertices
+    cdef SparseGraphBTNode **vertices_rev
+    cdef bint _directed
+    cpdef bint is_directed(self) noexcept
+
+    cdef int _del_arc_unsafe(self, int, int, SparseGraphBTNode **) except -1
+    cdef int _add_arc_label_unsafe(self, int, int, int, SparseGraphBTNode **) except -1
+    cdef int _del_arc_label_unsafe(self, int, int, int, SparseGraphBTNode **) noexcept
+    cdef SparseGraphLLNode* arc_labels_unsafe(self, int u, int v) noexcept
+    cpdef int out_degree(self, int u) noexcept
+    cpdef int in_degree(self, int u) noexcept
+
+    cdef inline int _neighbors_unsafe (self, int u, bint out, int *neighbors, int size) except -2
+
+    cdef inline int _neighbors_BTNode_unsafe (self, int u, bint out, SparseGraphBTNode **res, int size) except -2
+
+    cdef inline SparseGraphBTNode* next_out_neighbor_BTNode_unsafe(self, int u, int v) noexcept:
+        """
+        Return the next out-neighbor of ``u`` that is greater than ``v``.
+
+        If ``v`` is ``-1`` return the first neighbor of ``u``.
+
+        Return ``NULL`` in case there does not exist such an out-neighbor.
+
+        .. WARNING::
+
+            Repeated calls to this function until NULL is returned DOES NOT
+            yield a linear time algorithm in the number of neighbors of u.
+            To list the neighbors of a vertex in linear time, one should use
+            _neighbors_BTNode_unsafe.
+        """
+        return self.next_neighbor_BTNode_unsafe(self.vertices, u, v)
+
+    cdef inline SparseGraphBTNode* next_in_neighbor_BTNode_unsafe(self, int v, int u) noexcept:
+        """
+        Return the next in-neighbor of ``v`` that is greater than ``u``.
+
+        If ``u`` is ``-1`` return the first neighbor of ``v``.
+
+        Return ``NULL`` in case there does not exist such an in-neighbor.
+
+        .. WARNING::
+
+            Repeated calls to this function until NULL is returned DOES NOT
+            yield a linear time algorithm in the number of neighbors of u.
+            To list the neighbors of a vertex in linear time, one should use
+            _neighbors_BTNode_unsafe.
+        """
+        return self.next_neighbor_BTNode_unsafe(self.vertices_rev, v, u)
+
+    cdef inline SparseGraphBTNode* next_neighbor_BTNode_unsafe(self, SparseGraphBTNode** vertices, int u, int v) noexcept
+
+
+cdef class SparseGraphBackend(CGraphBackend):
+    cdef int edge_labels_max
+    cdef list edge_labels_available_ids
+    cdef SparseGraph _cg
+    cdef inline CGraph cg(self):
+        return <CGraph> self._cg