cell2fire-sof

Packaged fork of Cell2Fire for the Satellites on Fire wildfire simulation pipeline.

Relationship with upstream

Derived from tag v0.11. The git history is the changelog, and the upstream/v0.11 tag is the baseline:

upstream/v0.11   verbatim import of the tarball
      |
      +-- chore: ruff format (no functional change, verified by AST)
      |
      +-- fix: fuel type parsing, curing and pandas/matplotlib compatibility

git diff upstream/v0.11..HEAD shows everything that changed. tests/test_fork_inventory.py freezes the inventory: 19 modified functions and 1 new one. tests/test_format_is_functional_noop.py checks that the files without fixes are still upstream at the AST level.

Modifications

See the fix commit message for the detail. In short:

• FBP fuel type parsing. Upstream truncated the code to 2 characters before using the PC/PDF percentage, so the PCD/PDFD keys never matched and the conifer or dead balsam fir percentage was lost. normalize_fuel_type preserves it.
• Curing. The branch that reads cur.asc was dead code upstream: it compared against curing.asc, a name that is not in its own file list.
• Compatibility. groupby with list column selection (pandas 2.x dropped the old form) and plt.savefig without the figsize kwarg, which matplotlib does not accept.

Several of these are upstream bugs and are candidates for contributing back.

License

GPL-3.0-only, same as upstream. See LICENSE.

Engine authors: Cristobal Pais, Jaime Carrasco, David Martell, David L. Woodruff, Andres Weintraub.

Cite as: Pais et al., "Cell2Fire: A Cell-Based Forest Fire Growth Model to Support Strategic Landscape Management Planning", Frontiers in Forests and Global Change, 2021.

Build

The C++ binary is not committed: it is compiled from cell2fire/Cell2FireC/, unpatched (the C++ is verbatim v0.11). See .github/workflows/release.yml. The wheel published under Releases carries the compiled binary and is platform specific (linux_x86_64).

sudo apt-get -y install build-essential g++ libboost-all-dev libeigen3-dev
make -C cell2fire/Cell2FireC
pip install -e . && python -m pytest tests/ -v

Usage

cell2fire-sof --input-instance-folder <dir>/ --output-folder <dir> [flags]
cell2fire-sof-gen-data <input_dir>

The trailing slash on --input-instance-folder is part of the contract: the engine builds paths by concatenation.

Tests

File	What it guarantees
tests/test_fork_inventory.py	The set of modified and new functions is exactly the declared one (GPLv3 section 5(a)).
tests/test_format_is_functional_noop.py	The files without fixes are still upstream, AST for AST.
tests/test_dependencies_match_imports.py	The declared dependencies are exactly the third-party imports of the tree.
tests/test_cli.py	cell2fire-sof-gen-data writes Data.csv.
tests/test_golden.py	The recompiled binary produces byte for byte what the binary that lived in sof-ai produced before the split.

tests/fixtures/Sub40x40/ is upstream's data/Sub40x40 instance, trimmed to what the engine reads with these flags (no Weathers/, Data.dat, Demand.csv or values40x40.csv). Its fbp_lookup_table.csv is upstream's canonical Canadian catalog of 141 rows, and has nothing to do with sof-ai's fbp_lookup_table.csv, which is 10 rows mapping Dynamic World classes.

tests/fixtures/golden/Sub40x40/ holds the 8 ForestGrid*.csv produced by the binary that was committed in sof-ai (upstream v0.11, GLIBC_2.34). Regenerate only if the engine changes on purpose:

GOLDEN_UPDATE=1 python -m pytest tests/test_golden.py

scripts/verify_no_loss.py was the migration gate: it compared this tree against the one that lived in sof-ai to prove the fork reconstruction lost no change. It is kept as a record of how that was verified.