Random Number States¶

AUTHORS:

Carl Witty (2008-03): new file

This module manages all the available pseudo-random number generators in Sage. (For the rest of the documentation in this module, we will drop the “pseudo”.)

The goal is to allow algorithms using random numbers to be reproducible from one run of Sage to the next, and (to the extent possible) from one machine to the next (even across different operating systems and architectures).

There are two parts to the API. First we will describe the command line oriented API, for setting random number generator seeds. Then we will describe the library API, for people writing Sage library code that uses random numbers.

Library API¶

First, we’ll cover doctesting. Every docstring now has an implicit set_random_seed(0) prepended. Any uses of # random that are based on random numbers under the control of this module should be removed, and the reproducible answers inserted instead.

This practice has two potential drawbacks. First, it increases the work of maintaining doctests. For instance, in a long docstring that has many doctests that depend on random numbers, a change near the beginning (for instance, adding a new doctest) may invalidate all later doctests in the docstring. To reduce this downside, you may add calls to set_random_seed(0) throughout the docstring (in the extreme case, before every doctest).

Second, the # random in the doctest served as a signal to the reader of the docstring that the result was unpredictable and that it would not be surprising to get a different result when trying out the examples in the doctest. If a doctest specifically refers to ZZ.random_element() (for instance), this is presumably enough of a signal to render this function of # random unnecessary. However, some doctests are not obviously (from the name) random, but do depend on random numbers internally, such as the composition_series method of a PermutationGroup. In these cases, the convention is to insert the following text at the beginning of the EXAMPLES section.

These computations use pseudo-random numbers, so we set the
seed for reproducible testing.

    sage: set_random_seed(0)

Note that this call to set_random_seed(0) is redundant, since set_random_seed(0) is automatically inserted at the beginning of every docstring. However, it makes the example reproducible for somebody who just types the lines from the doctest and doesn’t know about the automatic set_random_seed(0).

Next, let’s cover setting the random seed from library code. The first rule is that library code should never call set_random_seed(). This function is only for command-line use. Instead, if the library code wants to use a different random seed, it should use with seed(s):. This will use the new seed within the scope of the with statement, but will revert to the previous seed once the with statement is completed. (Or the library can use with seed(): to get a seed automatically selected using os.urandom() or the current time, in the same way as described for set_random_seed() above.)

Ideally, using with seed(s): should not affect the outer random number sequence at all; we will call this property “isolation.” We achieve isolation for most, but not all, of the random number generators in Sage (we fail for generators, such as NTL, that do not provide an API to retrieve the current random number state).

We’ll demonstrate isolation. First, we show the sequence of random numbers that you get without intervening with seed.

Sage

sage: set_random_seed(0)
sage: r1 = rtest(); print(r1)
(303, -0.266166246380421, 1/2*x^2 - 1/95*x - 1/2, (1,3), [ 1, 0, 0, 1, 1 ], 265625921, 5842, 0.9661911734708414)
sage: r2 = rtest(); print(r2)
(105, 0.642309615982449, -x^2 - x - 6, (1,3)(4,5), [ 1, 0, 0, 0, 1 ], 53231108, 77132, 0.001767155077382232)

Python

>>> from sage.all import *
>>> set_random_seed(Integer(0))
>>> r1 = rtest(); print(r1)
(303, -0.266166246380421, 1/2*x^2 - 1/95*x - 1/2, (1,3), [ 1, 0, 0, 1, 1 ], 265625921, 5842, 0.9661911734708414)
>>> r2 = rtest(); print(r2)
(105, 0.642309615982449, -x^2 - x - 6, (1,3)(4,5), [ 1, 0, 0, 0, 1 ], 53231108, 77132, 0.001767155077382232)

We get slightly different results with an intervening with seed.

Sage

sage: set_random_seed(0)
sage: r1 == rtest()
True
sage: with seed(1): rtest()
(978, 0.0557699430711638, -3*x^2 - 1/12, (1,2), [ 0, 0, 1, 1, 0 ], 807447831, 29982, 0.8335077654199736)
sage: r2m = rtest(); r2m
(105, 0.642309615982449, -x^2 - x - 6, (1,3)(4,5), [ 1, 0, 0, 0, 1 ], 53231108, 40267, 0.001767155077382232)
sage: r2m == r2
False

Python

