Randomness¶
Random Number Generators (RNGs) are often used when generating, drawing
and computing properties or manipulating networks. NetworkX provides
functions which use one of two standard RNGs: NumPy’s package numpy.random
or Python’s built-in package random. They each provide the same
algorithm for generating numbers (Mersenne Twister). Their interfaces
are similar (dangerously similar) and yet distinct.
They each provide a global default instance of their generator that
is shared by all programs in a single session.
For the most part you can use the RNGs as NetworkX has them set up and
you’ll get reasonable pseudorandom results (results that are statistically
random, but created in a deterministic manner).
Sometimes you want more control over how the numbers are generated.
In particular, you need to set the seed of the generator to make
your results reproducible – either for scientific publication or
for debugging. Both RNG packages have easy functions to set the seed
to any integer, thus determining the subsequent generated values.
Since this package (and many others) use both RNGs you may need to
set the seed of both RNGs. Even if we strictly only used one of the
RNGs, you may find yourself using another package that uses the other.
Setting the state of the two global RNGs is as simple setting the
seed of each RNG to an arbitrary integer:
>>> import random
>>> random.seed(246) # or any integer
>>> import numpy
>>> numpy.random.seed(4812)
Many users will be satisfied with this level of control.
For people who want even more control, we include an optional argument
to functions that use an RNG. This argument is called seed, but
determines more than the seed of the RNG. It tells the function which
RNG package to use, and whether to use a global or local RNG.
>>> from networkx import path_graph, random_layout
>>> G = path_graph(9)
>>> pos = random_layout(G, seed=None) # use (either) global default RNG
>>> pos = random_layout(G, seed=42) # local RNG just for this call
>>> pos = random_layout(G, seed=numpy.random) # use numpy global RNG
>>> random_state = numpy.random.RandomState(42)
>>> pos = random_layout(G, seed=random_state) # use/reuse your own RNG
Each NetworkX function that uses an RNG was written with one RNG package
in mind. It either uses random or numpy.random by default.
But some users want to only use a single RNG for all their code.
This seed argument provides a mechanism so that any function
can use a numpy.random RNG even if the function is written for random.
It works as follows.
The default behavior (when seed=None) is to use the global RNG
for the function’s preferred package.
If seed is set to an integer value,
a local RNG is created with the indicated seed value and
is used for the duration of that function (including any
calls to other functions) and then discarded.
Alternatively, you can specify seed=numpy.random to ensure that
the global numpy RNG is used whether the function expects it or not.
Finally, you can provide a numpy RNG to be used by the function.
The RNG is then available to use in other functions or even other
package like sklearn.
In this way you can use a single RNG for all random numbers
in your project.
While it is possible to assign seed a random-style RNG for
NetworkX functions written for the random package API,
the numpy RNG interface has too
many nice features for us to ensure a random-style RNG will work in
all functions. In practice, you can do most things using only random
RNGs (useful if numpy is not available). But your experience will be
richer if numpy is available.
To summarize, you can easily ignore the seed argument and use the global
RNGs. You can specify to use only the numpy global RNG with
seed=numpy.random. You can use a local RNG by providing an integer
seed value. And you can provide your own numpy RNG, reusing it for all
functions. It is easier to use numpy RNGs if you want a single RNG for
your computations.