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

File trac_13115-groups-object-v2.patch, 25.8 KB (added by rbeezer, 10 years ago)
  • doc/en/reference/groups.rst

    # HG changeset patch
    # User Rob Beezer <beezer@ups.edu>
    # Date 1339645864 25200
    # Node ID 39d874497889a224b91cd5733136da8b0f94b913
    # Parent  7a2a36b9da0fc4bfc82fbd11ca7d48f741f74bf7
    13115: groups object to organize examples of groups
    
    diff --git a/doc/en/reference/groups.rst b/doc/en/reference/groups.rst
    a b  
    66.. toctree::
    77   :maxdepth: 2
    88
     9   sage/groups/group_generators
    910   sage/groups/group
    1011   sage/groups/generic
    1112   sage/groups/abelian_gps/abelian_group
  • sage/groups/all.py

    diff --git a/sage/groups/all.py b/sage/groups/all.py
    a b  
    1212from class_function import ClassFunction
    1313
    1414from additive_abelian.all import *
     15
     16from group_generators import groups
  • new file sage/groups/group_generators.py

    diff --git a/sage/groups/group_generators.py b/sage/groups/group_generators.py
    new file mode 100644
    - +  
     1r"""
     2Examples of Groups
     3~~~~~~~~~~~~~~~~~~
     4
     5    The ``groups`` object, an instance of the :class:`GroupGenerators` class,
     6    contains methods that return examples of various groups.  Using
     7    tab-completion on this object is an easy way to discover and quickly
     8    create the groups that are available (as listed here).
     9
     10    - Small Groups
     11        - :meth:`~sage.groups.group_generators.GroupGenerators.KleinFourPermutation`
     12        - :meth:`~sage.groups.group_generators.GroupGenerators.QuaternionPermutation`
     13        - :meth:`~sage.groups.group_generators.GroupGenerators.QuaternionMatrixGF3`
     14    - Families of Permutation Groups
     15        - :meth:`~sage.groups.group_generators.GroupGenerators.SymmetricPermutation`
     16        - :meth:`~sage.groups.group_generators.GroupGenerators.AlternatingPermutation`
     17        - :meth:`~sage.groups.group_generators.GroupGenerators.CyclicPermutation`
     18        - :meth:`~sage.groups.group_generators.GroupGenerators.DihedralPermutation`
     19        - :meth:`~sage.groups.group_generators.GroupGenerators.DiCyclicPermutation`
     20        - :meth:`~sage.groups.group_generators.GroupGenerators.MathieuPermutation`
     21        - :meth:`~sage.groups.group_generators.GroupGenerators.SuzukiPermutation`
     22    - Families of Matrix Groups
     23        - :meth:`~sage.groups.group_generators.GroupGenerators.GLMatrix`
     24        - :meth:`~sage.groups.group_generators.GroupGenerators.SLMatrix`
     25        - :meth:`~sage.groups.group_generators.GroupGenerators.PGLPermutation`
     26
     27"""
     28
     29class GroupGenerators(object):
     30    r"""
     31    An object of this class gives convenient references
     32    to examples of graphs.
     33
     34    The global ``groups`` object can be used with tab-completion
     35    to easily and quickly locate examples of groups implemented in Sage.
     36
     37    .. warning::
     38
     39        This list is under development, so may not be exhaustive.
     40    """
     41
     42    def __repr__(self):
     43        r"""
     44        A message about the purpose of this object.
     45
     46        TESTS::
     47       
     48            sage: groups   # indirect doctest
     49            Object collecting examples of graphs, try "groups.<tab>"
     50        """
     51        return 'Object collecting examples of graphs, try "groups.<tab>"'
     52       
     53    def KleinFourPermutation(self):
     54        r"""
     55        The non-cyclic group of order 4, isomorphic to `\ZZ_2\times\ZZ_2`.
     56
     57        OUTPUT:
     58
     59        The non-cyclic group of order 4, as a permutation group
     60        on 4 symbols.
     61
     62        EXAMPLES::
     63
     64            sage: K = groups.KleinFourPermutation()
     65            sage: K.list()
     66            [(), (3,4), (1,2), (1,2)(3,4)]
     67
     68        For further documentation, see
     69        :meth:`~sage.groups.perm_gps.permgroup_named.KleinFourGroup`.
     70        """
     71        import sage.groups.perm_gps.permgroup_named
     72        return sage.groups.perm_gps.permgroup_named.KleinFourGroup()
     73       
     74    def SymmetricPermutation(self, n):
     75        r"""
     76        The full symmetric group on `n` symbols, as a permutation group.
     77
     78        INPUT:
     79
     80        - ``n`` - a positive integer, or a list.  If ``n`` is
     81          an integer, then the symbol set is the integers
     82          `\{1,2,\dots,n\}`.  Otherwise the symbol set is
     83          the list given by `n`, provided the objects in
     84          the list are hashable (i.e. immutable).
     85
     86        OUTPUT:
     87
     88        The full group of order `n!` with all possible
     89        permutations of the `n` symbols.
     90
     91        EXAMPLES::
     92
     93            sage: G = groups.SymmetricPermutation(3)
     94            sage: G.list()
     95            [(), (2,3), (1,2), (1,2,3), (1,3,2), (1,3)]
     96            sage: H = groups.SymmetricPermutation(10)
     97            sage: H.order() == factorial(10)
     98            True
     99
     100        A symmetric group can be a good base for creating subgroups
     101        of interest.  ::
     102
     103            sage: S = groups.SymmetricPermutation(11)
     104            sage: a = S("(1, 2, 3, 4, 5)(7, 8, 9, 10,11)")
     105            sage: b = S("(1, 2, 3)(4, 5, 6, 7, 8)(9, 10, 11)")
     106            sage: H = S.subgroup([a, b])
     107            sage: S.order()/H.order()
     108            2
     109
     110        Alternate symbol sets are possible.  ::
     111
     112            sage: G = groups.SymmetricPermutation(['dog', 'cat', 'fish'])
     113            sage: G
     114            Symmetric group of order 3! as a permutation group
     115            sage: G.an_element()
     116            ('dog','cat','fish')
     117
     118        However, alternate symbols must be hashable (immutable,
     119        unchangeable).  For example, Python lists are not hashable. ::
     120
     121            sage: groups.SymmetricPermutation([[1,0], [0,1]])
     122            Traceback (most recent call last):
     123            ...
     124            TypeError: unhashable type: 'list'
     125
     126        For further documentation, see
     127        :meth:`~sage.groups.perm_gps.permgroup_named.SymmetricGroup`.
     128        """
     129        import sage.groups.perm_gps.permgroup_named
     130        return sage.groups.perm_gps.permgroup_named.SymmetricGroup(n)
     131
     132    def AlternatingPermutation(self, n):
     133        r"""
     134        The alternating group on `n` symbols, as a permutation group.
     135
     136        INPUT:
     137
     138        - ``n`` - a positive integer, or a list.  If ``n`` is
     139          an integer, then the symbol set is the integers
     140          `\{1,2,\dots,n\}`.  Otherwise the symbol set is
     141          the list given by `n`, provided the objects in
     142          the list are hashable (i.e. immutable).
     143
     144        OUTPUT:
     145
     146        The alternating group of order `n!/2` with all possible
     147        even permutations of the `n` symbols.  (An "even"
     148        permutation is one that can be written as a product
     149        of an even number of cycles of length two, which are also
     150        known as "transpositions".)
     151
     152        EXAMPLES::
     153
     154            sage: A = groups.AlternatingPermutation(3)
     155            sage: A.list()
     156            [(), (1,2,3), (1,3,2)]
     157            sage: H = groups.AlternatingPermutation(10)
     158            sage: H.order() == factorial(10)/2
     159            True
     160
     161        The :meth:`~sage.groups.perm_gps.permgroup_element.PermutationGroupElement.sign`
     162        method for permutation group elements is ``+1`` for
     163        an even permutation and ``-1`` for odd elements.  ::
     164
     165            sage: S = groups.SymmetricPermutation(5)
     166            sage: A = groups.AlternatingPermutation(5)
     167            sage: a = S("(1,3)(4,5)")
     168            sage: b = S("(2,3)(1,5)")
     169            sage: c = a*b
     170            sage: c.sign()
     171            1
     172            sage: c in A
     173            True
     174            sage: d = S("(1,2,3,4)")
     175            sage: d.sign()
     176            -1
     177            sage: d in A
     178            False
     179
     180        A symmetric group can be a good base for creating subgroups
     181        of interest.  ::
     182
     183            sage: G = groups.SymmetricPermutation(11)
     184            sage: a = G("(1, 2, 3, 4, 5)(7, 8, 9, 10,11)")
     185            sage: b = G("(1, 2, 3)(4, 5, 6, 7, 8)(9, 10, 11)")
     186            sage: H = G.subgroup([a, b])
     187            sage: H.order()
     188            19958400
     189
     190        Alternate symbol sets are possible.  The other permutation group
     191        which allows for the specification of an alternate symbol set is the :meth:`~sage.groups.group_generators.GroupGenerators.SymmetricPermutation`
     192        member of the ``groups`` object, so also look there for more
     193        documentation. ::
     194
     195            sage: A = groups.AlternatingPermutation(['dog', 'cat', 'fish'])
     196            sage: A
     197            Alternating group of order 3!/2 as a permutation group
     198            sage: A.an_element()
     199            ('dog','cat','fish')
     200
     201        For further documentation, see
     202        :meth:`~sage.groups.perm_gps.permgroup_named.AlternatingGroup`.
     203        """
     204        import sage.groups.perm_gps.permgroup_named
     205        return sage.groups.perm_gps.permgroup_named.AlternatingGroup(n)
     206       
     207    def CyclicPermutation(self, n):
     208        r"""
     209        A cyclic group as a permutation group.
     210
     211        INPUT:
     212
     213        - ``n`` - a positive integer, the size of the group.
     214
     215        OUTPUT:
     216
     217        A cyclic group of order `n` as a permutation group of size `n`.
     218
     219        EXAMPLES::
     220
     221            sage: G = groups.CyclicPermutation(4)
     222            sage: G.list()
     223            [(), (1,2,3,4), (1,3)(2,4), (1,4,3,2)]
     224
     225        For further documentation, see
     226        :meth:`~sage.groups.perm_gps.permgroup_named.CyclicPermutationGroup`.
     227        """
     228        import sage.groups.perm_gps.permgroup_named
     229        return sage.groups.perm_gps.permgroup_named.CyclicPermutationGroup(n)
     230
     231    def DihedralPermutation(self, n):
     232        r"""
     233        The dicyclic group of order `2n`, as a permutation group.
     234
     235        INPUT:
     236
     237        - ``n`` - a positive integer.
     238
     239        OUTPUT:
     240
     241        The dicyclic group of order `2n`, which is a
     242        non-abelian group containing the symmetries of a
     243        regular `n`-gon, represented as a permutation group.
     244
     245        EXAMPLES:
     246
     247        For an even `n` the center of the dihedral group
     248        will contain the symmetry that is a half-turn of
     249        the `n`-gon.  ::
     250
     251            sage: G = groups.DihedralPermutation(8)
     252            sage: G.order()
     253            16
     254            sage: G.is_abelian()
     255            False
     256            sage: G.center().list()
     257            [(), (1,5)(2,6)(3,7)(4,8)]
     258
     259        For further documentation, see
     260        :meth:`~sage.groups.perm_gps.permgroup_named.DihedralGroup`.
     261        """
     262        import sage.groups.perm_gps.permgroup_named
     263        return sage.groups.perm_gps.permgroup_named.DihedralGroup(n)
     264       
     265    def DiCyclicPermutation(self, n):
     266        r"""
     267        The dicyclic group of order `4n`, as a permutation group.
     268
     269        INPUT:
     270
     271        - ``n`` - a positive integer.
     272
     273        OUTPUT:
     274
     275        The dicyclic group of order `4n`, a non-abelian group
     276        represented as a permutation group.
     277
     278        EXAMPLES:
     279
     280        One notable property of the dicyclic group is that it has a single
     281        element of order 2.  There are 3 non-abelian groups of order 12;
     282        the alternating group on 4 symbols, the dihedral group that is
     283        symmetries of a regular hexagon, and the dicyclic group of
     284        order 12. ::
     285
     286            sage: G = groups.DiCyclicPermutation(3)
     287            sage: G.order()
     288            12
     289            sage: G.is_abelian()
     290            False
     291            sage: [a for a in G if a.order() == 2]
     292            [(1,2)(3,4)]
     293           
     294        For further documentation, see
     295        :meth:`~sage.groups.perm_gps.permgroup_named.DiCyclicGroup`.
     296        """
     297        import sage.groups.perm_gps.permgroup_named
     298        return sage.groups.perm_gps.permgroup_named.DiCyclicGroup(n)
     299
     300    def MathieuPermutation(self, degree):
     301        r"""
     302        Returns a Mathieu group as a permutation group.
     303
     304        INPUT:
     305
     306        - ``degree`` - the number of symbols in the
     307          ambient symmetric group.  Allowable values are
     308          9, 10, 11, 12, 21, 22, 23, and 24.
     309
     310        OUTPUT:
     311
     312        A Mathieu group, as a permutation of the integers
     313        ``1`` through ``degree``.
     314
     315        EXAMPLES:
     316
     317        `M_{22}` is simple and `3`-transitive.  ::
     318
     319            sage: G = groups.MathieuPermutation(22)
     320            sage: G.is_simple()
     321            True
     322            sage: S1 = G.stabilizer(1)
     323            sage: S1.orbits()
     324            [[1], [2, 7, 15, 3, 17, 13, 10, 4, 22, 19, 14, 11, 20, 21, 8, 6, 9, 12, 18, 16, 5]]
     325            sage: S2 = S1.stabilizer(2)
     326            sage: S2.orbits()
     327            [[1], [2], [3, 14, 22, 17, 4, 10, 13, 11, 9, 6, 5, 16, 18, 12, 8, 7, 15, 21, 20, 19]]
     328            sage: S3 = S2.stabilizer(3)
     329            sage: S3.orbits()
     330            [[1], [2], [3], [4, 12, 22, 14, 11, 5, 21, 9, 19, 13, 8, 15, 18, 17, 6, 16], [7, 10, 20]]
     331           
     332        For further documentation, see
     333        :meth:`~sage.groups.perm_gps.permgroup_named.MathieuGroup`.
     334        """
     335        import sage.groups.perm_gps.permgroup_named
     336        return sage.groups.perm_gps.permgroup_named.MathieuGroup(degree)
     337
     338    def SuzukiPermutation(self, q):
     339        r"""
     340        A Suzuki group over the field with `q` elements, as a permutation group.
     341
     342        INPUT:
     343
     344        - ``q`` - in a matrix group representation, the elements
     345          of the matrices are from a finite field of size `q`.  This
     346          must be an odd power of 2.
     347
     348        OUTPUT:
     349
     350        An instance of a Suzuki group, an infinite family of groups of
     351        Lie type. For `q > 2` each is a simple group.  This family of
     352        groups *does not* include the sporadic simple group known as
     353        the Suzuki group.
     354
     355        EXAMPLES:
     356
     357        The Suzuki groups have order `q^2(q^2+1)(q-1)` and are
     358        characterized as the non-cyclic, finite simple groups with
     359        orders not divisible by 3.  The number of conjugacy classes
     360        is given by `q+3`. ::
     361
     362            sage: q = 2^5
     363            sage: H = groups.SuzukiPermutation(2^5)
     364            sage: H.degree()
     365            1025
     366            sage: H.is_cyclic()
     367            False
     368            sage: H.is_simple()
     369            True
     370            sage: H.order()
     371            32537600
     372            sage: H.order() == q^2*(q^2+1)*(q-1)
     373            True
     374            sage: len(H.conjugacy_classes_representatives()) == q+3
     375            True
     376
     377        The smallest case is not a simple group, though the
     378        remainder are. ::
     379
     380            sage: G = groups.SuzukiPermutation(2^1)
     381            sage: G.order()
     382            20
     383            sage: G.is_simple()
     384            False
     385       
     386        For further documentation, see
     387        :meth:`~sage.groups.perm_gps.permgroup_named.SuzukiGroup`.
     388        """
     389        import sage.groups.perm_gps.permgroup_named
     390        return sage.groups.perm_gps.permgroup_named.SuzukiGroup(q)
     391       
     392    def QuaternionMatrixGF3(self):
     393        r"""
     394        The quaternion group as a set of `2\times 2` matrices over `GF(3)`.
     395
     396        OUTPUT:
     397
     398        A matrix group consisting of `2\times 2` matrices with
     399        elements from the finite field of order 3.  The group is
     400        the quaternion group, the nonabelian group of order 8 that
     401        is not isomorphic to the group of symmetries of a square
     402        (the dihedral group `D_4`).
     403
     404        EXAMPLES:
     405
     406        The generators are the matrix representations of the
     407        elements commonly called `I` and `J`, while `K`
     408        is the product of `I` and `J`. ::
     409           
     410            sage: Q = groups.QuaternionMatrixGF3()
     411            sage: Q.order()
     412            8
     413            sage: aye = Q.gens()[0]; aye
     414            [1 1]
     415            [1 2]
     416            sage: jay = Q.gens()[1]; jay
     417            [2 1]
     418            [1 1]
     419            sage: kay = aye*jay; kay
     420            [0 2]
     421            [1 0]
     422
     423        TESTS::
     424       
     425            sage: Q = groups.QuaternionMatrixGF3()
     426            sage: QP = Q.as_permutation_group()
     427            sage: QP.is_isomorphic(groups.QuaternionPermutation())
     428            True
     429            sage: H = DihedralGroup(4)
     430            sage: H.order()
     431            8
     432            sage: QP.is_abelian(), H.is_abelian()
     433            (False, False)
     434            sage: QP.is_isomorphic(H)
     435            False
     436        """
     437        from sage.rings.finite_rings.constructor import FiniteField
     438        from sage.matrix.matrix_space import MatrixSpace
     439        from sage.groups.matrix_gps.matrix_group import MatrixGroup
     440        MS = MatrixSpace(FiniteField(3), 2)
     441        aye = MS([1,1,1,2])
     442        jay = MS([2,1,1,1])
     443        return MatrixGroup([aye, jay])
     444
     445    def QuaternionPermutation(self):
     446        r"""
     447        The quaternion group as a set of permutations in `S_8`.
     448
     449        OUTPUT:
     450
     451        A group of permutations on the symbols ``1`` to ``8`` that
     452        is the nonabelian group of order 8 that is not isomorphic
     453        to the group of symmetries of a square (the dihedral
     454        group `D_4`).
     455
     456        EXAMPLES::
     457
     458            sage: G = groups.QuaternionPermutation()
     459            sage: G.degree()
     460            8
     461            sage: G.order()
     462            8
     463            sage: sorted([x.order() for x in G])
     464            [1, 2, 4, 4, 4, 4, 4, 4]
     465        """
     466        import sage.groups.perm_gps.permgroup_named
     467        return sage.groups.perm_gps.permgroup_named.QuaternionGroup()
     468
     469#~~~~~~~~~~~~~~
     470# Matrix Groups
     471#~~~~~~~~~~~~~~
     472
     473    def GLMatrix(self, n, R, name='a'):
     474        r"""
     475        The general linear group of invertible matrices,
     476        as a matrix group.
     477
     478        INPUT:
     479
     480        - ``n`` - a positive integer specifying the size
     481          of the matrices.
     482        - ``R`` - the ring used for entries of the matrices.
     483          Supported rings are the integers (``ZZ``),
     484          integers mod m (``Integers(m)``) and finite fields
     485          (``GF(p^k, 'a')``).  If an integer is given for this
     486          parameter, it will be interpreted as the order of a
     487          finite field (so hence must be a power of a prime)
     488          and for a field with a degree greater than 1 a default
     489          generator will be provided.
     490
     491        OUTPUT:
     492
     493        The group of `n\times n` matrices with entries from the
     494        ring ``R``.
     495
     496        EXAMPLES:
     497
     498        The order of `GL(4, 3)` can be shown to be
     499
     500        .. MATH::
     501
     502            (3^4-3^0)(3^4-3^1)(3^4-3^2)(3^4-3^3) = 24\,261\,120
     503
     504        ::
     505
     506            sage: S = groups.GLMatrix(4, GF(3))
     507            sage: S.order()
     508            24261120
     509            sage: s = S.an_element(); s
     510            [2 0 0 0]
     511            [0 1 0 0]
     512            [0 0 1 0]
     513            [0 0 0 1]
     514            sage: s.matrix().is_invertible()
     515            True
     516
     517        A finite field may given simply by its order.  A
     518        default generator will be provided for the field.
     519        Or you can provide a generator of your own.  Or,
     520        you can create the field yourself and provide it.  ::
     521
     522            sage: G = groups.GLMatrix(2, 5^3)
     523            sage: G
     524            General Linear Group of degree 2 over Finite Field in a of size 5^3
     525            sage: H = groups.GLMatrix(2, 5^3, name='b')
     526            sage: H
     527            General Linear Group of degree 2 over Finite Field in b of size 5^3
     528            sage: F.<c> = FiniteField(5^3)
     529            sage: K = groups.GLMatrix(2, F)
     530            sage: K
     531            General Linear Group of degree 2 over Finite Field in c of size 5^3
     532            sage: K.base_ring() is F
     533            True
     534
     535        Two types of rings, that are not fields, are supported.
     536        One produces an infinite group.  ::
     537
     538            sage: G = groups.GLMatrix(5, Integers(10))
     539            sage: G.order()
     540            2266004566425600000000000
     541            sage: H = groups.GLMatrix(5, ZZ)
     542            sage: H.order()
     543            +Infinity
     544               
     545        For further documentation, see
     546        :meth:`~sage.groups.matrix_gps.general_linear.GL`.
     547        """
     548        import sage.groups.matrix_gps.general_linear
     549        # R is a finite field, ZZ, Integers(m) 50.2-1 in GAP
     550        return sage.groups.matrix_gps.general_linear.GL(n, R, name)
     551       
     552    def SLMatrix(self, n, R, name='a'):
     553        r"""
     554        The special linear group of matrices with determinant 1,
     555        as a matrix group.
     556
     557        INPUT:
     558       
     559        - ``n`` - a positive integer specifying the size
     560          of the matrices.
     561        - ``R`` - the ring used for entries of the matrices.
     562          Supported rings are the integers (``ZZ``),
     563          integers mod m (``Integers(m)``) and finite fields
     564          (``GF(p^k, 'a')``).  If an integer is given for this
     565          parameter, it will be interpreted as the order of a
     566          finite field (so hence must be a power of a prime)
     567          and for a field with a degree greater than 1 a default
     568          generator will be provided.
     569
     570        OUTPUT:
     571
     572        The group of `n\times n` matrices with entries from the
     573        ring ``R`` and with determinant 1.
     574
     575        EXAMPLES:
     576
     577        The order of `SL(4, 3)` can be shown to be
     578
     579        .. MATH::
     580
     581            (3^4-3^0)(3^4-3^1)(3^4-3^2)(3^4-3^3)/(3-1) = 12\,130\,560
     582           
     583        ::
     584
     585            sage: S = groups.SLMatrix(4, GF(3))
     586            sage: S.order()
     587            12130560
     588            sage: s = S.an_element(); s
     589            [0 0 0 1]
     590            [2 0 0 0]
     591            [0 2 0 0]
     592            [0 0 2 0]
     593            sage: s.matrix().determinant()
     594            1
     595
     596        Over a field, this group is a normal subgroup of the
     597        general linear group, since it is the kernel of a
     598        natural homomorphism given by the determinant.
     599
     600        We do not have a check for normality for matrix groups,
     601        but we can convert our groups to native objects in GAP
     602        and then use a Pythonic interface to the commands available
     603        in GAP.  ::
     604
     605            sage: G = groups.GLMatrix(4, 3^2)
     606            sage: S = groups.SLMatrix(4, 3^2)
     607            sage: G.order()/S.order()
     608            8
     609
     610            sage: Ggap = G._gap_()
     611            sage: Sgap = S._gap_()
     612            sage: Sgap.IsNormal(Ggap)
     613            true
     614
     615        A finite field may given simply by its order.  A
     616        default generator will be provided for the field.
     617        Or you can provide a generator of your own.  Or,
     618        you can create the field yourself and provide it.  ::
     619
     620            sage: S = groups.SLMatrix(2, 5^3)
     621            sage: S
     622            Special Linear Group of degree 2 over Finite Field in a of size 5^3
     623            sage: T = groups.SLMatrix(2, 5^3, name='b')
     624            sage: T
     625            Special Linear Group of degree 2 over Finite Field in b of size 5^3
     626            sage: F.<c> = FiniteField(5^3)
     627            sage: U = groups.SLMatrix(2, F)
     628            sage: U
     629            Special Linear Group of degree 2 over Finite Field in c of size 5^3
     630            sage: U.base_ring() is F
     631            True
     632
     633        Two types of rings, that are not fields, are supported.
     634        One produces an infinite group.  ::
     635
     636            sage: S = groups.SLMatrix(5, Integers(10))
     637            sage: S.order()
     638            566501141606400000000000
     639            sage: S = groups.SLMatrix(5, ZZ)
     640            sage: S.order()
     641            +Infinity
     642
     643        For further documentation, see
     644        :meth:`~sage.groups.matrix_gps.special_linear.SL`.
     645        """
     646        import sage.groups.matrix_gps.special_linear
     647        # R is a finite field, ZZ, Integers(m) 50.2-1 in GAP
     648        return sage.groups.matrix_gps.special_linear.SL(n, R, name)
     649
     650    def PGLPermutation(self, n, q, name='a'):
     651        r"""
     652        The projective general linear group as a permutation group.
     653
     654        INPUT:
     655
     656        - ``n`` - size of the square matrices in the group
     657        - ``q`` - order of the finite field used for the
     658          entries of the matrices.  Must be a prime power order.
     659        - ``name`` - default: ``'a'`` - a string used to form
     660          the names of the elements of the finite field.
     661
     662        OUTPUT:
     663
     664        The projective general linear group has elements that
     665        are `n\times n` matrices.  Here we limit the entries of
     666        the matrices to elements of a finite field of order `q`.
     667        For finite fields of degree 2 or more ``name`` is a string
     668        that is used to construct the names of the elements of the
     669        field.  More specifically, the group is the quotient of
     670        the general linear group by its center.
     671
     672        The representation returned here is a permutation group
     673        rather than a matrix group. If `F` is the field field,
     674        then the items being permuted are the dimension one
     675        subspaces of the vector space `F^n`, which are also
     676        known as "lines".
     677
     678        EXAMPLES:
     679
     680        The general linear group of `2\times 2` matrices over a
     681        finite field of order 3 is composed of 48 invertible matrices.
     682        The center has order 2, hence the projective group has order 24.
     683        The vector space of dimension 2 over the field of order 3 has 8
     684        nonzero vectors, which partition into 4 dimension one subspaces
     685        (the lines).  Hence the permutation representation is a subgroup
     686        of the symmetric group on 4 symbols. ::
     687
     688            sage: G = groups.PGLPermutation(2,3)
     689            sage: G.order()
     690            24
     691            sage: F = G.base_ring()
     692            sage: V = F^2
     693            sage: len(list(V.subspaces(1)))
     694            4
     695            sage: G.degree()
     696            4
     697
     698        Using a finite field of degree greater than one, the symbol
     699        used to describe the elements of the field may be specified.
     700        The irreducible polynomial used to structure the field is
     701        provided automatically by the GAP library and may not be changed. ::
     702
     703            sage: K = groups.PGLPermutation(2, 81, name='c')
     704            sage: K.order()
     705            531360
     706            sage: F = K.base_ring(); F
     707            Finite Field in c of size 3^4
     708            sage: F.polynomial()
     709            c^4 + 2*c^3 + 2
     710       
     711        For further documentation, see
     712        :meth:`~sage.groups.perm_gps.permgroup_named.PGL`.
     713        """
     714        import sage.groups.perm_gps.permgroup_named
     715        return sage.groups.perm_gps.permgroup_named.PGL(n, q, name)
     716
     717
     718
     719
     720
     721
     722       
     723# This is the object available in the global namespace       
     724groups = GroupGenerators()
     725
     726
     727   
     728 No newline at end of file