>>> from sage.all import *
>>> set_random_seed(Integer(0))
>>> r1 == rtest()
True
>>> with seed(Integer(1)): rtest()
(978, 0.0557699430711638, -3*x^2 - 1/12, (1,2), [ 0, 0, 1, 1, 0 ], 807447831, 29982, 0.8335077654199736)
>>> r2m = rtest(); r2m
(105, 0.642309615982449, -x^2 - x - 6, (1,3)(4,5), [ 1, 0, 0, 0, 1 ], 53231108, 40267, 0.001767155077382232)
>>> r2m == r2
False

We can see that r2 and r2m are the same except for the call to ntl.ZZ_random(), which produces different results with and without the with seed.

However, we do still get a partial form of isolation, even in this case, as we see in this example:

Sage

sage: set_random_seed(0)
sage: r1 == rtest()
True
sage: with seed(1):
....:     print(rtest())
....:     print(rtest())
(978, 0.0557699430711638, -3*x^2 - 1/12, (1,2), [ 0, 0, 1, 1, 0 ], 807447831, 29982, 0.8335077654199736)
(138, -0.0404945051288503, 2*x - 24, (1,2,3), [ 1, 1, 0, 1, 1 ], 1010791326, 91360, 0.0033332230808060803)
sage: r2m == rtest()
True

Python

>>> from sage.all import *
>>> set_random_seed(Integer(0))
>>> r1 == rtest()
True
>>> with seed(Integer(1)):
...     print(rtest())
...     print(rtest())
(978, 0.0557699430711638, -3*x^2 - 1/12, (1,2), [ 0, 0, 1, 1, 0 ], 807447831, 29982, 0.8335077654199736)
(138, -0.0404945051288503, 2*x - 24, (1,2,3), [ 1, 1, 0, 1, 1 ], 1010791326, 91360, 0.0033332230808060803)
>>> r2m == rtest()
True

The NTL results after the with seed don’t depend on how many NTL random numbers were generated inside the with seed.

sage: set_random_seed(0) sage: r1 == rtest() True sage: with seed(1): ….: rtest() (978, 0.0557699430711638, -3*x^2 - 1/12, (1,2), [ 0, 0, 1, 1, 0 ], 807447831, 29982, 0.8335077654199736) sage: r2m == rtest() True

(In general, the above code is not exactly equivalent to the with statement, because if an exception happens in the body, the real with statement will pass the exception information as parameters to the __exit__ method. However, our __exit__ method ignores the exception information anyway, so the above is equivalent in our case.)

Generating random numbers in library code¶

Now we come to the last part of the documentation: actually generating random numbers in library code. First, the easy case. If you generate random numbers only by calling other Sage library code (such as random_element methods on parents), you don’t need to do anything special; the other code presumably already interacts with this module correctly.

Otherwise, it depends on what random number generator you want to use.

gmp_randstate_t – if you want to use some random number generator that takes a gmp_randstate_t (like mpz_urandomm or mpfr_urandomb), then use code like the following:
```
from sage.misc.randstate cimport randstate, current_randstate
...

cdef randstate rstate = current_randstate()
```
Then a gmp_randstate_t is available as rstate.gmp_state.

Fetch the current randstate with current_randstate() in every function that wants to use it; don’t cache it globally or in a class. (Such caching would break set_random_seed).
Python – if you want to use the random number generators from the random module, you have two choices. The slightly easier choice is to import functions from sage.misc.prandom; for instance, you can simply replace from random import randrange with from sage.misc.prandom import randrange. However, this is slightly less efficient, because the wrappers in sage.misc.prandom look up the current randstate on each call. If you’re generating many random numbers in a row, it’s faster to instead do
```
from sage.misc.randstate import current_randstate ...

randrange = current_randstate().python_random().randrange
```
Fetch the current randstate with current_randstate() in every function that wants to use it; don’t cache the randstate, the Random object returned by python_random, or the bound methods on that Random object globally or in a class. (Such caching would break set_random_seed).
GAP – if you are calling code in GAP that uses random numbers, call set_seed_gap at the beginning of your function, like this:
```
from sage.misc.randstate import current_randstate
...

current_randstate().set_seed_gap()
```
Fetch the current randstate with current_randstate() in every function that wants to use it; don’t cache it globally or in a class. (Such caching would break set_random_seed).
Pari – if you are calling code in the Pari library that uses random numbers, call set_seed_pari at the beginning of your function, like this:
```
from sage.misc.randstate import current_randstate
...

current_randstate().set_seed_pari()
```
Fetch the current randstate with current_randstate() in every function that wants to use it; don’t cache it globally or in a class. (Such caching would break set_random_seed).
Pari/gp – if you are calling code in a Pari/gp subprocess that uses random numbers, call set_seed_gp at the beginning of your function, like this:
```
from sage.misc.randstate import current_randstate
...

current_randstate().set_seed_gp()
```
This will set the seed in the gp process in sage.interfaces.gp.gp. If you have a different gp process, say in the variable my_gp, then call set_seed_gp(my_gp) instead.

