Function: ellgroup
Section: elliptic_curves
C-Name: ellgroup0
Prototype: GDGD0,L,
Help: ellgroup(E,{p},{flag}): computes the structure of the group E(Fp)
 If flag is 1, return also generators.
Doc: Let $E$ be an \var{ell} structure as output by \kbd{ellinit}, defined over
 $\Q$ or a finite field $\F_q$. The argument $p$ is best left omitted if the
 curve is defined over a finite field, and must be a prime number otherwise.
 This function computes the structure of the group $E(\F_q) \sim \Z/d_1\Z
 \times \Z/d_2\Z$, with $d_2\mid d_1$.

 If the curve is defined over $\Q$, $p$ must be explicitly given and the
 function computes the structure of the reduction over $\F_p$; the
 equation need not be minimal at $p$, but a minimal model will be more
 efficient. The reduction is allowed to be singular, and we return the
 structure of the (cyclic) group of non-singular points in this case.

 If the flag is $0$ (default), return $[d_1]$ or $[d_1, d_2]$, if $d_2>1$.
 If the flag is $1$, return a triple $[h,\var{cyc},\var{gen}]$, where
 $h$ is the curve cardinality, \var{cyc} gives the group structure as a
 product of cyclic groups (as per $\fl = 0$). More precisely, if $d_2 > 1$,
 the output is $[d_1d_2, [d_1,d_2],[P,Q]]$ where $P$ is
 of order $d_1$ and $[P,Q]$ generates the curve.
 \misctitle{Caution} It is not guaranteed that $Q$ has order $d_2$, which in
 the worst case requires an expensive discrete log computation. Only that
 \kbd{ellweilpairing(E, P, Q, d1)} has order $d_2$.
 \bprog
 ? E = ellinit([0,1]);  \\ y^2 = x^3 + 0.x + 1, defined over Q
 ? ellgroup(E, 7)
 %2 = [6, 2] \\ Z/6 x Z/2, non-cyclic
 ? E = ellinit([0,1] * Mod(1,11));  \\ defined over F_11
 ? ellgroup(E)   \\ no need to repeat 11
 %4 = [12]
 ? ellgroup(E, 11)   \\ ... but it also works
 %5 = [12]
 ? ellgroup(E, 13) \\ ouch, inconsistent input!
    ***   at top-level: ellgroup(E,13)
    ***                 ^--------------
    *** ellgroup: inconsistent moduli in Rg_to_Fp:
      11
      13
 ? ellgroup(E, 7, 1)
 %6 = [12, [6, 2], [[Mod(2, 7), Mod(4, 7)], [Mod(4, 7), Mod(4, 7)]]]
 @eprog\noindent
 If $E$ is defined over $\Q$, we allow singular reduction and in this case we
 return the structure of the group of non-singular points, satisfying
 $\#E_{ns}(\F_p) = p - a_p$.
 \bprog
 ? E = ellinit([0,5]);
 ? ellgroup(E, 5, 1)
 %2 = [5, [5], [[Mod(4, 5), Mod(2, 5)]]]
 ? ellap(E, 5)
 %3 = 0 \\ additive reduction at 5
 ? E = ellinit([0,-1,0,35,0]);
 ? ellgroup(E, 5, 1)
 %5 = [4, [4], [[Mod(2, 5), Mod(2, 5)]]]
 ? ellap(E, 5)
 %6 = 1 \\ split multiplicative reduction at 5
 ? ellgroup(E, 7, 1)
 %7 = [8, [8], [[Mod(3, 7), Mod(5, 7)]]]
 ? ellap(E, 7)
 %8 = -1 \\ non-split multiplicative reduction at 7
 @eprog

Variant: Also available is \fun{GEN}{ellgroup}{GEN E, GEN p}, corresponding
 to \fl = 0.