[Release] v0.3.0

.github/CODEOWNERS

@@ -0,0 +1,23 @@
+# This file contains the CODEOWNERS of hep-ce. It is used to determine 
+# required reviews on Pull Requests. Each line is a file pattern followed 
+# by one or more owners.
+
+# These owners will be the default owners for everything in
+# the repo. Unless a later match takes precedence,
+# @MJC598 and @ddbaptiste will be requested for
+# review when someone opens a pull request.
+*       @MJC598 @ddbaptiste
+
+# Order is important; the last matching pattern takes the most
+# precedence. When someone opens a pull request that only
+# modifies R or C++ files, only @the specified teams and not the global
+# owner(s) will be requested for a review.
+
+# Teams can be specified as code owners as well. Teams should
+# be identified in the format @org/team-name. Teams must have
+# explicit write access to the repository.
+*.R @SyndemicsLab/Analysts @SyndemicsLab/Developers
+*.py @SyndemicsLab/Developers
+*.cpp @SyndemicsLab/Developers
+*.hpp @SyndemicsLab/Developers
+*.sh @SyndemicsLab/Developers

.github/workflows/testing.yml

@@ -87,9 +87,3 @@ jobs:
 
             - name: Run tests with coverage
               run: uv run pytest --cov=respondpy --cov-report=term-missing --cov-report=xml tests
-
-            - name: Upload coverage to Codecov
-              uses: codecov/codecov-action@v5
-              with:
-                  token: ${{ secrets.CODECOV_TOKEN }}
-                  slug: SyndemicsLab/respondpy

CMakeLists.txt

@@ -62,8 +62,7 @@ set(SPDLOG_INSTALL ON)
 FetchContent_Declare(
     respond
     GIT_REPOSITORY https://github.com/SyndemicsLab/respond.git
-    GIT_TAG e9a452e7082b785978e66907b17af4db8b9bed53 # v2.4.1
-    #dcba9320f04dcac0fd161bb86ed3f04a1c016b65 # v2.5.0
+    GIT_TAG 2bc260ef749a76b7eba73a4d64e9d38c48ed2bdc # v2.5.1
     OVERRIDE_FIND_PACKAGE
 )
 set(RESPOND_BUILD_DOCS OFF)

README.md

@@ -32,3 +32,22 @@ This results in a wheel and `tar.gz` being placed in a `dist/` directory. From h
 ## Supported OSes
 
 We are currently working on supporting as many OSes as possible. As these are bindings for a C++ project, we are limited in our capacity. For the moment, we are generating many linux builds for python versions >= 3.10. We do not have a Windows or Mac build at the present.
+
+## Binding Parity Checklist
+
+Use this checklist when updating bindings, stubs, or API docs.
+
+- Run smoke tests: `uv run pytest -m smoke`
+- [ ] Runtime vs stubs parity:
+	- [ ] Confirm pybind runtime signatures and return shapes match `.pyi` annotations.
+	- [ ] Confirm enum members and bound method names match stub names exactly.
+	- [ ] Confirm overload behavior matches typed expectations.
+- [ ] Runtime vs docs parity:
+	- [ ] Confirm binding docstrings describe actual runtime return types and side effects.
+	- [ ] Confirm parameter defaults in docs match bound defaults.
+- [ ] Expected-failure messaging parity:
+	- [ ] Confirm incorrect arguments raise errors with stable, informative message patterns.
+	- [ ] Prefer regex pattern assertions in tests over exact full-message equality.
+- [ ] Smoke coverage scope:
+	- [ ] Runtime binding smoke lives in `tests/test_smoke_bindings_runtime.py`.
+	- [ ] Stub smoke via `mypy` in pytest lives in `tests/test_smoke_stubs_mypy.py`.

docs/source/conf.py

@@ -22,11 +22,14 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
-    'myst_parser'
+    'myst_parser',
+    'sphinxcontrib.mermaid'
 ]
 
 templates_path = ['_templates']
 exclude_patterns = []
+source_suffix = {".md": "markdown", ".rst": "restructuredtext"}
+myst_fence_as_directive = ["mermaid"]
 
 
 # -- Options for HTML output -------------------------------------------------

docs/source/explanations/architecture.md

@@ -1,97 +1,67 @@
 # Architecture
 
-This page summarizes the public surface and runtime flow of respondpy.
+This section explains the public API and runtime behavior of respondpy.
+It is intentionally conceptual: there are no references pages here and no
+how-to recipes.
 
