Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

GwyRandGenSet (HEAD)

GwyRandGenSet — Set of random number generators

Functions

GwyRandGenSet * gwy_rand_gen_set_new ()
void gwy_rand_gen_set_init ()
void gwy_rand_gen_set_free ()
GRand * gwy_rand_gen_set_rng ()
gdouble gwy_rand_gen_set_range ()
gdouble gwy_rand_gen_set_uniform ()
gdouble gwy_rand_gen_set_gaussian ()
gdouble gwy_rand_gen_set_exponential ()
gdouble gwy_rand_gen_set_triangular ()
gdouble gwy_rand_gen_set_multiplier ()
gdouble gwy_rand_gen_set_double ()
guint32 gwy_rand_gen_set_int ()
guint * gwy_rand_gen_set_choose_shuffle ()
void gwy_rand_gen_set_fill_doubles ()
void gwy_rand_gen_set_fill_ints ()

Types and Values

  GwyRandGenSet

Includes

#include <libgwyddion/gwyddion.h>

Description

GwyRandGenSet represents a set of pseudoradnom number generators initialised together, but each producing a different sequence of numbers. This is useful when you use pseudorandom number generators to optionally randomize several different things. Using a common generator would require always generating exactly the same number of random numbers, even for quantities you do not want randomized, in order to keep the random number sequences stable.

GwyRandGenSet also provides functions sample a few common distributions such as Gaussian or exponential. It should be noted that the individual sampling functions may advance the generator state differently. This means

1
2
x = gwy_rand_gen_set_gaussian(rngset, 0, 1.0);
y = gwy_rand_gen_set_gaussian(rngset, 0, 1.0);

may produce a different value of y than

1
2
x = gwy_rand_gen_set_exponential(rngset, 0, 1.0);
y = gwy_rand_gen_set_gaussian(rngset, 0, 1.0);

even if the initial generator state was the same.

Functions

gwy_rand_gen_set_new ()

GwyRandGenSet *
gwy_rand_gen_set_new (guint n);

Creates a new set of pseudorandom number generators.

The generators are initialised to random states.

Parameters

n

The number of generators.

 

Returns

A new set of pseudorandom number generators.

Since: 2.37

gwy_rand_gen_set_init ()

void
gwy_rand_gen_set_init (GwyRandGenSet *rngset,
                       guint seed);

Initialises a set of pseudorandom number generators using an integer seed.

Parameters

rngset

A set of pseudorandom number generators.

 

seed

The seed used to initialise the generators.

 

Since: 2.37

gwy_rand_gen_set_free ()

void
gwy_rand_gen_set_free (GwyRandGenSet *rngset);

Destroys a set of pseudorandom number generators.

If you obtained individual generators using gwy_rand_gen_set_rng() you may not use them any more after calling this function.

Parameters

rngset

A set of pseudorandom number generators.

 

Since: 2.37

gwy_rand_gen_set_rng ()

GRand *
gwy_rand_gen_set_rng (GwyRandGenSet *rngset,
                      guint i);

Obtains a single generator from a set of pseudorandom number generators.

The generator can be used to produce random numbers in any way for which you find the provided methods insufficient. However, if you reseed it manually, number sequence stability will be broken because sampling functions may keep persistent information between calls.

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

Returns

A pseudorandom number generator from rngset .

Since: 2.37

gwy_rand_gen_set_range ()

gdouble
gwy_rand_gen_set_range (GwyRandGenSet *rngset,
                        guint i,
                        gdouble lower,
                        gdouble upper);

Samples from a uniform distribution over given interval using one generator from a pseudorandom number generator set.

The generated number always lies inside the interval, neither endpoint value is ever returned. Note if there are no representable real numbers between lower and upper this function will never terminate. You must ensure upper is sufficiently larger than lower .

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

lower

Lower limit of the range.

 

upper

Upper limit of the range.

 

Returns

A pseudorandom number.

Since: 2.37

gwy_rand_gen_set_uniform ()

gdouble
gwy_rand_gen_set_uniform (GwyRandGenSet *rngset,
                          guint i,
                          gdouble sigma);

Samples from a centered uniform distribution using one generator from a pseudorandom number generator set.

The mean value of the distribution is zero, the rms value is given by sigma .

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

sigma

Rms of the distribution.

 

Returns

A pseudorandom number.

Since: 2.37

gwy_rand_gen_set_gaussian ()

