Skip to content

Data Classes

This module defines the dataclasses that carry configuration and results through the EMBRS pipeline. Users encounter them in two main contexts: setting up a simulation (via SimParams, MapParams, and WeatherParams loaded from .cfg files) and working with fire prediction outputs (via PredictionOutput, EnsemblePredictionOutput, and StateEstimate returned by FirePredictor). Most fields mirror the configuration file options documented in the Tutorials section.

Dataclasses for simulation parameters and state.

This module defines dataclasses used throughout EMBRS for storing configuration parameters, simulation state, and intermediate results.

Classes:

Name Description
- MapDrawerData

Data from the map drawing interface.
- GeoInfo

Geographic information for a simulation area.
- LandscapeData

Landscape raster data from LCP files.
- MapParams

Parameters for map configuration.
- PlaybackVisualizerParams

Parameters for playback visualization.
- VisualizerInputs

Input data for the visualizer.
- WeatherEntry

Single weather observation.
- WeatherParams

Weather input configuration.
- SimParams

Full simulation parameters.
- PredictorParams

Fire predictor configuration.
- WindNinjaTask

WindNinja processing task parameters.
- CellData

Cell-level data for fire calculations.
- PredictionOutput

Output from a single fire prediction.
- StateEstimate

Estimated fire state from observations.
- CellStatistics

Statistics for ensemble cell metrics.
- EnsemblePredictionOutput

Output from ensemble predictions.
Note

ForecastData, ForecastPool, and ForecastPoolManager have been moved to embrs.tools.forecast_pool. Importing them from this module still works but is deprecated.

CellData dataclass

Cell-level data for fire behavior calculations.

Attributes:

Name Type Description
fuel_type Fuel

Fuel model for this cell.
elevation float

Elevation in meters.
aspect float

Aspect in degrees (0=N, 90=E).
slope_deg float

Slope in degrees.
canopy_cover float

Canopy cover as a percentage.
canopy_height float

Canopy height in meters.
canopy_base_height float

Canopy base height in meters.
canopy_bulk_density float

Canopy bulk density in kg/m^3.
init_dead_mf List[float]

Initial dead fuel moisture fractions [1hr, 10hr, 100hr].
live_h_mf float

Live herbaceous moisture fraction.
live_w_mf float

Live woody moisture fraction.
Source code in embrs/utilities/data_classes.py 
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
@dataclass
class CellData:
    """Cell-level data for fire behavior calculations.

    Attributes:
        fuel_type (Fuel): Fuel model for this cell.
        elevation (float): Elevation in meters.
        aspect (float): Aspect in degrees (0=N, 90=E).
        slope_deg (float): Slope in degrees.
        canopy_cover (float): Canopy cover as a percentage.
        canopy_height (float): Canopy height in meters.
        canopy_base_height (float): Canopy base height in meters.
        canopy_bulk_density (float): Canopy bulk density in kg/m^3.
        init_dead_mf (List[float]): Initial dead fuel moisture fractions [1hr, 10hr, 100hr].
        live_h_mf (float): Live herbaceous moisture fraction.
        live_w_mf (float): Live woody moisture fraction.
    """

    fuel_type: Optional[Fuel] = None
    elevation: Optional[float] = None
    aspect: Optional[float] = None
    slope_deg: Optional[float] = None
    canopy_cover: Optional[float] = None
    canopy_height: Optional[float] = None
    canopy_base_height: Optional[float] = None
    canopy_bulk_density: Optional[float] = None
    init_dead_mf: Optional[List[float]] = field(default_factory=lambda: [0.06, 0.07, 0.08])
    live_h_mf: Optional[float] = 0.3
    live_w_mf: Optional[float] = 0.3

CellStatistics dataclass

Statistics for a single metric across ensemble members.

Attributes:

Name Type Description
mean float

Mean value across ensemble members.
std float

Standard deviation across ensemble members.
min float

Minimum value across ensemble members.
max float

Maximum value across ensemble members.
count int

Number of ensemble members with data for this cell.
Source code in embrs/utilities/data_classes.py 
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
@dataclass
class CellStatistics:
    """Statistics for a single metric across ensemble members.

    Attributes:
        mean (float): Mean value across ensemble members.
        std (float): Standard deviation across ensemble members.
        min (float): Minimum value across ensemble members.
        max (float): Maximum value across ensemble members.
        count (int): Number of ensemble members with data for this cell.
    """

    mean: float
    std: float
    min: float
    max: float
    count: int

EnsemblePredictionOutput dataclass

Output from ensemble fire prediction runs.

Aggregates statistics across multiple prediction runs with varying parameters to quantify prediction uncertainty.

Attributes:

Name Type Description
n_ensemble int

Number of ensemble members.
burn_probability dict

Maps time (s) to dict of (x, y) to burn probability (0-1).
flame_len_m_stats dict

Maps (x, y) to CellStatistics for flame length.
fli_kw_m_stats dict

Maps (x, y) to CellStatistics for fireline intensity.
ros_ms_stats dict

Maps (x, y) to CellStatistics for rate of spread.
spread_dir_stats dict

Maps (x, y) to dict with 'mean_x' and 'mean_y' for circular mean spread direction.
crown_fire_probability dict

