Skip to content

execution_modes.rst

Latest commit

 

History

History
158 lines (89 loc) · 6.24 KB

execution_modes.rst

File metadata and controls

158 lines (89 loc) · 6.24 KB

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 </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 forefire repository. Then navigate:

cd tests/runff
  1. 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:

forefire -i real_case.ff

If forefire is NOT in your PATH (run from the root of the repo):

../../bin/forefire -i real_case.ff
  1. 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):
cd tests/runff
  1. Start the ForeFire interpreter:

If forefire is in your PATH:

forefire

If forefire is NOT in your PATH (run from the root of the repo):

../../bin/forefire
  1. Run the script using the include command:

Once you see the forefire> prompt, type the command to execute the script file.

forefire> include[real_case.ff]
  1. 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):
cd tests/runff
  1. Start the ForeFire interpreter and launch the HTTP server:

Assuming forefire is in your PATH:

forefire

At the forefire> prompt, type:

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.

forefire -l
  1. 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: