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

File trac_13115-groups-object-v3.patch, 39.4 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 2332a0e5fd40c7eceedc0a90a5fde808d95b1ecd
    # 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    A selection of the twenty-six sporadic simple groups can be located
     28    similarly with tab-completion on the ``groups.sporadic`` object, which
     29    is an instance of the :class:`SporadicGroupGenerators` class.  Examples
     30    avaliable are listed here.
     31
     32    - First Generation (Mathieu groups, five subgroups of `M_{24}`)
     33        - :meth:`~sage.groups.group_generators.SporadicGroupGenerators.M11`
     34        - :meth:`~sage.groups.group_generators.SporadicGroupGenerators.M12`
     35        - :meth:`~sage.groups.group_generators.SporadicGroupGenerators.M22`
     36        - :meth:`~sage.groups.group_generators.SporadicGroupGenerators.M23`
     37        - :meth:`~sage.groups.group_generators.SporadicGroupGenerators.M24`
     38    - Second Generation (seven subquotients of the automorphism group of the Leech Lattice)
     39        - :meth:`~sage.groups.group_generators.SporadicGroupGenerators.Co3`
     40        - :meth:`~sage.groups.group_generators.SporadicGroupGenerators.HS`
     41        - :meth:`~sage.groups.group_generators.SporadicGroupGenerators.J2`
     42    - Third Generation (eight additional sections of the Monster group)
     43    - The Pariahs (six groups unrelated to the Monster group)
     44   
     45
     46       
     47"""
     48# Implementation Notes:
     49#   - organization of the sporadic groups taken on 2012/07/26 from
     50#      (a) article at: http://en.wikipedia.org/wiki/Sporadic_group
     51#      (b) organization at "the Atlas", http://brauer.maths.qmul.ac.uk/Atlas/v3/spor/
     52
     53##################
     54#  Sporadic Groups
     55##################
     56
     57class SporadicGroupGenerators(object):
     58    r"""
     59    An object of this class gives convenient references
     60    to examples of the twenty-six sporadic simple groups.
     61
     62    The global ``groups`` object can be used with tab-completion
     63    to easily and quickly locate examples of groups implemented in Sage,
     64    and then the ``groups.sporadic`` object will provide examples of
     65    the sporadic simple groups.
     66
     67    .. warning::
     68
     69        This list is under development, so is not complete.
     70    """
     71
     72    def __repr__(self):
     73        r"""
     74        A message about the purpose of this object.
     75
     76        TESTS::
     77
     78            sage: groups.sporadic   # indirect doctest
     79            Object collecting examples of sporadic simple groups, try "groups.sporadic.<tab>"
     80        """
     81        return 'Object collecting examples of sporadic simple groups, try "groups.sporadic.<tab>"'
     82
     83    ##################
     84    # First Generation
     85    ##################
     86
     87    def M11(self):
     88        r"""
     89        The Mathieu group of degree 11.
     90
     91        OUTPUT:
     92
     93        The Mathieu group on 11 symbols, `M_{11}`, which is simple
     94        and sharply 4-transitive.
     95
     96        EXAMPLES::
     97
     98            sage: M = groups.sporadic.M11(); M
     99            Mathieu group of degree 11 and order 7920 as a permutation group
     100            sage: M.is_simple()
     101            True
     102        """
     103        import sage.groups.perm_gps.permgroup_named
     104        return sage.groups.perm_gps.permgroup_named.MathieuGroup(11)
     105
     106    def M12(self):
     107        r"""
     108        The Mathieu group of degree 12.
     109
     110        OUTPUT:
     111
     112        The Mathieu group on 12 symbols, `M_{12}`, which is simple
     113        and sharply 5-transitive.
     114
     115        EXAMPLES::
     116
     117            sage: M = groups.sporadic.M12(); M
     118            Mathieu group of degree 12 and order 95040 as a permutation group
     119            sage: M.is_simple()
     120            True
     121        """
     122        import sage.groups.perm_gps.permgroup_named
     123        return sage.groups.perm_gps.permgroup_named.MathieuGroup(12)
     124
     125    def M22(self):
     126        r"""
     127        The Mathieu group of degree 22.
     128
     129        OUTPUT:
     130
     131        The Mathieu group on 22 symbols, `M_{22}`, which is simple
     132        and 3-transitive.
     133
     134        EXAMPLES::
     135
     136            sage: M = groups.sporadic.M22(); M
     137            Mathieu group of degree 22 and order 443520 as a permutation group
     138            sage: M.is_simple()
     139            True
     140        """
     141        import sage.groups.perm_gps.permgroup_named
     142        return sage.groups.perm_gps.permgroup_named.MathieuGroup(22)
     143
     144    def M23(self):
     145        r"""
     146        The Mathieu group of degree 23.
     147
     148        OUTPUT:
     149
     150        The Mathieu group on 23 symbols, `M_{23}`, which is simple
     151        and 4-transitive.
     152
     153        EXAMPLES::
     154
     155            sage: M = groups.sporadic.M23(); M
     156            Mathieu group of degree 23 and order 10200960 as a permutation group
     157            sage: M.is_simple()
     158            True
     159        """
     160        import sage.groups.perm_gps.permgroup_named
     161        return sage.groups.perm_gps.permgroup_named.MathieuGroup(23)
     162
     163    def M24(self):
     164        r"""
     165        The Mathieu group of degree 24.
     166
     167        OUTPUT:
     168
     169        The Mathieu group on 24 symbols, `M_{24}`, which is simple
     170        and 5-transitive.
     171
     172        EXAMPLES::
     173
     174            sage: M = groups.sporadic.M24(); M
     175            Mathieu group of degree 24 and order 244823040 as a permutation group
     176            sage: M.is_simple()
     177            True
     178        """
     179        import sage.groups.perm_gps.permgroup_named
     180        return sage.groups.perm_gps.permgroup_named.MathieuGroup(24)
     181
     182    ###################
     183    # Second Generation
     184    ###################
     185
     186    def HS(self):
     187        r"""
     188        The Higman-Sims group.
     189
     190        OUTPUT:
     191
     192        The Higman-Sims group, `HS`, a sporadic simple group.
     193
     194        EXAMPLES::
     195
     196            sage: HS = groups.sporadic.HS()
     197            sage: HS.order()
     198            44352000
     199            sage: HS.is_simple()
     200            True
     201        """
     202        import sage.graphs.graph_generators
     203        graph = sage.graphs.graph_generators.GraphGenerators().HigmanSimsGraph()
     204        aut = graph.automorphism_group()
     205        comp = aut.composition_series()
     206        return comp[1]
     207
     208    def J2(self, representation='minperm'):
     209        r"""
     210        The second Janko group, also known as the Hall-Janko group.
     211
     212        INPUT:
     213
     214        - ``representation`` - default: ``'minperm'`` - choice of
     215          representation for the group returned.  Options are:
     216
     217          - ``'minperm'`` - a permutation group with generators of
     218            the least degree available in the description at the
     219            "ATLAS of Finite Group Representations - Version 3."
     220
     221        OUTPUT:
     222
     223        The second Janko group, `J_2`, a sporadic simple group.  Also
     224        known as the Hall-Janko group, `HJ`.
     225
     226        EXAMPLES::
     227
     228            sage: J2 = groups.sporadic.J2()
     229            sage: J2.order()
     230            604800
     231            sage: J2.is_simple()
     232            True
     233        """
     234        import sage.groups.perm_gps.permgroup
     235        return sage.groups.perm_gps.permgroup.PermutationGroup(self.atlas_gens['J2'])
     236
     237    def Co3(self, representation='minperm'):
     238        r"""
     239        The third Conway group, also known as the Hall-Janko group.
     240
     241        INPUT:
     242
     243        - ``representation`` - default: ``'minperm'`` - choice of
     244          representation for the group returned.  Options are:
     245
     246          - ``'minperm'`` - a permutation group with generators of
     247            the least degree available in the description at the
     248            "ATLAS of Finite Group Representations - Version 3."
     249
     250        OUTPUT:
     251
     252        The third Conway group, `Co_3`, a sporadic simple group.
     253
     254        EXAMPLES::
     255
     256            sage: Co3 = groups.sporadic.Co3()
     257            sage: Co3.order()
     258            495766656000
     259            sage: Co3.is_simple()
     260            True
     261        """
     262        import sage.groups.perm_gps.permgroup
     263        return sage.groups.perm_gps.permgroup.PermutationGroup(self.atlas_gens['Co3'])
     264
     265    # generators from "ATLAS of Finite Group Representations - Version 3"
     266    # http://brauer.maths.qmul.ac.uk/Atlas/v3/
     267    # version 3.004, accessed 2012/07/26
     268    atlas_gens = {
     269    'J2':[
     270    r"""(1,84)(2,20)(3,48)(4,56)(5,82)(6,67)(7,55)(8,41)(9,35)(10,40)(11,78)(12,
     271    100)(13,49)(14,37)(15,94)(16,76)(17,19)(18,44)(21,34)(22,85)(23,92)(24,
     272    57)(25,75)(26,28)(27,64)(29,90)(30,97)(31,38)(32,68)(33,69)(36,53)(39,61)
     273    (42,73)(43,91)(45,86)(46,81)(47,89)(50,93)(51,96)(52,72)(54,74)(58,99)
     274    (59,95)(60,63)(62,83)(65,70)(66,88)(71,87)(77,98)(79,80)""",
     275    r"""(1,80,22)(2,9,11)(3,53,87)(4,23,78)(5,51,18)(6,37,24)(8,27,60)(10,62,47)
     276    (12,65,31)(13,64,19)(14,61,52)(15,98,25)(16,73,32)(17,39,33)(20,97,58)
     277    (21,96,67)(26,93,99)(28,57,35)(29,71,55)(30,69,45)(34,86,82)(38,59,94)
     278    (40,43,91)(42,68,44)(46,85,89)(48,76,90)(49,92,77)(50,66,88)(54,95,56)
     279    (63,74,72)(70,81,75)(79,100,83)"""],
     280    'Co3':[
     281    r"""(1,245,185)(2,42,87)(3,112,266)(4,15,22)(5,131,30)(6,7,188)(8,75,111)(9,
     282    132,82)(12,187,124)(13,186,136)(14,265,213)(16,159,99)(17,256,130)(18,43,
     283    167)(19,101,31)(20,123,269)(21,134,74)(23,32,60)(24,209,67)(25,238,162)
     284    (26,35,154)(27,45,221)(28,235,270)(29,126,129)(33,66,210)(34,80,114)(36,
     285    251,229)(37,117,161)(38,206,63)(39,71,196)(40,118,180)(41,93,170)(44,271,
     286    164)(46,261,108)(47,182,49)(48,155,248)(50,230,153)(51,172,103)(52,236,
     287    165)(53,109,64)(54,191,100)(55,76,203)(56,156,260)(57,73,149)(58,116,145)
     288    (59,147,273)(61,127,189)(62,231,197)(65,122,169)(69,86,95)(70,255,192)
     289    (72,139,78)(77,252,151)(79,262,184)(81,214,242)(83,181,223)(84,174,200)
     290    (88,250,276)(89,257,244)(90,243,91)(92,158,107)(94,148,215)(96,105,125)
     291    (97,249,202)(98,263,193)(102,115,175)(106,219,150)(110,204,152)(113,225,
     292    216)(119,237,166)(120,241,234)(121,224,195)(128,190,268)(133,143,228)
     293    (135,168,201)(137,227,247)(138,217,240)(140,258,232)(141,220,205)(142,
     294    178,207)(144,146,254)(157,274,179)(160,253,176)(163,272,226)(171,233,194)
     295    (173,246,212)(177,198,211)(183,267,222)(199,208,259)(218,264,239)""",
     296    r"""(1,204,123,82)(2,203,14,53)(3,33,40,118)(4,236,168,138)(6,172,188,157)
     297    (7,77,25,242)(8,76,85,264)(9,47,22,190)(10,146,50,26)(11,133,220,254)(12,
     298    224,179,58)(13,229,169,23)(15,84,148,78)(17,223)(18,228)(19,130,104,167)
     299    (20,131,90,60)(21,252,185,205)(24,263,214,81)(27,32,209,61)(28,196,67,
     300    137)(29,199,87,48)(30,65,218,112)(31,246,98,213)(34,99,165,265)(35,241)
     301    (36,198,161,89)(37,269)(38,251,42,271)(39,75,260,193)(41,176,192,57)(43,
     302    183,91,171)(44,116,173,102)(45,197,119,73)(46,238,124,162)(49,178,83,274)
     303    (51,174,244,100)(52,129)(54,153,217,151)(55,272,136,237)(56,257,154,121)
     304    (62,175,219,215)(63,106,66,259)(64,159,210,194)(68,258,221,234)(69,261,
     305    134,155)(70,164,211,266)(71,262)(72,189,114,222)(74,177,256,135)(79,226,
     306    267,202)(80,96,120,239)(86,132,216,160)(88,117,231,109)(92,201,111,276)
     307    (93,101,115,166)(94,253)(97,142,270,110)(105,243,212,225)(107,141,230,
     308    249)(113,139)(122,170,126,207)(125,163,184,158)(127,145,206,149)(140,273)
     309    (143,248,247,195)(144,180)(147,250,182,187)(152,232,208,191)(186,235,233,
     310    275)"""]
     311    }
     312       
     313       
     314##################
     315#  All Groups
     316##################
     317
     318class GroupGenerators(object):
     319    r"""
     320    An object of this class gives convenient references
     321    to examples of groups.
     322
     323    The global ``groups`` object can be used with tab-completion
     324    to easily and quickly locate examples of groups implemented in Sage.
     325
     326    .. warning::
     327
     328        This list is under development, so may not be exhaustive.
     329    """
     330
     331    # attribute to allow access to the sporadic simple group generator,
     332    # ie, this enables "groups.sporadic.<tab>"
     333    sporadic = SporadicGroupGenerators()
     334
     335    def __repr__(self):
     336        r"""
     337        A message about the purpose of this object.
     338
     339        TESTS::
     340       
     341            sage: groups   # indirect doctest
     342            Object collecting examples of groups, try "groups.<tab>"
     343        """
     344        return 'Object collecting examples of groups, try "groups.<tab>"'
     345       
     346    def KleinFourPermutation(self):
     347        r"""
     348        The non-cyclic group of order 4, isomorphic to `\ZZ_2\times\ZZ_2`.
     349
     350        OUTPUT:
     351
     352        The non-cyclic group of order 4, as a permutation group
     353        on 4 symbols.
     354
     355        EXAMPLES::
     356
     357            sage: K = groups.KleinFourPermutation()
     358            sage: K.list()
     359            [(), (3,4), (1,2), (1,2)(3,4)]
     360
     361        For further documentation, see
     362        :meth:`~sage.groups.perm_gps.permgroup_named.KleinFourGroup`.
     363        """
     364        import sage.groups.perm_gps.permgroup_named
     365        return sage.groups.perm_gps.permgroup_named.KleinFourGroup()
     366       
     367    def SymmetricPermutation(self, n):
     368        r"""
     369        The full symmetric group on `n` symbols, as a permutation group.
     370
     371        INPUT:
     372
     373        - ``n`` - a positive integer, or a list.  If ``n`` is
     374          an integer, then the symbol set is the integers
     375          `\{1,2,\dots,n\}`.  Otherwise the symbol set is
     376          the list given by `n`, provided the objects in
     377          the list are hashable (i.e. immutable).
     378
     379        OUTPUT:
     380
     381        The full group of order `n!` with all possible
     382        permutations of the `n` symbols.
     383
     384        EXAMPLES::
     385
     386            sage: G = groups.SymmetricPermutation(3)
     387            sage: G.list()
     388            [(), (2,3), (1,2), (1,2,3), (1,3,2), (1,3)]
     389            sage: H = groups.SymmetricPermutation(10)
     390            sage: H.order() == factorial(10)
     391            True
     392
     393        A symmetric group can be a good base for creating subgroups
     394        of interest.  ::
     395
     396            sage: S = groups.SymmetricPermutation(11)
     397            sage: a = S("(1, 2, 3, 4, 5)(7, 8, 9, 10,11)")
     398            sage: b = S("(1, 2, 3)(4, 5, 6, 7, 8)(9, 10, 11)")
     399            sage: H = S.subgroup([a, b])
     400            sage: S.order()/H.order()
     401            2
     402
     403        Alternate symbol sets are possible.  ::
     404
     405            sage: G = groups.SymmetricPermutation(['dog', 'cat', 'fish'])
     406            sage: G
     407            Symmetric group of order 3! as a permutation group
     408            sage: G.an_element()
     409            ('dog','cat','fish')
     410
     411        However, alternate symbols must be hashable (immutable,
     412        unchangeable).  For example, Python lists are not hashable. ::
     413
     414            sage: groups.SymmetricPermutation([[1,0], [0,1]])
     415            Traceback (most recent call last):
     416            ...
     417            TypeError: unhashable type: 'list'
     418
     419        For further documentation, see
     420        :meth:`~sage.groups.perm_gps.permgroup_named.SymmetricGroup`.
     421        """
     422        import sage.groups.perm_gps.permgroup_named
     423        return sage.groups.perm_gps.permgroup_named.SymmetricGroup(n)
     424
     425    def AlternatingPermutation(self, n):
     426        r"""
     427        The alternating group on `n` symbols, as a permutation group.
     428
     429        INPUT:
     430
     431        - ``n`` - a positive integer, or a list.  If ``n`` is
     432          an integer, then the symbol set is the integers
     433          `\{1,2,\dots,n\}`.  Otherwise the symbol set is
     434          the list given by `n`, provided the objects in
     435          the list are hashable (i.e. immutable).
     436
     437        OUTPUT:
     438
     439        The alternating group of order `n!/2` with all possible
     440        even permutations of the `n` symbols.  (An "even"
     441        permutation is one that can be written as a product
     442        of an even number of cycles of length two, which are also
     443        known as "transpositions".)
     444
     445        EXAMPLES::
     446
     447            sage: A = groups.AlternatingPermutation(3)
     448            sage: A.list()
     449            [(), (1,2,3), (1,3,2)]
     450            sage: H = groups.AlternatingPermutation(10)
     451            sage: H.order() == factorial(10)/2
     452            True
     453
     454        The :meth:`~sage.groups.perm_gps.permgroup_element.PermutationGroupElement.sign`
     455        method for permutation group elements is ``+1`` for
     456        an even permutation and ``-1`` for odd elements.  ::
     457
     458            sage: S = groups.SymmetricPermutation(5)
     459            sage: A = groups.AlternatingPermutation(5)
     460            sage: a = S("(1,3)(4,5)")
     461            sage: b = S("(2,3)(1,5)")
     462            sage: c = a*b
     463            sage: c.sign()
     464            1
     465            sage: c in A
     466            True
     467            sage: d = S("(1,2,3,4)")
     468            sage: d.sign()
     469            -1
     470            sage: d in A
     471            False
     472
     473        A symmetric group can be a good base for creating subgroups
     474        of interest.  ::
     475
     476            sage: G = groups.SymmetricPermutation(11)
     477            sage: a = G("(1, 2, 3, 4, 5)(7, 8, 9, 10,11)")
     478            sage: b = G("(1, 2, 3)(4, 5, 6, 7, 8)(9, 10, 11)")
     479            sage: H = G.subgroup([a, b])
     480            sage: H.order()
     481            19958400
     482
     483        Alternate symbol sets are possible.  The other permutation group
     484        which allows for the specification of an alternate symbol set is the :meth:`~sage.groups.group_generators.GroupGenerators.SymmetricPermutation`
     485        member of the ``groups`` object, so also look there for more
     486        documentation. ::
     487
     488            sage: A = groups.AlternatingPermutation(['dog', 'cat', 'fish'])
     489            sage: A
     490            Alternating group of order 3!/2 as a permutation group
     491            sage: A.an_element()
     492            ('dog','cat','fish')
     493
     494        For further documentation, see
     495        :meth:`~sage.groups.perm_gps.permgroup_named.AlternatingGroup`.
     496        """
     497        import sage.groups.perm_gps.permgroup_named
     498        return sage.groups.perm_gps.permgroup_named.AlternatingGroup(n)
     499       
     500    def CyclicPermutation(self, n):
     501        r"""
     502        A cyclic group as a permutation group.
     503
     504        INPUT:
     505
     506        - ``n`` - a positive integer, the size of the group.
     507
     508        OUTPUT:
     509
     510        A cyclic group of order `n` as a permutation group of size `n`.
     511
     512        EXAMPLES::
     513
     514            sage: G = groups.CyclicPermutation(4)
     515            sage: G.list()
     516            [(), (1,2,3,4), (1,3)(2,4), (1,4,3,2)]
     517
     518        For further documentation, see
     519        :meth:`~sage.groups.perm_gps.permgroup_named.CyclicPermutationGroup`.
     520        """
     521        import sage.groups.perm_gps.permgroup_named
     522        return sage.groups.perm_gps.permgroup_named.CyclicPermutationGroup(n)
     523
     524    def DihedralPermutation(self, n):
     525        r"""
     526        The dicyclic group of order `2n`, as a permutation group.
     527
     528        INPUT:
     529
     530        - ``n`` - a positive integer.
     531
     532        OUTPUT:
     533
     534        The dicyclic group of order `2n`, which is a
     535        non-abelian group containing the symmetries of a
     536        regular `n`-gon, represented as a permutation group.
     537
     538        EXAMPLES:
     539
     540        For an even `n` the center of the dihedral group
     541        will contain the symmetry that is a half-turn of
     542        the `n`-gon.  ::
     543
     544            sage: G = groups.DihedralPermutation(8)
     545            sage: G.order()
     546            16
     547            sage: G.is_abelian()
     548            False
     549            sage: G.center().list()
     550            [(), (1,5)(2,6)(3,7)(4,8)]
     551
     552        For further documentation, see
     553        :meth:`~sage.groups.perm_gps.permgroup_named.DihedralGroup`.
     554        """
     555        import sage.groups.perm_gps.permgroup_named
     556        return sage.groups.perm_gps.permgroup_named.DihedralGroup(n)
     557       
     558    def DiCyclicPermutation(self, n):
     559        r"""
     560        The dicyclic group of order `4n`, as a permutation group.
     561
     562        INPUT:
     563
     564        - ``n`` - a positive integer.
     565
     566        OUTPUT:
     567
     568        The dicyclic group of order `4n`, a non-abelian group
     569        represented as a permutation group.
     570
     571        EXAMPLES:
     572
     573        One notable property of the dicyclic group is that it has a single
     574        element of order 2.  There are 3 non-abelian groups of order 12;
     575        the alternating group on 4 symbols, the dihedral group that is
     576        symmetries of a regular hexagon, and the dicyclic group of
     577        order 12. ::
     578
     579            sage: G = groups.DiCyclicPermutation(3)
     580            sage: G.order()
     581            12
     582            sage: G.is_abelian()
     583            False
     584            sage: [a for a in G if a.order() == 2]
     585            [(1,2)(3,4)]
     586           
     587        For further documentation, see
     588        :meth:`~sage.groups.perm_gps.permgroup_named.DiCyclicGroup`.
     589        """
     590        import sage.groups.perm_gps.permgroup_named
     591        return sage.groups.perm_gps.permgroup_named.DiCyclicGroup(n)
     592
     593    def MathieuPermutation(self, degree):
     594        r"""
     595        Returns a Mathieu group as a permutation group.
     596
     597        INPUT:
     598
     599        - ``degree`` - the number of symbols in the
     600          ambient symmetric group.  Allowable values are
     601          9, 10, 11, 12, 21, 22, 23, and 24.
     602
     603        OUTPUT:
     604
     605        A Mathieu group, as a permutation of the integers
     606        ``1`` through ``degree``.
     607
     608        EXAMPLES:
     609
     610        `M_{22}` is simple and `3`-transitive.  ::
     611
     612            sage: G = groups.MathieuPermutation(22)
     613            sage: G.is_simple()
     614            True
     615            sage: S1 = G.stabilizer(1)
     616            sage: S1.orbits()
     617            [[1], [2, 7, 15, 3, 17, 13, 10, 4, 22, 19, 14, 11, 20, 21, 8, 6, 9, 12, 18, 16, 5]]
     618            sage: S2 = S1.stabilizer(2)
     619            sage: S2.orbits()
     620            [[1], [2], [3, 14, 22, 17, 4, 10, 13, 11, 9, 6, 5, 16, 18, 12, 8, 7, 15, 21, 20, 19]]
     621            sage: S3 = S2.stabilizer(3)
     622            sage: S3.orbits()
     623            [[1], [2], [3], [4, 12, 22, 14, 11, 5, 21, 9, 19, 13, 8, 15, 18, 17, 6, 16], [7, 10, 20]]
     624           
     625        For further documentation, see
     626        :meth:`~sage.groups.perm_gps.permgroup_named.MathieuGroup`.
     627        """
     628        import sage.groups.perm_gps.permgroup_named
     629        return sage.groups.perm_gps.permgroup_named.MathieuGroup(degree)
     630
     631    def SuzukiPermutation(self, q):
     632        r"""
     633        A Suzuki group over the field with `q` elements, as a permutation group.
     634
     635        INPUT:
     636
     637        - ``q`` - in a matrix group representation, the elements
     638          of the matrices are from a finite field of size `q`.  This
     639          must be an odd power of 2.
     640
     641        OUTPUT:
     642
     643        An instance of a Suzuki group, an infinite family of groups of
     644        Lie type. For `q > 2` each is a simple group.  This family of
     645        groups *does not* include the sporadic simple group known as
     646        the Suzuki group.
     647
     648        EXAMPLES:
     649
     650        The Suzuki groups have order `q^2(q^2+1)(q-1)` and are
     651        characterized as the non-cyclic, finite simple groups with
     652        orders not divisible by 3.  The number of conjugacy classes
     653        is given by `q+3`. ::
     654
     655            sage: q = 2^5
     656            sage: H = groups.SuzukiPermutation(2^5)
     657            sage: H.degree()
     658            1025
     659            sage: H.is_cyclic()
     660            False
     661            sage: H.is_simple()
     662            True
     663            sage: H.order()
     664            32537600
     665            sage: H.order() == q^2*(q^2+1)*(q-1)
     666            True
     667            sage: len(H.conjugacy_classes_representatives()) == q+3
     668            True
     669
     670        The smallest case is not a simple group, though the
     671        remainder are. ::
     672
     673            sage: G = groups.SuzukiPermutation(2^1)
     674            sage: G.order()
     675            20
     676            sage: G.is_simple()
     677            False
     678       
     679        For further documentation, see
     680        :meth:`~sage.groups.perm_gps.permgroup_named.SuzukiGroup`.
     681        """
     682        import sage.groups.perm_gps.permgroup_named
     683        return sage.groups.perm_gps.permgroup_named.SuzukiGroup(q)
     684       
     685    def QuaternionMatrixGF3(self):
     686        r"""
     687        The quaternion group as a set of `2\times 2` matrices over `GF(3)`.
     688
     689        OUTPUT:
     690
     691        A matrix group consisting of `2\times 2` matrices with
     692        elements from the finite field of order 3.  The group is
     693        the quaternion group, the nonabelian group of order 8 that
     694        is not isomorphic to the group of symmetries of a square
     695        (the dihedral group `D_4`).
     696
     697        EXAMPLES:
     698
     699        The generators are the matrix representations of the
     700        elements commonly called `I` and `J`, while `K`
     701        is the product of `I` and `J`. ::
     702           
     703            sage: Q = groups.QuaternionMatrixGF3()
     704            sage: Q.order()
     705            8
     706            sage: aye = Q.gens()[0]; aye
     707            [1 1]
     708            [1 2]
     709            sage: jay = Q.gens()[1]; jay
     710            [2 1]
     711            [1 1]
     712            sage: kay = aye*jay; kay
     713            [0 2]
     714            [1 0]
     715
     716        TESTS::
     717       
     718            sage: Q = groups.QuaternionMatrixGF3()
     719            sage: QP = Q.as_permutation_group()
     720            sage: QP.is_isomorphic(groups.QuaternionPermutation())
     721            True
     722            sage: H = DihedralGroup(4)
     723            sage: H.order()
     724            8
     725            sage: QP.is_abelian(), H.is_abelian()
     726            (False, False)
     727            sage: QP.is_isomorphic(H)
     728            False
     729        """
     730        from sage.rings.finite_rings.constructor import FiniteField
     731        from sage.matrix.matrix_space import MatrixSpace
     732        from sage.groups.matrix_gps.matrix_group import MatrixGroup
     733        MS = MatrixSpace(FiniteField(3), 2)
     734        aye = MS([1,1,1,2])
     735        jay = MS([2,1,1,1])
     736        return MatrixGroup([aye, jay])
     737
     738    def QuaternionPermutation(self):
     739        r"""
     740        The quaternion group as a set of permutations in `S_8`.
     741
     742        OUTPUT:
     743
     744        A group of permutations on the symbols ``1`` to ``8`` that
     745        is the nonabelian group of order 8 that is not isomorphic
     746        to the group of symmetries of a square (the dihedral
     747        group `D_4`).
     748
     749        EXAMPLES::
     750
     751            sage: G = groups.QuaternionPermutation()
     752            sage: G.degree()
     753            8
     754            sage: G.order()
     755            8
     756            sage: sorted([x.order() for x in G])
     757            [1, 2, 4, 4, 4, 4, 4, 4]
     758        """
     759        import sage.groups.perm_gps.permgroup_named
     760        return sage.groups.perm_gps.permgroup_named.QuaternionGroup()
     761
     762#~~~~~~~~~~~~~~
     763# Matrix Groups
     764#~~~~~~~~~~~~~~
     765
     766    def GLMatrix(self, n, R, name='a'):
     767        r"""
     768        The general linear group of invertible matrices,
     769        as a matrix group.
     770
     771        INPUT:
     772
     773        - ``n`` - a positive integer specifying the size
     774          of the matrices.
     775        - ``R`` - the ring used for entries of the matrices.
     776          Supported rings are the integers (``ZZ``),
     777          integers mod m (``Integers(m)``) and finite fields
     778          (``GF(p^k, 'a')``).  If an integer is given for this
     779          parameter, it will be interpreted as the order of a
     780          finite field (so hence must be a power of a prime)
     781          and for a field with a degree greater than 1 a default
     782          generator will be provided.
     783
     784        OUTPUT:
     785
     786        The group of `n\times n` matrices with entries from the
     787        ring ``R``.
     788
     789        EXAMPLES:
     790
     791        The order of `GL(4, 3)` can be shown to be
     792
     793        .. MATH::
     794
     795            (3^4-3^0)(3^4-3^1)(3^4-3^2)(3^4-3^3) = 24\,261\,120
     796
     797        ::
     798
     799            sage: S = groups.GLMatrix(4, GF(3))
     800            sage: S.order()
     801            24261120
     802            sage: s = S.an_element(); s
     803            [2 0 0 0]
     804            [0 1 0 0]
     805            [0 0 1 0]
     806            [0 0 0 1]
     807            sage: s.matrix().is_invertible()
     808            True
     809
     810        A finite field may given simply by its order.  A
     811        default generator will be provided for the field.
     812        Or you can provide a generator of your own.  Or,
     813        you can create the field yourself and provide it.  ::
     814
     815            sage: G = groups.GLMatrix(2, 5^3)
     816            sage: G
     817            General Linear Group of degree 2 over Finite Field in a of size 5^3
     818            sage: H = groups.GLMatrix(2, 5^3, name='b')
     819            sage: H
     820            General Linear Group of degree 2 over Finite Field in b of size 5^3
     821            sage: F.<c> = FiniteField(5^3)
     822            sage: K = groups.GLMatrix(2, F)
     823            sage: K
     824            General Linear Group of degree 2 over Finite Field in c of size 5^3
     825            sage: K.base_ring() is F
     826            True
     827
     828        Two types of rings, that are not fields, are supported.
     829        One produces an infinite group.  ::
     830
     831            sage: G = groups.GLMatrix(5, Integers(10))
     832            sage: G.order()
     833            2266004566425600000000000
     834            sage: H = groups.GLMatrix(5, ZZ)
     835            sage: H.order()
     836            +Infinity
     837               
     838        For further documentation, see
     839        :meth:`~sage.groups.matrix_gps.general_linear.GL`.
     840        """
     841        import sage.groups.matrix_gps.general_linear
     842        # R is a finite field, ZZ, Integers(m) 50.2-1 in GAP
     843        return sage.groups.matrix_gps.general_linear.GL(n, R, name)
     844       
     845    def SLMatrix(self, n, R, name='a'):
     846        r"""
     847        The special linear group of matrices with determinant 1,
     848        as a matrix group.
     849
     850        INPUT:
     851       
     852        - ``n`` - a positive integer specifying the size
     853          of the matrices.
     854        - ``R`` - the ring used for entries of the matrices.
     855          Supported rings are the integers (``ZZ``),
     856          integers mod m (``Integers(m)``) and finite fields
     857          (``GF(p^k, 'a')``).  If an integer is given for this
     858          parameter, it will be interpreted as the order of a
     859          finite field (so hence must be a power of a prime)
     860          and for a field with a degree greater than 1 a default
     861          generator will be provided.
     862
     863        OUTPUT:
     864
     865        The group of `n\times n` matrices with entries from the
     866        ring ``R`` and with determinant 1.
     867
     868        EXAMPLES:
     869
     870        The order of `SL(4, 3)` can be shown to be
     871
     872        .. MATH::
     873
     874            (3^4-3^0)(3^4-3^1)(3^4-3^2)(3^4-3^3)/(3-1) = 12\,130\,560
     875           
     876        ::
     877
     878            sage: S = groups.SLMatrix(4, GF(3))
     879            sage: S.order()
     880            12130560
     881            sage: s = S.an_element(); s
     882            [0 0 0 1]
     883            [2 0 0 0]
     884            [0 2 0 0]
     885            [0 0 2 0]
     886            sage: s.matrix().determinant()
     887            1
     888
     889        Over a field, this group is a normal subgroup of the
     890        general linear group, since it is the kernel of a
     891        natural homomorphism given by the determinant.
     892
     893        We do not have a check for normality for matrix groups,
     894        but we can convert our groups to native objects in GAP
     895        and then use a Pythonic interface to the commands available
     896        in GAP.  ::
     897
     898            sage: G = groups.GLMatrix(4, 3^2)
     899            sage: S = groups.SLMatrix(4, 3^2)
     900            sage: G.order()/S.order()
     901            8
     902
     903            sage: Ggap = G._gap_()
     904            sage: Sgap = S._gap_()
     905            sage: Sgap.IsNormal(Ggap)
     906            true
     907
     908        A finite field may given simply by its order.  A
     909        default generator will be provided for the field.
     910        Or you can provide a generator of your own.  Or,
     911        you can create the field yourself and provide it.  ::
     912
     913            sage: S = groups.SLMatrix(2, 5^3)
     914            sage: S
     915            Special Linear Group of degree 2 over Finite Field in a of size 5^3
     916            sage: T = groups.SLMatrix(2, 5^3, name='b')
     917            sage: T
     918            Special Linear Group of degree 2 over Finite Field in b of size 5^3
     919            sage: F.<c> = FiniteField(5^3)
     920            sage: U = groups.SLMatrix(2, F)
     921            sage: U
     922            Special Linear Group of degree 2 over Finite Field in c of size 5^3
     923            sage: U.base_ring() is F
     924            True
     925
     926        Two types of rings, that are not fields, are supported.
     927        One produces an infinite group.  ::
     928
     929            sage: S = groups.SLMatrix(5, Integers(10))
     930            sage: S.order()
     931            566501141606400000000000
     932            sage: S = groups.SLMatrix(5, ZZ)
     933            sage: S.order()
     934            +Infinity
     935
     936        For further documentation, see
     937        :meth:`~sage.groups.matrix_gps.special_linear.SL`.
     938        """
     939        import sage.groups.matrix_gps.special_linear
     940        # R is a finite field, ZZ, Integers(m) 50.2-1 in GAP
     941        return sage.groups.matrix_gps.special_linear.SL(n, R, name)
     942
     943    def PGLPermutation(self, n, q, name='a'):
     944        r"""
     945        The projective general linear group as a permutation group.
     946
     947        INPUT:
     948
     949        - ``n`` - size of the square matrices in the group
     950        - ``q`` - order of the finite field used for the
     951          entries of the matrices.  Must be a prime power order.
     952        - ``name`` - default: ``'a'`` - a string used to form
     953          the names of the elements of the finite field.
     954
     955        OUTPUT:
     956
     957        The projective general linear group has elements that
     958        are `n\times n` matrices.  Here we limit the entries of
     959        the matrices to elements of a finite field of order `q`.
     960        For finite fields of degree 2 or more ``name`` is a string
     961        that is used to construct the names of the elements of the
     962        field.  More specifically, the group is the quotient of
     963        the general linear group by its center.
     964
     965        The representation returned here is a permutation group
     966        rather than a matrix group. If `F` is the field,
     967        then the items being permuted are the dimension one
     968        subspaces of the vector space `F^n`, which are also
     969        known as "lines".
     970
     971        EXAMPLES:
     972
     973        The general linear group of `2\times 2` matrices over a
     974        finite field of order 3 is composed of 48 invertible matrices.
     975        The center has order 2, hence the projective group has order 24.
     976        The vector space of dimension 2 over the field of order 3 has 8
     977        nonzero vectors, which partition into 4 dimension one subspaces
     978        (the lines).  Hence the permutation representation is a subgroup
     979        of the symmetric group on 4 symbols. ::
     980
     981            sage: G = groups.PGLPermutation(2,3)
     982            sage: G.order()
     983            24
     984            sage: F = G.base_ring()
     985            sage: V = F^2
     986            sage: len(list(V.subspaces(1)))
     987            4
     988            sage: G.degree()
     989            4
     990
     991        Using a finite field of degree greater than one, the symbol
     992        used to describe the elements of the field may be specified.
     993        The irreducible polynomial used to structure the field is
     994        provided automatically by the GAP library and may not be changed. ::
     995
     996            sage: K = groups.PGLPermutation(2, 81, name='c')
     997            sage: K.order()
     998            531360
     999            sage: F = K.base_ring(); F
     1000            Finite Field in c of size 3^4
     1001            sage: F.polynomial()
     1002            c^4 + 2*c^3 + 2
     1003       
     1004        For further documentation, see
     1005        :meth:`~sage.groups.perm_gps.permgroup_named.PGL`.
     1006        """
     1007        import sage.groups.perm_gps.permgroup_named
     1008        return sage.groups.perm_gps.permgroup_named.PGL(n, q, name)
     1009
     1010    def PSLPermutation(self, n, q, name='a'):
     1011        r"""
     1012        The projective special linear group as a permutation group.
     1013
     1014        INPUT:
     1015
     1016        - ``n`` - size of the square matrices in the group
     1017        - ``q`` - order of the finite field used for the
     1018          entries of the matrices.  Must be a prime power order.
     1019        - ``name`` - default: ``'a'`` - a string used to form
     1020          the names of the elements of the finite field.
     1021
     1022        OUTPUT:
     1023
     1024        The projective special linear group has elements that are
     1025        `n\times n` matrices with determinant 1.  Here we limit the
     1026        entries of the matrices to elements of a finite field of
     1027        order `q`. For finite fields of degree 2 or more ``name``
     1028        is a string that is used to construct the names of the
     1029        elements of the field.  More specifically, the group is
     1030        the quotient of the special linear group by its center.
     1031
     1032        The representation returned here is a permutation group
     1033        rather than a matrix group. If `F` is the field,
     1034        then the items being permuted are the dimension one
     1035        subspaces of the vector space `F^n`, which are also
     1036        known as "lines".
     1037
     1038        EXAMPLES:
     1039
     1040        The special linear group of `3\times 3` matrices over
     1041        a finite field of order 5 is composed of
     1042        `124\cdot 120\cdot 100/4=372000` matrices of determinant 1.
     1043        Since the center is trivial, the projective group has the same
     1044        order. The vector space of dimension 3 over the field of
     1045        order 5 has 124 nonzero vectors, which partition into
     1046        31 dimension one subspaces (the lines).  Hence the permutation
     1047        representation is a subgroup of the symmetric group on 31 symbols. ::
     1048
     1049            sage: G = groups.PSLPermutation(3, 5)
     1050            sage: G.order()
     1051            372000
     1052            sage: F = G.base_ring()
     1053            sage: V = F^3
     1054            sage: len(list(V.subspaces(1)))
     1055            31
     1056            sage: G.degree()
     1057            31
     1058
     1059        Using a finite field of degree greater than one, the symbol
     1060        used to describe the elements of the field may be specified.
     1061        The irreducible polynomial used to structure the field is
     1062        provided automatically by the GAP library and may not be changed. ::
     1063
     1064            sage: K = groups.PSLPermutation(2, 81, name='c')
     1065            sage: K.order()
     1066            265680
     1067            sage: F = K.base_ring(); F
     1068            Finite Field in c of size 3^4
     1069            sage: F.polynomial()
     1070            c^4 + 2*c^3 + 2
     1071
     1072        For further documentation, see
     1073        :meth:`~sage.groups.perm_gps.permgroup_named.PSL`.
     1074        """
     1075        import sage.groups.perm_gps.permgroup_named
     1076        return sage.groups.perm_gps.permgroup_named.PSL(n, q, name)
     1077
     1078# This is the object available in the global namespace       
     1079groups = GroupGenerators()
     1080
     1081
     1082   
     1083 No newline at end of file