Running BurnP3+ on Linux

Here we provide a complete guide to setting up and running BurnP3+ on Linux using the SyncroSim console and the rsyncrosim R package, no GUI required.

BurnP3+ is a SyncroSim package that simulates wildfire ignition, spread, and suppression over many thousands of iterations to produce spatially explicit burn probability maps. It uses FireSTARR (or other fire growth engines) under the hood and requires spatial inputs including weather streams, fuel grids, topography, and ignition zones. Full BurnP3+ documentation is available at https://burnp3.github.io/BurnP3Plus.

Most BurnP3+ workflows assume you are working through the SyncroSim Studio graphical interface on Windows. However, if you are running analyses on a Linux server, a high-performance computing (HPC) cluster, or an automated pipeline, you need to work headlessly. This guide walks through everything required to get BurnP3+ running on Linux, from a bare system all the way through a complete model run using both the SyncroSim console and the rsyncrosim R package. Throughout this tutorial, terminology associated with SyncroSim will be italicized, and whenever possible, links will be provided to the SyncroSim online documentation.


Linux Tutorial

This tutorial will walk you through running BurnP3+ on Linux. The steps include:

  1. Installing SyncroSim on Linux
  2. Installing BurnP3+ and FireSTARR
  3. Running BurnP3+ from the SyncroSim console
  4. Troubleshooting


Step 1: Installing SyncroSim on Linux

Before you begin, make sure the following are in place:

Why Mono? SyncroSim is a .NET application. On Linux, it runs via Mono, which provides the runtime environment. On Windows, the native .NET runtime is used instead.

Why Conda? SyncroSim needs GDAL C# bindings to read and write spatial raster files. On Linux, Conda is used only to provide these bindings — the actual spatial libraries (GDAL, PROJ, GEOS) are installed system-wide via apt.


Install Mono

Mono provides the .NET runtime needed to execute SyncroSim on Linux.

Ubuntu / Debian

On Ubuntu or Debian-based systems, add the official Mono repository and install using the gpg --keyring method (required on Ubuntu 22.04 and later):

# Install GPG dependencies (required on minimal Ubuntu cloud images)
sudo apt-get update
sudo apt-get install -y gnupg2 dirmngr

# Initialize the gnupg directory for root
sudo gpg --list-keys

# Import the Mono signing key into a dedicated keyring file
sudo gpg --no-default-keyring \
    --keyring /usr/share/keyrings/mono-keyring.gpg \
    --keyserver hkp://keyserver.ubuntu.com:80 \
    --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF

# Add the Mono repository, referencing the keyring
echo "deb [signed-by=/usr/share/keyrings/mono-keyring.gpg] \
    https://download.mono-project.com/repo/ubuntu stable-focal main" \
    | sudo tee /etc/apt/sources.list.d/mono-official-stable.list

sudo apt-get update
sudo apt-get install -y mono-complete

RHEL / Rocky Linux / Fedora

On Red Hat-based systems, Mono is installed via an RPM repository. Follow the official instructions for your distribution at mono-project.com/download/stable; the steps vary slightly between RHEL versions.

Other distributions (Arch, openSUSE, etc.): Use your distribution’s package manager to install mono-complete or an equivalent package. Refer to the Mono project documentation for distro-specific guidance.

Always install the latest version of Mono — there is no hard minimum, but older builds can exhibit compatibility issues with SyncroSim. Verify your installation:

mono --version
# Mono JIT compiler version 6.x.x.xxx


Install Miniconda

Conda is used to set up the GDAL environment that SyncroSim needs for spatial operations. Install Miniconda, which is a lightweight version of the full Conda distribution:

curl -fsSL https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh \
    -o /tmp/miniconda.sh
bash /tmp/miniconda.sh -b -p $HOME/miniconda3
rm /tmp/miniconda.sh

# Initialize conda for your shell
$HOME/miniconda3/bin/conda init bash
source ~/.bashrc

