Skip to main content

ClikaRT::random::Generator

class

Header: ClikaRT/compute/generator.h

A random generator: the {seed, counter} state a random draw reads from. Every device holds one generator of its own, the device's DEFAULT: the ops:: random functions draw from it, and device::manual_seed seeds it. A generator you create (Generator::create(seed)) draws its own sequence beside the device's through its draw methods (gen.rand(...), gen.multinomial(...), the whole family below): a request served with a seed beside unseeded ones reads the values it would read alone, and the device's sequence stays where it was. The draw math is counter-based, so one generator reads the same sequence on every device it draws on, and copies of a Generator refer to the same generator.

Static member functions​

for_device()​

static Generator for_device(Device device)

device's default generator, the one device::manual_seed seeds and the ops:: random functions draw from on device.

Declared in ClikaRT/compute/generator.h, line 45

create()​

static Generator create(std::uint64_t seed = 0)

A new generator of your own, seeded at seed with its counter at 0, independent of every device's default and of every other generator.

Declared in ClikaRT/compute/generator.h, line 49

Member functions​

Generator()​

Generator() noexcept

A generator meaning "the device's default": its draws read what the ops:: random functions read. defined() reads false.

Declared in ClikaRT/compute/generator.h, line 41

Generator(Generator)​

Generator(const Generator& other)

Declared in ClikaRT/compute/generator.h, line 51

operator=(Generator)​

Generator& operator=(const Generator& other)

Declared in ClikaRT/compute/generator.h, line 52

Generator(Generator)​

Generator(Generator&& other) noexcept

Declared in ClikaRT/compute/generator.h, line 53

operator=(Generator)​

Generator& operator=(Generator&& other) noexcept

Declared in ClikaRT/compute/generator.h, line 54

~Generator()​

~Generator()

Declared in ClikaRT/compute/generator.h, line 55

defined()​

bool defined() const noexcept

True when this names a generator; false for the device-default form.

Declared in ClikaRT/compute/generator.h, line 58

manual_seed()​

void manual_seed(std::uint64_t seed)

Seed this generator and reset its counter, so its next draws replay the seeded sequence from its start. Do not call while a draw reading it is in flight. On the device-default form: no effect (seed the device through device::manual_seed).

Declared in ClikaRT/compute/generator.h, line 64

seed()​

std::uint64_t seed() const

The seed this generator draws from (the default seed, 0, on the device-default form).

Declared in ClikaRT/compute/generator.h, line 68

operator==()​

bool operator==(const Generator& other) const noexcept

Two handles compare equal when they name the same generator; two device-default forms compare equal.

Declared in ClikaRT/compute/generator.h, line 72

operator!=()​

bool operator!=(const Generator& other) const noexcept

Declared in ClikaRT/compute/generator.h, line 73

rand()​

Tensor rand(
    ClikaRT::Span<const ScalarOrTensor> shape,
    DataType dtype = DataType::Float32,
    StreamOrDevice device = {}
) const

Uniform [0, 1) draws of shape, as ops::rand.

Parameters

  • shape: the output shape (each extent a scalar or 0-D tensor).
  • dtype: output float dtype; default Float32.
  • device: stream or device to allocate/run on; default = the default device.

Returns: a shape-shaped tensor of uniform draws.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float dtype.

Declared in ClikaRT/compute/generator.h, line 88

rand_like()​

Tensor rand_like(Tensor reference, StreamOrDevice device = {}) const

Uniform [0, 1) draws shaped and typed like reference, as ops::rand_like.

Parameters

  • reference: the tensor whose shape and dtype the draws take.
  • device: stream or device; default = reference's.

Returns: uniform draws, shaped and typed like reference.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float reference.

Declared in ClikaRT/compute/generator.h, line 97

randn()​

Tensor randn(
    ClikaRT::Span<const ScalarOrTensor> shape,
    DataType dtype = DataType::Float32,
    StreamOrDevice device = {}
) const

Standard normal draws of shape, as ops::randn.

Parameters

  • shape: the output shape (each extent a scalar or 0-D tensor).
  • dtype: output float dtype; default Float32.
  • device: stream or device to allocate/run on; default = the default device.

