fireLib User Manual and Technical Reference

© 1996 by Collin D. Bevins

Release 1, October 1996

This research was supported in part by funds provided by the Intermountain Research Station, Forest Service, U.S. Department of Agriculture. Additional support was provided by Systems for Environmental Management, a Montana nonprofit research organization.

CONTENTS

0. Introduction

1. The Fire Behavior Calculation Pipeline

2. Fuel Catalog, Fuel Model, and Fuel Particle Objects

2.1 Fuel Catalog Objects and Methods

2.2 Fuel Model Objects and Methods

2.3 Fuel Particle Objects and Methods

2.4 Flame Length Table

3. Error Handling

3.1 Return Codes and Error Messages

3.2 catalogHandle Validation

4. Accessing Object Properties Using Macros

4.1 Fuel Catalog Property Macros

4.2 Fuel Model Property Macros

4.3 Fuel Particle Property Macros

4.4 Fuel Model Environment Property Macros

4.5 Fuel Model Fire Behavior Property Macros

5. Functional Review

5.1 Creating and Destroying Fuel Catalogs

5.2 Creating and Destroying Fuel Models

5.3 Creating Fuel Particles

5.4 Creating and Destroying Flame Length Tables

5.5 Calculating Fire Behavior

6. Example: A Simple Fire Growth Simulator

7. Validation and Performance

8. Availability and Licensing

8.1 Distribution

8.2 Bugs

8.3 Licensing

9. Selected References

10. Function Reference

Fire_FlameLengthTable()

Fire_FlameScorch()

Fire_FuelCatalogCreate()

Fire_FuelCatalogCreateStandard()

Fire_FuelCatalogDestroy()

Fire_FuelCombustion()

Fire_FuelModelCreate()

Fire_FuelModelDestroy()

Fire_FuelModelExists()

Fire_FuelParticleAdd()

Fire_SpreadAtAzimuth()

Fire_SpreadNoWindNoSlope()

Fire_SpreadWindSlopeMax()

0. Introduction

fireLib is a C function library for predicting the spread rate and intensity of free-burning wildfires. It is derived directly from the BEHAVE (Andrews 1986) fire behavior algorithms for predicting fire spread in two dimensions, but is optimized for highly iterative applications such as cell- or wave-based fire growth simulation.

The BEHAVE System was developed in the early 1980's to calculate a few (less than 50) fire behavior projections at a time and display the results in a small table. In the past decade greater attention has been given to spatially explicit fire growth modeling where fire is simulated within a large array of terrain, fuel, and weather conditions that vary spatially and temporally. Such growth models make highly repetitive computations of fire spread from each source point to multiple destination points; a process that is repeated for each source point in the map and for each time step in the simulation. This quickly results in millions of iterations and provides an opportunity to realize significant benefits from a library of optimally encapsulated fire behavior functions.

The fireLib library was developed to give fire growth modellers a simple, common, and optimized application programming interface (API) to use in their applications. It is written entirely in ANSI standard C and also compiles under a wide range of Kernighan & Ritchie (pre-ANSI standard) C and C++ compilers on a variety of personal computers and work stations.

While fireLib contains 13 functions, as few as 4 functions are required to create a simple yet efficient and functional fire growth simulator. The example simulator may serve as a foundation for more realistic applications.

This paper is both a user manual and a technical reference to fireLib. We assume the reader is familiar with the basic concepts of fuel models and fire behavior modeling and make no attempt to teach these concepts. Readers are furthermore cautioned to understand the assumptions and limitations (summarized by Andrews 1986) of the Rothermel (1972) fire model, the BEHAVE System, and all models derived from them, including the fireLib API.

1. The Fire Behavior Calculation Pipeline

Calculation of fire spread and intensity may be represented as a pipeline through which sets of input parameters are introduced at four stages to calculate succeeding fire behavior variables:

While fuel bed characteristics generally vary throughout the landscape, they are usually considered invariant within the time frame of a fire behavior growth simulation. A significant improvement in fire modelling performance is therefore realized by calculating and storing variables that are fuel bed dependent intermediate for each fuel model. In the first stage of the pipeline variables such as characteristic surface area, loading, and residence time are derived. The fireLib Fire_FuelCombustion() function performs the first stage computations.

Fuel moisture, wind speed, and wind direction are more temporal. Because the Rothermel (1972) fire model uses fuel moisture to determine the heat sink term in deriving fire reaction intensity and the no-wind no-slope spread rate, fuel moisture is introduced in the second stage of the pipeline. The fireLib Fire_SpreadNoWindNoSlope() function performs the second stage computations.

