Documentation/15 07 26/sphinx and uml

CMakeLists.txt

@@ -63,6 +63,7 @@ FetchContent_Declare(
     respond
     GIT_REPOSITORY https://github.com/SyndemicsLab/respond.git
     GIT_TAG e9a452e7082b785978e66907b17af4db8b9bed53 # v2.4.1
+    #dcba9320f04dcac0fd161bb86ed3f04a1c016b65 # v2.5.0
     OVERRIDE_FIND_PACKAGE
 )
 set(RESPOND_BUILD_DOCS OFF)

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,36 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import sys
+from pathlib import Path
+
+# Add the src directory to the Python path
+sys.path.insert(0, str(Path('../..', 'src').resolve()))
+
+project = 'respondpy'
+copyright = '2026, Syndemics Lab at Boston Medical Center '
+author = 'Matthew Carroll, Dimitri Baptiste'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'myst_parser'
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

docs/source/explanations/architecture.md

@@ -0,0 +1,97 @@
+# Architecture
+
+This page summarizes the public surface and runtime flow of respondpy.
+
+## Public API
+
+```mermaid
+flowchart LR
+	subgraph Pkg[respondpy package]
+		data[data]
+		discount[discount]
+		cwise_product[cwise_product]
+		cwise_min[cwise_min]
+		calculate_life_years[calculate_life_years]
+
+		History[History]
+		Model[Model]
+		build_model[build_model]
+		add_transitions_to_model[add_transitions_to_model]
+		build_model_transitions[build_model_transitions]
+
+		Simulation[Simulation]
+		build_simulation[build_simulation]
+
+		Transition[Transition]
+		transition_factory[transition_factory]
+		build_timestep_transition[build_timestep_transition]
+	end
+
+	build_simulation --> Simulation
+	build_model --> Model
+	add_transitions_to_model --> Model
+	build_model_transitions --> Model
+	transition_factory --> Transition
+	build_timestep_transition --> Transition
+```
+
+## Execution Diagram
+
+```mermaid
+flowchart LR
+	A[Input initialized with DB + sim.conf] --> B["build_simulation(input_data, cohort_ids)"]
+	B --> C{Iterate cohort ids}
+	C --> D["build_model(input_data, cohort_id)"]
+	D --> E["input_data.select_parameter(INITIAL_COHORT, cohort_id, time=1)"]
+	E --> F["Model.set_state(initial_population)"]
+	F --> G["build_model_transitions(model, input_data, cohort_id)"]
+	G --> H["build_timestep_transition(timestep, input_data, cohort_id)"]
+	H --> I["migration transition"]
+	H --> J["intervention transition"]
+	H --> K["behavior transition"]
+	H --> L["overdose transition"]
+	H --> M["background death transition"]
+	I --> N["add_transitions_to_model"]
+	J --> N
+	K --> N
+	L --> N
+	M --> N
+	N --> O["Simulation.add_model(model)"]
+	O --> P["Simulation.run()"]
+	P --> Q["get_model_sparse_histories() -> History objects"]
+```
+
+## UML Library Flow
+
+```mermaid
+sequenceDiagram
+	autonumber
+	actor User
+	participant In as Input
+	participant BS as build_simulation()
+	participant BM as build_model()
+	participant BMT as build_model_transitions()
+	participant BTT as build_timestep_transition()
+	participant Sim as Simulation
+	participant Mod as Model
+	participant Tr as Transition
+	participant Hist as History
+
+	User->>In: create Input(path or db_path/conf_path)
+	User->>BS: build_simulation(In, cohort_ids)
+	loop for each cohort_id
+		BS->>BM: build_model(In, cohort_id)
+		BM->>In: select_parameter(INITIAL_COHORT, cohort_id, time=1)
+		BM->>Mod: set_state(initial_population)
+		BM->>BMT: build_model_transitions(Mod, In, cohort_id)
+		loop for each timestep
+			BMT->>BTT: build_timestep_transition(timestep, In, cohort_id)
+			BTT-->>BMT: [migration, intervention, behavior, overdose, mortality]
+			BMT->>Mod: add_transition(Transition...)
+		end
+		BS->>Sim: add_model(Mod)
+	end
+	User->>Sim: run()
+	User->>Sim: get_model_sparse_histories()
+	Sim-->>Hist: return per-model History objects
+```

docs/source/how_to/data_loading.md

@@ -0,0 +1,3 @@
+# How-To Load Data
+
+Loading data

docs/source/index.rst

@@ -0,0 +1,22 @@
+.. respondpy documentation master file, created by
+   sphinx-quickstart on Wed Jul 15 14:57:47 2026.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to respondpy's documentation!
+=======================
+
+**respondpy** is a Python library for wrapping and interacting with the `RESPOND simulation model`_ C++ API. It provides a convenient and Pythonic interface for users to access the functionality of RESPOND, enabling seamless integration with Python applications.
+
+.. _RESPOND simulation model: https://github.com/SyndemicsLab/respond.git
+
+.. note::
+    This project is under active development, and the API may change in future releases. Users are encouraged to check the documentation for updates and refer to the source code for the latest features.
+
+.. toctree::
+   :maxdepth: 2
+
+   explanations/architecture
+   how_to/data_loading
+   references/wrapper_typing
+   tutorials/base_respond

docs/source/references/wrapper_typing.md

@@ -0,0 +1,3 @@
+# Wrapper Typing
+
+How the wrapper typing works between Python and C++

docs/source/tutorials/base_respond.md

@@ -0,0 +1,3 @@
+# Building and Running Base RESPOND
+
+Tutorial 1

pyproject.toml

@@ -45,7 +45,7 @@ Issues = "https://github.com/SyndemicsLab/respond/issues"
 [dependency-groups]
 docs = [
     "ipython",
-    "myst_parser>=0.13",
+    "myst-parser>=0.13",
     "nbsphinx",
     "sphinx-book-theme>=0.0.33",
     "sphinx>=4.0",
@@ -78,6 +78,7 @@ build.verbose = true
 logging.level = "INFO"
 minimum-version = "build-system.requires"
 cmake.version = ">=3.27.0"
+cmake.build-type = "Release"
 ninja.version = ">=1.11"
 sdist.exclude = [
     ".github/*",
@@ -87,7 +88,6 @@ sdist.exclude = [
 sdist.include = [
     "src/respondpy/_version.py"
 ]
-cmake.build-type = "Release"
 messages.after-success = "{green}Wheel successfully built"
 messages.after-failure = """
 {bold.red}Sorry{normal}, build failed. Your platform is {platform.platform}.
@@ -119,11 +119,11 @@ filterwarnings = [
     "default:could not create cache path:pytest.PytestCacheWarning",
 ]
 log_level = "INFO"
-markers = ["smoke", "unit", "benchmark"]
+markers = ["smoke", "unit", "integration", "benchmark"]
 required_plugins = ["pytest-benchmark"]
 
 [tool.coverage.run]
-omit = ["tests/*"]
+omit = ["tests/*", "docs/*", "benchmarks/*", "src/respondpy/_version.py"]
 
 [tool.coverage.report]
 exclude_also = [

src/respondpy/_core/simulation.pyi

@@ -4,7 +4,7 @@
 # Created Date: 2026-02-09                                                     #
 # Author: Matthew Carroll                                                      #
 # -----                                                                        #
-# Last Modified: 2026-06-16                                                    #
+# Last Modified: 2026-06-29                                                    #
 # Modified By: Matthew Carroll                                                 #
 # -----                                                                        #
 # Copyright (c) 2026 Syndemics Lab at Boston Medical Center                    #

src/respondpy/_utils.py

@@ -17,9 +17,21 @@ def str_to_int_list(config_string: str, *, delimiter: str = ',') -> list[int]:
 
     Whitespace around each token is stripped before conversion.
 
-    :param config_string: Delimited string of integer-like values.
-    :param delimiter: Token delimiter used to split ``config_string``.
-    :returns: Parsed integers in input order.
-    :raises ValueError: If any token cannot be converted to ``int``.
+    Parameters
+    ----------
+    config_string : str
+        Delimited string of integer-like values.
+    delimiter : str, default=","
+        Token delimiter used to split ``config_string``.
+
+    Returns
+    -------
+    list of int
+        Parsed integers in input order.
+
+    Raises
+    ------
+    ValueError
+        If any token cannot be converted to ``int``.
     """
     return [int(x.strip()) for x in config_string.split(delimiter)]