1 /********************************************************** 2 * Version $Id: fireLib.h 911 2011-02-14 16:38:15Z reklov_w $ 3 *********************************************************/ 4 /* 5 ******************************************************************************* 6 * 7 * fireLib.h 8 * 9 * Description 10 * Library of BEHAVE (Andrews 1986) fire behavior algorithms 11 * encapsulated and optimized for fire behavior simulation. 12 * 13 * Legalities 14 * Copyright (c) 1996 Collin D. Bevins. 15 * See the file "license.txt" for information on usage and 16 * redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES. 17 * 18 * Description 19 * This header file describes the externally-visible facilities of 20 * the Fire Behavior Library C API. 21 * 22 * This file really needs to be split into public and private portions. 23 * 24 * History 25 * 1996/09/04 Version 1.0.0 release. 26 * 1999/03/05 Fixed NNFL07 live SAVR from 1500 to 1550. 27 * 28 ******************************************************************************* 29 */ 30 31 #include <stdlib.h> 32 #include <stdio.h> 33 #include <string.h> 34 #include <math.h> 35 #include <assert.h> 36 37 #ifndef _FIRE_LIB 38 #define _FIRE_LIB 1 39 40 #define FIRELIB_VERSION "1.0" 41 #define FIRELIB_MAJOR_VERSION 1 42 #define FIRELIB_MINOR_VERSION 0 43 #define FIRELIB_PATCH_LEVEL 1 44 45 /* 46 *------------------------------------------------------------------------------ 47 * Definitions that allow this header file to be used either with or 48 * without ANSI C features like function prototypes. 49 *------------------------------------------------------------------------------ 50 */ 51 52 #undef _ANSI_ARGS_ 53 #undef CONST 54 #if ((defined(__STDC__) || defined(SABER)) && !defined(NO_PROTOTYPE)) || defined(__cplusplus) 55 # define _USING_PROTOTYPES_ 1 56 # define _ANSI_ARGS_(x) x 57 # define CONST const 58 # ifdef __cplusplus 59 # define VARARGS(first) (first, ...) 60 # else 61 # define VARARGS(first) () 62 # endif 63 #else 64 # define _ANSI_ARGS_(x) () 65 # define CONST 66 #endif 67 68 #ifdef __cplusplus 69 # define EXTERN extern "C" 70 #else 71 # define EXTERN extern 72 #endif 73 74 /* 75 *------------------------------------------------------------------------------ 76 * Macro to use instead of "void" for arguments that must have type "void *" 77 * in ANSI C; maps them to type "char *" in non-ANSI systems. 78 *------------------------------------------------------------------------------ 79 */ 80 81 #ifndef VOID 82 # ifdef __STDC__ 83 # define VOID void 84 # else 85 # define VOID char 86 # endif 87 #endif 88 89 /* 90 *------------------------------------------------------------------------------ 91 * Macro pseudo functions. 92 *------------------------------------------------------------------------------ 93 */ 94 95 #define Smidgen (0.000001) 96 #define DegreesToRadians(x) ((x)*0.017453293) 97 #define RadiansToDegrees(x) ((x)*57.29577951) 98 #define IsZero(x) (fabs(x)<Smidgen) 99 #define Equal(x,y) (fabs((x)-(y))<Smidgen) 100 101 /* 102 *------------------------------------------------------------------------------ 103 * Firelib return status codes. 104 *------------------------------------------------------------------------------ 105 */ 106 107 #define FIRE_STATUS_OK (0) 108 #define FIRE_STATUS_ERROR (-1) 109 #define FIRE_STATUS_EOF (1) 110 111 /* 112 *------------------------------------------------------------------------------ 113 * Fuel moisture and mass weighting classes. 114 *------------------------------------------------------------------------------ 115 */ 116 117 #define FIRE_LIFE_CATS (2) /* Number of fuel particle life categories */ 118 #define FIRE_LIFE_DEAD (0) 119 #define FIRE_LIFE_LIVE (1) 120 121 #define FIRE_SIZE_CLASSES (6) /* Number of mass weighting classes. */ 122 123 #define FIRE_MCLASSES (6) /* Number of fuel moisture classes. */ 124 #define FIRE_MCLASS_1HR (0) 125 #define FIRE_MCLASS_10HR (1) 126 #define FIRE_MCLASS_100HR (2) 127 #define FIRE_MCLASS_1000HR (3) 128 #define FIRE_MCLASS_HERB (4) 129 #define FIRE_MCLASS_WOOD (5) 130 131 /* 132 *------------------------------------------------------------------------------ 133 * FuelParticleData structure: fuel particle input and intermediate attributes. 134 *------------------------------------------------------------------------------ 135 */ 136 137 typedef struct fuelParticleDataStruct 138 { 139 /* INPUT */ 140 double load; /* fuel loading (lb/sqft) */ 141 double savr; /* surface area-to-volume ratio (1/ft) */ 142 double dens; /* particle density (lb/cuft) */ 143 double heat; /* heat of combustion (BTU/lb) */ 144 double stot; /* total silica content (fraction odw) */ 145 double seff; /* effective silica content (fraction odw) */ 146 /* PARTICLE_DEPENDENT */ 147 double area; /* surface area */ 148 double sigma; /* exp(-138./sigma) (dl) */ 149 /* MODEL-DEPENDENT */ 150 double awtg; /* surface area derived weighting factor (dl) */ 151 double gwtg; /* size class area weighting factor */ 152 /* ENVIRONMENT-DEPENDENT */ 153 double mois; /* particle moisture content (fraction) */ 154 size_t live; /* life category 0=dead, 1=live */ 155 size_t type; /* type category 0=dead, 1=herb, 2=live woody */ 156 size_t sizeClass; /* fuel moisture size class */ 157 } FuelParticleData, *FuelParticlePtr, *PartPtr; 158 159 #define FIRE_TYPE_DEAD (1) 160 #define FIRE_TYPE_HERB (2) 161 #define FIRE_TYPE_WOOD (3) 162 163 /* FuelParticleData structure access macros. */ 164 165 #define Fuel_Live(catalog,model,particle) \ 166 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->live) 167 168 #define Fuel_Type(catalog,model,particle) \ 169 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->type) 170 171 #define Fuel_SizeClass(catalog,model,particle) \ 172 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->sizeClass) 173 174 #define Fuel_Load(catalog,model,particle) \ 175 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->load) 176 177 #define Fuel_Savr(catalog,model,particle) \ 178 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->savr) 179 180 #define Fuel_Heat(catalog,model,particle) \ 181 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->heat) 182 183 #define Fuel_Density(catalog,model,particle) \ 184 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->dens) 185 186 #define Fuel_SiTotal(catalog,model,particle) \ 187 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->stot) 188 189 #define Fuel_SiEffective(catalog,model,particle) \ 190 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->seff) 191 192 #define Fuel_SurfaceArea(catalog,model,particle) \ 193 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->area) 194 195 #define Fuel_AreaWtg(catalog,model,particle) \ 196 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->awtg) 197 198 #define Fuel_SizeAreaWtg(catalog,model,particle) \ 199 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->gwtg) 200 201 #define Fuel_SigmaFactor(catalog,model,particle) \ 202 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->sigma) 203 204 #define Fuel_Moisture(catalog,model,particle) \ 205 ((catalog)->modelPtr[(model)]->partPtr[(particle)]->mois) 206 207 /* 208 *------------------------------------------------------------------------------ 209 * FuelModelData structure: fuel model bed input attributes. 210 *------------------------------------------------------------------------------ 211 */ 212 213 typedef struct fuelModelDataStruct 214 { 215 /* Input variables. */ 216 size_t modelId; /* fuel model number */ 217 size_t combustion; /* 0 if combustion not yet calculated */ 218 size_t maxParticles; /* maximum number of FuelParticles */ 219 size_t particles; /* current number of FuelParticles */ 220 PartPtr *partPtr; /* array of pointers to Fuel Particles */ 221 char *name; /* fuel model short name */ 222 char *desc; /* fuel model description text */ 223 char *reserved1; /* used for alignment */ 224 double depth; /* fuel bed depth (ft) */ 225 double mext; /* dead fuel extinction moisture (fraction) */ 226 double adjust; /* spread rate adjustment factor (dl) */ 227 /* Combustion intermediates. */ 228 double awtg[2]; /* dead & live fuel area weighting factors */ 229 double rxFactor[2]; /* dead and live fuel rx factors */ 230 double fineDead; /* fine dead fuel ratio */ 231 double liveFactor; /* live fuel moisture extinction factor */ 232 double rhob; /* fuel bed bulk density */ 233 double taur; /* residence time (min) */ 234 double propFlux; /* propagating flux ratio */ 235 double slopeK; /* slope parameter 'k' */ 236 double windB; /* wind parameter 'b' */ 237 double windE; /* wind parameter (ratio**e/c) */ 238 double windK; /* wind parameter (c * ratio**-e) */ 239 /* Current environment. */ 240 double moisture[FIRE_MCLASSES]; /* array of fuel moistures (fraction odw) */ 241 double windFpm; /* wind speed (ft/min) */ 242 double windDeg; /* wind vector (degrees from upslope) */ 243 double slope; /* slope (rise/reach) */ 244 double aspect; /* aspect (downslope) azimuth (compass degs) */ 245 /* Updated by Fire_SpreadNoWindNoSlope() */ 246 double rxInt; /* reaction intensity (BTU/sqft/min) */ 247 double spread0; /* no-wind, no-slope spread rate (ft/min) */ 248 double hpua; /* heat per unit area (BTU/sqft) */ 249 /* Updated by Fire_SpreadWindSlopeMax() */ 250 double spreadMax; /* spread in direction of max spread (ft/min) */ 251 double azimuthMax; /* direction of maximum spread (degrees) */ 252 double effWind; /* effective windspeed */ 253 double lwRatio; /* length-to-width ratio for eff windspeed */ 254 double eccentricity; /* eccentricity of ellipse for eff windspeed */ 255 double phiW; /* wind factor */ 256 double phiS; /* slope factor */ 257 double phiEw; /* combined wind-slope factor */ 258 size_t wLimit; /* wind limit 0=not reached, 1=reached */ 259 size_t reserved2; /* used for alignment */ 260 /* Updated by Fire_SpreadAtAzimuth() */ 261 double spreadAny; /* spread rate at arbitrary azimuth (ft/min) */ 262 double azimuthAny; /* direction of arbitrary spread (degrees) */ 263 double byrams; /* fireline intensity (BTU/ft/s) */ 264 double flame; /* flame length (ft) */ 265 double scorch; /* scorch height (ft) */ 266 } FuelModelData, *FuelModelPtr; 267 268 /* Fuel model input variable macros. */ 269 #define Fuel_Model(catalog,model) \ 270 ((catalog)->modelPtr[(model)]->modelId) 271 272 #define Fuel_Name(catalog,model) \ 273 ((catalog)->modelPtr[(model)]->name) 274 275 #define Fuel_Desc(catalog,model) \ 276 ((catalog)->modelPtr[(model)]->desc) 277 278 #define Fuel_Depth(catalog,model) \ 279 ((catalog)->modelPtr[(model)]->depth) 280 281 #define Fuel_Mext(catalog,model) \ 282 ((catalog)->modelPtr[(model)]->mext) 283 284 #define Fuel_SpreadAdjustment(catalog,model) \ 285 ((catalog)->modelPtr[(model)]->adjust) 286 287 #define Fuel_CombustionFlag(catalog,model) \ 288 ((catalog)->modelPtr[(model)]->combustion) 289 290 #define Fuel_MaxParticles(catalog,model) \ 291 ((catalog)->modelPtr[(model)]->maxParticles) 292 293 #define Fuel_Particles(catalog,model) \ 294 ((catalog)->modelPtr[(model)]->particles) 295 296 #define Fuel_ParticleArray(catalog,model) \ 297 ((catalog)->modelPtr[(model)]->partPtr) 298 299 #define Fuel_ParticlePtr(catalog,model,particle) \ 300 ((catalog)->modelPtr[(model)]->partPtr[(particle)]) 301 302 /* Fuel model combustion intermediates macros. */ 303 #define Fuel_LifeAreaWtg(catalog,model,life) \ 304 ((catalog)->modelPtr[(model)]->awtg[(life)]) 305 306 #define Fuel_LifeRxFactor(catalog,model,life) \ 307 ((catalog)->modelPtr[(model)]->rxFactor[(life)]) 308 309 #define Fuel_FineDead(catalog,model) \ 310 ((catalog)->modelPtr[(model)]->fineDead) 311 312 #define Fuel_LiveMextFactor(catalog,model) \ 313 ((catalog)->modelPtr[(model)]->liveFactor) 314 315 #define Fuel_BulkDensity(catalog,model) \ 316 ((catalog)->modelPtr[(model)]->rhob) 317 318 #define Fuel_ResidenceTime(catalog,model) \ 319 ((catalog)->modelPtr[(model)]->taur) 320 321 #define Fuel_PropFlux(catalog,model) \ 322 ((catalog)->modelPtr[(model)]->propFlux) 323 324 #define Fuel_SlopeK(catalog,model) \ 325 ((catalog)->modelPtr[(model)]->slopeK) 326 327 #define Fuel_WindB(catalog,model) \ 328 ((catalog)->modelPtr[(model)]->windB) 329 330 #define Fuel_WindE(catalog,model) \ 331 ((catalog)->modelPtr[(model)]->windE) 332 333 #define Fuel_WindK(catalog,model) \ 334 ((catalog)->modelPtr[(model)]->windK) 335 336 /* Fuel model fire behavior variable macros. */ 337 #define Fuel_RxIntensity(catalog,model) \ 338 ((catalog)->modelPtr[(model)]->rxInt) 339 340 #define Fuel_Spread0(catalog,model) \ 341 ((catalog)->modelPtr[(model)]->spread0) 342 343 #define Fuel_HeatPerUnitArea(catalog,model) \ 344 ((catalog)->modelPtr[(model)]->hpua) 345 346 #define Fuel_SpreadMax(catalog,model) \ 347 ((catalog)->modelPtr[(model)]->spreadMax) 348 349 #define Fuel_AzimuthMax(catalog,model) \ 350 ((catalog)->modelPtr[(model)]->azimuthMax) 351 352 #define Fuel_SpreadAny(catalog,model) \ 353 ((catalog)->modelPtr[(model)]->spreadAny) 354 355 #define Fuel_AzimuthAny(catalog,model) \ 356 ((catalog)->modelPtr[(model)]->azimuthAny) 357 358 #define Fuel_EffectiveWind(catalog,model) \ 359 ((catalog)->modelPtr[(model)]->effWind) 360 361 #define Fuel_LwRatio(catalog,model) \ 362 ((catalog)->modelPtr[(model)]->lwRatio) 363 364 #define Fuel_Eccentricity(catalog,model) \ 365 ((catalog)->modelPtr[(model)]->eccentricity) 366 367 #define Fuel_PhiWind(catalog,model) \ 368 ((catalog)->modelPtr[(model)]->phiW) 369 370 #define Fuel_PhiSlope(catalog,model) \ 371 ((catalog)->modelPtr[(model)]->phiS) 372 373 #define Fuel_PhiEffWind(catalog,model) \ 374 ((catalog)->modelPtr[(model)]->phiEw) 375 376 #define Fuel_WindLimit(catalog,model) \ 377 ((catalog)->modelPtr[(model)]->wLimit) 378 379 #define Fuel_ByramsIntensity(catalog,model) \ 380 ((catalog)->modelPtr[(model)]->byrams) 381 382 #define Fuel_FlameLength(catalog,model) \ 383 ((catalog)->modelPtr[(model)]->flame) 384 385 #define Fuel_ScorchHeight(catalog,model) \ 386 ((catalog)->modelPtr[(model)]->scorch) 387 388 /* Fuel model environment variable macros. */ 389 #define Fuel_EnvMoisture(catalog,model,mclass) \ 390 ((catalog)->modelPtr[(model)]->moisture[(mclass)]) 391 392 #define Fuel_WindSpeed(catalog,model) \ 393 ((catalog)->modelPtr[(model)]->windFpm) 394 395 #define Fuel_WindDir(catalog,model) \ 396 ((catalog)->modelPtr[(model)]->windDeg) 397 398 #define Fuel_Slope(catalog,model) \ 399 ((catalog)->modelPtr[(model)]->slope) 400 401 #define Fuel_Aspect(catalog,model) \ 402 ((catalog)->modelPtr[(model)]->aspect) 403 404 /* 405 *------------------------------------------------------------------------------ 406 * FuelCatData structure; provides a complete fuel catalog. 407 *------------------------------------------------------------------------------ 408 */ 409 410 #define FIRE_CATALOG_MAGIC (19520904L) 411 #define FIRE_ERROR_BUFFER_SIZE (1024) 412 413 typedef struct fuelCatalogStruct 414 { 415 long magicCookie; /* magic cookie for sanity checking */ 416 int status; /* return status of most recent call */ 417 size_t maxModels; /* maximum number of models in this catalog */ 418 size_t flameClasses; /* size of the flame length array */ 419 char *name; /* name for this catalog instance */ 420 char *error; /* error message buffer */ 421 FuelModelPtr *modelPtr; /* array of ModelPtr[maxModels+1] */ 422 double *flamePtr; /* flame length lookup array */ 423 double flameStep; /* size of each flame length table class (ft) */ 424 } FuelCatalogData, *FuelCatalogPtr; 425 426 #define FuelCat_MagicCookie(catalog) (catalog->magicCookie) 427 #define FuelCat_MaxModels(catalog) (catalog->maxModels) 428 #define FuelCat_Status(catalog) (catalog->status) 429 #define FuelCat_FlameClasses(catalog) (catalog->flameClasses) 430 #define FuelCat_FlameStep(catalog) (catalog->flameStep) 431 #define FuelCat_FlameArray(catalog) (catalog->flamePtr) 432 #define FuelCat_Name(catalog) (catalog->name) 433 #define FuelCat_Error(catalog) (catalog->error) 434 #define FuelCat_ModelArray(catalog) (catalog->modelPtr) 435 #define FuelCat_ModelPtr(catalog,model) (catalog->modelPtr[model]) 436 437 /* 438 *------------------------------------------------------------------------------ 439 * Function prototypes for fire behavior computations. 440 *------------------------------------------------------------------------------ 441 */ 442 443 #define FIRE_NONE (0) 444 #define FIRE_BYRAMS (1) 445 #define FIRE_FLAME (2) 446 #define FIRE_SCORCH (4) 447 448 EXTERN int Fire_FlameScorch _ANSI_ARGS_(( 449 FuelCatalogPtr catalog, /* FuelCatalogData instance pointer */ 450 size_t model, /* fuel model number [0-maxModels] */ 451 size_t doWhich /* FIRE_NONE | FIRE_BYRAMS | FIRE_FLAME | FIRE_SCORCH */ 452 )) ; 453 454 EXTERN int Fire_FuelCombustion _ANSI_ARGS_(( 455 FuelCatalogPtr catalog, /* FuelCatalogData instance pointer */ 456 size_t model /* fuel model number [0-maxModels] */ 457 )) ; 458 459 EXTERN int Fire_SpreadNoWindNoSlope _ANSI_ARGS_(( 460 FuelCatalogPtr catalog, /* FuelCatalogData instance pointer */ 461 size_t model, /* fuel model number [0-maxModels] */ 462 double moisture[FIRE_MCLASSES] /* array of fuel moistures (fractions) */ 463 )) ; 464 465 EXTERN int Fire_SpreadWindSlopeMax _ANSI_ARGS_(( 466 FuelCatalogPtr catalog, /* FuelCatalogData instance pointer */ 467 size_t model, /* fuel model number [0-maxModels] */ 468 double windFpm, /* wind speed (ft/min) */ 469 double windDeg, /* wind bearing vector (compass degs) */ 470 double slope, /* slope (rise/reach) */ 471 double aspect /* aspect (downslope) azimuth (compass degs) */ 472 )) ; 473 474 EXTERN int Fire_SpreadAtAzimuth _ANSI_ARGS_(( 475 FuelCatalogPtr catalog, /* FuelCatalogData instance pointer */ 476 size_t model, /* fuel model number [0-maxModels] */ 477 double azimuth, /* fire spread azimuth (deg from upslope) */ 478 size_t doWhich /* FIRE_NONE | FIRE_BYRAMS | FIRE_FLAME | FIRE_SCORCH */ 479 )) ; 480 481 /* 482 *------------------------------------------------------------------------------ 483 * Function prototypes for creating and destroying fuel catalogs, fuel models, 484 * fuel particles, and flame length tables. 485 *------------------------------------------------------------------------------ 486 */ 487 488 EXTERN int Fire_FlameLengthTable _ANSI_ARGS_(( 489 FuelCatalogPtr catalog, /* FuelCatalogData instance pointer */ 490 size_t flameClasses, /* number of flame length classes */ 491 double flameStep /* flame length step value per class */ 492 )) ; 493 494 EXTERN FuelCatalogPtr Fire_FuelCatalogCreate _ANSI_ARGS_(( 495 char *name, /* FuelCatalogData instance name */ 496 size_t maxModels /* maximum modelId allowed in this catalog */ 497 )) ; 498 499 EXTERN FuelCatalogPtr Fire_FuelCatalogCreateStandard _ANSI_ARGS_(( 500 char *name, /* FuelCatalogData instance name */ 501 size_t maxModels /* maximum modelId allowed in this catalog */ 502 )) ; 503 504 EXTERN int Fire_FuelCatalogDestroy _ANSI_ARGS_(( 505 FuelCatalogPtr catalog /* FuelCatalogData instance pointer */ 506 )) ; 507 508 EXTERN int Fire_FuelModelCreate _ANSI_ARGS_(( 509 FuelCatalogPtr catalog, /* FuelCatalogData instance */ 510 size_t model, /* fuel model number [0-maxModels] */ 511 char *name, /* short name */ 512 char *desc, /* longer description */ 513 double depth, /* bed depth (ft) */ 514 double mext, /* moisture of extinction (dl) */ 515 double adjust, /* spread adjustment factor (dl) */ 516 size_t maxParticles /* maximum number of fuel model particles */ 517 )) ; 518 519 EXTERN int Fire_FuelModelDestroy _ANSI_ARGS_(( 520 FuelCatalogPtr catalog, /* FuelCatalogData instance pointer */ 521 size_t model /* fuel model id number [0-maxModels] */ 522 )) ; 523 524 EXTERN int Fire_FuelModelExists _ANSI_ARGS_(( 525 FuelCatalogPtr catalog, /* FuelCatalogData instance pointer */ 526 size_t model /* fuel model id number [0-maxModels] */ 527 )) ; 528 529 EXTERN int Fire_FuelParticleAdd _ANSI_ARGS_(( 530 FuelCatalogPtr catalog, /* FuelCatalogData instance pointer */ 531 size_t model, /* fuel model id number [0-maxModels] */ 532 size_t type, /* FIRE_TYPE_DEAD, _TYPE_HERB, or _TYPE_WOOD */ 533 double load, /* fuel load (lbs/ft2) */ 534 double savr, /* surface-area-to-volume ratio (ft2/ft3) */ 535 double dens, /* density (lbs/ft3) */ 536 double heat, /* heat of combustion (btus/lb) */ 537 double stot, /* total silica content (lb/lb) */ 538 double seff /* effective silica content (lb/lb) */ 539 )) ; 540 541 #ifdef NEED_STRDUP 542 char *strdup ( const char *str ) ; 543 #endif 544 545 #endif 546 547 /* 548 ******************************************************************************* 549 * End of fireLib.h 550 ******************************************************************************* 551 */ 552