Ticket #13115: trac_13115-groups-object-v2.patch

doc/en/reference/groups.rst

@@ -6 +6 @@
 .. toctree::
    :maxdepth: 2
 
+   sage/groups/group_generators
    sage/groups/group
    sage/groups/generic
    sage/groups/abelian_gps/abelian_group

sage/groups/all.py

@@ -12 +12 @@
 from class_function import ClassFunction
 
 from additive_abelian.all import *
+
+from group_generators import groups

new file sage/groups/group_generators.py

@@ +1 @@
+r"""
+Examples of Groups
+~~~~~~~~~~~~~~~~~~
+
+    The ``groups`` object, an instance of the :class:`GroupGenerators` class,
+    contains methods that return examples of various groups.  Using
+    tab-completion on this object is an easy way to discover and quickly
+    create the groups that are available (as listed here).
+
+    - Small Groups
+        - :meth:`~sage.groups.group_generators.GroupGenerators.KleinFourPermutation`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.QuaternionPermutation`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.QuaternionMatrixGF3`
+    - Families of Permutation Groups
+        - :meth:`~sage.groups.group_generators.GroupGenerators.SymmetricPermutation`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.AlternatingPermutation`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.CyclicPermutation`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.DihedralPermutation`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.DiCyclicPermutation`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.MathieuPermutation`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.SuzukiPermutation`
+    - Families of Matrix Groups
+        - :meth:`~sage.groups.group_generators.GroupGenerators.GLMatrix`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.SLMatrix`
+        - :meth:`~sage.groups.group_generators.GroupGenerators.PGLPermutation`
+
+"""
+
+class GroupGenerators(object):
+    r"""
+    An object of this class gives convenient references
+    to examples of graphs.
+
+    The global ``groups`` object can be used with tab-completion
+    to easily and quickly locate examples of groups implemented in Sage.
+
+    .. warning::
+
+        This list is under development, so may not be exhaustive.
+    """
+
+    def __repr__(self):
+        r"""
+        A message about the purpose of this object.
+
+        TESTS::
+        
+            sage: groups   # indirect doctest
+            Object collecting examples of graphs, try "groups.<tab>"
+        """
+        return 'Object collecting examples of graphs, try "groups.<tab>"'
+        
+    def KleinFourPermutation(self):
+        r"""
+        The non-cyclic group of order 4, isomorphic to `\ZZ_2\times\ZZ_2`.
+
+        OUTPUT:
+
+        The non-cyclic group of order 4, as a permutation group
+        on 4 symbols.
+
+        EXAMPLES::
+
+            sage: K = groups.KleinFourPermutation()
+            sage: K.list()
+            [(), (3,4), (1,2), (1,2)(3,4)]
+
+        For further documentation, see
+        :meth:`~sage.groups.perm_gps.permgroup_named.KleinFourGroup`.
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.KleinFourGroup()
+        
+    def SymmetricPermutation(self, n):
+        r"""
+        The full symmetric group on `n` symbols, as a permutation group.
+
+        INPUT:
+
+        - ``n`` - a positive integer, or a list.  If ``n`` is
+          an integer, then the symbol set is the integers
+          `\{1,2,\dots,n\}`.  Otherwise the symbol set is
+          the list given by `n`, provided the objects in
+          the list are hashable (i.e. immutable).
+
+        OUTPUT:
+
+        The full group of order `n!` with all possible
+        permutations of the `n` symbols.
+
+        EXAMPLES::
+
+            sage: G = groups.SymmetricPermutation(3)
+            sage: G.list()
+            [(), (2,3), (1,2), (1,2,3), (1,3,2), (1,3)]
+            sage: H = groups.SymmetricPermutation(10)
+            sage: H.order() == factorial(10)
+            True
+
+        A symmetric group can be a good base for creating subgroups
+        of interest.  ::
+
+            sage: S = groups.SymmetricPermutation(11)
+            sage: a = S("(1, 2, 3, 4, 5)(7, 8, 9, 10,11)")
+            sage: b = S("(1, 2, 3)(4, 5, 6, 7, 8)(9, 10, 11)")
+            sage: H = S.subgroup([a, b])
+            sage: S.order()/H.order()
+            2
+
+        Alternate symbol sets are possible.  ::
+
+            sage: G = groups.SymmetricPermutation(['dog', 'cat', 'fish'])
+            sage: G
+            Symmetric group of order 3! as a permutation group
+            sage: G.an_element()
+            ('dog','cat','fish')
+
+        However, alternate symbols must be hashable (immutable,
+        unchangeable).  For example, Python lists are not hashable. ::
+
+            sage: groups.SymmetricPermutation([[1,0], [0,1]])
+            Traceback (most recent call last):
+            ...
+            TypeError: unhashable type: 'list'
+
+        For further documentation, see
+        :meth:`~sage.groups.perm_gps.permgroup_named.SymmetricGroup`.
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.SymmetricGroup(n)
+
+    def AlternatingPermutation(self, n):
+        r"""
+        The alternating group on `n` symbols, as a permutation group.
+
+        INPUT:
+
+        - ``n`` - a positive integer, or a list.  If ``n`` is
+          an integer, then the symbol set is the integers
+          `\{1,2,\dots,n\}`.  Otherwise the symbol set is
+          the list given by `n`, provided the objects in
+          the list are hashable (i.e. immutable).
+
+        OUTPUT:
+
+        The alternating group of order `n!/2` with all possible
+        even permutations of the `n` symbols.  (An "even"
+        permutation is one that can be written as a product
+        of an even number of cycles of length two, which are also
+        known as "transpositions".)
+
+        EXAMPLES::
+
+            sage: A = groups.AlternatingPermutation(3)
+            sage: A.list()
+            [(), (1,2,3), (1,3,2)]
+            sage: H = groups.AlternatingPermutation(10)
+            sage: H.order() == factorial(10)/2
+            True
+
+        The :meth:`~sage.groups.perm_gps.permgroup_element.PermutationGroupElement.sign`
+        method for permutation group elements is ``+1`` for
+        an even permutation and ``-1`` for odd elements.  ::
+
+            sage: S = groups.SymmetricPermutation(5)
+            sage: A = groups.AlternatingPermutation(5)
+            sage: a = S("(1,3)(4,5)")
+            sage: b = S("(2,3)(1,5)")
+            sage: c = a*b
+            sage: c.sign()
+            1
+            sage: c in A
+            True
+            sage: d = S("(1,2,3,4)")
+            sage: d.sign()
+            -1
+            sage: d in A
+            False
+
+        A symmetric group can be a good base for creating subgroups
+        of interest.  ::
+
+            sage: G = groups.SymmetricPermutation(11)
+            sage: a = G("(1, 2, 3, 4, 5)(7, 8, 9, 10,11)")
+            sage: b = G("(1, 2, 3)(4, 5, 6, 7, 8)(9, 10, 11)")
+            sage: H = G.subgroup([a, b])
+            sage: H.order()
+            19958400
+
+        Alternate symbol sets are possible.  The other permutation group
+        which allows for the specification of an alternate symbol set is the :meth:`~sage.groups.group_generators.GroupGenerators.SymmetricPermutation`
+        member of the ``groups`` object, so also look there for more
+        documentation. ::
+
+            sage: A = groups.AlternatingPermutation(['dog', 'cat', 'fish'])
+            sage: A
+            Alternating group of order 3!/2 as a permutation group
+            sage: A.an_element()
+            ('dog','cat','fish')
+
+        For further documentation, see
+        :meth:`~sage.groups.perm_gps.permgroup_named.AlternatingGroup`.
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.AlternatingGroup(n)
+        
+    def CyclicPermutation(self, n):
+        r"""
+        A cyclic group as a permutation group.
+
+        INPUT:
+
+        - ``n`` - a positive integer, the size of the group.
+
+        OUTPUT:
+
+        A cyclic group of order `n` as a permutation group of size `n`.
+
+        EXAMPLES::
+
+            sage: G = groups.CyclicPermutation(4)
+            sage: G.list()
+            [(), (1,2,3,4), (1,3)(2,4), (1,4,3,2)]
+
+        For further documentation, see
+        :meth:`~sage.groups.perm_gps.permgroup_named.CyclicPermutationGroup`.
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.CyclicPermutationGroup(n)
+
+    def DihedralPermutation(self, n):
+        r"""
+        The dicyclic group of order `2n`, as a permutation group.
+
+        INPUT:
+
+        - ``n`` - a positive integer.
+
+        OUTPUT:
+
+        The dicyclic group of order `2n`, which is a
+        non-abelian group containing the symmetries of a
+        regular `n`-gon, represented as a permutation group.
+
+        EXAMPLES:
+
+        For an even `n` the center of the dihedral group
+        will contain the symmetry that is a half-turn of
+        the `n`-gon.  ::
+
+            sage: G = groups.DihedralPermutation(8)
+            sage: G.order()
+            16
+            sage: G.is_abelian()
+            False
+            sage: G.center().list()
+            [(), (1,5)(2,6)(3,7)(4,8)]
+
+        For further documentation, see
+        :meth:`~sage.groups.perm_gps.permgroup_named.DihedralGroup`.
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.DihedralGroup(n)
+        
+    def DiCyclicPermutation(self, n):
+        r"""
+        The dicyclic group of order `4n`, as a permutation group.
+
+        INPUT:
+
+        - ``n`` - a positive integer.
+
+        OUTPUT:
+
+        The dicyclic group of order `4n`, a non-abelian group
+        represented as a permutation group.
+
+        EXAMPLES:
+
+        One notable property of the dicyclic group is that it has a single
+        element of order 2.  There are 3 non-abelian groups of order 12;
+        the alternating group on 4 symbols, the dihedral group that is
+        symmetries of a regular hexagon, and the dicyclic group of
+        order 12. ::
+
+            sage: G = groups.DiCyclicPermutation(3)
+            sage: G.order()
+            12
+            sage: G.is_abelian()
+            False
+            sage: [a for a in G if a.order() == 2]
+            [(1,2)(3,4)]
+            
+        For further documentation, see
+        :meth:`~sage.groups.perm_gps.permgroup_named.DiCyclicGroup`.
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.DiCyclicGroup(n)
+
+    def MathieuPermutation(self, degree):
+        r"""
+        Returns a Mathieu group as a permutation group.
+
+        INPUT:
+
+        - ``degree`` - the number of symbols in the
+          ambient symmetric group.  Allowable values are
+          9, 10, 11, 12, 21, 22, 23, and 24.
+
+        OUTPUT:
+
+        A Mathieu group, as a permutation of the integers
+        ``1`` through ``degree``.
+
+        EXAMPLES:
+
+        `M_{22}` is simple and `3`-transitive.  ::
+
+            sage: G = groups.MathieuPermutation(22)
+            sage: G.is_simple()
+            True
+            sage: S1 = G.stabilizer(1)
+            sage: S1.orbits()
+            [[1], [2, 7, 15, 3, 17, 13, 10, 4, 22, 19, 14, 11, 20, 21, 8, 6, 9, 12, 18, 16, 5]]
+            sage: S2 = S1.stabilizer(2)
+            sage: S2.orbits()
+            [[1], [2], [3, 14, 22, 17, 4, 10, 13, 11, 9, 6, 5, 16, 18, 12, 8, 7, 15, 21, 20, 19]]
+            sage: S3 = S2.stabilizer(3)
+            sage: S3.orbits()
+            [[1], [2], [3], [4, 12, 22, 14, 11, 5, 21, 9, 19, 13, 8, 15, 18, 17, 6, 16], [7, 10, 20]]
+            
+        For further documentation, see
+        :meth:`~sage.groups.perm_gps.permgroup_named.MathieuGroup`.
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.MathieuGroup(degree)
+
+    def SuzukiPermutation(self, q):
+        r"""
+        A Suzuki group over the field with `q` elements, as a permutation group.
+
+        INPUT:
+
+        - ``q`` - in a matrix group representation, the elements
+          of the matrices are from a finite field of size `q`.  This
+          must be an odd power of 2.
+
+        OUTPUT:
+
+        An instance of a Suzuki group, an infinite family of groups of
+        Lie type. For `q > 2` each is a simple group.  This family of
+        groups *does not* include the sporadic simple group known as
+        the Suzuki group.
+
+        EXAMPLES:
+
+        The Suzuki groups have order `q^2(q^2+1)(q-1)` and are
+        characterized as the non-cyclic, finite simple groups with
+        orders not divisible by 3.  The number of conjugacy classes
+        is given by `q+3`. ::
+
+            sage: q = 2^5
+            sage: H = groups.SuzukiPermutation(2^5)
+            sage: H.degree()
+            1025
+            sage: H.is_cyclic()
+            False
+            sage: H.is_simple()
+            True
+            sage: H.order()
+            32537600
+            sage: H.order() == q^2*(q^2+1)*(q-1)
+            True
+            sage: len(H.conjugacy_classes_representatives()) == q+3
+            True
+
+        The smallest case is not a simple group, though the
+        remainder are. ::
+
+            sage: G = groups.SuzukiPermutation(2^1)
+            sage: G.order()
+            20
+            sage: G.is_simple()
+            False
+        
+        For further documentation, see
+        :meth:`~sage.groups.perm_gps.permgroup_named.SuzukiGroup`.
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.SuzukiGroup(q)
+        
+    def QuaternionMatrixGF3(self):
+        r"""
+        The quaternion group as a set of `2\times 2` matrices over `GF(3)`.
+
+        OUTPUT:
+
+        A matrix group consisting of `2\times 2` matrices with
+        elements from the finite field of order 3.  The group is
+        the quaternion group, the nonabelian group of order 8 that
+        is not isomorphic to the group of symmetries of a square
+        (the dihedral group `D_4`).
+
+        EXAMPLES:
+
+        The generators are the matrix representations of the
+        elements commonly called `I` and `J`, while `K`
+        is the product of `I` and `J`. ::
+            
+            sage: Q = groups.QuaternionMatrixGF3()
+            sage: Q.order()
+            8
+            sage: aye = Q.gens()[0]; aye
+            [1 1]
+            [1 2]
+            sage: jay = Q.gens()[1]; jay
+            [2 1]
+            [1 1]
+            sage: kay = aye*jay; kay
+            [0 2]
+            [1 0]
+
+        TESTS::
+        
+            sage: Q = groups.QuaternionMatrixGF3()
+            sage: QP = Q.as_permutation_group()
+            sage: QP.is_isomorphic(groups.QuaternionPermutation())
+            True
+            sage: H = DihedralGroup(4)
+            sage: H.order()
+            8
+            sage: QP.is_abelian(), H.is_abelian()
+            (False, False)
+            sage: QP.is_isomorphic(H)
+            False
+        """
+        from sage.rings.finite_rings.constructor import FiniteField
+        from sage.matrix.matrix_space import MatrixSpace
+        from sage.groups.matrix_gps.matrix_group import MatrixGroup
+        MS = MatrixSpace(FiniteField(3), 2)
+        aye = MS([1,1,1,2])
+        jay = MS([2,1,1,1])
+        return MatrixGroup([aye, jay])
+
+    def QuaternionPermutation(self):
+        r"""
+        The quaternion group as a set of permutations in `S_8`.
+
+        OUTPUT:
+
+        A group of permutations on the symbols ``1`` to ``8`` that
+        is the nonabelian group of order 8 that is not isomorphic
+        to the group of symmetries of a square (the dihedral
+        group `D_4`).
+
+        EXAMPLES::
+
+            sage: G = groups.QuaternionPermutation()
+            sage: G.degree()
+            8
+            sage: G.order()
+            8
+            sage: sorted([x.order() for x in G])
+            [1, 2, 4, 4, 4, 4, 4, 4]
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.QuaternionGroup()
+
+#~~~~~~~~~~~~~~
+# Matrix Groups
+#~~~~~~~~~~~~~~
+
+    def GLMatrix(self, n, R, name='a'):
+        r"""
+        The general linear group of invertible matrices,
+        as a matrix group.
+
+        INPUT:
+
+        - ``n`` - a positive integer specifying the size
+          of the matrices.
+        - ``R`` - the ring used for entries of the matrices.
+          Supported rings are the integers (``ZZ``),
+          integers mod m (``Integers(m)``) and finite fields
+          (``GF(p^k, 'a')``).  If an integer is given for this
+          parameter, it will be interpreted as the order of a
+          finite field (so hence must be a power of a prime)
+          and for a field with a degree greater than 1 a default
+          generator will be provided.
+
+        OUTPUT:
+
+        The group of `n\times n` matrices with entries from the
+        ring ``R``.
+
+        EXAMPLES:
+
+        The order of `GL(4, 3)` can be shown to be
+
+        .. MATH::
+
+            (3^4-3^0)(3^4-3^1)(3^4-3^2)(3^4-3^3) = 24\,261\,120
+
+        ::
+
+            sage: S = groups.GLMatrix(4, GF(3))
+            sage: S.order()
+            24261120
+            sage: s = S.an_element(); s
+            [2 0 0 0]
+            [0 1 0 0]
+            [0 0 1 0]
+            [0 0 0 1]
+            sage: s.matrix().is_invertible()
+            True
+
+        A finite field may given simply by its order.  A
+        default generator will be provided for the field.
+        Or you can provide a generator of your own.  Or,
+        you can create the field yourself and provide it.  ::
+
+            sage: G = groups.GLMatrix(2, 5^3)
+            sage: G
+            General Linear Group of degree 2 over Finite Field in a of size 5^3
+            sage: H = groups.GLMatrix(2, 5^3, name='b')
+            sage: H
+            General Linear Group of degree 2 over Finite Field in b of size 5^3
+            sage: F.<c> = FiniteField(5^3)
+            sage: K = groups.GLMatrix(2, F)
+            sage: K
+            General Linear Group of degree 2 over Finite Field in c of size 5^3
+            sage: K.base_ring() is F
+            True
+
+        Two types of rings, that are not fields, are supported.
+        One produces an infinite group.  ::
+
+            sage: G = groups.GLMatrix(5, Integers(10))
+            sage: G.order()
+            2266004566425600000000000
+            sage: H = groups.GLMatrix(5, ZZ)
+            sage: H.order()
+            +Infinity
+                
+        For further documentation, see
+        :meth:`~sage.groups.matrix_gps.general_linear.GL`.
+        """
+        import sage.groups.matrix_gps.general_linear
+        # R is a finite field, ZZ, Integers(m) 50.2-1 in GAP
+        return sage.groups.matrix_gps.general_linear.GL(n, R, name)
+        
+    def SLMatrix(self, n, R, name='a'):
+        r"""
+        The special linear group of matrices with determinant 1,
+        as a matrix group.
+
+        INPUT:
+        
+        - ``n`` - a positive integer specifying the size
+          of the matrices.
+        - ``R`` - the ring used for entries of the matrices.
+          Supported rings are the integers (``ZZ``),
+          integers mod m (``Integers(m)``) and finite fields
+          (``GF(p^k, 'a')``).  If an integer is given for this
+          parameter, it will be interpreted as the order of a
+          finite field (so hence must be a power of a prime)
+          and for a field with a degree greater than 1 a default
+          generator will be provided.
+
+        OUTPUT:
+
+        The group of `n\times n` matrices with entries from the
+        ring ``R`` and with determinant 1.
+
+        EXAMPLES:
+
+        The order of `SL(4, 3)` can be shown to be
+
+        .. MATH::
+
+            (3^4-3^0)(3^4-3^1)(3^4-3^2)(3^4-3^3)/(3-1) = 12\,130\,560
+            
+        ::
+
+            sage: S = groups.SLMatrix(4, GF(3))
+            sage: S.order()
+            12130560
+            sage: s = S.an_element(); s
+            [0 0 0 1]
+            [2 0 0 0]
+            [0 2 0 0]
+            [0 0 2 0]
+            sage: s.matrix().determinant()
+            1
+
+        Over a field, this group is a normal subgroup of the
+        general linear group, since it is the kernel of a
+        natural homomorphism given by the determinant.
+
+        We do not have a check for normality for matrix groups,
+        but we can convert our groups to native objects in GAP
+        and then use a Pythonic interface to the commands available
+        in GAP.  ::
+
+            sage: G = groups.GLMatrix(4, 3^2)
+            sage: S = groups.SLMatrix(4, 3^2)
+            sage: G.order()/S.order()
+            8
+
+            sage: Ggap = G._gap_()
+            sage: Sgap = S._gap_()
+            sage: Sgap.IsNormal(Ggap)
+            true
+
+        A finite field may given simply by its order.  A
+        default generator will be provided for the field.
+        Or you can provide a generator of your own.  Or,
+        you can create the field yourself and provide it.  ::
+
+            sage: S = groups.SLMatrix(2, 5^3)
+            sage: S
+            Special Linear Group of degree 2 over Finite Field in a of size 5^3
+            sage: T = groups.SLMatrix(2, 5^3, name='b')
+            sage: T
+            Special Linear Group of degree 2 over Finite Field in b of size 5^3
+            sage: F.<c> = FiniteField(5^3)
+            sage: U = groups.SLMatrix(2, F)
+            sage: U
+            Special Linear Group of degree 2 over Finite Field in c of size 5^3
+            sage: U.base_ring() is F
+            True
+
+        Two types of rings, that are not fields, are supported.
+        One produces an infinite group.  ::
+
+            sage: S = groups.SLMatrix(5, Integers(10))
+            sage: S.order()
+            566501141606400000000000
+            sage: S = groups.SLMatrix(5, ZZ)
+            sage: S.order()
+            +Infinity
+
+        For further documentation, see
+        :meth:`~sage.groups.matrix_gps.special_linear.SL`.
+        """
+        import sage.groups.matrix_gps.special_linear
+        # R is a finite field, ZZ, Integers(m) 50.2-1 in GAP
+        return sage.groups.matrix_gps.special_linear.SL(n, R, name)
+
+    def PGLPermutation(self, n, q, name='a'):
+        r"""
+        The projective general linear group as a permutation group.
+
+        INPUT:
+
+        - ``n`` - size of the square matrices in the group
+        - ``q`` - order of the finite field used for the
+          entries of the matrices.  Must be a prime power order.
+        - ``name`` - default: ``'a'`` - a string used to form
+          the names of the elements of the finite field.
+
+        OUTPUT:
+
+        The projective general linear group has elements that
+        are `n\times n` matrices.  Here we limit the entries of
+        the matrices to elements of a finite field of order `q`.
+        For finite fields of degree 2 or more ``name`` is a string
+        that is used to construct the names of the elements of the
+        field.  More specifically, the group is the quotient of
+        the general linear group by its center.
+
+        The representation returned here is a permutation group
+        rather than a matrix group. If `F` is the field field,
+        then the items being permuted are the dimension one
+        subspaces of the vector space `F^n`, which are also
+        known as "lines".
+
+        EXAMPLES:
+
+        The general linear group of `2\times 2` matrices over a
+        finite field of order 3 is composed of 48 invertible matrices.
+        The center has order 2, hence the projective group has order 24.
+        The vector space of dimension 2 over the field of order 3 has 8
+        nonzero vectors, which partition into 4 dimension one subspaces
+        (the lines).  Hence the permutation representation is a subgroup
+        of the symmetric group on 4 symbols. ::
+
+            sage: G = groups.PGLPermutation(2,3)
+            sage: G.order()
+            24
+            sage: F = G.base_ring()
+            sage: V = F^2
+            sage: len(list(V.subspaces(1)))
+            4
+            sage: G.degree()
+            4
+
+        Using a finite field of degree greater than one, the symbol
+        used to describe the elements of the field may be specified.
+        The irreducible polynomial used to structure the field is
+        provided automatically by the GAP library and may not be changed. ::
+
+            sage: K = groups.PGLPermutation(2, 81, name='c')
+            sage: K.order()
+            531360
+            sage: F = K.base_ring(); F
+            Finite Field in c of size 3^4
+            sage: F.polynomial()
+            c^4 + 2*c^3 + 2
+        
+        For further documentation, see
+        :meth:`~sage.groups.perm_gps.permgroup_named.PGL`.
+        """
+        import sage.groups.perm_gps.permgroup_named
+        return sage.groups.perm_gps.permgroup_named.PGL(n, q, name)
+
+
+
+
+
+
+        
+# This is the object available in the global namespace        
+groups = GroupGenerators()
+
+
+    
+ No newline at end of file