forefireAPI · antonio-leblanc · Apr 30, 2025 · Apr 28, 2025 · Apr 28, 2025 · Apr 28, 2025
diff --git a/.gitignore b/.gitignore
@@ -49,3 +49,4 @@ tests/python/log.txt
 tests/python/runROS.bash
 changeLicense.py
 httpConnectInfo.txt
+tools/ai
diff --git a/README.md b/README.md
@@ -4,8 +4,8 @@
 
 
 ---
-[![linuxCI](https://github.com/forefireAPI/firefront/actions/workflows/main.yml/badge.svg)](https://github.com/forefireAPI/firefront/actions/workflows/main.yml)
-[![macOSCI](https://github.com/forefireAPI/firefront/actions/workflows/macos.yml/badge.svg)](https://github.com/forefireAPI/firefront/actions/workflows/macos.yml)
+[![linuxCI](https://github.com/forefireAPI/forefire/actions/workflows/main.yml/badge.svg)](https://github.com/forefireAPI/forefire/actions/workflows/main.yml)
+[![macOSCI](https://github.com/forefireAPI/forefire/actions/workflows/macos.yml/badge.svg)](https://github.com/forefireAPI/forefire/actions/workflows/macos.yml)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 ![Language](https://img.shields.io/badge/C++-00599C?logo=c%2B%2B&logoColor=white)
 ![Language](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white)
@@ -45,7 +45,7 @@ The easiest way to get started is often using Docker and the interactive console
 
     ``` bash
     # Clone the repository
-    git clone https://github.com/forefireAPI/firefront.git
+    git clone https://github.com/forefireAPI/forefire.git
     cd firefront
     ```
 

diff --git a/bindings/python/README.md b/bindings/python/README.md
@@ -115,5 +115,5 @@ This project is licensed under the terms specified in the `LICENSE` file.
 
 ## Project URLs
 
-- **Homepage:** [https://github.com/forefireAPI/firefront](https://github.com/forefireAPI/firefront)
-- **Repository:** [https://github.com/forefireAPI/firefront](https://github.com/forefireAPI/firefront)
+- **Homepage:** [https://github.com/forefireAPI/forefire](https://github.com/forefireAPI/forefire)
+- **Repository:** [https://github.com/forefireAPI/forefire](https://github.com/forefireAPI/forefire)
diff --git a/bindings/python/pyproject.toml b/bindings/python/pyproject.toml
@@ -25,5 +25,5 @@ classifiers = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/forefireAPI/firefront"
-Repository = "https://github.com/forefireAPI/firefront"
+Homepage = "https://github.com/forefireAPI/forefire"
+Repository = "https://github.com/forefireAPI/forefire"
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -1,4 +1,8 @@
 .wy-nav-side .wy-menu-vertical header,
 .wy-nav-side .wy-menu-vertical p.caption {
   color: #F86C23 !important;
+}
+
+.wy-nav-side .wy-menu-vertical a:active {
+  background-color: rgba(248, 108, 35, 0.4) !important;
 }
diff --git a/docs/source/about/license.rst b/docs/source/about/license.rst
@@ -3,4 +3,4 @@ License
 
 ForeFire is licensed under the **GNU General Public License v3.0 (GPLv3)**.
 
-You can find the full license text in the `LICENSE <https://github.com/forefireAPI/firefront/blob/master/LICENSE>`_ file in the root of the project repository.
+You can find the full license text in the `LICENSE <https://github.com/forefireAPI/forefire/blob/master/LICENSE>`_ file in the root of the project repository.
diff --git a/docs/source/installation.rst → docs/source/getting_started/installation.rst b/docs/source/installation.rst → docs/source/getting_started/installation.rst
@@ -32,7 +32,7 @@ The repository provides a convenience script (`install-forefire.sh`) that automa
 
   .. code-block:: bash
 
-    git clone https://github.com/forefireAPI/firefront.git
+    git clone https://github.com/forefireAPI/forefire.git
     cd firefront
 
 2.  **Run the install script:**
@@ -65,7 +65,7 @@ Use this method if you are not on Debian/Ubuntu, prefer manual control, or don't
 
   .. code-block:: bash
 
-    git clone https://github.com/forefireAPI/firefront.git
+    git clone https://github.com/forefireAPI/forefire.git
     cd firefront
 
 2.  **Install Prerequisites Manually:**
@@ -87,7 +87,12 @@ Use this method if you are not on Debian/Ubuntu, prefer manual control, or don't
     cmake ..
     make
 
-The main executable `forefire` will be located at `../bin/forefire` (relative to the `build` directory).
+The main executable `forefire` will be located at `../bin/forefire` (relative to the `build` directory). Check installation with
+
+  .. code-block:: bash
+
+    cd .. # Go back to the root of the repository
+    ./bin/forefire -v
 
 4. **Making ForeFire Executable System-Wide (Manual PATH setup)**
 

diff --git a/docs/source/getting_started/introduction.rst b/docs/source/getting_started/introduction.rst
@@ -0,0 +1,67 @@
+.. _introduction:
+
+Introduction
+============
+
+Welcome to the official documentation for ForeFire.
+
+What is ForeFire?
+-----------------
+
+ForeFire is a powerful, open-source **wildfire simulation engine** written in C++. Its core purpose is to simulate the spread of wildfires over complex terrain using various physical models and geospatial data inputs.
+
+Architecturally, it consists of two primary components:
+
+1.  **Simulation Engine (Library):**
+
+  The core C++ logic containing the physics, data structures, and simulation algorithms. This is compiled into a **reusable shared library** (``libforefireL.so``/``.dylib``) which can be directly linked by other programs (e.g., for atmospheric coupling).
+
+2.  **Interpreter (Executable):**
+
+  The ``forefire`` program acts as the primary user interface. It's a **command-line interpreter** that reads instructions and directs the underlying Simulation Engine. Users interact with the interpreter via:
+
+  - Script files (``.ff``)
+  - Interactive console commands
+  - A web UI (powered by the ``listenHTTP[]`` command)
+
+This separation allows ForeFire to function both as a standalone simulation tool and as an embeddable computational engine for larger systems.
+
+Key Capabilities
+----------------
+
+- **Physics-Based Simulation:** Implements established Rate of Spread (ROS) models (e.g., based on Rothermel equations) and provides a framework for adding custom models.
+- **Geospatial Data Handling:** Natively uses NetCDF files for input data layers such as elevation, fuel type, and weather variables.
+- **Fire-Atmosphere Coupling:** Explicitly designed for two-way coupling with atmospheric models (e.g., MesoNH) to capture crucial wind-fire interactions.
+- **High-Performance Computing:** The C++ core is optimized for performance, and MPI support enables efficient parallel execution on multi-core systems and clusters, allowing for large-scale and faster-than-real-time simulations.
+- **Multiple Interaction Modes:** Accessible via command-line scripts, an interactive console, a web-based visualization interface, direct C++ library linking, and potentially Python bindings.
+- **Extensibility:** Users can implement and integrate their own C++ modules for specific fire behavior (ROS) or flux calculations.
+- **Open Source:** Developed under the GPLv3 license, fostering transparency and community contributions.
+
+Intended Use Cases
+------------------
+
+ForeFire is suitable for a range of applications, including:
+
+- Wildfire behavior research
+- Detailed reanalysis of past fire events
+- Operational or near-real-time fire spread forecasting (standalone or ensemble)
+- Investigating fire-atmosphere interactions through coupled simulations
+- Testing and comparing different fire spread models
+
+Supported Platforms
+-------------------
+
+ForeFire is primarily developed and tested on **Unix-like systems (Linux and macOS)**. It can run o Windows via **WSL** (windows Subsystem for Linux) or **Docker**.
+
+About This Documentation
+------------------------
+
+This documentation aims to provide comprehensive guidance for users and developers. It is organized into the following main sections:
+
+- **Getting Started:** Installation, quick start guides, and running basic examples.
+- **User Guide:** Explanations of core concepts, configuration files, and common workflows.
+- **Reference:** Detailed reference material for commands, parameters, and file formats.
+- **API Reference:** Documentation for the C++ library classes and functions (generated from source code).
+- **About:** License, citation information, and acknowledgements.
+
+We recommend starting with the :doc:`quickstart` or :doc:`installation` guides.
diff --git a/docs/source/quickstart.rst → docs/source/getting_started/quickstart.rst b/docs/source/quickstart.rst → docs/source/getting_started/quickstart.rst
@@ -1,7 +1,7 @@
 Quick Start
 ===========
 
-This guide shows the quickest way to **see ForeFire in action** using its interactive web console, powered by **Docker**. This method bundles all dependencies, so you don't need to install them on your host system, and is the only way to run ForeFire on Windows.
+This guide shows the quickest way to get the standard **ForeFire example simulation running** using its interactive web console, powered by Docker. This method bundles all dependencies, so you don't need to install them on your host system, and is the only way to run ForeFire on Windows.
 
 Prerequisites
 -------------
@@ -15,7 +15,7 @@ Steps
 
   .. code-block:: bash
 
-    git clone https://github.com/forefireAPI/firefront.git
+    git clone https://github.com/forefireAPI/forefire.git
 
 2.  **Build the Docker image:**
 

diff --git a/docs/source/getting_started/running_the_example.rst b/docs/source/getting_started/running_the_example.rst
@@ -0,0 +1,133 @@
+.. _running-the-example:
+
+Running an Example
+==================
+
+After successfully installing ForeFire (either :doc:`from source <installation>` or via :doc:`Docker <quickstart>`), you can run the example simulation located in the ``tests/runff/`` directory. This helps verify your installation and introduces you to the basic command execution methods.
+
+Simulation Files Used
+---------------------
+
+The directory ``tests/runff/`` contains the necessary files for the ``real_case.ff`` simulation:
+
+- ``real_case.ff``: The main **script file** defining the simulation steps and commands. This is the file we will execute.
+- ``params.ff``: Contains simulation parameters (like model choices, resolutions) included by ``real_case.ff``.
+- ``data.nc``: The NetCDF **landscape file** containing geospatial data (elevation, fuel types) for the simulation domain.
+- ``fuels.csv``: The **fuels definition file**, specifying properties for different fuel types referenced in ``data.nc``.
+
+The ``real_case.ff`` file itself contains a sequence of ForeFire commands that set up parameters, load data, define an ignition, run the simulation, and save results. To learn about the syntax, structure, and typical commands used within a ``.ff`` script file, please refer to the :doc:`ForeFire Script File guide </user_guide/forefire_script>`.
+
+Executing the Example Script
+----------------------------
+
+The following sections demonstrate three different ways to execute the commands contained within the ``real_case.ff`` script using the ``forefire`` interpreter.
+
+1: Direct Execution (Command Line / Batch Mode)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the simplest way to run a simulation non-interactively by feeding the entire script file to the interpreter. It's useful for automated runs.
+
+1.  **Navigate to the test directory:**
+
+  Ensure your terminal's current directory is the root of the cloned `firefront` repository. Then navigate:
+
+  .. code-block:: bash
+
+    cd tests/runff
+
+2.  **Execute using the** ``-i`` **flag:**
+
+  This tells ForeFire to read and execute all commands sequentially from the specified file (``real_case.ff``).
+
+  If ``forefire`` is in your PATH:
+
+  .. code-block:: bash
+
+    forefire -i real_case.ff
+
+  If ``forefire`` is NOT in your PATH (run from the root of the repo):
+
+  .. code-block:: bash
+
+    ../../bin/forefire -i real_case.ff
+
+3.  **Observe:** ForeFire will print status messages to the console as it executes the commands within ``real_case.ff``. It will likely create output files (as specified by ``print``/``save`` commands in the script) in the current directory (``tests/runff``).
+
+2: Interactive Console
+~~~~~~~~~~~~~~~~~~~~~~
+
+This method starts the ForeFire interpreter first, allowing you to execute the script file using the ``include`` command, and potentially interact further before or after.
+
+1.  **Navigate to the test directory** (if not already there):
+
+  .. code-block:: bash
+
+    cd tests/runff
+
+2.  **Start the ForeFire interpreter:**
+
+  If ``forefire`` is in your PATH:
+
+  .. code-block:: bash
+
+    forefire
+
+  If ``forefire`` is NOT in your PATH (run from the root of the repo):
+
+  .. code-block:: bash
+
+    ../../bin/forefire
+
+3.  **Run the script using the** ``include`` **command:**
+
+  Once you see the ``forefire>`` prompt, type the command to execute the script file.
+
+  .. code-block:: none
+
+    forefire> include[input=real_case.ff]
+
+
+4.  **Observe:** The simulation will run similarly to Method 1, executing the commands from ``real_case.ff`` and printing output to the console. Afterwards, you remain in the interactive console (``forefire>`` prompt) and can inspect parameters (e.g., ``getParameter[propagationModel]``), run further steps manually (e.g., ``step[dt=600]``), or exit using ``quit[]``.
+
+3: Web Interface
+~~~~~~~~~~~~~~~~
+
+This method uses the built-in HTTP server to provide a web-based console and map visualization. It executes commands in the same way as the interactive console but through your browser.
+
+1.  **Navigate to the test directory** (if not already there):
+
+  .. code-block:: bash
+
+    cd tests/runff
+
+2.  **Start the ForeFire interpreter** (as shown in Method 2, ensuring you start it from *within* the `tests/runff` directory for simplicity with file paths in the next steps).
+
+3.  **Launch the HTTP server:**
+
+  At the ``forefire>`` prompt, type:
+
+  .. code-block:: none
+
+    forefire> listenHTTP[]
+
+4.  **Use the Web Interface:**
+
+  - Open your browser to ``http://localhost:8000/`` (or the specified port).
+  - In the command input box in the web UI, type ``include[input=real_case.ff]`` and press Enter or click Send. This executes the script file relative to where the interpreter was started (which we ensured was `tests/runff`).
+  - Click "Refresh Map" periodically to see the simulation progress visually. You can also type other commands directly into the web console.
+
+Choosing a Method
+-----------------
+
+- Use **Method 1 (Direct Execution)** for standard, non-interactive runs or scripting.
+- Use **Method 2 (Interactive Console)** when you want to experiment with commands step-by-step or inspect the state directly via text after running a script.
+- Use **Method 3 (Web UI)** for visual feedback and interactive demonstrations.
+
+Next Steps
+----------
+
+Now that you've seen the different ways to *execute* a ForeFire script, you can learn more about:
+
+- How to **write and structure** your own scripts in the :doc:`ForeFire Script File guide </user_guide/forefire_script>`.
+- The specific :doc:`Input Files </user_guide/basic_configuration>` required (Fuels, Landscape).
+- The detailed :doc:`Command </reference/commands>` and :doc:`Parameter </reference/parameters>` references.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -5,28 +5,30 @@ Welcome to the official documentation for ForeFire — the open-source wildfire
 
 **Key Links:**
 
-- `GitHub Repository <https://github.com/forefireAPI/firefront>`_
+- `GitHub Repository <https://github.com/forefireAPI/forefire>`_
 - `Online Demo Simulator <http://forefire.univ-corse.fr/sim/dev/>`_
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Getting Started
 
-   introduction
-   quickstart
-   installation
-   running_the_example
+   getting_started/introduction
+   getting_started/quickstart
+   getting_started/installation
+   getting_started/running_the_example
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: User Guide
 
    user_guide/basic_configuration
    user_guide/fuels_file
    user_guide/landscape_file
+   user_guide/forefire_script
+   user_guide/core_concepts
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Reference
 
    reference/commands
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,4 +3,4 @@ License

		ForeFire is licensed under the GNU General Public License v3.0 (GPLv3).

		You can find the full license text in the `LICENSE <https://github.com/forefireAPI/firefront/blob/master/LICENSE>`_ file in the root of the project repository.
		You can find the full license text in the `LICENSE <https://github.com/forefireAPI/forefire/blob/master/LICENSE>`_ file in the root of the project repository.