Release candidate/v4.0.0

.github/workflows/deploy.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.11"
+          python-version: "3.13"
       - name: Install dependencies
         run: |
           python --version

.readthedocs.yml

@@ -11,7 +11,7 @@ sphinx:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.13"
 python:
   install:
       # This runs pip install .[docs] from the project root.

CHANGELOG.rst

@@ -1,3 +1,85 @@
+**4.0.0 - TBD TBD TBD**
+-----------------------
+
+This release introduces a major refactor of the population management system as well 
+as various other miscellaneous changes.
+
+Breaking changes
+----------------
+
+Population management system refactor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Interactive context: 'get_population()' will now error if requesting an attribute that doesn't exist.
+- Population views: Replace subviews and 'get()' method with 'get_attributes()',
+  'get_attribute_frame()', and 'get_private_columns()'.
+
+  - You must now explicitly request which attributes you want to retrieve.
+  - Write access (via the 'update()' method) is now restricted to private columns
+    created by the component the view is attached to.
+
+- Population views: Remove support for population view default queries.
+- Population interface: Replace the 'tracked' column and corresponding auto-filter
+  logic with a new 'register_tracked_query()' method and 'include_untracked' argument
+  when getting attributes or private columns from a population view.
+- Population interface: Require explicit initializer method registration instead 
+  of inferring from methods named 'on_initialize_simulants()'. Supports multiple
+  initializer methods per component.
+
+  - Remove columns_created, columns_required, and initialization_requirements properties throughout.
+  - Changed the names of all initializer methods (no longer 'on_initialize_simulants').
+
+- Population manager: 'get_population()' now requires an explicit attribute request ("all" is allowed).
+- Stop returning AttributePipelines (previously Pipelines) when registering them.
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+- Split managers and their corresponding interfaces into separate modules.
+- Replace 'requires_columns' and 'requires_values' arguments with 'requires_attributes' throughout.
+- Replace 'dependencies' arguments with 'required_resources' throughout.
+- Change default behavior of state machine 'allow_self_transition' to True.
+
+Major changes
+-------------
+
+- Replace all Pipelines with AttributePipelines throughout.
+- Support attribute names as source and/or modifiers to AttributePipelines.
+- Add support for python 3.12 and 3.13
+
+Other changes
+-------------
+
+Population management system refactor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- InteractiveContext: Allow specific column request to 'get_population()'.
+- InteractiveContext: Implement new 'get_columns()' method to get all attribute names.
+- Population views: Implement new 'get_filtered_index()' method.
+- Stop using population views inappropriately when using individualized clocks.
+- Implement 'skip_post_processor' argument to population view 'get_attributes()'
+  and population manager 'get_population()' methods.
+- Ensure Pipeline 'union_post_processor' always returns a Series or DataFrame.
+- Change 'alive' string column to 'is_alive' boolean column in disease model example and various tests.
+- Make Mortality a sub-component of BasePopulation component in disease model example.
+- Update documentation.
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+- LookupTables: Improve type hinting.
+- LookupTables: Register tables as resources.
+- LookupTables: Warn if unused tables are registered.
+- Properly set Pipeline source dependencies.
+- Infer component when creating a Resource.
+- Clean up Resource registration.
+- Clean up ComponentManager.
+- Only get random draws for non-0 and non-1 probabilities when calling 'filter_for_probability()'.
+- Fix mypy error in setup.py.
+- Fix mypy errors in disease model example.
+- Create a Component.logger property for better type-checking.
+- Removed unnecessary InitializerComponentSet class.
+
 **3.6.6 - 01/06/26**
 
   - Fail deployment if changelog date is not current date

README.rst

@@ -19,7 +19,7 @@ Vivarium
 Vivarium is a simulation framework written using standard scientific Python
 tools.
 
-**Vivarium requires Python 3.8-3.11 to run**
+**Vivarium requires Python 3.10-3.13 to run**
 
 You can install ``vivarium`` from PyPI with pip:
 
@@ -31,7 +31,7 @@ or build it from source with
 
   ``> cd vivarium``
 
-  ``> conda create -n ENVIRONMENT_NAME python=3.11``
+  ``> conda create -n ENVIRONMENT_NAME python=3.12``
 
   ``> pip install -e .[dev]``
 

docs/nitpick-exceptions

@@ -47,9 +47,13 @@ py:exc ResultsConfigurationError
 py:exc vivarium.framework.results.exceptions.ResultsConfigurationError
 py:class vivarium.framework.plugins.M
 py:class vivarium.framework.plugins.I
-py:class vivarium.framework.utilities.T
+py:class vivarium.framework.utilities.TimeValue
+py:class T
+py:class vivarium.framework.components.manager.T
+py:class vivarium.framework.components.manager.C
 
 # layered_config_tree
+py:class LayeredConfigTree
 py:class layered_config_tree.main.LayeredConfigTree
 py:exc layered_config_tree.exceptions.ConfigurationError
 
@@ -69,5 +73,8 @@ py:class Logger
 py:class Path
 py:class LookupTableData
 
+# pathlib internals
+py:class pathlib._local.Path
+
 # typing
 py:data typing.Union

docs/source/api_reference/framework/event/index.rst

@@ -0,0 +1,11 @@
+================
+Event Management
+================
+
+.. automodule:: vivarium.framework.event
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/source/api_reference/framework/event/interface.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.event.interface

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

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

docs/source/api_reference/framework/logging/index.rst

@@ -1,3 +1,7 @@
+==================
+Logging Management
+==================
+
 .. automodule:: vivarium.framework.logging
 
 .. toctree::

docs/source/api_reference/framework/lookup/index.rst

@@ -1,3 +1,7 @@
+=======================
+Lookup Table Management
+=======================
+
 .. automodule:: vivarium.framework.lookup
 
 .. toctree::

docs/source/api_reference/framework/population/interface.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.population.interface

docs/source/api_reference/framework/population/utilities.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.population.utilities

docs/source/api_reference/framework/time/index.rst

@@ -0,0 +1,11 @@
+===============
+Time Management
+===============
+
+.. automodule:: vivarium.framework.time
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/source/api_reference/framework/time/interface.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.time.interface

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

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

docs/source/api_reference/framework/values/interface.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.values.interface

docs/source/concepts/builder.rst

@@ -24,10 +24,10 @@ they register for services and provide information about their structure. For ex
 a component needing to leverage the simulation clock and step size
 to determine a numerical effect to apply on each time step, will get the
 simulation clock and step size though the Builder and will register
-method(s) to apply the effect (e.g., via :meth:`vivarium.framework.values.manager.ValuesInterface.register_value_modifier`).
-Another component, needing to initialize state for simulants at before the
-simulation begin, might call :meth:`vivarium.framework.population.manager.PopulationInterface.initializes_simulants` in its setup
-method to register method(s) that setup the additional state.
+method(s) to apply the effect (e.g., via :meth:`vivarium.framework.values.interface.ValuesInterface.register_value_modifier`).
+Another component, needing to initialize state for simulants before the
+simulation begins, might call :meth:`vivarium.framework.population.interface.PopulationInterface.register_initializer` 
+in its setup method to register method(s) that set up the additional state.
 
 
 Outline

docs/source/concepts/crn.rst

@@ -188,30 +188,31 @@ for this decision point of whether to move left or not. Here's how we'd do it:
 
     import pandas as pd
 
-    class MoveLeft:
+    from vivarium import Component
+
+    class MoveLeft(Component):
 
         @property
         def name(self):
             return 'move_left'
 
         def setup(self, builder):
-            self.randomness = builder.randomness.get_stream('move_left')
-
-            builder.population.initializes_simulants(self.on_initialize_simulants,
-                                                     creates_columns=['location'])
-
-            self.population_view = builder.population.get_view(['location'])
+            self.randomness = builder.randomness.get_stream(self.name)
 
-            builder.event.register_listener('time_step', self.on_time_step)
+            builder.population.register_initializer(
+                initializer=self.initialize_location,
+                columns='location',
+                required_resources=[self.randomness],
+            )
 
-        def on_initialize_simulants(self, pop_data):
+        def initialize_location(self, pop_data):
             # all simulants start at position 10
             self.population_view.update(pd.Series(10, index=pop_data.index, name='location'))
 
         def on_time_step(self, event):
             # with probability 0.5 simulants move to the left 1 position
             to_move_index = self.randomness.filter_for_probability(event.index, pd.Series(0.5, index=event.index))
-            moved_locations = self.population_view.get(to_move_index).location - 1
+            moved_locations = self.population_view.get_attributes(to_move_index, "location") - 1
             self.population_view.update(moved_locations)
 
 

docs/source/concepts/event.rst

@@ -17,9 +17,9 @@ a means of coordinating across various components in a simulation.
 What is an Event?
 -----------------
 
-An :class:`Event <vivarium.framework.event.Event>` is a simple container for a
-group of attributes that provide all the necessary information to respond to
-the event.  Events have the following attributes:
+An :class:`~ <vivarium.framework.event.manager.Event>` is a simple container for a
+group of class attributes that provide all the necessary information to respond to
+the event. Each Event contains the following:
 
 .. list-table:: **Event Attributes**
    :header-rows: 1
@@ -28,7 +28,7 @@ the event.  Events have the following attributes:
    * - Name
      - Description
    * - | index
-     - | An index into the population table that contains all
+     - | An index into the population state table that contains all
        | individuals that may respond to the event.
    * - | time
      - | The time at which the event will resolve.  The current simulation
@@ -89,14 +89,14 @@ these phases.
 Interacting with Events
 -----------------------
 
-The :class:`EventInterface <vivarium.framework.event.EventInterface>` is
+The :class:`~ <vivarium.framework.event.interface.EventInterface>` is
 available off the :ref:`Builder <builder_concept>` and provides two options for
 interacting with the event system:
 
-1. :func:`register_listener <vivarium.framework.event.EventInterface.register_listener()>` to add a
+1. :func:`~ <vivarium.framework.event.interface.EventInterface.register_listener()>` to add a
 listener to a given event to be called on emission
 
-2. :func:`get_emitter <vivarium.framework.event.EventInterface.get_emitter()>`
+2. :func:`~ <vivarium.framework.event.interface.EventInterface.get_emitter()>`
 to retrieve a callable emitter for a given event
 
 Although methods for both getting emitters and registering listeners are
@@ -109,9 +109,9 @@ Registering Listeners
 
 In order to register a listener to an event to respond when that event is
 emitted, we can use the
-:func:`register_listener <vivarium.framework.event.EventInterface.register_listener()>`. The listener
+:func:`~ <vivarium.framework.event.interface.EventInterface.register_listener()>`. The listener
 itself should be a callable function that takes as its only argument
-the :class:`Event <vivarium.framework.event.Event>` that is emitted.
+the :class:`~ <vivarium.framework.event.manager.Event>` that is emitted.
 
 Suppose we wish to track how many simulants are affected each time step. We
 could do this by creating an observer component with an ``on_time_step`` method
@@ -144,11 +144,18 @@ another row to our dataframe tracking the number of affected simulants.
    simulation at the beginning of the next time step should only depend on the
    current state of the system.
 
+.. note::
+
+   If a new component is being created that inherits from :class:`vivarium.component.Component`,
+   listeners are registered automatically if the component defines methods named
+   ``on_<event_name>``, where ``<event_name>`` is one of the lifecycle names
+   (e.g. ``time_step``, ``collect_metrics``, etc.).
+
 
 Emitting Events
 +++++++++++++++
 
-The :func:`get_emitter <vivarium.framework.event.EventInterface.get_emitter()>`
+The :func:`~ <vivarium.framework.event.interface.EventInterface.get_emitter()>`
 provides a way to get a callable emitter for a given named event. It can be
 used as follows:
 

docs/source/concepts/lifecycle.rst

@@ -115,7 +115,7 @@ the simulation components will have their ``setup`` method called with
 the simulation :ref:`builder <builder_concept>` as an argument.  The
 builder allows the components to request services like
 :ref:`randomness <crn_concept>` or views into the
-:term:`population state table <State Table>` or to register themselves
+:term:`state table <Population State Table>` or to register themselves
 with various simulation subsystems. Setting up components may also involve
 loading data, registering or getting :ref:`pipelines <values_concept>`,
 creating :ref:`lookup tables <lookup_concept>`, and registering
@@ -173,7 +173,7 @@ the state transitions by emitting a series of events for each
    simulation outputs.
 
 By listening for these events, individual components can perform actions,
-including manipulating the :ref:`state table <population_concept>`. This
+including manipulating the :ref:`population state table <population_concept>`. This
 sequence of events is repeated until the simulation clock passes the
 simulation end time.