# Repository Guidelines

## Project Structure & Module Organization

- `*.py`: Standalone analysis/optimization scripts (run directly with Python).
  - `kmin_effectiveness.py`: k-min vs effectiveness/fairness analysis; writes artifacts to `data/`.
  - `fairness_optimization.py`, `analyze_visits.py`, `plot_sites.py`: additional analyses/plots.
- `prob/`: Problem statement and source dataset (e.g., `prob/MFP Regular Sites 2019.xlsx`).
- `latex-template/`: Report template and compilation assets.
- `data/` (generated): Output CSV/PNG artifacts produced by scripts.

## Build, Test, and Development Commands

This repo is script-driven (no package build step).

- Run k-min analysis: `python3 kmin_effectiveness.py`
  - Outputs: `data/kmin_effectiveness.png`, `data/kmin_effectiveness_data.csv`, `data/kmin_effectiveness_sites.csv`
- Run visit analysis: `python3 analyze_visits.py` (generates plots in the workspace)
- Run site map: `python3 plot_sites.py`
- Quick syntax check: `python3 -m py_compile kmin_effectiveness.py`

Dependencies commonly used: `numpy`, `pandas`, `matplotlib`, plus Excel readers like `openpyxl`.

## Coding Style & Naming Conventions

- Python: 4-space indentation; keep scripts runnable as `python3 <script>.py`.
- Prefer descriptive names (`k_min`, `total_demand`) and Chinese comments/docstrings where already used.
- Output files should be written under `data/` and named predictably (e.g., `kmin_effectiveness_*.csv/png`).

## Testing Guidelines

There is no formal test suite currently. When changing math/metrics:

- Add a small deterministic check (e.g., `py_compile`, or seed-controlled simulation runs).
- Prefer reproducible randomness via explicit seeds (see `RANDOM_SEED` in `kmin_effectiveness.py`).

## Commit & Pull Request Guidelines

Commit history uses short subjects, sometimes with prefixes (e.g., `P1:` / `add:`). Follow this pattern:

- Keep messages concise and action-oriented (e.g., `P1: add gini plot`).
- PRs should include: what changed, which script(s) to run, and expected outputs (file names under `data/`).