Fire process

Purpose

Fire is the first stochastic landscape process in the ecosystem layer. It consumes the event record, the counter-based tape, and the cohort state, and it is the vertical slice that proves the architecture end to end. It is a LANDIS-class skeleton, not a calibrated fire-behaviour model: ignition is Poisson, spread is graph percolation, severity drives cohort mortality, and salvage is a deterministic controlled source.

The process is annual. It does not modify the compiled management dataset; it reads the cohort state and writes a replayable event log, disturbance rows, and account values.

Ignition

Every eligible fragment-year draws a Poisson count:

count = Poisson(ignition_rate_per_fragment_year)
key   = (scenario seed, "fire", fragment, year, 0)

A fragment is eligible when its area-weighted fuel is positive. Each ignition in the count receives a uniform time inside the year and an ignition event with phase ignition. The count is the analytic oracle: over many fragment-years the total must approach the configured rate.

Spread

An ignition starts a breadth-first walk over the undirected landscape graph. For each edge into an unburned target fragment, the crossing probability is:

p = base_spread_probability
    × min(1, target fuel / fuel_reference_t_ha)
    × exp(-distance_m / distance_scale_m)
    × wind factor

The wind factor is one when wind is disabled or the edge has no bearing. Otherwise it is max(0, 1 + wind_strength × cos(bearing - wind_direction)). The target fragment’s fuel is used, so a zero-fuel barrier stops the fire. The draw is keyed by the edge, so the same scenario tape gives the same crossing decision regardless of traversal order.

The legacy probability path is retained for replay tests. A run that supplies FireBehaviourConfig uses the validated FBP surface/crown kernel instead:

  • the head rate of spread and ellipse shape come from the FBP layer;

  • the edge direction relative to the effective wind gives a directional rate of spread;

  • the crossing probability is min(1, directional ROS × time step / edge distance);

  • the crossing draw remains keyed by the edge and scenario tape;

  • the event time advances by distance / (ROS × minutes per year).

Every behaviour-driven fire event carries behaviour_source, fbp_fuel_type, FFMC, BUI, wind, slope, ros_m_min, head_fire_intensity_kw_m, flame_length_m, crown_fraction_burned, surface_fuel_consumption_kg_m2, smoke_strength, fire_description, and kernel_version. The scene reads those attributes to scale flames and smoke, so the event record is the single source of the visual state.

Every burned fragment produces one fire event with phase propagation, a severity class and value, the mortality fraction, the fragment area, and the event that caused it. The event id is derived from the ignition event id and the fragment id, so two fires in one year cannot collide.

Severity and mortality

Severity is a uniform draw in [severity_min, severity_max], keyed by the fragment and year. Mortality is:

mortality = min(1, severity × mortality_factor)

For every cohort in the burned fragment, the killed area fraction becomes a new age-zero cohort with zero live biomass and zero fuel. The killed biomass leaves a snag pool of biomass_t_ha × snag_fraction. The surviving cohort keeps the remaining fraction. The total area fraction stays one, so the area-conservation check passes after every fire.

Salvage

The salvage source is deterministic. After salvage_delay_years it emits one salvage event per burned fragment with a positive snag volume. The event is a controlled event with phase treatment, a parent link to the fire event, and the merchantable volume:

volume_m3 = Σ snag_t_ha × area_fraction × fragment_area_ha × volume_per_t

Applying the event removes the fragment’s snags. The event log keeps the volume, so the account is auditable even after the state changes.

Accounts

A run writes account rows with year, account, and value:

  • fire.count

  • fire.burned_area_ha

  • fire.mortality_area_ha

  • fire.severity_area_weighted

  • fire.killed_biomass_t

  • fire.snag_created_t

  • fire.emitted_biomass_t

  • fire.ros_mean_m_min

  • fire.ros_max_m_min

  • fire.intensity_mean_kw_m

  • fire.intensity_max_kw_m

  • fire.flame_length_mean_m

  • fire.flame_length_max_m

  • fire.crown_fraction_area_weighted

  • salvage.count

  • salvage.area_ha

  • salvage.volume_m3

  • state.biomass_t

  • state.fuel_t

  • state.snag_t

The biomass accounts close a live-mass balance: the initial live biomass equals the final live biomass plus cumulative killed biomass, and killed biomass equals the snag-created and emitted shares. That is a biomass-mass check, not a full CBM pool-and-flux accounting; the carbon ledger’s fire/salvage event source is a later task.

The result also writes events.json (the event log), disturbances.json (the fire events as femic.disturbance.v1 consumer rows), cohorts.csv, and summary.json. The disturbance export maps simulation offsets to calendar years with start_year (default 1900), because the disturbance contract’s year is a calendar year while the event log’s year is the annual accounting offset.

Configuration

FireConfig fields:

Field

Default

Meaning

ignition_rate_per_fragment_year

0.01

Poisson ignition rate per eligible fragment-year.

base_spread_probability

0.45

Base edge-crossing probability.

fuel_reference_t_ha

20.0

Target fuel at which the fuel factor reaches one.

distance_scale_m

250.0

Exponential distance decay scale.

wind_direction_deg

null

Wind direction clockwise from north; null disables wind.

wind_strength

0.0

Wind strength in [0, 1].

severity_min

0.2

Minimum severity draw.

severity_max

1.0

Maximum severity draw.

mortality_factor

0.8

Fraction of severity that kills a cohort.

snag_fraction

0.1

Fraction of killed biomass left as snags.

salvage_delay_years

1

Delay before a burned fragment is salvaged.

salvage_volume_m3_per_t

1.0

Merchantable volume per tonne of snag.

max_spread_steps

10000

Guard against a runaway fire.

Example

The repository ships a synthetic grid demo:

python examples/ecosystem_fire_demo.py

The same run is available programmatically:

from ws4.ecosystem import run_fire_demo

result = run_fire_demo(rows=5, cols=5, years=30, seed=7)
print(result.log.replay_token)
print(result.accounts.tail())

A run over a compiled dataset and an ecosystem package:

from ws4.ecosystem import FireConfig, FireRun, load_ecosystem_package, synthetic_grid

package = load_ecosystem_package("dataset/ecosystem")
state = package.cohort_state("dataset")
_, _, edges = synthetic_grid(5, 5)
result = FireRun(
    state,
    edges,
    FireConfig(ignition_rate_per_fragment_year=0.02),
    scenario_id="base",
    seed=42,
    package_hashes=(("ecosystem", package.fingerprint),),
).run(30)
result.write("runs/base-fire")

Oracles

  • Poisson count. A single fragment over 1,000 years at rate 0.05 lands near 50 ignitions.

  • Geometric chain. A one-dimensional chain with base probability 0.5 has a mean burn length of 1 / (1 - 0.5) = 2 fragments from one ignition.

  • Barrier. A zero-fuel column stops a fire that would otherwise cross the grid.

  • Wind. A downwind edge crosses at probability one while its upwind reverse does not.

  • Area conservation. Fire and salvage preserve each fragment’s area fractions.

  • Replay. The same state, configuration, and seed produce the same event log and digest.

Limits

  • The process is not calibrated to fire behaviour, fuels, weather, or topography.

  • Time is annual. Continuous-time event scheduling is a later task.

  • Fires in the same year are processed in ignition order; overlapping fires are not treated as a simultaneous front.

  • Other processes (wind, insects, drought, succession) are not implemented yet.

  • The optimizer does not yet search fire-aware policies. Scenario ensembles and risk targets are P144.5.

Cross-references