Maps time in seconds to dict of (x, y) to crown fire probability (0-1).
hold_prob_stats dict

Maps (x, y) to CellStatistics for hold probability.
breach_frequency dict

Maps (x, y) to breach probability (0-1).
active_fire_probability Optional[dict]

Maps time in seconds to dict of (x, y) to probability of active fire presence (0-1). Optional.
burnt_probability Optional[dict]

Maps time in seconds to dict of (x, y) to probability of being burnt (0-1). Optional.
individual_predictions List[PredictionOutput]

Individual prediction outputs for inspection. Optional.
forecast_indices Optional[List[int]]

List of ints indicating the indices of the forecast_pool used for each of the predictions in the ensemble.
Source code in embrs/utilities/data_classes.py 
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
@dataclass
class EnsemblePredictionOutput:
    """Output from ensemble fire prediction runs.

    Aggregates statistics across multiple prediction runs with varying
    parameters to quantify prediction uncertainty.

    Attributes:
        n_ensemble (int): Number of ensemble members.
        burn_probability (dict): Maps time (s) to dict of (x, y) to burn
            probability (0-1).
        flame_len_m_stats (dict): Maps (x, y) to CellStatistics for flame length.
        fli_kw_m_stats (dict): Maps (x, y) to CellStatistics for fireline intensity.
        ros_ms_stats (dict): Maps (x, y) to CellStatistics for rate of spread.
        spread_dir_stats (dict): Maps (x, y) to dict with 'mean_x' and 'mean_y'
            for circular mean spread direction.
        crown_fire_probability (dict): Maps time in seconds to dict of (x, y) to crown fire probability (0-1).
        hold_prob_stats (dict): Maps (x, y) to CellStatistics for hold probability.
        breach_frequency (dict): Maps (x, y) to breach probability (0-1).
        active_fire_probability (Optional[dict]): Maps time in seconds to dict of (x, y) to probability of active fire presence (0-1). Optional.
        burnt_probability (Optional[dict]): Maps time in seconds to dict of (x, y) to probability of being burnt (0-1). Optional.
        individual_predictions (List[PredictionOutput]): Individual prediction
            outputs for inspection. Optional.
        forecast_indices (Optional[List[int]]): List of ints indicating the indices of 
            the forecast_pool used for each of the predictions in the ensemble.
    """

    n_ensemble: int
    burn_probability: dict
    flame_len_m_stats: dict
    fli_kw_m_stats: dict
    ros_ms_stats: dict
    spread_dir_stats: dict
    crown_fire_probability: dict
    hold_prob_stats: dict
    breach_frequency: dict
    active_fire_probability: Optional[dict] = None
    burnt_probability: Optional[dict] = None
    individual_predictions: Optional[List[PredictionOutput]] = None
    forecast_indices: Optional[List[int]] = None

GeoInfo dataclass

Geographic information for a simulation area.

Attributes:

Name Type Description
bounds BoundingBox

Spatial bounds from rasterio.
center_lat float

Center latitude in degrees (WGS84).
center_lon float

Center longitude in degrees (WGS84).
timezone str

IANA timezone string (e.g., 'America/Denver').
north_angle_deg float

Rotation from grid north to true north in degrees.
Source code in embrs/utilities/data_classes.py 
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
@dataclass
class GeoInfo:
    """Geographic information for a simulation area.

    Attributes:
        bounds (BoundingBox): Spatial bounds from rasterio.
        center_lat (float): Center latitude in degrees (WGS84).
        center_lon (float): Center longitude in degrees (WGS84).
        timezone (str): IANA timezone string (e.g., 'America/Denver').
        north_angle_deg (float): Rotation from grid north to true north in degrees.
    """

    bounds: Optional[BoundingBox] = None
    center_lat: Optional[float] = None
    center_lon: Optional[float] = None
    timezone: Optional[str] = None
    north_angle_deg: Optional[float] = None

    def calc_center_coords(self, source_crs: 'pyproj.CRS') -> None:
        """Calculate center lat/lon from bounds and source CRS.

        Args:
            source_crs (pyproj.CRS): Coordinate reference system of the bounds.

        Raises:
            ValueError: If bounds is None.
        """
        if self.bounds is None:
            raise ValueError("Can't perform this function without bounds")

        mid_x = (self.bounds.left + self.bounds.right) / 2
        mid_y = (self.bounds.bottom + self.bounds.top) / 2

        transformer = Transformer.from_crs(source_crs, "EPSG:4326", always_xy=True)

        self.center_lon, self.center_lat = transformer.transform(mid_x, mid_y)

    def calc_time_zone(self) -> None:
        """Calculate timezone from center coordinates.

        Raises:
            ValueError: If center coordinates are not set.
        """
        if self.center_lat is None or self.center_lon is None:
            raise ValueError("Center coordinates must be set before computing the time zone")

        tf = TimezoneFinder()
        self.timezone = tf.timezone_at(lng=self.center_lon, lat=self.center_lat)

calc_center_coords(source_crs)

Calculate center lat/lon from bounds and source CRS.

Parameters:

Name Type Description Default
source_crs CRS

Coordinate reference system of the bounds.

 required

Raises:

Type Description
ValueError

