Document the numpy path - ForeFire runs with no NetCDF and no GIS

[HugoFara]

addScalarLayer and addIndexLayer (bindings/python/src/pyforefire/_pyforefire.cpp:135,151) take numpy arrays directly. A user can therefore build a fuel map and a wind field as arrays, hand them over, and step a simulation — with no landscape file, no NetCDF, and no GIS at all.

That path completely sidesteps #167, the biggest adoption blocker. It is documented nowhere.

A complete working example already exists, in the test folder

tests/python/idealizedwind.py — 164 lines, 45 of them comments — builds a fuel map, constructs a rotating wind field, extends the fuel table, runs 15 iterations and plots the fronts. It touches no NetCDF and calls no loadData:

ff.addIndexLayer("table", "fuel", ..., fuel_map)
ff.addScalarLayer("windScalDir", "windU", ..., windU)
ff.addScalarLayer("windScalDir", "windV", ..., windV)

I ran it on current dev; it completes cleanly:

Iteration  15 / 15  angle:  360.0    time:  75.0
exit=0

But it is invisible

grep -rn idealizedwind outside tests/ returns nothing — no docs page, no README link, no CI. And the two places a user would look do not cover it:

• docs/source/user_guide/api_reference.rst contains 11 doxygenclass directives, all C++ (libforefire::FireDomain, FireFront, DataBroker, …). There is no Python API documentation at all, despite pip wheels being the advertised install path.
• The README's Python snippet (README.md:59-68) stops at a flat isotropic square — FireDomain, addLayer("propagation","Iso"), startFire, step. No fuel map, no wind, nothing a real case needs.

So the lowest-friction path in the project is invisible to the people who would benefit most: the ML and surrogate-modelling audience, who install by pip, want numpy in and numpy out, and do not care about NetCDF. Everything they need already works and is merely undocumented.

Suggested fix

In increasing order of effort:

1. Move idealizedwind.py out of tests/ into examples/ and link it from the README under the pip snippet. Nearly free, and it stops looking like test scaffolding.
2. A docs page: "Build a case in Python, no GIS needed" — prose around the code that already exists, showing the array shapes each layer expects. Two to three hours, zero new code.
3. Document the Python API in api_reference.rst. addScalarLayer, addIndexLayer, execute, getString. Currently a pip user has no reference for the interface they actually use.
4. Wire it into CI so it stays working — see Wire the unwired test suites into CI, and fix runANN #163. It is already an executable specification of the numpy path.

Worth noting for the WebAssembly question as well: if the engine is ever compiled to WASM, this is precisely the interface a browser build would expose, with JS typed arrays in place of numpy. This example is effectively its specification.

---

Drafted by Claude Opus 5 from a codebase audit. Reviewed by a maintainer before filing.

[HugoFara]

Merged in #189, closing.