erand

package
v1.4.31 Latest Latest
Warning

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

 Go to latest Published: Sep 27, 2023 License: BSD-3-Clause Imports: 6 Imported by: 72

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

View Source 
var KiT_RndDists = kit.Enums.AddEnum(RndDistsN, kit.NotBitFlag, nil)

Functions

func BetaGen added in v1.3.48 

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 added in v1.3.48 

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 added in v1.0.0 

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 added in v1.3.48 

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 added in v1.3.48 

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 added in v1.3.48 

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 added in v1.0.0 

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 added in v1.0.0 

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 added in v1.4.31 

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 added in v1.4.31 

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 added in v1.3.48 

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 added in v1.4.31 

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 added in v1.3.48 

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 int

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

	RndDistsN
)

The random number distributions

func (*RndDists) FromString 

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

func (RndDists) MarshalJSON 

func (ev RndDists) MarshalJSON() ([]byte, error)

func (RndDists) String 

func (i RndDists) String() string

func (*RndDists) UnmarshalJSON 

func (ev *RndDists) UnmarshalJSON(b []byte) error

type RndParams 

type RndParams struct {

	// distribution to generate random numbers from
	Dist RndDists `desc:"distribution to generate random numbers from"`

	// mean of random distribution -- typically added to generated random variants
	Mean float64 `desc:"mean of random distribution -- typically added to generated random variants"`

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

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

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

func (*RndParams) Defaults added in v1.3.49 

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 added in v1.3.2 

type Seeds []int64

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

func (*Seeds) Init added in v1.3.2 

func (rs *Seeds) Init(n int)

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

func (*Seeds) NewSeeds added in v1.3.2 

func (rs *Seeds) NewSeeds()

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

func (*Seeds) Set added in v1.3.2 

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 added in v1.3.48 

type SysRand struct {

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

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 added in v1.3.48 

func NewGlobalRand() *SysRand

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

func NewSysRand added in v1.3.48 

func NewSysRand(seed int64) *SysRand

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

func (*SysRand) ExpFloat64 added in v1.3.48 

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 added in v1.3.48 

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 added in v1.3.48 

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 added in v1.3.48 

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

Int returns a non-negative pseudo-random int.

func (*SysRand) Int31 added in v1.3.48 

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

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

func (*SysRand) Int31n added in v1.3.48 

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 added in v1.3.48 

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

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

func (*SysRand) Int63n added in v1.3.48 

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 added in v1.3.48 

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 added in v1.3.48 

func (r *SysRand) NewRand(seed int64)

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

func (*SysRand) NormFloat64 added in v1.3.48 

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 added in v1.3.48 

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 added in v1.3.48 

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 added in v1.3.48 

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 added in v1.3.48 

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

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

func (*SysRand) Uint64 added in v1.3.48 

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
distsplot plots histograms of random distributions
 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.