-## Public API
+If you need task-oriented steps, use [How-To Guides](../how_to/data_loading.md).
+If you need API signatures and symbol-level details, use
+[References](../references/wrapper_typing.md).
+If you want guided learning exercises, use
+[Tutorials](../tutorials/base_respond.md).
+
+```{toctree}
+:maxdepth: 1
+
+public-api
+object-lifecycle
+data-flow
+runtime-execution
+```
+
+## Overview
 
 ```mermaid
 flowchart LR
-	subgraph Pkg[respondpy package]
+	subgraph Public[respondpy public surface]
 		data[data]
-		discount[discount]
-		cwise_product[cwise_product]
-		cwise_min[cwise_min]
-		calculate_life_years[calculate_life_years]
-
+		cost[cost_effectiveness]
 		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]
-
+		Timestep[Timestep]
 		Transition[Transition]
-		transition_factory[transition_factory]
-		build_timestep_transition[build_timestep_transition]
+		build_simulation[build_simulation]
+		build_model[build_model]
+		build_timestep[build_timestep]
+		build_default_transitions[build_default_transitions]
+		build_transition[build_transition]
+		add_matrix_to_transition[add_matrix_to_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"]
+	build_timestep --> Timestep
+	build_default_transitions --> Transition
+	build_transition --> Transition
+	add_matrix_to_transition --> Transition
+	Simulation --> History
+	data --> Model
+	data --> Transition
 ```
 
-## UML Library Flow
+## Scope
 
 ```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
+flowchart TB
+	A[Public API]
+	B[Core runtime objects]
+	C[Data access and validation]
+	D[Simulation assembly helpers]
+	E[Execution and output flow]
 
-	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
+	A --> B
+	A --> C
+	A --> D
+	A --> E
 ```

docs/source/explanations/data-flow.md

@@ -0,0 +1,56 @@
+# Explanation: Data Flow
+
+This page follows the path from persisted RESPOND inputs to model-ready arrays
+and transition matrices.
+
+See also:
+- [How-To: Load RESPOND Input Data](../how_to/load_input_data.md)
+- [References: respondpy.data](../references/data.md)
+- [Tutorial: Parameter Change-Time Experiment](../tutorials/parameter_change_experiment.md)
+
+## Input Processing
+
+```mermaid
+flowchart LR
+	A[SQLite database] --> B[Input]
+	C[sim.conf] --> B
+	B --> D[Parameter]
+	D --> E[select_parameter]
+	E --> F[Raw rows or numpy arrays]
+```
+
+## Parameter Mapping
+
+```mermaid
+flowchart TB
+	A[ParameterType]
+	A --> B[INITIAL_COHORT]
+	A --> C[MIGRATION_COHORT]
+	A --> D[INTERVENTION_TRANSITION_PROBABILITY]
+	A --> E[BEHAVIOR_TRANSITION_PROBABILITY]
+	A --> F[OVERDOSE_PROBABILITY]
+	A --> G[OVERDOSE_FATALITY_PROBABILITY]
+	A --> H[BACKGROUND_DEATH_PROBABILITY]
+	A --> I[STANDARD_MORTALITY_RATIO]
+
+	D --> J[transition matrix columns]
+	E --> J
+	F --> K[probability column]
+	G --> K
+	H --> K
+	I --> L[ratio column]
+	B --> M[count column]
+	C --> M
+```
+
+## Validation and Normalization
+
+```mermaid
+flowchart LR
+	A[change-time values] --> B[validate_time_list]
+	B --> C[normalized ascending times]
+	D[transition rows] --> E[verify_no_nulls]
+	D --> F[verify_no_duplicates]
+	D --> G[update_retention_probability]
+	G --> H[normalized transitions]
+```

docs/source/explanations/object-lifecycle.md

@@ -0,0 +1,69 @@
+# Explanation: Object Lifecycle
+
+This page describes the main runtime objects and how ownership flows through
+the simulation assembly process.
+
+See also:
+- [How-To: Build a Single Cohort Model](../how_to/single_model_build.md)
+- [References: Runtime Objects](../references/runtime_objects.md)
+- [Tutorial: First End-to-End Simulation Run](../tutorials/first_run.md)
+
+## Runtime Ownership
+
+```mermaid
+flowchart TB
+	User[User code] --> In[Input]
+	In --> BS[build_simulation]
+	BS --> Sim[Simulation]
+	BS --> BM[build_model]
+	BM --> Mod[Model]
+	BM --> BT[build_timestep]
+	BT --> TS[Timestep]
+	BT --> Tr[Transition]
+	TS --> Mod
+	Mod --> Sim
+	Sim --> Hist[History]
+```
+
+## Class Roles
+
+```mermaid
+classDiagram
+	class Input {
+	  +config
+	  +select_parameter()
+	  +get_cohort_ids()
+	}
+
+	class Model
+	class Simulation {
+	  +set_duration()
+	  +add_model()
+	  +run()
+	}
+	class Timestep {
+	  +add_transition()
+	}
+	class Transition {
+	  +add_matrix()
+	}
+	class History
+
+	Simulation "1" o-- "many" Model
+	Model "1" o-- "many" Timestep
+	Timestep "1" o-- "many" Transition
+	Simulation ..> History : returns
+	Input ..> Model : initial state lookup
+	Input ..> Transition : parameter lookup
+```
+
+## Assembly Boundaries
+
+```mermaid
+flowchart LR
+	A[Data access] --> B[Model construction]
+	B --> C[Timestep assembly]
+	C --> D[Transition population]
+	D --> E[Simulation execution]
+	E --> F[History output]
+```