Configuring the Simulation#

The configuration for SimFire is all done through a YAML file. All of the configurable settings will be explained in the sections below.

This file can have any name, as a path is required to load the configuration file, but the hierarchy of the file must match the hierarchy found in the example operational_config.yml. This example configuration can be seen in its entirety at the bottom of this page.

Note

This example in the docs may be out of date, so it is better to rely on the configs found in the configs directory of the repository.

Settings#

Area Parameters#

Attention

These parameters will be overwritten if you are using the “Operational” data.

screen_size#

(Tuple[int, int])
Determines how large the simulation is in pixels. The screen_size sets both the height and the width of the screen.

pixel_scale#

(float)
The number of feet across that one pixel represents. i.e. for the default value, one pixel represents a 50ft x 50ft square of land.

Display Parameters#

fire_size#

(int)
The size of the flame/fire size in pixels. Only used for display purposes, and does not change fire dynamics.

control_line_size#

(int)
The size of the control lines in pixels. Only used for display purposes, and does not change how much space the control line takes up in the simulation.

agent_size#

(int)
The size of the agent(s) in pixels. Only used for display purposes, and does not change how much space the agent takes up in the simulation.

rescale_factor#

(int)
The factor to increase the height and width of the screen for display purposes only.

Simulation Parameters#

update_rate#

(float)
The number of minutes that each game/frame update represents in simulation time. Note that this can be fractional to account for times that are non-integer and/or less than 1.

runtime#

(str)
The amount of time that the simulation is supposed to run. This can be expressed in days, hours, and minutes in any of the following ways and more: 2d, 2day, 2days, 24h, 1d 23h 60m, etc. If no designation is given or if the value is given with a space in between the integer and the time span (e.g. 2 days), the program will assume the units are in minutes.

headless#

(bool)
Whether or not to run the simulation in a headless state.

sf_home#

(str)
Where to save the LandFire operational data, GIF recordings, and burn graphs of simulation runs. It will create subfolders in sf_home that are called landfire, gifs, and graphs. This can be overriden for GIFs and burn graphs in individual function calls for save_gif and save_spread_graph. This will also set the environment variable SF_HOME to the same value.

draw_spread_graph#

(bool)

record#

(bool)

save_data#

(bool)

data_type#

(str)
The format to save the data of the simulation. Can by type: “npy”, “h5”.

Mitigation Parameters#

ros_attenuation#

(bool)
Whether or not to attenuate rate of spread based on the type of line being used. These attenuation values can be seen in enums.py. These values will be subtracted from the rate of spread for a given pixel based on the control line type. If this value is set to false, all lines will completely stop a fire and the rate of spread for any pixel with a control line will be set to zero.

Operational Parameters#

These are the operational parameters that will be used for the operational data layers that rely on a location, if those layers’ types are set to operational.

Attention

If using operational data, this will overwrite the values set in the Area Parameters section, as the height, width, and resolution set here will take precedence.

seed#

(int)
The seed that would pick a random latitude and longitude. Leave empty if using the latitude and longitude below.

latitude#

(float)
The latitude given in decimal degrees. The latitude sets the North-bounding (top-left) coordinate.

longitude#

(float)
The longitude given in decimal degrees. The longitude sets the West-bounding (top-left) coordinate.

height#

(int)
The height of the screen in meters. This is not randomized if choosing a seed.

width#

(int)
The width of the screen in meters. This is not randomized if choosing a seed.

resolution#

(int)
The resolution of each pixel in meters. Data is measured in pixels corresponding to the resolution i.e: resolution = 30m x 30m = 1 pixel. This is not randomized if choosing a seed. The area.pixel_scale auto-scales to this resolution, i.e 30m ~= 98ft.

year#

(int)
The year of the fuel data. Current options are 2019, 2020, and 2022. This is not randomized if choosing a seed.

Terrain Parameters#

topography#

All configuration settings for the topography in the simulation area.

type#

(str)
Can be either operational or functional.

