Dev

README.md

@@ -1,50 +1,133 @@
-# PROPAGATOR: An Operational Cellular-Automata Based Wildfire Simulator
+# PROPAGATOR: An Operational Cellular-Automata Wildfire Simulator
 
-This repository contains the python implementation of the PROPAGATOR wildfire simulation algorithm, developed by CIMA Research Foundation.
-The package contains the core simulation engine in the `core` module, I/O utilities in the `io` module, and a command line interface (CLI) in the `cli` module.
+PROPAGATOR is an operational wildfire spread model developed by
+[CIMA Research Foundation](https://www.cimafoundation.org). The project couples
+a Numba-accelerated cellular automata core (`propagator.core`), reusable I/O
+pipelines (`propagator.io`), and a configurable CLI for stochastic
+fire propagation modeling. Comprehensive documentation lives under `docs/`, covering quick starts, API reference, and
+programmatic guides.
 
-Link to the research paper: [PROPAGATOR: An Operational Cellular-Automata Based Wildfire Simulator](https://www.mdpi.com/2571-6255/3/3/26)
+## Quick Start
 
-## How to use it as a library
-
-Install the package using pip, poetry, uv or any other tool that can install from a git repository.
+Clone the repository and create an environment with the CLI and I/O extras:
 
 ```bash
-pip install git+https://github.com/CIMAFOUNDATION/propagator_sim.git
+uv sync --dev --all-extras
 ```
 
-Then, you can use the `propagator` package in your python code.
-This command will install the latest version from the `main` branch. It will resolve to the minimal dependencies for the core simulation engine.
-If you want to use the I/O utilities or the CLI, you need to install the extra dependencies as well.
+or, using plain `pip`:
 
 ```bash
-pip install git+https://github.com/CIMAFOUNDATION/propagator_sim.git[io,cli]
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[cli,io]'
 ```
 
-You can find an example of how to use the package in the `examples/example.py` file.
+This installs the PROPAGATOR package in editable mode together with the optional
+extras required for raster handling, the CLI, and documentation tooling.
 
-## How to develop
+## Running Simulations
 
-Clone this repository. Use `uv sync --dev --all-extras` to create a virtual environment and install the required dependencies.
+Launch the CLI over the bundled GeoTIFF sample:
 
 ```bash
-uv sync
+uv run propagator \
+  --config example/config.json \
+  --mode geotiff \
+  --dem example/dem.tif \
+  --fuel example/veg.tif \
+  --output results/quickstart
 ```
 
-## Launch a simulation
-
-
-```bash
-uv run propagator
+See `uv run propagator --help` or `docs/cli.md` for the full argument table.
+
+### Programmatic API
+
+You can embed PROPAGATOR directly into Python workflows:
+
+```python
+import numpy as np
+from propagator.core import BoundaryConditions, FUEL_SYSTEM_LEGACY, Propagator
+
+dem = np.zeros((2000, 2000), dtype=np.float32)
+veg = np.full_like(dem, 5, dtype=np.int32)
+
+sim = Propagator(
+    dem=dem,
+    veg=veg,
+    realizations=10,
+    fuels=FUEL_SYSTEM_LEGACY,
+    do_spotting=False,
+    out_of_bounds_mode="raise",
+)
+
+ignition_mask = np.zeros_like(dem, dtype=np.uint8)
+ignition_mask[dem.shape[0] // 2, dem.shape[1] // 2] = 1
+
+sim.set_boundary_conditions(
+    BoundaryConditions(
+        time=0,
+        ignition_mask=ignition_mask,
+        wind_speed=np.ones_like(dem) * 40,
+        wind_dir=np.ones_like(dem) * 90,
+        moisture=np.zeros_like(dem),
+    )
+)
+
+while (next_time := sim.next_time()) is not None and sim.time <= 3600:
+    sim.step()
+    if sim.time % 600 == 0:
+        fire_prob = sim.compute_fire_probability()
+        # Persist or visualise probability grids here.
 ```
 
-See `uv run propagator --help` for command line args.
+For an end-to-end script that mirrors the CLI pipeline (including loaders and
+writers), see `docs/programmatic.md` or the `example/example.py` file.
 
 ## Documentation
 
-This repo uses MkDocs with the Material theme and mkdocstrings for API reference.
+The MkDocs site covers:
+
+- **Getting Started** (`docs/getting-started.md`): prerequisites, environment
+  setup, quick run instructions, and programmatic usage tips.
+- **CLI Usage** (`docs/cli.md`): operating modes, flag reference, output
+  products, and troubleshooting.
+- **Programmatic Workflow** (`docs/programmatic.md`): loader/writer pipeline
+  example with `propagator.io`.
+- **API Reference** (`docs/reference/`): mkdocstrings pages for the core,
+  I/O, and Numba packages.
+- **Bibliography** (`docs/bibliography.md`): peer-reviewed work describing
+  PROPAGATOR and its operational deployments.
+
+Serve the docs locally:
 
-- Serve locally: `uv run mkdocs serve`
-- Build static site: `uv run mkdocs build`
+```bash
+uv run mkdocs serve
+```
+
+Build the static site:
+
+```bash
+uv run mkdocs build
+```
 
-Docs live under `docs/` and are configured by `mkdocs.yml`.
+## How to Contribute
+
+We welcome issues and pull requests! To contribute:
+
+1. Fork the repository and create a feature branch (`git checkout -b feat/xyz`).
+2. Set up the development environment with `uv sync --dev --all-extras`.
+3. Make your changes, keeping module structure and style guidelines in mind.
+4. Run the quality gates before submitting:
+   ```bash
+   uv run ruff check src tests
+   uv run pytest -q
+   uv run mkdocs build
+   ```
+5. Commit using Conventional Commit messages (e.g., `feat(core): add wind bias`).
+6. Open a pull request describing the change, verification steps, and any
+   relevant screenshots or artefacts.
+
+For major features or architectural changes, please open an issue first to
+discuss the proposal. Contributors are encouraged to reference the documentation
+pages above when adding or modifying features.

docs/bibliography.md

@@ -0,0 +1,27 @@
+# Bibliography
+
+Key references describing PROPAGATOR’s scientific background, operational use,
+and applications to prescribed fire planning.
+
+## Core Simulator
+
+- A. Trucchia, M. D’Andrea, F. Baghino, P. Fiorucci, L. Ferraris, D. Negro, A.
+  Gollini, and M. Severino. “Propagator: An operational cellular-automata based
+  wildfire simulator.” *Fire* 3(3):26, 2020.
+  [doi:10.3390/fire3030026](https://doi.org/10.3390/fire3030026)
+
+## Operational Deployments
+
+- A. Trucchia, M. D’Andrea, F. Baghino, N. Perello, N. Rebora, and P. Fiorucci.
+  “Experiences and lessons learnt in wildfire management with PROPAGATOR, an
+  operational cellular-automata-based wildfire simulator.” In D. Sempere-Torres,
+  A. Karakostas, C. Rossi, and P. Quevauviller (eds.), *Responding to Extreme
+  Weather Events*, chapter 3. Wiley, 2024.
+  [doi:10.1002/9781119741374.ch3](https://doi.org/10.1002/9781119741374.ch3)
+
+## Prescribed Fire Planning
+
+- N. Perello, A. Trucchia, F. Baghino, B. S. Asif, L. Palmieri, N. Rebora, and
+  P. Fiorucci. “Cellular automata-based simulators for the design of prescribed
+  fire plans: the case study of Liguria, Italy.” *Fire Ecology* 20(7), 2024.
+  [doi:10.1186/s42408-023-00239-7](https://doi.org/10.1186/s42408-023-00239-7)

docs/cli.md

@@ -1,24 +1,78 @@
 # CLI Usage
 
-The CLI entrypoint is `propagator` (defined in `project.scripts`).
-
-Show help:
+The `propagator` command drives simulations from the terminal. It validates
+input files, prepares rasters, runs the propagation loop, and writes outputs on
+every reporting interval.
 
 ```bash
 uv run propagator --help
 ```
 
-Typical usage:
+## Basic Invocation
 
 ```bash
 uv run propagator \
-  -f ./example/params.json \
-  -of ./example/output \
-  -tl 86400 \
-  -dem ./example/dem.tif \
-  -veg ./example/veg.tif
+  --config example/config.json \
+  --mode geotiff \
+  --dem example/dem.tif \
+  --fuel example/fuel.tif \
+  --output results/run-2025-02-19
 ```
 
-All time-related flags (`-tl`, etc.) are expressed in seconds.
+CLI arguments are powered by `pydantic-settings`; required inputs raise clear
+validation errors before the simulation starts.
+
+## Operating Modes
+
+- **GeoTIFF mode** (`--mode geotiff`): supply explicit DEM (`--dem`) and fuel
+  (`--fuel`) GeoTIFF rasters. Use this for bespoke datasets or the bundled
+  quickstart sample.
+- **Tiles mode** (`--mode tiles`, default): point to a directory of tiled DEM
+  and vegetation rasters with `--tilespath` and choose a tileset via
+  `--tileset`. The simulator infers the geographic window from ignition
+  coordinates defined in the configuration.
+
+Switching between modes controls which arguments are required; passing both
+`--dem` and `--fuel` automatically activates GeoTIFF mode even if `--mode` is
+left at the default.
+
+## Argument Reference
+
+| Flag | Type / Default | Description |
+| --- | --- | --- |
+| `--config PATH` | required | JSON configuration file parsed into `PropagatorConfigurationLegacy`. |
+| `--fuel-config PATH` | optional | YAML file defining a custom fuel system (`fuels` mapping). |
+| `--mode {tiles,geotiff}` | `tiles` | Select how static rasters are loaded (see above). |
+| `--dem PATH` | required in geotiff mode | DEM GeoTIFF when running in geotiff mode. |
+| `--fuel PATH` | required in geotiff mode | Fuel/vegetation GeoTIFF when running in geotiff mode. |
+| `--tilespath PATH` | required in tiles mode | Base directory containing tiled rasters. |
+| `--tileset NAME` | optional | Tileset to use within `tilespath` (defaults to `default`). |
+| `--output PATH` | required | Destination directory; created if missing. Stores GeoTIFF, GeoJSON, and JSON outputs. |
+| `--isochrones FLOAT …` | `0.5 0.75 0.9` | Probability thresholds for GeoJSON isochrone export. Repeat the flag to set multiple values. |
+| `--record` | flag, default off | When enabled, saves a Rich console log in the output directory. |
+| `--ignore-out-of-bounds` | flag, default off | Continue the simulation when the fire reaches the DEM boundary. |
+| `--verbose` | flag, default off | Print status tables, boundary conditions, and timing information. |
+
+Boolean switches use implicit flags: including `--verbose`, `--record`, or
+`--ignore-out-of-bounds` turns each behaviour on.
+
+## Output Products
+
+During the run, the CLI periodically writes:
+- GeoTIFF rasters for fire probability, fireline intensity (mean/max), and rate
+  of spread (mean/max).
+- GeoJSON isochrones for configured probability thresholds.
+- Metadata JSON capturing CLI arguments, execution time, and summary statistics.
+
+Set `--record` to capture the Rich console log alongside these artefacts, which
+is useful for post-run audits.
+
+## Troubleshooting
 
-See `propagator_cli/args_parser.py` for all flags and their meanings.
+- Missing GeoTIFFs or tiles raise validation errors before the simulation
+  boots; check path spelling if you hit them.
+- If dependency wheels complain about PROJ/GDAL, ensure the native libraries
+  are installed (see [Getting Started](getting-started.md#prerequisites)).
+- For reproducible runs across multiple ignitions or meteorological scenarios,
+  adjust `realizations`, `time_limit`, and `boundary_conditions` inside the
+  JSON configuration file.