It is good practice to configure conda-forge as your primary channel and disable the default channel to avoid package conflicts:

conda config --remove channels defaults 2>/dev/null || true
sed -i '/defaults/d' $HOME/miniconda3/.condarc 2>/dev/null || true
conda config --add channels conda-forge
conda config --set channel_priority strict


Install SyncroSim

Download and extract the SyncroSim Linux build. You can find the latest version number on the SyncroSim downloads page:

# Download SyncroSim (adjust version as needed)
curl -fsSL "https://downloads.syncrosim.com/3-1-29/syncrosim-linux-3-1-29.zip" \
    -o /tmp/syncrosim.zip

sudo apt install unzip
unzip -q /tmp/syncrosim.zip -d $HOME/syncrosim
rm /tmp/syncrosim.zip

# Make the executables executable
chmod 755 $HOME/syncrosim/SyncroSim.Console.exe \
          $HOME/syncrosim/SyncroSim.PackageManager.exe

For convenience, create shell wrappers so you can invoke ssim and ssimpm from anywhere on the system:

SYNCROSIM_DIR="$HOME/syncrosim"

sudo tee /usr/local/bin/ssim > /dev/null << EOF
#!/bin/bash
mono ${SYNCROSIM_DIR}/SyncroSim.Console.exe "\$@"
EOF

sudo tee /usr/local/bin/ssimpm > /dev/null << EOF
#!/bin/bash
mono ${SYNCROSIM_DIR}/SyncroSim.PackageManager.exe "\$@"
EOF

sudo chmod +x /usr/local/bin/ssim /usr/local/bin/ssimpm

Note: If you are working in a shared environment or HPC cluster without sudo access, add $HOME/bin to your PATH and place the wrapper scripts there instead.


Install system spatial libraries

BurnP3+ requires several spatial C libraries for raster and vector operations. Install them system-wide via apt:

sudo apt-get install -y \
    libgdal-dev \
    libproj-dev \
    libgeos-dev \
    libsqlite3-dev \
    libspatialite-dev \
    libudunits2-dev \
    gdal-bin \
    proj-bin

Verify the installations:

gdal-config --version
proj

Set up the GDAL Conda environment

SyncroSim requires GDAL C# bindings (.dll files) to interface with spatial raster files. These are provided by the gdal-csharp conda package. Note that this conda environment is only used during setup to copy the bindings into the SyncroSim folder — it does not need to be activated at runtime.

# Create a new environment named "gdal-mono" (do not install gdal into base environment)
conda create -y --name gdal-mono gdal-csharp=1.1.1

