Pyretechnics

A Python library for simulating fire behavior in a variety of ways.

Latest API Documentation: https://pyregence.github.io/pyretechnics/

Conda installation instructions: https://www.anaconda.com/docs/tools/working-with-conda/packages/pip-install

Overview

The Pyretechnics library provides modules that implement the fundamental equations used in most operational wildland fire behavior models like GridFire, ELMFIRE, FlamMap, FARSITE, FSIM, and BehavePlus. These fall into the following categories:

• pyretechnics.fuel_models: Fuel Model and Moisture Definitions
• pyretechnics.surface_fire: Surface Fire Equations
• pyretechnics.crown_fire: Crown Fire Equations
• pyretechnics.spot_fire: Spot Fire Equations
• pyretechnics.burn_cells: Burning Cells on a Grid
• pyretechnics.eulerian_level_set: Fire Spread Algorithm (ELMFIRE)

In addition, it provides a module for unifying 0D (constant), 1D (temporal), 2D (spatial), and 3D (spatiotemporal) input datasets (of potentially different resolutions) for fuels, topography, wind, and moisture called pyretechnics.space_time_cube.

The user of this library simply loads in their input datasets as Numpy arrays, wraps them in SpaceTimeCube objects to make all of their dimensions and resolutions match, and feeds them into the functions for burning cells (pyretechnics.burn_cells) or spreading a fire from a point or existing burn scar (pyretechnics.eulerian_level_set). The cell-burning functions will return the fire behavior metrics for the burned cell (i.e., fire type, spread rate, spread direction, fireline intensity, flame length) as a Python dictionary. The fire spreading functions return a dictionary containing these same metrics (+ time of arrival) in Numpy arrays, covering the simulation area.

Since the library's main functions take and return Numpy arrays, you are free to create them as needed for your own projects. You can load arrays from numerous geospatial file formats using the Python rasterio library. You could grab data from a PostGIS raster using psycopg2 or load in NetCDF files with the netCDF4 library. You could also create your own arrays using Numpy or Scipy functions based on your needs. And, of course, you could use these same libraries to apply random noise, value perturbations, or other preprocessing steps on the arrays before initiating fire spread simulations.

Similary, you can use any Python library or algorithm to post-process the output arrays into aggregate arrays (e.g., annual/conditional burn frequency), visualize them (e.g., with matplotlib), and/or write them out as raster files, CSVs, or any other format that you can think of.

Notably, Pyretechnics is written as a Literate Program, which you can read online here: https://pyregence.github.io/pyretechnics

Each module has its own dedicated chapter, with two subsections:

• For Developers
• For Users

The For Developers sections are the literate programming implementation of the equations and algorithms included in that module. Read these sections if you want to understand the science and engineering behind that module.

The For Users sections are notebook programming examples of how to use the public functions in each module along with their computed outputs. If you just want to use the Pyretechnics library, you can jump to these sections and cut-and-paste the example scripts into your own Python file or Jupyter notebook to get yourself going quickly.

Design Principles

Free and Open Source Software

To promote open review and encourage collaborative development of the various algorithms implemented in Pyretechnics, this library is released under a free and open source license. See the License section in this document for more information.

Reproducible Research

One of the most persistently challenging aspects of software development is the fact that the environments in which software is built vary from one person's computer to another, including but not limited to different types and versions of operating systems, applications, libraries, and services installed. Since most software, including Pyretechnics, is written so as to rely on external libraries and applications at both build and run time, it is necessary to be able to easily reproduce the computer environments needed for these steps on new users' machines.

To do so, Pyretechnics uses GNU Guix to automatically install software dependencies and create ephemeral development environments without requiring root privileges or interfering with the main package manager of the underlying operating system.

If you are running a GNU/Linux distribution on your computer, the easiest way to install Guix is to simply follow the "Binary Installation" instructions in the manual here:

https://guix.gnu.org/manual/en/html_node/Binary-Installation.html

This will add the guix command as an auxiliary package, environment, and container manager on your machine.

If you are not running GNU/Linux, you will need to run Guix System in a virtual machine. This is a complete GNU/Linux distribution that uses Guix as its package manager and Shepherd as its service manager. You can find instructions on getting this installed and running through QEMU in the "Running Guix in a Virtual Machine" section of the Guix manual here:

https://guix.gnu.org/manual/en/html_node/Running-Guix-in-a-VM.html

1. Creating a Reproducible Development Environment

   Once installed, you can tell Guix to download all the necessary dependencies for Pyretechnics development and enter a shell in which they are available by running this command from the root directory of this repository:

   ./make.sh shell

   On its first invocation, this command will download the necessary software packages and install them under /gnu/store. When this is done, you will be dropped into a shell environment in which the environment variables have been automatically configured to point to these newly downloaded packages.

   On subsequent calls to ./make.sh shell, you should be dropped directly into the shell environment without the need to install any new software unless the guix.scm or channels.scm files have been updated.

