35 lines
2.7 KiB
Markdown
35 lines
2.7 KiB
Markdown
# 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.
|