Fetch the current randstate with current_randstate() in every function that wants to use it; don’t cache it globally or in a class. (Such caching would break set_random_seed).
NTL – if you are calling code in the NTL library that uses random numbers, call set_seed_ntl at the beginning of your function, like this:
```
from sage.misc.randstate import current_randstate ...

current_randstate().set_seed_ntl(False)
```
Fetch the current randstate with current_randstate() in every function that wants to use it; don’t cache it globally or in a class. (Such caching would break set_random_seed).
libc – if you are writing code that calls the libc function random(): don’t! The random() function does not give reproducible results across different operating systems, so we can’t make portable doctests for the results. Instead, do:
```
from sage.misc.randstate cimport random
```
The random() function in sage.misc.randstate gives a 31-bit random number, but it uses the gmp_randstate_t in the current randstate, so it is portable. (This range was chosen for two reasons: it matches the range of random() on 32-bit and 64-bit Linux, although not Solaris; and it’s the largest range of nonnegative numbers that fits in a 32-bit signed integer.)

However, you may still need to set the libc random number state; for instance, if you are wrapping a library that uses random() internally and you don’t want to change the library. In that case, call set_seed_libc at the beginning of your function, like this:
```
from sage.misc.randstate import current_randstate
...

current_randstate().set_seed_libc(False)
```
Fetch the current randstate with current_randstate() in every function that wants to use it; don’t cache it globally or in a class. (Such caching would break set_random_seed).

Classes and methods¶

sage.misc.randstate.benchmark_libc()[source]¶

This function was used to test whether moving from libc to GMP’s Mersenne Twister for random numbers would be a significant slowdown.

EXAMPLES:

Sage

sage: from sage.misc.randstate import benchmark_libc, benchmark_mt
sage: timeit('benchmark_libc()')  # random
125 loops, best of 3: 1.95 ms per loop
sage: timeit('benchmark_mt()')    # random
125 loops, best of 3: 2.12 ms per loop

Python

>>> from sage.all import *
>>> from sage.misc.randstate import benchmark_libc, benchmark_mt
>>> timeit('benchmark_libc()')  # random
125 loops, best of 3: 1.95 ms per loop
>>> timeit('benchmark_mt()')    # random
125 loops, best of 3: 2.12 ms per loop

sage.misc.randstate.benchmark_mt()[source]¶

This function was used to test whether moving from libc to GMP’s Mersenne Twister for random numbers would be a significant slowdown.

EXAMPLES:

Sage

sage: from sage.misc.randstate import benchmark_libc, benchmark_mt
sage: timeit('benchmark_libc()')  # random
125 loops, best of 3: 1.95 ms per loop
sage: timeit('benchmark_mt()')    # random
125 loops, best of 3: 2.11 ms per loop

Python

>>> from sage.all import *
>>> from sage.misc.randstate import benchmark_libc, benchmark_mt
>>> timeit('benchmark_libc()')  # random
125 loops, best of 3: 1.95 ms per loop
>>> timeit('benchmark_mt()')    # random
125 loops, best of 3: 2.11 ms per loop

sage.misc.randstate.current_randstate()[source]¶

Return the current random number state.

EXAMPLES:

Sage

sage: set_random_seed(0)
sage: current_randstate()
<sage.misc.randstate.randstate object at 0x...>
sage: current_randstate().python_random().random()
0.111439293741037

Python

>>> from sage.all import *
>>> set_random_seed(Integer(0))
>>> current_randstate()
<sage.misc.randstate.randstate object at 0x...>
>>> current_randstate().python_random().random()
0.111439293741037

sage.misc.randstate.initial_seed()[source]¶

Return the initial seed used to create the current randstate.

EXAMPLES:

Sage

sage: set_random_seed(42)
sage: initial_seed()
42

Python

>>> from sage.all import *
>>> set_random_seed(Integer(42))
>>> initial_seed()
42

If you set a random seed (by failing to specify the seed), this is how you retrieve the seed actually chosen by Sage. This can also be used to retrieve the seed chosen for a new Sage run (if the user has not used set_random_seed()).

