Ticket #14291: 14291_reviewer.patch

sage/groups/perm_gps/permgroup.py

@@ -96 +96 @@
 
 - Javier Lopez Pena (2013): Added conjugacy classes.
 
+- Nathann Cohen, Dmitrii Pasechnik (2013): Added non-default actions.
+
 REFERENCES:
 
 - Cameron, P., Permutation Groups. New York: Cambridge University
@@ -1039 +1041 @@
     def orbits(self):
         """
         Returns the orbits of the elements of the domain under the
-        group action.
+        default group action.
         
         EXAMPLES::
         
@@ -1066 +1068 @@
         return [[self._domain_from_gap[x] for x in orbit] for orbit in
                 self._gap_().Orbits(self._domain_gap()).sage()]
 
+    supported_actions = ["OnPoints", "OnTuples", "OnSets", "OnPairs", "OnSetsSets", 
+                "OnSetsDisjointSets", "OnSetsTuples", "OnTuplesSets", "OnTuplesTuples"]
+
     @cached_method
     def orbit(self, point, action = "OnPoints"):
         """
-        Return the orbit of a point (or set, or tuple) under the group action.
+        Return the orbit of a point under the group action in the list
+        `self.supported_actions`. 
+        These are taken from `http://www.gap-system.org/Manuals/doc/ref/chap41.html`_. 
 
         INPUT:
 
-        - ``point`` -- can be a point or a tuple of points, depending on the
-          action to be considered.
-
-        - ``action`` (string) -- when ``point`` is a tuple of points, this
-          variable defines whether the group is to be considered as acting on
-          tuples (``action="ontuples"``) or acting on sets
-          (``action="onsets"``). It is set to ``"onpoints"`` by default. See
-          below for examples.
+        - ``point`` -- can be a point or any of the list above, depending on the
+          action to be considered. Note that sets should be "canonical", i.e. their
+          members must be sorted w.r.t. to the default order on them.
+
+        - ``action`` (string) -- if ``point`` is a tuple (of tuples) of points, this
+          variable describes how the group is acting. The list of possibilites is 
+          is given by  `self.supported_actions`.
+          It is set to ``"OnPoints"`` by default. See below for examples.
 
         EXAMPLES::
 
@@ -1104 +1111 @@
 
             sage: S3.orbit((1,2), action = "OnTuples")
             [[1, 2], [2, 3], [2, 1], [3, 1], [1, 3], [3, 2]]
+        
+        Action of `S_4` on sets of disjoint sets::
+
+            sage: S4 = groups.permutation.Symmetric(4)
+            sage: S4.orbit(((1,2),(3,4)), action = "OnSetsDisjointSets")
+            [[[1, 2], [3, 4]], [[1, 4], [2, 3]], [[1, 3], [2, 4]]]
+
         """
         if action == "OnPoints":
             try:
@@ -1115 +1129 @@
                                  "argument explicitly.")
             return [self._domain_from_gap[x] for x in self._gap_().Orbit(point).sage()]
 
-        elif action in ["OnTuples", "OnSets"]:
-            points = [self._domain_to_gap[x] for x in point]
-            orbits = self._gap_().Orbit(points, action).sage()
-            return [[self._domain_from_gap[x] for x in o] for o in orbits]
+        elif action in self.supported_actions:
+            if action in ['OnTuples', 'OnSets', 'OnPairs']:
+                points = [self._domain_to_gap[x] for x in point]
+                orbits = self._gap_().Orbit(points, action).sage()
+                return [[self._domain_from_gap[x] for x in o] for o in orbits]
+            else:
+                points = [[self._domain_to_gap[x] for x in p] for p in point]
+                orbits = self._gap_().Orbit(points, action).sage()
+                return [[[self._domain_from_gap[x] for x in p] for p in o] 
+                        for o in orbits]
+
         else:
-            raise ValueError("'action' can only take values among 'OnPoints', 'OnTuples' or 'OnSets'.")
+            raise ValueError("'action' can only take values among "+
+                             self.supported_actions)
+
+    def action(self, domain, action = "OnPoints"):
+        """
+        Return the permutation group induced by self acting on domain.
+        
+        INPUT:
+
+        - ``domain`` -- the list of things for which GAP knows how to compute
+          the action of the permutation group. For instance it can be obtained by
+          calling :meth:`orbit`. 
+
+        - ``action`` (string) -- the action on domain. Need not be limited to 
+          `self.supported_actions`.
+          It is set to ``"OnPoints"`` by default. See below for examples.
+
+        EXAMPLES::
+
+            Action of `S_5` on 2-subsets::
+
+            sage: S5 = groups.permutation.Symmetric(5)
+            sage: o10 = S5.orbit((1,2), action = "OnSets")
+            sage: S5_10 = S5.action(o10, action = "OnSets"); S5_10
+            Permutation Group with generators [(2,4)(6,9)(7,10), (1,2,3,5,7)(4,6,8,9,10)]
+            
+            Non-faithful action of `S_4` on sets of disjoint sets::
+
+            sage: S4 = groups.permutation.Symmetric(4)
+            sage: o3 = S4.orbit(((1,2),(3,4)), action = "OnSetsDisjointSets")
+            sage: S3 = S4.action(o3,  "OnSetsDisjointSets"); S3
+            Permutation Group with generators [(2,3), (1,2)]
+            sage: S3.order()
+            6
+
+        """
+        return PermutationGroup(gap_group = self._gap_().Action(domain, action))
 
     def transversals(self, point):
         """