Function: random
Section: conversions
C-Name: genrand
Prototype: DG
Help: random({N=2^31}): random object, depending on the type of N.
 Integer between 0 and N-1 (t_INT), int mod N (t_INTMOD), element in a finite
 field (t_FFELT), point on an elliptic curve (ellinit mod p or over a finite
 field).
Doc:
 returns a random element in various natural sets depending on the
 argument $N$.

 \item \typ{INT}: returns an integer
 uniformly distributed between $0$ and $N-1$. Omitting the argument
 is equivalent to \kbd{random(2\pow31)}.

 \item \typ{REAL}: returns a real number in $[0,1[$ with the same accuracy as
 $N$ (whose mantissa has the same number of significant words).

 \item \typ{INTMOD}: returns a random intmod for the same modulus.

 \item \typ{FFELT}: returns a random element in the same finite field.

 \item \typ{VEC} generated by \kbd{ellinit} over a finite field $k$
 (coefficients are \typ{INTMOD}s modulo a prime or \typ{FFELT}s): returns a
 random $k$-rational \emph{affine} point on the curve. More precisely an
 abscissa is drawn uniformly at random until \tet{ellordinate} succeeds.
 In particular, the curves over $\F_2$ with a single point (at infinity!)
 will trigger an infinite loop. Note that this is definitely not a uniform
 distribution over $E(k)$.

 \item \typ{POL} return a random polynomial of degree at most the degree of $N$.
 The coefficients are drawn by applying \kbd{random} to the leading
 coefficient of $N$.

 \bprog
 ? random(10)
 %1 = 9
 ? random(Mod(0,7))
 %2 = Mod(1, 7)
 ? a = ffgen(ffinit(3,7), 'a); random(a)
 %3 = a^6 + 2*a^5 + a^4 + a^3 + a^2 + 2*a
 ? E = ellinit([0,0,0,3,7]*Mod(1,109)); random(E)
 %4 = [Mod(103, 109), Mod(10, 109)]
 ? E = ellinit([0,0,0,1,7]*a^0); random(E)
 %5 = [a^6 + a^5 + 2*a^4 + 2*a^2, 2*a^6 + 2*a^4 + 2*a^3 + a^2 + 2*a]
 ? random(Mod(1,7)*x^4)
 %6 = Mod(5, 7)*x^4 + Mod(6, 7)*x^3 + Mod(2, 7)*x^2 + Mod(2, 7)*x + Mod(5, 7)

 @eprog
 These variants all depend on a single internal generator, and are
 independent from the system's random number generator.
 A random seed may be obtained via \tet{getrand}, and reset
 using \tet{setrand}: from a given seed, and given sequence of \kbd{random}s,
 the exact same values will be generated. The same seed is used at each
 startup, reseed the generator yourself if this is a problem.

 \misctitle{Technical note}
 Up to
 version 2.4 included, the internal generator produced pseudo-random numbers
 by means of linear congruences, which were not well distributed in arithmetic
 progressions. We now
 use Brent's XORGEN algorithm, based on Feedback Shift Registers, see
 \kbd{http://wwwmaths.anu.edu.au/\til{}brent/random.html}. The generator has period
 $2^{4096}-1$, passes the Crush battery of statistical tests of L'Ecuyer and
 Simard, but is not suitable for cryptographic purposes: one can reconstruct
 the state vector from a small sample of consecutive values, thus predicting
 the entire sequence.
Variant:
  Also available: \fun{GEN}{ellrandom}{GEN E} and \fun{GEN}{ffrandom}{GEN a}.
