genForeFireCase.py is documented in four places but is not in the repository

[HugoFara]

The single biggest adoption blocker: users hit it about twenty minutes after the Docker demo works, because it is the tool that builds the landscape file, without which ForeFire runs only on the shipped example.

Documented in four places, present in none

git ls-files | grep genForeFireCase returns nothing, while these describe it:

• docs/source/user_guide/landscape_file.rst:84 — "Previous versions of ForeFire included Python helper scripts (e.g. genForeFireCase.py). While the status of V2 helpers is pending…"
• tools/README.md:12,20,62 — documents FiretoNC() argument by argument
• tools/preprocessing/READMEscripts.md
• docs/_legacy/UserGuide/ForeFireGeneralUsage.tex:170

It was removed in ac0baba ("clean more post-processing", Dec 2023), which deleted 129 lines and added 21 lines to tools/TODO.md.

It is recoverable, and it still works — with two fixes

I pulled it back and ran it:

git show ac0baba^:tools/preprocessing/genForeFireCase.py

Generating a 100×100 landscape and loading it produced:

variables: ['fuel', 'altitude', 'windU', 'windV', 'domain', 'parameters']
LOADED OK
SIMULATED OK

ForeFire loads the output, ignites, and steps. So restoring it is genuinely the right call — but it is not a clean revert. Three things need attention.

1. The 3-D and 4-D paths are broken. addFieldToNcFile reads the input shape as (NY, NX, NZ, NT):

ncfile.createDimension('%sNX'%fieldname, sp[1])
ncfile.createDimension('%sNY'%fieldname, sp[0])
ncfile.createDimension('%sNZ'%fieldname, sp[2])
ncfile.createDimension('%sNT'%fieldname, sp[3])
variable = ncfile.createVariable(fieldname, dvartype, ('NT','NZ','NY','NX'))
variable[:,:,:,:] = field

but creates the variable with the axes in the opposite order and assigns without transposing. That only succeeds when NY == NT and NX == NZ. A 4-D field fails with:

ValueError: could not broadcast input array from shape (1,1,100,100) into shape (100,100,1,1)

Only the 2-D path is correct. Since time-varying wind is exactly what a 4-D field is for, this needs fixing before the tool is advertised.

2. scipy.io.netcdf is deprecated. It still imports on scipy 1.18, but emits DeprecationWarning: … the scipy.io.netcdf namespace is deprecated and will be removed in SciPy 2.0.0. One-line fix to netcdf_file. Worth considering netCDF4 instead, which the project already depends on for testing.

3. parametersProperties has seven undocumented required keys. Omitting any of date, duration, refYear, refDay, year, month, day raises a bare KeyError after the file has already been partially written. tools/README.md calls this argument "the other optional properties you may want to put in the list" — it is not optional.

Suggested fix

Restore the file to tools/preprocessing/, fix the axis order, move off the deprecated import, document or default the required keys, and add a smoke test — the sequence above is already one. Then correct the four documents so they describe what exists.

Roughly half a day, and it removes the top reason people bounce off the project.

The alternative — deleting every mention — is much cheaper but leaves users with no way to build a case at all. Documenting a tool that does not exist reads worse than documenting nothing, but having the tool reads best.

---

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

[HugoFara]

Correction to this issue: the removal was deliberate, and the wording above implies otherwise.

fd4b1c8 2023-10-12 FiretoNC copied into prealCF2Case.py
ac0baba 2023-12-18 genForeFireCase.py deleted ("clean more post-processing")

Two months apart, consumer first. The function was inlined where it was used and the standalone file was then removed as dead code. That is ordinary de-duplication, not an oversight, and any restoration is a reversal of it rather than a repair.

What has changed since is that prealCF2Case.py's copy diverged. It now sets the domain and parameters attributes by iterating the dicts with no required-key check, writes elevation as f4, and writes wind as a single combined wind variable in a potential-field form with the windU/windV calls commented out above it. It is the back half of the Meso-NH PGD pipeline and needs a PGD file to run.

So the gap this issue describes is real — there is no general-purpose landscape writer, while four documents describe one — but the fix is a decision, not a correction. #179 proposes restoring the general writer and is left as a draft for that reason. Deleting the four references instead is cheaper and respects ac0baba more directly; it just leaves a new user with no way to build a case.