FFT Online: User Documentation

 

Running FCCS & Consume From Command Line

You can run large sets of fuelbeds through the FCCS & Consume calculators by calling their executables from a command prompt.

Prerequisites: Java and Python installed with PATH environment variable updated on your computer.

Start by downloading and unzipping the FccsConsumeCommandLine.zip file (unzipping to the C:\ drive in this example).

Contents of extracted FccsConsumeCommandLine.zip file

The command line instructions for each tool (FCCS_Command_line_instructions.docx and Consume5_CommandLine_instructions.docx) included in this package will be the most up-to-date and will supersede those given here where different. These instructions assume that Java and Python are installed with environment variables configured for command line use. Instructions below are for Windows/DOS users. Instructions for Linux/other users are given in the zip file's Word documents.

Running FCCS in DOS

  1. Set up your FCCS environment
    1. Unzip the fccs.zip file contained in the zip file.
    2. Add fuelbed .xml files to the fccs folder that contains the fuelbed.jar file (in this example, C:\FccsConsumeCommandLine\fccs\fccs). Copy your custom fuelbeds into their own folder ("fuelbeds_custom" in this example) and/or download and unzip FCCS fuelbed packages:
      1. FCCS Reference fuelbeds (base package of original 946 FCCS fuelbeds)
        Download | File documentation
      2. FCCS Disturbance fuelbeds (~15K files)
        Download | File documentation
      3. Region 6 pathway fuelbeds (487 files)
        Download | File documentation
    3. If you plan to specify custom fuel moistures, create a new folder ("ev_files" in this example) and copy the sample fuel moisture file (sample_fccs_moisture.csv) from the input_files folder into it to use as a template. (Skip this step to accept the benchmark D2L2 moisture profile.)

      FCCS fuel moisture inputs file data dictionary
      This optional file contains a header followed by a single row of values that will apply to all fuelbeds in the given run.
      Column name Definition Benchmark values
      oneHourFM Fuel moisture % of 1-hr fuels (e.g., < 0.25” in diameter) 6
      tenHourFM Fuel moisture % of 1-hr fuels (e.g., 0.25-1” in diameter) 7
      hundredHourFM Fuel moisture % of 1-hr fuels (e.g., 1-3” in diameter) 8
      liveNonWoodyFM Fuel moisture % of live forbs and graminoids 60
      liveShrubFM Fuel moisture % of live shrubs 90
      crownFM Fuel moisture % of live canopy 60

      The sample file is populated with the FCCS default/benchmark fuel moisture percents (D2L2). Here is the list of D#L# moisture profiles for reference.
      FM Code FM Desc 1,10,100,herb,shrub,crown
      D1L1 Very low dead, fully cured herb 3,4,5,30,60,60
      D1L2 Very low dead, 2/3 cured herb 3,4,5,60,90,90
      D1L3 Very low dead, 1/3 cured herb 3,4,5,90,120,120
      D1L4 Very low dead, fully green herb 3,4,5,120,150,150
      D2L1 Low dead, fully cured herb 6,7,8,30,60,60
      D2L2 Low dead, 2/3 cured herb 6,7,8,60,90,90
      D2L3 Low dead, 1/3 cured herb 6,7,8,90,120,60
      D2L4 Low dead, fully green herb 6,7,8,120,150,90
      D3L1 Moderate dead, fully cured herb 9,10,11,30,60,90
      D3L2 Moderate dead, 2/3 cured herb 9,10,11,60,90,90
      D3L3 Moderate dead, 1/3 cured herb 9,10,11,90,120,120
      D3L4 Moderate dead, fully green herb 9,10,11,120,150,120
      D4L1 High dead, fully cured herb 12,13,14,30,60,120
      D4L2 High dead, 2/3 cured herb 12,13,14,60,90,150
      D4L3 High dead, 1/3 cured herb 12,13,14,90,120,150
      D4L4 High dead, fully green herb 12,13,14,120,150,150

      Edit copies of this file to create custom fuel moisture scenarios. E.g., you could save the csv file with D1L1 values and name it 'D1L1.csv' to get outputs under drier conditions. That file would look like:
      oneHourFM,tenHourFM,hundredHourFM,liveNonWoodyFM,liveShrubFM,crownFM
      3,4,5,30,60,60
    4. Assuming you downloaded the base (reference) fuelbeds package and created the two folders for custom inputs, your file structure will now look something like:
  2. Open a command prompt. In Windows, you can type "cmd" in the search box of the Start menu to open a DOS window. The following instructions will be for Windows users.
  3. Change directories to the fccs folder that contains the fuelbed.jar file. In our example, at the C prompt type:
    cd C:\FccsConsumeCommandLine\fccs\fccs
  4. To test the waters, type
    java -jar fuelbed.jar
    to get basic usage instructions with the full list of argument options and example code.
  5. Run FCCS. The only required argument to run FCCS is the path to fuelbed(s). To run FCCS for all fuelbeds within a folder (e.g., "fuelbeds_custom") using benchmark (default) fuel moistures, type:
    java –jar fuelbed.jar fuelbeds_custom\*.xml

    • Important: you will need to type the commands in manually as copying and pasting from your browser to the DOS prompt causes errors (the hyphen in HTML renders improperly when pasted into a DOS window.
    • If you get a 'Java not recognized' error double check that you have Java installed and that the executable is added to your computer's PATH environmental variable. This page has a nice walk-through.
    • If you get a ' Could not find or load main class ?jar' error recheck your syntax and paths (this error is typical when you copy/paste commands or when you're not in the same directory as the fccs.jar file).
       
    In this example we had 3 fuelbeds in the fuelbeds_custom folder. If all goes well, you will get a message similar to: 'Elapsed: 0m 1s Files processed: 3' before the C: prompt returns.

    Two output files will be created in the same folder as the fccs.jar file: fccs_summary.csv (FCCS outputs) and consume_loadings.csv (the input file needed to run Consume for given fuelbeds).
  6. To specify optional environmental parameters use the -p indicator followed by parameter name=parameter value. Here's the syntax to run the fuelbeds in the fuelbeds_custom folder using the dry D1L1 scenario we saved in the ev_files folder, with 10mph windspeed (instead of the default of 4mph) and 15% slope (instead of 0%):
    java –jar fuelbed.jar fuelbeds_custom\*.xml –p moisture_file=ev_files\D1L1.csv -p windspeed=10 -p slope=15
  7. To convert the output file (fccs_summary.csv) to metric values, type:
    python fccs_post_process.py fccs_summary.csv metric_all.csv metric_output.csv true
  8. For other arguments, such as specifying an output filename and location, please refer to the help Word document included in the zip file.

Running Consume (building from above instructions)

The Consume 5 calculator module contains the consumption equations published in:
Prichard et al. 2017. Predicting forest floor and woody fuel consumption from prescribed burns in southern and western pine ecosystems of the United States. Forest Ecology and Management 405:328-338. The Consume source code was written in Python and can be cloned from GitHub repository https://github.com/pnwairfire/fera-apps-consume.

  1. Unzip the consume.zip file contained in the zip file.
  2. Organize your input files.
    1. Create 2 folders in the Consume working directory (the folder that contains the consume_batch.py file, in this case C:\FccsConsumeCommandLine\consume):
      'loadings' for the fuelbed loadings file generated by FCCS (consume_loadings.csv) and
      'ev_files' to store your Consume environmental variables files.
    2. Copy the consume_loadings.csv file created by running FCCS above from C:\FccsConsumeCommandLine\fccs\fccs to the loadings folder.
    3. Copy the various sample environmental variables input files from the C:\FccsConsumeCommandLine\input_files folder into the Consume ev_files folder to use as templates (recommend using sample_activity_input_9_52.csv and sample_natural_input_9_52.csv, which contain scenarios for a hypothetical run with fuelbed numbers 9 and 52). Unlike with FCCS, where the ev file contains a single row of moisture values that apply to all fuelbeds in a given run, Consume's ev file contains one row for every fuelbed in the run, corresponding to the fuelbeds given in the consume_loadings.csv file. The columns needed depend on whether you specify natural or activity fuels at command line.
    4. Edit the appropriate sample environmental variables file to match the fuelbeds in your run. In the example FCCS run above we ran 3 fuelbeds, so we would need to copy/paste a 3rd row, update the fuelbed numbers to the ones in this run, and change any of the burn time conditions as needed. Refer to the Consume EV file data dictionary for more information. In this example we'll save the file as 'natural_ev.csv'.
    The file structure of the Consume working directory will now look like:
  3. Open a command prompt and change into the Consume working directory (the folder that contains the consume_batch.py file). In our example:
    cd C:\FccsConsumeCommandLine\consume
  4. Consume requires python 3.10+. Check your python installation by typing:
    python –-version

    If you get a ‘Python was not found’ message, you may either need to install (or reinstall) python, or add the executable to your computer’s PATH variable.
  5. Set up a virtual environment in which to run Consume. The following commands require you have the Python virtual environment creator venv and the package installer pip installed on your system. You will have to run all 3 of these commands the first time you run Consume on your system. Thereafter you only enter the first 2 commands (as the required packages will have already been installed).

    python -m venv my310env    [Note: might take several seconds before the cursor reappears]
    my310env\Scripts\activate.bat (my310env)    [This starts the virtual environment, denoted by (my310env) appearing before the C: prompt]
    pip install -r requirements.txt    [*1st time only*]

    Here's what you should see if all goes well (truncated):

    After a long scroll, the screen should revert to the command prompt within the virtual environment.
  1. Run Consume.
    Consume required command line arguments:
    1. Burn type (activity or natural)
      Activity refers to a burn in recent logging slash and Natural refers to a burn in natural fuels that have not been influenced by recent logging or other disturbances (e.g., wind throw) .
    2. Environmental inputs file (e.g., natural_ev.csv).
      See data dictionaries for natural/activity input files below.
      Note: each fuelbed has to have a corresponding input file record.
    3. Consume loadings file designated with the -f option.

    Example command line entries using the directory structure above: 
    python consume_batch.py natural ev_files\natural_ev.csv –f loadings\consume_loadings.csv
    python consume_batch.py activity ev_files\activity_ev –f loadings\consume_loadings.csv

    Here's an example for a natural fire and what you should see if all went well:

    If you get the error "Invalid fuelbed specified", that probably means there's a mismatch between your loadings and ev file. Check that the environmental variables file has the same fuelbeds as the loadings file.

    The Consume output file (consume_results.csv) has 195 columns (view data dictionary).

    Review of Consume command line arguments:
    Variable Sample arguments Definitions
    Burn type activity
    natural    		 Activity refers to a burn in recent logging slash and Natural refers to a burn in natural fuels that have not been influenced by recent logging or other disturbances (e.g., wind throw)
    Environmental inputs file input_western.csv, sample_activity_inputs.csv,
    sample_natural_inputs.csv    		 The environmental input file specifies environmental variables listed in the table below for each fuelbed listed in the fccs_loadings.csv file.
    Consume loadings file -f fccs_loadings.csv Consume loadings by fuelbed stratum.  This file is a standard output of FCCS calculations (either batch or within the FFT).
    Additional optional arguments are detailed in Consume5_CommandLine_instructions.docx (included in the zip file). 

    Consume environmental inputs file data dictionary
    This optional file should have the same number of records as the fccs_loadings.csv.
    Field Definition (units) Sample data
    fuelbeds Fuelbed number in fccs_loadings.csv (one per row) 220u1
    area Area (acres) 1
    fm_duff Fuel moisture content of duff (%) 40
    fm_1000hr Fuel moisture content of 1000-hr fuels (%) 15
    can_con_pct Percent of canopy stratum blackened by fire (%) 0
    shrub_black_pct Percent of shrub stratum blackened by fire (%) 50
    pile_black_pct Percent consumption of piles (%) 90
    units Tons or Mg/ha tons
    ecoregion Region applicable to natural burn types (boreal, southern, or western) western
    fm_litter Fuel moisture content of litter (%) 10
    season Winter, spring, summer, or fall fall
    duff_pct_available % duff available for consumption, 0-100% 55
    sound_cwd_pct_available % sound coarse woody debris available for consumption, 0-100% 55
    rotten_cwd_pct_available % rotten coarse woody debris available for consumption, 0-100% 70
    Activity fuels only:
    slope Slope gradient (%) 0
    windspeed Windspeed (mph) 4
    days_since_rain Number of days since significant rainfall (> ¼ inch) 7
    length_of_ignition Time to ignite burn unit (min.) 30
    fm_type Type of fuel moisture (MEAS-Th or NFDRS-Th) MEAS-Th
    fm_10hr Fuel moisture of 10-hr wood 10

Fuelbed generator spreadsheet tool

csvAndScript.zip April 1, 2025 (19KB)

.zip file includes an Excel spreadsheet template (fuelbedInputTemplate.xslx) and Python script (generateFuelbeds.py). generateFuelbeds.py will create fuelbeds based on fuelbedInputTemplate.xslx. (No validation support re fuelbed structure and values).