forsubgroup

Function: forsubgroup
Section: programming/control
C-Name: forsubgroup0
Prototype: vV=GDGI
Help: forsubgroup(H=G,{bound},seq): execute seq for each subgroup H of the
 abelian group G, whose index is bounded by bound if not omitted. H is given
 as a left divisor of G in HNF form.
Wrapper: (,,vG)
Description:
 (gen,?gen,closure):void  forsubgroup(${3 cookie}, ${3 wrapper}, $1, $2)
Doc: evaluates \var{seq} for
 each subgroup $H$ of the \emph{abelian} group $G$ (given in
 SNF\sidx{Smith normal form} form or as a vector of elementary divisors).

 If \var{bound} is present, and is a positive integer, restrict the output to
 subgroups of index less than \var{bound}. If \var{bound} is a vector
 containing a single positive integer $B$, then only subgroups of index
 exactly equal to $B$ are computed

 The subgroups are not ordered in any
 obvious way, unless $G$ is a $p$-group in which case Birkhoff's algorithm
 produces them by decreasing index. A \idx{subgroup} is given as a matrix
 whose columns give its generators on the implicit generators of $G$. For
 example, the following prints all subgroups of index less than 2 in $G =
 \Z/2\Z g_1 \times \Z/2\Z g_2$:

 \bprog
 ? G = [2,2]; forsubgroup(H=G, 2, print(H))
 [1; 1]
 [1; 2]
 [2; 1]
 [1, 0; 1, 1]
 @eprog\noindent
 The last one, for instance is generated by $(g_1, g_1 + g_2)$. This
 routine is intended to treat huge groups, when \tet{subgrouplist} is not an
 option due to the sheer size of the output.

 For maximal speed the subgroups have been left as produced by the algorithm.
 To print them in canonical form (as left divisors of $G$ in HNF form), one
 can for instance use
 \bprog
 ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
 [2, 1; 0, 1]
 [1, 0; 0, 2]
 [2, 0; 0, 1]
 [1, 0; 0, 1]
 @eprog\noindent
 Note that in this last representation, the index $[G:H]$ is given by the
 determinant. See \tet{galoissubcyclo} and \tet{galoisfixedfield} for
 applications to \idx{Galois} theory.

 \synt{forsubgroup}{void *data, long (*call)(void*,GEN), GEN G, GEN bound}.