randx

package
v0.3.3 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2024 License: BSD-3-Clause Imports: 5 Imported by: 34

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func BetaGen 

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

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 

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

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 

func BoolP(p float64, 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. Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func BoolP32 

func BoolP32(p float32, 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. Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func GammaGen 

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

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 

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

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 

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

Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func IntMinMax 

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

Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func IntZeroN 

func IntZeroN(n int64, 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, 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). Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func PChoose64 

func PChoose64(ps []float64, 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) 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, randOpt ...Rand) float64

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 

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, randOpt ...Rand) float64

Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func UniformMinMax 

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

Optionally can pass a single Rand interface to use -- otherwise uses system global Rand source.

func ZeroOne 

func ZeroOne(randOpt ...Rand) float64

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) Desc 

func (i RandDists) Desc() string

Desc returns the description of the RandDists value.

func (RandDists) Int64 

func (i RandDists) Int64() int64

Int64 returns the RandDists value as an int64.

func (RandDists) MarshalText 

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

MarshalText implements the encoding.TextMarshaler interface.

func (*RandDists) SetInt64 

func (i *RandDists) SetInt64(in int64)

SetInt64 sets the RandDists value from an int64.

func (*RandDists) SetString 

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

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

func (RandDists) String 

func (i RandDists) String() string

String returns the string representation of this RandDists value.

func (*RandDists) UnmarshalText 

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

UnmarshalText implements the encoding.TextUnmarshaler interface.

func (RandDists) Values 

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

Values returns all possible values for the type RandDists.

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
}

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.

func (*RandParams) ShouldDisplay added in v0.2.1 

func (rp *RandParams) ShouldDisplay(field string) bool

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 `display:"-"`
}

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 

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() 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() 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() 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() int

Int returns a non-negative pseudo-random int.

func (*SysRand) Int31 

func (r *SysRand) Int31() int32

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

func (*SysRand) Int31n 

func (r *SysRand) Int31n(n int32) 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() int64

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

func (*SysRand) Int63n 

func (r *SysRand) Int63n(n int64) 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) 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() 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) []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, 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() uint32

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

func (*SysRand) Uint64 

func (r *SysRand) Uint64() uint64

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

Source Files

View all Source files

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.