If bounds is None.
Source code in embrs/utilities/data_classes.py 
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def calc_center_coords(self, source_crs: 'pyproj.CRS') -> None:
    """Calculate center lat/lon from bounds and source CRS.

    Args:
        source_crs (pyproj.CRS): Coordinate reference system of the bounds.

    Raises:
        ValueError: If bounds is None.
    """
    if self.bounds is None:
        raise ValueError("Can't perform this function without bounds")

    mid_x = (self.bounds.left + self.bounds.right) / 2
    mid_y = (self.bounds.bottom + self.bounds.top) / 2

    transformer = Transformer.from_crs(source_crs, "EPSG:4326", always_xy=True)

    self.center_lon, self.center_lat = transformer.transform(mid_x, mid_y)

calc_time_zone()

Calculate timezone from center coordinates.

Raises:

Type Description
ValueError

If center coordinates are not set.
Source code in embrs/utilities/data_classes.py 
101
102
103
104
105
106
107
108
109
110
111
def calc_time_zone(self) -> None:
    """Calculate timezone from center coordinates.

    Raises:
        ValueError: If center coordinates are not set.
    """
    if self.center_lat is None or self.center_lon is None:
        raise ValueError("Center coordinates must be set before computing the time zone")

    tf = TimezoneFinder()
    self.timezone = tf.timezone_at(lng=self.center_lon, lat=self.center_lat)

LandscapeData dataclass

Landscape raster data extracted from LCP files.

Attributes:

Name Type Description
elevation_map ndarray

Elevation in meters.
slope_map ndarray

Slope in degrees.
aspect_map ndarray

Aspect in degrees (0=N, 90=E).
fuel_map ndarray

Fuel model IDs.
canopy_cover_map ndarray

Canopy cover as fraction.
canopy_height_map ndarray

Canopy height in meters.
canopy_base_height_map ndarray

Canopy base height in meters.
canopy_bulk_density_map ndarray

Canopy bulk density in kg/m^3.
rows int

Number of raster rows.
cols int

Number of raster columns.
resolution int

Raster resolution in meters.
width_m float

Total width in meters.
height_m float

Total height in meters.
transform any

Rasterio affine transform.
crs any

Coordinate reference system.
Source code in embrs/utilities/data_classes.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
@dataclass
class LandscapeData:
    """Landscape raster data extracted from LCP files.

    Attributes:
        elevation_map (np.ndarray): Elevation in meters.
        slope_map (np.ndarray): Slope in degrees.
        aspect_map (np.ndarray): Aspect in degrees (0=N, 90=E).
        fuel_map (np.ndarray): Fuel model IDs.
        canopy_cover_map (np.ndarray): Canopy cover as fraction.
        canopy_height_map (np.ndarray): Canopy height in meters.
        canopy_base_height_map (np.ndarray): Canopy base height in meters.
        canopy_bulk_density_map (np.ndarray): Canopy bulk density in kg/m^3.
        rows (int): Number of raster rows.
        cols (int): Number of raster columns.
        resolution (int): Raster resolution in meters.
        width_m (float): Total width in meters.
        height_m (float): Total height in meters.
        transform (any): Rasterio affine transform.
        crs (any): Coordinate reference system.
    """

    elevation_map: np.ndarray
    slope_map: np.ndarray
    aspect_map: np.ndarray
    fuel_map: np.ndarray
    canopy_cover_map: np.ndarray
    canopy_height_map: np.ndarray
    canopy_base_height_map: np.ndarray
    canopy_bulk_density_map: np.ndarray
    rows: int
    cols: int
    resolution: int
    width_m: float
    height_m: float
    transform: any
    crs: any

MapDrawerData dataclass

Data collected from the interactive map drawing interface.

Attributes:

Name Type Description
fire_breaks Dict

Fire break geometries keyed by ID.
break_widths List

Width in meters for each fire break.
break_ids List

Identifiers for fire breaks.
initial_ign List

Initial ignition point coordinates.
Source code in embrs/utilities/data_classes.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
@dataclass
class MapDrawerData:
    """Data collected from the interactive map drawing interface.

    Attributes:
        fire_breaks (Dict): Fire break geometries keyed by ID.
        break_widths (List): Width in meters for each fire break.
        break_ids (List): Identifiers for fire breaks.
        initial_ign (List): Initial ignition point coordinates.
    """

    fire_breaks: Optional[Dict] = field(default_factory=dict)
    break_widths: Optional[List] = field(default_factory=list)
    break_ids: Optional[List] = field(default_factory=list)
    initial_ign: Optional[List] = field(default_factory=list)

MapParams dataclass

Parameters for map configuration.

Attributes:

Name Type Description
folder str

Path to the map data folder.
lcp_filepath str

Path to the source LCP file.
cropped_lcp_path str

Path to cropped LCP file if applicable.
import_roads bool

Whether to import roads from OSM.
lcp_data LandscapeData

Extracted landscape data.
roads List

List of road geometries.
geo_info GeoInfo

Geographic information.
scenario_data MapDrawerData

User-drawn scenario elements.
fbfm_type str