Sage

sage: set_random_seed()
sage: initial_seed()          # random
121030915255244661507561642968348336774

Python

>>> from sage.all import *
>>> set_random_seed()
>>> initial_seed()          # random
121030915255244661507561642968348336774

sage.misc.randstate.random()[source]¶

Return a 31-bit random number. Intended as a drop-in replacement for the libc random() function.

EXAMPLES:

Sage

sage: set_random_seed(31)
sage: from sage.misc.randstate import random
sage: random()
32990711

Python

>>> from sage.all import *
>>> set_random_seed(Integer(31))
>>> from sage.misc.randstate import random
>>> random()
32990711

class sage.misc.randstate.randstate[source]¶

Bases: object

The randstate class. This class keeps track of random number states and seeds. Type sage.misc.randstate? for much more information on random numbers in Sage.

ZZ_seed()[source]¶

When called on the current randstate, returns a 128-bit Integer suitable for seeding another random number generator.

EXAMPLES:

Sage

sage: set_random_seed(1414)
sage: current_randstate().ZZ_seed()
48314508034782595865062786044921182484

Python

>>> from sage.all import *
>>> set_random_seed(Integer(1414))
>>> current_randstate().ZZ_seed()
48314508034782595865062786044921182484

c_rand_double()[source]¶

Return a random floating-point number between 0 and 1.

EXAMPLES:

Sage

sage: set_random_seed(2718281828)
sage: current_randstate().c_rand_double()
0.22437207488974298

Python

>>> from sage.all import *
>>> set_random_seed(Integer(2718281828))
>>> current_randstate().c_rand_double()
0.22437207488974298

c_random()[source]¶

Return a 31-bit random number. Intended for internal use only; instead of calling current_randstate().c_random(), it is equivalent (but probably faster) to call the random method of this randstate class.

EXAMPLES:

Sage

sage: set_random_seed(1207)
sage: current_randstate().c_random()
2008037228

Python

>>> from sage.all import *
>>> set_random_seed(Integer(1207))
>>> current_randstate().c_random()
2008037228

We verify the equivalence mentioned above.

Sage

sage: from sage.misc.randstate import random
sage: set_random_seed(1207)
sage: random()
2008037228

Python

>>> from sage.all import *
>>> from sage.misc.randstate import random
>>> set_random_seed(Integer(1207))
>>> random()
2008037228

long_seed()[source]¶

When called on the current randstate, returns a 128-bit Python long suitable for seeding another random number generator.

EXAMPLES:

Sage

sage: set_random_seed(1618)
sage: current_randstate().long_seed()
256056279774514099508607350947089272595

Python

>>> from sage.all import *
>>> set_random_seed(Integer(1618))
>>> current_randstate().long_seed()
256056279774514099508607350947089272595

python_random(cls=None, seed=None)[source]¶

Return a random.Random object. The first time it is called on a given randstate, a new random.Random is created (seeded from the current randstate); the same object is returned on subsequent calls.

It is expected that python_random will only be called on the current randstate.

INPUT:

cls – (optional) a class with the same interface as random.Random (e.g. a subclass thereof) to use as the Python RNG interface. Otherwise the standard random.Random is used.
seed – (optional) an integer to seed the random.Random instance with upon creation; if not specified it is seeded using ZZ.random_element(1 << 128).

EXAMPLES:

Sage

sage: set_random_seed(5)
sage: rnd = current_randstate().python_random()
sage: rnd.random()
0.013558022446944151
sage: rnd.randrange(1000)
544

Python

>>> from sage.all import *
>>> set_random_seed(Integer(5))
>>> rnd = current_randstate().python_random()
>>> rnd.random()
0.013558022446944151
>>> rnd.randrange(Integer(1000))
544

seed()[source]¶

Return the initial seed of a randstate object. (This is not the current state; it does not change when you get random numbers.)

EXAMPLES:

Sage

sage: set_random_seed(0)
sage: from sage.misc.randstate import randstate
sage: r = randstate(314159)
sage: r.seed()
314159
sage: r.python_random().random()
0.111439293741037
sage: r.seed()
314159

Python

>>> from sage.all import *
>>> set_random_seed(Integer(0))
>>> from sage.misc.randstate import randstate
>>> r = randstate(Integer(314159))
>>> r.seed()
314159
>>> r.python_random().random()
0.111439293741037
>>> r.seed()
314159

set_seed_gap()[source]¶

