From 120b0faa06fda4824c22f8ca00cb18ce26689cf6 Mon Sep 17 00:00:00 2001
From: Alexander Hulpke <hulpke@math.colostate.edu>
Date: Thu, 1 Feb 2018 13:38:30 -0700
Subject: [PATCH] ENHANCE: Added manual to `LowIndexSubgroups'.

as requested in #2131

Also added `LowLayerSubgroups` and minor rephrasing.

Also redid part of #683, as for some reason (probably my stupidity)
part of #683 had fallen out of master. Added it again.
---
 doc/ref/groups.xml |  3 ++-
 lib/grp.gd         | 10 ++++++----
 lib/grplatt.gi     | 17 +++++++++++++++++
 3 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/doc/ref/groups.xml b/doc/ref/groups.xml
index b90516e4d32..003c6706b0a 100644
--- a/doc/ref/groups.xml
+++ b/doc/ref/groups.xml
@@ -449,8 +449,9 @@ the series without destroying the properties of the series.
 <#Include Label="IsConjugacyClassSubgroupsRep">
 <#Include Label="ConjugacyClassesSubgroups">
 <#Include Label="ConjugacyClassesMaximalSubgroups">
-<#Include Label="AllSubgroups">
 <#Include Label="MaximalSubgroupClassReps">
+<#Include Label="LowIndexSubgroups">
+<#Include Label="AllSubgroups">
 <#Include Label="MaximalSubgroups">
 <#Include Label="NormalSubgroups">
 <#Include Label="MaximalNormalSubgroups">
diff --git a/lib/grp.gd b/lib/grp.gd
index c0648525658..42a8274a085 100644
--- a/lib/grp.gd
+++ b/lib/grp.gd
@@ -4495,12 +4495,12 @@ DeclareGlobalFunction("GroupEnumeratorByClosure");
 ##
 ##  <#GAPDoc Label="LowIndexSubgroups">
 ##  <ManSection>
-##  <Oper Name="LowIndexSubgroups"
-##   Arg='G, index'/>
 ##  <Oper Name="LowIndexSubgroups" Arg='G, index'/>
+##  <Oper Name="LowLayerSubgroups" Arg='G, layer'/>
 ##
 ##  <Description>
-##  These operations computes representatives of the conjugacy classes of
+##  The operation <C>LowIndexSubgroups</C> computes representatives of the
+##  conjugacy classes of
 ##  subgroups of the group <A>G</A> that 
 ##  index less than or equal to
 ##  <A>index</A>.
@@ -4509,13 +4509,15 @@ DeclareGlobalFunction("GroupEnumeratorByClosure");
 ##  <C>LowIndexSubgroupsFpGroup</C>. In other cases, it uses repeated
 ##  calculation of maximal subgroups.
 ##  <P/>
+##  The operation <C>LowLayerSubgroups</C> works similar but does not bound
+##  the index, but instead considers up to <A>layer</A>-th maximal
+##  subgroups.
 ##  <Example><![CDATA[
 ##  gap> g:=TransitiveGroup(18,950);;
 ##  gap> l:=LowIndexSubgroups(g,20);;Collected(List(l,x->Index(g,x)));
 ##  [ [ 1, 1 ], [ 2, 1 ], [ 5, 1 ], [ 6, 1 ], [ 10, 2 ], [ 12, 3 ], [ 15, 1 ], 
 ##    [ 16, 2 ], [ 18, 1 ], [ 20, 9 ] ]
 ##  ]]></Example>
-##  <P/>
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>
diff --git a/lib/grplatt.gi b/lib/grplatt.gi
index 623df0722d2..64b5c2c2bd1 100644
--- a/lib/grplatt.gi
+++ b/lib/grplatt.gi
@@ -3053,6 +3053,23 @@ local recog,m,len;
   return m;
 end);
 
+InstallMethod(LowIndexSubgroups,"finite groups, using iterated maximals",
+  true,[IsGroup and IsFinite,IsPosInt],0,
+function(G,n)
+local m,all,m2;
+  m:=[G];
+  all:=[G];
+  while Length(m)>0 do
+    m2:=Concatenation(List(m,MaximalSubgroupClassReps));
+    m2:=Unique(Filtered(m2,x->Index(G,x)<=n));
+    m2:=List(SubgroupsOrbitsAndNormalizers(G,m2,false),x->x.representative);
+    m2:=Filtered(m2,x->ForAll(all,y->RepresentativeAction(G,x,y)=fail));
+    Append(all,m2);
+    m:=Filtered(m2,x->Index(G,x)<=n/2); # otherwise subgroups will have too large index
+  od;
+  return all;
+end);
+
 #############################################################################
 ##
 #F  LowLayerSubgroups( [<act>,] <G>, <lim> [,<cond> [,<dosub>]] )