If operational, will use the parameters in the Operational Parameters section to determine topography in the simulation area.

If functional, will use the parameters in terrain.topography.functional to determine topography in the simulation area.

functional#

All configuration settings for determining the functional topography data layer.

function#

(str)
The function that determines how elevation is distributed throughout the simulation area. The available elevation functions are currently:

  • perlin

  • gaussian

  • flat

perlin#

All arguments that would be passed into the PerlinNoise2D elevation class.

  • amplitude (int):
    The amplitude of the perlin noise function.

  • shape (Tuple[int, int]):
    The output shape of the noise. Most often, should probably be (area.screen_size, area.screen_size).

  • resolution (Tuple[int, int]):
    The output resolution of the noise. Could be thought of as the “altitude” and aspect ratio at which the data (1, 1) is seen.

  • seed (int):
    The random seed used to determine the terrain elevation so that the user can recreate repeatable terrain.

gaussian#

All arguments that would be passed into the gaussian function.

  • amplitude (int):
    The amplitude of the gaussian noise function.

  • mu_x (int):
    The mean of the 2D normal distribution in the x direction.

  • mu_y (int):
    The mean of the 2D normal distribution in the y direction.

  • sigma_x (int):
    The variance of the 2D normal distribution in the x direction.

  • sigma_x (int):
    The variance of the 2D normal distribution in the y direction.

fuel#

All configuration settings for the fuel in the simulation area.

type#

(str)
Can be either operational or functional.

If operational, will use the parameters in the Operational Parameters section to determine fuel in the simulation area.

If functional, will use the parameters in terrain.fuel.functional to determine fuel in the simulation area.

functional#

All configuration settings for determining the functional topography data layer.

function#

(str)
The function that determines how fuel is distributed throughout the simulation area. The available fuel functions are currently:

  • chaparral

chaparral#

All arguments that would be passed into the chaparral fuel array function.

  • seed (int):
    The random seed used to determine the fuel distribution so that the user can recreate repeatable fuel patterns.

Fire Parameters#

fire_initial_position#

(Tuple[int, int])
The initial location to start the fire. This should be set every time when running the simulation.

max_fire_duration#

(int)
The maximum number of frames that a single pixel can be on fire.

diagonal_spread#

(bool)
Whether or not to have the fire spread calculation apply to diagonal pixels. If this is true, the fire may spread through firelines that don’t take this into account.

Environment Parameters#

Defines the Environment class.

moisture#

(float)
Used in simulator fire spread calculation. Most of Southern California has the default value of 0.03.

Wind Parameters#

Defines wind speed and direction generation.

function#

(str)
The function that determines how wind is distributed throughout the simulation area. The available wind functions are currently:

  • cfd

  • simple

  • perlin

cfd#

A function for wind that uses a computational fluid dynamics (CFD) algorithm for wind modeling.

  • time_to_train (int):
    @ckempis: The time to train the CFD algorithm when preprocessing.

  • iterations (int):
    @ckempis

  • scale (int):
    @ckempis

  • timestep_dt (int):
    @ckempis

  • diffusion (int):
    @ckempis

  • viscosity (int):
    @ckempis

  • speed (int):
    @ckempis

  • direction (int):
    @ckempis

simple#

A function for wind that keeps direction and speed constant throughout the whole simulation area.

  • speed (int | float):
    The wind speed in miles per hour.

  • direction (int | float):
    The wind direction expressed in degrees clockwise from North (E.g. East == 90.0, South == 180.0, etc.).

perlin#

All arguments that would be passed into the WindController class.

speed#

All arguments that define wind speed layer generation.

  • seed (int):
    The random seed used to determine the wind speed layer so that the user can recreate repeatable wind speed layers.

  • scale (int):
    How large to make the noise. Can be seen as an “elevation”, but don’t take that literally.

  • octaves (int):
    How many passes/layers to the noise algorithm. Each pass adds more detail.

  • persistence (float):
    How much more each successive value brings. Keep between 0 and 1.0.

  • lacunarity (float):
    The level of detail added per pass. Usually kept at 2.0.

  • min (int| float):
    The minimum wind speed for any individual pixel location. Expressed in miles per hour.

  • max (int | float):
    The maximum wind speed for any individual pixel location. Expressed in miles per hour.

