.. _reference-parameters: Parameter Reference =================== This page lists commonly used configurable parameters that control ForeFire's behavior, focusing on those documented in previous versions and still present in ForeFire V2. Parameters are case-sensitive. How to Set Parameters --------------------- You can set parameters using the :ref:`setParameter ` or :ref:`setParameters ` commands in the ForeFire interpreter or a script file (`.ff`). * **Single Parameter:** .. code-block:: none setParameter[parameterName=value] setParameter[perimeterResolution=30] setParameter[propagationModel=Rothermel] * **Multiple Parameters:** .. code-block:: none setParameters[param1=value1;param2=value2;...] setParameters[perimeterResolution=30;spatialIncrement=1.5;dumpMode=geojson] List of Parameters ------------------ Parameters are grouped below by category for easier navigation. File and Directory Paths ~~~~~~~~~~~~~~~~~~~~~~~~ caseDirectory """"""""""""" * **Description:** Base directory for the simulation case. Affects relative path resolution for other files. * **Default:** Current working directory (`.` determined by `getenv("PWD")`) ForeFireDataDirectory """"""""""""""""""""" * **Description:** Directory containing auxiliary ForeFire data, often relative to `caseDirectory`. * **Default:** `ForeFire` experiment """""""""" * **Description:** Name identifier for the simulation experiment. May affect output filenames. * **Default:** `ForeFire` NetCDFfile """""""""" * **Description:** Specifies the *primary* NetCDF landscape file to be loaded via the :ref:`loadData ` command if not provided directly in the command itself. If empty, `loadData` requires the filename argument. * **Default:** `""` (Empty string) fuelsTableFile """""""""""""" * **Description:** Default filename for the fuel parameter table. While the default is `.ff` (legacy), ForeFire V2 typically expects a `.csv` file in practice. This file defines fuel properties (e.g., for Rothermel model). * **Default:** `fuels.ff` *(Note: Use a `.csv` file in practice)* paramsFile """""""""" * **Description:** Default filename for a file containing simulation parameters, which can be loaded via :ref:`include `. * **Default:** `Params.ff` InitFile """""""" * **Description:** Default filename for a script file containing initial fire front state (nodes, locations) used for non-parallel starts (e.g., loaded via `include`). * **Default:** `Init.ff` InitFiles """"""""" * **Description:** Pattern for filenames containing fire front state for parallel restarts. Typically includes processor rank and time information. Example: `output.0.1200` (processor 0 at time 1200). * **Default:** `output` BMapsFiles """""""""" * **Description:** Pattern for filenames containing pre-computed burning map data for restarts or one-way coupling. * **Default:** `1234567890` *(Placeholder suggests it needs to be explicitly set)* fireOutputDirectory """"""""""""""""""" * **Description:** Directory where fire-related output files (e.g., front state from `print`, arrival maps from `save`) are written. * **Default:** `.` (Current directory) atmoOutputDirectories """"""""""""""""""""" * **Description:** Directory (or comma-separated list of directories for nested models) where atmospheric coupling-related outputs are written. * **Default:** `.` (Current directory) outputFiles """"""""""" * **Description:** Base pattern for output filenames generated by ForeFire (e.g., during `print` or `save` if no filename is specified). Processor rank, variable name, and time are often appended automatically. * **Default:** `output` Simulation Control & Time ~~~~~~~~~~~~~~~~~~~~~~~~~ parallelInit """""""""""" * **Description:** Boolean (0 or 1) enabling parallel initialization (restart from a previous parallel simulation state). * **Default:** `0` (Disabled) InitTime """""""" * **Description:** Specifies the simulation time (in seconds) to use for parallel restart initialization, matching the time encoded in `InitFiles`. A very large default suggests it needs to be set explicitly for restarts. * **Default:** `99999999999999` 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. * **Default:** `40` spatialIncrement """""""""""""""" * **Description:** Distance (in meters) each FireNode is advanced computationally during its update step. Related to `perimeterResolution` via `spatialCFLmax`. * **Default:** `2` spatialCFLmax """"""""""""" * **Description:** Maximum allowed ratio of `spatialIncrement / perimeterResolution`. Controls numerical stability and computational step size relative to front resolution. * **Default:** `0.3` normalScheme """""""""""" * **Description:** Algorithm used to calculate the normal vector at each FireNode (determines local spread direction). Available schemes likely include `medians`, `weightedMedians`, `splines`. * **Default:** `medians` smoothing """"""""" * **Description:** Parameter controlling the degree of smoothing applied during the calculation of the normal vector or front curvature. Affects front shape stability. * **Default:** `1` relax """"" * **Description:** Relaxation factor used in iterative calculations, potentially for normal vector or front depth computation, to improve convergence or stability. * **Default:** `0.5` curvatureComputation """""""""""""""""""" * **Description:** Boolean (0 or 1) enabling/disabling the computation of local front curvature. Required by some advanced propagation models. * **Default:** `1` (Enabled) curvatureScheme """"""""""""""" * **Description:** Algorithm used to calculate front curvature if `curvatureComputation` is enabled. Available schemes likely include `angles`, `circumradius`, `splines`. * **Default:** `circumradius` frontDepthComputation """"""""""""""""""""" * **Description:** Boolean (0 or 1) enabling/disabling the computation of fire front depth. Required by some propagation or flux models. * **Default:** `0` (Disabled) frontDepthScheme """""""""""""""" * **Description:** Algorithm used to calculate front depth if `frontDepthComputation` is enabled. * **Default:** `normalDir` Physics & Models ~~~~~~~~~~~~~~~~ .. _param-propagationModel: propagationModel """""""""""""""" * **Description:** Name of the Rate of Spread (ROS) model to use. ForeFire is a general solver, and this choice dictates how spread speed is calculated and what fuel parameterization is required. * **Default:** `Iso` * **Available Models:** The string provided must match the name of a registered C++ model class. Common supported models include: * `Iso`: A simple isotropic model. Does not use a fuels file. Speed is set via the `Iso.speed` parameter. * `Rothermel`: The Rothermel 1972 surface fire spread model. Requires a detailed fuel parameterization file. * `BalbiNov2011`, `Balbi2015`: Physical models from Balbi et al. Also use the fuel parameterization file. * **More Info:** See the :doc:`/user_guide/fuels_and_models` guide for detailed explanations of each model and their data requirements. burningTresholdFlux """"""""""""""""""" * **Description:** Threshold flux value (likely W/m²) used to determine if a location is considered actively burning, potentially used for front depth or flux calculations. * **Default:** `10` minimalPropagativeFrontDepth """""""""""""""""""""""""""" * **Description:** Minimum front depth (in meters) required for a segment of the fire front to be considered active and propagating. Below this, propagation may cease. * **Default:** `10.` maxFrontDepth """"""""""""" * **Description:** Maximum effective front depth (in meters). If computed depth exceeds this value, its effect on propagation/flux models may be capped. * **Default:** `200.` initialFrontDepth """"""""""""""""" * **Description:** Front depth (in meters) assigned to the fire front upon initialization (e.g., via `startFire` or `FireFront`/`FireNode`). * **Default:** `20` initialBurningDuration """""""""""""""""""""" * **Description:** Duration (in seconds) for which the area inside the *initial* fire front is considered burning, relevant for flux calculations immediately after ignition. (Formerly `initialBurningTime` in V1). * **Default:** `30` Output, Logging & Debugging ~~~~~~~~~~~~~~~~~~~~~~~~~~~ outputsUpdate """"""""""""" * **Description:** Frequency (in seconds) for automatically saving simulation outputs (e.g., front state via `print` using `outputFiles` pattern). Set to 0 to disable periodic automatic saving. * **Default:** `0` (Disabled) bmapOutputUpdate """""""""""""""" * **Description:** Frequency (in seconds) for automatically saving the burning map (arrival times). Set to 0 to disable. *Note: Can be computationally expensive.* * **Default:** `0` (Disabled) surfaceOutputs """""""""""""" * **Description:** Boolean (0 or 1) enabling/disabling the output of surface properties, typically related to fluxes calculated for atmospheric coupling. * **Default:** `0` (Disabled) debugFronts """"""""""" * **Description:** Boolean (0 or 1) enabling/disabling saving of detailed front state information frequently (e.g., every atmospheric step in coupled mode), mainly for debugging. Files might be overwritten. * **Default:** `0` (Disabled) watchedProc """"""""""" * **Description:** Controls MPI process rank for debug outputs: * `-2`: No debug output from any process. * `-1`: Debug output from all processes. * `n` (>= 0): Debug output only from the process with MPI rank `n`. * **Default:** `-2` CommandOutputs """""""""""""" * **Description:** Boolean (0 or 1) enabling/disabling verbose debug messages related to command processing. * **Default:** `0` (Disabled) FireDomainOutputs """"""""""""""""" * **Description:** Boolean (0 or 1) enabling/disabling verbose debug messages related to the FireDomain (events, parallel operations). * **Default:** `0` (Disabled) FireFrontOutputs """""""""""""""" * **Description:** Boolean (0 or 1) enabling/disabling verbose debug messages related to FireFront operations (topology changes, merging, splitting). * **Default:** `1` (Enabled) FireNodeOutputs """"""""""""""" * **Description:** Boolean (0 or 1) enabling/disabling verbose debug messages related to FireNode operations (movement, speed/normal calculation). * **Default:** `1` (Enabled) FDCellsOutputs """""""""""""" * **Description:** Boolean (0 or 1) enabling/disabling verbose debug messages related to FDCells (flux calculations within grid cells). *(Note: FDCell might be legacy or internal naming)*. * **Default:** `1` (Enabled) HaloOutputs """"""""""" * **Description:** Boolean (0 or 1) enabling/disabling verbose debug messages related to halo regions used in parallel communication. * **Default:** `1` (Enabled) Coupling & Grid Parameters (Often used in Coupled Mode) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ atmoNX """""" * **Description:** Number of grid cells in the X (longitude/East-West) direction for the atmospheric model grid or the grid used for flux aggregation. Often imposed by the coupled model. * **Default:** `100` atmoNY """""" * **Description:** Number of grid cells in the Y (latitude/North-South) direction for the atmospheric model grid or flux aggregation grid. Often imposed by the coupled model. * **Default:** `100` atmoNZ """""" * **Description:** Number of grid cells in the Z (vertical) direction for the atmospheric model grid. Often imposed by the coupled model. * **Default:** `20` refLongitude """""""""""" * **Description:** Reference longitude for the simulation domain origin, often imposed by a coupled atmospheric model. * **Default:** `0` refLatitude """"""""""" * **Description:** Reference latitude for the simulation domain origin, often imposed by a coupled atmospheric model. * **Default:** `0` year, month, day """""""""""""""" * **Description:** Reference date components for the simulation start, often imposed by a coupled atmospheric model. Combines with `ISOdate`. * **Default:** `year=2012`, `month=1`, `day=1`