Ticket #3676: 3676-ncalexan-docstring-changes.patch

File 3676-ncalexan-docstring-changes.patch, 4.8 KB (added by ncalexan, 13 years ago)
  • sage/groups/perm_gps/partn_ref/refinement_graphs.pyx

    a b  
    2222    INPUT:
    2323    G_in -- a Sage graph
    2424    partition -- a list of lists representing a partition of the vertices
    25     lab -- if True, return the canonical label in addition to the automorphism
    26         group.
    27     dig -- if True, does not use Lemma 2.25 in [1], and the algorithm is valid
    28         for digraphs and graphs with loops.
    29     dict_rep -- if True, explain which vertices are which elements of the set
    30         {1,2,...,n} in the representation of the automorphism group.
    31     certify -- if True, return the relabeling from G to its canonical
    32         label.
     25    lab -- if True, compute and return the canonical label in addition to the
     26        automorphism group.
     27    dig -- set to True for digraphs and graphs with loops.  If True, does not
     28        use optimizations based on Lemma 2.25 in [1] that are valid only for
     29        simple graphs.
     30    dict_rep -- if True, return a dictionary with keys the vertices of the
     31        input graph G_in and values elements of the set the permutation group
     32        acts on.  (The point is that graphs are arbitrarily labelled, often
     33        0..n-1, and permutation groups always act on 1..n.  This dictionary
     34        maps vertex labels (such as 0..n-1) to the domain of the permutations.)
     35    certify -- if True, return the permutation from G to its canonical label.
    3336    verbosity -- currently ignored
    3437    use_indicator_function -- option to turn off indicator function
    35         (False -> slower)
     38        (True is generally faster)
    3639    sparse -- whether to use sparse or dense representation of the graph
    3740        (ignored if G is already a CGraph - see sage.graphs.base)
    3841    base -- whether to return the first sequence of split vertices (used in
     
    314317        return tuple(return_tuple)
    315318
    316319cdef int refine_by_degree(PartitionStack *PS, object S, int *cells_to_refine_by, int ctrb_len):
    317     """
     320    r"""
    318321    Refines the input partition by checking degrees of vertices to the given
    319322    cells.
    320323   
     
    325328        question, and some flags.
    326329    cells_to_refine_by -- a list of pointers to cells to check degrees against
    327330        in refining the other cells (updated in place)
    328     ctrb_len -- how many cells in the above
     331    ctrb_len -- how many cells in cells_to_refine_by
    329332   
    330333    OUTPUT:
    331     An invariant, such that if the function is called with a permutation of the
    332     situation (i.e. there is a gamma taking one graph to the other, which also
    333     takes one partition to the other), the same number is returned.
     334
     335    An integer invariant under the orbits of $S_n$.  That is, if $\gamma$ is a
     336    permutation of the vertices, then
     337    $$ I(G, PS, cells_to_refine_by) = I( \gamma(G), \gamma(PS), \gamma(cells_to_refine_by) ) .$$
     338
    334339    """
    335340    cdef GraphStruct GS = <GraphStruct> S
    336341    cdef CGraph G = GS.G
     
    425430        return 0
    426431   
    427432cdef int compare_graphs(int *gamma_1, int *gamma_2, object S):
    428     """
    429     Compare gamma_1(G) and gamma_2(G), returning 0 iff gamma_1(G) == gamma_2(G).
     433    r"""
     434    Compare gamma_1(G) and gamma_2(G).
     435
     436    Return return -1 if gamma_1(G) < gamma_2(G), 0 if gamma_1(G) ==
     437    gamma_2(G), 1 if gamma_1(G) > gamma_2(G).  (Just like the python
     438    \code{cmp}) function.
    430439   
    431440    INPUT:
    432441    gamma_1, gamma_2 -- list permutations (inverse)
     
    447456
    448457cdef bint all_children_are_equivalent(PartitionStack *PS, object S):
    449458    """
    450     Returns True if any refinement of the current partition results in the same
    451     structure. Converse does not hold in general.
    452    
     459    Return True if every refinement of the current partition results in the
     460    same structure.
     461
     462    WARNING:
     463    Converse does not hold in general!  See Lemma 2.25 of [1] for details.
     464
    453465    INPUT:
    454466    PS -- the partition stack to be checked
    455467    S -- a graph struct object
     
    606618    """
    607619    Tests to make sure that C(gamma(G)) == C(G) for random permutations gamma
    608620    and random graphs G.
    609    
    610     DOCTEST:
     621
     622    INPUT:
     623    t -- run tests for approximately this many seconds
     624    n_max -- test graphs with at most this many vertices
     625    perms_per_graph -- test each graph with this many random permutations
     626
     627    DISCUSSION:
     628
     629    Until t seconds have elapsed, this code generates a random graph G on at
     630    most n_max vertices.  The density of edges is chosen randomly between 0
     631    and 1.
     632
     633    For each graph G generated, we uniformly generate perms_per_graph random
     634    permutations and verify that the canonical labels of G and the image of G
     635    under the generated permutation are equal.
     636       
     637    TESTS:
    611638        sage: import sage.groups.perm_gps.partn_ref.refinement_graphs
    612639        sage: sage.groups.perm_gps.partn_ref.refinement_graphs.random_tests()
    613640        All passed: ... random tests on ... graphs.