erand

package
v2.0.0-dev0.0.13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 20, 2024 License: BSD-3-Clause Imports: 5 Imported by: 0

README

Docs: GoDoc

Package erand provides randomization functionality built on top of standard math/rand random number generation functions. Includes:

  • RndParams: specifies parameters for random number generation according to various distributions used e.g., for initializing random weights and generating random noise in neurons
  • Permute*: basic convenience methods calling rand.Shuffle on e.g., []int slice

Here are the distributions and how the parameters in RndParams map onto distributional parameters -- the Mean and Var are not the actual mean and variance of the distribution, but rather provide parameters roughly corresponding to these values, along with the extra Par value:

	// Binomial represents number of 1's in n (Par) random (Bernouli) trials of probability p (Var)
	Binomial

	// Poisson represents number of events in interval, with event rate (lambda = Var) plus Mean
	Poisson

	// Gamma represents maximum entropy distribution with two parameters: scaling parameter (Var)
	// and shape parameter k (Par) plus Mean
	Gamma

	// Gaussian normal with Var = stddev plus Mean
	Gaussian

	// Beta with Var = alpha and Par = beta shape parameters
	Beta

	// Mean is just the constant Mean, no randomness
	Mean

See distplot for a program to plot the histograms of these different distributions as you vary the parameters.

Documentation

Overview

Package erand provides randomization functionality built on top of standard math/rand random number generation functions.

erand.Rand is an interface that enables calling the standard global rand functions, or a rand.Rand separate source, and is used for all methods in this package. Methods also take a thr thread arg to support a random generator that handles separate threads, such as gosl/slrand.

erand.StdRand implements the interface.

  • RndParams: specifies parameters for random number generation according to various distributions, used e.g., for initializing random weights and generating random noise in neurons

- Permute*: basic convenience methods calling rand.Shuffle on e.g., []int slice

- BoolP: boolean for given probability

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BetaGen 

func BetaGen(alpha, beta float64, thr int, randOpt ...Rand) float64

BetaGen returns beta random number with two shape parameters alpha > 0 and beta > 0 Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func BinomialGen 

func BinomialGen(n, p float64, thr int, randOpt ...Rand) float64

BinomialGen returns binomial with n trials (par) each of probability p (var) Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func BoolP 

func BoolP(p float64, thr int, randOpt ...Rand) bool

BoolP is a simple method to generate a true value with given probability (else false). It is just rand.Float64() < p but this is more readable and explicit. Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func BoolP32 

func BoolP32(p float32, thr int, randOpt ...Rand) bool

BoolP32 is a simple method to generate a true value with given probability (else false). It is just rand.Float32() < p but this is more readable and explicit. Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func GammaGen 

func GammaGen(alpha, beta float64, thr int, randOpt ...Rand) float64

GammaGen represents maximum entropy distribution with two parameters: a shape parameter (Alpha, Par in RndParams), and a scaling parameter (Beta, Var in RndParams). Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func GaussianGen 

func GaussianGen(mean, sigma float64, thr int, randOpt ...Rand) float64

GaussianGen returns gaussian (normal) random number with given mean and sigma standard deviation. Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func IntMeanRange 

func IntMeanRange(mean, rnge int64, thr int, randOpt ...Rand) int64

IntMeanRange returns uniform random integer with given range on either side of the mean: [mean - range, mean + range] Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func IntMinMax 

func IntMinMax(min, max int64, thr int, randOpt ...Rand) int64

IntMinMax returns uniform random integer in range between min and max, exclusive of max: [min,max). Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func IntZeroN 

func IntZeroN(n int64, thr int, randOpt ...Rand) int64

IntZeroN returns uniform random integer in the range between 0 and n, exclusive of n: [0,n). Thr is an optional parallel thread index (-1 0 to ignore). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func PChoose32 

func PChoose32(ps []float32, thr int, randOpt ...Rand) int

PChoose32 chooses an index in given slice of float32's at random according to the probilities of each item (must be normalized to sum to 1). Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func PChoose64 

