Ticket #8513: trac_8513_graph_theory_documentation-abm.patch

File trac_8513_graph_theory_documentation-abm.patch, 8.4 KB (added by abmasse, 11 years ago)

Adds digraph.py and generic_graph.py in the doctree

  • doc/en/reference/graphs.rst

    # HG changeset patch
    # User Alexandre Blondin Masse < alexandre.blondin.masse at gmail.com>
    # Date 1269287092 -3600
    # Node ID fb26ae3b55b2a1491727483c8d1ed5ed845f760c
    # Parent  2b6f82c8b0075babce925e6f0cc90a792c7b8515
    #8513 Including the files digraph.py and generic_graph.py in the doctree.
    Also removes all the warnings displayed when the documentation is generated by Sphinx.
    
    diff --git a/doc/en/reference/graphs.rst b/doc/en/reference/graphs.rst
    a b Graph Theory 
    55   :maxdepth: 2
    66
    77   sage/graphs/cliquer
     8   sage/graphs/digraph
     9   sage/graphs/generic_graph
    810   sage/graphs/graph
    911   sage/graphs/graph_coloring
    1012   sage/graphs/graph_generators
  • sage/graphs/generic_graph.py

    diff --git a/sage/graphs/generic_graph.py b/sage/graphs/generic_graph.py
    a b class GenericGraph(GenericGraph_pyx): 
    19491949         
    19501950        INPUT:
    19511951 
    1952         - ``root_vertex`` -- integer (default: the first vertex) This is the vertex
    1953         that will be used as root for all spanning out-trees if the graph
    1954         is a directed graph.
    1955         This argument is ignored if the graph is not a digraph.
    1956          
     1952        - ``root_vertex`` -- integer (default: the first vertex) This is
     1953          the vertex that will be used as root for all spanning out-trees
     1954          if the graph is a directed graph. This argument is ignored if
     1955          the graph is not a digraph.
     1956         
     1957
    19571958        REFERENCES:
    19581959         
    1959         - [1] http://mathworld.wolfram.com/MatrixTreeTheorem.html
    1960          
    1961         - [2] Lih-Hsing Hsu, Cheng-Kuan Lin, "Graph Theory and Interconnection
    1962         Networks"
     1960        [1] http://mathworld.wolfram.com/MatrixTreeTheorem.html
     1961         
     1962        [2] Lih-Hsing Hsu, Cheng-Kuan Lin, "Graph Theory and Interconnection Networks"
     1963
    19631964         
    19641965        AUTHORS:
    19651966         
    19661967        - Anders Jonsson (2009-10-10)
    19671968         
     1969
    19681970        EXAMPLES::
    19691971         
    19701972            sage: G = graphs.PetersenGraph()
    class GenericGraph(GenericGraph_pyx): 
    20142016        possible maximum outdegree of the current graph.
    20152017
    20162018        Given a Graph `G`, is is polynomial to compute an orientation
    2017         `D` of the edges of `G` such that the maximum out-degree in `D`
    2018         is minimized. This problem, though, is NP-complete in the
     2019        `D` of the edges of `G` such that the maximum out-degree in
     2020        `D` is minimized. This problem, though, is NP-complete in the
    20192021        weighted case [AMOZ06]_.
    20202022
    20212023        INPUT:
    20222024
    20232025        - ``use_edge_labels`` (boolean)
    20242026
    2025             - When set to ``True``, uses edge labels as weights to
    2026               compute the orientation and assumes a weight of `1`
    2027               when there is no value available for a given edge.
    2028 
    2029             - When set to ``False`` (default), gives a weight of 1
    2030               to all the edges.       
     2027          - When set to ``True``, uses edge labels as weights to
     2028            compute the orientation and assumes a weight of `1`
     2029            when there is no value available for a given edge.
     2030          - When set to ``False`` (default), gives a weight of 1
     2031            to all the edges.       
     2032
    20312033
    20322034        EXAMPLE:
    20332035
    20342036        Given a complete bipartite graph `K_{n,m}`, the maximum out-degree
    2035         of an optimal orientation is
    2036         `\left\lceil \frac {nm} {n+m}\right\rceil`::
     2037        of an optimal orientation is `\left\lceil \frac {nm} {n+m}\right\rceil`::
    20372038
    20382039            sage: g = graphs.CompleteBipartiteGraph(3,4)
    20392040            sage: o = g.minimum_outdegree_orientation() # optional - requires GLPK or CBC
    20402041            sage: max(o.out_degree()) == ceil((4*3)/(3+4)) # optional - requires GLPK or CBC
    20412042            True
    20422043
    2043 
    2044 
    20452044        REFERENCES:
    20462045       
    20472046        .. [AMOZ06] Asahiro, Y. and Miyano, E. and Ono, H. and Zenmyo, K.
    class GenericGraph(GenericGraph_pyx): 
    20492048          Proceedings of the 12th Computing: The Australasian Theroy Symposium
    20502049          Volume 51, page 20
    20512050          Australian Computer Society, Inc. 2006
    2052 
    20532051        """
    20542052
    20552053        if self.is_directed():
    class GenericGraph(GenericGraph_pyx): 
    78157813        Returns the Wiener index of the graph.
    78167814
    78177815        The Wiener index of a graph `G` can be defined in two equivalent
    7818         ways [KRG96]_ :
     7816        ways [1] :
    78197817
    78207818        - `W(G) = \frac 1 2 \sum_{u,v\in G} d(u,v)` where `d(u,v)` denotes the distance between
    78217819          vertices `u` and `v`.
    class GenericGraph(GenericGraph_pyx): 
    78277825       
    78287826        EXAMPLE:
    78297827       
    7830         From [GYLL93]_, cited in [KRG96]_::
     7828        From [2], cited in [1]::
    78317829
    78327830            sage: g=graphs.PathGraph(10)
    78337831            sage: w=lambda x: (x*(x*x -1)/6)
    class GenericGraph(GenericGraph_pyx): 
    78367834
    78377835        REFERENCE:
    78387836
    7839         .. [KRG96] Klavzar S., Rajapakse A., Gutman I. (1996). The Szeged and
    7840           the Wiener index of graphs .
    7841           Applied Mathematics Letters, 9 (5), pp. 45-49.
     7837        [1] Klavzar S., Rajapakse A., Gutman I. (1996). The Szeged and the
     7838        Wiener index of graphs. Applied Mathematics Letters, 9 (5), pp. 45-49.
     7839
     7840        [2] I Gutman, YN Yeh, SL Lee, YL Luo (1993), Some recent results in
     7841        the theory of the Wiener number. INDIAN JOURNAL OF CHEMISTRY SECTION A
     7842        PUBLICATIONS & INFORMATION DIRECTORATE, CSIR
     7843        """
     7844
     7845        return sum([sum(v.itervalues()) for v in self.distance_all_pairs().itervalues()])/2
     7846
     7847    def average_distance(self):
     7848        r"""
     7849        Returns the average distance between vertices of the graph.
     7850
     7851        Formally, for a graph `G` this value is equal to
     7852        `\frac 1 {n(n-1)} \sum_{u,v\in G} d(u,v)` where `d(u,v)`
     7853        denotes the distance between vertices `u` and `v` and `n`
     7854        is the number of vertices in `G`.
     7855
     7856        EXAMPLE:
     7857       
     7858        From [GYLL93]_::
     7859
     7860            sage: g=graphs.PathGraph(10)
     7861            sage: w=lambda x: (x*(x*x -1)/6)/(x*(x-1)/2)
     7862            sage: g.average_distance()==w(10)
     7863            True
     7864
     7865
     7866        REFERENCE:
    78427867
    78437868        .. [GYLL93] I Gutman, YN Yeh, SL Lee, YL Luo (1993),
    78447869          Some recent results in the theory of the Wiener number.
    78457870          INDIAN JOURNAL OF CHEMISTRY SECTION A
    78467871          PUBLICATIONS & INFORMATION DIRECTORATE, CSIR
    7847      
    7848         """
    7849 
    7850         return sum([sum(v.itervalues()) for v in self.distance_all_pairs().itervalues()])/2
    7851 
    7852     def average_distance(self):
    7853         r"""
    7854         Returns the average distance between vertices of the graph.
    7855 
    7856         Formally, for a graph `G` this value is equal to
    7857         `\frac 1 {n(n-1)} \sum_{u,v\in G} d(u,v)` where `d(u,v)`
    7858         denotes the distance between vertices `u` and `v` and `n`
    7859         is the number of vertices in `G`.
    7860 
    7861         EXAMPLE:
    7862        
    7863         From [GYLL93]_::
    7864 
    7865             sage: g=graphs.PathGraph(10)
    7866             sage: w=lambda x: (x*(x*x -1)/6)/(x*(x-1)/2)
    7867             sage: g.average_distance()==w(10)
    7868             True
    7869 
    7870 
    7871         REFERENCE:
    7872 
    7873         .. [GYLL93] I Gutman, YN Yeh, SL Lee, YL Luo (1993),
    7874           Some recent results in the theory of the Wiener number.
    7875           INDIAN JOURNAL OF CHEMISTRY SECTION A
    7876           PUBLICATIONS & INFORMATION DIRECTORATE, CSIR
    78777872
    78787873        """
    78797874
    class GenericGraph(GenericGraph_pyx): 
    78867881        For any `uv\in E(G)`, let
    78877882        `N_u(uv) = \{w\in G:d(u,w)<d(v,w)\}, n_u(uv)=|N_u(uv)|`
    78887883
    7889         The Szeged index of a graph is then defined as [KRG96]_ :
     7884        The Szeged index of a graph is then defined as [1]:
    78907885        `\sum_{uv \in E(G)}n_u(uv)\times n_v(uv)`
    78917886
    78927887        EXAMPLE:
    78937888
    7894         True for any connected graph [KRG96]_::
     7889        True for any connected graph [1]::
    78957890
    78967891            sage: g=graphs.PetersenGraph()
    78977892            sage: g.wiener_index()<= g.szeged_index()
    78987893            True
    78997894
    7900         True for all trees [KRG96]_::
     7895        True for all trees [1]::
    79017896
    79027897            sage: g=Graph()
    79037898            sage: g.add_edges(graphs.CubeGraph(5).min_spanning_tree())
    class GenericGraph(GenericGraph_pyx): 
    79077902
    79087903        REFERENCE:
    79097904
    7910         .. [KRG96] Klavzar S., Rajapakse A., Gutman I. (1996). The Szeged and
    7911           the Wiener index of graphs .
    7912           Applied Mathematics Letters, 9 (5), pp. 45-49.
    7913 
     7905        [1] Klavzar S., Rajapakse A., Gutman I. (1996). The Szeged and the
     7906        Wiener index of graphs. Applied Mathematics Letters, 9 (5), pp. 45-49.
    79147907        """
    79157908        distances=self.distance_all_pairs()
    79167909        s=0