antonio-leblanc · Nov 11, 2026 · Nov 11, 2026 · Nov 11, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,11 @@ history, so they summarise each release rather than list every change. The
 
 ### Added
 
+- `tests/mnh_coupled.bash` goes from a bare Linux machine to a coupled
+  ForeFire + Meso-NH run: it downloads and builds Meso-NH 6.0.1, builds
+  ForeFire with MPI, links them and runs `tests/mnh_real_nested`. With
+  `--compare <branch>` it runs the case on both builds and reports the output
+  files that differ beyond run-to-run noise. ([#266])
 - A User Guide page introduces Meso-NH coupling, the supplied cases and the live 3D viewer.
 - A User Guide page lists the propagation and flux models that have a
   published reference, with a link to it and how to select each model.
@@ -352,3 +357,4 @@ repository stays easy to return to.
 [#265]: https://github.com/forefireAPI/forefire/issues/265
 [#242]: https://github.com/forefireAPI/forefire/pull/242
 [#270]: https://github.com/forefireAPI/forefire/pull/270
+[#266]: https://github.com/forefireAPI/forefire/issues/266
diff --git a/docs/mnh/coupledMNHInstall.md b/docs/mnh/coupledMNHInstall.md
@@ -3,125 +3,122 @@
 [Meso-NH](https://mesonh.cnrs.fr) is the French atmospheric research model
 (CNRS / Météo-France). Coupled runs load ForeFire as a shared library: at
 every step Meso-NH sends wind to the fire and receives heat and vapour fluxes
-back. This guide sets the coupling up from scratch and shows how to check
-that a change to ForeFire does not alter coupled results.
+back.
 
 Tested on Ubuntu 24.04 (WSL) with GCC/gfortran 13.3, OpenMPI 4.1.6 and
 Meso-NH 6.0.1. macOS notes, from an older Meso-NH 5.7 setup, are at the end.
 
-## 1. Prerequisites
+## 1. Run the script
 
-```bash
-sudo apt install build-essential gfortran openmpi-bin libopenmpi-dev \
-                 cmake git git-lfs libnetcdf-dev libnetcdf-c++4-dev netcdf-bin
-```
-
-Use Bash, not Ksh, for everything below. Meso-NH's profile reads
-`SRC_MESONH` before defining it, so do not run with `set -u`.
-
-## 2. Get and build Meso-NH
-
-The 6.0.1 release is on [Zenodo](https://zenodo.org/records/21395048). The
-[CNRS GitLab](https://src.koda.cnrs.fr/mesonh/mesonh-code) also works when it
-is reachable (it needs Git LFS). Official instructions:
-[download](https://mesonh.readthedocs.io/en/mnh-6-0/getting_started/download.html),
-[compile](https://mesonh.readthedocs.io/en/mnh-6-0/getting_started/compile.html).
+From a ForeFire clone, in Bash:
 
 ```bash
-mkdir -p ~/mesonh
-tar xzf mnh601.tar.gz -C ~/mesonh
-cd ~/mesonh/mesonh-code-PACK-MNH-V6-0-1/src
-export ARCH=LXgfortran VER_MPI=MPIAUTO OPTLEVEL=O2
-./configure
-. ../conf/profile_mesonh-LXgfortran-R8I4-MNH-V6-0-1-MPIAUTO-O2
-make -j 12
-make installmaster
+tests/mnh_coupled.bash
 ```
 
-The build takes about 15 minutes on 12 cores. Load the profile in every new
-shell before running a case: it sets `SRC_MESONH` and `XYZ`, which the test
-scripts use.
+It goes from a bare Linux machine to a finished coupled run, and skips
+whatever is already done, so running it again is cheap:
 
-## 3. Build ForeFire and link it
+1. Checks the prerequisites and, if any are missing, prints the
+   `sudo apt install` line for them. It never runs `sudo` itself.
+2. Downloads Meso-NH 6.0.1 from [Zenodo](https://zenodo.org/records/21395048)
+   (190 MB) and checks its MD5. `--tarball FILE` uses a copy you already have.
+3. Builds Meso-NH: about 15 minutes on 12 cores.
+4. Builds the ForeFire library with MPI, from the clone the script is in.
+5. Links it as `$SRC_MESONH/exe/libForeFire.so`.
+6. Runs `tests/mnh_real_nested` in a fresh copy: Pedrógão Grande 2017, two
+   nested domains, 4 MPI processes, about 7 minutes.
 
-MPI is on by default in a plain CMake build. Check that the configure output
-says MPI was found: without it the coupled run does not work. A warning that
-the Git LFS check failed for files under `tests/runff` does not matter here;
-the `mnh_*` files must be listed as OK.
+To watch the run in 3D (terrain, fire front, plume, wind), open
+<http://localhost:8080/mnh3d.html> while it runs (it loads three.js from a
+CDN, so the browser needs internet; use one tab at a time).
 
-```bash
-git clone https://github.com/forefireAPI/forefire.git
-cd forefire
-git lfs pull
-cmake -S . -B build
-cmake --build build -j 4
-```
+Everything goes under `~/forefire-mnh` (`--workdir` or `FF_MNH_WORKDIR` to
+change it), about 10 GB: Meso-NH, the ForeFire builds, `logs/` and one
+directory per run under `runs/`. `--help` lists the options.
 
-This produces `lib/libforefireL.so`. Meso-NH opens
-`$SRC_MESONH/exe/libForeFire.so` at run time, so link it there:
+The packages it asks for on Ubuntu:
 
 ```bash
-ln -sf "$PWD/lib/libforefireL.so" "$SRC_MESONH/exe/libForeFire.so"
+sudo apt install build-essential gfortran openmpi-bin libopenmpi-dev \
+                 cmake git git-lfs curl libnetcdf-dev libnetcdf-c++4-dev
 ```
 
-## 4. Run a coupled case
-
-Two cases ship with ForeFire:
-
-| Case | What it is |
-| --- | --- |
-| `tests/mnh_real_nested` | Pedrógão Grande 2017, two nested domains, 4 MPI processes, 1200 s of simulation (about 7 min) |
-| `tests/mnh_ideal` | Idealised relief, single domain, a few seconds; needs `ncgen` (from `netcdf-bin`) |
+## 2. Check that a change does not alter coupled results
 
 ```bash
-cd tests/mnh_real_nested
-bash clean.bash
-bash run.bash
+tests/mnh_coupled.bash --compare my-branch
 ```
 
-`run.bash` only checks that `ForeFire/Outputs/ForeFire.0.nc` exists and is
-larger than 15 kB. It does not compare against `ForeFire.0.nc.ref`, and the
-grid size depends on the Meso-NH version (680×680 on 6.0.1, 666×666 reported
-on 6.1). A meaningful check is the comparison in section 5.
-
-`mnh_real_nested/ForeFire/Init.ff` starts
-`listenHTTP[host=127.0.0.1:8080]`, so port 8080 must be free.
-
-To watch the run in 3D (terrain, fire front, plume, wind), export
-`FOREFIREHOME=/path/to/forefire` before `run.bash` and open
-<http://localhost:8080/mnh3d.html> while it runs (it loads three.js from a
-CDN, so the browser needs internet). The page sends commands that run
-alongside the time step, so leave it closed for the comparison in section 5;
-use one tab at a time.
-
-## 5. Check that a change does not alter coupled results
+`--compare` takes a branch, tag or commit of the same clone, or a directory
+with another ForeFire source tree. The script builds both, runs the case four
+times (this clone, the other one, this clone, the other one), switching the
+`libForeFire.so` link before each run, and compares byte for byte the files
+in `ForeFire/Outputs`, `MODEL1`, `MODEL2` and the `RUN12.*.FIRE.*.nc` files.
+It takes about 30 minutes and exits non-zero on a real difference. Leave
+`mnh3d.html` closed during `--compare`, as it sends commands that run
+alongside the time step.
 
-Run the same case with ForeFire built from `dev` and from the branch under
-review, and compare the outputs byte for byte.
-
-1. Build both versions with the same options, each in its own worktree
-   (`git worktree add ../ff-pr <branch>`).
-2. Make a clean copy of the case for each run.
-3. Run `dev`, branch, `dev`, branch, switching the `libForeFire.so` link
-   before each run.
-4. Compare with `cmp` the files in `ForeFire/Outputs`, `MODEL1`, `MODEL2` and
-   the `RUN12.*.FIRE.*.nc` files.
-
-Two runs of the same build already differ in a few places, so the second
-`dev` run is what separates noise from a real change:
+Two runs of the same build already differ in a few places, so the second run
+of this clone is what separates noise from a real change:
 
 - `RUN12.*.FIRE.*.nc`: 7 to 9 bytes, the timestamp in the `history`
   attribute and the HDF5 header checksum.
 - `MODEL*/output.*.air_density`: meaningless values (NaN, ±10¹⁰) that change
   on every run. This comes from Meso-NH, not from ForeFire.
 
-Everything else must be identical. A file that differs between `dev` and the
-branch, but not between the two `dev` runs, is a real difference.
+Everything else must be identical. A file that differs between the two
+builds, but not between the two runs of this clone, is a real difference.
+A file that differs between the two runs of this clone and is not in the list
+above is reported as unexpected noise.
+
+## 3. What the script relies on
+
+What follows explains the setup for anyone doing it by hand or debugging it.
+Official Meso-NH instructions:
+[download](https://mesonh.readthedocs.io/en/mnh-6-0/getting_started/download.html),
+[compile](https://mesonh.readthedocs.io/en/mnh-6-0/getting_started/compile.html).
+The [CNRS GitLab](https://src.koda.cnrs.fr/mesonh/mesonh-code) also has the
+sources when it is reachable (it needs Git LFS).
+
+- **Meso-NH build.** `ARCH=LXgfortran VER_MPI=MPIAUTO OPTLEVEL=O2 ./configure`
+  in `src/`, then load the profile it writes in `conf/`, then `make` and
+  `make installmaster`. The profile sets `SRC_MESONH` and `XYZ`, which the
+  test cases use, so load it in every new shell before running one by hand.
+  It reads `SRC_MESONH` before defining it, so do not use `set -u` around it.
+- **ForeFire build.** `cmake -S . -B build -DFOREFIRE_ENABLE_MPI=ON`. The
+  configuration summary must say `MPI .......... ON`: without MPI the coupled
+  run does not work. Whatever the build directory, CMake writes
+  `lib/libforefireL.so` into the source tree, so two builds of one tree
+  overwrite each other's library. The script copies it to
+  `forefire/<name>/libforefireL.so` in its work directory before linking.
+- **The link.** Meso-NH opens `$SRC_MESONH/exe/libForeFire.so` at run time:
+
+  ```bash
+  ln -sf /path/to/libforefireL.so "$SRC_MESONH/exe/libForeFire.so"
+  ```
+
+- **Case data.** The `mnh_*` inputs are in Git LFS. If they are short text
+  stubs, the script runs `git lfs pull` for the case.
+- **Port 8080.** `mnh_real_nested/ForeFire/Init.ff` starts
+  `listenHTTP[host=127.0.0.1:8080]`, so the port must be free; the script
+  stops if it is not. With `FOREFIREHOME` set to the ForeFire clone, which
+  the script does, that server also serves the pages in `tools/htdocs`.
+- **What `run.bash` checks.** Only that `ForeFire/Outputs/ForeFire.0.nc`
+  exists and is larger than 15 kB. It does not compare against
+  `ForeFire.0.nc.ref`, and the grid size depends on the Meso-NH version
+  (680×680 on 6.0.1, 666×666 reported on 6.1). The comparison in section 2
+  is the meaningful check.
+
+The other coupled case, `tests/mnh_ideal` (idealised relief, single domain, a
+few seconds), is not run by the script. With the profile loaded and the link
+in place: `cd tests/mnh_ideal && bash clean.bash && bash run.bash`. It needs
+`ncgen`, from `netcdf-bin`.
 
 ## macOS notes (Meso-NH 5.7)
 
-These come from an earlier setup on Apple Silicon with macOS Ventura and
-Meso-NH 5.7. They may no longer apply to 6.x.
+The script targets Linux. These notes come from an earlier setup on Apple
+Silicon with macOS Ventura and Meso-NH 5.7. They may no longer apply to 6.x.
 
 Install `gcc`, `gfortran` and `open-mpi` with Homebrew. On 5.7, also
 `export MNH_FOREFIRE=1.0` before `./configure`. The library is

diff --git a/tests/README.md b/tests/README.md
@@ -30,8 +30,10 @@ ctest --test-dir build --output-on-failure
 * The test fixtures are stored in **Git LFS**. `git lfs pull` if the `.nc`
   files look like short text stubs.
 
-* *(optional)* **Meso-NH**, for the `mnh_*` tests only. Setup and the `dev` × PR
-  check: [`docs/mnh/coupledMNHInstall.md`](../docs/mnh/coupledMNHInstall.md).
+* *(optional)* **Meso-NH**, for the `mnh_*` tests only. `mnh_coupled.bash`
+  builds it, links ForeFire and runs `mnh_real_nested`; with `--compare` it
+  runs the `dev` × PR check. See
+  [`docs/mnh/coupledMNHInstall.md`](../docs/mnh/coupledMNHInstall.md).
 
   ```bash
   # sets SRC_MESONH and XYZ, which the mnh_* scripts use