# HG changeset patch
# User Rob Beezer
# 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/doc/en/reference/groups.rst
+++ b/doc/en/reference/groups.rst
@@ -6,6 +6,7 @@
.. toctree::
:maxdepth: 2
+ sage/groups/group_generators
sage/groups/group
sage/groups/generic
sage/groups/abelian_gps/abelian_group
diff --git a/sage/groups/all.py b/sage/groups/all.py
--- a/sage/groups/all.py
+++ b/sage/groups/all.py
@@ -12,3 +12,5 @@
from class_function import ClassFunction
from additive_abelian.all import *
+
+from group_generators import groups
diff --git a/sage/groups/group_generators.py b/sage/groups/group_generators.py
new file mode 100644
--- /dev/null
+++ b/sage/groups/group_generators.py
@@ -0,0 +1,727 @@
+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."
+ """
+ return 'Object collecting examples of graphs, try "groups."'
+
+ 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. = 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. = 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