Ticket #2850: 2850.patch

sage/calculus/calculus.py

@@ -1127 +1127 @@
     ##################################################################
     # The maxima one is special:
     def _maxima_(self, session=None):
+        r"""
+        Method for coercing self as a Maxima \code{RingElement}.
+        """
         if session is None:
             return RingElement._maxima_(self, maxima)
         else:
@@ -4453 +4456 @@
 
     def __call__(self, *args, **kwargs):
         """
+        Method for handling a function call.
+        
         EXAMPLES:
             sage: x,y,z=var('x,y,z')
             

sage/groups/perm_gps/permgroup.py

@@ -197 +197 @@
         True
     """
     def __init__(self, gens, from_group = False, check=True):
+        r"""
+        Initializes instance of self, a \code{PermutationGroup_generic} object.
+        The flag from_group determines whether or not self should be
+        initialized as a Gap \code{Group} object and sent to the Gap
+        interpreter. If gens are Gap objects, then self is intialized as a Gap
+        \code{Group}.
+
+        EXAMPLES:
+        We explicitly construct the alternating group on four elements.
+            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4
+            Permutation Group with generators [(1,2,3), (2,3,4)]
+            sage: A4.__init__([[(1,2,3)],[(2,3,4)]]); A4
+            Permutation Group with generators [(1,2,3), (2,3,4)]
+            sage: A4.center()
+            Permutation Group with generators [()]
+            sage: loads(A4.dumps()) == A4
+            True
+        """
         if from_group and isinstance(gens, str):
             self.__gap = gens
             self.gens()  # so will check that group can be defined in GAP (e.g., no missing packages, etc.)
@@ -236 +254 @@
         self.gens()
 
     def _gap_init_(self):
+        r"""
+        Returns a string showing how to declare / initialize self in Gap.
+        Stored in the \code{self.__gap} attribute.
+
+        EXAMPLES:
+        The \code{_gap_init_} method shows how you would define the Sage
+        \code{PermutationGroup_generic} object in Gap:
+            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4
+            Permutation Group with generators [(1,2,3), (2,3,4)]
+            sage: A4._gap_init_()
+            'Group([((1,2,3)), ((2,3,4))])'
+        """
         return self.__gap
 
     def _magma_init_(self):
+        r"""
+        Returns a string showing how to declare / intialize self in Magma.
+
+        EXAMPLES:
+        We explicitly construct the alternating group on four elements. In
+        Magma, one would type the string below to construct the group.
+            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4
+            Permutation Group with generators [(1,2,3), (2,3,4)]
+            sage: A4._magma_init_()
+            'PermutationGroup<4 | (1,2,3), (2,3,4)>'
+        """
         g = str(self.gens())[1:-1]
         return 'PermutationGroup<%s | %s>'%(self.degree(), g)
 
@@ -512 +553 @@
         return self._gap_().SmallGeneratingSet()
 
     def gen(self, i):
+        r"""
+        Returns the ith generator of self; that is, the ith element of the
+        list \code{self.gens()}.
+
+        EXAMPLES:
+        We explicitly construct the alternating group on four elements:
+            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4
+            Permutation Group with generators [(1,2,3), (2,3,4)]
+            sage: A4.gens()
+            ((1,2,3), (2,3,4))
+            sage: A4.gen(0)
+            (1,2,3)
+            sage: A4.gen(1)
+            (2,3,4)
+            sage: A4.gens()[0]; A4.gens()[1]
+            (1,2,3)
+            (2,3,4)
+        """
         return self.gens()[Integer(i)]
 
     def cayley_table(self, names="x"):
@@ -682 +741 @@
             return O
     
     def _repr_(self):
+        r"""
+        Returns a string describing self.
+
+        EXAMPLES:
+        We explicitly construct the alternating group on four elements. Note
+        that
+        the \code{AlternatingGroup} class has its own representation string:
+            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4
+            Permutation Group with generators [(1,2,3), (2,3,4)]
+            sage: A4._repr_()
+            'Permutation Group with generators [(1,2,3), (2,3,4)]'
+            sage: AlternatingGroup(4)._repr_()
+            'Alternating group of order 4!/2 as a permutation group'
+        """
         G = self.gens()
         return "Permutation Group with generators %s"%list(self.gens())
 
     def _latex_(self):
+        r"""
+        Method for describing self in LaTeX. Encapsulates \code{self.gens()}
+        in angle brackets to denote that self in generated by these elements.
+        Called by the \code{latex()} function.
+
+        EXAMPLES:
+        We explicitly construct the alternating group on four elements.
+            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4
+            Permutation Group with generators [(1,2,3), (2,3,4)]
+            sage: latex(A4)
+            \langle (1,2,3), (2,3,4) \rangle
+            sage: A4._latex_()
+            '\\langle (1,2,3), (2,3,4) \\rangle'
+        """
         return '\\langle ' + \
                ', '.join([x._latex_() for x in self.gens()]) + ' \\rangle'
 