# Copy the GDAL C# bindings into the SyncroSim folder
cp $HOME/miniconda3/envs/gdal-mono/lib/*_csharp.dll $HOME/syncrosim/
cp $HOME/miniconda3/envs/gdal-mono/lib/*.so* $HOME/syncrosim/

# Remove libraries that conflict with system versions
rm $HOME/syncrosim/libsqlite3.so*
rm -f $HOME/syncrosim/libproj.so*
rm -f $HOME/syncrosim/libgeos*.so*
rm -f $HOME/syncrosim/libgdal.so*
rm -f $HOME/syncrosim/libspatialite.so*
rm -f $HOME/syncrosim/libcurl.so*

# Create symlink so SyncroSim can find libspatialite
sudo ln -s /lib/x86_64-linux-gnu/libspatialite.so.8 \
           /lib/x86_64-linux-gnu/libspatialite.so.7
sudo ldconfig

What this does: The gdal-csharp package provides the “glue” between SyncroSim (a .NET application) and GDAL (a C library). Copying the .dll files into the SyncroSim folder makes them available when SyncroSim starts up. The system spatial libraries installed in the previous step are used at runtime instead of the conda versions, which avoids library conflicts.

Now, tell SyncroSim where your Conda installation lives:

ssim --conda --path="$HOME/miniconda3"

This registers the Conda path in SyncroSim’s configuration so it can locate the environment at runtime.


Configure your environment for runtime

Before running any spatially explicit model, set the library search path so SyncroSim can find its bundled libraries:

export LD_LIBRARY_PATH=$HOME/syncrosim:${LD_LIBRARY_PATH:-}

Note: Unlike the Windows workflow, you do not need to activate a conda environment before running BurnP3+ on Linux. The conda environment (gdal-mono) was only needed during setup to provide the GDAL C# bindings. All spatial operations at runtime use the system libraries installed via apt.

Add this line to your ~/.bashrc if you are running BurnP3+ frequently:

echo 'export LD_LIBRARY_PATH=$HOME/syncrosim:${LD_LIBRARY_PATH:-}' >> ~/.bashrc

Install R Package Dependencies

BurnP3+ and FireSTARR require the following R packages. First install R and all required system dependencies:

# Install R
sudo apt-get install -y r-base r-base-dev
R --version

# Install system dependencies required for R spatial packages
sudo apt-get install -y \
    cmake \
    libssl-dev \
    libabsl-dev \
    libfontconfig1-dev \
    libfreetype-dev \
    libharfbuzz-dev \
    libfribidi-dev

Then install the R packages from source so they compile against the system spatial libraries installed earlier:

sudo Rscript -e "
pkgs = c('data.table', 'lubridate', 'rlang', 'rsyncrosim', 's2', 'sf', 'terra', 'tidyverse')
pkgs_to_install = pkgs[!pkgs %in% rownames(installed.packages())]
if (length(pkgs_to_install) > 0) install.packages(pkgs_to_install, type='source', repos='https://cloud.r-project.org')
"

# Install a compatible version of arrow — BurnP3+ 2.6.5 requires arrow >= 14.0.1
sudo Rscript -e "install.packages('arrow', type='source', repos='https://cloud.r-project.org')"

# Verify all packages installed correctly
sudo Rscript -e "
pkgs = c('data.table', 'lubridate', 'rlang', 'rsyncrosim', 'sf', 'terra', 'tidyverse', 'arrow')
for (p in pkgs) cat(p, ':', as.character(packageVersion(p)), '\n')
"

Why install from source? Installing from source ensures R packages compile against the system spatial libraries (GDAL, PROJ, GEOS) rather than pre-built binaries that may link against incompatible versions. Note that tidyverse and arrow can take 10–15 minutes to compile.


Step 2: Installing BurnP3+ and FireSTARR

BurnP3+ is distributed as a SyncroSim package. The FireSTARR fire growth engine is distributed as a companion package. There are two ways to install them: directly from the SyncroSim package server (recommended), or from a local file (useful for airgapped or offline systems).

Install from the package server

The easiest approach is to install directly using the SyncroSim package manager, which downloads and installs the package in one step:

# Install BurnP3+ from the package server
ssimpm --install=burnP3Plus --version=2.6.5

# Install the FireSTARR companion package
ssimpm --install=burnP3PlusFireSTARR --version=1.5.5

Tip: Check the BurnP3Plus GitHub releases page for the current version numbers of BurnP3+ and its compatible FireSTARR release. Always install versions that are listed as compatible with each other.

Verify the packages installed correctly:

ssimpm --list --installed

You should see burnP3Plus and burnP3PlusFireSTARR in the output.

After installing the packages, ensure the FireSTARR binary is executable:

chmod +x $HOME/syncrosim/Packages/burnP3PlusFireSTARR/*/tbd

Why this is needed: On Linux, the FireSTARR executable (tbd) is not automatically marked as executable when the package is installed. Without this step, FireSTARR will appear to run but will silently produce no output, causing Transformer 3 to complete in under 2 seconds with no fires burned.

Offline / Airgapped Install

If your server does not have internet access, download the package files on another machine and transfer them manually. Download the .ssimpkg files from the BurnP3Plus GitHub releases page, then copy them to the server using scp.

First, on the server, create the destination directory:

mkdir -p $HOME/burnp3

Then, on your local machine, transfer the files:

scp -i /path/to/your-key.pem \
    /path/to/burnP3Plus-2-6-5.ssimpkg \
    /path/to/burnP3PlusFireSTARR-1-5-5.ssimpkg \
    ubuntu@<server-ip>:$HOME/burnp3/

Windows users (PowerShell): The backslash line continuation used above is bash syntax and will not work in PowerShell. Use backticks for line continuation, quote the filenames, and use the literal /home/ubuntu path instead of $HOME (which PowerShell will not expand on the remote side):

scp -i C:\path\to\your-key.pem `
    "C:\path\to\burnP3Plus-2-6-5.ssimpkg" `
    "C:\path\to\burnP3PlusFireSTARR-1-5-5.ssimpkg" `
    ubuntu@<server-ip>:/home/ubuntu/burnp3/

Replace /path/to/your-key.pem with your SSH key, /path/to/ with the local directory containing the .ssimpkg files, and <server-ip> with your server’s IP address or hostname.

Then, back on the server, install from the local package files:

# Run this on the SERVER
ssimpm --finstall="$HOME/burnp3/burnP3Plus-2-6-5.ssimpkg"
ssimpm --finstall="$HOME/burnp3/burnP3PlusFireSTARR-1-5-5.ssimpkg"
ssimpm --list --installed

chmod +x $HOME/syncrosim/Packages/burnP3PlusFireSTARR/*/tbd


Step 3: Running BurnP3+ from the SyncroSim console

With SyncroSim and BurnP3+ installed, you can run any BurnP3+ library entirely from the command line. This is the approach you would use in a batch script, cron job, or HPC job submission. The full SyncroSim console reference is available at docs.syncrosim.com/reference/console_core.html.

A SyncroSim library (.ssim file) is the top-level container for a modeling project. Inside a library, you have one or more projects, and within each project, one or more scenarios. A scenario defines all the model inputs and configuration for a single run. When running from the console, you reference scenarios by their scenario ID — an integer assigned when the scenario is created. To list the scenarios available in a library:

SSIMLIB=/path/to/your/burnp3.ssim
ssim --lib=$SSIMLIB --list --scenarios


Configuring run control and multiprocessing

Before running a scenario, configure how many fire iterations to run and how many CPU cores to use. In SyncroSim, these settings live in datasheets — named tables that hold model configuration. You can import datasheet values from CSV files using the console.

Create a Run_Control.csv with your iteration settings:

cat > $HOME/burnp3/Run_Control.csv << 'EOF'
MinimumIteration,MaximumIteration,MinimumTimestep,MaximumTimestep
1,100,1,1
EOF

Create a Multiprocessing.csv to enable parallel processing:

cat > $HOME/burnp3/Multiprocessing.csv << 'EOF'
EnableMultiprocessing,MaximumJobs,EnableMultiScenario,EnableCopyExternalFiles
Yes,7,,
EOF

Note: Set MaximumJobs to one less than the total number of available CPU cores, leaving one core free for the system. The example above uses 7, appropriate for an 8-core machine. Setting this value higher than the number of available cores can cause FireSTARR jobs to silently produce no output.

Then import them into your scenario before running:

ssim --import --lib=$SSIMLIB --sheet=burnP3Plus_RunControl \
     --sid=1 --file=$HOME/burnp3/Run_Control.csv

ssim --import --lib=$SSIMLIB --sheet=core_Multiprocessing \
     --sid=1 --file=$HOME/burnp3/Multiprocessing.csv

Set MaximumJobs to match the number of CPU cores you want to use. On an HPC cluster, this should match the number of cores allocated to your job (e.g., $SLURM_CPUS_PER_TASK).


Running a scenario 

# Set library path so SyncroSim can find its bundled libraries
export LD_LIBRARY_PATH=$HOME/syncrosim:${LD_LIBRARY_PATH:-}

# Run scenario with ID 1 in your library
ssim --lib=$SSIMLIB --run --sid=1 --verbose

Note: if you have not signed into your syncrosim account, run ssim --signin and follow the prompts to complete the sign-in process before running the scenario

The table below summarizes the most useful console flags. For a complete reference, see docs.syncrosim.com/reference/console_core.html.

Flag Description
--lib=<path> Path to the .ssim library file
--run Execute a model run
--sid=<id> Scenario ID to run
--pid=<id> Project ID (useful for project-level operations)
--list List scenarios or projects in the library
--export Export data from a scenario
--import Import data into a scenario
--sheet=<name> Datasheet name (used with --import / --export)
--file=<path> CSV file path (used with --import / --export)
--trx=<name> Run a specific transformer by name
--inplace Write results back to the parent scenario
--verbose Stream log output to the console during a run


Running individual transformers

BurnP3+ runs a pipeline of processing steps called transformers. Normally, running a scenario executes all transformers in sequence automatically. However, you can also run each transformer individually — this is useful for debugging, restarting a failed run mid-pipeline, or inspecting intermediate outputs.

A full BurnP3+ run consists of four stages:

SSIMLIB=/path/to/your/burnp3.ssim

# Stage 1 — Generate ignition locations
ssim --lib=$SSIMLIB --run --sid=1 \
     --trx=burnP3Plus_generateIgnitions --inplace --verbose

# Stage 2 — Generate burning conditions (weather)
ssim --lib=$SSIMLIB --run --sid=1 \
     --trx=burnP3Plus_generateBurningConditions --inplace --verbose

# Stage 3 — Run fire growth (FireSTARR)
ssim --lib=$SSIMLIB --run --sid=1 \
     --trx=burnP3PlusFireSTARR_fireGrowthFireSTARR --inplace --verbose

# Stage 4 — Compute burn probability
ssim --lib=$SSIMLIB --run --sid=1 \
     --trx=burnP3Plus_burnProbability --verbose

--inplace writes results back into the parent scenario rather than creating a new result scenario. Use this when running transformers individually to ensure results accumulate correctly.

--verbose streams the transformer’s log output to the console as it runs, which makes it easier to follow progress and diagnose errors.


Example SLURM job script

If you are running BurnP3+ on an HPC cluster running SLURM, a minimal job script looks like this:

#!/bin/bash
#SBATCH --job-name=burnp3_run
#SBATCH --cpus-per-task=16
#SBATCH --mem=64G
#SBATCH --time=12:00:00
#SBATCH --output=burnp3_%j.out
#SBATCH --error=burnp3_%j.err

source ~/.bashrc
export LD_LIBRARY_PATH=$HOME/syncrosim:${LD_LIBRARY_PATH:-}

SSIMLIB=$HOME/projects/burnp3/my_project.ssim

cat > /tmp/mp.csv << EOF
EnableMultiprocessing,MaximumJobs,EnableMultiScenario,EnableCopyExternalFiles
Yes,$SLURM_CPUS_PER_TASK,,
EOF

ssim --import --lib=$SSIMLIB --sheet=core_Multiprocessing \
     --sid=1 --file='/tmp/mp.csv'

ssim --lib=$SSIMLIB --run --sid=1

echo "BurnP3+ run complete."

Note: Replace $HOME/projects/ with the appropriate path for your cluster. Many HPC systems provide a $WORK or $SCRATCH-equivalent variable for project storage — check your cluster’s documentation for the recommended location for large data files.

Submit with:

sbatch run_burnp3.sh


Step 4: Troubleshooting

GDAL load failures

Symptom: SyncroSim errors on startup or when opening a spatial library, with messages like Unable to load DLL 'gdal_csharp' or GDAL not found.

Fix: Verify that the .dll files were copied into your SyncroSim directory during setup:

ls $HOME/syncrosim/*_csharp.dll

Also ensure LD_LIBRARY_PATH includes the SyncroSim directory:

export LD_LIBRARY_PATH=$HOME/syncrosim:${LD_LIBRARY_PATH:-}

If the .dll files are missing, re-run the copy step from the GDAL setup section above.

Mono version issues

Symptom: SyncroSim crashes on launch, or you see cryptic .NET runtime errors.

Fix: Ensure you have a recent version of Mono installed (6.x or later). Run mono --version to check. If you installed Mono from your distribution’s default package manager rather than the official Mono repository, you may have an older version — follow the Mono install instructions above to install from the official source.

Package version mismatch errors

Symptom: After installing BurnP3+ and FireSTARR, SyncroSim reports a version mismatch or a package fails to load.

Fix: BurnP3+ and FireSTARR must be installed as compatible versions. Check the BurnP3+ releases page to confirm which FireSTARR version is required for your BurnP3+ release. Uninstall and reinstall the mismatched package:

ssimpm --uninstall=burnP3PlusFireSTARR
ssimpm --install=burnP3PlusFireSTARR --version=<correct_version>

SQLite crash on library open
Symptom: SyncroSim crashes with a SIGSEGV and a managed stacktrace pointing to Mono.Data.Sqlite.UnsafeNativeMethods:sqlite3_open_v2 when trying to open a .ssim library file.

Fix: The conda-forge version of libsqlite3 copied from the gdal-mono environment is incompatible with Mono’s SQLite bindings. Remove it and let Mono fall back to the system version:

rm $HOME/syncrosim/libsqlite3.so*

R package load failures (terra, sf, or others)

Symptom: A transformer fails with an error like:

unable to load shared object '.../terra/libs/terra.so':
  /usr/lib/x86_64-linux-gnu/libspatialite.so.8: undefined symbol: freexl_get_worksheets_count

Fix: This is a known incompatibility on Ubuntu 24.04 between pre-built R package binaries and the system libspatialite/libfreexl versions. First ensure the correct system libraries are installed. Note that the package name for libspatialite varies by Ubuntu version:

# Ubuntu 24.04
sudo apt-get install -y libspatialite8t64 libfreexl1

# Ubuntu 20.04 / 22.04
sudo apt-get install -y libspatialite7 libfreexl1

sudo ldconfig

Then reinstall the affected R packages from source so they compile against the correct libraries:

sudo Rscript -e "install.packages(c('terra', 'sf'), type='source', repos='https://cloud.r-project.org')"

If other packages show the same error, reinstall them from source using the same approach.

Segfault when loading spatial rasters

Symptom: A transformer crashes with a segfault (caught segfault, address (nil)) when trying to open a .tif file, with a traceback pointing to rast() or SpatRaster$new().

Fix: This is caused by conflicting versions of spatial libraries (GDAL, PROJ, GEOS) between the SyncroSim folder and the system. The SyncroSim folder should only contain the GDAL C# bindings, not the full spatial libraries. Remove any conflicting libraries:

rm -f $HOME/syncrosim/libproj.so*
rm -f $HOME/syncrosim/libgeos*.so*
rm -f $HOME/syncrosim/libgdal.so*
rm -f $HOME/syncrosim/libspatialite.so*
rm -f $HOME/syncrosim/libcurl.so*
sudo ldconfig

Then verify R packages are linking against system libraries:

ldd $(sudo Rscript -e "cat(system.file('libs/terra.so', package='terra'))") | grep -E "gdal|proj|geos"

All paths should point to /lib/x86_64-linux-gnu/.


For more on SyncroSim, visit syncrosim.com. BurnP3+ package documentation is available at apexrms.github.io/burnP3Plus. The full SyncroSim console reference can be found at docs.syncrosim.com/reference/console_core.html.