27143: initial version

src/sage/groups/matrix_gps/finitely_generated.py

@@ -62,7 +62,7 @@
 ##############################################################################
 from __future__ import print_function
 
-from sage.rings.all import ZZ
+from sage.rings.all import ZZ, Integer
 from sage.rings.all import QQbar
 from sage.interfaces.gap import gap
 from sage.structure.element import is_Matrix
@@ -512,7 +512,7 @@ def __reduce__(self):
         return (MatrixGroup,
                 tuple(g.matrix() for g in self.gens()) + ({'check':False},))
 
-    def as_permutation_group(self, algorithm=None):
+    def as_permutation_group(self, algorithm=None, seed=None):
         r"""
         Return a permutation group representation for the group.
 
@@ -527,13 +527,19 @@ def as_permutation_group(self, algorithm=None):
         - ``algorithm`` -- ``None`` or ``'smaller'``. In the latter
           case, try harder to find a permutation representation of
           small degree.
+        - ``seed`` -- ``None`` or an integer specifying the seed
+          to fix results depending on pseudo-random-numbers. Here
+          it makes sense to be used with respect to the ``'smaller'``
+          option, since gap produces random output in that context.
 
         OUTPUT:
 
         A permutation group isomorphic to ``self``. The
         ``algorithm='smaller'`` option tries to return an isomorphic
         group of low degree, but is not guaranteed to find the
-        smallest one.
+        smallest one and must not even differ from the one obtained
+        without the option. In that case repeating the invocation
+        may help (see the example below).
 
         EXAMPLES::
 
@@ -550,25 +556,42 @@ def as_permutation_group(self, algorithm=None):
             sage: G = MatrixGroup(GG.GeneratorsOfGroup())
             sage: G.cardinality()
             21499084800
-            sage: set_random_seed(0); current_randstate().set_seed_gap()
             sage: P = G.as_permutation_group()
+            sage: Psmaller = G.as_permutation_group(algorithm="smaller", seed=6)
+            sage: P == Psmaller  # see the note below
+            True
+            sage: Psmaller = G.as_permutation_group(algorithm="smaller")
+            sage: P == Psmaller
+            False
             sage: P.cardinality()
             21499084800
-            sage: P.degree()  # random output
+            sage: P.degree()
             144
-            sage: set_random_seed(3); current_randstate().set_seed_gap()
-            sage: Psmaller = G.as_permutation_group(algorithm="smaller")
             sage: Psmaller.cardinality()
             21499084800
-            sage: Psmaller.degree()  # random output
-            108
+            sage: Psmaller.degree()
+            80
+
+        ..  NOTE::
+
+            In this case, the "smaller" option returned an isomorphic
+            group of lower degree. The above example used GAP's library
+            of irreducible maximal finite ("imf") integer matrix groups
+            to construct the MatrixGroup G over GF(7). The section
+            "Irreducible Maximal Finite Integral Matrix Groups" in the
+            GAP reference manual has more details.
+
+        ..  NOTE::
+
+            Concerning the option ``algorithm='smaller'`` you should note
+            the following from GAP documentation: "The methods used might
+            involve the use of random elements and the permutation
+            representation (or even the degree of the representation) is
+            not guaranteed to be the same for different calls of
+            SmallerDegreePermutationRepresentation."
 
-        In this case, the "smaller" option returned an isomorphic group of
-        lower degree. The above example used GAP's library of irreducible
-        maximal finite ("imf") integer matrix groups to construct the
-        MatrixGroup G over GF(7). The section "Irreducible Maximal Finite
-        Integral Matrix Groups" in the GAP reference manual has more
-        details.
+            To obtain a reproducible result the optional argument ``seed``
+            may be used as in the example above.
 
         TESTS::
 
@@ -596,7 +619,7 @@ def as_permutation_group(self, algorithm=None):
         Check that :trac:`25706` still works after :trac:`26903`::
 
             sage: MG = GU(3,2).as_matrix_group()
-            sage: PG = MG.as_permutation_group()  # this constructs the morphism
+            sage: PG = MG.as_permutation_group()
             sage: mg = MG.an_element()
             sage: PG(mg)
             (1,2,6,19,35,33)(3,9,26,14,31,23)(4,13,5)(7,22,17)(8,24,12)(10,16,32,27,20,28)(11,30,18)(15,25,36,34,29,21) 
@@ -607,6 +630,11 @@ def as_permutation_group(self, algorithm=None):
         from sage.groups.perm_gps.permgroup import PermutationGroup
         if not self.is_finite():
             raise NotImplementedError("Group must be finite.")
+        if seed is not None:
+            if not isinstance(seed, (int, Integer)):
+                raise ValueError( 'seed must be an integer' )
+            from sage.libs.gap.libgap import libgap
+            libgap.set_seed(seed)
         iso=self._libgap_().IsomorphismPermGroup()
         if algorithm == "smaller":
             iso=iso.Image().SmallerDegreePermutationRepresentation()

src/sage/groups/perm_gps/permgroup.py

@@ -871,6 +871,19 @@ def _coerce_map_from_(self, G):
             ....:             if f is not None and g is not None:
             ....:                 h = G3.coerce_map_from(G1)
             ....:                 assert h(elt) == g(f(elt))
+
+        Check that :trac:`26903` is fixed::
+
+            sage: G = SO(4,3,-1)
+            sage: P = G.as_permutation_group(algorithm='smaller', seed=5)
+            sage: P1 = G.as_permutation_group()
+            sage: P == P1
+            False
+            sage: g1, g2, g3 = G.gens()
+            sage: P(g1*g2)
+            (1,9,7,6)(2,10)(3,11)(4,5,8,12)
+            sage: P1(g1*g2)
+            (1,4,13,11)(2,5,14,18)(3,15,8,16)(6,7)(9,20,19,12)(10,17)
         """
         if isinstance(G, PermutationGroup_subgroup):
             if G._ambient_group is self: