vivarium-interactive 1.0.0__tar.gz

vivarium_interactive-1.0.0/.readthedocs.yaml

@@ -0,0 +1,37 @@
+# Paths are repo-root-relative even when this file lives in a subdirectory,
+# so the package path must be qualified with libs/interactive/.
+#
+# This file is read by RTD only when the vivarium-interactive RTD
+# project's Admin > Advanced Settings > "Path for .readthedocs.yaml" points
+# here. The root-level /.readthedocs.yaml is a placeholder used by the
+# import wizard and ignored for any project that has overridden the path.
+version: 2
+
+sphinx:
+  configuration: libs/interactive/docs/source/conf.py
+  fail_on_warning: true
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+  jobs:
+    post_checkout:
+      - git fetch --unshallow origin 2>/dev/null || git fetch origin main
+      # Cancel PR (external) builds that don't touch this lib (Exit 183 is RTD's
+      # signal to cancel the build immediately).
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet "origin/main...HEAD" -- libs/interactive/; then
+          echo "Skipping docs build: this PR changes nothing under libs/interactive/."
+          exit 183
+        fi
+
+python:
+  install:
+    - method: pip
+      path: libs/interactive
+      extra_requirements:
+        - docs
+
+formats:
+  - pdf

vivarium_interactive-1.0.0/CHANGELOG.rst

@@ -0,0 +1,4 @@
+**1.0.0 - 10/28/26**
+
+- Initial release: ``InteractiveContext`` split out of ``vivarium-engine`` into its own package and renamed to ``Simulation``
+- ``log_progress``, ``run_from_ipython`` and ``ObservationError`` now live here alongside ``Simulation``

vivarium_interactive-1.0.0/Jenkinsfile

@@ -0,0 +1,39 @@
+/* This Jenkinsfile simply loads the `reusable_pipeline` pipeline from the
+vivarium-build-utils package, which lives at ``libs/build-utils/`` inside the
+``ihmeuw/vivarium-suite`` monorepo (https://github.com/ihmeuw/vivarium-suite).
+
+vivarium-build-utils is loaded as a Jenkins shared library
+(https://www.jenkins.io/doc/book/pipeline/shared-libraries/).
+Jenkins shared library convention dictates that importable modules must be stored
+in the 'vars' folder.
+
+Jenkins shared libraries can be configured in the Jenkins UI:
+* Manage Jenkins
+  * Configure System
+    * Global Pipeline Libraries section
+      * Library subsection
+        * Name: The Name for the lib
+        * Version: The branch you want to use. Throws an error
+                   for nonexistent branches.
+        * Project Repository: Url to the shared lib
+        * Credentials: SSH key to access the repo
+
+Note that updating the shared repo will take effect on the next pipeline invocation.
+*/
+
+// Load the get_vbu_version function from build-utils/bootstrap/
+// (the directory to load from is defined in the Jenkins shared library configuration)
+@Library("get_vbu_version@main") _
+
+// Load the full vivarium_build_utils library at the expected version
+library("vivarium_build_utils@${get_vbu_version()}")
+
+reusable_pipeline(
+    scheduled_branches: [
+        // Add additional branches for cron jobs below.
+        // Note: Newly added branches will require a manual trigger of the first build
+        // for subsequent scheduled builds to run.
+        "main"
+    ],
+    env_reqs: "ci_jenkins",
+)

vivarium_interactive-1.0.0/LICENSE

@@ -0,0 +1,27 @@
+BSD 3-Clause License
+
+Copyright 2018 Institute for Health Metrics and Evaluation
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list
+   of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this
+   list of conditions and the following disclaimer in the documentation and/or other
+   materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may
+   be used to endorse or promote products derived from this software without specific
+   prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

vivarium_interactive-1.0.0/Makefile

@@ -0,0 +1,129 @@
+# Check if we're running in Jenkins
+ifdef JENKINS_URL
+# 	Files are already in workspace from shared library
+	MAKE_INCLUDES := .
+else
+# 	For local dev, use the installed vivarium.build_utils package if it exists
+# 	First, check if we can import vivarium.build_utils and assign 'yes' or 'no'.
+# 	We do this by importing the package in python and redirecting stderr to the null device.
+# 	If the import is successful (&&), it will print 'yes', otherwise (||) it will print 'no'.
+	VIVARIUM_BUILD_UTILS_AVAILABLE := $(shell python -c "import vivarium.build_utils" 2>/dev/null && echo "yes" || echo "no")
+# 	If vivarium.build_utils is available, get the makefiles path or else set it to empty
+	ifeq ($(VIVARIUM_BUILD_UTILS_AVAILABLE),yes)
+		MAKE_INCLUDES := $(shell python -c "from vivarium.build_utils.resources import get_makefiles_path; print(get_makefiles_path())")
+	else
+		MAKE_INCLUDES :=
+	endif
+endif
+
+# Set the package name as the last part of this file's parent directory path
+PACKAGE_NAME = $(notdir $(CURDIR))
+
+ifneq ($(MAKE_INCLUDES),) # not empty
+# Include makefiles from vivarium.build_utils
+include $(MAKE_INCLUDES)/base.mk
+include $(MAKE_INCLUDES)/test.mk
+else # empty
+# Use this help message (since the vivarium.build_utils version is not available)
+help:
+	@echo
+	@echo "For Make's standard help, run 'make --help'."
+	@echo
+	@echo "Most of our Makefile targets are provided by the vivarium.build_utils"
+	@echo "package. To access them, you need to create a development environment first."
+	@echo
+	@echo "make build-env"
+	@echo
+	@echo "USAGE:"
+	@echo "  make build-env [name=<environment name>] [py=<python version>] [artifactory_access=<yes|no>] [keep_env=<yes|no>]"
+	@echo
+	@echo "ARGUMENTS:"
+	@echo "  name [optional]"
+	@echo "      Name of the conda environment to create (defaults to <PACKAGE_NAME>)"
+	@echo "  py [optional]"
+	@echo "      Python version (defaults to latest supported)"
+	@echo "  artifactory_access [optional]"
+	@echo "      Whether the build host can reach the IHME artifactory. Either 'yes'"
+	@echo "      (default) or 'no'; use 'no' to build off-VPN without artifactory."
+	@echo "  keep_env [optional]"
+	@echo "      Whether to keep a failed build's partial environment for inspection."
+	@echo "      Either 'yes' or 'no' (default, i.e. tear it down)."
+	@echo
+	@echo "After creating the environment:"
+	@echo "  1. Activate it: 'conda activate <environment_name>'"
+	@echo "  2. Run 'make help' again to see all newly available targets"
+	@echo
+endif
+
+build-env: # Create a new environment with installed packages
+#	Validate arguments - exit if unsupported arguments are passed
+	@allowed="name py artifactory_access keep_env"; \
+	for arg in $(filter-out build-env,$(MAKECMDGOALS)) $(MAKEFLAGS); do \
+		case $$arg in \
+			*=*) \
+				arg_name=$${arg%%=*}; \
+				if ! echo " $$allowed " | grep -q " $$arg_name "; then \
+					allowed_list=$$(echo $$allowed | sed 's/ /, /g'); \
+					echo "Error: Invalid argument '$$arg_name'. Allowed arguments are: $$allowed_list" >&2; \
+					exit 1; \
+				fi \
+				;; \
+		esac; \
+	done
+	
+#   Handle arguments and set defaults
+#	name
+	@$(eval name ?= $(PACKAGE_NAME))
+#	python version - validate if specified, else get default from json file
+	@supported_versions=$$(python -c "import json; print(' '.join(json.load(open('python_versions.json'))))" 2>/dev/null || echo ""); \
+	if [ -n "$(py)" ] && ! echo "$$supported_versions" | grep -q "$(py)"; then \
+		echo "Error: Python version '$(py)' is not supported. Available: $$(echo $$supported_versions | sed 's/ /, /g')" >&2; \
+		exit 1; \
+	fi
+	@$(eval py ?= $(shell python -c "import json; print(max(json.load(open('python_versions.json')), key=lambda x: tuple(map(int, x.split('.')))))"))
+#	artifactory_access
+	@$(eval artifactory_access ?= yes)
+	@case "$(artifactory_access)" in \
+		yes|no) ;; \
+		*) echo "Error: 'artifactory_access' must be 'yes' or 'no', got '$(artifactory_access)'" >&2; exit 1 ;; \
+	esac
+#	keep_env
+	@$(eval keep_env ?= no)
+	@case "$(keep_env)" in \
+		yes|no) ;; \
+		*) echo "Error: 'keep_env' must be 'yes' or 'no', got '$(keep_env)'" >&2; exit 1 ;; \
+	esac
+
+#	Tear down on failure rather than leave an env that activates with nothing installed.
+	@if ! $(MAKE) --no-print-directory _build-env \
+			name=$(name) py=$(py) artifactory_access=$(artifactory_access); then \
+		echo >&2; \
+		if [ "$(keep_env)" = "yes" ]; then \
+			echo "Error: failed to build environment '$(name)'. Keeping it (keep_env=yes)." >&2; \
+		else \
+			echo "Error: failed to build environment '$(name)'. Removing it; pass keep_env=yes to keep it for inspection." >&2; \
+			conda env remove -n $(name) --yes; \
+		fi; \
+		exit 1; \
+	fi
+
+	@echo
+	@echo "Finished building environment"
+	@echo "  name: $(name)"
+	@echo "  python version: $(py)"
+	@echo
+	@echo "Don't forget to activate it with:"
+	@echo "conda activate $(name)"
+	@echo
+
+# Private: the build steps live here so `build-env` can tear down the env if any fails.
+.PHONY: _build-env
+_build-env:
+	conda create -n $(name) python=$(py) --yes
+# 	--no-capture-output streams output, so a failure isn't hidden behind a long silence.
+	conda run --no-capture-output -n $(name) pip install vivarium-build-utils
+# 	artifactory_access=no passes an empty IHME_PYPI, which clears base.mk's EXTRA_INDEX_FLAGS
+	conda run --no-capture-output -n $(name) make install $(if $(filter no,$(artifactory_access)),IHME_PYPI=)
+# 	A fresh env's only editable install is this checkout, so an empty list means it never installed.
+	@conda run --no-capture-output -n $(name) pip list --editable --format=freeze | grep -q . \
+		|| { echo "Error: nothing was installed into '$(name)' from $(CURDIR)." >&2; exit 1; }

vivarium_interactive-1.0.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: vivarium-interactive
+Version: 1.0.0
+Summary: Run and inspect vivarium simulations interactively, for example in a notebook.
+Author-email: The vivarium developers <vivarium.dev@gmail.com>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ihmeuw/vivarium-suite
+Project-URL: Source, https://github.com/ihmeuw/vivarium-suite/tree/main/libs/interactive
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: BSD
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: vivarium-engine<7,>=5.19.1
+Requires-Dist: vivarium-config-tree
+Requires-Dist: vivarium-dependencies[numpy,pandas]
+Requires-Dist: vivarium-build-utils<5.0.0,>=4.0.0
+Provides-Extra: interactive
+Requires-Dist: vivarium-dependencies[interactive]; extra == "interactive"
+Provides-Extra: test
+Requires-Dist: vivarium-dependencies[ipython,loguru,networkx,pytest,pyyaml]; extra == "test"
+Requires-Dist: pytest-vivarium; extra == "test"
+Requires-Dist: vivarium-fuzzy-checker; extra == "test"
+Provides-Extra: docs
+Requires-Dist: vivarium-dependencies[sphinx]; extra == "docs"
+Provides-Extra: lint
+Requires-Dist: vivarium-dependencies[lint]; extra == "lint"
+Provides-Extra: dev
+Requires-Dist: vivarium-interactive[docs,interactive,lint,test]; extra == "dev"
+Provides-Extra: cluster
+Provides-Extra: ci-github
+Requires-Dist: vivarium-interactive[docs,lint,test]; extra == "ci-github"
+Provides-Extra: ci-jenkins
+Requires-Dist: vivarium-interactive[ci_github,cluster]; extra == "ci-jenkins"
+Dynamic: license-file
+
+====================
+Vivarium Interactive
+====================
+
+.. image:: https://badge.fury.io/py/vivarium-interactive.svg
+    :target: https://badge.fury.io/py/vivarium-interactive
+
+.. image:: https://readthedocs.org/projects/vivarium-interactive/badge/?version=latest
+    :target: https://vivarium-interactive.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+This library provides ``Simulation``, a way to run and inspect a vivarium
+simulation interactively, for example in a Jupyter notebook. It steps the
+simulation on demand and exposes the population, pipelines, resources,
+and results for inspection.
+
+**Supported Python versions: 3.11, 3.12, 3.13**
+
+You can install ``vivarium-interactive`` from PyPI with pip:
+
+.. code-block:: bash
+
+   pip install vivarium-interactive
+
+or build it from source by cloning the monorepo and installing this package:
+
+.. code-block:: bash
+
+   git clone https://github.com/ihmeuw/vivarium-suite.git
+   cd vivarium-suite
+   pip install libs/interactive
+
+For broader monorepo development setup, see the monorepo README at
+https://github.com/ihmeuw/vivarium-suite.
+
+`Check out the docs! <https://vivarium-interactive.readthedocs.io/en/latest/>`_
+-------------------------------------------------------------------------------

vivarium_interactive-1.0.0/README.rst

@@ -0,0 +1,37 @@
+====================
+Vivarium Interactive
+====================
+
+.. image:: https://badge.fury.io/py/vivarium-interactive.svg
+    :target: https://badge.fury.io/py/vivarium-interactive
+
+.. image:: https://readthedocs.org/projects/vivarium-interactive/badge/?version=latest
+    :target: https://vivarium-interactive.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+This library provides ``Simulation``, a way to run and inspect a vivarium
+simulation interactively, for example in a Jupyter notebook. It steps the
+simulation on demand and exposes the population, pipelines, resources,
+and results for inspection.
+
+**Supported Python versions: 3.11, 3.12, 3.13**
+
+You can install ``vivarium-interactive`` from PyPI with pip:
+
+.. code-block:: bash
+
+   pip install vivarium-interactive
+
+or build it from source by cloning the monorepo and installing this package:
+
+.. code-block:: bash
+
+   git clone https://github.com/ihmeuw/vivarium-suite.git
+   cd vivarium-suite
+   pip install libs/interactive
+
+For broader monorepo development setup, see the monorepo README at
+https://github.com/ihmeuw/vivarium-suite.
+
+`Check out the docs! <https://vivarium-interactive.readthedocs.io/en/latest/>`_
+-------------------------------------------------------------------------------

vivarium_interactive-1.0.0/docs/nitpick-exceptions

@@ -0,0 +1,62 @@
+# numpy
+py:class np.number
+py:class np.object_
+py:class npt.NDArray
+py:class npt.NBitBase
+py:class NDArray
+py:class numpy._typing._array_like.GenericAlias
+# pandas
+py:class CategoricalDtype
+py:class pandas.api.typing.DataFrameGroupBy
+py:class pandas.core.indexes.base.Index
+py:class pandas.core.indexes.multi.MultiIndex
+py:class pandas._libs.tslibs.timestamps.Timestamp
+py:class pandas._libs.tslibs.timedeltas.Timedelta
+py:class pandas.core.frame.DataFrame
+py:class pandas.core.series.Series
+py:class pandas.core.generic.PandasObject
+py:class pandas.core.groupby.generic.DataFrameGroupBy
+py:class pd.Index
+py:class pd.Series
+py:class pd.DataFrame
+
+# loguru
+py:class loguru.Logger
+
+# networkx: the ``nx.DiGraph`` return annotation on the resource manager renders
+# as a bare ``:class:`nx.DiGraph``` cross-ref that intersphinx (whose target is
+# the qualified ``networkx.DiGraph``) can't match. autodoc-typehints also strips
+# the ``[Resource]`` parameter, so the unresolved target is always ``nx.DiGraph``.
+py:class nx.DiGraph
+
+# vivarium-config-tree: type annotations in source use the bare name
+# ``ConfigTree`` (via ``from vivarium.config_tree import ConfigTree``), which
+# autodoc-typehints renders as a bare ``:class:`ConfigTree``` cross-ref that
+# Sphinx can't match against the qualified intersphinx target. Fully-qualified
+# references (e.g. ``:class:`~vivarium.config_tree.main.ConfigTree``` in
+# docstrings/rst) resolve correctly via intersphinx; only the autodoc-derived
+# bare form needs suppression.
+py:class ConfigTree
+
+# Special methods that Sphinx can't resolve
+py:meth __init__
+py:meth __repr__
+py:meth __call__
+
+# pathlib internals
+py:class pathlib._local.Path
+
+# typing
+py:data typing.Union
+
+# vivarium-engine type aliases render as bare names that Sphinx can't match.
+py:class ClockTime
+py:class ClockStepSize
+py:class Time
+py:class Timedelta
+
+# Bare names from type hints and Raises sections that autodoc renders without a
+# module, so Sphinx can't match them.
+py:class Path
+py:class Component
+py:class LookupTable

