draco.util.random

Utilities for drawing random numbers.

Functions

complex_normal([loc, scale, size, dtype, ...])

Get a set of complex normal variables.

complex_wishart(C, n[, rng])

Draw a complex Wishart matrix.

default_rng()

Returns an instance of the default random number generator to use.

mpi_random_seed(seed[, extra, gen])

Use a specific random seed and return to the original state on exit.

standard_complex_normal(shape[, dtype, rng])

Get a set of standard complex normal variables.

standard_complex_wishart(m, n[, rng])

Draw a standard Wishart matrix.

Classes

MultithreadedRNG([seed, threads, bitgen])

A multithreaded random number generator.

RandomTask()

A base class for MPI tasks that need to generate random numbers.
class draco.util.random.MultithreadedRNG(seed: int | None = None, threads: int | None = None, bitgen: BitGenerator | None = None)[source]

Bases: Generator

A multithreaded random number generator.

This wraps specific methods to allow generation across multiple threads. See PARALLEL_METHODS for the specific methods wrapped.

Parameters:

  • seed – The seed to use.

  • nthreads – The number of threads to use. If not set, this tries to get the number from the OMP_NUM_THREADS environment variable, or just uses 4 if that is also not set.

  • bitgen – The BitGenerator to use, if not set this uses _default_bitgen.

class draco.util.random.RandomTask[source]

Bases: MPILoggedTask

A base class for MPI tasks that need to generate random numbers.

seed

Set the seed for use in the task. If not set, a random seed is generated and broadcast to all ranks. The seed being used is logged, to repeat a previous run, simply set this as the seed parameter.

Type:

int, optional

threads

Set the number of threads to use for the random number generator. If not explicitly set this will use the value of the OMP_NUM_THREADS environment variable, or fall back to four.

Type:

int, optional

Initialize pipeline task.

May be overridden with no arguments. Will be called after any config.Property attributes are set and after ‘input’ and ‘requires’ keys are set up.

property local_seed: int

Get the seed to be used on this rank.

Warning

Generating the seed is a collective operation if the seed is not set, and so all ranks must participate in the first access of this property.

property rng: Generator

A random number generator for this task.

Warning

Initialising the RNG is a collective operation if the seed is not set, and so all ranks must participate in the first access of this property.

Returns:

rng – A deterministically seeded random number generator suitable for use in MPI jobs.

Return type:

np.random.Generator

draco.util.random.complex_normal(loc=0.0, scale=1.0, size=None, dtype=None, rng=None, out=None)[source]

Get a set of complex normal variables.

By default generate standard complex normal variables.

Parameters:

  • size (tuple) – Shape of the array of variables.

  • loc (np.ndarray or complex float, optional) – The mean of the complex output. Can be any array which broadcasts against an array of size.

  • scale (np.ndarray or float, optional) – The standard deviation of the complex output. Can be any array which broadcasts against an array of size.

  • dtype ({np.complex64, np.complex128}, optional) – Output datatype.

  • rng (np.random.Generator, optional) – Generator object to use.

  • out (np.ndarray[shape], optional) – Array to place output directly into.

Returns:

out – Complex gaussian variates.

Return type:

np.ndarray[shape]

draco.util.random.complex_wishart(C, n, rng=None)[source]

Draw a complex Wishart matrix.

Parameters:

  • C (np.ndarray[:, :]) – Expected covaraince matrix.

  • n (integer) – Number of measurements the covariance matrix is estimated from.

  • rng (np.random.Generator, optional) – Random number generator to use.

Returns:

C_samp – Sample covariance matrix.

Return type:

np.ndarray

draco.util.random.default_rng()[source]

Returns an instance of the default random number generator to use.

This creates a randomly seeded generator using the fast SFC64 bit generator underneath. This is only initialise on the first call, subsequent calls will return the same Generator.

Returns:

rng

Return type:

np.random.Generator

draco.util.random.mpi_random_seed(seed, extra=0, gen=None)[source]

Use a specific random seed and return to the original state on exit.

This is designed to work for MPI computations, incrementing the actual seed of each process by the MPI rank. Overall each process gets the numpy seed: numpy_seed = seed + mpi_rank + 4096 * extra. This can work for either the global numpy.random context or for new np.random.Generator.

Parameters:

  • seed (int) – Base seed to set. If seed is None, re-seed randomly.

  • extra (int, optional) – An extra part of the seed, which should be changed for calculations using the same seed, but that want different random sequences.

  • gen – A RandomGen bit_generator whose internal seed state we are going to influence.

Yields:

  • If we are setting the numpy.random context, nothing is yielded.

  • class: Generator – If we are setting the RandomGen bit_generator, it will be returned.

draco.util.random.standard_complex_normal(shape, dtype=None, rng=None)[source]

Get a set of standard complex normal variables.

Parameters:

  • shape (tuple) – Shape of the array of variables.

  • dtype ({np.complex64, np.complex128}, optional) – Output datatype.

  • rng (np.random.Generator, optional) – Generator object to use.

Returns:

out – Complex gaussian variates.

Return type:

np.ndarray[shape]

draco.util.random.standard_complex_wishart(m, n, rng=None)[source]

Draw a standard Wishart matrix.

Parameters:

  • m (integer) – Number of variables (i.e. size of matrix).

  • n (integer) – Number of measurements the covariance matrix is estimated from.

  • rng (np.random.Generator, optional) – Random number generator to use.

Returns:

B

Return type:

np.ndarray[m, m]