Returns: a shape-shaped tensor of standard normal draws.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float dtype.

Declared in ClikaRT/compute/generator.h, line 108

randn_like()​

Tensor randn_like(Tensor reference, StreamOrDevice device = {}) const

Standard normal draws shaped and typed like reference, as ops::randn_like.

Parameters

  • reference: the tensor whose shape and dtype the draws take.
  • device: stream or device; default = reference's.

Returns: standard normal draws, shaped and typed like reference.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float reference.

Declared in ClikaRT/compute/generator.h, line 117

randint()​

Tensor randint(
    int64_t low,
    int64_t high,
    ClikaRT::Span<const ScalarOrTensor> shape,
    DataType dtype = DataType::Int64,
    StreamOrDevice device = {}
) const

Integer draws in [low, high) of shape, as ops::randint.

Parameters

  • low: the lowest value drawn.
  • high: one past the highest value drawn; above low.
  • shape: the output shape (each extent a scalar or 0-D tensor).
  • dtype: output integer dtype; default Int64.
  • device: stream or device to allocate/run on; default = the default device.

Returns: a shape-shaped tensor of integer draws.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on an empty range, a non-integer dtype or a range the dtype cannot hold.

Declared in ClikaRT/compute/generator.h, line 131

randint_like()​

Tensor randint_like(
    Tensor reference,
    int64_t low,
    int64_t high,
    StreamOrDevice device = {}
) const

Integer draws in [low, high) shaped and typed like reference, as ops::randint_like.

Parameters

  • reference: the tensor whose shape and dtype the draws take.
  • low: the lowest value drawn.
  • high: one past the highest value drawn; above low.
  • device: stream or device; default = reference's.

Returns: integer draws, shaped and typed like reference.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on an empty range or a non-integer reference.

Declared in ClikaRT/compute/generator.h, line 143

uniform_inplace_impl()​

Result<void> uniform_inplace_impl(
    Tensor& self,
    double low,
    double high,
    StreamOrDevice device
) const

Declared in ClikaRT/compute/generator.h, line 145

uniform_()​

Tensor& uniform_(
    Tensor& self,
    double low = 0.0,
    double high = 1.0,
    StreamOrDevice device = {}
) const

In-place: overwrite self with uniform draws in [low, high), as ops::uniform_.

Parameters

  • self: the float tensor to fill.
  • low: the range's lower bound (drawn); default 0.
  • high: the range's upper bound (never drawn); default 1.
  • device: stream or device; default = self's.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float self or an empty range.

Declared in ClikaRT/compute/generator.h, line 154

normal_inplace_impl()​

Result<void> normal_inplace_impl(
    Tensor& self,
    ScalarOrTensor mean,
    ScalarOrTensor stddev,
    StreamOrDevice device
) const

Declared in ClikaRT/compute/generator.h, line 156

normal_()​

Tensor& normal_(
    Tensor& self,
    ScalarOrTensor mean = 0,
    ScalarOrTensor stddev = 1,
    StreamOrDevice device = {}
) const

In-place: overwrite self with normal draws of mean and stddev, as ops::normal_.

Parameters

  • self: the float tensor to fill.
  • mean: the mean, a scalar or a tensor broadcast over self; default 0.
  • stddev: the standard deviation, a scalar or a tensor broadcast over self; default 1.
  • device: stream or device; default = self's.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float self.

Declared in ClikaRT/compute/generator.h, line 165

normal()​

Tensor normal(
    ScalarOrTensor mean,
    ScalarOrTensor stddev,
    ClikaRT::Span<const ScalarOrTensor> shape,
    StreamOrDevice device = {}
) const

Normal draws of mean and stddev shaped shape, as ops::normal.

Parameters

  • mean: the mean, a scalar or a tensor broadcast over the output.
  • stddev: the standard deviation, a scalar or a tensor broadcast over the output.
  • shape: the output shape (each extent a scalar or 0-D tensor).
  • device: stream or device to allocate/run on; default = the default device.

Returns: a shape-shaped Float32 tensor of normal draws.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a shape the operands cannot broadcast over.

Declared in ClikaRT/compute/generator.h, line 179

exponential_inplace_impl()​

