Randomness Manager

class vivarium.engine.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, 'rate_conversion_type': 'linear'}}

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, initializes_crn_attributes=False, rate_conversion_type='linear')

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

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

• rate_conversion_type (Literal['linear', 'exponential']) – The type of conversion to use. Default is “linear” for a simple multiplication of rate and time_scaling_factor. The other option is “exponential”.

Returns:

An entry point into the Common Random Number 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)

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