2. Authorizing Guix to Automatically Read guix.scm

   The first time that you run ./make.sh shell, you will be prompted to authorize Guix to read the guix.scm file in this repository for instructions on what to download and how to set up your ephemeral shell environment. Assuming you have set the PYRETECHNICS_REPO shell variable to the directory containing this repository, you can do so with this command:

   echo $PYRETECHNICS_REPO >> $HOME/.config/guix/shell-authorized-directories

3. Exiting the Reproducible Development Environment

   You can always exit from the shell with this command:

   exit

4. Running the Test Suite

   You can run the Pyretechnics library's test suite by invoking pytest through the Guix shell like so:

   ./make.sh test

5. Building the Pyretechnics Library with Guix

   To build the Pyretechnics library, including running its tests, constructing a Python wheel, and unpacking it into the Guix /gnu/store directory, simply run this command:

   ./make.sh build-guix

6. Building the Pyretechnics Library as a Distribution

   To create a dist folder containing source (.tar.gz) and built (.whl) distributions of the Pyretechnics library, you can run this command:

   ./make.sh build-dist

7. Uploading the Built Distribution to TestPyPI

   To upload the built distribution to TestPyPI, you can use this command:

   ./make.sh upload-testpypi

   You will be prompted for a username and password. For the username, use __token__. For the password, use the TestPyPI API token value that you created here, including the pypi- prefix.

8. Uploading the Built Distribution to PyPI

   To upload the built distribution to PyPI, you can use this command:

   ./make.sh upload-pypi

   You will be prompted for a username and password. For the username, use __token__. For the password, use the PyPI API token value that you created here, including the pypi- prefix.

9. Installing the Pyretechnics Library with Guix

   You have two options for installing the Pyretechnics library locally:

   First, you can simply install it into a temporary shell environment like so:

   ./make.sh install-shell

   You can leave this shell by typing exit.

   Your second option is to install the Pyretechnics library into your Guix profile with this command:

   ./make.sh install-guix

   Next, you will need to invoke the following Bash commands in your shell to make the newly installed library available via $GUIX_PYTHONPATH. This environment variable is referenced automatically by the Guix-installed Python package.

   GUIX_PROFILE="$HOME/.guix-profile"
   . "$GUIX_PROFILE/etc/profile"

   It is recommended that you add these two lines to your $HOME/.bash_profile, so that they are run automatically each time you login.

10. Using the Pyretechnics Library

    Once you have installed the library into a temporary shell environment, installed it into your Guix profile, or downloaded it from PyPI, you should be able to launch python and load the library as follows:

    import pyretechnics

Literate Programming

Pyretechnics has been coded as a literate program using Emacs' org-mode. This means that its source code is embedded within a larger document, which explains the rationale behind the code using text, equations, citations, tables, and figures. The reason for this approach is to make the science and engineering decisions within Pyretechnics fully transparent to our users, whether or not they feel confident reading source code directly. We believe that this better promotes the goals of open science than open source software alone.

What this means practically is that the org directory in this software repository contains a single literate program document called org/pyretechnics.org, which is used to automatically generate all of the other source code and documentation files within this repository.

1. Regenerating HTML Documentation

   The latest HTML documentation can always be found in docs/index.html.

   After editing org/pyretechnics.org, you can regenerate the HTML documentation by running this command:

   ./make.sh weave

2. Regenerating the Source Code Tree

   After editing org/pyretechnics.org, you can regenerate all the source code files in this repository by running this command:

   ./make.sh tangle

3. Bringing Source Code File Edits Back into the Literate Program

   If you edit a source code file directly, its changes can be automatically incorporated back into the literate program by running this command:

   ./make.sh detangle

4. Running All the Source Code Blocks in the Literate Program

   If your changes would impact the results of the example code blocks in the literate program, then you can run them again to update their results in org/pyretechnics.org with this command:

   ./make.sh org-eval

Contact

Authors

• Gary W. Johnson, PhD

  • Email: gjohnson@sig-gis.com
  • Web: https://sig-gis.com

• Valentin Waeselynck

  • Email: vwaeselynck@sig-gis.com
  • Web: https://sig-gis.com

• Chris Lautenberger, PhD, PE

  • Email: chris@cloudfire.com
  • Web: https://cloudfire.com

• David Saah, PhD

  • Email: dsaah@sig-gis.com
  • Web: https://sig-gis.com

License

Copyright © 2023-2025 Spatial Informatics Group, LLC.

Pyretechnics is distributed by Spatial Informatics Group, LLC. under the terms of the Eclipse Public License version 2.0 (EPLv2). See LICENSE in this directory for more information.