func PChoose64(ps []float64, thr int, randOpt ...Rand) int

PChoose64 chooses an index in given slice of float64's at random according to the probilities of each item (must be normalized to sum to 1) Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func PermuteFloat32s 

func PermuteFloat32s(ins []float32, randOpt ...Rand)

PermuteFloat32s permutes (shuffles) the order of elements in the given float32 slice using the standard Fisher-Yates shuffle https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle So you don't have to remember how to call rand.Shuffle Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func PermuteFloat64s 

func PermuteFloat64s(ins []float64, randOpt ...Rand)

PermuteFloat64s permutes (shuffles) the order of elements in the given float64 slice using the standard Fisher-Yates shuffle https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle So you don't have to remember how to call rand.Shuffle Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func PermuteInts 

func PermuteInts(ins []int, randOpt ...Rand)

PermuteInts permutes (shuffles) the order of elements in the given int slice using the standard Fisher-Yates shuffle https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle So you don't have to remember how to call rand.Shuffle. Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func PermuteStrings 

func PermuteStrings(ins []string, randOpt ...Rand)

PermuteStrings permutes (shuffles) the order of elements in the given string slice using the standard Fisher-Yates shuffle https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle So you don't have to remember how to call rand.Shuffle Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func PoissonGen 

func PoissonGen(lambda float64, thr int, randOpt ...Rand) float64

PoissonGen returns poisson variable, as number of events in interval, with event rate (lmb = Var) plus mean Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func SequentialInts 

func SequentialInts(ins []int, start int)

SequentialInts initializes slice of ints to sequential start..start+N-1 numbers -- for cases where permuting the order is optional.

func UniformMeanRange 

func UniformMeanRange(mean, rnge float64, thr int, randOpt ...Rand) float64

UniformMeanRange returns uniform random number with given range on either size of the mean: [mean - range, mean + range] Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func UniformMinMax 

func UniformMinMax(min, max float64, thr int, randOpt ...Rand) float64

UniformMinMax returns uniform random number between min and max values inclusive (Do not use for generating integers - will not include max!) Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func ZeroOne 

func ZeroOne(thr int, randOpt ...Rand) float64

ZeroOne returns a uniform random number between zero and one (exclusive of 1) Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

Types

type Rand 

type Rand interface {
	// Seed uses the provided seed value to initialize the generator to a deterministic state.
	// Seed should not be called concurrently with any other Rand method.
	Seed(seed int64)

	// Int63 returns a non-negative pseudo-random 63-bit integer as an int64.
	Int63(thr int) int64

	// Uint32 returns a pseudo-random 32-bit value as a uint32.
	Uint32(thr int) uint32

	// Uint64 returns a pseudo-random 64-bit value as a uint64.
	Uint64(thr int) uint64

	// Int31 returns a non-negative pseudo-random 31-bit integer as an int32.
	Int31(thr int) int32

	// Int returns a non-negative pseudo-random int.
	Int(thr int) int

	// Int63n returns, as an int64, a non-negative pseudo-random number in the half-open interval [0,n).
	// It panics if n <= 0.
	Int63n(n int64, thr int) int64

	// Int31n returns, as an int32, a non-negative pseudo-random number in the half-open interval [0,n).
	// It panics if n <= 0.
	Int31n(n int32, thr int) int32

	// Intn returns, as an int, a non-negative pseudo-random number in the half-open interval [0,n).
	// It panics if n <= 0.
	Intn(n int, thr int) int

	// Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0).
	Float64(thr int) float64

	// Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0).
	Float32(thr int) float32

	// NormFloat64 returns a normally distributed float64 in the range
	// [-math.MaxFloat64, +math.MaxFloat64] with
	// standard normal distribution (mean = 0, stddev = 1)
	// from the default Source.
	// To produce a different normal distribution, callers can
	// adjust the output using:
	//
	//	sample = NormFloat64() * desiredStdDev + desiredMean
	NormFloat64(thr int) float64

	// ExpFloat64 returns an exponentially distributed float64 in the range
	// (0, +math.MaxFloat64] with an exponential distribution whose rate parameter
	// (lambda) is 1 and whose mean is 1/lambda (1) from the default Source.
	// To produce a distribution with a different rate parameter,
	// callers can adjust the output using:
	//
	//	sample = ExpFloat64() / desiredRateParameter
	ExpFloat64(thr int) float64

	// Perm returns, as a slice of n ints, a pseudo-random permutation of the integers
	// in the half-open interval [0,n).
	Perm(n int, thr int) []int

	// Shuffle pseudo-randomizes the order of elements.
	// n is the number of elements. Shuffle panics if n < 0.
	// swap swaps the elements with indexes i and j.
	Shuffle(n int, thr int, swap func(i, j int))
}

