Merge pull request #3 from dsih-artpark/feature

PyPI readiness: Finalization of patchsim

Author: snehasaisneha

.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

CHANGELOG.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:

README.md

@@ -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"

configs/sample-sir-ode.yaml

@@ -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/networks/sample-network-static.csv

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