diff --git a/.github/workflows/increment-version.yml b/.github/workflows/increment-version.yml index 13295451..88ae1051 100644 --- a/.github/workflows/increment-version.yml +++ b/.github/workflows/increment-version.yml @@ -2,7 +2,8 @@ name: Increment Version on Dev on: push: - # branches: [ dev ] we can add back later if needed + # we can add back to branch dev if needed + branches: [ dev2 ] workflow_dispatch: jobs: diff --git a/docs/source/getting_started/running_the_example.rst b/docs/source/getting_started/execution_modes.rst similarity index 73% rename from docs/source/getting_started/running_the_example.rst rename to docs/source/getting_started/execution_modes.rst index e53c4577..899e858a 100644 --- a/docs/source/getting_started/running_the_example.rst +++ b/docs/source/getting_started/execution_modes.rst @@ -1,9 +1,17 @@ -.. _running-the-example: +.. _execution_modes: -Running an Example +Execution Modes ================== -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. +In the :doc:`quickstart` guide, you launched the example simulation using the interactive Web UI. That is just one of several ways to operate the ``forefire`` interpreter. + +This page details all three primary execution modes, allowing you to choose the best method for your specific task: + +- **Direct Execution (Batch Mode):** Best for standard, non-interactive runs or for use in automated scripts. +- **Interactive Console:** Ideal for experimenting with commands step-by-step or inspecting the simulation state. +- **Web Interface:** Excellent for visual feedback and interactive demonstrations. + +Below, we demonstrate each method using the same ``real_case.ff`` script. Simulation Files Used --------------------- @@ -51,7 +59,10 @@ This is the simplest way to run a simulation non-interactively by feeding the en ../../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``). +3. **Observe:** ForeFire will create 2 files: + + - ``to_reload.ff``: a Forefire ascii state file ready to be reincluded or modified to run + - ``ForeFire.0.nc``: a burning map matrix in netcdf 2: Interactive Console ~~~~~~~~~~~~~~~~~~~~~~ @@ -84,15 +95,15 @@ This method starts the ForeFire interpreter first, allowing you to execute the s .. code-block:: none - forefire> include[input=real_case.ff] + 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[]``. +4. **Observe:** The simulation will run similarly to Method 1, executing the commands from ``real_case.ff``. 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. +This method, which you may have already used in the :doc:`quickstart` guide, 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): @@ -120,14 +131,14 @@ This method uses the built-in HTTP server to provide a web-based console and map Alternatively, to launch the HTTP server directly without entering the interactive console first, you can use the `-l` command-line option. This is convenient if you primarily want to use the web interface. - .. code-block:: none + .. code-block:: bash forefire -l 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`). + - 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 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 diff --git a/docs/source/getting_started/introduction.rst b/docs/source/getting_started/introduction.rst index e997f231..b96bd310 100644 --- a/docs/source/getting_started/introduction.rst +++ b/docs/source/getting_started/introduction.rst @@ -51,7 +51,7 @@ ForeFire is suitable for a range of applications, including: 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**. +ForeFire is primarily developed and tested on **Unix-like systems (Linux and macOS)**. It can run on Windows via **WSL** (Windows Subsystem for Linux) or **Docker**. About This Documentation ------------------------ diff --git a/docs/source/getting_started/quickstart.rst b/docs/source/getting_started/quickstart.rst index 85e28976..ac5d2f31 100644 --- a/docs/source/getting_started/quickstart.rst +++ b/docs/source/getting_started/quickstart.rst @@ -76,7 +76,7 @@ Steps :align: center :width: 90% - **This confirms your Docker setup is working!** For other ways to run ForeFire scripts (like directly from the command line), see the :doc:`running_the_example` page. + **This confirms your Docker setup is working!** 9. **Stop the Container:** @@ -85,3 +85,10 @@ Steps - In the ForeFire console (either web or terminal inside the container), type `quit`. - In the container's bash shell (terminal), type `exit`. - The `docker run` command used `--rm`, so the container will be automatically removed upon exit. + +.. rubric:: Next Steps + +Congratulations! You've successfully run your first ForeFire simulation and have a working environment. Here are some recommended next steps to deepen your understanding: + +- **Explore Execution Modes:** Learn about the command-line (batch) and interactive console alternatives to the Web UI by reading the :doc:`execution_modes` guide. +- **Understand the Script:** To see what was inside the ``real_case.ff`` script you just ran, dive into the :doc:`/user_guide/forefire_script` guide. diff --git a/docs/source/index.rst b/docs/source/index.rst index 9170a1be..5419b666 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,7 +15,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire getting_started/introduction getting_started/quickstart getting_started/installation - getting_started/running_the_example + getting_started/execution_modes .. toctree:: :maxdepth: 1 diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt index 063a9e6b..a0d135b1 100644 --- a/docs/source/requirements.txt +++ b/docs/source/requirements.txt @@ -1,25 +1,11 @@ -alabaster==1.0.0 -babel==2.17.0 -breathe==4.36.0 -certifi==2025.1.31 -charset-normalizer==3.4.1 -docutils==0.21.2 -idna==3.10 -imagesize==1.4.1 -Jinja2==3.1.6 -MarkupSafe==3.0.2 -packaging==24.2 -Pygments==2.19.1 -requests==2.32.4 -snowballstemmer==2.2.0 -Sphinx==8.1.3 -sphinx-rtd-theme==3.0.2 -sphinxcontrib-applehelp==2.0.0 -sphinxcontrib-devhelp==2.0.0 -sphinxcontrib-htmlhelp==2.1.0 -sphinxcontrib-jquery==4.1 -sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-qthelp==2.0.0 -sphinxcontrib-serializinghtml==2.0.0 -tomli==2.2.1 -urllib3==2.3.2 +# Core documentation generator +sphinx>=8.1,<9.0 + +# Theme for Read the Docs +sphinx-rtd-theme>=3.0,<4.0 + +# Doxygen/C++ integration +breathe>=4.36,<5.0 + +# A dependency for the RTD theme +sphinxcontrib-jquery \ No newline at end of file diff --git a/docs/source/user_guide/forefire_script.rst b/docs/source/user_guide/forefire_script.rst index cf7cc20b..72232203 100644 --- a/docs/source/user_guide/forefire_script.rst +++ b/docs/source/user_guide/forefire_script.rst @@ -67,7 +67,7 @@ While the exact commands depend on the simulation, a common workflow within a `` .. code-block:: none # Include parameters from a separate file (optional) - # include[input=params.ff] + # include[params.ff] # Set specific parameters directly setParameters[propagationModel=Rothermel;perimeterResolution=30;dumpMode=geojson] diff --git a/src/include/Version.h b/src/include/Version.h index 3a45bb67..812f01e9 100644 --- a/src/include/Version.h +++ b/src/include/Version.h @@ -1,3 +1,3 @@ #pragma once -const char* ff_version = "v2.1.114"; +const char* ff_version = "v2.1.122";