Make runANN work, and run it in CI

.github/workflows/main.yml

@@ -68,4 +68,13 @@ jobs:
       - name: Run 'runff' Test Script
         run: |
           cd tests/runff
-          bash ff-run.bash # Execute the complete test logic script
+          bash ff-run.bash # Execute the complete test logic script
+
+      # The only coverage for ANNPropagationModel and BMapLoggerForANNTraining:
+      # both read a .ffann network in their constructor and abort without one,
+      # so the unit suite cannot reach them. ANN_test is built by the step
+      # above, since FOREFIRE_BUILD_TOOLS defaults on outside wheel builds.
+      - name: Run 'runANN' Test Script
+        run: |
+          cd tests/runANN
+          bash run.bash

TESTING.md

@@ -32,7 +32,7 @@ They need no Python and no test data. Configure with
 
 ## Running the Core Test (`runff`)
 
-The primary automated test, validated in our CI pipeline, is located in `tests/runff/`. This test verifies core simulation, save/reload functionality, and NetCDF/KML output generation against reference files.
+The primary physics regression test, validated in CI by `main.yml` and `macos.yml`, is located in `tests/runff/`. This test verifies core simulation, save/reload functionality, and NetCDF/KML output generation against reference files.
 
 **To run this test manually:**
 
@@ -111,9 +111,56 @@ which is the point — it is the failing test the work in #175 has to make pass.
 Wiring it into CI belongs with the last step of that issue, once it can pass
 for the right reason.
 
+## Running the ANN Test (`runANN`)
+
+Validated in CI by `main.yml`. It is the only coverage for
+`ANNPropagationModel` and `BMapLoggerForANNTraining`: both read a `.ffann`
+network in their constructor and abort without one, so the C++ unit suite
+cannot construct them.
+
+It runs the trained network in `Rothermel.ffann` over the 1424 inputs in
+`modelrun.csv` and checks the root mean squared error against what the
+propagation model produced.
+
+**To run it manually**, after building (`ANN_test` needs
+`-DFOREFIRE_BUILD_TOOLS=ON`, which is the default outside wheel builds):
+
+```bash
+cd tests/runANN
+bash run.bash
+```
+
+Add `print` to `ANN_test` for a per-input dump:
+
+```bash
+../../bin/ANN_test Rothermel.ffann modelrun.csv print
+```
+
+The tolerance is calibrated between a working network and a useless one:
+
+| | RMSE |
+| --- | --- |
+| trained network | 0.0235 |
+| predicting the mean of every output | 0.0966 |
+| normalisation weights scaled by 1% | 17817 |
+| **tolerance** | **0.05** |
+
+Note the fixture is weak: the expected outputs take four distinct values
+spanning 1.1 in 12412, which is why the gap between a working network and a
+constant one is so narrow. Replacing `modelrun.csv` with inputs that produce a
+real spread of rates of spread would make this a much stronger check.
+
 ## Other Tests
 
-The `tests/` directory contains other subdirectories (`mnh_*`, `runANN`) for testing specific features like coupled simulations. A main `tests/run.bash` script exists but is not currently fully validated in CI. Refer to specific subdirectories for details if needed.
+`tests/run.bash` runs every suite that its environment allows: `runff` and
+`runANN` always, the `mnh_*` coupled cases when `SRC_MESONH` is set, and
+`tests/python/` when `PYTHONEXE` is set. It is not itself invoked by CI, which
+runs the suites individually.
+
+`tests/python/` also holds `idealizedwind.py`, `farsite_flat.py` and
+`percolation.py`. They are examples rather than tests — they produce plots and
+assert nothing — and are not run anywhere. They are the closest thing to
+worked examples in the repository, so keeping them executable is worthwhile.
 
 ## Sanitizers
 

tests/runANN/clean.bash

@@ -1 +1,8 @@
-rm -f results.txt
+#!/bin/bash
+# run.bash writes nothing to disk any more — it reads the RMSE off ANN_test's
+# stdout — so there is nothing to clean. Kept because tests/run.bash calls a
+# clean.bash in each suite directory.
+#
+# The old result.txt this used to remove was named results.txt here, so it
+# never matched anything either.
+exit 0