11  Managing simulation experiments

The iLand viewer (iland.exe) is an excellent tool for designing, initializing, evaluating, debugging, and visualizing your iLand landscape and simulation experiment. However, once you are ready to scale up from a single simulation run to a set of simulation scenarios (e.g., different climate, disturbance, or management scenarios) and multiple replications, it is much more efficient to automate this process. To do this, you can use the iLand console (ilandc.exe), which runs on both Windows and Linux platforms, and a shell script written in, e.g., Windows CMD or in bash. The critical first step of this process is making sure you are using the same version of the iLand viewer and iLand console. To check this, open iland.exe and go to Help > About iLand and note both the SVN-Revision number and build date. Then navigate to the iLand executable folder and enter ilandc.exe in a command line window and compare.

11.1 Command line parameters

The iLand console requires two inputs, the project file and the number of simulation years, and can take any number of additional options.

Listing 11.1: A generic example of running ilandc in the command-line. years and additional-options are placeholders that have to be replaced by actual values, see Listing 11.2.

# command-line input
ilandc.exe project-file.xml <years> <additional-options>

Additional inputs include any settings in the project file and should be specified following the hierarchical structure of the XML below the <project> level. For example, a different input climate database could be specified with database.climate.out=new_climate.sqlite or a different sequence of prescribed disturbance events could be specified with
model.world.timeEventsFile=timeevents_2.txt.
Additional inputs can also include a javascript function run on model creation or simulation end.

Listing 11.2: A more specific example of running ilandc in bash (for the general syntax see Listing 11.1). The simulation setup is defined in site_1.xml and the simulation will run for 1000 years. Additional options are given that substitute corresponding values in site_1.xml.

#!/bin/bash
# "\" indicates line continuation
# make sure there is NO space after "\"
iland/ilandc.exe site_1.xml 1000 \
system.database.out=output_site_1.sqlite \
system.logging.logFile=log/log_site_1.txt \
model.site.availableNitrogen=50 \
model.site.soilDepth=100 \
model.site.pctSand=40 \
model.site.pctSilt=40 \
model.site.pctClay=20 \
model.climate.tableName=site_1

For additional examples and more detail, see the iLand console wiki page.

You can check the console output and/or the iLand log file to ensure that XML settings are being modified as expected.

11.2 Running multiple scenarios and replicates

The ability to modify any settings in the project file from the command line makes it straightforward to run many different simulation scenarios and multiple replicates in sequence or in parallel on a local machine or server. Scenarios can be specified in a file to run in sequence, as input arguments to a shell script to enable running in parallel, or as a combination of the two.

Here is an example of a .csv file with different climate and disturbance scenarios, each with 10 replicates.

gcm,rcp,wind_speed_mult,nreps
ICHEC-EC-EARTH,rcp45,0,10
ICHEC-EC-EARTH,rcp85,0,10
ICHEC-EC-EARTH,rcp45,15,10
ICHEC-EC-EARTH,rcp85,15,10
MPI-M-MPI-ESM-LR,rcp45,0,10
MPI-M-MPI-ESM-LR,rcp85,0,10
MPI-M-MPI-ESM-LR,rcp45,15,10
MPI-M-MPI-ESM-LR,rcp85,15,10

These can be used as inputs in a script to sequentially run iLand. Example bash script:

#!/bin/bash
# bash script to run iland for a list of scenarios
# usage: bash scripts/run_iland_local.sh 

#####
# variables and arguments
#####

# set variables
# set this path to location of iland exe
path="/c/Users/user1/iland_executable/" 
simulation_years="80"
csv_name="iland/main_file.csv" # csv filename
xml="cc_wind.xml"

#####
# loop through csv and run iland for each scenario
#####

# read in line by line, assign to variable
sed 1d $csv_name | while IFS=, read -r gcm rcp wind nreps
do 
    for rep in $(seq 1 $nreps)
    do
        echo "running gcm $gcm with wind speed $wind rep $rep"

        # run iland with scenario settings
        ${path}ilandc.exe iland/${xml} $simulation_years \
        system.database.out=output_${gcm}_${wind}_${rep}.sqlite \
        system.database.climate=${gcm}.sqlite \
        model.world.timeEventsFile=timeevents_${rcp}_${wind}_${rep}.txt
  
    done
done

To run this script in bash, enter:

bash scripts/run_iland_local.sh

The script could alternatively include arguments, such as replicate number, that would make it easy to run multiple simulations in parallel. For example, the below script allows running all simulation scenarios for only a specified range of replicates:

