# 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/`.

## Setup, Build, and Run
- 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>`).

## Coding Style & Naming Conventions
- 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`.

## Testing Guidelines
- 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 & Pull Request Guidelines
- 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.

## Data & Configuration Tips
- 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.