Fuel model type ('Anderson' or 'ScottBurgan').
Source code in embrs/utilities/data_classes.py 
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
@dataclass
class MapParams:
    """Parameters for map configuration.

    Attributes:
        folder (str): Path to the map data folder.
        lcp_filepath (str): Path to the source LCP file.
        cropped_lcp_path (str): Path to cropped LCP file if applicable.
        import_roads (bool): Whether to import roads from OSM.
        lcp_data (LandscapeData): Extracted landscape data.
        roads (List): List of road geometries.
        geo_info (GeoInfo): Geographic information.
        scenario_data (MapDrawerData): User-drawn scenario elements.
        fbfm_type (str): Fuel model type ('Anderson' or 'ScottBurgan').
    """

    folder: Optional[str] = None
    lcp_filepath: Optional[str] = None
    cropped_lcp_path: Optional[str] = None
    import_roads: Optional[bool] = None
    lcp_data: Optional[LandscapeData] = None
    roads: Optional[List] = field(default_factory=list)
    geo_info: Optional[GeoInfo] = None
    scenario_data: Optional[MapDrawerData] = None
    fbfm_type: Optional[str] = "Anderson"

    def size(self) -> Tuple[float, float]:
        """Get the map size in meters.

        Returns:
            Tuple[float, float]: (width_m, height_m).
        """
        return (self.lcp_data.width_m, self.lcp_data.height_m)

    def shape(self, cell_size: int) -> Tuple[int, int]:
        """Calculate grid shape for a given cell size.

        Args:
            cell_size (int): Hexagon side length in meters.

        Returns:
            Tuple[int, int]: (rows, cols) for the hexagonal grid.
        """
        rows = int(np.floor(self.lcp_data.height_m/(1.5*cell_size))) + 1
        cols = int(np.floor(self.lcp_data.width_m/(np.sqrt(3)*cell_size))) + 1

        return (rows, cols)

shape(cell_size)

Calculate grid shape for a given cell size.

Parameters:

Name Type Description Default
cell_size int

Hexagon side length in meters.

 required

Returns:

Type Description
Tuple[int, int]

Tuple[int, int]: (rows, cols) for the hexagonal grid.
Source code in embrs/utilities/data_classes.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
def shape(self, cell_size: int) -> Tuple[int, int]:
    """Calculate grid shape for a given cell size.

    Args:
        cell_size (int): Hexagon side length in meters.

    Returns:
        Tuple[int, int]: (rows, cols) for the hexagonal grid.
    """
    rows = int(np.floor(self.lcp_data.height_m/(1.5*cell_size))) + 1
    cols = int(np.floor(self.lcp_data.width_m/(np.sqrt(3)*cell_size))) + 1

    return (rows, cols)

size()

Get the map size in meters.

Returns:

Type Description
Tuple[float, float]

Tuple[float, float]: (width_m, height_m).
Source code in embrs/utilities/data_classes.py 
178
179
180
181
182
183
184
def size(self) -> Tuple[float, float]:
    """Get the map size in meters.

    Returns:
        Tuple[float, float]: (width_m, height_m).
    """
    return (self.lcp_data.width_m, self.lcp_data.height_m)

PlaybackVisualizerParams dataclass

Parameters for playback visualization from log files.

Attributes:

Name Type Description
cell_file str

Path to cell_logs.parquet file.
init_location bool

Whether init_state.parquet was found.
save_video bool

Whether to save visualization as video.
video_folder str

Folder to save video output.
video_name str

Video filename.
has_agents bool

Whether agent logs are available.
has_actions bool

Whether action logs are available.
has_predictions bool

Whether prediction logs are available.
video_fps int

Video frames per second.
agent_file str

Path to agent_logs.parquet.
action_file str

Path to action_logs.parquet.
prediction_file str

Path to prediction_logs.parquet.
freq float

Update frequency in seconds.
scale_km float

Scale bar size in kilometers.
show_legend bool

Whether to display fuel legend.
show_wind_cbar bool

Whether to show wind colorbar.
show_wind_field bool

Whether to show wind field.
show_weather_data bool

Whether to show weather info.
show_compass bool

Whether to show compass.
show_visualization bool

Whether to render visualization.
show_temp_in_F bool

Whether to display temperature in Fahrenheit.
Source code in embrs/utilities/data_classes.py 
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
@dataclass
class PlaybackVisualizerParams:
    """Parameters for playback visualization from log files.

    Attributes:
        cell_file (str): Path to cell_logs.parquet file.
        init_location (bool): Whether init_state.parquet was found.
        save_video (bool): Whether to save visualization as video.
        video_folder (str): Folder to save video output.
        video_name (str): Video filename.
        has_agents (bool): Whether agent logs are available.
        has_actions (bool): Whether action logs are available.
        has_predictions (bool): Whether prediction logs are available.
        video_fps (int): Video frames per second.
        agent_file (str): Path to agent_logs.parquet.
        action_file (str): Path to action_logs.parquet.
        prediction_file (str): Path to prediction_logs.parquet.
        freq (float): Update frequency in seconds.
        scale_km (float): Scale bar size in kilometers.
        show_legend (bool): Whether to display fuel legend.
        show_wind_cbar (bool): Whether to show wind colorbar.
        show_wind_field (bool): Whether to show wind field.
        show_weather_data (bool): Whether to show weather info.
        show_compass (bool): Whether to show compass.
        show_visualization (bool): Whether to render visualization.
        show_temp_in_F (bool): Whether to display temperature in Fahrenheit.
    """

    cell_file: str
    init_location: bool
    save_video: bool
    video_folder: str
    video_name: str
    has_agents: bool
    has_actions: bool
    has_predictions: bool
    video_fps: Optional[int] = 10
    agent_file: Optional[str] = None
    action_file: Optional[str] = None
    prediction_file: Optional[str] = None

    freq: Optional[float] = 300
    scale_km: Optional[float] = 1.0
    show_legend: Optional[bool] = True
    show_wind_cbar: Optional[bool] = True
    show_wind_field: Optional[bool] = True
    show_weather_data: Optional[bool] = True
    show_compass: Optional[bool] = True
    show_visualization: Optional[bool] = True
    show_temp_in_F: Optional[bool] = True