Rand provides an interface with most of the standard rand.Rand methods, to support the use of either the global rand generator or a separate Rand source. All methods take an optional thr argument for the thread number in the parallel threaded case. The gosl.slrand generator for example supports this. If not used set to 0 or -1

type RndDists 

type RndDists int32 //enums:enum

RndDists are different random number distributions 

const (
	// Uniform has a uniform probability distribution over Var = range on either side of the Mean
	Uniform RndDists = iota

	// Binomial represents number of 1's in n (Par) random (Bernouli) trials of probability p (Var)
	Binomial

	// Poisson represents number of events in interval, with event rate (lambda = Var) plus Mean
	Poisson

	// Gamma represents maximum entropy distribution with two parameters: scaling parameter (Var)
	// and shape parameter k (Par) plus Mean
	Gamma

	// Gaussian normal with Var = stddev plus Mean
	Gaussian

	// Beta with Var = alpha and Par = beta shape parameters
	Beta

	// Mean is just the constant Mean, no randomness
	Mean
)

The random number distributions 

const RndDistsN RndDists = 7

RndDistsN is the highest valid value for type RndDists, plus one.

func RndDistsValues 

func RndDistsValues() []RndDists

RndDistsValues returns all possible values for the type RndDists.

func (RndDists) Desc 

func (i RndDists) Desc() string

Desc returns the description of the RndDists value.

func (RndDists) Int64 

func (i RndDists) Int64() int64

Int64 returns the RndDists value as an int64.

func (RndDists) MarshalText 

func (i RndDists) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (*RndDists) SetInt64 

func (i *RndDists) SetInt64(in int64)

SetInt64 sets the RndDists value from an int64.

func (*RndDists) SetString 

func (i *RndDists) SetString(s string) error

SetString sets the RndDists value from its string representation, and returns an error if the string is invalid.

func (RndDists) String 

func (i RndDists) String() string

String returns the string representation of this RndDists value.

func (*RndDists) UnmarshalText 

func (i *RndDists) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

func (RndDists) Values 

func (i RndDists) Values() []enums.Enum

Values returns all possible values for the type RndDists.

type RndParams 

type RndParams struct {

	// distribution to generate random numbers from
	Dist RndDists

	// mean of random distribution -- typically added to generated random variants
	Mean float64

	// variability parameter for the random numbers (gauss = standard deviation, not variance; uniform = half-range, others as noted in RndDists)
	Var float64

	// extra parameter for distribution (depends on each one)
	Par float64 `view:"if Dist=Gamma,Binomial,Beta"`
}

RndParams provides parameterized random number generation according to different distributions and variance, mean params

func (*RndParams) Defaults 

func (rp *RndParams) Defaults()

func (*RndParams) Gen 

func (rp *RndParams) Gen(thr int, randOpt ...Rand) float64

Gen generates a random variable according to current parameters. Thr is an optional parallel thread index (-1 for none). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

type Seeds 

type Seeds []int64

Seeds is a set of random seeds, typically used one per Run

func (*Seeds) Init 

func (rs *Seeds) Init(n int)

Init allocates given number of seeds and initializes them to sequential numbers 1..n

func (*Seeds) NewSeeds 

func (rs *Seeds) NewSeeds()

