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>