Heat System

How heat accumulates per agent in MAFIS, triggers Overheat faults, and produces heatmap visualizations of congestion.

The heat system models thermal stress and congestion penalty in MAFIS. Heat builds up in areas of high agent density and waiting, eventually triggering Overheat faults that kill agents and create permanent obstacles.

Heat Accumulation

Heat is tracked per agent. Each tick, the accumulate_heat system updates every living agent’s heat level based on four factors:

Factor	Config param	Description
Movement heat	`heat_per_move`	Minor heat generated by navigating cells
Wait heat	`heat_per_wait`	Higher heat for standing still (congestion penalty)
Congestion bonus	`congestion_heat_bonus`	Extra heat per nearby agent within `congestion_heat_radius`
Dissipation	`heat_dissipation`	Heat lost per tick when not congested

The heat_per_wait penalty is typically higher than heat_per_move. This ensures that the worst-case heat scenario is an agent stuck waiting in a congested corridor, not an agent moving efficiently.

Overheat Threshold

[!WARNING] When an agent’s heat exceeds overheat_threshold, the agent dies permanently. Tune heat_per_wait and congestion_heat_bonus carefully, as dense corridors can trigger chain overheat events.

When an agent’s accumulated heat exceeds overheat_threshold, a FaultType::Overheat is triggered:

Agent state → Dead
Agent’s cell → permanent obstacle in GridMap
Cascade pipeline fires (ADG → BFS → replan)
FaultEventRecord created with fault_type: FaultType::Overheat

Overheat faults are automatic. They are not externally injected but arise from the simulation dynamics. A scheduler that assigns tasks creating congestion hot spots will generate Overheat faults even at low breakdown_probability settings.

Heatmap

The heatmap is a spatial density grid updated each tick. It provides a real-time overlay in the 3D viewport showing congestion hot spots. Cells where agents frequently wait show high density; lightly trafficked cells show low density.

Research Use

The heat system creates a direct link between scheduler strategy and fault generation rate:

A scheduler that concentrates tasks in busy corridors will generate more Overheat faults per unit time than a scheduler that distributes load.
This means fault intensity is not just an external configuration knob. It emerges from the interaction between the scheduler and the map topology.

[!TIP] This emergent behavior is by design. The observatory observes how the system’s own dynamics create fault pressure, and how different configurations handle that pressure differently.

Configuration

Heat parameters live in FaultConfig (src/fault/config.rs):

pub struct FaultConfig {
    pub heat_per_move: f32,
    pub heat_per_wait: f32,
    pub congestion_heat_radius: u32,
    pub congestion_heat_bonus: f32,
    pub heat_dissipation: f32,
    pub overheat_threshold: f32,
    pub breakdown_probability: f32,
}

Default values are tuned so that at medium fault intensity, Overheat faults begin appearing within 50–100 ticks of the fault injection phase on a dense grid.

Code Location

src/fault/heat.rs : accumulate_heat system, HeatmapState resource
src/fault/config.rs : FaultConfig resource
src/analysis/fault_metrics.rs : fault metrics computation