Split randomness into subpackage (#263)

Split randomness into a package

docs/source/api_reference/framework/randomness/core.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.randomness.core

docs/source/api_reference/framework/randomness/exceptions.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.randomness.exceptions

docs/source/api_reference/framework/randomness.rst → docs/source/api_reference/framework/randomness/index.rst

@@ -1 +1,7 @@
 .. automodule:: vivarium.framework.randomness
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *

docs/source/api_reference/framework/randomness/index_map.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.randomness.index_map

docs/source/api_reference/framework/randomness/manager.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.randomness.manager

docs/source/api_reference/framework/randomness/stream.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.randomness.stream

docs/source/concepts/crn.rst

@@ -52,14 +52,14 @@ fit into our cube.
     decisions need to be made: does a machine lose power? does a person contract
     a disease? does a robot make a widget? etc. Each of these questions we
     consider a decision point and each should have a dedicated set (or
-    :class:`RandomnessStream <vivarium.framework.randomness.RandomnessStream>`
+    :class:`RandomnessStream <vivarium.framework.randomness.stream.RandomnessStream>`
     as we will discuss shortly) of random numbers to make the decision.
 
 Cutting our cube along the y-axis yields a slice we can think of as
 representing a simulant within the randomness system: all the decision points
 over all simulation time for a single value in the randomness index.
 
-A :class:`RandomnessStream <vivarium.framework.randomness.RandomnessStream>`,
+A :class:`RandomnessStream <vivarium.framework.randomness.stream.RandomnessStream>`,
 which from a practical standpoint we will interact with most often in a
 simulation, is a single decision point over all simulation time for all
 simulants in the randomness index.
@@ -146,15 +146,15 @@ simulations.
 Using randomness in ``vivarium``
 ---------------------------------
 We've talked about two key ways in which client code may interact with the
-randomness system: in getting and using :class:`RandomnessStreams <vivarium.framework.randomness.RandomnessStream>`
+randomness system: in getting and using :class:`RandomnessStreams <vivarium.framework.randomness.stream.RandomnessStream>`
 and in registering simulants with the system using a set of carefully-chosen
 characteristics to identify them uniquely across scenarios.
 
 Registering simulants
 ++++++++++++++++++++++
 
 Let's start with registering simulants. The randomness system provides the
-aptly named :func:`register_simulants <vivarium.framework.randomness.RandomnessInterface.register_simulants>`,
+aptly named :func:`register_simulants <vivarium.framework.randomness.manager.RandomnessInterface.register_simulants>`,
 which handles the mapping process we looked at above where simulants'
 chosen characteristics are used to map them to a specific location in the
 **randomness index**. This should be used in initializing simulants.
@@ -178,10 +178,10 @@ RandomnessStreams
 
 More commonly, you may want to get and use RandomnessStreams for specific
 **decision points**. The randomness system provides the
-:func:`get_stream <vivarium.framework.randomness.RandomnessInterface.get_stream>` to do this. Let's
+:func:`get_stream <vivarium.framework.randomness.manager.RandomnessInterface.get_stream>` to do this. Let's
 look at a quick example of how we'd use this. Say we want a component that will
 move simulants one position left every time step with probability 0.5. We should
-use a :class:`RandomnessStreams <vivarium.framework.randomness.RandomnessStream>`
+use a :class:`RandomnessStreams <vivarium.framework.randomness.stream.RandomnessStream>`
 for this decision point of whether to move left or not. Here's how we'd do it:
 
 .. code-block:: python

docs/source/tutorials/disease_model.rst

@@ -160,7 +160,7 @@ a dictionary that supports ``.``-access notation.
    :lineno-start: 2
 
 Lines 4-13 interact with Vivarium's
-:class:`randomness system <vivarium.framework.randomness.RandomnessInterface>`.
+:class:`randomness system <vivarium.framework.randomness.manager.RandomnessInterface>`.
 Several things are happening here.
 
 Lines 4-9 deal with the topic of :doc:`Common Random Numbers </concepts/crn>`,
@@ -206,7 +206,7 @@ We'll explore this much later when we're looking at running simulations with
 interventions.
 
 The next thing we do is grab actual
-:class:`randomness streams <vivarium.framework.randomness.RandomnessStream>`
+:class:`randomness streams <vivarium.framework.randomness.stream.RandomnessStream>`
 from the framework.
 
 .. literalinclude:: ../../../src/vivarium/examples/disease_model/population.py
@@ -362,7 +362,7 @@ data here to generate arbitrarily complex starting populations.
 The only thing really of note here is the call to
 ``self.age_randomness.get_draw``.  If we recall from the ``setup`` method,
 ``self.age_randomness`` is an instance of a
-:class:`~vivarium.framework.randomness.RandomnessStream` which supports several
+:class:`~vivarium.framework.randomness.stream.RandomnessStream` which supports several
 convenience methods for interacting with random numbers.  ``get_draw`` takes
 in an ``index`` representing particular simulants and returns a
 ``pandas.Series`` with a uniformly drawn random number for each simulant

docs/source/tutorials/exploration.rst

@@ -88,20 +88,19 @@ One of the things we might want to look at is the simulation
 information, but leaves many things set to defaults. We can see what's in the
 configuration by simply printing it.
 
-.. testsetup::
+.. testsetup:: configuration
 
    from vivarium.examples.disease_model import get_disease_model_simulation
 
    sim = get_disease_model_simulation()
 
-   if 'input_data' in sim.configuration:
-       del sim.configuration['input_data']
+   del sim.configuration['input_data']
 
-.. testcode::
+.. testcode:: configuration
 
    print(sim.configuration)
 
-.. testoutput::
+.. testoutput:: configuration
 
     randomness:
         key_columns:
@@ -164,14 +163,6 @@ configuration by simply printing it.
             component_configs: True
         extrapolate:
             component_configs: True
-    input_data:
-        artifact_path:
-            component_configs: None
-        artifact_filter_term:
-            component_configs: None
-        input_draw_number:
-            component_configs: None
-
 
 
 What do we see here?  The configuration is *hierarchical*.  There are a set of