From df48be7244cdd7ddb106c800da8f3849b8e3a53f Mon Sep 17 00:00:00 2001 From: HugoFara Date: Wed, 28 Oct 2026 23:23:33 +0100 Subject: [PATCH 1/3] feat(python): fork a running simulation with ForeFireRunner.fork() (#172) fork() returns a new runner holding a copy of the simulation, so ensemble members can branch from one spin-up instead of rerunning it. The worker forks itself, not the caller: the worker has no threads, and the copy starts with the whole kernel state. The new socket is passed over the existing one, and the copy is double-forked so nobody has to reap it. A fork takes a few milliseconds, against about 80 ms for a new runner. Open files are shared with the copy, and an HTTP command server is not copied. --- CHANGELOG.md | 8 ++ TESTING.md | 7 +- bindings/python/src/pyforefire/_runner.py | 91 +++++++++++++++++++++-- bindings/python/src/pyforefire/_worker.py | 35 ++++++++- tests/python/test_runner.py | 71 +++++++++++++++++- 5 files changed, 199 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ce7af6d..446672d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,13 @@ history, so they summarise each release rather than list every change. The ## [Unreleased] +### Added + +- `ForeFireRunner.fork()` returns a new runner holding a copy of the + simulation, so ensemble members can branch from one spin-up instead of + rerunning it. The worker forks itself, which takes a few milliseconds where + a new runner takes about 80. ([#172]) + ### Fixed - Commands that need a domain print an error when there is none, instead of @@ -303,3 +310,4 @@ repository stays easy to return to. [#203]: https://github.com/forefireAPI/forefire/pull/203 [#205]: https://github.com/forefireAPI/forefire/issues/205 [#171]: https://github.com/forefireAPI/forefire/issues/171 +[#172]: https://github.com/forefireAPI/forefire/issues/172 diff --git a/TESTING.md b/TESTING.md index adffffdc..05e53839 100644 --- a/TESTING.md +++ b/TESTING.md @@ -116,9 +116,10 @@ for the right reason. Checks `pyforefire.ForeFireRunner`, which runs each simulation in its own worker process (#175). Eight runners driven from threads must each reproduce the in-process fire node count; exceptions in the worker must reach the -caller, and a killed worker must raise `WorkerDied`. It needs no free-threaded -interpreter, because the runners are separate processes. CI runs it in the -Model Invariants workflow. +caller, and a killed worker must raise `WorkerDied`. A fork taken mid-run must +finish with the same count, and changes on either side of a fork must not reach +the other (#172). It needs no free-threaded interpreter, because the runners +are separate processes. CI runs it in the Model Invariants workflow. ```bash ./.venv/bin/python tests/python/test_runner.py diff --git a/bindings/python/src/pyforefire/_runner.py b/bindings/python/src/pyforefire/_runner.py index 5275088c..3369ce21 100644 --- a/bindings/python/src/pyforefire/_runner.py +++ b/bindings/python/src/pyforefire/_runner.py @@ -10,17 +10,26 @@ replies are pickled over a socket pair. The worker's stdout and stderr are the caller's, so kernel output still shows up where it did before. +`fork()` does fork, but the worker rather than the caller: the worker has no +threads, and its copy starts with the whole simulation state, which is what an +ensemble branching from a common spin-up needs (see issue #172). + runner = ForeFireRunner() runner.execute("FireDomain[sw=(0,0,0);ne=(1000,1000,0);t=0]") runner["propagationModel"] = "Iso" + copy = runner.fork() runner.close() """ +import os +import signal import socket import subprocess import sys import threading +import time from multiprocessing.connection import Connection +from multiprocessing.reduction import send_handle __all__ = ["ForeFireRunner", "WorkerDied"] @@ -29,6 +38,41 @@ class WorkerDied(RuntimeError): """The worker process ended while a call was pending, or before it.""" +class _ForkedProcess: + """The part of `subprocess.Popen` the runner uses, for a forked worker. + + A forked worker is not a child of the caller, so its exit status is + unknown: `poll()` and `wait()` always return None, and `wait()` watches + the process with signal 0 instead of waiting for it. + """ + + def __init__(self, pid): + self.pid = pid + + def _alive(self): + try: + os.kill(self.pid, 0) + except (ProcessLookupError, PermissionError): + return False + return True + + def poll(self): + return None + + def wait(self, timeout=None): + deadline = None if timeout is None else time.monotonic() + timeout + while self._alive(): + if deadline is not None and time.monotonic() > deadline: + raise subprocess.TimeoutExpired(f"pid {self.pid}", timeout) + time.sleep(0.01) + + def kill(self): + try: + os.kill(self.pid, signal.SIGKILL) + except ProcessLookupError: + pass + + class ForeFireRunner: """A `pyforefire.ForeFire` that lives in a separate process. @@ -45,27 +89,34 @@ class ForeFireRunner: def __init__(self): parent, child = socket.socketpair() try: - self._process = subprocess.Popen( + process = subprocess.Popen( [sys.executable, "-m", "pyforefire._worker", str(child.fileno())], pass_fds=(child.fileno(),), ) finally: child.close() - self._conn = Connection(parent.detach()) + self._attach(Connection(parent.detach()), process) + + def _attach(self, conn, process): + self._conn = conn + self._process = process self._lock = threading.Lock() - def _call(self, name, *args): + def _call(self, name, *args, fd=None): with self._lock: if self._conn is None: raise WorkerDied("the runner is closed") try: self._conn.send((name, args)) + if fd is not None: + send_handle(self._conn, fd, self._process.pid) ok, value = self._conn.recv() except (EOFError, OSError): code = self._process.wait() self._conn.close() self._conn = None - raise WorkerDied(f"the ForeFire worker exited with status {code}") from None + status = "" if code is None else f" with status {code}" + raise WorkerDied(f"the ForeFire worker exited{status}") from None if not ok: raise value return value @@ -81,6 +132,37 @@ def __getitem__(self, key): def __setitem__(self, key, value): self._call("__setitem__", key, value) + def fork(self): + """Return a new runner holding a copy of this simulation. + + The worker forks itself, so the copy starts with the same domain, + layers, fronts and parameters, then shares nothing with this runner: + each can be stepped or changed without affecting the other, and + closing one leaves the other running. Memory pages are copied only + when one side writes them, so forking after a long spin-up is cheap. + + Files the simulation has open are shared with the copy, and a running + HTTP command server is not copied. + """ + ours, theirs = socket.socketpair() + try: + try: + self._call("__fork__", fd=theirs.fileno()) + finally: + theirs.close() + conn = Connection(ours.detach()) + except BaseException: + ours.close() + raise + try: + pid = conn.recv() + except (EOFError, OSError): + conn.close() + raise WorkerDied("the forked ForeFire worker exited before it started") from None + copy = ForeFireRunner.__new__(ForeFireRunner) + copy._attach(conn, _ForkedProcess(pid)) + return copy + def close(self): """Stop the worker and wait for it. Calling it twice is harmless.""" with self._lock: @@ -107,4 +189,3 @@ def __exit__(self, *exc): def __del__(self): if getattr(self, "_process", None) is not None: self.close() - diff --git a/bindings/python/src/pyforefire/_worker.py b/bindings/python/src/pyforefire/_worker.py index eec95777..8878f72f 100644 --- a/bindings/python/src/pyforefire/_worker.py +++ b/bindings/python/src/pyforefire/_worker.py @@ -4,8 +4,34 @@ the caller sends None or goes away. """ +import os import sys from multiprocessing.connection import Connection +from multiprocessing.reduction import recv_handle + + +def _fork(conn): + """Answer `ForeFireRunner.fork()`: copy this process onto a new socket. + + The caller sends the socket after the request. The copy is forked twice, + so it is reparented as soon as the middle process exits and nobody has to + reap it. Returns the new connection in the copy, None in the original. + """ + fd = recv_handle(conn) + pid = os.fork() + if pid == 0: + if os.fork() != 0: + os._exit(0) + try: + conn.close() + copy = Connection(fd) + copy.send(os.getpid()) + return copy + except BaseException: + os._exit(1) + os.close(fd) + os.waitpid(pid, 0) + return None def _serve(conn): @@ -21,7 +47,14 @@ def _serve(conn): return name, args = request try: - reply = (True, getattr(ff, name)(*args)) + if name == "__fork__": + copy = _fork(conn) + if copy is not None: + conn = copy + continue + reply = (True, None) + else: + reply = (True, getattr(ff, name)(*args)) except Exception as e: reply = (False, e) try: diff --git a/tests/python/test_runner.py b/tests/python/test_runner.py index ba641bd1..822772ef 100644 --- a/tests/python/test_runner.py +++ b/tests/python/test_runner.py @@ -20,16 +20,25 @@ RUNNERS = 8 -def run_simulation(ff): - """One self-contained simulation. Returns its fire node count.""" +def start_simulation(ff): ff.execute(f"FireDomain[sw=(0,0,0);ne=({SIZE},{SIZE},0);t=0]") ff.addLayer("propagation", "Iso", "propagationModel") ff.execute(f"startFire[loc=({SIZE / 2},{SIZE / 2},0)]") - for _ in range(STEPS): + + +def advance(ff, steps): + """Step `steps` times. Returns the fire node count.""" + for _ in range(steps): ff.execute("step[dt=100]") return ff.execute("print[]").count("FireNode") +def run_simulation(ff): + """One self-contained simulation. Returns its fire node count.""" + start_simulation(ff) + return advance(ff, STEPS) + + def test_matches_in_process(baseline): """A runner must give exactly what the in-process object gives.""" import pyforefire @@ -128,6 +137,58 @@ def test_worker_death(): return failures +def test_fork(baseline): + """A fork continues the simulation exactly, and independently.""" + import pyforefire + + failures = [] + with pyforefire.ForeFireRunner() as runner: + start_simulation(runner) + advance(runner, 2) + runner["perimeterResolution"] = 7.5 + with runner.fork() as copy: + got = advance(copy, STEPS - 2) + if got != baseline: + failures.append(f"the fork produced {got} fire nodes, expected {baseline}") + if copy["perimeterResolution"] != 7.5: + failures.append("the fork did not inherit a parameter set before it") + copy["perimeterResolution"] = 3.0 + if runner["perimeterResolution"] != 7.5: + failures.append("setting a parameter on the fork changed the original") + with copy.fork() as grandcopy: + if grandcopy["perimeterResolution"] != 3.0: + failures.append("a fork of a fork did not inherit the fork's state") + got = advance(runner, STEPS - 2) + if got != baseline: + failures.append(f"the original produced {got} fire nodes after forking, expected {baseline}") + return failures + + +def test_fork_outlives_original(): + """Closing or killing one side of a fork leaves the other running.""" + import pyforefire + + failures = [] + runner = pyforefire.ForeFireRunner() + start_simulation(runner) + copy = runner.fork() + runner.close() + if advance(copy, 1) == 0: + failures.append("the fork lost its front when the original closed") + other = copy.fork() + os.kill(copy._process.pid, signal.SIGKILL) + try: + copy.execute("print[]") + failures.append("a call on a killed fork did not raise") + except pyforefire.WorkerDied: + pass + copy.close() + if advance(other, 1) == 0: + failures.append("a fork stopped answering when its parent was killed") + other.close() + return failures + + def main(): import pyforefire @@ -140,13 +201,15 @@ def main(): failures += test_parameters() failures += test_errors_are_raised_here() failures += test_worker_death() + failures += test_fork(baseline) + failures += test_fork_outlives_original() if failures: print(f"\nFAILED with {len(failures)} problem(s):") for f in failures: print(f" - {f}") return 1 - print(f"OK: {RUNNERS} concurrent runners matched the baseline; errors and crashes surfaced") + print(f"OK: {RUNNERS} concurrent runners and forks matched the baseline; errors and crashes surfaced") return 0 From 90d1db91eca2aeaf21e541fbaa151d85b54fa239 Mon Sep 17 00:00:00 2001 From: HugoFara Date: Wed, 28 Oct 2026 23:43:36 +0100 Subject: [PATCH 2/3] feat(python): run an ensemble and map its burn probability (#172) run_ensemble(setup, members, until, perturb) runs setup once, forks one runner per member, applies perturb to each and steps them in parallel to `until`. It returns the arrival-time maps, [member, y, x], and burn_probability() turns them into the fraction of members burnt by any time. With fork=False each member gets a fresh runner and perturb runs before setup, for parameters the kernel reads only at construction, such as windReductionFactor and propagationSpeedAdjustmentFactor. The maps are read through plot[parameter=arrival_time] into an ASCII grid, because the BMap layer is never filled outside coupled runs; bbox crops them on large domains. ForeFireRunner takes stdout and stderr like Popen, and ensemble members discard their output by default. A User Guide page runs a 32-member wind ensemble end to end, and test_ensemble.py runs in the Model Invariants workflow. --- .github/workflows/invariants.yml | 3 + CHANGELOG.md | 8 ++ TESTING.md | 13 ++ bindings/python/src/pyforefire/__init__.py | 13 +- bindings/python/src/pyforefire/_ensemble.py | 113 +++++++++++++++ bindings/python/src/pyforefire/_runner.py | 12 +- docs/source/index.rst | 1 + docs/source/user_guide/ensembles.rst | 114 ++++++++++++++++ tests/python/README.md | 16 ++- tests/python/test_ensemble.py | 144 ++++++++++++++++++++ 10 files changed, 427 insertions(+), 10 deletions(-) create mode 100644 bindings/python/src/pyforefire/_ensemble.py create mode 100644 docs/source/user_guide/ensembles.rst create mode 100644 tests/python/test_ensemble.py diff --git a/.github/workflows/invariants.yml b/.github/workflows/invariants.yml index 135a6da0..e25d4dec 100644 --- a/.github/workflows/invariants.yml +++ b/.github/workflows/invariants.yml @@ -66,3 +66,6 @@ jobs: - name: Run the worker process runner test run: ./.venv/bin/python tests/python/test_runner.py + + - name: Run the ensemble test + run: ./.venv/bin/python tests/python/test_ensemble.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 446672d2..3c75edc7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,10 +14,18 @@ history, so they summarise each release rather than list every change. The ### Added +- `pyforefire.run_ensemble` runs one simulation per member in parallel + worker processes and returns their arrival-time maps; + `pyforefire.burn_probability` turns them into a burn-probability map. A + User Guide page shows a wind ensemble end to end. ([#172]) - `ForeFireRunner.fork()` returns a new runner holding a copy of the simulation, so ensemble members can branch from one spin-up instead of rerunning it. The worker forks itself, which takes a few milliseconds where a new runner takes about 80. ([#172]) +- `ForeFireRunner(stdout=..., stderr=...)` redirects the kernel's output, as + in `subprocess.Popen`. ([#172]) +- `pyforefire.arrival_time(ff, path, bbox=None)` reads the arrival-time map + as an array, through the `plot` command. ([#172]) ### Fixed diff --git a/TESTING.md b/TESTING.md index 05e53839..396b7ea5 100644 --- a/TESTING.md +++ b/TESTING.md @@ -125,6 +125,19 @@ are separate processes. CI runs it in the Model Invariants workflow. ./.venv/bin/python tests/python/test_runner.py ``` +## Running the Ensemble Test (`test_ensemble.py`) + +Checks `pyforefire.run_ensemble` and `pyforefire.burn_probability` (#172). +Unperturbed members, forked or not, must reproduce the deterministic arrival +times exactly; a perturbation applied to forks must show in the probability +map, and a parameter read at construction must take effect with `fork=False`. +Probabilities must stay in [0, 1] and never decrease with time. CI runs it in +the Model Invariants workflow. + +```bash +./.venv/bin/python tests/python/test_ensemble.py +``` + ## Running the ANN Test (`runANN`) Validated in CI by `main.yml`. It is the only coverage for diff --git a/bindings/python/src/pyforefire/__init__.py b/bindings/python/src/pyforefire/__init__.py index 0fd7dea3..5931fa2c 100644 --- a/bindings/python/src/pyforefire/__init__.py +++ b/bindings/python/src/pyforefire/__init__.py @@ -1,7 +1,8 @@ -# src/pyforefire/__init__.py - -from .helpers import * -from ._pyforefire import * # Import the C++ extension -from ._runner import ForeFireRunner, WorkerDied - +# src/pyforefire/__init__.py + +from .helpers import * +from ._pyforefire import * # Import the C++ extension +from ._runner import ForeFireRunner, WorkerDied +from ._ensemble import run_ensemble, burn_probability, arrival_time + __all__ = ['helpers', '_pyforefire'] \ No newline at end of file diff --git a/bindings/python/src/pyforefire/_ensemble.py b/bindings/python/src/pyforefire/_ensemble.py new file mode 100644 index 00000000..dd7fea22 --- /dev/null +++ b/bindings/python/src/pyforefire/_ensemble.py @@ -0,0 +1,113 @@ +"""Run an ensemble of simulations and turn it into a burn-probability map. + +Each member runs in its own `ForeFireRunner`, so members run in parallel and +cannot disturb each other (see issue #172). + + def setup(ff): + ff.execute("FireDomain[sw=(0,0,0);ne=(1000,1000,0);t=0]") + ff.addLayer("propagation", "Iso", "propagationModel") + ff.execute("startFire[loc=(500,500,0)]") + ff.execute("goTo[t=600]") # spin-up shared by every member + + def perturb(ff, wind): + ff.execute(f"trigger[wind;vel=({wind[0]},{wind[1]},0)]") + + arrivals = run_ensemble(setup, [(3, 0), (2, 2), (0, 3)], until=3600, perturb=perturb) + probability = burn_probability(arrivals, t=1800) +""" + +import os +import subprocess +import tempfile +from concurrent.futures import ThreadPoolExecutor + +import numpy as np + +from ._runner import ForeFireRunner + +__all__ = ["run_ensemble", "burn_probability", "arrival_time"] + + +def arrival_time(ff, path, bbox=None): + """Return the arrival-time map of `ff` as an array indexed [y, x]. + + Row 0 is the south edge, and cells the front has not reached are `inf`. + `bbox=(left, bottom, right, top)` in domain coordinates crops the map to + that area at the same resolution; by default it covers the whole domain. + The map is written to `path` by the kernel's `plot` command, as an ASCII + grid with one row per x, then read back. + """ + area = "" if bbox is None else ";BBoxLBRT=({},{},{},{})".format(*bbox) + ff.execute(f"plot[parameter=arrival_time;filename={path}{area}]") + return np.loadtxt(path, skiprows=6, ndmin=2).T + + +def _set_parameters(ff, member): + for key, value in member.items(): + ff[key] = value + + +def run_ensemble(setup, members, until, perturb=_set_parameters, fork=True, + bbox=None, max_workers=None, stdout=subprocess.DEVNULL, stderr=None): + """Run one simulation per item of `members` up to time `until`. + + `setup(ff)` builds the simulation: domain, layers, ignition and any + spin-up steps. `perturb(ff, member)` applies one member's changes; by + default `member` is a dict of parameters, set with `ff[key] = value`. + + With `fork=True`, `setup` runs once and each member is a fork of it, so + `perturb` runs after `setup`. It can change the wind with + `trigger[wind;vel=(u,v,0)]`, the fuels with `trigger[fuel;...]`, or any + parameter the kernel reads while stepping. With `fork=False`, each member + gets a fresh runner and `perturb` runs before `setup`, so it can also set + the parameters read only when the domain and models are built, such as + `windReductionFactor` and `propagationSpeedAdjustmentFactor`. + + `bbox=(left, bottom, right, top)` limits the maps to that area (see + `arrival_time`). The result holds one float64 map per member, so crop a + large domain to where the fire can go. + + Members run `max_workers` at a time, one per CPU by default. The kernel's + output is discarded unless `stdout` and `stderr` say otherwise (see + `ForeFireRunner`). + + Returns the arrival times as an array indexed [member, y, x], `inf` where + a member's front did not arrive by `until`. + """ + members = list(members) + if max_workers is None: + max_workers = os.cpu_count() or 1 + + base = None + + def run(index, member): + ff = base.fork() if fork else ForeFireRunner(stdout=stdout, stderr=stderr) + with ff: + perturb(ff, member) + if not fork: + setup(ff) + ff.execute(f"goTo[t={until}]") + return arrival_time(ff, os.path.join(tmp, f"member{index}.asc"), bbox) + + with tempfile.TemporaryDirectory(prefix="forefire-ensemble-") as tmp: + try: + if fork: + base = ForeFireRunner(stdout=stdout, stderr=stderr) + setup(base) + with ThreadPoolExecutor(max_workers=max_workers) as pool: + maps = list(pool.map(run, range(len(members)), members)) + finally: + if base is not None: + base.close() + return np.stack(maps) if maps else np.empty((0, 0, 0)) + + +def burn_probability(arrivals, t=None): + """Return the fraction of members burnt at each point by time `t`. + + `arrivals` is the [member, y, x] array from `run_ensemble`. With `t` + None, a point counts as burnt if the front reached it at all. + """ + arrivals = np.asarray(arrivals) + burnt = np.isfinite(arrivals) if t is None else arrivals <= t + return burnt.mean(axis=0) diff --git a/bindings/python/src/pyforefire/_runner.py b/bindings/python/src/pyforefire/_runner.py index 3369ce21..2aaba3ea 100644 --- a/bindings/python/src/pyforefire/_runner.py +++ b/bindings/python/src/pyforefire/_runner.py @@ -8,7 +8,8 @@ The worker is a fresh interpreter (`python -m pyforefire._worker `) rather than a fork of the caller, because the caller may have threads. Requests and replies are pickled over a socket pair. The worker's stdout and stderr are the -caller's, so kernel output still shows up where it did before. +caller's unless redirected, so kernel output still shows up where it did +before. `fork()` does fork, but the worker rather than the caller: the worker has no threads, and its copy starts with the whole simulation state, which is what an @@ -84,14 +85,21 @@ class ForeFireRunner: Calls on one runner are serialised by a lock. Separate runners do not share anything and can be driven from separate threads. + + `stdout` and `stderr` redirect the kernel's output as in + `subprocess.Popen`, for example `subprocess.DEVNULL` or an open file. + By default it goes to the caller's own streams. A fork keeps the streams + of the runner it was forked from. """ - def __init__(self): + def __init__(self, stdout=None, stderr=None): parent, child = socket.socketpair() try: process = subprocess.Popen( [sys.executable, "-m", "pyforefire._worker", str(child.fileno())], pass_fds=(child.fileno(),), + stdout=stdout, + stderr=stderr, ) finally: child.close() diff --git a/docs/source/index.rst b/docs/source/index.rst index a170d273..3cb637f3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -26,6 +26,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire user_guide/fuels_and_models user_guide/landscape_file user_guide/python_arrays + user_guide/ensembles user_guide/forefire_script user_guide/core_concepts diff --git a/docs/source/user_guide/ensembles.rst b/docs/source/user_guide/ensembles.rst new file mode 100644 index 00000000..9baf478e --- /dev/null +++ b/docs/source/user_guide/ensembles.rst @@ -0,0 +1,114 @@ +.. _userguide-ensembles: + +Ensembles and burn probability +============================== + +A single simulation gives one perimeter for one wind. Wind forecasts are +uncertain, so the more useful answer is often a **burn-probability map**: run +the same fire under many plausible winds and count, for each point, the +fraction of runs that burnt it. + +``pyforefire.run_ensemble`` runs the members and returns their arrival times; +``pyforefire.burn_probability`` turns them into that map. Each member runs in +its own :class:`ForeFireRunner` worker process, so the members run in parallel +and cannot disturb each other. + +A complete example +------------------ + +The script below ignites a fire in a 4 km square domain, runs a two-minute +spin-up once, then forks 32 members that each continue under a different +easterly wind. It uses the minimal ``WindDriven`` model of +:ref:`Running from NumPy arrays ` and runs as-is +against a ``pip``-installed ForeFire. + +.. code-block:: python + + import numpy as np + import pyforefire + + L = 4000.0 + + def setup(ff): + ff["fuelsTable"] = "Index;vv_coeff;Kcurv;beta\n1;1.0;1.0;1.0" + ff["defaultFuelType"] = 1. + ff["windReductionFactor"] = 1.0 + ff["propagationModel"] = "WindDriven" + ff.execute(f"FireDomain[sw=(0,0,0);ne=({L},{L},0);t=0]") + ff.addLayer("propagation", "WindDriven", "propagationModel") + ff.addIndexLayer("table", "fuel", 0., 0., 0., L, L, 0., np.ones((1, 1, 10, 10))) + wind = np.zeros((2, 2, 10, 10)) + wind[0, 0] = 1.0 # windU along x + wind[1, 1] = 1.0 # windV along y + ff.addScalarLayer("windScalDir", "windU", 0., 0., 0., L, L, 0., wind[0:1]) + ff.addScalarLayer("windScalDir", "windV", 0., 0., 0., L, L, 0., wind[1:2]) + ff.execute("startFire[loc=(1000,2000,0);t=0]") + ff.execute("trigger[wind;loc=(0,0,0);vel=(3,0,0)]") + ff.execute("goTo[t=120]") # spin-up shared by every member + + def perturb(ff, wind): + u, v = wind + ff.execute(f"trigger[wind;loc=(0,0,0);vel=({u},{v},0)]") + + rng = np.random.default_rng(1) + angle = rng.normal(0, np.radians(20), 32) # easterly, give or take 20 degrees + speed = rng.uniform(2, 4, 32) + winds = list(zip(speed * np.cos(angle), speed * np.sin(angle))) + + arrivals = pyforefire.run_ensemble(setup, winds, until=600, perturb=perturb) + p = pyforefire.burn_probability(arrivals) + +``arrivals`` is indexed ``[member, y, x]``, with row 0 at the south edge, and +holds ``inf`` where a member's front never arrived. ``p`` is indexed ``[y, x]``. +``burn_probability(arrivals, t=300)`` gives the probability of having burnt by +``t = 300`` instead of by the end of the run, so one ensemble answers the +question for any time up to ``until``. + +To plot it: + +.. code-block:: python + + import matplotlib.pyplot as plt + + fig, ax = plt.subplots() + im = ax.imshow(p, origin="lower", extent=(0, L, 0, L), cmap="inferno", vmin=0, vmax=1) + ax.contour(pyforefire.burn_probability(arrivals, t=300), levels=[0.5], + origin="lower", extent=(0, L, 0, L), colors="cyan") + fig.colorbar(im, label="burn probability") + +What a member may change +------------------------ + +``setup(ff)`` builds the simulation; ``perturb(ff, member)`` applies one +member's changes. By default each member is a dict of parameters, set with +``ff[key] = value``. + +With the default ``fork=True``, ``setup`` runs once and each member is a +:meth:`ForeFireRunner.fork` of it, so ``perturb`` runs **after** the spin-up. +That is the fast path, but it only reaches what the kernel reads while +stepping: the wind through ``trigger[wind;...]``, the fuels through +``trigger[fuel;...]``, new ignitions, and runtime parameters. + +Some parameters are read once, when the domain and the models are built. +``windReductionFactor``, ``propagationSpeedAdjustmentFactor`` and +``Iso.speed`` are among them, so changing them on a fork has no effect. To +vary those, pass ``fork=False``: each member then gets a fresh runner and +``perturb`` runs **before** ``setup``. + +.. code-block:: python + + members = [{"propagationSpeedAdjustmentFactor": f} for f in (0.4, 0.6, 0.8)] + arrivals = pyforefire.run_ensemble(setup, members, until=600, fork=False) + +Size and output +--------------- + +* The result holds one ``float64`` map per member at the domain's burning-map + resolution. On a large domain, pass ``bbox=(left, bottom, right, top)`` in + domain coordinates to keep only the area the fire can reach. +* Members run one per CPU by default; ``max_workers`` changes that. +* The kernel's output is discarded. Pass ``stdout=None`` to see it, or an open + file to keep it. +* An exception in ``setup``, ``perturb`` or a member's run is raised again by + ``run_ensemble``; a crash of a member's kernel raises + ``pyforefire.WorkerDied``. diff --git a/tests/python/README.md b/tests/python/README.md index fb952c43..a3635d23 100644 --- a/tests/python/README.md +++ b/tests/python/README.md @@ -59,13 +59,25 @@ python tests/python/test_moisture_invariants.py # -v for every probe Checks `pyforefire.ForeFireRunner`: eight simulations, each in its own worker process and driven from a thread, must match the in-process node count, and -worker errors and crashes must surface as Python exceptions. Run in CI by -`invariants.yml`. Manually: +worker errors and crashes must surface as Python exceptions. Forks taken +mid-run must match too, and stay independent. Run in CI by `invariants.yml`. +Manually: ```bash python tests/python/test_runner.py ``` +### `test_ensemble.py` + +Checks `pyforefire.run_ensemble` and `pyforefire.burn_probability`: +unperturbed members reproduce the deterministic arrival times, perturbations +show in the probability map, and probabilities stay in [0, 1] and never +decrease with time. Run in CI by `invariants.yml`. Manually: + +```bash +python tests/python/test_ensemble.py +``` + ### `test_threading.py` Runs eight simulations in threads and requires each to reproduce the node diff --git a/tests/python/test_ensemble.py b/tests/python/test_ensemble.py new file mode 100644 index 00000000..d1e8deee --- /dev/null +++ b/tests/python/test_ensemble.py @@ -0,0 +1,144 @@ +"""Tests for `pyforefire.run_ensemble` and `pyforefire.burn_probability`. + + python tests/python/test_ensemble.py + +Exit status is 0 only if every check passes. +""" + +import os +import sys +import tempfile + +import numpy as np + +SIZE = 1000 +UNTIL = 500 + + +def setup(ff): + ff.execute(f"FireDomain[sw=(0,0,0);ne=({SIZE},{SIZE},0);t=0]") + ff.addLayer("propagation", "Iso", "propagationModel") + ff.execute(f"startFire[loc=({SIZE / 2},{SIZE / 2},0)]") + ff.execute("goTo[t=100]") + + +def deterministic(): + """The arrival times of one in-process run of `setup`.""" + import pyforefire + + ff = pyforefire.ForeFire() + setup(ff) + ff.execute(f"goTo[t={UNTIL}]") + with tempfile.TemporaryDirectory() as tmp: + return pyforefire.arrival_time(ff, os.path.join(tmp, "at.asc")) + + +def test_identical_members(reference): + """Unperturbed members, forked or not, all reproduce the deterministic run.""" + import pyforefire + + failures = [] + for fork in (True, False): + arrivals = pyforefire.run_ensemble(setup, [{}] * 3, UNTIL, fork=fork) + if arrivals.shape != (3,) + reference.shape: + failures.append(f"fork={fork}: shape {arrivals.shape}, expected {(3,) + reference.shape}") + continue + if not all(np.array_equal(a, reference) for a in arrivals): + failures.append(f"fork={fork}: a member differs from the deterministic run") + p = pyforefire.burn_probability(arrivals) + if not np.array_equal(p, np.isfinite(reference).astype(float)): + failures.append(f"fork={fork}: probability is not the deterministic burnt area") + return failures + + +def test_forked_perturbation(): + """`perturb` runs on each fork, after the shared setup.""" + import pyforefire + + def ignite(ff, loc): + if loc is not None: + ff.execute(f"startFire[loc=({loc[0]},{loc[1]},0)]") + + # By t=250 the shared fire is still far from the corner. + corner = (150, 150) + arrivals = pyforefire.run_ensemble(setup, [None, corner, corner, corner], 250, perturb=ignite) + p = pyforefire.burn_probability(arrivals) + n = arrivals.shape[1] + i = int(corner[1] / SIZE * n) + j = int(corner[0] / SIZE * n) + failures = [] + if p[i, j] != 0.75: + failures.append(f"probability {p[i, j]} at the second ignition, expected 0.75") + if p[n // 2, n // 2] != 1.0: + failures.append(f"probability {p[n // 2, n // 2]} at the shared ignition, expected 1") + return failures + + +def test_construction_parameters(): + """With fork=False, parameters read when the model is built take effect.""" + import pyforefire + + speeds = [0.5, 1.0, 2.0] + arrivals = pyforefire.run_ensemble(setup, [{"Iso.speed": s} for s in speeds], UNTIL, fork=False) + burnt = np.isfinite(arrivals).sum(axis=(1, 2)) + if not (burnt[0] < burnt[1] < burnt[2]): + return [f"burnt cells {list(burnt)} do not grow with Iso.speed {speeds}"] + return [] + + +def test_probability_properties(): + """Probabilities lie in [0, 1] and never decrease with time.""" + import pyforefire + + arrivals = pyforefire.run_ensemble(setup, [{"Iso.speed": s} for s in (0.5, 1, 1.5, 2)], UNTIL, fork=False) + failures = [] + previous = None + for t in (150, 250, 350, UNTIL): + p = pyforefire.burn_probability(arrivals, t) + if p.min() < 0 or p.max() > 1: + failures.append(f"probability outside [0, 1] at t={t}") + if previous is not None and (p < previous).any(): + failures.append(f"probability decreased somewhere between two times up to t={t}") + previous = p + if not np.array_equal(pyforefire.burn_probability(arrivals, UNTIL), pyforefire.burn_probability(arrivals)): + failures.append("the probability at `until` differs from the probability of burning at all") + return failures + + +def test_member_error(): + """An exception in one member reaches the caller.""" + import pyforefire + + def fail(ff, member): + if member: + raise ValueError("member failed") + + try: + pyforefire.run_ensemble(setup, [False, True], UNTIL, perturb=fail) + except ValueError: + return [] + return ["a failing member did not raise"] + + +def main(): + reference = deterministic() + print(f"deterministic run: {int(np.isfinite(reference).sum())} burnt cells of {reference.size}") + + failures = [] + failures += test_identical_members(reference) + failures += test_forked_perturbation() + failures += test_construction_parameters() + failures += test_probability_properties() + failures += test_member_error() + + if failures: + print(f"\nFAILED with {len(failures)} problem(s):") + for f in failures: + print(f" - {f}") + return 1 + print("OK: ensembles reproduce the deterministic run, perturbations apply, probabilities are consistent") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) From 167f5bab13b58359e5dc16ae790ac0ad71bbefba Mon Sep 17 00:00:00 2001 From: HugoFara Date: Thu, 29 Oct 2026 00:03:09 +0100 Subject: [PATCH 3/3] fix(python): read plot's arrival-time grid north row first (#229) #229 makes plot[...;filename=*.asc] write a valid ESRI grid, one row per y from the north edge, so arrival_time flips it instead of transposing it. --- bindings/python/src/pyforefire/_ensemble.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/bindings/python/src/pyforefire/_ensemble.py b/bindings/python/src/pyforefire/_ensemble.py index dd7fea22..ad096ca2 100644 --- a/bindings/python/src/pyforefire/_ensemble.py +++ b/bindings/python/src/pyforefire/_ensemble.py @@ -34,12 +34,12 @@ def arrival_time(ff, path, bbox=None): Row 0 is the south edge, and cells the front has not reached are `inf`. `bbox=(left, bottom, right, top)` in domain coordinates crops the map to that area at the same resolution; by default it covers the whole domain. - The map is written to `path` by the kernel's `plot` command, as an ASCII - grid with one row per x, then read back. + The map is written to `path` by the kernel's `plot` command, as an ESRI + ASCII grid with the north row first, then read back. """ area = "" if bbox is None else ";BBoxLBRT=({},{},{},{})".format(*bbox) ff.execute(f"plot[parameter=arrival_time;filename={path}{area}]") - return np.loadtxt(path, skiprows=6, ndmin=2).T + return np.flipud(np.loadtxt(path, skiprows=6, ndmin=2)) def _set_parameters(ff, member):