PredictionOutput dataclass

Output from a single fire spread prediction.

Attributes:

Name Type Description
spread dict

Maps time in seconds to list of (x, y) positions where fire is predicted to arrive at that time.
flame_len_m dict

Maps (x, y) to flame length in meters.
fli_kw_m dict

Maps (x, y) to fireline intensity in kW/m.
ros_ms dict

Maps (x, y) to rate of spread in m/s.
spread_dir dict

Maps (x, y) to spread direction in degrees.
all_crown_fire dict

Maps (x, y) to time in seconds when crown fire is first predicted.
active_crown_fire dict

Maps time in seconds to dict of ((x, y), crown_fire_status('active' or 'passive')).
end_active_crown dict

Maps (x,y) to time in seconds when crown fire goes out.
breaches dict

Maps (x, y) to breach status (bool).
active_fire_front dict

Maps time in seconds to list of (x, y) positions where fire is predicted to be currently burning at that time.
burnt_spread dict

Maps time in seconds to list of (x, y) positions where cells are predicted to already be fully burnt.
forecast_index Optional[int]

Indicates the index of the forecast_pool that was used to generate the prediction.
Source code in embrs/utilities/data_classes.py 
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
@dataclass
class PredictionOutput:
    """Output from a single fire spread prediction.

    Attributes:
        spread (dict): Maps time in seconds to list of (x, y) positions
            where fire is predicted to arrive at that time.
        flame_len_m (dict): Maps (x, y) to flame length in meters.
        fli_kw_m (dict): Maps (x, y) to fireline intensity in kW/m.
        ros_ms (dict): Maps (x, y) to rate of spread in m/s.
        spread_dir (dict): Maps (x, y) to spread direction in degrees.
        all_crown_fire (dict): Maps (x, y) to time in seconds when crown fire is first predicted.
        active_crown_fire (dict): Maps time in seconds to dict of ((x, y), crown_fire_status('active' or 'passive')).
        end_active_crown (dict): Maps (x,y) to time in seconds when crown fire goes out.
        breaches (dict): Maps (x, y) to breach status (bool).
        active_fire_front (dict): Maps time in seconds to list of (x, y) positions
            where fire is predicted to be currently burning at that time.
        burnt_spread (dict): Maps time in seconds to list of (x, y) positions where
            cells are predicted to already be fully burnt.
        forecast_index (Optional[int]): Indicates the index of the forecast_pool that was used to
            generate the prediction.
    """

    spread: dict
    flame_len_m: dict
    fli_kw_m: dict
    ros_ms: dict
    spread_dir: dict
    all_crown_fire: dict
    active_crown_fire: dict
    end_active_crown: dict
    hold_probs: dict
    breaches: dict
    active_fire_front: dict
    burnt_spread: dict
    forecast_index: Optional[int] = None

PredictorParams dataclass

Fire predictor configuration.

Attributes:

Name Type Description
time_horizon_hr float

Prediction time horizon in hours.
time_step_s int

Prediction time step in seconds.
cell_size_m float

Cell size in meters.
dead_mf float

Dead fuel moisture fraction.
live_mf float

Live fuel moisture fraction.
model_spotting bool

Whether to model spotting.
spot_delay_s float

Spot ignition delay in seconds.
wind_speed_bias float

Wind speed bias in m/s.
wind_dir_bias float

Wind direction bias in degrees.
wind_uncertainty_factor float

Wind uncertainty scaling factor.
ros_bias float

Rate of spread bias factor.
max_wind_speed_bias float

Maximum wind speed bias in m/s.
max_wind_dir_bias float

Maximum wind direction bias in degrees.
base_wind_spd_std float

Base wind speed std dev in m/s.
base_wind_dir_std float

Base wind direction std dev in degrees.
max_beta float

