class

`SushiBLAS::RandomOps`

Records random fills of tensors, drawing from one random stream.

Declared in: include/SushiBLAS/engine/math/random.hpp

Uses a hand-written, portable Philox4x32-10 counter-based PRNG implemented directly in SYCL to generate numbers from various distributions on the accelerator - no oneMKL dependency.

Public member functions

RandomOps(TaskRecorder &recorder, RngStream &stream) noexcept

Builds a view over a recorder and a stream; both must outlive the view.

explicit RandomOps(Engine &engine) noexcept

Builds a view that records on engine's graph and draws from engine's stream.

RandomOps(const RandomOps &)=default

RandomOps & operator=(const RandomOps &)=delete

RandomOps(RandomOps &&)=default

RandomOps & operator=(RandomOps &&)=delete

~RandomOps()=default

void set_seed(uint64_t seed)

Sets the stream's seed and rewinds its offset to zero.

void seed(uint64_t s)

Alias for set_seed.

TaskHandle constant(Tensor &t, double value)

Fills a tensor with a constant value.

Parameters

t: Tensor to fill.
value: The constant value.

Returns

The handle of the recorded task.

TaskHandle uniform(Tensor &t, double min=0.0, double max=1.0)

Fills a tensor from a uniform distribution on [min, max).

Parameters

t: Tensor to fill; FLOAT32, FLOAT64, COMPLEX32 or COMPLEX64, contiguous.
min: Minimum value (default 0.0); finite, not above max; min == max fills min.
max: Maximum value (default 1.0); max - min finite in t's dtype.

Exceptions

std::invalid_argument: unless the bounds are finite and ordered.

Returns

The handle of the recorded task.

TaskHandle normal(Tensor &t, double mean=0.0, double stddev=1.0)

Fills a tensor from a normal distribution.

Parameters

mean: Mean of the distribution; finite.
stddev: Standard deviation; finite and at least 0.

Exceptions

std::invalid_argument: when mean or stddev breaks its rule, or t is HALF.

Returns

The handle of the recorded task.

TaskHandle log_normal(Tensor &t, double mean=0.0, double stddev=1.0)

Fills a tensor from a log-normal distribution.

Parameters

mean: Mean of the underlying normal distribution; finite.
stddev: Standard deviation of the underlying normal; finite and at least 0.

Exceptions

std::invalid_argument: when mean or stddev breaks its rule, or t is not real.

Returns

The handle of the recorded task.

TaskHandle exponential(Tensor &t, double lambda=1.0)

Fills a tensor from an exponential distribution.

Parameters

lambda: Rate, one over the mean; finite and above 0.

Exceptions

std::invalid_argument: when lambda breaks its rule or t is not real.

Returns

The handle of the recorded task.

TaskHandle poisson(Tensor &t, double lambda=1.0)

Fills a tensor from a Poisson distribution, by Knuth below 10 and PTRS above.

Parameters

t: Tensor to fill; FLOAT32 or FLOAT64, contiguous, on a device with fp64.
lambda: Mean of the distribution; finite and in [0, K_MAX_POISSON_LAMBDA].

Exceptions

std::invalid_argument: when lambda or t breaks its rule.

Returns

The handle of the recorded task.

TaskHandle discrete_uniform(Tensor &t, int32_t min, int32_t max)

Fills a tensor with integers drawn uniformly from the closed range [min, max].

Parameters

t: Tensor to fill; FLOAT64, or FLOAT32 while |min| and |max| are at most 2^24.
max: Maximum value (inclusive); not below min.

Exceptions

std::invalid_argument: when min > max, t is complex or FLOAT32 past 2^24.

Returns

The handle of the recorded task.

TaskHandle truncated_normal(Tensor &t, double mean=0.0, double stddev=1.0, double a=-2.0, double b=2.0)

Fills a tensor from a truncated normal distribution.

Parameters

a: Lower bound, in standard deviations; clamped to -40 before recording.
b: Upper bound, in standard deviations; clamped to 40 before recording.

Exceptions

std::invalid_argument: when t is not FLOAT32 or FLOAT64.
std::runtime_error: when a and b are not finite with a < b, or bound no mass in t's dtype.

TaskHandle bernoulli(Tensor &t, double p=0.5)

Fills a tensor from a Bernoulli distribution.

Parameters

t: Tensor to fill; FLOAT32 or FLOAT64, contiguous.
p: Probability of a 1; within [0, 1].

Exceptions

std::invalid_argument: when p is NaN or outside [0, 1], or t is complex.

Returns

The handle of the recorded task.

TaskHandle xavier_uniform(Tensor &t, int64_t n_in, int64_t n_out)

Fills a tensor by Xavier (Glorot) uniform initialisation.

Exceptions

std::invalid_argument: when n_in + n_out is not above 0 or t is not real.

Returns

The handle of the recorded task.

TaskHandle xavier_normal(Tensor &t, int64_t n_in, int64_t n_out)

Fills a tensor by Xavier (Glorot) normal initialisation.

Exceptions

std::invalid_argument: when n_in + n_out is not above 0 or t is not real.

Returns

The handle of the recorded task.

TaskHandle he_uniform(Tensor &t, int64_t n_in)

Fills a tensor by He (Kaiming) uniform initialisation.

Exceptions

std::invalid_argument: when n_in is not above 0 or t is not real.

Returns

The handle of the recorded task.

TaskHandle he_normal(Tensor &t, int64_t n_in)

Fills a tensor by He (Kaiming) normal initialisation.

Exceptions

std::invalid_argument: when n_in is not above 0 or t is not real.

Returns

The handle of the recorded task.

TaskHandle orthogonal(Tensor &t, double gain=1.0)

Fills a matrix with a random (semi-)orthogonal matrix scaled by gain.

Parameters

t: Must be rank 2, non-empty, and FLOAT32 or FLOAT64.

Exceptions

std::invalid_argument: when t is not FLOAT32 or FLOAT64, has no storage or is not contiguous.
std::runtime_error: when t is not a non-empty rank-2 tensor.