#!/bin/bash
# bash script to run iland for a list of scenarios
# usage: bash scripts/run_iland_local.sh [start_rep] [end_rep]

#####
# variables and arguments
#####

# arguments
start_rep=$1
end_rep=$2

# set variables
# set this path to location of iland exe
path="/c/Users/user1/iland_executable/" 
simulation_years="80"
csv_name="iland/main_file.csv" # csv filename
xml="cc_wind.xml"

#####
# loop through csv and run iland for each scenario
#####

# read in line by line, assign to variable
sed 1d $csv_name | while IFS=, read -r gcm rcp wind nreps
do 
    for rep in $(seq $start_rep $end_rep)
    do
        echo "running gcm $gcm with wind speed $wind rep $rep"

        # run iland with scenario settings
        ${path}ilandc.exe iland/${xml} $simulation_years \
        system.database.out=output_${gcm}_${wind}_${rep}.sqlite \
        system.database.climate=${gcm}.sqlite \
        model.world.timeEventsFile=timeevents_${rcp}_${wind}_${rep}.txt
  
    done
done

To run this script in bash for a single replicate (e.g., replicate 4), enter:

bash scripts/run_iland_local.sh 4 4

11.3 Pre-processing outputs

The same automation and scripting approach can be used to pre-process iLand outputs, for example using an .R script. This may be desirable if detailed iLand outputs (i.e., large file sizes) are needed, but then the same set of steps are applied to generate the dataset used for one’s analysis. For example, Braziunas et al. (2021) applied a custom calculation to estimate fire intensity from iLand outputs. This required detailed information on stand structure, species composition, and sapling cohorts by resource unit, as well as fire spread rasters for each fire event. By adding a pre-processing step, they were able to automate the computationally intensive process of calculating fire intensity, delete the large iLand output files, and save a much smaller output file for each simulation replicate. Scripts associated with this project are on GitHub.

Listing 11.3: Example bash script with pre-processing iLand output

#!/bin/bash
# bash script to run iland for a list of scenarios
# usage: bash scripts/run_iland_local.sh [reps]

#####
# arguments and other variables
#####

# arguments
nreps=$1

# other variables
# set this path to location of iland exe
path="/c/Users/user1/iland_executable/" 
simulation_years="120"
csv_name="iland/main_file.csv" # csv filename

#####
# loop through csv and run iland for each scenario
#####

# read in line by line, assign to variable
sed 1d $csv_name | while IFS=, read -r forest_type scen gcm kbdi
do 
    for rep in $(seq 1 $nreps)
    do
    
        echo "running forest type $forest_type management scenario $scen \
        gcm $gcm"

        # management javascript file requires two inputs,
        # which change with each management scenario. 
        # Here, I switch out these inputs for a given scenario 
        and rep, each of
        # which has a unique clustered or dispersed management 
        configuration generated
        # from a neutral landscape model.
        cp iland/gis/mgmt/${scen}_${rep}.txt iland/gis/mgmt/scenario_map.txt
        cp iland/gis/mgmt/${scen}_${rep}.csv iland/gis/mgmt/scenario_rids.csv

        # run each scenario
        ${path}ilandc.exe iland/${forest_type}_${scen}.xml $simulation_years \
        model.world.environmentFile=gis/${forest_type}_\
        ${gcm}_environment.txt \
        system.database.out=${forest_type}_${gcm}_${scen}_\
        output_${rep}.sqlite \
        modules.fire.KBDIref=$kbdi

        # reduce outputs with R code
        Rscript.exe iland/scripts/iland_output_prep.R
        Rscript.exe iland/scripts/fire_intensity.R
        
        # clean up
        rm output/${forest_type}_${gcm}_${scen}_output_${rep}.sqlite
        rm output/fire/*
  
    done
done

11.4 Running on a cluster

To further decrease the time required to complete simulations, iLand can be run on a compute cluster, which enables running many scenarios and replicates in parallel across multiple machines. This process requires compiling iLand on the compute cluster and preparing other files and scripts based on the cluster management software. If supported, pre-processing of outputs can also be included in compute cluster runs.

For additional information and examples, see the iLand wiki cluster page and this GitHub for an example with HTCondor software.

Braziunas, Kristin H., Rupert Seidl, Werner Rammer, and Monica G. Turner. 2021. “Can We Manage a Future with More Fire? Effectiveness of Defensible Space Treatment Depends on Housing Amount and Configuration.” Landscape Ecology 36: 309–30. https://doi.org/10.1007/s10980-020-01162-x.