vivarium_interactive-1.0.0/docs/source/_static/style.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 1000px !important;
+}

vivarium_interactive-1.0.0/docs/source/api_reference.rst

@@ -0,0 +1,3 @@
+.. automodule:: vivarium.interactive.simulation
+
+.. automodule:: vivarium.interactive.exceptions

vivarium_interactive-1.0.0/docs/source/conf.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Sphinx configuration for vivarium-interactive docs."""
+
+import importlib.metadata
+
+from vivarium.engine.framework.logging.utilities import configure_logging_to_terminal
+
+# Simulations add their terminal log sink once per process, bound to whatever sys.stdout
+# is at that moment. Add it now, while sys.stdout is the real terminal, so that log
+# messages don't become part of a doctest example's checked output.
+configure_logging_to_terminal(verbosity=0)
+
+# -- Project information -----------------------------------------------------
+
+project = "vivarium.interactive"
+author = "The vivarium developers"
+copyright = "2026, Institute for Health Metrics and Evaluation"
+
+version = importlib.metadata.version("vivarium-interactive")
+release = version
+
+
+# -- General configuration ------------------------------------------------
+
+needs_sphinx = "4.0"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.doctest",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+source_suffix = ".rst"
+master_doc = "index"
+language = "en"
+exclude_patterns: list[str] = []
+pygments_style = "sphinx"
+todo_include_todos = True
+
+
+# -- Options for HTML output ----------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_css_files = ["style.css"]
+html_sidebars = {
+    "**": [
+        "globaltoc.html",
+        "searchbox.html",
+    ]
+}
+
+htmlhelp_basename = f"{project}doc"
+
+
+# -- Options for LaTeX / man / texinfo output -----------------------------
+
+latex_elements: dict[str, str] = {}
+latex_documents = [
+    (master_doc, f"{project}.tex", f"{project} Documentation", author, "manual")
+]
+man_pages = [(master_doc, project, f"{project} Documentation", [author], 1)]
+texinfo_documents = [
+    (
+        master_doc,
+        project,
+        f"{project} Documentation",
+        author,
+        project,
+        "Run and inspect vivarium simulations interactively, for example in a notebook.",
+        "Miscellaneous",
+    ),
+]
+
+
+# -- Intersphinx ---------------------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "tables": ("https://www.pytables.org/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "networkx": ("https://networkx.org/documentation/stable/", None),
+    # Sibling monorepo libs whose docs these docs reference.
+    "vivarium_config_tree": ("https://vivarium-config-tree.readthedocs.io/en/latest/", None),
+    "vivarium_engine": ("https://vivarium-engine.readthedocs.io/en/latest/", None),
+}
+
+
+# -- Autodoc configuration ------------------------------------------------
+
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": True,
+    "private-members": False,
+}
+autodoc_typehints = "description"
+
+
+# -- nitpicky mode --------------------------------------------------------
+
+nitpicky = True
+
+nitpick_ignore: list[tuple[str, str]] = []
+with open("../nitpick-exceptions") as f:
+    for line in f:
+        if line.strip() == "" or line.startswith("#"):
+            continue
+        dtype, target = line.split(None, 1)
+        target = target.strip()
+        nitpick_ignore.append((dtype, target))

vivarium_interactive-1.0.0/docs/source/index.rst

@@ -0,0 +1,18 @@
+====================
+Vivarium Interactive
+====================
+
+This package provides :class:`~vivarium.interactive.simulation.Simulation`, a way to run
+and inspect a `vivarium <https://vivarium-engine.readthedocs.io/en/latest/>`_
+simulation interactively, for example in a Jupyter notebook.
+
+It is one of the libraries in the
+`vivarium-suite <https://github.com/ihmeuw/vivarium-suite>`_ monorepo, maintained
+by the Institute for Health Metrics and Evaluation's Simulation Science team.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/interactive
+   tutorials/exploration
+   api_reference