README
¶
randx
Package randx provides randomization functionality built on top of standard math/rand
random number generation functions. Includes:
- RandParams: 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 RandParams 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 randx provides randomization functionality built on top of standard math/rand random number generation functions.
randx.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.
randx.StdRand implements the interface.
- RandParams: 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 ¶
- func BetaGen(alpha, beta float64, randOpt ...Rand) float64
- func BinomialGen(n, p float64, randOpt ...Rand) float64
- func BoolP(p float64, randOpt ...Rand) bool
- func BoolP32(p float32, randOpt ...Rand) bool
- func GammaGen(alpha, beta float64, randOpt ...Rand) float64
- func GaussianGen(mean, sigma float64, randOpt ...Rand) float64
- func IntMeanRange(mean, rnge int64, randOpt ...Rand) int64
- func IntMinMax(min, max int64, randOpt ...Rand) int64
- func IntZeroN(n int64, randOpt ...Rand) int64
- func PChoose32(ps []float32, randOpt ...Rand) int
- func PChoose64(ps []float64, randOpt ...Rand) int
- func PermuteFloat32s(ins []float32, randOpt ...Rand)
- func PermuteFloat64s(ins []float64, randOpt ...Rand)
- func PermuteInts(ins []int, randOpt ...Rand)
- func PermuteStrings(ins []string, randOpt ...Rand)
- func PoissonGen(lambda float64, randOpt ...Rand) float64
- func SequentialInts(ins []int, start int)
- func UniformMeanRange(mean, rnge float64, randOpt ...Rand) float64
- func UniformMinMax(min, max float64, randOpt ...Rand) float64
- func ZeroOne(randOpt ...Rand) float64
- type Rand
- type RandDists
- func (i RandDists) Desc() string
- func (i RandDists) Int64() int64
- func (i RandDists) MarshalText() ([]byte, error)
- func (i *RandDists) SetInt64(in int64)
- func (i *RandDists) SetString(s string) error
- func (i RandDists) String() string
- func (i *RandDists) UnmarshalText(text []byte) error
- func (i RandDists) Values() []enums.Enum
- type RandParams
- type Seeds
- type SysRand
- func (r *SysRand) ExpFloat64() float64
- func (r *SysRand) Float32() float32
- func (r *SysRand) Float64() float64
- func (r *SysRand) Int() int
- func (r *SysRand) Int31() int32
- func (r *SysRand) Int31n(n int32) int32
- func (r *SysRand) Int63() int64
- func (r *SysRand) Int63n(n int64) int64
- func (r *SysRand) Intn(n int) int
- func (r *SysRand) NewRand(seed int64)
- func (r *SysRand) NormFloat64() float64
- func (r *SysRand) Perm(n int) []int
- func (r *SysRand) Seed(seed int64)
- func (r *SysRand) Shuffle(n int, swap func(i, j int))
- func (r *SysRand) Uint32() uint32
- func (r *SysRand) Uint64() uint64
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BetaGen ¶
BetaGen returns beta random number with two shape parameters alpha > 0 and beta > 0 Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func BinomialGen ¶
note: this file contains random distribution functions from gonum.org/v1/gonum/stat/distuv which we modified only to use the randx.Rand interface. BinomialGen returns binomial with n trials (par) each of probability p (var) Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func BoolP ¶
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. Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func BoolP32 ¶
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. Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func GammaGen ¶
GammaGen represents maximum entropy distribution with two parameters: a shape parameter (Alpha, Par in RandParams), and a scaling parameter (Beta, Var in RandParams). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func GaussianGen ¶
GaussianGen returns gaussian (normal) random number with given mean and sigma standard deviation. Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func IntMeanRange ¶
Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func IntMinMax ¶
Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func IntZeroN ¶
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 ¶
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). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func PChoose64 ¶
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) Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func PermuteFloat32s ¶
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 ¶
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 ¶
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 ¶
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 ¶
PoissonGen returns poisson variable, as number of events in interval, with event rate (lmb = Var) plus mean Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func SequentialInts ¶
SequentialInts initializes slice of ints to sequential start..start+N-1 numbers -- for cases where permuting the order is optional.
func UniformMeanRange ¶
Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.
func UniformMinMax ¶
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() int64
// Uint32 returns a pseudo-random 32-bit value as a uint32.
Uint32() uint32
// Uint64 returns a pseudo-random 64-bit value as a uint64.
Uint64() uint64
// Int31 returns a non-negative pseudo-random 31-bit integer as an int32.
Int31() int32
// Int returns a non-negative pseudo-random int.
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) 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) 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) int
// Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0).
Float64() float64
// Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0).
Float32() 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() 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() 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) []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, 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.
type RandDists ¶
type RandDists int32 //enums:enum
RandDists are different random number distributions
const ( // Uniform has a uniform probability distribution over Var = range on either side of the Mean Uniform RandDists = 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 RandDistsN RandDists = 7
RandDistsN is the highest valid value for type RandDists, plus one.
func RandDistsValues ¶
func RandDistsValues() []RandDists
RandDistsValues returns all possible values for the type RandDists.
func (RandDists) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface.
func (*RandDists) SetString ¶
SetString sets the RandDists value from its string representation, and returns an error if the string is invalid.
func (*RandDists) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface.
type RandParams ¶
type RandParams struct {
// distribution to generate random numbers from
Dist RandDists
// 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 RandDists)
Var float64
// extra parameter for distribution (depends on each one)
Par float64 `view:"if Dist=Gamma,Binomial,Beta"`
}
RandParams provides parameterized random number generation according to different distributions and variance, mean params
func (*RandParams) Defaults ¶
func (rp *RandParams) Defaults()
func (*RandParams) Gen ¶
func (rp *RandParams) Gen(randOpt ...Rand) float64
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 ¶
Init allocates given number of seeds and initializes them to sequential numbers 1..n
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 randx.Rand interface, with the system global rand source.
func NewSysRand ¶
NewSysRand returns a new SysRand with a new rand.Rand random source with given initial seed.
func (*SysRand) ExpFloat64 ¶
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 ¶
Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0).
func (*SysRand) Float64 ¶
Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0).
func (*SysRand) Int31n ¶
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) Int63n ¶
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 ¶
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) NormFloat64 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files
Directories