Result<void> exponential_inplace_impl(
    Tensor& self,
    double lambd,
    StreamOrDevice device
) const

Declared in ClikaRT/compute/generator.h, line 181

exponential_()​

Tensor& exponential_(
    Tensor& self,
    double lambd = 1.0,
    StreamOrDevice device = {}
) const

In-place: overwrite self with exponential draws of rate lambd, as ops::exponential_.

Parameters

  • self: the float tensor to fill.
  • lambd: the rate, above 0; default 1.
  • device: stream or device; default = self's.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float self or a rate at or below 0.

Declared in ClikaRT/compute/generator.h, line 189

bernoulli()​

Tensor bernoulli(Tensor probabilities, StreamOrDevice device = {}) const

Independent Bernoulli draws from per-element success probabilities, as ops::bernoulli.

Parameters

  • probabilities: per-element success chances in [0, 1]; float dtype.
  • device: stream or device; default = the input's.

Returns: 0/1 draws, same shape and dtype as probabilities.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float input.

Declared in ClikaRT/compute/generator.h, line 199

bernoulli_inplace_impl()​

Result<void> bernoulli_inplace_impl(Tensor& self, StreamOrDevice device) const

Declared in ClikaRT/compute/generator.h, line 201

bernoulli_()​

void bernoulli_(Tensor& self, StreamOrDevice device = {}) const

In-place: overwrite self, whose values are the per-element success probabilities, with the 0/1 draws, as ops::bernoulli_.

Parameters

  • self: the float tensor of success chances, filled with the draws.
  • device: stream or device; default = self's.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float self.

Declared in ClikaRT/compute/generator.h, line 208

poisson()​

Tensor poisson(Tensor rates, StreamOrDevice device = {}) const

Independent Poisson draws from per-element rates, as ops::poisson.

Parameters

  • rates: per-element rates at or above 0; float dtype.
  • device: stream or device; default = the input's.

Returns: the counts, same shape and dtype as rates.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-float input.

Declared in ClikaRT/compute/generator.h, line 217

randperm()​

Tensor randperm(
    ScalarOrTensor n,
    DataType dtype = DataType::Int64,
    StreamOrDevice device = {}
) const

A random permutation of 0 .. n-1, as ops::randperm.

Parameters

  • n: the permutation's length, a scalar or a 0-D tensor.
  • dtype: output integer dtype; default Int64.
  • device: stream or device to allocate/run on; default = the default device.

Returns: an [n] tensor holding each of 0 .. n-1 once.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-integer dtype or a negative n.

Declared in ClikaRT/compute/generator.h, line 229

multinomial()​

Tensor multinomial(
    Tensor probabilities,
    int64_t num_samples,
    bool replacement = false,
    StreamOrDevice device = {}
) const

Categorical draws from per-row weights, as ops::multinomial.

Parameters

  • probabilities: [.., C] non-negative weights per row (not necessarily normalized); float dtype.
  • num_samples: draws per row.
  • replacement: draw with replacement; default false (then num_samples is at most C).
  • device: stream or device; default = the input's.

Returns: Int64 category indices, [.., num_samples].

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) when a weight is negative or num_samples exceeds C without replacement.

Declared in ClikaRT/compute/generator.h, line 243

random_inplace_impl()​

Result<void> random_inplace_impl(
    Tensor& self,
    std::optional<std::int64_t> low,
    std::optional<std::int64_t> high,
    StreamOrDevice device
) const

Declared in ClikaRT/compute/generator.h, line 245

random_()​

Tensor& random_(
    Tensor& self,
    std::optional<std::int64_t> low = std::nullopt,
    std::optional<std::int64_t> high = std::nullopt,
    StreamOrDevice device = {}
) const

In-place: overwrite the integer tensor self with draws in [low, high), or over the dtype's whole range when both bounds are unset, as ops::random_.

Parameters

  • self: the integer tensor to fill.
  • low: the lowest value drawn; set with high or not at all.
  • high: one past the highest value drawn; set with low or not at all.
  • device: stream or device; default = self's.

Throws

  • ClikaRT::Error: (INVALID_ARGUMENT) on a non-integer self, a half-set range or an empty one.

Declared in ClikaRT/compute/generator.h, line 257