Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions .github/workflows/wasm.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
name: 🌐 Build WASM

# Builds the WebAssembly module (issue #171) and runs the Node smoke test. The
# .wasm is built here rather than committed: it is a megabyte of generated
# output, and a stale binary next to live sources is worse than a two minute
# build.

on:
push:
branches:
- "master"
- "dev"
pull_request:
branches: [ "master", "dev" ]
workflow_dispatch:

permissions:
contents: read

jobs:
build-wasm:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v6
# No LFS: the WASM build reads no test data, and emcmake turns the
# integrity check off by default.

- name: Cache Emscripten SDK
id: emsdk-cache
uses: actions/cache@v4
with:
path: ~/emsdk
key: emsdk-${{ runner.os }}-6.0.6

- name: Install Emscripten
if: steps.emsdk-cache.outputs.cache-hit != 'true'
run: |
# Pinned to the version the module was developed and tested against.
git clone --depth 1 https://github.com/emscripten-core/emsdk.git ~/emsdk
~/emsdk/emsdk install 6.0.6
~/emsdk/emsdk activate 6.0.6

- name: Build the WebAssembly module
run: |
source ~/emsdk/emsdk_env.sh
emcmake cmake -S . -B build-wasm -DCMAKE_BUILD_TYPE=Release
cmake --build build-wasm -j"$(nproc)"

- name: Report size
run: |
{
echo "### WebAssembly build"
echo "| file | raw | gzip | brotli |"
echo "| --- | --- | --- | --- |"
for f in bin/forefire.wasm bin/forefire.mjs; do
printf '| `%s` | %s | %s | %s |\n' "$(basename "$f")" \
"$(stat -c%s "$f" | numfmt --to=iec)" \
"$(gzip -c "$f" | wc -c | numfmt --to=iec)" \
"$(brotli -c "$f" | wc -c | numfmt --to=iec)"
done
} | tee -a "$GITHUB_STEP_SUMMARY"

