Class RandomStreamFactory

Namespace

Mrg32k3a.NET

Assembly

Mrg32k3a.NET.dll

A source of non-overlapping RandomStream instances. The factory owns a seed and a creation order: the first stream it hands out starts at that seed, and every later stream starts 2^127 values beyond the one before it.

public sealed class RandomStreamFactory

Inheritance

object

RandomStreamFactory

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Use a separate instance for each independent piece of work, such as a simulation run, an experiment or a test. Factories built from the same seed produce the same sequence of streams without affecting each other, so separate pieces of work stay reproducible even when they run at the same time. To start again from a different seed, create a new factory.

Handing out a stream is thread safe. The streams themselves are not, so give each worker its own.

A factory is restored by building a new one from a snapshot with FromState(RandomStreamFactoryState), rather than by loading into an existing instance. Its seed never changes once it is constructed, which is what lets Seed and CreateStreamAt(long, string?) read it without waiting on the streams other threads are creating.

Constructors

RandomStreamFactory()

Creates a factory seeded with DefaultSeed, six copies of 12345.

public RandomStreamFactory()

RandomStreamFactory(Mrg32k3aState)

Creates a factory with an explicit seed.

public RandomStreamFactory(Mrg32k3aState seed)

Parameters

seed Mrg32k3aState

The initial state of the first stream.

Exceptions

ArgumentException

seed is the uninitialised default value.

Properties

CreatedStreamCount

Gets the number of streams this factory has handed out through CreateStream(string?) and CreateStreams(int).

public long CreatedStreamCount { get; }

Property Value

long

Seed

Gets the seed of this factory, which is the initial state of its first stream.

public Mrg32k3aState Seed { get; }

Property Value

Mrg32k3aState

Methods

CreateStream(string?)

Hands out the next stream, starting 2^127 values beyond the stream handed out before it.

public RandomStream CreateStream(string? name = null)

Parameters

name string

An optional label, used only in diagnostics.

Returns

RandomStream

A new stream positioned at the start of its own block.

CreateStreamAt(long, string?)

Builds the stream at a given position in this factory's ordering without creating the ones before it, and without touching the creation order.

public RandomStream CreateStreamAt(long index, string? name = null)

Parameters

index long

Zero-based position; index zero is the stream that starts at the factory seed.

name string

An optional label, used only in diagnostics.

Returns

RandomStream

A stream identical to the one CreateStream(string?) would produce at that position.

Remarks

Unlike CreateStream(string?), this identifies a stream by its position rather than by creation order. It exists for parallel and distributed runs, where a worker knows its rank but not the history of the run. The cost grows with the logarithm of index, not with index itself.

Exceptions

ArgumentOutOfRangeException

index is negative.

CreateStreams(int)

Hands out the next count streams in creation order, typically one for each worker.

public RandomStream[] CreateStreams(int count)

Parameters

count int

The number of streams to hand out.

Returns

RandomStream[]

A new array of streams, identical to calling CreateStream(string?) that many times. The streams are consecutive even when other threads create streams at the same time.

Exceptions

ArgumentOutOfRangeException

count is negative.

FromState(RandomStreamFactoryState)

Rebuilds a factory from a snapshot taken by SaveState().

public static RandomStreamFactory FromState(RandomStreamFactoryState state)

Parameters

state RandomStreamFactoryState

The snapshot to restore.

Returns

RandomStreamFactory

A factory whose next stream is the one the saved factory would have handed out next.

Remarks

There is no counterpart that loads into an existing factory. A factory is shared between threads, so replacing its seed underneath them would let one worker take a stream from the old ordering and another from the new one, which is the duplication this snapshot exists to prevent.

Exceptions

ArgumentNullException

state is null.

ArgumentException

The snapshot is of an unknown version or holds an invalid seed or count.

SaveState()

Captures what this factory needs in order to resume: its seed and its creation order.

public RandomStreamFactoryState SaveState()

Returns

RandomStreamFactoryState

A fresh snapshot, safe to serialize.

Remarks

The seed and the count are read together, so a snapshot taken while another thread is creating streams describes a position the factory actually passed through.