Rothermel (1972) modelled the effect of slope on fire behavior using the same mechanism as for wind; in fact he calls the combined effect of slope and wind the "effective windspeed". Thus, although slope and aspect are invariant over time, they are introduced into the pipeline at stage 3 along with wind speed and wind direction. In the third stage the maximum spread rate and direction of maximum spread are calculated by the fireLib Fire_SpreadWindSlopeMax() function.

In Stage 4, fire behavior in any compass direction is determined using the elliptical growth model developed by Anderson (1983) and employed by BEHAVE (Andrews 1986). The four vector-dependent fire behavior outputs of spread rate, Byram's fireline intensity, flame length, and scorch height are derived by the fireLib Fire_SpreadAtAzimuth() function.

Significant improvement in fire model performance is realized by partitioning the fire behavior computations into these four stages and proceeding only through those stages necessary to arrive at new behavior estimates.

After optimizing the fire behavior algorithms from BEHAVE, the following proportion of time is spent in a single iteration through each stage of the pipeline:

2. Fuel Catalog, Fuel Model, and Fuel Particle Objects

The fireLib API employs the concepts of a fuel catalog, a fuel model, and a fuel particle. A fireLib application may contain one or more fuel catalogs. A fuel catalog is a collection of zero or more fire behavior fuel models, and each fuel model contains zero or more fuel particles.

2.1 Fuel Catalog Objects and Methods

A fuel catalog is merely a collection of fuel models. In addition to fuel data, it serves as a container for state information on function status, error messages, and use of the optional flame length table. Each fuel catalog is identified by a handle (or pointer) returned by one of the fuel catalog creation functions. All other functions require this handle as an input argument.

The Fire_FuelCatalogCreate() function creates a new fuel catalog. The catalog name and maximum number of fuel models it may contain are specified as function arguments. The fuel models are subsequently defined for the catalog by the Fire_FuelModelCreate() function (see below).

The Fire_FuelCatalogCreateStandard() function also creates a new fuel catalog with the specified name and fuel model capacity. It also automatically pre-defines 14 fuel models; a no-fuel model and the 13 standard fire behavior models.

The Fire_FuelCatalogDestroy() function removes the specified fuel catalog and all its fuel models from program memory.

2.2 Fuel Model Objects and Methods

A fuel model describes the fuel particles and fuel bed arrangement for a stylized or representative fuel condition. The fuel model object also serves as a container for all the current fire environment, fuel bed, and fire behavior state information relating to the fuel model.

Each fuel model within a catalog is identified by a unique integer number. This number may range from zero to the maximum number of models allowed in the catalog. All fireLib fire behavior functions require the fuel catalog handle and the fuel model number as input arguments.

The Fire_FuelModelCreate() function creates a new fuel model. The catalog handle, model number, name, description, maximum number of fuel particles allowed, fuel bed depth, and dead fuel extinction moisture content are specified as function arguments. This function will also re-define any fuel model with the same model number in the catalog. Fuel particles are subsequently added to the fuel model by the Fire_FuelParticleAdd() function (see below).

The Fire_FuelModelDestroy()function removes a fuel model and its fuel particles from its catalog.

It is important to note that because each fuel catalog is a separate object, there is not necessarily any correspondence between fuel models with the same numbers in different catalogs. For example, fuel model 6 in one fuel catalog may be entirely different from fuel model 6 in another catalog, depending on how the fuel models were created.

2.3 Fuel Particle Objects and Methods

A fuel particle is a specific type of fuel component found in a fuel model. Examples of fuel particles include needle, grass, or foliage litter; standing grass; dead and down twigs and branches of various diameters; and live stems and foliage.

The Fire_FuelParticleAdd() function adds new fuel particles to a fuel model within a catalog. Function arguments include the particle life code (dead, live herbaceous, or live woody stem), surface-area-to-volume ratio, loading, particle density, low heat of combustion, and total and effective silica content. Each fuel model may contain from zero to the maximum number of fuel particles specified when the fuel model was created.

Fuel particles are assigned an index number (starting with 0) as they are added to the fuel model. Programmers use the fuel particle property macros (section 5.2) to access or update particle characteristics. There is no function for removing fuel particles from a fuel model.

2.4 Flame Length Table

The flame length table is an optional object belonging to the fuel catalog.

The Fire_SpreadAtAzimuth() and Fire_FlameScorch() functions calculate flame length using a power function of the fireline intensity. The power function can significantly impact program performance, and it is generally more efficient to look up the flame length from a pre-calculated table given the fireline intensity. Since flame length is strictly an output variable (it is never used to derive any other variable), it is usually not necessary to calculate it to full floating point precision anyway.

