Function: elltwist
Section: elliptic_curves
C-Name: elltwist
Prototype: GDG
Help: elltwist(E,{P}): returns an ell structure for the twist of the elliptic
 curve E by the quadratic extension defined by P (when P is a polynomial of
 degree 2) or quadpoly(P) (when P is an integer). If E is defined over a
 finite field, then P can be omitted.
Doc: returns an \kbd{ell} structure (as given by \kbd{ellinit}) for the twist
 of the elliptic curve $E$ by the quadratic extension of the coefficient
 ring defined by $P$ (when $P$ is a polynomial) or \kbd{quadpoly(P)} when $P$
 is an integer.  If $E$ is defined over a finite field, then $P$ can be
 omitted, in which case a random model of the unique nontrivial twist is
 returned. If $E$ is defined over a number field, the model should be
 replaced by a minimal model (if one exists).

 The elliptic curve $E$ can be given in some of the formats allowed by
 \kbd{ellinit}: an \kbd{ell} structure, a $5$-component vector
 $[a_1,a_2,a_3,a_4,a_6]$ or a $2$-component vector $[a_4,a_6]$.

 Twist by discriminant $-3$:
 \bprog
 ? elltwist([0,a2,0,a4,a6], -3)[1..5]
 %1 = [0, -3*a2, 0, 9*a4, -27*a6]
 ? elltwist([a4,a6], -3)[1..5]
 %2 = [0, 0, 0, 9*a4, -27*a6]
 @eprog
 Twist by the Artin-Schreier extension given by $x^2+x+T$ in
 characteristic $2$:
 \bprog
 ? lift(elltwist([a1,a2,a3,a4,a6]*Mod(1,2), x^2+x+T)[1..5])
 %1 = [a1, a2+a1^2*T, a3, a4, a6+a3^2*T]
 @eprog
 Twist of an elliptic curve defined over a finite field:
 \bprog
 ? E = elltwist([1,7]*Mod(1,19)); lift([E.a4, E.a6])
 %1 = [11, 12]
 @eprog
