Local Random Streams

Home > Model Development Topics > Local Random Streams

The local_random_streams option enables distinct random number generator (RNG) streams for individual entities. This can help maintain coherence between runs of time-based models, but requires additional memory in entities to maintain RNG state.

Related topics

• Model Code
• Microdata Output: Activating and using microdata output

Topic contents

• Introduction and Background
• Syntax and Use How to activate and use
• Illustrative Example Illustrative example using IDMM

Introduction and Background

under construction

Quick review of RNG streams.

    double x = RandUniform(1);
    double y = RandNormal(2);
    double z = RandPoisson(3);

Decoherence control using independent RNG streams is applicable to case-based models which have more than one entity of a give type per case, or to time-based models.

[back to topic contents]

Syntax and Use

under construction

options local_random_streams = Host; options local_random_streams = Ticker;

Multiple statements allowed, one for each entity for which local streams are desired.

During model build, a message like

Entity 'Host' has 11 local random streams, of which 1 are Normal

will be issued for each entity with local random streams.

If an entity with local RNG streams calls RandUniform, RandNormal, or RandLogistic to initialize attributes before it enters the simulation, e.g. in a Start function, the built-in function initialize_local_random_streams() must be called first. The function initialize_local_random_streams() calls get_entity_key(), so be sure that any attributes used by get_entity_key() have been assigned first.

Otherwise, a run-time error like

Simulation error: RandUniform called with uninitialized local random streams.

If there are no RNG calls before the entity enters the simulation, it is not necessary to call initialize_local_random_streams() when initializing the entity.

Model code can call initialize_local_random_streams even if the entity has no local RNG streams (no effect).

Normal behaviour of random streams in PreSimulation, and in Simulation (to create a starting population, for example, as in IDMM). Normal behaviour of random streams in other entities which were not named using the local_random_streams option.

For entities named in local_random_streams, the streams used in the entity are maintained at the entity level.

Streams are seeded using the result of get_entity_key, combined with the run seed, member seed (and for case-based models with the case seed).

[back to topic contents]

Illustrative Example

under construction

This example is divided into the following sections:

Illustrative example sections

• Summary
• IDMM overview
• Base run
• Variant run
• Coherence with global random streams
• Coherence with local random streams
• IDMM differences Differences with the distributed version of IDMM

[back to topic contents]

Summary

This example illustrates the impact of local vs. global random streams using the time-based IDMM model.

A Base run .

A slightly different Variant run is compared to a Base run.

A modified version of the IDMM model is used in

[back to illustrative example]
[back to topic contents]

IDMM overview

IDMM simulates an interacting dynamic contact network of Host entities, together with a disease which can be transmitted over that contact network. The contact network is initialized randomly at the start of the simulation. During the simulation, each Host interacts with other Hosts to which it is connected during a contact event. Each Host can change the Hosts to which it is connected during a contact change event. Optionally, a Host can change a connected Host during a contact event, if that host is infectious.

During a contact event, the disease can propagate between the two Hosts, depending on the disease status of each. An infected Host progresses through the 4 disease phases susceptible, latent, infectious, immune, each of fixed duration. On infection, the Host enters the latent phase, during which they are both asymptomatic and non-infectious. After the latent phase, the Host enters an infectious phase during which they can infect another Host during a contact event. After the infectious phase, the Host enters the immune phase during which they cannot be infected by an infectious Host during a contact event. After the immune phase, the Host becomes susceptible once again.

Before the simulation starts, all Host entities are in the susceptible state. At the beginning of the simulation, a portion of the Host population is randomly infected with a given probability.

[back to illustrative example]
[back to topic contents]

IDMM differences

under construction

Refer to coherence example using IDMM example in Microdata Output

• Similar example here, but using two runs Run1 and Run2 of IDMM, with InitialDiseasePrevalence very slightly higher to generate at least one (but very few) additional infected Hopsts at the beginning of the simulation.
• Use Microdata Output to show decoherence in disease phase at end of runs
• Perhaps, measure coherence between two runs over time, by output microdata at time steps.
• Turn on local rng for Host entities, repeat Run1 and Run2
• Use Microdata Output to show coherence in disease phase at end of runs (or evolution over time).

[back to illustrative example]
[back to topic contents]