Getting started

Installation

Install from GitHub in your project environment:

using Pkg
Pkg.add(url = "https://github.com/tandem-rng/TandemRNG.jl")

Commit your project's Project.toml and Manifest.toml to retain the source revision. TandemRNG requires Julia 1.10 or later. GPU packages are optional.

Draw and continue

Tandem8x32 is immutable. Assign the returned generator to continue its stream. Reusing the same generator repeats the same draw.

using TandemRNG
start = Tandem8x32(42)
x, rng = rand_next(start, Float64)
y, rng = rand_next(rng, Float64)
(x, y, rngposition(rng))

(0.9829130398628935, 0.6164720475192338, 0x0000000000000080)

rand_at reads without advancing. Its index is one-based and relative to the current position.

@assert rand_at(start, Float64, 2) == y
rand_at(rng, Float64, 1)

0.47759300283385586

Omitting the type selects Float64. Integer seeds must satisfy 0 <= seed < 2^128.

Allocate or fill arrays

Allocating draws return (array, next_rng). Pass dimensions separately or as a tuple. rand_fill! fills an existing array and returns only the next generator.

using TandemRNG
start = Tandem8x32(42)
values, after_allocation = rand_next(start, Float32, 3, 2)
buffer = similar(values)
after_fill = rand_fill!(start, buffer)
@assert buffer == values
@assert rngposition(after_fill) == rngposition(after_allocation)
values

3×2 Matrix{Float32}:
 0.023072  0.616472
 0.982913  0.969846
 0.993267  0.477593

Arrays consume the stream in Julia's linear, column-major order. Fills agree with successive scalar draws. CPU destinations require one-based indexing and can include contiguous or strided views. CPU fills use Julia threads by default. Pass nthreads = 1 when an outer loop already distributes work.

Result types

Floating-point draws lie in [0, 1). Complex draws contain two successive real draws. Character draws produce Unicode scalar values. Integers use their full bit width. Device array restrictions appear in Devices.

Integer ranges, normals, and exponentials have immutable draws and fills too, with the values every Tandem port returns. See Derived draws. Use Stateful with Julia's Random API for these and other samplers. See Random.