The Fire_FlameLengthTable() builds a flame length look up table that is subsequently used by Fire_SpreadAtAzimuth() and Fire_FlameScorch() instead of direct computation. The function takes as arguments the number of flame length classes and the size of each flame length class (e.g., 1 foot), so the user has control over the table precision.

3. Error Handling

3.1 Return Codes and Error Messages

Most fireLib functions return a status code of FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure. The two exceptions are the fuel catalog creation functions Fire_FuelCatalogCreate() and Fire_FuelCatalogCreateStandard(), which return a catalog handle on success or NULL on failure.

In the event of a failure, all fireLib functions write an error message to the catalog's error message buffer. The programmer may access and display the message using the macro:

error = FuelCat_Error(catalog);

The error message remains intact until overwritten by a subsequent message. The return status of the most recent fireLib function is also available via the macro:

status = FuelCat_Status(catalog);

Error messages issued by each fireLib function are discussed in the Function Reference.

3.2 catalogHandle Validation

All fireLib functions also validate the catalog handle argument to ensure it is not NULL and that it contains a valid magic cookie. The validation is performed within the standard C assert() function, which prints a short (compiler-dependent) message to stderr and aborts the program with a core dump.

If you are satisfied that your program is not passing around invalid catalog handles, you may circumvent the assert() test by the standard C mechanism of defining the macro NDEBUG. This may slightly improve your application performance.

4. Accessing Object Properties Using Macros

fireLib functions return a success or failure code rather than computation results. Access to catalog, fuel model, and fuel particle properties, including all input variables, stored intermediates, and all fire behavior outputs, is available to the programmer via C macros. These macros are used like C function calls to access or update current object properties.

A property macro consists of the "Fuel_" prefix followed by a descriptive label and a 1, 2, or 3 arguments. The first argument is always the catalog handle. If two or more arguments, the second is always the fuel modelNumber. If three or more arguments, the third argument is either the fuel particle index, life class index, or moisture class index.

The following symbols are used to represent the property macro argument types:

For example, the macro Fuel_Load(c,m,p) refers to the loading of fuel particle p in fuel model m of fuel catalog c.

The following tables document the property macro names, arguments, units of measure, and whether the property is input by the user (I) or derived by the function (D).

4.1 Fuel Catalog Property Macros

Macros for accessing fuel catalog properties require one argument, the catalog, which must be a valid FuelCatalogPtr handle. A common use of a fuel catalog macro is to get the current error message:

message = FuelCat_Error(catalog);

4.2 Fuel Model Property Macros

Macros for accessing fuel model properties require two arguments; catalog, and modelNumber. The catalog argument must be a valid FuelCatalogPtr handle and the modelNumber argument is a fuel model number. To access, for example, the the light logging slash (fuel model 11) fuel bed depth:

depth = Fuel_Depth(catalog,11);

4.3 Fuel Particle Property Macros

Macros for accessing fuel particle properties require three arguments; catalog, modelNumber, and the particle index. The catalog argument must be a valid FuelCatalogPtr handle, the modelNumber argument is a fuel model number. Particle indexes start at 0 and correspond to the order in which Fire_FuelParticleAdd() was called. To access, for example, the light logging slash (fuel model 11) 10-hour fuel load:

load = Fuel_Load(catalog,11,1);

4.4 Fuel Model Environment Property Macros

Macros for accessing fuel model environment properties require two arguments; catalog and modelNumber. The catalog argument must be a valid FuelCatalogPtr handle and the modelNumber argument is a fuel model number. To access, for example, the current aspect setting for the light logging slash model (fuel model 11):

aspect = Fuel_Aspect(catalog,11);

The macro to access environmental fuel moisture requires a third argument, mclass, which indicates which of four dead fuel classes or two live fuel classes to access. To access the live herbaceous fuel moisture content:

herbMoisture = Fuel_EnvMoisture(catalog,11,FIRE_MCLASS_HERB);

4.5 Fuel Model Fire Behavior Property Macros

Macros for accessing fuel model fire behavior properties require two arguments; catalog and modelNumber. The catalog argument must be a valid FuelCatalogPtr handle and the modelNumber argument is a fuel model number. To access, for example, the spread rate at the current azimuth for the light logging slash model (fuel model 11):

spread = Fuel_SpreadAny(catalog,11);

5. Functional Review