direction#

All arguments that define wind direction layer generation.

  • seed (int):
    The random seed used to determine the wind speed layer so that the user can recreate repeatable wind speed layers.

  • scale (int):
    How large to make the noise. Can be seen as an “elevation”, but don’t take that literally.

  • octaves (int):
    How many passes/layers to the noise algorithm. Each pass adds more detail.

  • persistence (float):
    How much more each successive value brings. Keep between 0 and 1.0.

  • lacunarity (float):
    The level of detail added per pass. Usually kept at 2.0.

  • min (int):
    The minimum wind direction for any individual pixel location. Expressed in degrees clockwise from North (E.g. East == 90.0, South == 180.0, etc.).

  • max (int):
    The maximum wind direction for any individual pixel location. Expressed in degrees clockwise from North (E.g. East == 90.0, South == 180.0, etc.).

Render Parameters#

Defines rendering.

inline#

(bool)
Whether or not to render at each call to the step() function in FirelineEnv.

post_agent#

(bool)
Whether or not to render with post agent in place.

post_agent_with_fire#

(bool)
Whether or not to render with post agent and fire in place.

Example Config File#

Go here for more examples.

Note

If this config doesn’t work, look to the most up-to-date version in the link above.

# For a description of config parameters, go to
# https://fireline.pages.mitre.org/simfire/config.html
area:
  screen_size: [225, 450] # h, w
  pixel_scale: 50

display:
  fire_size: 2
  control_line_size: 2
  agent_size: 4
  rescale_factor: 2

simulation:
  update_rate: 1
  runtime: 15h
  headless: false
  draw_spread_graph: false
  record: true
  save_data: true
  data_type: "npy"
  sf_home: "~/.simfire"

mitigation:
  ros_attenuation: false

operational:
  seed:
  latitude: 38.422 # top left corner
  longitude: -118.266 # top left corner
  height: 2000 # in meters
  width: 2000 # in meters
  resolution: 30 # in meters
  year: 2020

terrain:
  topography:
    type: operational
    functional:
      function: perlin
      perlin:
        octaves: 3
        persistence: 0.7
        lacunarity: 2.0
        seed: 827
        range_min: 100.0
        range_max: 300.0
      gaussian:
        amplitude: 500
        mu_x: 50
        mu_y: 50
        sigma_x: 50
        sigma_y: 50
  fuel:
    type: operational
    functional:
      function: chaparral
      chaparral:
        seed: 1113
    burn_probability:
      type: operational
      functional:
        function: perlin
        perlin:
          octaves: 3
          persistence: 0.7
          lacunarity: 2.0
          seed: 827
          range_min: 100.0
          range_max: 300.0
        gaussian:
          amplitude: 500
          mu_x: 50
          mu_y: 50
          sigma_x: 50
          sigma_y: 50


fire:
  fire_initial_position:
    type: static
    static:
      position: (25, 25)
    random:
      seed: 1234
  max_fire_duration: 5
  diagonal_spread: true

environment:
  moisture: 0.001

wind:
  function: perlin
  cfd:
    time_to_train: 1000
    result_accuracy: 1
    iterations: 1
    scale: 1
    timestep_dt: 1.0
    diffusion: 0.0
    viscosity: 0.0000001
    speed: 19.0
    direction: north
  simple:
    speed: 7
    direction: 90.0
  perlin:
    speed:
      seed: 2345
      scale: 400
      octaves: 3
      persistence: 0.7
      lacunarity: 2.0
      range_min: 7
      range_max: 47
    direction:
      seed: 650
      scale: 1500
      octaves: 2
      persistence: 0.9
      lacunarity: 1.0
      range_min: 0.0
      range_max: 360.0