.. _execution_modes: Execution Modes ================== 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 --------------------- 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 `forefire` 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 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 ~~~~~~~~~~~~~~~~~~~~~~ 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[real_case.ff] 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, 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): .. code-block:: bash cd tests/runff 2. **Start the ForeFire interpreter and launch the HTTP server:** Assuming ``forefire`` is in your PATH: .. code-block:: bash forefire At the ``forefire>`` prompt, type: .. code-block:: none forefire> listenHTTP[] You should see the output: `>> ForeFire HTTP command server listening at http://localhost:8000`. **Alternative Shortcut** using ``-l`` (listen) flag: 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:: 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[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.