trac #18317: Merged with 6.7.beta3

src/doc/en/reference/graphs/index.rst

@@ -35,6 +35,7 @@ Low-level implementation
 .. toctree::
    :maxdepth: 1
 
+   sage/graphs/base/overview
    sage/graphs/base/c_graph
    sage/graphs/base/sparse_graph
    sage/graphs/base/dense_graph

src/sage/graphs/base/c_graph.pyx

@@ -1,4 +1,4 @@
-"""
+r"""
 Fast compiled graphs
 
 This is a Cython implementation of the base class for sparse and dense graphs
@@ -7,6 +7,8 @@ extend this base class and implement missing functionalities. Whenever
 possible, specific methods should also be overridden with implementations that
 suit the graph type under consideration.
 
+For an overview of graph data structures in sage, see
+:mod:`~sage.graphs.base.overview`.
 
 Data structure
 --------------

src/sage/graphs/base/dense_graph.pyx

@@ -1,6 +1,9 @@
 r"""
 Fast dense graphs
 
+For an overview of graph data structures in sage, see
+:mod:`~sage.graphs.base.overview`.
+
 Usage Introduction
 ------------------
 

src/sage/graphs/base/graph_backends.py

@@ -1,6 +1,51 @@
-"""
-Implements various backends for Sage graphs.
-
+r"""
+Backends for Sage (di)graphs.
+
+This module implements :class:`GenericGraphBackend` (the base class for
+backends) and :class:`NetworkXGraphBackend` (a wrapper for `NetworkX
+<http://networkx.lanl.gov/>`__ graphs)
+
+Any graph backend must redefine the following methods (for which
+:class:`GenericGraphBackend` raises a ``NotImplementedError``)
+
+.. csv-table::
+    :class: contentstable
+    :widths: 30, 70
+    :delim: |
+
+    :meth:`~GenericGraphBackend.add_edge` | Add an edge `(u,v)` to ``self``, with label `l`.
+    :meth:`~GenericGraphBackend.add_edges` | Add a sequence of edges to ``self``.
+    :meth:`~GenericGraphBackend.add_vertex` | Add a labelled vertex to ``self``.
+    :meth:`~GenericGraphBackend.add_vertices` | Add labelled vertices to ``self``.
+    :meth:`~GenericGraphBackend.degree` | Returns the total number of vertices incident to v.
+    :meth:`~GenericGraphBackend.in_degree` | Return the in-degree of `v`
+    :meth:`~GenericGraphBackend.out_degree` | Return the out-degree of `v`
+    :meth:`~GenericGraphBackend.del_edge` | Deletes the edge `(u,v)` with label `l`.
+    :meth:`~GenericGraphBackend.del_vertex` | Delete a labelled vertex in ``self``.
+    :meth:`~GenericGraphBackend.del_vertices` | Delete labelled vertices in ``self``.
+    :meth:`~GenericGraphBackend.get_edge_label` | Returns the edge label of `(u,v)`.
+    :meth:`~GenericGraphBackend.has_edge` | True if ``self`` has an edge `(u,v)` with label `l`.
+    :meth:`~GenericGraphBackend.has_vertex` | True if ``self`` has a vertex with label `v`.
+    :meth:`~GenericGraphBackend.iterator_edges` | Iterate over the edges incident to a sequence of vertices.
+    :meth:`~GenericGraphBackend.iterator_in_edges` | Iterate over the incoming edges incident to a sequence of vertices.
+    :meth:`~GenericGraphBackend.iterator_out_edges` | Iterate over the outbound edges incident to a sequence of vertices.
+    :meth:`~GenericGraphBackend.iterator_nbrs` | Iterate over the vertices adjacent to `v`.
+    :meth:`~GenericGraphBackend.iterator_in_nbrs` | Iterate over the vertices u such that the edge `(u,v)` is in ``self`` (that is, predecessors of `v`).
+    :meth:`~GenericGraphBackend.iterator_out_nbrs` | Iterate over the vertices u such that the edge `(v,u)` is in ``self`` (that is, successors of `v`).
+    :meth:`~GenericGraphBackend.iterator_verts` | Iterate over the vertices `v` with labels in verts.
+    :meth:`~GenericGraphBackend.loops` | Get/set whether or not ``self`` allows loops.
+    :meth:`~GenericGraphBackend.multiple_edges` | Get/set whether or not ``self`` allows multiple edges.
+    :meth:`~GenericGraphBackend.name` | Get/set name of ``self``.
+    :meth:`~GenericGraphBackend.num_edges` | The number of edges in ``self``
+    :meth:`~GenericGraphBackend.num_verts` | The number of vertices in ``self``
+    :meth:`~GenericGraphBackend.relabel` | Relabel the vertices of ``self`` by a permutation.
+    :meth:`~GenericGraphBackend.set_edge_label` | Label the edge `(u,v)` by `l`.
+
+For an overview of graph data structures in sage, see
+:mod:`~sage.graphs.base.overview`.
+
+Classes and methods
+-------------------
 """
 
 #*******************************************************************************

src/sage/graphs/base/overview.py

@@ -0,0 +1,88 @@
+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
+    <class 'sage.graphs.base.sparse_graph.SparseGraphBackend'>
+
+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 backends defined in Sage are:
+
+- :class:`~sage.graphs.base.c_graph.CGraphBackend` (default)
+
+- :class:`~sage.graphs.base.graph_backends.NetworkXGraphBackend` (a wrapper for
+  `NetworkX <http://networkx.lanl.gov/>`__ graphs)
+
+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.
+"""

src/sage/graphs/base/sparse_graph.pyx

@@ -1,6 +1,9 @@
 r"""
 Fast sparse graphs
 
+For an overview of graph data structures in sage, see
+:mod:`~sage.graphs.base.overview`.
+
 Usage Introduction
 ------------------
 

src/sage/graphs/base/static_dense_graph.pyx

@@ -16,6 +16,9 @@ It is all based on the binary matrix data structure described in
 structure. The only difference is that it differentiates the rows (the vertices)
 instead of storing the whole data in a long bitset, and we can use that.
 
+For an overview of graph data structures in sage, see
+:mod:`~sage.graphs.base.overview`.
+
 Index
 -----
 

src/sage/graphs/base/static_sparse_backend.pyx

@@ -11,6 +11,9 @@ you need to list the graph's edge, or those incident to a vertex, but an
 adjacency test can be much longer than in a dense data structure (i.e. like in
 :mod:`sage.graphs.base.static_dense_graph`)
 
+For an overview of graph data structures in sage, see
+:mod:`~sage.graphs.base.overview`.
+
 Two classes
 -----------
 

src/sage/graphs/base/static_sparse_graph.pyx

@@ -13,9 +13,11 @@ for graph algorithms whose main operation is to *list the out-neighbours of a
 vertex* (which is precisely what BFS, DFS, distance computations and the
 flow-related stuff waste their life on).
 
-The code contained in this module is written C-style. While Sage needs a class
-for static graphs (not available today, i.e. 2012-01-13) it is not what we try
-to address here. The purpose is efficiency and simplicity.
+The code contained in this module is written C-style. The purpose is efficiency
+and simplicity.
+
+For an overview of graph data structures in sage, see
+:mod:`~sage.graphs.base.overview`.
 
 Author:
 

src/sage/graphs/digraph.py

@@ -119,8 +119,7 @@
 
 
 class DiGraph(GenericGraph):
-    """
-    Directed graph.
+    """Directed graph.
 
     A digraph or directed graph is a set of vertices connected by oriented
     edges. For more information, see the
@@ -264,7 +263,8 @@ class DiGraph(GenericGraph):
       ``data_structure="sparse"``, and ``sparse=False`` is an alias for
       ``data_structure="dense"``.
 
-    -  ``data_structure`` -- one of the following
+    - ``data_structure`` -- one of the following (for more information, see
+       :mod:`~sage.graphs.base.overview`):
 
        * ``"dense"`` -- selects the :mod:`~sage.graphs.base.dense_graph`
          backend.

src/sage/graphs/graph.py

@@ -692,7 +692,8 @@ class Graph(GenericGraph):
       ``data_structure="sparse"``, and ``sparse=False`` is an alias for
       ``data_structure="dense"``.
 
-    -  ``data_structure`` -- one of the following
+    - ``data_structure`` -- one of the following (for more information, see
+       :mod:`~sage.graphs.base.overview`)
 
        * ``"dense"`` -- selects the :mod:`~sage.graphs.base.dense_graph`
          backend.