Check to see if self was the most recent randstate to seed the GAP random number generator. If not, seeds the generator.

EXAMPLES:

Sage

sage: set_random_seed(99900000999)
sage: current_randstate().set_seed_gap()
sage: gap.Random(1, 10^50)
1496738263332555434474532297768680634540939580077
sage: gap(35).SCRRandomString()
[ 1, 0, 1, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 1, 0, 1, 0, 1, 1,
  1, 0, 0, 1, 1, 1, 1, 1, 0, 1 ]

Python

>>> from sage.all import *
>>> set_random_seed(Integer(99900000999))
>>> current_randstate().set_seed_gap()
>>> gap.Random(Integer(1), Integer(10)**Integer(50))
1496738263332555434474532297768680634540939580077
>>> gap(Integer(35)).SCRRandomString()
[ 1, 0, 1, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 1, 0, 1, 0, 1, 1,
  1, 0, 0, 1, 1, 1, 1, 1, 0, 1 ]

set_seed_gp(gp=None)[source]¶

Check to see if self was the most recent randstate to seed the random number generator in the given instance of gp. (If no instance is given, uses the one in gp.) If not, seeds the generator.

EXAMPLES:

Sage

sage: set_random_seed(987654321)
sage: current_randstate().set_seed_gp()
sage: gp.random()
23289294

Python

>>> from sage.all import *
>>> set_random_seed(Integer(987654321))
>>> current_randstate().set_seed_gp()
>>> gp.random()
23289294

set_seed_libc(force)[source]¶

Check to see if self was the most recent randstate to seed the libc random number generator. If not, seeds the libc random number generator. (Do not use the libc random number generator if you have a choice; its randomness is poor, and the random number sequences it produces are not portable across operating systems.)

If the argument force is True, seeds the generator unconditionally.

EXAMPLES:

Sage

sage: from sage.misc.randstate import _doctest_libc_random
sage: set_random_seed(0xBAD)
sage: current_randstate().set_seed_libc(False)
sage: _doctest_libc_random()   # random
1070075918

Python

>>> from sage.all import *
>>> from sage.misc.randstate import _doctest_libc_random
>>> set_random_seed(Integer(0xBAD))
>>> current_randstate().set_seed_libc(False)
>>> _doctest_libc_random()   # random
1070075918

set_seed_ntl(force)[source]¶

Check to see if self was the most recent randstate to seed the NTL random number generator. If not, seeds the generator. If the argument force is True, seeds the generator unconditionally.

EXAMPLES:

Sage

sage: set_random_seed(2008)

Python

>>> from sage.all import *
>>> set_random_seed(Integer(2008))

This call is actually redundant; ntl.ZZ_random() will seed the generator itself. However, we put the call in to make the coverage tester happy.

Sage

sage: current_randstate().set_seed_ntl(False)
sage: ntl.ZZ_random(10^40)
1495283511775355459459209288047895196007

Python

>>> from sage.all import *
>>> current_randstate().set_seed_ntl(False)
>>> ntl.ZZ_random(Integer(10)**Integer(40))
1495283511775355459459209288047895196007

set_seed_pari()[source]¶

Check to see if self was the most recent randstate to seed the Pari random number generator. If not, seeds the generator.

Note

Since pari 2.4.3, pari’s random number generator has changed a lot. the seed output by getrand() is now a vector of integers.

EXAMPLES:

Sage

sage: set_random_seed(5551212)
sage: current_randstate().set_seed_pari()
sage: pari.getrand().type()
't_INT'

Python

>>> from sage.all import *
>>> set_random_seed(Integer(5551212))
>>> current_randstate().set_seed_pari()
>>> pari.getrand().type()
't_INT'

sage.misc.randstate.seed[source]¶: alias of randstate

sage.misc.randstate.set_random_seed(seed=None)[source]¶

Set the current random number seed from the given seed (which must be coercible to a Python long).

If no seed is given, then a seed is automatically selected using os.urandom() if it is available, or the current time otherwise.

Type sage.misc.randstate? for much more information on random numbers in Sage.

This function is only intended for command line use. Never call this from library code; instead, use with seed(s):.

Note that setting the random number seed to 0 is much faster than using any other number.

EXAMPLES:

Sage

sage: set_random_seed(5)
sage: initial_seed()
5

Python

>>> from sage.all import *
>>> set_random_seed(Integer(5))
>>> initial_seed()
5

Random Number States¶

Command line oriented API¶

Library API¶

Generating random numbers in library code¶

Classes and methods¶