Repository Guidelines

Project Structure & Module Organization

Core simulation: simulation_model.py (Mesa Model), production_line.py, demand_agent.py.
UI & orchestration: app.py (Solara dashboard, matplotlib plotting, loads data/<year> based on year.json).
Optimization helpers: genetic_calibration.py, ga_two_factor_calibration.py, build_distance_matrix.py.
Data: data/<year>/ CSV/JSON inputs and outputs; temporary artifacts can live in output/.

Create env: conda env create -f environment.yml then conda activate gw.
Launch dashboard locally: solara run app.py --host 0.0.0.0 --port 8765 (loads year set in year.json).
Recompute distance matrix when locations change: python build_distance_matrix.py.
Run calibration scripts headless: python genetic_calibration.py or python ga_two_factor_calibration.py (writes tuned params under data/<year>).

Follow Python 3.13 + PEP 8; 4-space indents; prefer type hints and docstrings for public functions/classes.
Use snake_case for variables/functions/modules, CapWords for classes, and descriptive names for data columns.
Keep plotting/fonts consistent with existing matplotlib config (Chinese labels enabled); reuse helpers instead of duplicating logic.
Guard data-file access with clear error messages and UTF-8/GBK fallbacks as seen in app.py.

No formal suite exists yet; add pytest-style tests under tests/ when feasible, mocking file I/O and using small sample CSVs.
For quick checks, run calibration scripts on a narrowed product set and validate outputs in output/ or data/<year> before committing.
Validate UI flows by running solara and confirming charts render and download links work for the target year.

Commit messages: short, imperative summaries (e.g., Add capacity cap to Shenzhen lines); keep body focused on rationale and data assumptions.
PRs should include: scope summary, affected year(s) in data/, before/after metrics or screenshots for UI changes, and steps to reproduce or rerun (solara run ..., script commands).
Link related issues/requests and note any regenerated files (e.g., distance_matrix.csv, calibration outputs) so reviewers can verify.

Set year.json to the active dataset before running any scripts; keep year directories consistent (data/2025, data/2026, etc.).
Preserve CSV headers and encodings; when adding factories/products, update factory_mapping.json and rerun distance matrix generation.
Avoid committing large intermediate artifacts under output/ unless they are required inputs; prefer deterministic script outputs for reviewability.