Randomness System Manager

class vivarium.framework.randomness.manager.RandomnessManager

Access point for common random number generation.

CONFIGURATION_DEFAULTS: dict[str, Any] = {'randomness': {'additional_seed': None, 'key_columns': [], 'map_size': 1000000, 'random_seed': 0}}

A dictionary containing the defaults for any configurations managed by this manager. An empty dictionary indicates no managed configurations.

property name: str

setup(builder)

Defines custom actions this manager needs to run during the setup lifecycle phase.

This method is intended to be overridden by subclasses to perform any necessary setup operations specific to the manager. By default, it does nothing.

Return type:

None

Parameters:

builder (Builder) – The builder object used to set up the manager.

get_randomness_stream(decision_point, component, initializes_crn_attributes=False)

Provides a new source of random numbers for the given decision point.

Return type:

RandomnessStream

Parameters:

• decision_point (str) – A unique identifier for a stream of random numbers. Typically represents a decision that needs to be made each time step like ‘moves_left’ or ‘gets_disease’.

• component (Component | None) – The component that is requesting the randomness stream.

• initializes_crn_attributes (bool) – A flag indicating whether this stream is used to generate key initialization information that will be used to identify simulants in the Common Random Number framework. These streams cannot be copied and should only be used to generate the state table columns specified in builder.configuration.randomness.key_columns.

Returns:

An entry point into the Common Random Number generation framework. The stream provides vectorized access to random numbers and a few other utilities.

Raises:

RandomnessError – If another location in the simulation has already created a randomness stream with the same identifier.

get_seed(decision_point)

Get a randomly generated seed for use with external randomness tools.

Return type:

int

Parameters:

decision_point (str) – A unique identifier for a stream of random numbers. Typically represents a decision that needs to be made each time step like ‘moves_left’ or ‘gets_disease’.

Returns:

A seed for a random number generation that is linked to Vivarium’s common random number framework.

register_simulants(simulants)

Adds new simulants to the randomness mapping.

Return type:

None

Parameters:

simulants (DataFrame) – A table with state data representing the new simulants. Each simulant should pass through this function exactly once.

Raises:

RandomnessError – If the provided table does not contain all key columns specified in the configuration.

class vivarium.framework.randomness.manager.RandomnessInterface(manager)

Parameters:

manager (RandomnessManager)

get_stream(decision_point, component=None, initializes_crn_attributes=False)

Provides a new source of random numbers for the given decision point.

vivarium provides a framework for Common Random Numbers which allows for variance reduction when modeling counter-factual scenarios. Users interested in causal analysis and comparisons between simulation scenarios should be careful to use randomness streams provided by the framework wherever randomness is employed.

Return type:

RandomnessStream

Parameters:

• decision_point (str) – A unique identifier for a stream of random numbers. Typically, this represents a decision that needs to be made each time step like ‘moves_left’ or ‘gets_disease’.

• component (Component | None) – The component that is requesting the randomness stream.

• initializes_crn_attributes (bool) – A flag indicating whether this stream is used to generate key initialization information that will be used to identify simulants in the Common Random Number framework. These streams cannot be copied and should only be used to generate the state table columns specified in builder.configuration.randomness.key_columns.

Returns:

An entry point into the Common Random Number generation framework. The stream provides vectorized access to random numbers and a few other utilities.

get_seed(decision_point)

Get a randomly generated seed for use with external randomness tools.

Return type:

int

Parameters:

decision_point (str) – A unique identifier for a stream of random numbers. Typically represents a decision that needs to be made each time step like ‘moves_left’ or ‘gets_disease’.

Returns:

A seed for a random number generation that is linked to Vivarium’s common random number framework.

register_simulants(simulants)

Registers simulants with the Common Random Number Framework.

Return type:

None

Parameters:

simulants (DataFrame) – A section of the state table with new simulants and at least the columns specified in builder.configuration.randomness.key_columns. This function should be called as soon as the key columns are generated.