Maximum uncertainty beta value.
Source code in embrs/utilities/data_classes.py 
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
@dataclass
class PredictorParams:
    """Fire predictor configuration.

    Attributes:
        time_horizon_hr (float): Prediction time horizon in hours.
        time_step_s (int): Prediction time step in seconds.
        cell_size_m (float): Cell size in meters.
        dead_mf (float): Dead fuel moisture fraction.
        live_mf (float): Live fuel moisture fraction.
        model_spotting (bool): Whether to model spotting.
        spot_delay_s (float): Spot ignition delay in seconds.
        wind_speed_bias (float): Wind speed bias in m/s.
        wind_dir_bias (float): Wind direction bias in degrees.
        wind_uncertainty_factor (float): Wind uncertainty scaling factor.
        ros_bias (float): Rate of spread bias factor.
        max_wind_speed_bias (float): Maximum wind speed bias in m/s.
        max_wind_dir_bias (float): Maximum wind direction bias in degrees.
        base_wind_spd_std (float): Base wind speed std dev in m/s.
        base_wind_dir_std (float): Base wind direction std dev in degrees.
        max_beta (float): Maximum uncertainty beta value.
    """

    time_horizon_hr: float = 2.0
    time_step_s: int = 30
    cell_size_m: float = 30
    dead_mf: float = 0.08
    live_mf: float = 0.30
    model_spotting: bool = False
    spot_delay_s: float = 1200
    wind_speed_bias: float = 0
    wind_dir_bias: float = 0
    wind_uncertainty_factor: float = 0
    ros_bias: float = 0

    max_wind_speed_bias: float = 2.5
    max_wind_dir_bias: float = 20.0
    base_wind_spd_std: float = 1.0
    base_wind_dir_std: float = 5.0
    max_beta: float = 0.95

SimParams dataclass

Full simulation parameters.

Attributes:

Name Type Description
map_params MapParams

Map configuration.
log_folder str

Path to log output folder.
weather_input WeatherParams

Weather configuration.
t_step_s int

Simulation time step in seconds.
cell_size int

Hexagon side length in meters.
init_mf List[float]

Initial dead fuel moisture [1hr, 10hr, 100hr].
fuel_moisture_map Dict

Per-fuel-model moisture values.
fms_has_live bool

Whether FMS file includes live moisture.
live_h_mf float

Live herbaceous moisture fraction.
live_w_mf float

Live woody moisture fraction.
model_spotting bool

Whether to model spotting.
canopy_species int

Canopy species ID for spotting.
dbh_cm float

Diameter at breast height in cm.
spot_ign_prob float

Spot ignition probability (0-1).
min_spot_dist float

Minimum spotting distance in meters.
spot_delay_s float

Spot ignition delay in seconds.
duration_s float

Simulation duration in seconds.
visualize bool

Whether to show real-time visualization.
num_runs int

Number of simulation iterations.
user_path str

Path to user control module.
user_class str

Name of user control class.
write_logs bool

Whether to write log files.
Source code in embrs/utilities/data_classes.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
@dataclass
class SimParams:
    """Full simulation parameters.

    Attributes:
        map_params (MapParams): Map configuration.
        log_folder (str): Path to log output folder.
        weather_input (WeatherParams): Weather configuration.
        t_step_s (int): Simulation time step in seconds.
        cell_size (int): Hexagon side length in meters.
        init_mf (List[float]): Initial dead fuel moisture [1hr, 10hr, 100hr].
        fuel_moisture_map (Dict): Per-fuel-model moisture values.
        fms_has_live (bool): Whether FMS file includes live moisture.
        live_h_mf (float): Live herbaceous moisture fraction.
        live_w_mf (float): Live woody moisture fraction.
        model_spotting (bool): Whether to model spotting.
        canopy_species (int): Canopy species ID for spotting.
        dbh_cm (float): Diameter at breast height in cm.
        spot_ign_prob (float): Spot ignition probability (0-1).
        min_spot_dist (float): Minimum spotting distance in meters.
        spot_delay_s (float): Spot ignition delay in seconds.
        duration_s (float): Simulation duration in seconds.
        visualize (bool): Whether to show real-time visualization.
        num_runs (int): Number of simulation iterations.
        user_path (str): Path to user control module.
        user_class (str): Name of user control class.
        write_logs (bool): Whether to write log files.
    """

    map_params: Optional[MapParams] = None
    log_folder: Optional[str] = None
    weather_input: Optional[WeatherParams] = None
    t_step_s: Optional[int] = None
    cell_size: Optional[int] = None
    init_mf: Optional[List[float]] = field(default_factory=lambda: [0.06, 0.07, 0.08])
    fuel_moisture_map: Dict[int, List[float]] = field(default_factory=dict)
    fms_has_live: bool = False
    live_h_mf: Optional[float] = None
    live_w_mf: Optional[float] = None
    model_spotting: Optional[bool] = False
    canopy_species: Optional[int] = 5
    dbh_cm: Optional[float] = 20.0
    spot_ign_prob: Optional[float] = 0.05
    min_spot_dist: Optional[float] = 50
    spot_delay_s: Optional[float] = 1200
    duration_s: Optional[float] = None
    visualize: Optional[bool] = None
    num_runs: Optional[int] = None
    user_path: Optional[str] = None
    user_class: Optional[str] = None
    burn_area_threshold: Optional[float] = 0.75
    write_logs: Optional[bool] = None

StateEstimate dataclass

Estimated fire state from observations.

Attributes:

Name Type Description
burnt_polys List[Polygon]

Polygons of burnt area.
burning_polys List[Polygon]

Polygons of actively burning area.
start_time_s Optional[float]

Start time in seconds from simulation start. If None, uses current fire simulation time.
scheduled_ignitions Optional[Dict[float, List[Polygon]]]