- name: Smoke test under Node
run: node bindings/wasm/smoke.mjs bin/forefire.mjs
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,11 @@ Merged since v2.5.0, not yet released.
the first step towards a WebAssembly build and a slim wheel. Commands that
read or write NetCDF files report that the build has no NetCDF support.
The default stays on. ([#171])
- An experimental WebAssembly build: `emcmake cmake` compiles the engine
without NetCDF into an ES module whose embind API mirrors `pyforefire`, with
typed arrays in place of NumPy arrays. `FOREFIRE_BUILD_CLI` and
`FOREFIRE_BUILD_WASM` control the two executables. See
`bindings/wasm/README.md`. ([#171])

### Fixed

Expand Down
82 changes: 76 additions & 6 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,28 @@ else()
set(_ff_default_tests ON)
endif()

# Emscripten has no NetCDF and no reason for one: a browser build reads its
# data from JS typed arrays. Detecting it here rather than making the caller
# pass the flags keeps `emcmake cmake` a one-liner.
if(EMSCRIPTEN)
set(_ff_default_mpi OFF)
set(_ff_default_native OFF)
set(_ff_default_python OFF)
set(_ff_default_static ON)
set(_ff_default_tools OFF)
set(_ff_default_lfs OFF)
set(_ff_default_netcdf OFF)
set(_ff_default_cli OFF)
set(_ff_default_tests OFF)
else()
set(_ff_default_netcdf ON)
set(_ff_default_cli ON)
endif()

option(FOREFIRE_ENABLE_MPI "Enable MPI coupling when MPI is available" ${_ff_default_mpi})
option(FOREFIRE_ENABLE_NETCDF "Build the NetCDF-backed I/O paths" ON)
option(FOREFIRE_ENABLE_NETCDF "Build the NetCDF-backed I/O paths" ${_ff_default_netcdf})
option(FOREFIRE_BUILD_CLI "Build the interactive forefire command line shell" ${_ff_default_cli})
option(FOREFIRE_BUILD_WASM "Build the Emscripten/embind module" ${EMSCRIPTEN})
option(FOREFIRE_NATIVE_ARCH "Optimise for the build machine's CPU (-march=native)" ${_ff_default_native})
option(FOREFIRE_BUILD_PYTHON "Build the pyforefire Python extension module" ${_ff_default_python})
option(FOREFIRE_STATIC_CORE "Build the ForeFire core as a static library" ${_ff_default_static})
Expand Down Expand Up @@ -270,6 +290,12 @@ if(FOREFIRE_WARNINGS_AS_ERRORS AND _ff_warning_flags)
endif()
endif()

if(EMSCRIPTEN)
# Emscripten defaults to -fno-exceptions; the command parser signals bad
# input by throwing, so every translation unit needs them enabled.
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fexceptions")
endif()

# ----------------------------------
# Output Directories
# ----------------------------------
Expand Down Expand Up @@ -330,10 +356,14 @@ endif()
# ----------------------------------
# Main Project Executable
# ----------------------------------
add_executable(forefire app/forefire/ForeFire.cpp app/forefire/AdvancedLineEditor.cpp)
target_link_libraries(forefire PRIVATE forefireL)
if(_ff_warning_flags)
target_compile_options(forefire PRIVATE ${_ff_warning_flags})
# The shell is termios-driven and has no meaning in a browser, so a WASM build
# skips it and ships the embind module below instead.
if(FOREFIRE_BUILD_CLI)
add_executable(forefire app/forefire/ForeFire.cpp app/forefire/AdvancedLineEditor.cpp)
target_link_libraries(forefire PRIVATE forefireL)
if(_ff_warning_flags)
target_compile_options(forefire PRIVATE ${_ff_warning_flags})
endif()
endif()

# ----------------------------------
Expand All @@ -344,6 +374,44 @@ if(FOREFIRE_BUILD_TESTS)
add_subdirectory(tests/unit)
endif()

# ----------------------------------
# WebAssembly Module
# ----------------------------------
if(FOREFIRE_BUILD_WASM)
add_executable(forefire_wasm bindings/wasm/forefire_wasm.cpp)
target_link_libraries(forefire_wasm PRIVATE forefireL)
# Two things are non-obvious here. embind refuses to compile below C++17,
# so this one translation unit moves up while the core stays on C++11 —
# both sit on the same libc++. And the output is an ES module, which Node
# only recognises from a .js file when a package.json says so, hence .mjs.
set_target_properties(forefire_wasm PROPERTIES
OUTPUT_NAME "forefire"
SUFFIX ".mjs"
CXX_STANDARD 17
CXX_STANDARD_REQUIRED ON)
target_link_options(forefire_wasm PRIVATE
"--bind"
# A single ES module plus its .wasm, so a static page can import it.
"-sMODULARIZE=1"
"-sEXPORT_ES6=1"
"-sEXPORT_NAME=createForeFire"
"-sENVIRONMENT=web,worker,node"
# The domain allocates its grids up front and can grow well past the
# 16 MB default; the fire domain sizes are not known at build time.
"-sALLOW_MEMORY_GROWTH=1"
"-sINITIAL_MEMORY=64MB"
"-sSTACK_SIZE=4MB"
# C++ exceptions are load-bearing here: BadOption and friends are how
# the command parser reports bad input.
"-fexceptions"
# There is no main(): the module is driven entirely through embind.
# FS stays exported so callers can stage fuels.csv and read back what
# print[<file>] writes.
"-sEXPORTED_RUNTIME_METHODS=['FS']"
"-sFORCE_FILESYSTEM=1")
target_compile_options(forefire_wasm PRIVATE "-fexceptions")
endif()

# ----------------------------------
# Python Extension Module
# ----------------------------------
Expand Down Expand Up @@ -386,7 +454,9 @@ if(NOT _ff_wheel_build)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_SOURCE_DIR}/LICENSE") # Adjust as necessary

# Specify installation directories
install(TARGETS forefire RUNTIME DESTINATION bin)
if(FOREFIRE_BUILD_CLI)
install(TARGETS forefire RUNTIME DESTINATION bin)
endif()
if(NOT FOREFIRE_STATIC_CORE)
# With a static core there is no libforefireL to install: it is linked
# straight into the executables.
Expand Down
110 changes: 110 additions & 0 deletions bindings/wasm/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# ForeFire in WebAssembly

Follow-up to [issue #171](https://github.com/forefireAPI/forefire/issues/171):
compile the engine to WebAssembly and run a simulation with no NetCDF, in Node
or in a browser tab.

This is an experimental build, not a supported one yet. It answers the three
questions the issue left open: does it link, does it run, how big is it.

`.github/workflows/wasm.yml` builds the module and runs `smoke.mjs` on every
pull request. The `.wasm` is built in CI rather than committed: it is a
megabyte of generated output, and a stale binary sitting next to live sources
is worse than a two minute build.

## What made it possible

`#include <netcdf>` sat in `src/DataBroker.h`, and the `using namespace netCDF`
next to it pulled the dependency into 48 of the 58 files in `src/`.
`-DFOREFIRE_ENABLE_NETCDF=OFF` (#208) compiles that include out, along with
every code path behind it, and leaves a stub in each entry point that reports
the missing support. The command table is unchanged, so a script that reaches
for NetCDF gets a message instead of a link error.

Nothing else needed touching. MPI was already behind `MPI_COUPLING`, the HTTP
server and `popen` are never reached from the WASM entry point, and `termios`
lives only in the CLI shell, which a WASM build does not compile.

## Building

Needs Emscripten. With the SDK image:

```sh
podman run --rm -v "$PWD":/w:z -w /w docker.io/emscripten/emsdk:6.0.6 bash -lc '
emcmake cmake -S . -B build-wasm -DCMAKE_BUILD_TYPE=Release &&
cmake --build build-wasm -j8'
```

`emcmake` sets `EMSCRIPTEN`, which turns off NetCDF, MPI, the Python module,
the unit tests and the CLI shell, and turns on `forefire_wasm`. The outputs
land in `bin/`:

| File | Size | gzip | brotli |
| --- | --- | --- | --- |
| `forefire.wasm` | 990 KB | 298 KB | 224 KB |
| `forefire.mjs` | 131 KB | 33 KB | — |

Roughly 257 KB over the wire with brotli, for the whole engine and all its
propagation and flux models.

## Running

Headless, under Node:

```sh
node bindings/wasm/smoke.mjs bin/forefire.mjs
```

## The API

`forefire.mjs` is an ES module exporting a `createForeFire()` factory. It
mirrors the pybind11 module in `bindings/python`, with typed arrays in place of
NumPy arrays — see
[Running from NumPy arrays](../../docs/source/user_guide/python_arrays.rst) for
the concepts, which carry over unchanged.

```js
import createForeFire from "./forefire.mjs";

const Module = await createForeFire();
const ff = new Module.ForeFire();

ff.setString("propagationModel", "WindDriven");
ff.execute("FireDomain[sw=(0,0,0);ne=(4000,4000,0);t=0]");
ff.addLayer("propagation", "WindDriven", "propagationModel");
ff.addIndexLayer("table", "fuel", 0, 0, 0, 4000, 4000, 0, 200, 200, 1, 1, fuelArray);
ff.execute("startFire[loc=(2000,2000,0.);t=0]");
ff.execute("step[dt=30]");
const front = ff.execute("print[]");
```

The layer methods take the four dimensions explicitly — `nx, ny, nz, nt` — where
the NumPy binding reads them off the array's shape. Otherwise the contract is
identical: pass a flat C-order `(t, z, y, x)` array, indexed
`x + nx * (y + ny * (z + nz * t))`, exactly as `numpy.ndarray.ravel()` would
give you. The binding transposes it into the x-major order the data layers
index with, the same shuffle `_pyforefire.cpp` performs.

## What was measured

- **All 58 files in `src/` compile** under `em++` with
`FOREFIRE_ENABLE_NETCDF=OFF`. Zero errors. The only diagnostics are seven
`-Wvla-cxx-extension` warnings, the latent portability issue #171 already
flags.
- **It links and runs.** `smoke.mjs` runs a full 240 s simulation.
- **The answers match the Python binding.** `smoke.mjs` is a line-for-line port
of the worked example in the NumPy documentation. Run against a native
`pyforefire` built from the same tree, the two agree exactly: 349 front nodes,
x 1980..3905, y 1763..2308, the front stretched downwind as the doc describes.

## Known limits

- **Single-threaded.** Emscripten pthreads need `SharedArrayBuffer` and
COOP/COEP headers, which is exactly the deployment complexity a static page
is meant to avoid. Nothing in the engine's simulation path threads today —
only the HTTP server does, and it is not reachable here.
- **The embind translation unit is C++17**; the core stays C++11. embind
refuses to compile below C++17, and mixing is fine against one libc++.
- **No file I/O worth the name.** `FS` is exported so a caller can stage
`fuels.csv` or read back what `print[<file>]` writes, but there is no landscape
file support at all — arrays are the only way in.
Loading
Loading