Added documentation (and minor fixes) for DecomPoly.

doc/ref/algfld.xml

@@ -95,6 +95,15 @@ gap> m^2;
 
 <#Include Label="IsAlgebraicElement">
 
+</Section>
+
+
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Finding Subfields">
+<Heading>Finding Subfields</Heading>
+
+<#Include Label="IdealDecompositionsOfPolynomial">
+
 </Section>
 </Chapter>
 

lib/algfld.gd

@@ -188,3 +188,45 @@ DeclareGlobalFunction("AlgExtEmbeddedPol");
 
 DeclareGlobalFunction("AlgExtSquareHensel");
 
+#############################################################################
+##
+#F  IdealDecompositionsOfPolynomial( <f> [:"onlyone"] )  finds ideal decompositions of rational f
+##
+##  <#GAPDoc Label="IdealDecompositionsOfPolynomial">
+##  <ManSection>
+##  <Func Name="IdealDecompositionsOfPolynomial" Arg='pol'/>
+##
+##  <Description>
+##  Let <M>f</M> be a univariate, rational, irreducible, polynomial. A
+##  pair <M>g</M>,<M>h</M> of polynomials of degree strictly
+##  smaller than that of <M>f</M>, such that <M>f(x)|g(h(x))</M> is
+##  called an ideal decomposition. In the context of field
+##  extensions, if <M>\alpha</M> is a root of <M>f</M> in a suitable extension
+##  and <M>Q</M> the field of rational numbers. Such decompositions correspond
+##  to (proper) subfields <M>Q\lt Q(\beta)\lt Q(\alpha)</M>, where <M>g</M> is the
+##  minimal polynomial of <M>\beta</M>.
+##  This function determines such decompositions up to equality of the subfields
+##  <M>Q(\beta)</M>, thus determining subfields of a given algebraic extension.
+##  It returns a list of pairs <M>[g,h]</M> (and an empty list if no such
+##  decomposition exists). If the option <A>onlyone</A> is given it returns at
+##  most one such decomposition (and performs faster).
+##  <Example><![CDATA[
+##  gap> x:=X(Rationals,"x");;pol:=x^8-24*x^6+144*x^4-288*x^2+144;;
+##  gap> l:=IdealDecompositionsOfPolynomial(pol);
+##  [ [ x^2+72*x+144, x^6-20*x^4+60*x^2-36 ],
+##    [ x^2-48*x+144, x^6-21*x^4+84*x^2-48 ],
+##    [ x^2+288*x+17280, x^6-24*x^4+132*x^2-288 ],
+##    [ x^4-24*x^3+144*x^2-288*x+144, x^2 ] ]
+##  gap> List(l,x->Value(x[1],x[2])/pol);
+##  [ x^4-16*x^2-8, x^4-18*x^2+33, x^4-24*x^2+120, 1 ]
+##  gap> IdealDecompositionsOfPolynomial(pol:onlyone);
+##  [ [ x^2+72*x+144, x^6-20*x^4+60*x^2-36 ] ]
+##  ]]></Example>
+##  In this example the given polynomial is regular with Galois group
+##  <M>Q_8</M>, as expected we get four proper subfields.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareGlobalFunction("IdealDecompositionsOfPolynomial");
+DeclareSynonym("DecomPoly",IdealDecompositionsOfPolynomial);

lib/algfld.gi

@@ -172,7 +172,8 @@ if Length(extra)>0 and IsString(extra[1]) then
   SetCharacteristic(fam,Characteristic(f));
   fam!.indeterminateName:=nam;
   colf:=CollectionsFamily(fam);
-  e:=Objectify(NewType(colf,IsAlgebraicExtensionDefaultRep),
+  e:=Objectify(NewType(colf,
+      IsAlgebraicExtensionDefaultRep and IsAlgebraicExtension),
                rec());
 
   fam!.wholeField:=e;
@@ -2193,13 +2194,14 @@ end);
 
 #############################################################################
 ##
-#F  DecomPoly( <f> [,"all"] )  finds (all) ideal decompositions of rational f
+#F  IdealDecompositionsOfPolynomial( <f> [,"onlyone"] )  finds ideal decompositions of rational f
 ##                       This is equivalent to finding subfields of K(alpha).
 ##
-DecomPoly := function(arg)
-local f,n,e,ff,p,ffp,ffd,roots,allroots,nowroots,fm,fft,comb,combi,k,h,i,j,
-      gut,avoid,blocks,g,m,decom,z,R,scale,allowed,hp,hpc,a,kfam;
-  f:=arg[1];
+InstallGlobalFunction(IdealDecompositionsOfPolynomial,function(f)
+local n,e,ff,p,ffp,ffd,roots,allroots,nowroots,fm,fft,comb,combi,k,h,i,j,
+      gut,avoid,blocks,g,m,decom,z,R,scale,allowed,hp,hpc,a,kfam,only;
+
+  only:=ValueOption("onlyone")=true;
   n:=DegreeOfUnivariateLaurentPolynomial(f);
   if IsPrime(n) then
     return [];
@@ -2255,9 +2257,9 @@ local f,n,e,ff,p,ffp,ffd,roots,allroots,nowroots,fm,fft,comb,combi,k,h,i,j,
     fft:=ff{combi};
     ffp:=List(fft,i->AlgebraicPolynomialModP(kfam,i,fm[1],p));
     roots:=Filtered(fm,i->ForAny(ffp,j->Value(j,i)=Zero(k)));
-  if Length(roots)<>Sum(ffd{combi}) then
-    Error("serious error");
-  fi;
+    if Length(roots)<>Sum(ffd{combi}) then
+      Error("serious error");
+    fi;
     allroots:=Union(roots,[fm[1]]);
     gut:=true;
     j:=1;
@@ -2270,9 +2272,7 @@ local f,n,e,ff,p,ffp,ffd,roots,allroots,nowroots,fm,fft,comb,combi,k,h,i,j,
     if gut then
       Info(InfoPoly,2,"block found");
       Add(blocks,combi);
-      if Length(arg)>1 then
-        gut:=false;
-      fi;
+      if only<>true then gut:=false; fi;
     fi;
     h:=h+1;
   od;
@@ -2328,15 +2328,12 @@ local f,n,e,ff,p,ffp,ffd,roots,allroots,nowroots,fm,fft,comb,combi,k,h,i,j,
       #h:=Value(h,X(Rationals)*z);
       Add(decom,[g,h]);
     od;
-    if Length(arg)=1 then
-      decom:=decom[1];
-    fi;
     return decom;
   else
     Info(InfoPoly,2,"primitive");
     return [];
   fi;
-end;
+end);
 
 #############################################################################
 ##

lib/grp.gd

@@ -4543,14 +4543,17 @@ DeclareOperation( "LowIndexSubgroups",
 ##  provided only as a separate function, and not as method for the operation
 ##  <C>Normalizer</C>, as it can often be slower than other built-in routines.
 ##  In certain hard cases (non-solvable groups with nontrivial radical), however
-##  its performance is substantially superior.  The function thus provided as a
+##  its performance is substantially superior.
+##  The function thus is provided as a
 ##  non-automated tool for advanced users.
 ##  <Example><![CDATA[
 ##  gap> g:=TransitiveGroup(30,2030);;
 ##  gap> s:=SylowSubgroup(g,5);;
 ##  gap> Size(NormalizerViaRadical(g,s));
 ##  28800
 ##  ]]></Example>
+##  Note that this example only demonstrates usage, but that in this case
+##  in fact the ordinary <C>Normalizer</C> routine performs faster.
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>