NewSeeds sets a new set of random seeds based on current time

func (*Seeds) Set 

func (rs *Seeds) Set(idx int, randOpt ...Rand)

Set sets the given seed to either the single Rand interface passed, or the system global Rand source.

type SysRand 

type SysRand struct {

	// if non-nil, use this random number source instead of the global default one
	Rand *rand.Rand `view:"-"`
}

SysRand supports the system random number generator for either a separate rand.Rand source, or, if that is nil, the global rand stream.

func NewGlobalRand 

func NewGlobalRand() *SysRand

NewGlobalRand returns a new SysRand that implements the erand.Rand interface, with the system global rand source.

func NewSysRand 

func NewSysRand(seed int64) *SysRand

NewSysRand returns a new SysRand with a new rand.Rand random source with given initial seed.

func (*SysRand) ExpFloat64 

func (r *SysRand) ExpFloat64(thr int) float64

ExpFloat64 returns an exponentially distributed float64 in the range (0, +math.MaxFloat64] with an exponential distribution whose rate parameter (lambda) is 1 and whose mean is 1/lambda (1) from the default Source. To produce a distribution with a different rate parameter, callers can adjust the output using: 

sample = ExpFloat64() / desiredRateParameter

func (*SysRand) Float32 

func (r *SysRand) Float32(thr int) float32

Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0).

func (*SysRand) Float64 

func (r *SysRand) Float64(thr int) float64

Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0).

func (*SysRand) Int 

func (r *SysRand) Int(thr int) int

Int returns a non-negative pseudo-random int.

func (*SysRand) Int31 

func (r *SysRand) Int31(thr int) int32

Int31 returns a non-negative pseudo-random 31-bit integer as an int32.

func (*SysRand) Int31n 

func (r *SysRand) Int31n(n int32, thr int) int32

Int31n returns, as an int32, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n <= 0.

func (*SysRand) Int63 

func (r *SysRand) Int63(thr int) int64

Int63 returns a non-negative pseudo-random 63-bit integer as an int64.

func (*SysRand) Int63n 

func (r *SysRand) Int63n(n int64, thr int) int64

Int63n returns, as an int64, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n <= 0.

func (*SysRand) Intn 

func (r *SysRand) Intn(n int, thr int) int

Intn returns, as an int, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n <= 0.

func (*SysRand) NewRand 

func (r *SysRand) NewRand(seed int64)

NewRand sets Rand to a new rand.Rand source using given seed.

func (*SysRand) NormFloat64 

func (r *SysRand) NormFloat64(thr int) float64

NormFloat64 returns a normally distributed float64 in the range [-math.MaxFloat64, +math.MaxFloat64] with standard normal distribution (mean = 0, stddev = 1) from the default Source. To produce a different normal distribution, callers can adjust the output using: 

sample = NormFloat64() * desiredStdDev + desiredMean

func (*SysRand) Perm 

func (r *SysRand) Perm(n int, thr int) []int

Perm returns, as a slice of n ints, a pseudo-random permutation of the integers in the half-open interval [0,n).

func (*SysRand) Seed 

func (r *SysRand) Seed(seed int64)

Seed uses the provided seed value to initialize the generator to a deterministic state. Seed should not be called concurrently with any other Rand method.

func (*SysRand) Shuffle 

func (r *SysRand) Shuffle(n int, thr int, swap func(i, j int))

Shuffle pseudo-randomizes the order of elements. n is the number of elements. Shuffle panics if n < 0. swap swaps the elements with indexes i and j.

func (*SysRand) Uint32 

func (r *SysRand) Uint32(thr int) uint32

Uint32 returns a pseudo-random 32-bit value as a uint32.

func (*SysRand) Uint64 

func (r *SysRand) Uint64(thr int) uint64

Uint64 returns a pseudo-random 64-bit value as a uint64.

Source Files

View all Source files

Directories

Path Synopsis
Command distsplot plots histograms of random distributions
 Command distsplot plots histograms of random distributions

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.