gdouble
gwy_rand_gen_set_gaussian (GwyRandGenSet *rngset,
                           guint i,
                           gdouble sigma);

Samples from a centered Gaussian distribution using one generator from a pseudorandom number generator set.

The mean value of the distribution is zero, the rms value is given by sigma .

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

sigma

Rms of the distribution.

 

Returns

A pseudorandom number.

Since: 2.37

gwy_rand_gen_set_exponential ()

gdouble
gwy_rand_gen_set_exponential (GwyRandGenSet *rngset,
                              guint i,
                              gdouble sigma);

Samples from a centered exponential distribution using one generator from a pseudorandom number generator set.

The mean value of the distribution is zero, the rms value is given by sigma .

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

sigma

Rms of the distribution.

 

Returns

A pseudorandom number.

Since: 2.37

gwy_rand_gen_set_triangular ()

gdouble
gwy_rand_gen_set_triangular (GwyRandGenSet *rngset,
                             guint i,
                             gdouble sigma);

Samples from a centered triangular distribution using one generator from a pseudorandom number generator set.

The mean value of the distribution is zero, the rms value is given by sigma .

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

sigma

Rms of the distribution.

 

Returns

A pseudorandom number.

Since: 2.37

gwy_rand_gen_set_multiplier ()

gdouble
gwy_rand_gen_set_multiplier (GwyRandGenSet *rngset,
                             guint i,
                             gdouble range);

Samples from a multiplier distribution using one generator from a pseudorandom number generator set.

The multiplier distribution is triangular distribution centered at 1, with values from [1-range , 1+range ].

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

range

Half-range of the distribution.

 

Returns

A pseudorandom number.

Since: 2.37

gwy_rand_gen_set_double ()

gdouble
gwy_rand_gen_set_double (GwyRandGenSet *rngset,
                         guint i);

Samples uniform distribution over [0,1) using one generator from a pseudorandom number generator set.

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

Returns

A pseudorandom number.

Since: 2.37

gwy_rand_gen_set_int ()

guint32
gwy_rand_gen_set_int (GwyRandGenSet *rngset,
                      guint i);

Samples a 32bit integer using a generator from a pseudorandom number generator set.

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

Returns

A pseudorandom number.

Since: 2.37

gwy_rand_gen_set_choose_shuffle ()

guint *
gwy_rand_gen_set_choose_shuffle (GwyRandGenSet *rngset,
                                 guint i,
                                 guint n,
                                 guint nchoose);

Chooses randomly a subset of indices, in random order.

The function creates an array containing integers from the set {0, 1, 2, ..., n-1}, each at most once, in random order.

To generate a permutation, simply pass nchoose equal to n .

Parameters

rngset

A set of pseudorandom number generators.

 

i

Index of a generator from the set.

 

n

Total number of possible indices.

 

nchoose

Number of values to choose (at most equal to n ). It is permitted to pass zero; the function returns NULL then.

 

Returns

A newly allocated array of nchoose integers.

Since: 2.46

gwy_rand_gen_set_fill_doubles ()

void
gwy_rand_gen_set_fill_doubles (GwyRandGenSet *rngset,
                               gdouble *random_numbers,
                               gint n);

Fill an array with random doubles from a pseudorandom number generator set

If rngset has N generators then the array is split into N equally sized blocks (at least approximately) and each block is filled from a different generator. The filling of individual blocks is run multi-threaded (if parallelisation is enabled). The result does not depend on the number of threads, allowing parallelisation of random number generation.

Note that the number of generators N must be a fixed constant for reproducible results. It must not depend on the actual number of processor cores or a similar variable quantity.

Parameters

rngset

A set of pseudorandom number generators.

 

random_numbers

Array to be filled with random numbers.

 

n

How many numbers to generated.

 

Since: 2.59

gwy_rand_gen_set_fill_ints ()

void
gwy_rand_gen_set_fill_ints (GwyRandGenSet *rngset,
                            guint32 *random_numbers,
                            gint n);

Fill an array with random integers from a pseudorandom number generator set

See gwy_rand_gen_set_fill_doubles() for discussion and caveats.

Parameters

rngset

A set of pseudorandom number generators.

 

random_numbers

Array to be filled with random numbers.

 

n

How many numbers to generated.

 

Since: 2.59

Types and Values

GwyRandGenSet

typedef struct _GwyRandGenSet GwyRandGenSet;

GwyRandGenSet is an opaque data structure and should be only manipulated with the functions below.

Since: 2.37

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS