Python port of Consume, a software program developed by the USFS that calculates consumption and emissions from wildland fires
Project description
Python-Consume is a Python package that is a port of Consume 3.0, a software program developed by the USFS that calculates consumption and emissions from wildland fires.
Consume 3.0 was developed and designed originally in Java by US Forest Service Fire and Environmental Research Applications (FERA) team.
This is a recoded version (2010) developed by Michigan Tech Research Institute (MTRI) in consultation with FERA. This version was developed for use in MTRI’s Wildfire Emissions Information System (WFEIS) (wfeis.mtri.org), but was also designed to include more user-friendly shell-based analysis options.
During the recoding process, several errors were identified in the original Consume 3.0 source code, but were fixed (via consultation with original developers Roger Ottmar and Susan Prichard) for this version. For this reason, results from this version will not always align with results from the official Consume 3.0 GUI version of the software. Notable errors include:
incorrect calculation of ‘duff’ reduction (p. 182 in the Consume 3.0)
a bug that interchanges ‘squirrel midden’ density and radius when FCCS values are loaded
a typo that incorrectly calculates pm2.5 emissions from ‘canopy’ consumption (thus influencing total pm2.5 emissions values as well)
For users familiar with the original Consume 3.0 GUI software, see the notes section below for functionality and operational differences between this version and the original.
References:
Requirements:
Python 2.4 or above (free from http://www.python.org)
numpy package (free from http://np.scipy.org/)
For questions/comments, contact:
Michael G. Billmire mgbillmi@mtu.edu
Tyler A. Erickson taericks@mtu.edu
Dependencies
Python 2.4 or above
python-numpy (free from http://np.scipy.org/)
Notes for users familiar with the original Consume 3.0 GUI software
This version relies entirely on FCCS fuelbed data and does NOT use SAF/SRM cover type data except in the background for selecting the correct emissions factor groups to use from a link table provided by FERA.
Heat release output is coupled with consumption outputs.
Instead of selecting a specific ecoregion from Bailey’s set, this version only requires the user to specify whether the fuelbed is located in western, boreal, or southern regions. See the original Consume 3.0 User’s Manual to view which Bailey’s ecoregions fit into these broader categories.
Installation
Python-Consume can be installed from the Python Package Index, using either easy_install or pip:
$ sudo easy_install python-consume
or
$ sudo pip install python-consume
The installation can be tested by running the following:
$ nosetests -s –with-coverage
Usage
(See next section for a complete, uninterrupted example…)
Getting Started with the Fuel Consumption Object
Open a Python shell program (e.g. IDLE, ipython, etc.). Import the module:
>>> from consume import consume
Declare a Consume FuelConsumption object:
>>> fc_obj = consume.FuelConsumption()
Note: if the .xml fuel loading database is located somewhere other than the default location, user can specify this using the ‘fccs_file’ argument, e.g.: fc_obj = consume.FuelConsumption(fccs_file=”C:/Documents/FCCSLoadings.xml”)
SETTING INPUT PARAMETERS
There are a number of alternative options for setting input values:
Start a program that will prompt the user for inputs: >>> fc_obj.prompt_for_inputs()
Load inputs from a pre-formatted csv file (see example file: “consume_inputs_example.csv” for correct formatting):
>>> fc_obj.load_scenario("myscenario.csv")OR to load, calculate outputs, and store outputs at once, use the batch_process method:
>>> fc_obj.batch_process("myscenario.csv", "myoutputs.csv")Individually set/change input values manually:
>>> fc_obj.burn_type = <'natural' or 'activity'> >>> fc_obj.fuelbed_fccs_ids = [FCCSID#1,FCCSID#2,...] >>> fc_obj.fuelbed_area_acres = [AREA#1,AREA#2,...] >>> fc_obj.fuelbed_ecoregion = [ECOREGION#1, ECOREGION#2,...] >>> fc_obj.fuel_moisture_1000hr_pct = [1000hrFM#1, 1000hrFM#2,...] >>> fc_obj.fuel_moisture_duff_pct = [DuffFM#1, DuffFM#2, ...] >>> fc_obj.canopy_consumption_pct = [PctCan#1, PctCan#2,...] >>> fc_obj.shrub_blackened_pct = [PercentShrub#1, PercentShrub#2,...]
inputs specific to ‘activity’ burns:
>>> fc_obj.fuel_moisture_10hr_pct = [10HourFM#1, 10HourFM#2, ...] >>> fc_obj.slope = [Slope#1, Slope#2, ...] >>> fc_obj.windspeed = [Windspeed#1, Windspeed#2, ...] >>> fc_obj.fm_type = <'MEAS-Th', 'ADJ-Th', or 'NFDRS-Th'> >>> fc_obj.days_since_rain = [Days#1, Days#2, ...] >>> fc_obj.lengthOfIgnition = [Length#1, Length#2, ...]
Note: When setting input values, the user can also select a SINGLE value (instead of a list) for any environment variable that will apply to the entire scenario. These environment variables include the following: ecoregion, fuel_moisture_1000hr_pct, fuel_moisture_duff_pct, canopy_consumption_pct, shrub_blackened_pct, slope, windpseed, fm_type, days_since_rain, lengthOfIgnition
Description of the input parameters:
- burn_type
Use this variable to select ‘natural’ burn equations or ‘activity’ (i.e. prescribed) burn equations. Note that ‘activity’ burns require 6 additional input parameters: 10hr fuel moisture, slope, windpseed, fuel moisture type, days since significant rainfall, and length of ignition.
- fuelbed_fccs_ids
a list of Fuel Characteristic Classification System (FCCS) (http://www.fs.fed.us/pnw/fera/fccs/index.shtml) fuelbed ID numbers (1-291). Use the .FCCS.browse() method to load a list of all FCCS ID#’s and their associated site names. Use .FCCS.info(id#) to get a site description of the specified FCCD ID number. To get a complete listing of fuel loadings for an FCCS fuelbed, use: .FCCS.info(id#, detail=True)
- fuelbed_area_acres
a list (or single number to be used for all fuelbeds) of numbers in acres that represents area for the corresponding FCCS fuelbed ID listed in the ‘fuelbeds_fccs_ids’ variable.
- fuelbed_ecoregion
a list (or single region to be used for all fuelbeds) of ecoregions (‘western’, ‘southern’, or ‘boreal’) that represent the ecoregion for the corresponding FCCS fuelbed ID listed in the ‘fuelbeds_fccs_ids’ variable. Regions within the US that correspond to each broad regional description can be found in the official Consume 3.0 User’s Guide, p. 60. Further info on Bailey’s ecoregions can be found here: www.eoearth.org/article/Ecoregions_of_the_United_States_(Bailey) Default is ‘western’
- fuel_moisture_1000hr_pct
1000-hr fuel moisture in the form of a number or list of numbers ranging from 0-100 representing a percentage. Default is 50%
- fuel_moisture_10hr_pct
<specific to ‘activity’ burns> 10-hr fuel moisture in the form of a number or list of numbers ranging from 0-100 representing a percentage. Default is 50%
- fuel_moisture_duff_pct
Duff fuel moisture. A number or list of numbers ranging from 0-100 representing a percentage. Default is 50%.
- canopy_consumption_pct
Percent canopy consumed. A number or list of numbers ranging from 0-100 representing a percentage. Set to ‘-1’ to use an FCCS-fuelbed dependent precalculated canopy consumption percentage based on crown fire initiation potential, crown to crown transmissivity, and crown fire spreading potential. (note: auto-calc is not available for FCCS ID’s 401-456) Default is -1
- shrub_blackened_pct
Percent of shrub that has been blackened. A number or list of numbers ranging from 0-100 representing a percentage. Default is 50%
- slope
<specific to ‘activity’ burns> Percent slope of a fuelbed unit. Used in predicting 100-hr (1-3” diameter) fuel consumption in ‘activity’ fuelbeds. Valid values: a number or list of numbers ranging from 0-100 representing a percentage. Default is 5%
- windspeed
<specific to ‘activity’ burns> Mid-flame wind speed (mph) during the burn. Maximum is 35 mph. Used in predicting 100-hr (1-3” diameter) fuel consumption in ‘activity’ fuelbeds. Default is 5 mph
- fm_type
<specific to ‘activity’ burns> Source of 1000-hr fuel moisture data.
“Meas-Th” (default) : measured directly
“NFDRS-Th” : calculated from NFDRS
“ADJ-Th” : adjusted for PNW conifer types
Note: 1000-hr fuel moisture is NOT calculated by Consume, i.e. user must derive 1000-hr fuel moisture & simply select the method used.
- days_since_rain
<specific to ‘activity’ burns> Number of days since significant rainfall. According to the Consume 3.0 User’s Guide, “Significant rainfall is one-quarter inch in a 48-hour period.” Used to predict duff consumption in ‘activity’ fuelbeds.
- lengthOfIgnition
<specific to ‘activity’ burns> The amount of time (minutes) it will take to ignite the area to be burned. Used to determine if a fire will be of high intensity, which affects diameter reduction of large woody fuels in ‘activity’ fuelbeds.
The user can also optionally set alternate output units. Use the list_valid_units() method to view output unit options. Default fuel consumption units are tons/acre (‘tons_ac’).
>>> consume.list_valid_units()
Output:
['lbs', 'lbs_ac', 'tons', 'tons_ac', 'kg', 'kg_m^2', 'kg_ha', 'kg_km^2' 'tonnes', 'tonnes_ha', 'tonnes_km^2']
>>> fc_obj.output_units = 'lbs'
CUSTOMIZING FUEL LOADINGS
Fuel loadings are automatically imported from the FCCS database based on the FCCS fuelbed ID#s selected by the user. If desired, the user can also customize FCCS fuel loadings by setting the ‘.customized_fuel_loadings’ variable to a list of 3 value lists in this format: [fuelbed index number {interger}, fuel stratum {string}, loading value {number}]
e.g.:
>>> fc_obj.customized_fuel_loadings = [[1, 'overstory', 4.5],[2, 'shrub_prim', 5]]
The above command will change the canopy ‘overstory’ loading in the first (‘1’) fuelbed to 4.5 (tons/acre) and will change the ‘shrub_prim’ (primary shrub loading) in the second (‘2’) fuelbed to 5 tons/acre. To view all valid stratum names and units, use the fc_obj.FCCS.list_fuel_loading_names() method.
OUTPUTS
Consumption outputs can be accessed by calling the .results(), .report(), or .batch_process() methods. Calling any of these methods will trigger the calculation of all fuel consumption equation and will return the results in a variety of different formats:
>>> fc_obj.results()
… generates & prints a python DICTIONARY of consumption results by fuel category (major and minor categories) See complete example below to see how individual data categories can be accessed from this dictionary.
>>> fc_obj.report(csv="")
…prints a TABULAR REPORT of consumption results for the major fuel categories (similar to the “Fuel Consumption by Combustion Stage” report produced by the official Consume 3.0 GUI program). To export a version of this report as a CSV FILE, use the ‘csv’ argument to specify a file name, e.g.: >>> fc_obj.report(csv = “consumption_report.csv”)
>>> fc_obj.batch_process(csvin="", csvout="")
…similar to the .report() method, although requires an input csv file and will export results to the specified CSV output.
OTHER USEFUL METHODS
>>> consume.list_valid_units()
…displays a list of valid output unit options
>>> consume.list_valid_consumption_strata()
…displays a list of valid consumption strata group names
>>> fc_obj.list_variable_names()
…displays a list of the variable names used for each input parameter
>>> fc_obj.FCCS.browse()
…loads a list of all FCCS fuelbed ID numbers and their site names
>>> fc_obj.FCCS.info(#)
…provides site description of the FCCS fuelbed with the specified ID number. Set detail=True to print out detailed fuel loading information
>>> fc_obj.FCCS.get_canopy_pct(#)
…displays estimated canopy consumption percent as calculated by MTRI for the specified FCCS ID number. This is the value that will be used if canopy_consumption_pct is set to -1.
>>> fc_obj.load_example()
…loads an example scenario with 2 Fuelbeds
>>> fc_obj.reset_inputs_and_outputs()
…clears input and output parameters
>>> fc_obj.display_inputs()
…displays a list of the input parameters. Useful for checking that scenario parameters were set correctly
Working with the EMISSIONS Object
For emissions data, declare a Consume Emissions object by nesting in the FuelConsumption object we were working on above as the only required argument.
>>> e_obj = consume.Emissions(fc_obj)
SETTING INPUT PARAMETERS
Input parameters for emissions calculations are much easier to set than those for FuelConsumption, as they are ALL ultimately automatically derived from the parameters set within the nested FuelConsumption object. The input parameters required for the emissions calculations are as follows:
FUEL CONSUMPTION (tons/ac) & the scenario of corresponding FCCS ID#s, AREAS, and ECOREGIONS, all of which is derived from the FuelConsumption object specified in the Emissions object declaration we just did
EMISSIONS FACTOR GROUP (‘efg’), which specifies the appropriate set of emissions factors (lbs/tons consumed for each of 7 emissions species) to use for the scenario. This is automatically selected based on the FCCS fuelbeds in the consumption scenario, but the user can override the auto-select process if desired as described below.
As with the FuelConsumption object, the user can also optionally set alternate output units for the Emissions object. Use the consume.list_valid_units() method to view output unit options. Default output units for emissions are lbs/ac.
>>> e_obj.output_units = 'kg_ha'
To change the FuelConsumption units, simply modify the units of the FC object that is nested within the Emissions object:
>>> e_obj.FCobj.output_units = 'kg_ha'
OUTPUTS
As with the FuelConsumption object, Emissions outputs can be accessed by calling the .results() or .report() methods. Calling either methods will trigger the calculation of emissions and output results in a variety of different formats:
>>> e_obj.results()
…generates a python DICTIONARY similar to the one created by the FuelConsumption object, but with Emissions results added (consumption data is also included). See complete example below to see how specific data categories can be accessed in this dictionary.
>>> e_obj.report()
…prints a TABULAR REPORT of emissions results for all pollutants and combustion stages (similar to the “Emissions by Combustion Stage” report produced in the official Consume 3.0 GUI program). To export a version of this report as a CSV FILE, use the ‘csv’ argument to specify a file name, e.g.: >>> e_obj.report(csv = “emissions_report.csv”)
OTHER USEFUL METHODS
>>> e_obj.display_inputs()
…displays a list of the input parameters. Useful for checking that scenario parameters were set correctly
>>> e_obj.efDB.browse()
…displays a list of all emissions factor groups and their associated fuel types and references
>>> e_obj.efDB.info(#)
…display detailed information about the specified emissions factor group ID# (use the .browse() method above to view ID#s). Includes the actual emissions factor values.
For further help on specific methods or properties, type “help([CONSUME METHOD])” within a python shell, e.g.:
>>> help(fc_obj.FCCS.info)
Output:
Help on method info in module consume_obj:
info(self, fccs_id, detail=False) method of consume_obj.FCCSDB instance
Display an FCCS fuelbed description.
Prints fuel loading information on the fuelbed with the specified
FCCS ID. Requires one argument: an integer refering to a specific FCCS
ID. For a list of valid FCCS IDs, use the .browse() method."
Complete Uninterrupted Example
The following example sets up a ‘natural’ burn scenario in which 100 acres FCCS fuelbed ID #1 (“Black cottonwood - Douglas fir - Quaking aspen riparian forest”) and 200 acres of FCCS fuelbed ID #47 (“Redwood - Tanoak forest”) are consumed. 1000-hr and duff fuel moisture is set at 50% for fuelbed ID #1 and 40% for fuelbed ID #47. Canopy consumption and shrub percent black is set at 25% for both fuelbeds.
>>> from consume import consume >>> fc_obj = consume.FuelConsumption() >>> fc_obj.fuelbed_fccs_ids = [1, 47] >>> fc_obj.fuelbed_area_acres = [100, 200] >>> fc_obj.fuelbed_ecoregion = 'western' >>> fc_obj.fuel_moisture_1000hr_pct = [50, 40] >>> fc_obj.fuel_moisture_duff_pct = [50, 40] >>> fc_obj.canopy_consumption_pct = 25 >>> fc_obj.shrub_blackened_pct = 25 >>> fc_obj.output_units = 'kg_ha' >>> fc_obj.display_inputs()
Output:
Current scenario parameters: Parameter Value(s) -------------------------------------------------------------- Burn type natural FCCS fuelbeds (ID#) [1, 47] Fuelbed area (acres) [100, 200] Fuelbed ecoregion western Fuel moisture (1000-hr, %) [50, 40] Fuel moisture (duff, %) [50, 40] Canopy consumption (%) 25 Shrub blackened (%) 25 Output units kg_ha
>>> fc_obj.report()
Output:
FUEL CONSUMPTION Consumption units: kg/ha Heat release units: btu/ha Total area: 300 acres FCCS ID: 1 Area: 100 Ecoregion: western CATEGORY Flaming Smoldering Residual TOTAL canopy 1.25e+04 9.58e+02 1.51e+02 1.36e+04 shrub 1.26e+03 6.97e+01 0.00e+00 1.33e+03 nonwoody 3.95e+02 2.08e+01 0.00e+00 4.16e+02 llm 2.32e+03 2.20e+02 0.00e+00 2.54e+03 ground fuels 8.97e+02 1.51e+04 3.72e+04 5.32e+04 woody fuels 9.71e+03 5.61e+03 8.81e+03 2.41e+04 TOTAL: 2.70e+04 2.20e+04 4.61e+04 9.52e+04 Heat release: 1.19e+08 9.70e+07 2.03e+08 4.20e+08 FCCS ID: 47 Area: 200 Ecoregion: western CATEGORY Flaming Smoldering Residual TOTAL canopy 7.93e+03 2.48e+03 2.05e+03 1.25e+04 shrub 3.87e+03 2.69e+02 0.00e+00 4.13e+03 nonwoody 9.88e+02 5.20e+01 0.00e+00 1.04e+03 llm 4.93e+03 5.41e+02 0.00e+00 5.47e+03 ground fuels 3.59e+03 4.08e+04 6.98e+04 1.14e+05 woody fuels 2.56e+04 2.06e+04 2.49e+04 7.11e+04 TOTAL: 4.69e+04 6.47e+04 9.67e+04 2.08e+05 Heat release: 2.07e+08 2.85e+08 4.27e+08 9.18e+08 ALL FUELBEDS: Consumption: 4.03e+04 5.04e+04 7.99e+04 1.71e+05 Heat release: 3.26e+08 3.82e+08 6.30e+08 1.34e+09
>>> fc_obj.results()['consumption']['ground fuels']
Output:
{'basal accumulations': {'flaming': array([-0., 0.]),
'residual': array([-0., 0.]),
'smoldering': array([-0., 0.]),
'total': array([-0., 0.])},
'duff, lower': {'flaming': array([ 0., 0.]),
'residual': array([ 35377.20573062, 62608.52081126]),
'smoldering': array([ 8844.30143266, 15652.13020281]),
'total': array([ 44221.50716328, 78260.65101407])},
'duff, upper': {'flaming': array([ 896.68092549, 3586.72370195]),
'residual': array([ 1793.36185097, 7173.4474039 ]),
'smoldering': array([ 6276.76647841, 25107.06591365]),
'total': array([ 8966.80925487, 35867.23701949])},
'squirrel middens': {'flaming': array([ 0., 0.]),
'residual': array([ 0., 0.]),
'smoldering': array([ 0., 0.]),
'total': array([ 0., 0.])}}
>>> e_obj = consume.Emissions(fc_obj) >>> e_obj.display_inputs()
Output:
CONSUMPTION Current scenario parameters: Parameter Value(s) -------------------------------------------------------------- Burn type ['natural'] FCCS fuelbeds (ID#) [1, 47] Fuelbed area (acres) [ 100. 200.] Fuelbed ecoregion ['western'] Fuel moisture (1000-hr, %) [ 50. 40.] Fuel moisture (duff, %) [ 50. 40.] Canopy consumption (%) [ 25.] Shrub blackened (%) [ 25.] Output units ['kg_ha'] EMISSIONS Current scenario parameters: Parameter Value(s) --------------------------------------------------------------
>>> e_obj.report()
Output:
EMISSIONS Units: lbs_ac FCCS ID: 1 Area: 100 ac. (40.5 ha) Emissions factor group: 2 SPECIES Flaming Smoldering Residual TOTAL pm 2.77e+02 3.73e+02 7.82e+02 1.43e+03 pm10 1.69e+02 2.54e+02 5.33e+02 9.56e+02 pm2.5 1.47e+02 2.30e+02 4.82e+02 8.58e+02 co 1.11e+03 3.59e+03 7.53e+03 1.22e+04 co2 4.09e+04 2.80e+04 5.87e+04 1.28e+05 ch4 5.31e+01 1.92e+02 4.03e+02 6.49e+02 nmhc 6.27e+01 1.37e+02 2.88e+02 4.88e+02 FCCS ID: 47 Area: 200 ac. (80.9 ha) Emissions factor group: 4 SPECIES Flaming Smoldering Residual TOTAL pm 4.60e+02 9.69e+02 1.45e+03 2.88e+03 pm10 2.45e+02 7.30e+02 1.09e+03 2.07e+03 pm2.5 2.01e+02 6.81e+02 1.02e+03 1.90e+03 co 1.11e+03 7.87e+03 1.18e+04 2.08e+04 co2 7.24e+04 8.72e+04 1.30e+05 2.90e+05 ch4 6.28e+01 5.08e+02 7.60e+02 1.33e+03 nmhc 6.70e+01 3.81e+02 5.70e+02 1.02e+03 ALL FUELBEDS: Units: lbs_ac Total area: 300 ac. (121.4 ha) pm 3.99e+02 7.70e+02 1.23e+03 2.40e+03 pm10 9.45e+01 3.02e+01 2.14e+01 1.46e+02 pm2.5 2.96e+01 3.08e+00 0.00e+00 3.27e+01 co 7.81e+00 6.37e-01 0.00e+00 8.45e+00 co2 4.02e+01 6.65e+00 0.00e+00 4.68e+01 ch4 2.65e+01 4.93e+02 9.07e+02 1.43e+03 nmhc 2.01e+02 2.37e+02 2.99e+02 7.36e+02
>>> e_obj.results()['emissions']['co2']
Output:
{'flaming': array([ 40877.14600611, 72354.16061005]),
'residual': array([ 58664.90328723, 130457.66209735]),
'smoldering': array([ 27980.07467362, 87193.41115534]),
'total': array([ 127522.12396695, 290005.23386274])}
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
