Randomness System Manager

class vivarium.framework.randomness.manager.RandomnessManager[source]

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

setup(builder)[source]

get_randomness_stream(decision_point, initializes_crn_attributes=False)[source]

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

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’.
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.

Raises:

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

Return type:

RandomnessStream

get_seed(decision_point)[source]

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

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.
Return type:: int

register_simulants(simulants)[source]

Adds new simulants to the randomness mapping.

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)[source]

Parameters:: manager (RandomnessManager) –

get_stream(decision_point, initializes_crn_attributes=False)[source]

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.

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’.
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.

Return type:

RandomnessStream

get_seed(decision_point)[source]

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

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.
Return type:: int

register_simulants(simulants)[source]

Registers simulants with the Common Random Number Framework.

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.