@@ -729 +816 @@
 
     def id(self):
         """
-        Same as self.group_id()
+        (Same as self.group_id().) Return the ID code of this group, which is
+        a list of two integers. Requires "optional" database_gap-4.4.x package.
+
+        EXAMPLES:
+            sage: G = PermutationGroup([[(1,2,3),(4,5)], [(1,2)]])
+            sage: G.group_id()    # requires optional database_gap-4.4.6 package
+            [12, 4]
         """
         return self.group_id()
 
@@ -1713 +1806 @@
     """
     def __init__(self, ambient, gens, from_group = False, 
                  check=True):
+        r"""
+        Initialization method for the \code{PermutationGroup_subgroup} class.
+
+        INPUTS:
+            ambient -- the ambient group from which to construct this subgroup
+            gens -- the generators of the subgroup
+            from_group -- True: subroup is generated from a Gap string representation of the generators
+            check-- True: checks if gens are indeed elements of the ambient group
+            
+        EXAMPLES:
+        An example involving the dihedral group on four elements. $D_8$
+        contains a cyclic subgroup or order four:
+            sage: G = DihedralGroup(4)
+            sage: H = CyclicPermutationGroup(4)
+            sage: gens = H.gens(); gens
+            ((1,2,3,4),)
+            sage: S = PermutationGroup_subgroup(G,list(gens))
+            sage: S
+            Subgroup of Dihedral group of order 8 as a permutation group generated by [(1,2,3,4)]
+            sage: S.list()
+            [(), (1,2,3,4), (1,3)(2,4), (1,4,3,2)]
+            sage: S.ambient_group()
+            Dihedral group of order 8 as a permutation group
+
+        However, $D_8$ does not contain a cyclic subgroup of order three:
+            sage: G = DihedralGroup(4)
+            sage: H = CyclicPermutationGroup(3)
+            sage: gens = H.gens()
+            sage: S = PermutationGroup_subgroup(G,list(gens))
+            Traceback (most recent call last):
+            ...
+            TypeError: each generator must be in the ambient group
+        """
         if not isinstance(ambient, PermutationGroup_generic):
             raise TypeError, "ambient (=%s) must be perm group."%ambient
         if not isinstance(gens, list):
@@ -1764 +1890 @@
             return 1
             
     def _repr_(self):
+        r"""
+        Returns a string representation / description of the permutation
+        subgroup.
+
+        EXAMPLES:
+        An example involving the dihedral group on four elements, $D_8$:
+            sage: G = DihedralGroup(4)
+            sage: H = CyclicPermutationGroup(4)
+            sage: gens = H.gens()
+            sage: S = PermutationGroup_subgroup(G, list(gens))
+            sage: S
+            Subgroup of Dihedral group of order 8 as a permutation group generated by [(1,2,3,4)]
+            sage: S._repr_()
+            'Subgroup of Dihedral group of order 8 as a permutation group generated by [(1,2,3,4)]'
+        """
         s = "Subgroup of %s generated by %s"%(self.ambient_group(), self.gens())
         return s
 
     def _latex_(self):
         r"""
         Return latex representation of this group.
+
+        EXAMPLES:
+        An example involving the dihedral group on four elements, $D_8$:
+            sage: G = DihedralGroup(4)
+            sage: H = CyclicPermutationGroup(4)
+            sage: gens = H.gens()
+            sage: S = PermutationGroup_subgroup(G, list(gens))
+            sage: latex(S)
+            Subgroup of Dihedral group of order 8 as a permutation group generated by [(1,2,3,4)]
+            sage: S._latex_()
+            'Subgroup of Dihedral group of order 8 as a permutation group generated by [(1,2,3,4)]'
         """
         return self._repr_()
 
@@ -1777 +1929 @@
     def ambient_group(self):
         """
         Return the ambient group related to self.
+
+        EXAMPLES:
+        An example involving the dihedral group on four elements, $D_8$:
+            sage: G = DihedralGroup(4)
+            sage: H = CyclicPermutationGroup(4)
+            sage: gens = H.gens()
+            sage: S = PermutationGroup_subgroup(G, list(gens))
+            sage: S.ambient_group()
+            Dihedral group of order 8 as a permutation group
+            sage: S.ambient_group() == G
+            True
         """
         return self.__ambient_group
 
     def gens(self):
         """
         Return the generators for this subgroup.
+
+        EXAMPLES:
+        An example involving the dihedral group on four elements, $D_8$:
+            sage: G = DihedralGroup(4)
+            sage: H = CyclicPermutationGroup(4)
+            sage: gens = H.gens()
+            sage: S = PermutationGroup_subgroup(G, list(gens))
+            sage: S.gens()
+            [(1,2,3,4)]
+            sage: S.gens() == list(H.gens())
+            True
         """
         return self.__gens