FireSTARR
Loading...
Searching...
No Matches
FuelType.h
1/* SPDX-License-Identifier: AGPL-3.0-or-later */
2#ifndef FS_FUELTYPE_H
3#define FS_FUELTYPE_H
4#include "stdafx.h"
5#include "Duff.h"
6#include "FireSpread.h"
7#include "FWI.h"
8namespace fs
9{
10using duff::Duff;
11// References
12// Forestry Canada
13// Development and Structure of the Canadian Forest Fire Behaviour Prediction System (ST-X-3)
14// https://cfs.nrcan.gc.ca/pubwarehouse/pdfs/10068.pdf
15//
16// Wotton, B.M., Alexander, M.E., Taylor, S.W.
17// Updates and revision to the 1992 Canadian Forest Fire Behavior Prediction System (GLC-X-10)
18// https://cfs.nrcan.gc.ca/pubwarehouse/pdfs/31414.pdf
19//
20// Anderson, Kerry
21// Incorporating Smoldering Into Fire Growth Modelling
22// https://www.cfs.nrcan.gc.ca/pubwarehouse/pdfs/19950.pdf
23//
24// default grass fuel load (kg/m^2)
25static constexpr MathSize DEFAULT_GRASS_FUEL_LOAD = 0.35;
26// amount of duff to apply ffmc moisture to (cm) (1.2 cm is from Kerry's paper)
27static constexpr MathSize DUFF_FFMC_DEPTH = 1.2;
34[[nodiscard]] constexpr MathSize fire_intensity(const MathSize fc, const MathSize ros)
35{
36 return 300.0 * fc * ros;
37}
42{
43public:
47 [[nodiscard]] virtual bool isValid() const = 0;
53 [[nodiscard]] static constexpr FuelCodeSize safeCode(const FuelType* fuel)
54 {
55 return nullptr == fuel ? static_cast<FuelCodeSize>(INVALID_FUEL_CODE) : fuel->code();
56 }
62 [[nodiscard]] static constexpr const char* safeName(const FuelType* fuel)
63 {
64 return nullptr == fuel ? "NULL" : fuel->name();
65 }
72 [[nodiscard]] static constexpr MathSize criticalRos(const MathSize sfc, const MathSize csi)
73 {
74 return sfc > 0 ? csi / (300.0 * sfc) : 0.0;
75 }
82 [[nodiscard]] static constexpr bool isCrown(const MathSize csi, const MathSize sfi)
83 {
84 return sfi > csi;
85 }
90 [[nodiscard]] virtual MathSize cfl() const = 0;
91 virtual ~FuelType() noexcept = default;
98 constexpr FuelType(const FuelCodeSize& code, const char* name, const bool can_crown) noexcept
99 : name_(name), can_crown_(can_crown), code_(code)
100 { }
101 FuelType(FuelType&& rhs) noexcept = delete;
102 FuelType(const FuelType& rhs) noexcept = delete;
103 FuelType& operator=(FuelType&& rhs) noexcept = delete;
104 FuelType& operator=(const FuelType& rhs) noexcept = delete;
109 [[nodiscard]] constexpr bool canCrown() const { return can_crown_; }
114 [[nodiscard]] virtual MathSize grass_curing(const int, const FwiWeather&) const
115 {
116 // NOTE: grass overrides this but everything else doesn't have curing
117 return INVALID_CURING;
118 }
123 [[nodiscard]] virtual MathSize cbh() const = 0;
130 [[nodiscard]] virtual MathSize crownFractionBurned(MathSize rss, MathSize rso) const noexcept = 0;
136 [[nodiscard]] virtual MathSize probabilityPeat(MathSize mc_fraction) const noexcept = 0;
143 [[nodiscard]] virtual ThresholdSize survivalProbability(const FwiWeather& wx) const noexcept = 0;
149 [[nodiscard]] virtual MathSize buiEffect(MathSize bui) const = 0;
155 [[nodiscard]] virtual MathSize crownConsumption(MathSize cfb) const = 0;
163 [[nodiscard]] virtual MathSize calculateRos(int nd, const FwiWeather& wx, MathSize isi) const = 0;
170 [[nodiscard]] virtual MathSize calculateIsf(const SpreadInfo& spread, MathSize isi) const = 0;
176 [[nodiscard]] virtual MathSize surfaceFuelConsumption(const SpreadInfo& spread) const = 0;
182 [[nodiscard]] virtual MathSize lengthToBreadth(MathSize ws) const = 0;
191 [[nodiscard]] virtual MathSize finalRos(
192 const SpreadInfo& spread,
193 MathSize isi,
194 MathSize cfb,
195 MathSize rss
196 ) const = 0;
202 [[nodiscard]] virtual MathSize criticalSurfaceIntensity(const SpreadInfo& spread) const = 0;
207 [[nodiscard]] constexpr const char* name() const { return name_; }
212 [[nodiscard]] constexpr FuelCodeSize code() const { return code_; }
213
214private:
218 const char* name_{nullptr};
222 const bool can_crown_;
226 FuelCodeSize code_;
227};
234template <int BulkDensity, int InorganicPercent, int DuffDepth>
235class FuelBase : public FuelType
236{
237public:
238 ~FuelBase() override = default;
247 constexpr FuelBase(
248 const FuelCodeSize& code,
249 const char* name,
250 const bool can_crown,
251 const Duff* duff_ffmc,
252 const Duff* duff_dmc
253 )
254 : FuelType(code, name, can_crown), duff_ffmc_(duff_ffmc), duff_dmc_(duff_dmc)
255 { }
256 FuelBase(FuelBase&& rhs) noexcept = delete;
257 FuelBase(const FuelBase& rhs) = delete;
258 FuelBase& operator=(FuelBase&& rhs) noexcept = delete;
259 FuelBase& operator=(const FuelBase& rhs) = delete;
263 [[nodiscard]] bool isValid() const override { return true; }
270 [[nodiscard]] MathSize crownFractionBurned(const MathSize rss, const MathSize rso)
271 const noexcept override
272 {
273 // can't burn crown if it doesn't exist
274 return cfl() > 0 ? max(0.0, 1.0 - exp(-0.230 * (rss - rso))) : 0.0;
275 }
281 [[nodiscard]] ThresholdSize probabilityPeat(const MathSize mc_fraction) const noexcept override
282 {
283 // Anderson table 1
284 constexpr auto pb = bulkDensity();
285 // Anderson table 1
286 constexpr auto fi = inorganicPercent();
287 constexpr auto pi = fi * pb;
288 // Inorganic ratio
289 constexpr auto ri = fi / (1 - fi);
290 constexpr auto const_part = -19.329 + 1.7170 * ri + 23.059 * pi;
291 // Anderson eq 1
292 return 1 / (1 + exp(17.047 * mc_fraction / (1 - fi) + const_part));
293 }
300 [[nodiscard]] ThresholdSize survivalProbability(const FwiWeather& wx) const noexcept override
301 {
302 // divide by 100 since we need moisture ratio
303 // IFERROR(((1 / (1 + EXP($G$43 + $I$43 *
304 // (Q$44 * $O$43 + $N$43)))) -
305 // (1 / (1 + EXP($G$43 + $I$43 * (2.5 * $O$43 + $N$43)))))
306 // / (1 / (1 + EXP($G$43 + $I$43 * $N$43))), 0)
307 // HACK: use same constants for all fuels because they seem to work nicer than
308 // using the ratios, but they change anyway because of the other fuel attributes
309 static const auto WFfmc = 0.25;
310 static const auto WDmc = 1.0;
311 static const auto RatioHartford = 0.5;
312 static const auto RatioFrandsen = 1.0 - RatioHartford;
313 static const auto RatioAspen = 0.5;
314 static const auto RatioFuel = 1.0 - RatioAspen;
315 const auto mc_ffmc = wx.mcFfmc() * WFfmc + WDmc;
316 static const auto McFfmcSaturated = 2.5 * WFfmc + WDmc;
317 static const auto McDmc = WDmc;
318 const auto prob_ffmc_peat = probabilityPeat(mc_ffmc);
319 const auto prob_ffmc_peat_saturated = probabilityPeat(McFfmcSaturated);
320 const auto prob_ffmc_peat_zero = probabilityPeat(McDmc);
321 const auto prob_ffmc_peat_weighted =
322 (prob_ffmc_peat - prob_ffmc_peat_saturated) / prob_ffmc_peat_zero;
323 const auto prob_ffmc = duffFfmcType()->probabilityOfSurvival(mc_ffmc * 100);
324 const auto prob_ffmc_saturated = duffFfmcType()->probabilityOfSurvival(McFfmcSaturated * 100);
325 const auto prob_ffmc_zero = duffFfmcType()->probabilityOfSurvival(McDmc);
326 const auto prob_ffmc_weighted = (prob_ffmc - prob_ffmc_saturated) / prob_ffmc_zero;
327 const auto term_otway = exp(-3.11 + 0.12 * wx.dmc.value);
328 const auto prob_otway = term_otway / (1 + term_otway);
329 const auto mc_pct = wx.mcDmcPct() * dmcRatio() + wx.mcFfmcPct() * ffmcRatio();
330 const auto prob_weight_ffmc = duffFfmcType()->probabilityOfSurvival(mc_pct);
331 const auto prob_weight_ffmc_peat = probabilityPeat(mc_pct / 100);
332 const auto prob_weight_dmc = duffDmcType()->probabilityOfSurvival(wx.mcDmcPct());
333 const auto prob_weight_dmc_peat = probabilityPeat(wx.mcDmc());
334 // chance of survival is 1 - chance of it not surviving in every fuel
335 const auto tot_prob =
336 1
337 - (1 - prob_ffmc_peat_weighted) * (1 - prob_ffmc_weighted)
338 * ((1 - prob_otway) * RatioAspen + ((1 - prob_weight_ffmc_peat) * RatioHartford + (1 - prob_weight_ffmc) * RatioFrandsen) * ((1 - prob_weight_dmc_peat) * RatioHartford + (1 - prob_weight_dmc) * RatioFrandsen) * RatioFuel);
339 return tot_prob;
340 }
345 [[nodiscard]] static constexpr MathSize bulkDensity() { return BulkDensity / 1000.0; }
350 [[nodiscard]] static constexpr MathSize inorganicPercent() { return InorganicPercent / 100.0; }
355 [[nodiscard]] static constexpr MathSize duffDepth() { return DuffDepth / 10.0; }
360 [[nodiscard]] constexpr const Duff* duffDmcType() const { return duff_dmc_; }
365 [[nodiscard]] constexpr const Duff* duffFfmcType() const { return duff_ffmc_; }
370 [[nodiscard]] static constexpr MathSize ffmcRatio() { return 1 - dmcRatio(); }
375 [[nodiscard]] static constexpr MathSize dmcRatio()
376 {
377 return (duffDepth() - DUFF_FFMC_DEPTH) / duffDepth();
378 }
379
380private:
384 const Duff* duff_ffmc_{nullptr};
388 const Duff* duff_dmc_{nullptr};
389};
393class InvalidFuel final : public FuelType
394{
395public:
396 InvalidFuel() noexcept : InvalidFuel(0, nullptr) { }
402 constexpr InvalidFuel(const FuelCodeSize& code, const char* name) noexcept
403 : FuelType(code, name, false)
404 { }
405 ~InvalidFuel() override = default;
406 InvalidFuel(const InvalidFuel& rhs) noexcept = delete;
407 InvalidFuel(InvalidFuel&& rhs) noexcept = delete;
408 InvalidFuel& operator=(const InvalidFuel& rhs) noexcept = delete;
409 InvalidFuel& operator=(InvalidFuel&& rhs) noexcept = delete;
413 [[nodiscard]] bool isValid() const override { return false; }
418 [[nodiscard]] MathSize grass_curing(const int nd, const FwiWeather& wx) const override;
423 [[nodiscard]] MathSize cbh() const override;
428 [[nodiscard]] MathSize cfl() const override;
433 [[nodiscard]] MathSize buiEffect(MathSize) const override;
438 [[nodiscard]] MathSize crownConsumption(MathSize) const override;
443 [[nodiscard]] MathSize calculateRos(int, const FwiWeather&, MathSize) const override;
448 [[nodiscard]] MathSize calculateIsf(const SpreadInfo&, MathSize) const override;
453 [[nodiscard]] MathSize surfaceFuelConsumption(const SpreadInfo&) const override;
458 [[nodiscard]] MathSize lengthToBreadth(MathSize) const override;
463 [[nodiscard]] MathSize finalRos(const SpreadInfo&, MathSize, MathSize, MathSize) const override;
468 [[nodiscard]] MathSize criticalSurfaceIntensity(const SpreadInfo&) const override;
473 [[nodiscard]] MathSize crownFractionBurned(MathSize, MathSize) const noexcept override;
478 [[nodiscard]] ThresholdSize probabilityPeat(MathSize) const noexcept override;
483 [[nodiscard]] ThresholdSize survivalProbability(const FwiWeather&) const noexcept override;
484};
485}
486#endif
Base class for all FuelTypes.
Definition FuelType.h:236
constexpr const Duff * duffDmcType() const
Type of duff deeper underground.
Definition FuelType.h:360
const Duff * duff_dmc_
Type of duff deeper underground.
Definition FuelType.h:388
static constexpr MathSize dmcRatio()
What fraction of the duff layer should use DMC to determine moisture.
Definition FuelType.h:375
constexpr FuelBase(const FuelCodeSize &code, const char *name, const bool can_crown, const Duff *duff_ffmc, const Duff *duff_dmc)
Constructor.
Definition FuelType.h:247
constexpr const Duff * duffFfmcType() const
Type of duff near the surface.
Definition FuelType.h:365
static constexpr MathSize ffmcRatio()
What fraction of the duff layer should use FFMC to determine moisture.
Definition FuelType.h:370
MathSize crownFractionBurned(const MathSize rss, const MathSize rso) const noexcept override
Crown Fraction Burned (CFB) [ST-X-3 eq 58].
Definition FuelType.h:270
ThresholdSize survivalProbability(const FwiWeather &wx) const noexcept override
Survival probability calculated using probability of ony survival based on multiple formulae.
Definition FuelType.h:300
static constexpr MathSize duffDepth()
DuffDepth Depth of Duff layer (cm) [Anderson table 1].
Definition FuelType.h:355
bool isValid() const override
Is fuel a valid fuel type.
Definition FuelType.h:263
static constexpr MathSize inorganicPercent()
Inorganic Percent (% / 100) [Anderson table 1].
Definition FuelType.h:350
static constexpr MathSize bulkDensity()
Duff Bulk Density (kg/m^3) [Anderson table 1].
Definition FuelType.h:345
ThresholdSize probabilityPeat(const MathSize mc_fraction) const noexcept override
Calculate probability of burning [Anderson eq 1].
Definition FuelType.h:281
const Duff * duff_ffmc_
Type of duff near the surface.
Definition FuelType.h:384
An FBP fuel type.
Definition FuelType.h:42
virtual MathSize lengthToBreadth(MathSize ws) const =0
Length to Breadth ratio [ST-X-3 eq 79].
constexpr FuelCodeSize code() const
Code for this fuel type.
Definition FuelType.h:212
static constexpr MathSize criticalRos(const MathSize sfc, const MathSize csi)
Critical rate of spread (m/min)
Definition FuelType.h:72
virtual bool isValid() const =0
Is fuel a valid fuel type.
const bool can_crown_
Whether or not this fuel can have a crown fire.
Definition FuelType.h:222
virtual MathSize cfl() const =0
Crown fuel load (kg/m^2) [ST-X-3 table 8].
virtual MathSize criticalSurfaceIntensity(const SpreadInfo &spread) const =0
Critical Surface Fire Intensity (CSI) [ST-X-3 eq 56].
virtual MathSize surfaceFuelConsumption(const SpreadInfo &spread) const =0
Surface fuel consumption (SFC) (kg/m^2) [ST-X-3 eq 9-25].
constexpr bool canCrown() const
Whether or not this fuel can have a crown fire.
Definition FuelType.h:109
virtual MathSize crownFractionBurned(MathSize rss, MathSize rso) const noexcept=0
Crown Fraction Burned (CFB) [ST-X-3 eq 58].
static constexpr bool isCrown(const MathSize csi, const MathSize sfi)
Whether or not this is a crown fire.
Definition FuelType.h:82
virtual MathSize crownConsumption(MathSize cfb) const =0
Crown Fuel Consumption (CFC) (kg/m^2) [ST-X-3 eq 66].
constexpr const char * name() const
Name of the fuel.
Definition FuelType.h:207
static constexpr const char * safeName(const FuelType *fuel)
Convert FuelType to its name, or 0 if nullptr.
Definition FuelType.h:62
static constexpr FuelCodeSize safeCode(const FuelType *fuel)
Convert FuelType to its code, or 0 if nullptr.
Definition FuelType.h:53
virtual MathSize buiEffect(MathSize bui) const =0
BUI Effect on surface fire rate of spread [ST-X-3 eq 54].
virtual MathSize finalRos(const SpreadInfo &spread, MathSize isi, MathSize cfb, MathSize rss) const =0
Final rate of spread (m/min)
virtual MathSize grass_curing(const int, const FwiWeather &) const
Grass curing.
Definition FuelType.h:114
FuelCodeSize code_
Code to identify fuel with.
Definition FuelType.h:226
virtual MathSize calculateRos(int nd, const FwiWeather &wx, MathSize isi) const =0
Calculate rate of spread (m/min)
virtual ThresholdSize survivalProbability(const FwiWeather &wx) const noexcept=0
Survival probability calculated using probability of ony survival based on multiple formulae.
virtual MathSize cbh() const =0
Crown base height (m) [ST-X-3 table 8].
virtual MathSize probabilityPeat(MathSize mc_fraction) const noexcept=0
Calculate probability of burning [Anderson eq 1].
const char * name_
Name of the fuel.
Definition FuelType.h:218
constexpr FuelType(const FuelCodeSize &code, const char *name, const bool can_crown) noexcept
Fuel type.
Definition FuelType.h:98
virtual MathSize calculateIsf(const SpreadInfo &spread, MathSize isi) const =0
Calculate ISI with slope influence and zero wind (ISF) [ST-X-3 eq 41/42].
Placeholder fuel that throws exceptions if it ever gets used.
Definition FuelType.h:394
MathSize calculateRos(int, const FwiWeather &, MathSize) const override
Throw a runtime_error.
Definition FuelType.cpp:20
ThresholdSize survivalProbability(const FwiWeather &) const noexcept override
Throw a runtime_error.
Definition FuelType.cpp:52
MathSize crownConsumption(MathSize) const override
Throw a runtime_error.
Definition FuelType.cpp:16
ThresholdSize probabilityPeat(MathSize) const noexcept override
Throw a runtime_error.
Definition FuelType.cpp:48
constexpr InvalidFuel(const FuelCodeSize &code, const char *name) noexcept
Placeholder fuel that throws exceptions if it ever gets used.
Definition FuelType.h:402
MathSize finalRos(const SpreadInfo &, MathSize, MathSize, MathSize) const override
Throw a runtime_error.
Definition FuelType.cpp:36
MathSize calculateIsf(const SpreadInfo &, MathSize) const override
Throw a runtime_error.
Definition FuelType.cpp:24
MathSize lengthToBreadth(MathSize) const override
Throw a runtime_error.
Definition FuelType.cpp:32
MathSize crownFractionBurned(MathSize, MathSize) const noexcept override
Throw a runtime_error.
Definition FuelType.cpp:44
MathSize cbh() const override
Throw a runtime_error.
Definition FuelType.cpp:10
bool isValid() const override
Is fuel a valid fuel type.
Definition FuelType.h:413
MathSize surfaceFuelConsumption(const SpreadInfo &) const override
Throw a runtime_error.
Definition FuelType.cpp:28
MathSize buiEffect(MathSize) const override
Throw a runtime_error.
Definition FuelType.cpp:12
MathSize cfl() const override
Throw a runtime_error.
Definition FuelType.cpp:11
MathSize grass_curing(const int nd, const FwiWeather &wx) const override
Throw a runtime_error.
Definition FuelType.cpp:6
MathSize criticalSurfaceIntensity(const SpreadInfo &) const override
Throw a runtime_error.
Definition FuelType.cpp:40
Information regarding spread within a Cell for a specific Scenario and time.
Definition FireSpread.h:40
A Weather value with calculated FWI indices.
Definition FWI.h:142
A specific type of Duff layer, and the associated smouldering coefficients.
Definition Duff.h:40
ThresholdSize probabilityOfSurvival(const MathSize mc_pct) const noexcept
Probability of survival (% / 100) [eq Ig-1].
Definition Duff.h:70