Future ignitions keyed by absolute simulation time (seconds). Used for staggered strip firing rollouts. Polygons are resolved to cells inside the worker process via get_cells_at_geometry().
Source code in embrs/utilities/data_classes.py 
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
@dataclass
class StateEstimate:
    """Estimated fire state from observations.

    Attributes:
        burnt_polys (List[Polygon]): Polygons of burnt area.
        burning_polys (List[Polygon]): Polygons of actively burning area.
        start_time_s (Optional[float]): Start time in seconds from simulation start.
            If None, uses current fire simulation time.
        scheduled_ignitions (Optional[Dict[float, List[Polygon]]]): Future ignitions
            keyed by absolute simulation time (seconds). Used for staggered strip
            firing rollouts. Polygons are resolved to cells inside the worker
            process via get_cells_at_geometry().
    """

    burnt_polys: List[Polygon]
    burning_polys: List[Polygon]
    start_time_s: Optional[float] = None
    scheduled_ignitions: Optional[Dict[float, List[Polygon]]] = None

VisualizerInputs dataclass

Input data for the real-time visualizer.

Attributes:

Name Type Description
cell_size float

Hexagon side length in meters.
sim_shape Tuple[int, int]

Grid shape (rows, cols).
sim_size Tuple[float, float]

Map size (width_m, height_m).
start_datetime datetime

Simulation start time.
north_dir_deg float

Rotation to true north in degrees.
wind_forecast ndarray

Wind field data array.
wind_resolution float

Wind mesh resolution in meters.
wind_t_step float

Wind time step in seconds.
wind_xpad float

Wind field x padding in meters.
wind_ypad float

Wind field y padding in meters.
temp_forecast ndarray

Temperature forecast values.
rh_forecast ndarray

Relative humidity forecast values.
forecast_t_step float

Forecast time step in seconds.
elevation ndarray

Coarse elevation data for display.
roads list

Road geometries for display.
fire_breaks list

Fire break geometries for display.
init_entries list

Initial cell state entries.
scale_bar_km float

Scale bar size in kilometers.
show_legend bool

Whether to show fuel legend.
show_wind_cbar bool

Whether to show wind colorbar.
show_wind_field bool

Whether to show wind field.
show_weather_data bool

Whether to show weather info.
show_temp_in_F bool

Whether to show temperature in Fahrenheit.
show_compass bool

Whether to show compass.
Source code in embrs/utilities/data_classes.py 
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
@dataclass
class VisualizerInputs:
    """Input data for the real-time visualizer.

    Attributes:
        cell_size (float): Hexagon side length in meters.
        sim_shape (Tuple[int, int]): Grid shape (rows, cols).
        sim_size (Tuple[float, float]): Map size (width_m, height_m).
        start_datetime (datetime): Simulation start time.
        north_dir_deg (float): Rotation to true north in degrees.
        wind_forecast (np.ndarray): Wind field data array.
        wind_resolution (float): Wind mesh resolution in meters.
        wind_t_step (float): Wind time step in seconds.
        wind_xpad (float): Wind field x padding in meters.
        wind_ypad (float): Wind field y padding in meters.
        temp_forecast (np.ndarray): Temperature forecast values.
        rh_forecast (np.ndarray): Relative humidity forecast values.
        forecast_t_step (float): Forecast time step in seconds.
        elevation (np.ndarray): Coarse elevation data for display.
        roads (list): Road geometries for display.
        fire_breaks (list): Fire break geometries for display.
        init_entries (list): Initial cell state entries.
        scale_bar_km (float): Scale bar size in kilometers.
        show_legend (bool): Whether to show fuel legend.
        show_wind_cbar (bool): Whether to show wind colorbar.
        show_wind_field (bool): Whether to show wind field.
        show_weather_data (bool): Whether to show weather info.
        show_temp_in_F (bool): Whether to show temperature in Fahrenheit.
        show_compass (bool): Whether to show compass.
    """

    cell_size: float
    sim_shape: Tuple[int, int]
    sim_size: Tuple[float, float]
    start_datetime: datetime
    north_dir_deg: float
    wind_forecast: np.ndarray
    wind_resolution: float
    wind_t_step: float
    wind_xpad: float
    wind_ypad: float
    temp_forecast: np.ndarray
    rh_forecast: np.ndarray
    forecast_t_step: float
    elevation: np.ndarray
    roads: list
    fire_breaks: list
    init_entries: list

    scale_bar_km: Optional[float] = 1.0
    show_legend: Optional[bool] = True
    show_wind_cbar: Optional[bool] = True
    show_wind_field: Optional[bool] = True
    show_weather_data: Optional[bool] = True
    show_temp_in_F: Optional[bool] = True
    show_compass: Optional[bool] = True

WeatherEntry dataclass

Single weather observation at a point in time.

Attributes:

Name Type Description
wind_speed float

Wind speed in m/s.
wind_dir_deg float

Wind direction in degrees (meteorological).
temp float

Temperature in Celsius.
rel_humidity float

Relative humidity as fraction (0-1).
cloud_cover float

Cloud cover as fraction (0-1).
rain float

Rainfall in mm.
dni float

Direct normal irradiance in W/m^2.
dhi float

Diffuse horizontal irradiance in W/m^2.
ghi float

Global horizontal irradiance in W/m^2.
solar_zenith float

Solar zenith angle in degrees.
solar_azimuth float

