Merge branch 'dev'

Author: filippi

.github/workflows/docker.yml

@@ -1,29 +1,58 @@
-name: Docker
+name: Build, Test, and Push Docker Image
 
 on:
   push:
-    branches:
-      - "master"
-      # - "dev-ci"
+    branches: [ "master" ]
+    tags: [ 'v*.*.*' ] # Trigger on semver tags
   pull_request:
     branches: [ "master" ]
-
   workflow_dispatch:
 
-jobs:
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
 
-  docker:
+jobs:
+  build-test-and-push:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          lfs: true
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
 
-      - name: Build Docker Image
-        run: docker build -t forefire:latest .
+      - name: Build and push Docker image
+        id: build-and-push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          # Only push if the ref starts with 'refs/tags/'
+          push: ${{ startsWith(github.ref, 'refs/tags/') }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          load: true
 
-      - name: Check ForeFire version inside Docker
+      - name: Run 'runff' Test Script on the built image
         run: |
-          docker run --rm forefire:latest forefire -v
+          TEST_TAG=$(echo "${{ steps.meta.outputs.tags }}" | head -n 1)
+          echo "Testing image with tag: $TEST_TAG"
+          docker run --rm $TEST_TAG bash -c "cd tests/runff && bash ff-run.bash"

.github/workflows/macos.yml

@@ -13,7 +13,9 @@ jobs:
     runs-on: macos-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+        with:
+          lfs: true
 
       - name: Make install script executable
         run: chmod +x ./install-forefire-osx.sh
@@ -23,3 +25,18 @@ jobs:
 
       - name: Check ForeFire version
         run: ./bin/forefire -v
+
+      - name: Install Python test dependencies
+        run: pip3 install --break-system-packages lxml xarray netCDF4
+
+      - name: Add Build/Runtime Diagnostics
+        run: |
+          echo "--- Input data.nc Info ---"
+          ls -lh tests/runff/data.nc
+          brew install netcdf
+          ncdump -k tests/runff/data.nc || echo "Could not check data.nc format"
+
+      - name: Run 'runff' Test Script
+        run: |
+          cd tests/runff
+          bash ff-run.bash

Dockerfile

@@ -12,6 +12,9 @@ RUN apt-get update && \
     git && \
     rm -rf /var/lib/apt/lists/*
 
+# Install Python dependencies for testing
+RUN pip3 install --no-cache-dir lxml xarray netCDF4
+
 WORKDIR /forefire
 ENV FOREFIREHOME=/forefire
 
@@ -24,7 +27,7 @@ RUN sh cmake-build.sh
 # Add the main forefire executable to the PATH
 RUN cp /forefire/bin/forefire /usr/local/bin/
 
-# Use pip to install the Python dependencies defined in pyproject.toml
+# Use pip to install the Python bindings
 RUN pip3 install ./bindings/python
 
 # Set the entrypoint to bash for interactive sessions

docs/source/index.rst

@@ -22,7 +22,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire
    :caption: User Guide
 
    user_guide/basic_configuration
-   user_guide/fuels_file
+   user_guide/fuels_and_models
    user_guide/landscape_file
    user_guide/forefire_script
    user_guide/core_concepts

docs/source/reference/parameters.rst

@@ -171,8 +171,13 @@ Physics & Models
 
 propagationModel
 """"""""""""""""
-*   **Description:** Name of the primary Rate of Spread (ROS) model to use for calculating fire spread speed (e.g., `Iso`, `Rothermel`, `Balbi`). Specific models may have their own parameters (e.g., `Iso.speed`).
+*   **Description:** Name of the Rate of Spread (ROS) model to use. ForeFire is a general solver, and this choice dictates how spread speed is calculated and what fuel parameterization is required.
 *   **Default:** `Iso`
+*   **Available Models:** The string provided must match the name of a registered C++ model class. Common supported models include:
+    *   `Iso`: A simple isotropic model. Does not use a fuels file. Speed is set via the `Iso.speed` parameter.
+    *   `Rothermel`: The Rothermel 1972 surface fire spread model. Requires a detailed fuel parameterization file.
+    *   `BalbiNov2011`, `Balbi2015`: Physical models from Balbi et al. Also use the fuel parameterization file.
+*   **More Info:** See the :doc:`/user_guide/fuels_and_models` guide for detailed explanations of each model and their data requirements.
 
 burningTresholdFlux
 """""""""""""""""""

docs/source/user_guide/basic_configuration.rst

@@ -3,13 +3,20 @@ Basic Configuration
 
 ForeFire simulations typically require three main input files to run:
 
-1.  **Fuels File (.csv)**: Defines the classes of fuels and their associated parameters used by the fire spread model (e.g., Rothermel).
-2.  **Landscape File (.nc)**: A NetCDF file containing geospatial data layers for the simulation domain, typically including:
+1.  **Model Parameter File (e.g., fuels.csv)**:
+    
+    A file that defines physical parameters required by the selected propagation model. For example, the `Rothermel` and `Balbi` models use a ``fuels.csv`` file to define fuel bed properties. Other models, like `Iso`, do not require an external file. See the :doc:`Fuels & Models guide <fuels_and_models>` for details.
+2.  **Landscape File (.nc)**:
+
+A NetCDF file containing geospatial data layers for the simulation domain, typically including:
 
     - Elevation (Digital Elevation Model - DEM)
     - Fuel types map (matching the indices in the Fuels File)
     - (Optionally) Pre-defined wind fields or other environmental data.
-3.  **ForeFire Script File (.ff)**: A text file containing commands and parameters that control the simulation execution. This includes:
+
+3.  **ForeFire Script File (.ff)**:
+
+A text file containing commands and parameters that control the simulation execution. This includes:
 
     - Setting simulation parameters (e.g., propagation model, output format).
     - Loading the landscape and fuels data.

docs/source/user_guide/fuels_and_models.rst

@@ -0,0 +1,102 @@
+.. _userguide-fuels-and-models:
+
+Fuel & Model Parameterization
+=============================
+
+A core feature of ForeFire is its flexibility as a **general Rate of Spread (ROS) model solver**. Rather than being tied to a single fire spread equation, it can use different physical or empirical models depending on the user's needs. This is controlled via the :ref:`propagationModel <param-propagationModel>` parameter.
+
+.. note::
+   **For New Users:** The most common use case for ForeFire is simulating surface wildfires using the standard **Rothermel** model. This model **requires a ``fuels.csv`` file**. If this is your goal, you can skip directly to the section :ref:`The Rothermel / Balbi Fuel File <rothermel-fuel-file>` to learn how to prepare this critical input.
+
+The choice of propagation model is critical because it dictates what physical parameters the simulation requires. This guide explains the available models and how to provide the necessary parameterization for each.
+
+Available Propagation Models
+----------------------------
+
+ForeFire includes several built-in propagation models. Below are the primary models intended for general use. For a complete list of all implemented models, including experimental ones, users can refer to the C++ source code.
+
+**Iso**
+^^^^^^^
+*   **Description:** A simple isotropic model where the fire spreads at a constant rate in all directions. It ignores all environmental factors except for blocking terrain.
+*   **Use Case:** Ideal for simple tests, debugging setups, or scenarios where a constant spread rate is desired.
+*   **Parameterization:** This model **does not** use an external fuels file. The spread speed is set directly in the simulation script via a model-specific parameter.
+*   **Example:**
+
+  .. code-block:: bash
+
+    setParameter[propagationModel=Iso]
+    setParameter[Iso.speed=0.5]  # Sets spread to 0.5 meters/second
+
+**Rothermel**
+^^^^^^^^^^^^^
+*   **Description:** Implements the Rothermel (1972) surface fire spread model, a widely used semi-empirical model in wildfire simulation.
+*   **Use Case:** The standard choice for simulating surface fire spread in various fuel types (grass, shrub, timber litter).
+*   **Parameterization:** This model requires a detailed set of fuel bed parameters. These are provided via a **CSV file**, the format of which is detailed in the section below.
+
+**Balbi** variants (e.g., `BalbiNov2011`, `Balbi2015`)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*   **Description:** Implements physical models based on the work of Balbi et al. These models take a different approach from Rothermel, often considering factors like flame geometry and radiative heat transfer more explicitly.
+*   **Use Case:** Primarily for research applications, model comparison studies, or scenarios where a more physics-based approach is preferred.
+*   **Parameterization:** These models also source their parameters from the same CSV fuel file format used by Rothermel, though they may use a different subset of the columns for their calculations.
+
+.. note::
+  The relationship between a model and its parameters is key: when a model like `Rothermel` is selected, it informs the simulation engine which properties it needs (e.g., `slope`, `normalWind`, `fuel.Rhod`, etc.). The engine then provides these values, retrieving the `fuel.*` properties from the loaded CSV table.
+
+----
+
+.. _rothermel-fuel-file:
+
+The Rothermel / Balbi Fuel File (`fuels.csv`)
+-----------------------------------------------
+
+When a `propagationModel` like `Rothermel` or a `Balbi` variant is selected, ForeFire needs a file that defines the physical characteristics of the fuel types present in the landscape.
+
+**File Format**
+
+*   **Format:** Comma Separated Value (CSV).
+*   **Delimiter:** The parser expects a **semicolon (`;`)** as the delimiter.
+*   **Header:** The first line *must* be a header row containing the exact column names specified below. The file parser requires all columns to be present, even if a specific model does not use all of them.
+
+**Required Columns**
+
+The ``Index`` column links these properties to the integer values in the landscape file's fuel layer.
+
+*   ``Index``: **Critical.** Unique non-negative integer for the fuel type (e.g., `0` for non-burnable).
+*   ``Rhod``: Oven-dry particle density (kg/m³).
+*   ``Rhol``: (Model Specific)
+*   ``Md``: Oven-dry fuel moisture content (dimensionless ratio, e.g., 0.1 for 10%).
+*   ``Ml``: (Model Specific)
+*   ``sd``: Surface-area-to-volume ratio of dry fuel (m²/m³).
+*   ``sl``: (Model Specific)
+*   ``e``: Fuel bed depth (meters).
+*   ``Sigmad``: Oven-dry fuel load (kg/m²).
+*   ``Sigmal``: (Model Specific)
+*   ``stoch``: (Model Specific)
+*   ``RhoA``: (Model Specific)
+*   ``Ta``: (Model Specific)
+*   ``Tau0``: (Model Specific)
+*   ``Deltah``: (Model Specific)
+*   ``DeltaH``: Fuel particle heat content (J/kg).
+*   ``Cp``: (Model Specific)
+*   ``Cpa``: (Model Specific)
+*   ``Ti``: (Model Specific)
+*   ``X0``: (Model Specific)
+*   ``r00``: (Model Specific)
+*   ``Blai``: (Model Specific)
+*   ``me``: Moisture content of extinction (dimensionless ratio).
+
+.. important::
+   While all columns are required by the file parser, the parameters most fundamentally driving the *Rothermel* calculation are typically: ``Index``, ``Rhod``, ``Md``, ``sd``, ``e``, ``Sigmad``, ``DeltaH``, and ``me``. Different models may utilize different columns.
+
+----
+
+Finding and Creating Fuel Parameter Sets
+----------------------------------------
+
+Finding appropriate fuel parameter values is a scientific task in itself. Users have two primary resources:
+
+1.  **Reference Examples:** The test cases within the ForeFire repository (e.g., `tests/runff/fuels.csv`) provide the best and intended reference for a correctly formatted file.
+2.  **External Parameter Libraries:** For users looking for standard or pre-published fuel parameter sets, the following external repository, maintained by the ForeFire team, is the recommended resource:
+
+    *   **wildfire_ROS_models:** `https://github.com/forefireAPI/wildfire_ROS_models`
+    *   This repository contains parameterizations for various fuel models and is a valuable companion to ForeFire for preparing simulation inputs.