There are eight functions for creating, querying, and destroying fuel catalog, fuel model, fuel particle, and flame length table objects, and four functions for determining fire behavior for fuel models.

5.1 Creating and Destroying Fuel Catalogs

FuelCatalogPtr Fire_FuelCatalogCreate (char *name, size_t maxModels )

Creates a fuel catalog instance and returns its handle. The new catalog has space for fuel models numbered 0 through maxModels, but none are defined until subsequent calls by Fire_FuelModelCreate(). The function returns NULL if unable to create the catalog.

FuelCatalogPtr Fire_FuelCatalogCreateStandard (char *name,size_t maxModels )

Creates a fuel catalog instance, defines the 13 standard fire behavior fuel models (models 1-13) and a no-fuel model (model 0), and returns the new catalog's handle. Additional fuel models (14 - maxModels) may be defined using Fire_FuelModelCreate(). The function returns NULL if unable to create the catalog.

int Fire_FuelCatalogDestroy ( FuelCatalogPtr catalog )

Destroys the specified fuel catalog and releases all memory allocated to the catalog's fuel models and fuel particles. The catalog handle is no longer valid. The function returns FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure.

5.2 Creating and Destroying Fuel Models

int Fire_FuelModelCreate ( FuelCatalogPtr catalog, size_t modelNumber, char *name, char *desc, double depth, double mext, double adjust, size_t maxParticles )

Adds a new fuel modelNumber to catalog. If a fuel model with modelNumber already exists in the catalog, it is first destroyed before the new one is created. While space is set aside for up to maxParticle fuel particles, no particles are defined until subsequent calls to Fire_FuelParticleAdd(). The function returns FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure.

int Fire_FuelModelExists ( FuelCatalogPtr catalog, size_t modelNumber )

This function returns 1 if fuel modelNumber is currently defined in catalog, otherwise it returns 0.

int Fire_FuelModelDestroy ( FuelCatalogPtr catalog, size_t modelNumber )

Removes fuel modelNumber from catalog and releases all memory allocated to the model and its fuel particles. The modelNumber may be re-used by a subsequent call to Fire_FuelModelCreate(). The function returns FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure.

5.3 Creating Fuel Particles

5.4 Creating and Destroying Flame Length Tables

int Fire_FlameLengthTable ( FuelCatalogPtr catalog, size_t flameClasses, double flameStep )

Creates a flame length look-up table for catalog and returns FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure. If no table is defined for catalog, Fire_SpreadAtAzimuth() and Fire_FlameScorch() calculate flame lengths using the BEHAVE equations. In some simulations, these calculations may consume most of the computation time, and using a look-up table is significantly faster.

This function creates a table with flameClasses categories (beginning at flame length 0) of size flameStep feet. The table is then populated and automatically used in all subsequent calls to Fire_SpreadAtAzimuth() and Fire_FlameScorch().

The flame length table may be redefined at any time by issuing another call to Fire_FlameLengthTable() with new flameClasses and flameStep values. The flame length table is destroyed by calling Fire_FlameLengthTable() with a 0 value for fireClasses, after which all flame lengths are again calculated rather than looked up.

5.5 Calculating Fire Behavior

int Fire_FuelCombustion ( FuelCatalogPtr catalog, size_t modelNumber )

Calculates all intermediate fuel bed and combustion variables that are solely dependent upon fuel bed characteristics (stage 1). It is normally not called directly by the user as it is automatically called by Fire_SpreadNoWindNoSlope() whenever fuel modelNumber has been defined or updated. The function returns FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure.

A large number of intermediate fuel and combustion variables are calculated and stored by this function. The original BEHAVE System spends approximately 80% of its computation time in the redundant calculation of these non-variant values. Isolating these computations within a function which is called only once per fuel model dramatically improves performance.

int Fire_SpreadNoWindNoSlope ( FuelCatalogPtr catalog, size_t modelNumber, double moisture[FIRE_MCLASSES] )

Calculates reaction intensity, heat per unit area, and no-wind no-slope fire spread rate for fuel modelNumber. It automatically calls Fire_FuelCombustion() if needed for modelNumber . The moisture[] array contains the current fuel moistures (fraction of oven-dry weight) for four size classes of dead fuel (1-, 10-, 100-, and 1000-hour time lag) and 2 classes of live fuel (herbaceous and stem). The function returns FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure.

int Fire_SpreadWindSlopeMax ( FuelCatalogPtr catalog, size_t modelNumber, double windFpm, double windDeg, double slope, double aspect )

