Ticket #11637: trac_11637.patch

File trac_11637.patch, 5.0 KB (added by ncohen, 8 years ago)
  • sage/graphs/generic_graph.py

    # HG changeset patch
    # User Nathann Cohen <nathann.cohen@gmail.com>
    # Date 1312040261 -7200
    # Node ID 51968dc8bd9b53030f1760702d416b8203c2a302
    # Parent  8532a2ad1e558cbc91ddaaa6b7cc79956dd1e8ba
    trac #11637 -- updated documentation for Graph.cores()
    
    diff -r 8532a2ad1e55 -r 51968dc8bd9b sage/graphs/generic_graph.py
    a b  
    99529952        """
    99539953        Returns the core number for each vertex in an ordered list.
    99549954       
    9955            K-cores in graph theory were introduced by Seidman in 1983
    9956            and by Bollobas in 1984 as a method of (destructively)
    9957            simplifying graph topology to aid in analysis and
    9958            visualization. They have been more recently defined as the
    9959            following by Batagelj et al: given a graph `G` with
    9960            vertices set `V` and edges set `E`, the `k`-core is
    9961            computed by pruning all the vertices (with their respective
    9962            edges) with degree less than `k`. That means that if a
    9963            vertex `u` has degree `d_u`, and it has `n` neighbors with
    9964            degree less than `k`, then the degree of `u` becomes `d_u -
    9965            n`, and it will be also pruned if `k > d_u - n`. This
    9966            operation can be useful to filter or to study some
    9967            properties of the graphs. For instance, when you compute
    9968            the 2-core of graph G, you are cutting all the vertices
    9969            which are in a tree part of graph.  (A tree is a graph with
    9970            no loops). [WPkcore]_
    9971        
    9972         [PSW1996]_ defines a `k`-core as the largest subgraph with minimum
    9973         degree at least `k`.
     9955
     9956        **DEFINITIONS**
     9957
     9958        * *K-cores* in graph theory were introduced by Seidman in 1983 and by
     9959          Bollobas in 1984 as a method of (destructively) simplifying graph
     9960          topology to aid in analysis and visualization. They have been more
     9961          recently defined as the following by Batagelj et al:
     9962
     9963          *Given a graph `G` with vertices set `V` and edges set `E`, the
     9964          `k`-core of `G` is the graph obtained from `G` by recursively removing
     9965          the vertices with degree less than `k`, for as long as there are any.*
     9966
     9967          This operation can be useful to filter or to study some properties of
     9968          the graphs. For instance, when you compute the 2-core of graph G, you
     9969          are cutting all the vertices which are in a tree part of graph.  (A
     9970          tree is a graph with no loops). [WPkcore]_
     9971       
     9972          [PSW1996]_ defines a `k`-core of `G` as the largest subgraph (it is
     9973          unique) of `G` with minimum degree at least `k`.
     9974
     9975        * Core number of a vertex
     9976
     9977          The core number of a vertex `v` is the largest integer `k` such that
     9978          `v` belongs to the `k`-core of `G`.
     9979
     9980        * Degeneracy
     9981
     9982          The *degeneracy* of a graph `G`, usually denoted `\delta^*(G)`, is the
     9983          smallest integer `k` such that the graph `G` can be reduced to the
     9984          empty graph by iteratively removing vertices of degree `\leq
     9985          k`. Equivalently, `\delta^*(G)=k` if `k` is the smallest integer such
     9986          that the `k`-core of `G` is empty.
     9987
     9988        **IMPLEMENTATION**
    99749989
    99759990        This implementation is based on the NetworkX implementation of
    99769991        the algorithm described in [BZ]_.
    99779992
    9978         INPUT:
    9979        
    9980         - ``k`` (integer) --
    9981 
    9982             * If ``k = None`` (default), returns the core number for
    9983               each vertex, according to the value of ``with_labels``.
    9984 
    9985             * Otherwise, returns a pair ``(ordering, core)``, where
    9986               ``core`` is the list of vertices in the `k`-core of
    9987               ``self``, and ``ordering`` is an elimination order for
    9988               the others vertices such that each vertex is of degree
    9989               strictly less than `k` when it is to be eliminated from
    9990               the graph.
    9991        
    9992         -  ``with_labels`` - default False returns list as
    9993            described above. True returns dict keyed by vertex labels.
    9994        
     9993        **INPUT**
     9994       
     9995        - ``k`` (integer)
     9996
     9997            * If ``k = None`` (default), returns the core number for each vertex.
     9998
     9999            * If ``k`` is an integer, returns a pair ``(ordering, core)``, where
     10000              ``core`` is the list of vertices in the `k`-core of ``self``, and
     10001              ``ordering`` is an elimination order for the others vertices such
     10002              that each vertex is of degree strictly less than `k` when it is to
     10003              be eliminated from the graph.
     10004       
     10005        - ``with_labels`` (boolean)
     10006
     10007           * When set to ``False``, and ``k = None``, the method returns a list
     10008             whose `i` th element is the core number of the `i` th vertex. When
     10009             set to ``True``, the method returns a dictionary whose keys are
     10010             vertices, and whose values are the corresponding core numbers.
     10011
     10012             By default, ``with_labels = False``.
    999510013       
    999610014        REFERENCE:
    999710015