Solar azimuth angle in degrees.
Source code in embrs/utilities/data_classes.py 
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
@dataclass
class WeatherEntry:
    """Single weather observation at a point in time.

    Attributes:
        wind_speed (float): Wind speed in m/s.
        wind_dir_deg (float): Wind direction in degrees (meteorological).
        temp (float): Temperature in Celsius.
        rel_humidity (float): Relative humidity as fraction (0-1).
        cloud_cover (float): Cloud cover as fraction (0-1).
        rain (float): Rainfall in mm.
        dni (float): Direct normal irradiance in W/m^2.
        dhi (float): Diffuse horizontal irradiance in W/m^2.
        ghi (float): Global horizontal irradiance in W/m^2.
        solar_zenith (float): Solar zenith angle in degrees.
        solar_azimuth (float): Solar azimuth angle in degrees.
    """

    wind_speed: float
    wind_dir_deg: float
    temp: float
    rel_humidity: float
    cloud_cover: float
    rain: float
    dni: float
    dhi: float
    ghi: float
    solar_zenith: float
    solar_azimuth: float

WeatherParams dataclass

Weather input configuration.

Attributes:

Name Type Description
input_type str

Weather source type ('OpenMeteo' or 'File').
file str

Path to weather file if using file input.
mesh_resolution int

WindNinja mesh resolution in meters.
conditioning_start datetime

Start time for fuel moisture conditioning.
start_datetime datetime

Simulation start time.
end_datetime datetime

Simulation end time.
Source code in embrs/utilities/data_classes.py 
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
@dataclass
class WeatherParams:
    """Weather input configuration.

    Attributes:
        input_type (str): Weather source type ('OpenMeteo' or 'File').
        file (str): Path to weather file if using file input.
        mesh_resolution (int): WindNinja mesh resolution in meters.
        conditioning_start (datetime): Start time for fuel moisture conditioning.
        start_datetime (datetime): Simulation start time.
        end_datetime (datetime): Simulation end time.
    """

    input_type: Optional[str] = None
    file: Optional[str] = ""
    mesh_resolution: Optional[int] = None
    conditioning_start: Optional[datetime] = None
    start_datetime: Optional[datetime] = None
    end_datetime: Optional[datetime] = None

WindNinjaTask dataclass

Parameters for a WindNinja processing task.

Attributes:

Name Type Description
index int

Task index in the processing queue.
time_step float

Time step for this wind field.
entry WeatherEntry

Weather data for this time step.
elevation_path str

Path to elevation raster file.
timezone str

IANA timezone string.
north_angle float

Rotation to true north in degrees.
mesh_resolution float

WindNinja mesh resolution in meters.
temp_file_path str

Path for temporary output files.
cli_path str

Path to WindNinja CLI executable.
start_datetime timedelta

Time offset from simulation start.
wind_height float

Wind measurement height.
wind_height_units str

Units for wind height.
input_speed_units str

Units for input wind speed.
temperature_units str

Units for temperature.
Source code in embrs/utilities/data_classes.py 
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
@dataclass
class WindNinjaTask:
    """Parameters for a WindNinja processing task.

    Attributes:
        index (int): Task index in the processing queue.
        time_step (float): Time step for this wind field.
        entry (WeatherEntry): Weather data for this time step.
        elevation_path (str): Path to elevation raster file.
        timezone (str): IANA timezone string.
        north_angle (float): Rotation to true north in degrees.
        mesh_resolution (float): WindNinja mesh resolution in meters.
        temp_file_path (str): Path for temporary output files.
        cli_path (str): Path to WindNinja CLI executable.
        start_datetime (timedelta): Time offset from simulation start.
        wind_height (float): Wind measurement height.
        wind_height_units (str): Units for wind height.
        input_speed_units (str): Units for input wind speed.
        temperature_units (str): Units for temperature.
    """

    index: int
    time_step: float
    entry: WeatherEntry
    elevation_path: str
    timezone: str
    north_angle: float
    mesh_resolution: float
    temp_file_path: str
    cli_path: str
    start_datetime: timedelta
    wind_height: float
    wind_height_units: str
    input_speed_units: str
    temperature_units: str

__getattr__(name)

Lazy import for backwards compatibility.

ForecastData, ForecastPool, and ForecastPoolManager have been moved to embrs.tools.forecast_pool. This allows old import paths to continue working while avoiding circular imports.

Source code in embrs/utilities/data_classes.py 
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
def __getattr__(name):
    """Lazy import for backwards compatibility.

    ForecastData, ForecastPool, and ForecastPoolManager have been moved to
    embrs.tools.forecast_pool. This allows old import paths to continue
    working while avoiding circular imports.
    """
    if name in ('ForecastData', 'ForecastPool', 'ForecastPoolManager'):
        import warnings
        warnings.warn(
            f"{name} has been moved to embrs.tools.forecast_pool. "
            f"Please update your imports to: from embrs.tools.forecast_pool import {name}",
            DeprecationWarning,
            stacklevel=2
        )
        from embrs.tools.forecast_pool import ForecastData, ForecastPool, ForecastPoolManager
        return {'ForecastData': ForecastData, 'ForecastPool': ForecastPool,
                'ForecastPoolManager': ForecastPoolManager}[name]
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")