Calculates the maximum spread rate and direction of maximum spread given the wind and terrain conditions. Once Fire_SpreadNoWindNoSlope() has been called to establish initial conditions for this fuel modelNumber, Fire_SpreadWindSlopeMax() may be called repeatedly with different input arguments to optimize simulation performance. The function returns FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure.

int Fire_SpreadAtAzimuth ( FuelCatalogPtr catalog, size_t modelNumber, double azimuth, size_t whichOutputs )

Calculates spread rate along the requested compass azimuth for fuel modelNumber, and optionally calculates Byram's fireline intensity, flame length, and/or scorch height along azimuth as requested by whichOutputs. Once Fire_SpreadWindSlopeMax() has been called to establish initial conditions, Fire_SpreadAtAzimuth() may be called repeatedly to get fire behavior at multiple azimuths. The function returns FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure.

whichOutputs is specified by OR'ing together any of the following macro constants: FIRE_NONE, FIRE_BYRAMS, FIRE_FLAME, and/or FIRE_SCORCH. If FIRE_NONE is specified alone, only the spread rate is determined for the azimuth. FIRE_NONE and FIRE_BYRAMS require little computation time. FIRE_FLAME adds a call to the C pow() function (unless a flame length table is in use), and FIRE_SCORCH adds a call to both pow() and sqrt(), and therefore exacts the greatest performance pendalty.

If a flame length table has been defined for catalog via a previous call to Fire_FlameLengthTable(), it is used to look up the flame length. Otherwise, flame lengths are calculated directly.

int Fire_FlameScorch ( FuelCatalogPtr catalog, size_t modelNumber, size_t whichOutputs )

Calculates the flame length or scorch height along the azimuth established by the most recent call to Fire_SpreadAtAzimuth(). It is provided for those cases where it is faster to call Fire_SpreadAtAzimuth() with the FIRE_NONE option (perhaps to check all points of the compass), then calculate the flame length and/or scorch height for a specific azimuth. The function returns FIRE_STATUS_OK on success or FIRE_STATUS_ERROR on failure.

whichOutputs is specified by OR'ing together the macro constants FIRE_FLAME and/or FIRE_SCORCH.

If a flame length table has been defined for catalog via a previous call to Fire_FlameLengthTable(), it is used to look up the flame length. Otherwise, flame lengths are calculated directly.

6. Example: A Simple Fire Growth Simulator

A simple but functional fire growth simulator is presented as an example application using the fireLib API. The source code for this example resides in the file named fireSim.c.

Although the source listing is fairly short (about 200 lines of C code plus comments), it is capable of simulating fire growth within a spatially variable fuel, slope, aspect, wind speed, wind direction, and fuel moisture complex. It reads an ignition time map that may be seeded with any number of pre-planned ignitions in any shape and at any time or set of staggered times. The ignition map is modified as part of the simulation, and upon completion may be saved along with a flame length map to a GRASS format ASCII map file.

While the example simulation creates fuel, slope, aspect, and environmental conditions that are spatially constant, it is easily modified to create variable fuels, fuel breaks, variable weather, and multiple and time-staggered ignition points to acheive interesting effects. The figures below were generated by changing just a few source lines to acheive interesting effects.

