PyPI readiness: Finalization of patchsim

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main, feature, dev, develop]
+  pull_request: null
+
+jobs:
+  test-and-lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Sync dependencies (including dev)
+        run: uv sync --extra dev --frozen
+
+      - name: Ruff lint
+        run: uv run --no-sync --frozen ruff check .
+
+      - name: Ruff format check
+        run: uv run --no-sync --frozen ruff format --check .
+
+      - name: Run tests
+        run: uv run --no-sync --frozen pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test-and-lint
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Sync dependencies
+        run: uv sync --frozen
+
+      - name: Build package
+        run: uv build

.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: null
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    environment:
+      name: pypi
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Sync dependencies (including dev)
+        run: uv sync --extra dev --frozen
+
+      - name: Lint
+        run: uv run --no-sync --frozen ruff check .
+
+      - name: Format check
+        run: uv run --no-sync --frozen ruff format --check .
+
+      - name: Test
+        run: uv run --no-sync --frozen pytest -q
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -85,7 +85,7 @@ profile_default/
 ipython_config.py
 
 # pyenv
-.python-version
+# .python-version is tracked for CI reproducibility
 
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
@@ -152,6 +152,16 @@ dmypy.json
 *.xlsx
 output/**
 
+# Keep package template scaffold files tracked
+!src/patchsim/templates/project/data/
+!src/patchsim/templates/project/data/networks/
+!src/patchsim/templates/project/data/networks/*.csv
+!src/patchsim/templates/project/data/patch/
+!src/patchsim/templates/project/data/patch/*.csv
+!src/patchsim/templates/project/data/seeds/
+!src/patchsim/templates/project/data/seeds/*.csv
+!src/patchsim/templates/project/output/.gitkeep
+
 # Additions for GeoJSON, .zip files, and shapefiles
 *.geojson
 *.zip
@@ -164,4 +174,15 @@ output/**
 .pdm-build/
 
 # Exception for .png files in assets/
-!assets/*.png
+!assets/*.png
+
+# Allow tracked data CSVs
+!data/
+!data/networks/
+!data/networks/*.csv
+
+!data/patch/
+!data/patch/*.csv
+
+!data/seeds/
+!data/seeds/*.csv

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

.python-version

@@ -0,0 +1 @@
+3.11

README.md

@@ -15,6 +15,27 @@ To develop a general-purpose, modular simulation framework for patch-based metap
 
 ---
 
+## Unique Selling Point (USP)
+
+PatchSim combines metapopulation network dynamics with a lightweight, configuration-first workflow:
+
+- Network-aware compartment transitions across connected patches
+- Arrow-map transition syntax in YAML for explicit model specification
+- Fast iteration loop from config edits to reproducible outputs
+
+---
+
+## Unique Value Proposition (UVP)
+
+Compared to many epidemiology tools that are either code-heavy or tightly bound to a specific disease model, PatchSim offers:
+
+- **Model flexibility**: define SIR/SIRS-style variants through config transitions
+- **Research-friendly reproducibility**: deterministic inputs, logged runs, and versioned config files
+- **Dual interface**: SDK import for programmatic workflows and CLI for operational runs
+- **Extensibility path**: built-in structure for adding custom models and project templates
+
+---
+
 ## Core Features
 
 PatchSim aims to support a range of modelling features commonly used in metapopulation disease simulations:
@@ -40,7 +61,13 @@ PatchSim aims to support a range of modelling features commonly used in metapopu
 
 ## Installation
 
-To install PatchSim using [uv](https://github.com/astral-sh/uv):
+Install from PyPI:
+
+```bash
+pip install patchsim
+```
+
+Install from source using [uv](https://github.com/astral-sh/uv):
 
 ```bash
 # Clone the repository
@@ -62,17 +89,36 @@ uv pip install -e .[dev]
 
 ### Command Line Interface
 
-PatchSim provides a command-line interface for running simulations:
+PatchSim provides a subcommand-based CLI. Always run using `uv run` to ensure correct dependency resolution:
 
 ```bash
 # Show help and available options
-patchsim --help
+uv run patchsim --help
+
+# Show package version
+uv run patchsim --version
+
+# Initialize a new self-contained project
+uv run patchsim init my-project
+
+# Validate config without running
+uv run patchsim validate -c my-project/config.yaml
+
+# Run simulation
+uv run patchsim run -c my-project/config.yaml
+
+# List built-in models
+uv run patchsim list-models
+```
+
+### Python SDK
 
-# Run simulation with sample SIR model
-patchsim --config configs/sample-sir-ode.yaml
+```python
+import patchsim
 
-# Run simulation with custom model
-patchsim --config path/to/your/config.yaml
+config = patchsim.load_config("config.yaml")
+net, y0, patches, n = patchsim.setup_simulation(config)
+patchsim.run_simulation(config, "my-model", net, y0, patches, n)
 ```
 
 The simulation outputs are saved in the following structure:

configs/sample-sir-ode.yaml

@@ -15,6 +15,10 @@ StartDate: 2020-01-01
 EndDate: 2022-12-31
 OutputDir: output/sample-sir-ode
 compartments: ["S", "I", "R"]
-Parameters: {"beta": 0.5, "gamma": 0.1}
-Transitions: [{"from": "S", "to": "I", "rate": "beta * S * I / (S + I + R)"}, {"from": "I", "to": "R", "rate": "gamma * I"}]
-
+Parameters:
+  beta: 0.08
+  gamma: 0.1
+#PatchParameters: [{"patch": "PatchA", "parameters": {"beta": 0.2, "gamma": 0.1}}, {"patch": "PatchB", "parameters": {"beta": 0.25, "gamma": 0.1}}]
+Transitions:
+  "S -> I": "beta"
+  "I -> R": "gamma * I"

data/networks/sample-network-static.csv

@@ -0,0 +1,5 @@
+day,source,target,weight
+0,A,A,0.9
+0,A,B,0.1
+0,B,B,0.9
+0,B,A,0.1

data/patch/sample-sir-ode-patch-population.csv

@@ -0,0 +1,3 @@
+patch,Population
+A, 1000
+B, 500

data/seeds/sample-sir-ode-patchA-2.csv

@@ -0,0 +1,3 @@
+patch,S,I,R
+A,999,1,0
+B,500,0,0

docs/architecture.md

@@ -0,0 +1,25 @@
+
+# Architecture
+
+PatchSim follows a layered architecture:
+
+## Core components
+
+### Patch
+Represents a single subpopulation with:
+- Fixed population size
+- Compartment state vector
+- Parameter dictionary
+- Validation logic
+
+### Network
+Defines interactions between patches via a weighted directed graph.
+
+### Model
+Orchestrates:
+- ODE construction
+- Numerical integration
+- Visualization of results
+
+This separation ensures that changes to network structure do not require
+rewriting patch-level dynamics.

docs/configuration.md

@@ -0,0 +1,30 @@
+# Configuration
+
+PatchSim simulations are configured using YAML files.
+
+## Model definition
+
+```yaml
+# Input files (required)
+PatchFile: data/patch/patch-population.csv
+NetworkFile: data/networks/network.csv
+SeedFile: data/seeds/seed-initial.csv
+
+# Model configuration
+ModelName: sample-sir-ode
+
+# Simulation parameters
+TMax: 50
+Tolerance: 1e-8
+MaxIter: 10000
+StartDate: 2020-01-01
+EndDate: 2022-12-31
+OutputDir: output/sample-sir-ode
+compartments: ["S", "I", "R"]
+Parameters:
+  beta: 0.08
+  gamma: 0.1
+Transitions:
+  "S -> I": "beta"
+  "I -> R": "gamma * I"
+```

docs/getting-started.md

@@ -0,0 +1,23 @@
+
+
+# Getting Started
+
+## Installation
+
+### From PyPI (Recommended)
+
+Install patchsim from PyPI:
+
+```bash
+pip install patchsim
+```
+
+### For Contributors
+
+Clone the repository and install in editable mode for development:
+
+```bash
+git clone https://github.com/dsih-artpark/patchsim.git
+cd patchsim
+pip install -e .
+```

docs/index.md

@@ -1,13 +1,25 @@
 # PatchSim
 
-PatchSim is a modular, general-purpose metapopulation epidemiological simulation framework designed for research and translation use cases. 
+PatchSim is a modular, general-purpose metapopulation epidemiological simulation framework designed for research and translation use cases. It is a flexible and modular system for simulating epidemiological compartment models across single or multiple interacting patches.
 
+The framework generalizes classical compartmental models (e.g. SIR) by allowing multiple subpopulations ("patches") to interact through a weighted directed network.
+
+PatchSim emphasizes:
+- Explicit separation between patch dynamics and network structure
+- Continuous-time ODE-based simulation
+- Configurable parameters via YAML
+- Extensibility toward richer network and mobility models
+
 ## Features
-- ODE and discrete-time simulation modes
-- Supports multiple diseases and problem types
-- Integrated CLI for running models
-- Built-in reproducibility and parameter management
-- Extensible and user-friendly
+
+- **Flexible Compartment Models**: Define custom SIR, SEIR, or other compartmental models that support multiple diseases and problem types
+- **Multi-Patch Networks**: Simulate disease spread across connected geographical regions
+- **CLI Integration**: Integrated CLI for running models
+- **Multiple Simulation Methods**: Support for both ODE and discrete-time simulation modes
+- **YAML Configuration**: Structured, readable configuration files
+- **Per-Patch Parameters**: Built-in reproducibility and management of different parameters for each patch
+- **Network Connectivity**: Define custom mixing matrices between patches
+- **Extensibility**: Extensible and user-friendly
 
 ## Documentation
 - [Core Module](reference/core.md)