diff --git a/.gitignore b/.gitignore index 2b79d65f..3a481649 100644 --- 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 index 7d0a5380..aa78e237 100644 --- 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 index 4b1b65d3..883fa44f 100644 --- 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 index 5fd4d24c..ecfd9e1d 100644 --- 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 index 5f1efcc5..41a09d94 100644 --- 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; } \ No newline at end of file diff --git a/docs/source/about/license.rst b/docs/source/about/license.rst index 19e3c06f..b24e62c6 100644 --- 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 `_ file in the root of the project repository. \ No newline at end of file +You can find the full license text in the `LICENSE `_ file in the root of the project repository. \ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/getting_started/installation.rst similarity index 94% rename from docs/source/installation.rst rename to docs/source/getting_started/installation.rst index 4c8440e3..1f15cdf7 100644 --- a/docs/source/installation.rst +++ b/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 new file mode 100644 index 00000000..e997f231 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/source/quickstart.rst b/docs/source/getting_started/quickstart.rst similarity index 87% rename from docs/source/quickstart.rst rename to docs/source/getting_started/quickstart.rst index c694661d..8c3a59ae 100644 --- a/docs/source/quickstart.rst +++ b/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 new file mode 100644 index 00000000..e303f9dc --- /dev/null +++ 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 ` or via :doc:`Docker `), 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 `. + +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 `. +- The specific :doc:`Input Files ` required (Fuels, Landscape). +- The detailed :doc:`Command ` and :doc:`Parameter ` references. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 67fbcc35..f4b68ad6 100644 --- 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 `_ +- `GitHub Repository `_ - `Online Demo Simulator `_ .. 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 diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst deleted file mode 100644 index c4987c9c..00000000 --- a/docs/source/introduction.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. _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. - -The engine's logic is compiled into a **reusable shared library** (``libforefireL.so``) that can be directly linked against by other C/C++ or Fortran programs. The most common way to use ForeFire is through the ``forefire`` **executable program**. - -This ``forefire`` program acts as a **command-line interpreter**. It reads and executes commands from: - -* Script files (typically `.ff` files) -* An interactive console session -* An HTTP server interface (activated by the ``listenHTTP[]`` command, powering the web UI) - -These commands instruct the underlying library engine to perform actions like loading data, setting parameters, defining ignitions, and advancing the simulation state over time. - -This structure allows ForeFire to be both a versatile standalone simulation tool and a computational engine integrable into larger modeling 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)**. - -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. \ No newline at end of file diff --git a/docs/source/reference/parameters.rst b/docs/source/reference/parameters.rst index 29e7f53b..4ce368d6 100644 --- a/docs/source/reference/parameters.rst +++ b/docs/source/reference/parameters.rst @@ -111,6 +111,8 @@ InitTime Domain & Discretization ~~~~~~~~~~~~~~~~~~~~~~~ +.. _param-perimeterResolution: + perimeterResolution """"""""""""""""""" * **Description:** Target maximum distance (in meters) between adjacent FireNodes discretizing the fire front. The simulation dynamically adds nodes to maintain this resolution. @@ -165,6 +167,8 @@ frontDepthScheme Physics & Models ~~~~~~~~~~~~~~~~ +.. _param-propagationModel: + 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`). diff --git a/docs/source/running_the_example.rst b/docs/source/running_the_example.rst deleted file mode 100644 index 05f14044..00000000 --- a/docs/source/running_the_example.rst +++ /dev/null @@ -1,178 +0,0 @@ -Running an Example -================== - -After successfully installing ForeFire (either :doc:`from source ` or via :doc:`Docker `), you can run the example simulation located in the ``tests/runff/`` directory. This helps verify your installation and introduces you to the basic workflow and command execution methods. - -Simulation files ----------------- - -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. 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``. - - -Understanding the Example Script (`real_case.ff`) -------------------------------------------------- - -Before running the example, let's briefly look at what the ``real_case.ff`` script instructs ForeFire to do. While the full script might be longer, it typically performs actions like these using specific ForeFire commands: - -1. **Include Parameters:** Often starts by including parameter settings from another file (like ``params.ff``) using the :ref:`include ` command. - - .. code-block:: none - - # Example snippet from a .ff file: - include[input=params.ff] - -2. **Load Landscape Data:** Loads the terrain, fuel, and potentially weather data from the NetCDF file (``data.nc``) using the :ref:`loadData ` command, associating it with a start date/time. - - .. code-block:: none - - # Example snippet: - loadData[data.nc;2020-02-10T17:35:54Z] # Date/time may vary - -3. **Define Ignition:** Starts the fire at a specific location and time using the :ref:`startFire ` command. - - .. code-block:: none - - # Example snippet (coordinates may vary): - startFire[lonlat=(8.916,41.816);t=0] - -4. **Set Dynamic Conditions (Optional):** May use :ref:`trigger ` commands to introduce changes during the simulation, like setting wind conditions at specific times. - - .. code-block:: none - - # Example snippet (values/time may vary): - trigger[fuelType=wind;vel=(5.0, 2.0, 0.0);t=1800] # Set wind at 1800s - -5. **Run the Simulation:** Advances the simulation time using :ref:`step ` (run for a duration) or :ref:`goTo ` (run until a specific time). - - .. code-block:: none - - # Example snippet (time may vary): - goTo[t=7200] # Run simulation until t = 7200 seconds (2 hours) - -6. **Generate Output:** Saves the final state (or intermediate states) using commands like :ref:`print ` (saves front geometry) or :ref:`save ` (saves arrival time map). - - .. code-block:: none - - # Example snippet (filename may vary): - setParameter[dumpMode=geojson] # Set output format - print[output_front.geojson] - save[] # Save arrival time map - -7. **Terminate:** The script execution finishes, or it might contain an explicit :ref:`quit ` command. - -Knowing these basic steps helps understand what happens when you execute the ``real_case.ff`` script using the methods below. For full details on each command, see the :doc:`Command Reference `. - -Executing the Example Script ----------------------------- - -You can run the ``real_case.ff`` simulation (which contains commands like those shown above) using the ``forefire`` executable in several ways: - -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 or when you don't need interaction. - -1. **Navigate to the test directory:** - - .. 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 (running from ``tests/runff``): - - .. 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 (like ``to_reload.ff`` or others 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 type all the commands manually. You can then use the ``include`` command to execute the script file, and potentially interact further before or after. - -1. **Navigate to the test directory:** - - .. 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 (running from ``tests/runff``): - - .. 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[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. It's great for demonstrations or visual exploration. - -1. **Navigate to the test directory:** - - .. code-block:: bash - - cd tests/runff - -2. **Start the ForeFire interpreter** (as shown in Method 2). - -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[real_case.ff]`` and press Enter or click Send. This executes the script file. - * 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 how to run an existing example script and understand the basic commands it contains, you can learn more about: - -* The :doc:`basic_configuration` files required for setting up your own simulations. -* The detailed :doc:`reference/commands` and :doc:`reference/parameters`. -* Exploring the core concepts in the **User Guide** (coming soon!). \ No newline at end of file diff --git a/docs/source/user_guide/core_concepts.rst b/docs/source/user_guide/core_concepts.rst new file mode 100644 index 00000000..4592d368 --- /dev/null +++ b/docs/source/user_guide/core_concepts.rst @@ -0,0 +1,116 @@ +.. _userguide-core-concepts: + +Core Concepts +============= + +Understanding the fundamental concepts behind ForeFire can help you use the simulator more effectively and interpret its behavior and outputs. This page provides a high-level overview of the key components and the simulation process. + +Simulation Engine & Interpreter +------------------------------- + +As discussed in the :doc:`/getting_started/introduction`, ForeFire consists of: + +1. **Simulation Engine** (Library ``libforefireL``): The core C++ code containing the physics, data structures, and algorithms for simulating fire spread. +2. **Interpreter** (Executable ``forefire``): The program you typically interact with. It reads commands (from scripts, console, or web UI) and instructs the engine library what to do. + +This separation allows ForeFire to be used both as a standalone tool (via the interpreter) and as a component linked into other software (like atmospheric models). + +Key Simulation Components +------------------------- + +The simulation engine relies on several key C++ components (classes) to manage the fire spread process: + +* **`Simulator` & `TimeTable` (Event-Driven Core)** + + * ForeFire uses an **event-driven** approach. Instead of fixed time steps for the entire simulation, it maintains a `TimeTable` (a prioritized queue) of future events. + * Each event typically corresponds to a `FireNode` needing an update at a specific future time. + * The `Simulator` processes events from the `TimeTable` in chronological order. It retrieves the next event, tells the associated object (like a `FireNode`) to update its state and calculate its next move, and then the object schedules its *next* update event back into the `TimeTable`. + * **This event-driven approach means the simulation doesn't use fixed global time steps; different parts of the front can advance according to their own calculated timings.** + +* **`FireDomain` (The Simulation World)** + + * Represents the overall simulation area and context. + * Manages the simulation's current time. + * Defines the spatial boundaries (often derived from the :doc:`/user_guide/landscape_file`). + * Contains the `DataBroker` to access environmental data. + * Owns the main `FireFront` (s). + * Manages the `TimeTable` of simulation events. + * May handle discretization of the domain into cells (e.g., for flux calculations or burning map outputs). + +* **`FireFront` & `FireNode` (Representing the Fire)** + + * ForeFire uses a **Lagrangian** approach to track the fire's edge. + * A `FireFront` represents a continuous segment of the fire perimeter. It is essentially a linked list of `FireNode` objects. + * A `FireNode` is a point (marker) on the fire front. It has properties like: + + * Location (x, y, z coordinates) + * Velocity (calculated based on local conditions) + * Normal vector (direction perpendicular to the front) + * Curvature and potentially front depth + * When a `FireNode`'s event occurs, it calculates its propagation speed based on local environmental data and the chosen :ref:`propagation model `, determines its next location, and schedules its next update. + * The `FireDomain` monitors the `FireNode` s to handle topological changes: + + * **Adding nodes:** When nodes spread too far apart (controlled by :ref:`perimeterResolution `), new nodes are inserted. + * **Merging:** When different parts of a `FireFront` touch, they merge. + * **Splitting:** Not explicitly mentioned in summary, but might occur if front self-intersects or hits complex boundaries. + * **Inner Fronts:** `FireFront` s can be nested to represent unburned islands within the main fire perimeter. + +* **`DataBroker` & `DataLayer` (Accessing Environmental Data)** + + * The `DataBroker` is the central hub for all environmental data needed by the simulation (terrain, fuel, weather). + * It manages a collection of `DataLayer` objects. Each `DataLayer` provides access to a specific type of data (e.g., elevation, fuel index, wind speed). + * **Data layers can also manage which specific physical model (e.g., which heat flux calculation) applies at different locations, often based on index maps read from the input files.** + * Different `DataLayer` subclasses handle various data sources and formats: + + * Loading grids from the NetCDF :doc:`/user_guide/landscape_file`. + * Handling constant values across the domain (e.g., constant wind). + * Calculating gradients (like slope/aspect from elevation). + * Accessing the computed arrival time map (Burning Map). + * Interpolating data in space and potentially time (e.g., for time-varying wind fields). + * When a `FireNode` needs environmental data to calculate its speed, it asks the `DataBroker`, which efficiently retrieves the necessary values from the relevant `DataLayer` (s) at the node's location. + +* **`PropagationModel` & `FluxModel` (The Physics)** + + * ForeFire uses a **Strategy pattern** for physical calculations, allowing different models to be plugged in. + * `PropagationModel` subclasses (e.g., `Rothermel`, `Balbi`, `Iso`) implement specific algorithms to calculate the Rate of Spread (ROS) based on properties fetched via the `DataBroker`. The active model is chosen using the :ref:`propagationModel ` parameter. + * `FluxModel` subclasses (e.g., `HeatFluxBasicModel`) calculate fluxes (like heat, water vapor) from the burning area, often needed for coupled simulations or specific research outputs. + +* **`SimulationParameters` (Configuration)** + + * A central place (likely a Singleton class internally) holding the global configuration values set by the user via :ref:`setParameter ` or :ref:`setParameters ` commands. This includes things like model choices, resolution parameters, output settings, etc. + +Simulation Workflow Summary +--------------------------- + +1. **Initialization:** + + * The `forefire` interpreter starts. + * Commands from a script file (or interactive input) are processed. + * :doc:`Parameters ` are set. + * The :ref:`FireDomain ` is created. + * :ref:`loadData ` populates the `DataBroker` with `DataLayer`s from the :doc:`/user_guide/landscape_file`. The :doc:`/user_guide/fuels_file` information is associated. + * The initial fire state is defined using :ref:`startFire ` or custom `FireFront`/`FireNode` commands, scheduling the first update events for the initial nodes into the `TimeTable`. + +2. **Simulation Loop (driven by `step` or `goTo`):** + + * The `Simulator` gets the chronologically next event (usually a `FireNode` update) from the `TimeTable`. + * The `Simulator` advances the global simulation time to the event time. + * The `Simulator` calls the update method on the `FireNode`. + * The `FireNode` calculates its new position based on its previously calculated velocity. + * The `FireDomain` checks for topological changes (node spacing, potential merges). + * The `Simulator` calls the time-advance method on the `FireNode`. + * The `FireNode`: + + * Determines its local normal vector and curvature. + * Requests necessary environmental properties (fuel type, slope, wind, etc.) from the `DataBroker` for its current location. + * Calls the active `PropagationModel`'s `getSpeed()` method with these properties. + * Calculates its new velocity and intended next location. + * Determines its next update time based on speed and resolution parameters. + * Schedules its next update event back into the `TimeTable`. + * This loop continues until the target time specified by :ref:`goTo ` is reached, the duration specified by :ref:`step ` elapses, or the `TimeTable` becomes empty. + +3. **Output:** + + * Commands like :ref:`print `, :ref:`save `, or :ref:`plot ` are executed (either when encountered in the script or scheduled via :ref:`@t=... `) to query the state of the `FireFront` (s) or `DataLayer` (s) (like the burning map) and write them to files. + +Understanding these core concepts provides context for the various commands, parameters, and input files required to run a ForeFire simulation. \ No newline at end of file diff --git a/docs/source/user_guide/forefire_script.rst b/docs/source/user_guide/forefire_script.rst new file mode 100644 index 00000000..cf7cc20b --- /dev/null +++ b/docs/source/user_guide/forefire_script.rst @@ -0,0 +1,152 @@ +.. _userguide-forefire-script: + +ForeFire Script File (.ff) +========================== + +The ForeFire Script File, conventionally given a ``.ff`` extension, is a plain text file that contains a sequence of commands to control and execute a ForeFire simulation. It acts as the primary way to define a simulation scenario for non-interactive runs. + +Purpose +------- + +The script file allows you to automate the entire simulation process, including: + +- Setting simulation parameters. +- Loading necessary input data (landscape, fuels). +- Defining the initial state of the fire (ignition points or lines). +- Specifying dynamic conditions (like changing winds). +- Controlling the simulation's time progression. +- Generating output files at desired intervals or at the end. + +Basic Syntax +------------ + +- **One Command Per Line:** Each line in the script file generally represents a single ForeFire command. +- **Command Structure:** Commands follow the format ``CommandName[argument1=value1;argument2=value2;...]``. + + - The command name is case-sensitive (e.g., ``setParameter`` is different from ``setparameter``). + - Arguments are enclosed in square brackets ``[...]``. + - Arguments are typically key-value pairs separated by an equals sign ``=``. + - Multiple arguments within the brackets are separated by semicolons ``;``. + - Some commands might take positional arguments (like :ref:`loadData `) or have optional arguments (prefixed with `opt:` in the :doc:`Command Reference `). +- **Comments:** Lines beginning with a hash symbol ``#`` are treated as comments and are ignored by the interpreter. +- **Whitespace:** Leading and trailing whitespace on a line is generally ignored, except for indentation (see below). + +Indentation for Hierarchy (FireFront / FireNode) +------------------------------------------------ + +Certain commands, specifically :ref:`FireFront ` and :ref:`FireNode `, use **leading spaces (indentation)** to define their relationship within the simulation structure when creating custom initial fire perimeters: + +- A ``FireFront`` defined within a :ref:`FireDomain ` is typically indented (e.g., 4 spaces). +- A ``FireNode`` belonging to that ``FireFront`` is indented further relative to the `FireFront` (e.g., another 4 spaces, totaling 8). +- An inner ``FireFront`` (representing an unburned island within another `FireFront`) would be indented relative to its parent `FireFront`. + +.. code-block:: none + :caption: Example Indentation for Custom Front + + # FireDomain defined earlier or implicitly... + + # Indented FireFront (e.g., 4 spaces) + FireFront[t=0] + # Further indented FireNode (e.g., 8 spaces total) + FireNode[loc=(100,100,0);t=0] + FireNode[loc=(200,100,0);t=0] + FireNode[loc=(150,150,0);t=0] + # ... potentially more nodes defining the outer perimeter + + +.. important:: + Consistent use of spaces (not tabs) is recommended for indentation. The exact number of spaces required might need experimentation or checking examples, but the relative indentation defines the hierarchy. Using :ref:`startFire ` is often simpler for basic point ignitions. + +Typical Script Workflow +----------------------- + +While the exact commands depend on the simulation, a common workflow within a ``.ff`` script looks like this: + +1. **Setup Parameters:** Define simulation controls, model choices, resolution, etc. + + .. code-block:: none + + # Include parameters from a separate file (optional) + # include[input=params.ff] + + # Set specific parameters directly + setParameters[propagationModel=Rothermel;perimeterResolution=30;dumpMode=geojson] + +2. **Load Input Data:** Load the geospatial context. + + .. code-block:: none + + # Load landscape and associate with a time + loadData[my_landscape.nc;2024-01-01T12:00:00Z] + # Note: The fuels file (e.g., fuels.csv) is usually implicitly loaded + # based on the 'fuelsTableFile' parameter or defaults, + # but its path might need to be relative to 'caseDirectory'. + +3. **Define Simulation Domain (if needed):** While ``loadData`` can implicitly define the domain extent based on the NetCDF file, you can also explicitly define it using ``FireDomain``. + + .. code-block:: none + + # Optional explicit domain definition (using projected coords) + # FireDomain[sw=(0,0,0);ne=(50000,50000,0);t=0] + +4. **Define Initial Fire State:** Specify where and when the fire starts. + + .. code-block:: none + + # Simple point ignition + startFire[lonlat=(9.1, 42.2); t=0] # Using geographic coordinates + + # --- OR --- + + # Custom initial front (using projected coords and indentation) + # Ensure FireDomain covers these coordinates + # FireFront[t=0] + # FireNode[loc=(2500,3000,150);t=0] + # FireNode[loc=(2600,3000,150);t=0] + # FireNode[loc=(2550,3100,150);t=0] + + +5. **Set Dynamic Conditions (Optional):** Introduce time-varying inputs, like wind changes. + + .. code-block:: none + + # Set initial wind (applied from t=0 if not in landscape file) + trigger[fuelType=wind;vel=(3.0, -1.0, 0.0);t=0] + + # Change wind later in the simulation + trigger[fuelType=wind;vel=(0.0, 5.0, 0.0);t=3600] # New wind at 1 hour + +6. **Advance Simulation Time:** Run the simulation forward. + + .. code-block:: none + + # Run until a specific absolute simulation time + goTo[t=7200] # Run until t = 2 hours + + # --- OR --- + + # Run in discrete steps (useful for periodic output) + # step[dt=600] # Run for 10 minutes + # print[front_t600.geojson]@t=600 # Output using scheduler + # step[dt=600] # Run for another 10 minutes + # print[front_t1200.geojson]@t=1200 + # ... + +7. **Generate Outputs:** Save the simulation results. + + .. code-block:: none + + # Save final front geometry (format set by dumpMode parameter) + print[final_front.geojson] + + # Save final arrival time map to NetCDF + save[] # Uses default filename pattern ForeFire..nc + + # Plot a specific variable to an image + # plot[parameter=arrival_time_of_front;filename=arrival_map.png] + + +Complete Example (`real_case.ff`) +--------------------------------- + +The file ``tests/runff/real_case.ff`` serves as a complete, working example demonstrating many of these concepts in practice. After understanding the basics outlined here and consulting the :doc:`Command ` and :doc:`Parameter ` references, studying ``real_case.ff`` is highly recommended. \ No newline at end of file