The example remains simplistic, however, in that is does not allow temporal variability in wind speed, wind direction, or fuel moisture content; this is left as an exercise for the reader (I've always wanted to say that!).

Perhaps the best use of the example is to illustrate some common problems with cell-based contagious growth algorithms. The example simulation uses a simple 8-neighbor cell contagion algorithm for fire spread. These type of algorithms produce notoriously distorted fire perimeters whenever the direction of maximum spread approaches, but is not aligned with, a major neighbor vector (see French 1992 for a more thorough discussion).

Figure 1 maps the fire ignition times from a single ignition point in uniform fuel and environmental conditions without any slope or wind effect. It was created by changing wind speed to 0 (at fireSim.c line 42) and centering the ignition point (line 125). The octogonal shape is characteristic of the 8-neighbor contagion algorithm, and illustrates the amount of distortion from the expected circular perimeter.

Adding a 4 miles/hour windspeed (figure 2) shows how increasing spread rate produce fire shapes that do not resemble the expected elliptical geometry. It was generated by the source code listing in fireSim.c.

In figure 3 the wind direction was changed from 0 to 8 degrees east of north (line 43). This figure illustrates how a small deviation from an octogonal axis exaserbates the geometric distortion.

Figure 4 illustrates the ignition pattern resulting from two simultaneous ignition points. This was acheived by changing line 125 and inserting two new statements after line 26:

125 cell = Cols/3 + Cols*(Rows/4);

126a cell = 2*Cols/3 + Cols*(Rows/4);

126b ignMap[cell] = 1.0;

In figure 5 the two initial ignitions points by are staggered by100 minutes by changing line 126b:

126b ignMap[cell] = 100.0;

In figure 6 the fire burns around a fuel break spanning the middle 80% of the fuel array's central meridian. The fuel break was created by inserting the following statements after line 122:

122a

122b for ( cell=Cols*(Rows/2)+Cols/10, col=Cols/10; col<Cols-Cols-10; col++, cell++)

122c fuelMap[cell] = 0;

The burning pattern in an array of randomly assigned fuels is shown in figure 7. This effect was accomplished by changing line 110:

110 fuelMap[cell] = rand()%14;

7. Validation and Performance

The fireLib outputs were compared with BEHAVE outputs over a wide range of input variables and were found to be in agreement within 1 part in 10000.

The example fire growth simulator listed in Appendix A was used to test fireLib performance on a variety of computer-operating system-compiler configurations.

8. Availability and Licensing

8.1 Distribution

The fireLib distribution may be obtained by downloading the SEM home page at www.montana.com/sem or by FTP from ftp.montana.com/sem. Included in the distribution are:

CHANGES documents any changes in fireLib distribution

fireLib.c fireLib source code file

fireLib.h fireLib header file

fireLib.ps fireLib manual in Postscript (tm) format

fireSim.c the example fire simulator source code

license.txt fireLib license terms

makefile make file to create the exdample fireSim program

README latest information on fireLib installation and updates

Each version of the fireLib distribution is compressed into a single file and labeled with the version number. You have a choice of three compression schemes when downloading the distribution; gzipped tar Unix text or zipped DOS text. For example, firelib-1.0.0.tar.gz and firelib-1.0.0.zip both contain the initial distribution. The first version featuring bug fixes will appear as firelib-1.0.1.tar.gz and firelib-1.0.1.zip. The first version featuring new capabilities will appear as firelib-1.1.0.tar.gz and firelib-1.1.0.zip.

8.2 Bugs

Send bug reports to cbevins@montana.com. Please send a working example of the code that causes the error; I can only fix the error if I am able to duplicate it.

8.3 Licensing

The fireLib library is copyrighted © by Collin D. Bevins. The file license.txt contains the entire license agreement, and is reproduced below:

Collin D. Bevins

Systems for Environmental Management

315 South Fourth East

P.O. Box 8868

Missoula, MT 59807

cbevins@montana.com

(406) 549-7478 or (406) 728-7130

This software (hereafter, Software) is copyrighted by Collin D. Bevins (hereafter, Grantor) and other parties. The following terms apply to all files associated with the software, including but not limited to source, binary, documentation, and data files, unless explicitly disclaimed in individual files.

The Grantor hereby grants you (hereafter, Licensee) a license to use the Software for academic, research, and internal business purposes only, without a fee. Licensee may distribute the Software to third parties provided that the copyright notice and this statement appears verbatim on all copies and that no charge is associated with such copies.

Licensee may make derivative works. However, if Licensee distributes any derivative work based on or derived from the Software, then the Licensee will (1) notify the Grantor regarding its distribution of the derivative work, and (2) clearly notify users that such derivative work is a modified version and not the original Software distributed by the Grantor.

Any Licensee wishing to make commercial use of the Software should contact the Grantor to negotiate an appropriate license for such commercial use. Commercial use includes (1) integration of all or part of the source code into a product for sale or license by or on behalf of the Licensee to third parties, or (2) distribution of the binary or source code to third parties that need it to utilize a commercial product sold or licensed by or on behalf of the Licensee.

IN NO EVENT SHALL THE GRANTOR, AUTHORS, OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE GRANTOR, AUTHORS, OR DISTRIBUTORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE GRANTOR, AUTHORS, AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE GRANTOR, AUTHORS, AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

IT IS THE LICENSEE'S RESPONSIBILITY TO ASSURE THAT THIS SOFTWARE AND DOCUMENTATION IS ADEQUATE FOR THE USER'S PURPOSE, AND IS USED IN A SAFE AND RESPONSIBLE MANNER.

By using or copying this Software, the Licensee agree to abide by the copyright law and all other applicable laws of the U.S. including, but not limited to, export control laws, and the terms of this license. The Grantor shall have the right to terminate this license immediately by written notice upon Licensee's breach of, or non-compliance with, any of its terms. Licensee may be held legally responsible for any copyright infringement that is caused or encouraged by Licensee's failure to abide by the terms of this license.

RESTRICTED RIGHTS: Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause as DFARS 252.227-7013 and FAR 52.227-19.

9. Selected References

Albini, Frank A. Estimating wildland fire behavior and effects. General Technical Report INT-30. Ogden,UT: U.S. Department of Agriculture, Forest Service, Intermountain Forest and Range Experiment Station; 1976a. 92 p.

Albini, Frank A. Computer based models of wildland fire behavior: a user's manual. Ogden,UT: U.S. Department of Agriculture, Forest Service, Intermountain Forest and Range Experiment Station; 1976b. 68 p.

Anderson, Hal E. Predicting wind-driven wildland fire size and shape. Research Paper INT-305. Ogden,UT: U.S. Department of Agriculture, Forest Service, Intermountain Forest and Range Experiment Station; 1983. 26 p.

Andrews, Patricia L. BEHAVE: fire behavior prediction and fuel modeling system - BURN Subsystem, part 1. General Technical Report INT-194. Ogden, UT: U.S. Department of Agriculture, Forest Service, Intermountain Research Station; 1986. 130 p.

Finney, Mark A. Modeling the spread and behavior of prescribed natural fires. In Proceedings of the 12th Conference on Fire and Forest Meteorology: 138-14; 1994.

Finney, Mark A. And Patricia L. Andrews The FARSITE fire area simulator: fire management applications and lessons of summer 1994. Interior West Fire Council Meeting and Symposium; Coeur d'Alene, ID; 1994.

French, Ian A. Visualisation techniques for the computer simulation of bushfires in two dimensions. M.S. Thesis, University of New South Wales, Australian Defense Force Academy; 1992.

Kourtz, Peter S and W. G. O"Reagan. A model for a small forest fire to simulate burned and burning area for use in a detection model. Forestry Science 17(2): 163-169.

Richards, G. D. An elliptical growth model of forest fire fronts and its numerical solution. Int. J. Numer. Meth. Eng. 30: 1163-1179; 1990.

Rothermel, Richard C. A mathematical model for predicting fire spread in wildland fuels. Research Paper INT-115. Ogden,UT: U.S. Department of Agriculture, Forest Service, Intermountain Forest and Range Experiment Station; 1972. 40 p.

Rothermel, Richard C. How to predict the spread and intensity of forets and range fires. General Technical Report INT-143. Ogden, UT: U.S. Department of Agriculture, Forest Service, Intermountain Forest and Range Research Station; 1983. 161 p.

Rothermel, Richard C. Predicting behavior and size of crown fires in the northern Rocky Mountains. Research Paper INT-438. Ogden,UT: U.S. Department of Agriculture, Forest Service, Intermountain Forest and Range Experiment Station; 1991.

10. Function Reference

This section contains the technical reference to all fireLib functions. Each reference includes the following information:

Signature:

The ANSI standard C function declaration and required header files.

Arguments:

A description of each function argument and, when appropriate, its units of measure.

Returns:

The function return type and return codes.

Description:

A narrative of the function's purpose and operation.

Side Effects:

Lists all objects that are created or destroyed and all object properties that are updated.

Error Messages:

Lists error messages that may appear in the FuelCat_Error property if the function returns an error condition.

See Also:

Lists related functions.

Fire_FlameLengthTable()

Signature:

#include <fireLib.h>

int Fire_FlameLengthTable (

FuelCatalogPtr catalog,

size_t flameClasses,

double flameStep )

Arguments:

catalog Fuel catalog handle returned by Fire_FuelCatalogCreate()or Fire_FuelCatalogCreateStandard().

flameClasses Number of classes within the table or 0 to delete an existing table.

flameStep Size of each flame class in feet. The first flame class covers zero through flameStep feet.

Returns:

FIRE_STATUS_OK on success, FIRE_STATUS_ERROR on failure.

Description:

Fire_FlameLengthTable() creates a flame length look up table for catalog. In the absence of this table, Fire_SpreadAtAzimuth() and Fire_FlameScorch() calculate flame lengths using the BEHAVE equations, which use the pow() function and can consume most of the computation time in some applications. Defining a flame length table may improve performance by forcing these functions to look up rather than calculate flame length.

The flame length table is redefined by calls to Fire_FlameLengthTable() using new values for flameClasses and flameStep. Any existing flame length table is destroyed by calling this function with a flameClasses value of zero, after which all flame lengths are again calculated.

Side Effects:

Any existing flame length table is destroyed.

FuelCat_FlameArray(c) property is set to NULL.

FuelCat_FlameClasses(c) and FuelCat_FlameStep(c) properties set to zero.

If flameClasses is zero, returns FIRE_STATUS_OK.

Allocates a new flame length table pointed to by FuelCat_FlameArray(c) property.

FuelCat_FlameClasses(c) property set to flameClasses.

FuelCat_FlameStep(c) property set to flameStep.

Error Messages:

Fire_FlameLengthTable(): unable to allocate flame length table with <flameClasses> classes of <flameStep> feet.

Examples:

To create a flame length table with 200 1-foot flame length classes:

Fire_FlameLengthTable(catalog, 200, 1.0);

To destroy the above table and create a new table with 500 6-inch classes ranging from 0.5 through 250 feet:

Fire_FlameLengthTable(catalog, 500, 0.5);

To destroy any existing flame length table and force direct calculation of flame lengths:

Fire_FlameLengthTable(catalog, 0, 0.);

See Also:

Fire_SpreadAtAzimuth(), Fire_FlameScorch().

Fire_FlameScorch()

Signature:

#include <fireLib.h>

int Fire_FlameScorch (

FuelCatalogPtr catalog,

size_t modelNumber,

size_t whichOutputs )

Arguments:

catalog Fuel catalog handle returned by Fire_FuelCatalogCreate()or Fire_FuelCatalogCreateStandard().

modelNumber Fuel model number.

whichOutputs Flag indicating which fire behavior outputs to calculate. Specify this argument by OR'ing together FIRE_FLAME and/or FIRE_SCORCH.

Returns:

FIRE_STATUS_OK on success, FIRE_STATUS_ERROR on failure.

Description:

Fire_FlameScorch() determines the flame length and/or scorch height along the azimuth established by the most recent call to Fire_SpreadAtAzimuth(). It is provided for those cases where it is faster to call Fire_SpreadAtAzimuth() without flame length or scorch height computations, and then later ask for these values.

If a flame length table has been defined for catalog via a previous call to Fire_FlameLengthTable(), it is used to look up the flame length. Otherwise, flame lengths are calculated directly.

Side Effects:

Fuel_FlameLength(c,m) updated if whichOutputs includes FIRE_FLAME.

Fuel_ScorchHeight(c,m) updated if whichOutputs includes FIRE_SCORCH.

Error Messages:

Fire_FlameScorch(): fuel model <modelNumber> doesn't exist in fuel catalog <catalogName>.

See Also:

Fire_FlameLengthTable().

Fire_FuelCatalogCreate()

Signature:

#include <fireLib.h>

FuelCatalogPtr Fire_FuelCatalogCreate (

char *catalogName,

size_t maxModels )

Arguments:

catalogName A unique name assigned to this fuel catalog.

maxModels Maximum fuel model number allowed in this catalog.

Returns:

Returns a non-NULL handle (FuelCatalogPtr) on success, NULL on failure.

Description:

Fire_FuelCatalogCreate() creates a new fuel catalog object capable of holding maxModels+1 fuel models (e.g., fuel models numbered 0 through maxModels). The fuel catalog contains no fuel models until they are defined by subsequent calls to Fire_FuelModelCreate().

Side Effects:

Allocates a new fuel catalog object referenced by the returned catalog handle.

FuelCat_MagicCookie(c) property initialized.

FuelCat_Name(c) property set to catalogName.

FuelCat_MaxModels(c) property set to maxModels+1.

Allocates a catalog error buffer pointed to by FuelCat_Error(c) property.

Allocates an array of fuel model object pointers pointed to by FuelCat_ModelArray(c) property.

FuelCat_FlameArray(c) property set to NULL.

FuelCat_FlameClasses(c)property initialized to zero.

FuelCat_FlameStep(c) property initialized to zero.

FuelCat_Status(c) property initialized to zero.

Error Messages:

All error messages are printed to stderr. Since a NULL return indicates that the fuel catalog object was not created, there is no error buffer for the catalog.

Fire_FuelCatalogCreate(): unable to allocate fuel catalog <catalogName> object.

Fire_FuelCatalogCreate(): unable to duplicate fuel catalog <catalogName> name.

Fire_FuelCatalogCreate(): unable to allocate fuel catalog <catalogName> error buffer.

Fire_FuelCatalogCreate(): unable to allocate fuel catalog <catalogName> with <maxModels> fuel models.

See Also:

Fire_FuelCatalogCreateStandard(), Fire_FuelModelCreate(), Fire_FuelCatalogDestroy().

Fire_FuelCatalogCreateStandard()