% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rng.R
\name{randompack_rng}
\alias{randompack_rng}
\title{Create and Use Random Number Generators}
\usage{
randompack_rng(engine = "x256++simd", bitexact = FALSE, full_mantissa = FALSE)
}
\arguments{
\item{engine}{RNG engine}

\item{bitexact}{Logical; set TRUE to make samples bit-identical across platforms}

\item{full_mantissa}{Logical; set TRUE to use full mantissas for floating draws}
}
\value{
An RNG object with methods for drawing random variates.
}
\description{
To create a random number generator (RNG) object use \code{randompack_rng()},
and to specify the underlying RNG engine use \code{randompack_rng(engine)} where
\code{engine} is a character string naming the engine (see Available Engines
below).
}
\details{
Once created, the RNG object provides methods for drawing samples from
various distributions (e.g., \verb{$normal()}, \verb{$uniform()}, \verb{$int()}). The object
can be configured using configure methods (e.g., \verb{$seed()}, \verb{$randomize()}).
Multiple independent RNG objects can be used for parallel random number
generation across different processes or threads.
}
\section{Available Engines}{

\tabular{lll}{
\code{x256++simd} \tab\tab xorshift256++ with streams (default) \cr
\code{sfc64simd} \tab\tab sfc64 with streams \cr
\code{x256++} \tab\tab xoshiro256++ (Vigna and Blackman, 2018) \cr
\code{x256**} \tab\tab xoshiro256** (Vigna and Blackman, 2018) \cr
\code{x128+} \tab\tab xorshift128+ (Vigna, 2014) \cr
\code{xoro++} \tab\tab xoroshiro128++ (Vigna and Blackman, 2016) \cr
\code{pcg64} \tab\tab PCG64 DXSM (O'Neill, 2014) \cr
\code{sfc64} \tab\tab sfc64 (Chris Doty-Humphrey, 2013) \cr
\code{squares} \tab\tab squares64 (Widynski, 2021) \cr
\code{philox} \tab\tab Philox-4×64 (Salmon and Moraes, 2011) \cr
\code{cwg128} \tab\tab cwg128 (Działa, 2022) \cr
\code{ranlux++} \tab\tab ranlux++ (Sibidanov, 2017) \cr
\code{chacha20} \tab\tab ChaCha20 (Bernstein, 2008) \cr
}
}

\section{Continuous distributions}{

The RNG object provides methods for generating random variates from common
continuous probability distributions. All methods return a numeric vector
of length \code{len}.

\describe{
\item{\code{rng$unif(len)}}{Uniform variates on [0,1).}
\item{\code{rng$unif(len, a, b)}}{Uniform variates on [a,b) with
\code{a < b}.}
\item{\code{rng$normal(len)}}{Standard normal variates (mean 0 and standard
deviation 1).}
\item{\code{rng$normal(len, mu, sigma)}}{Normal variates with mean \code{mu}
and standard deviation \code{sigma} (defaults 0 and 1).}
\item{\code{rng$skew_normal(len, mu, sigma, alpha)}}{Skew-normal variates with
location \code{mu} and scale \code{sigma} (defaults 0 and 1), and shape \code{alpha}
(required).}
\item{\code{rng$lognormal(len, mu, sigma)}}{Lognormal variates derived from an
underlying normal distribution (defaults 0 and 1).}
\item{\code{rng$exp(len)}}{Standard exponential variates (scale 1).}
\item{\code{rng$exp(len, scale)}}{Exponential variates with scale
\code{scale}.}
\item{\code{rng$gamma(len, shape, scale)}}{Gamma variates with given shape and
scale (default 1).}
\item{\code{rng$chi2(len, nu)}}{Chi-square variates with \code{nu} degrees of
freedom.}
\item{\code{rng$beta(len, a, b)}}{Beta variates with shape parameters \code{a}
and \code{b}.}
\item{\code{rng$t(len, nu)}}{Student's t variates with \code{nu} degrees of
freedom.}
\item{\code{rng$f(len, nu1, nu2)}}{F variates with \code{nu1} and \code{nu2}
degrees of freedom.}
\item{\code{rng$gumbel(len, mu, beta)}}{Gumbel variates with location \code{mu}
and scale \code{beta} (defaults 0 and 1).}
\item{\code{rng$pareto(len, xm, alpha)}}{Pareto variates with minimum value
\code{xm} and shape \code{alpha}.}
\item{\code{rng$weibull(len, shape, scale)}}{Weibull variates with given shape
and scale (default 1).}
\item{\code{rng$mvn(n, Sigma, mu = NULL)}}{Multivariate normal variates as an
\code{n} by \code{d} matrix, where \code{d} is the dimension of
\code{Sigma}.}
}
}

\section{Discrete distributions}{

The RNG object provides methods for generating random variates from common
discrete distributions and combinatorial constructions.

\describe{
\item{\code{rng$int(len, min, max)}}{Uniform integers on \verb{[min, max]}.}
\item{\code{rng$perm(n)}}{Random permutation of \code{1:n}.}
\item{\code{rng$sample(n, k)}}{Sample \code{k} elements without replacement
from \code{1:n}.}
\item{\code{rng$raw(len)}}{Generate \code{len} random bytes as a raw vector.}
}
}

\section{Configuration and Copying}{

Methods for creating, configuring, and managing RNG state. All state-setting
methods accept numeric vectors (double or integer) whose elements must be
nonnegative whole numbers not exceeding \eqn{2^{32}-1}. Where applicable,
shorter vectors are padded with zeros.

\describe{
\item{\code{rng$seed(seed, spawn_key = integer(0))}}{
Reinitialize the RNG deterministically from \code{seed} and an optional
numeric vector \code{spawn_key}.
}
\item{\code{rng$randomize()}}{Randomize the RNG state from system entropy.}
\item{\code{rng$jump(p)}}{
Jump an xor-family or \verb{ranlux++} engine ahead by \eqn{2^p} steps. The
\verb{x128+} and \verb{xoro128++} engines support \verb{p = 32, 64, 96}, while
\verb{x256++}, \verb{x256**}, \code{x256++simd}, and \verb{ranlux++} also support
\code{p = 128} and \code{p = 192}.
}
\item{\code{rng$advance(delta)}}{
Advance the \code{pcg64} engine by an arbitrary 128-bit delta. \code{delta} may
be a scalar, interpreted as \code{[delta, 0]}, or have length up to 4; shorter
vectors are zero-padded.
}
\item{\code{rng$duplicate()}}{Duplicate the RNG, preserving its state.}
\item{\code{rng$serialize()}}{Serialize the current RNG state as a raw vector.}
\item{\code{rng$deserialize(raw_state)}}{Restore state from a raw vector created
by \code{serialize()}.}
\item{\code{rng$set_state(state)}}{Set the engine state directly (advanced use).}
\item{\code{rng$pcg64_set_inc(inc)}}{
Set the increment of the PCG64 engine. The increment may have length up
to 4 and shorter vectors are zero-padded.
}
\item{\code{rng$cwg128_set_weyl(weyl)}}{
Set the Weyl increment of the cwg128 engine. \code{weyl} may have length up
to 4 and shorter vectors are zero-padded.
}
\item{\code{rng$sfc64_set_abc(abc)}}{
Set the \code{a}, \code{b}, \code{c} state words of the sfc64 engine. \code{abc} may have
length up to 6 and shorter vectors are zero-padded.
}
\item{\code{rng$chacha_set_nonce(nonce)}}{
Set the nonce of the ChaCha20 engine. The nonce may have length up to 3
and shorter vectors are zero-padded.
}
\item{\code{rng$philox_set_key(key)}}{
Set the key of the Philox engine. The key may have length up to 4 and
shorter vectors are zero-padded.
}
\item{\code{rng$squares_set_key(key)}}{
Set the key of the Squares engine. The key may have length up to 2 and
shorter vectors are zero-padded.
}
}
}

\examples{
# Create an RNG
rng <- randompack_rng()                    # Default engine (xoshiro256++)
rng_pcg <- randompack_rng("pcg64")         # Specify engine
rng_chacha <- randompack_rng("chacha20")

# Continuous distributions
x <- rng$unif(5)
x <- rng$normal(100)                    # Standard normal
x <- rng$normal(100, 1, 2)              # N(1,2)
x <- rng$skew_normal(100, mu=0, sigma=1, alpha=2)
x <- rng$lognormal(5)
x <- rng$beta(5, a=2, b=3)
Sigma <- diag(2)
x <- rng$mvn(10, Sigma, mu=c(1,2))

# Discrete distributions
x <- rng$int(5, min=1, max=10)
x <- rng$perm(5)
x <- rng$sample(10, k=3)
x <- rng$raw(4)

# Configuration and copying
rng$seed(12345)                          # seed for reproducibility
rng$randomize()                          # randomize from system entropy
rngm <- randompack_rng(full_mantissa = TRUE)  # 53-bit mantissas for doubles
rng2 <- rng$duplicate()                  # duplicate with same state
identical(rng$unif(3), rng2$unif(3))     # TRUE
raw_state <- rng$serialize()             # save state
rng3 <- randompack_rng()                 # another default RNG
rng3$deserialize(raw_state)              # restore state
identical(rng$unif(3), rng3$unif(3))     # TRUE
rng_sq <- randompack_rng("squares")      # engine-specific state setting
rng_sq$set_state(c(2, 0, 0, 0))          # counter = (2,0)
rng_sq$squares_set_key(c(3,4))

}
\seealso{
\code{\link{randompack_engines}} to list all available engines
}
