Data and example code for STILT tutorials is located in the STILT Tutorials Github repository.

WBB Carbon Dioxide

Here, we’ll simulate a day of carbon dioxide concentrations for the UATAQ Lab, housed in the William Browning Building on the University of Utah campus. This tutorial assumes a base level of knowledge for navigating UNIX based filesystems from the command line, that you have read through installing STILT, and know where to find documentation for the different model controls.

Dependencies

Let’s start by checking to be sure the necessary dependencies are installed.

The University of Utah CHPC clusters use modules to manage environment paths. To load dependencies within one of the CHPC clusters, you need to load the netcdf-c and R modules. You can run module load netcdf-c R in your current bash session or add it to the bottom of your shell configuration file (.bashrc) to load the dependencies at every login.

We need R version 3.2.5 or higher, which you can find in the output from

bash
Rscript --version
R scripting front-end version 3.4.1 (2017-06-30)

If R is not found or the version is too old, you’ll need to update R on your system before continuing.

STILT requires several R packages as helpers for file input/output, data manipulation, and parallel execution. We can install the dependencies in R with

R
install.packages(c('devtools', 'dplyr', 'ncdf4', 'parallel', 'raster', 'rslurm'))
...

To compile the hymodelc executable, the makefile will default to searching for gfortran. We can check if gfortran is installed with

bash
which gfortran
/usr/bin/gfortran

If which returns a path, then gfortran is installed. If which returns something along the lines of /usr/bin/which: no gfortran in..., you need to make some changes for the compilation to be successful. To use gfortran, you’ll need to add the executable to your shell’s PATH. To use a different compiler, you’ll need to manually clone the STILT Github Repository, specify the compiler in fortran/Makefile using the FC variable, then run the ./setup executable. See the documentation for installation for details.

Last, we need to check if we have netCDF installed. Footprints are saved in compressed netCDF files, which reduces their file size and stores results with associated metadata so that the output is self documenting. We can check if netCDF is installed with

bash
nc-config --all
This netCDF 4.4.1 has been built with the following features:
...

If nc-config --all returns build information about the netCDF configuration, then netCDF is installed. Otherwise, you will need to install netCDF on your system before continuing or (advanced) reconfigure the footprint file output extension in simulation_step() and calc_footprint() to return footprints using a different file format.

Project setup

Now that we have the dependencies we need, let’s start a new STILT project using the uataq R package. We can install this package from Github within R using the devtools package as

R
devtools::install_github('benfasoli/uataq')

Then we can initialize our STILT project in our current directory within R using

R
uataq::stilt_init('wbb-tutorial')

To ensure everything compiled correctly, check to be sure you can find hymodelc in exe/

bash
cd wbb-tutorial
ls exe
ASCDATA.CFG CONC.CFG hymodelc LANDUSE.ASC ROUGLEN.ASC

Success! We’ve now set up our STILT project.

Input data

The minimum we need to simulate the carbon dioxide concentration at WBB is (1) meteorological data to transport the STILT particles and (2) a near-field emissions inventory. You can download example data for this tutorial in the base directory of your STILT project using

bash
git clone https://github.com/uataq/stilt-tutorials
ls stilt-tutorials/01-wbb
emissions.rds met/ tutorial.r

which contains

  1. emissions.rds - 0.002deg hourly emissions inventory
  2. met/ - meteorological data files
  3. tutorial.r - a simple script to combine footprints with the emissions inventory and plot a timeseries of the concentrations

Configuration

Now, we need to configure STILT for our example. Begin by opening r/run_stilt.r in a text editor. Unless otherwise described below, leave the simulation settings as their defaults.

Set the simulation timing and receptor location to

# Simulation timing, yyyy-mm-dd HH:MM:SS
t_start <- '2015-12-10 00:00:00'
t_end <- '2015-12-10 23:00:00'
run_times <- seq(from = as.POSIXct(t_start, tz='UTC'),
                 to = as.POSIXct(t_end, tz='UTC'),
                 by = 'hour')

# Receptor locations
lati <- 40.766189
long <- -111.847672
zagl <- 25

Next, we need to tell STILT where to find the meteorological data files for the sample. Set the met_directory to

# Meteorological data input
met_directory <- file.path(stilt_wd, 'stilt-tutorials', '01-wbb', 'met')
met_file_format <- '%Y%m%d.%Hz.hrrra'

Last, let’s adjust the footprint grid settings so that it uses the same domain as our emissions inventory. Set the footprint grid settings to

# Footprint grid settings
xmn <- -112.30
xmx <- -111.52
ymn <- 40.390
ymx <- 40.95
xres <- 0.002
yres <- xres

That’s it! We’re all set to run the model. From the base directory of our STILT project, run Rscript r/run_stilt.r and wait a few minutes for the simulations to complete.

bash
Rscript r/run_stilt.r
Parallelization disabled...
Running simulation ID: 2015121000_-111.847672_40.766189_25
Running simulation ID: 2015121001_-111.847672_40.766189_25
...

Applying emissions

Now that we have 24 footprints for each hour of our simulation, the next step is to convolve the footprints with our emissions inventory. An example of how to do this can be found in stilt-tutorials/01-wbb/tutorial.r, which makes some overly-basic assumptions to calculate the carbon dioxide concentration at the receptor.

To convolve the footprints with emissions estimates,

bash
cd stilt-tutorials/01-wbb
Rscript tutorial.r

which will output timeseries.png to the current directory showing the modeled concentrations

as well as maps for the average footprint (average_footprint.png) and average contribution of fluxes over space (average_contribution.png).

Note that the strange boundary of the contributed emissions is the extent of Salt Lake County, which is the area for which the emissions data exists and is non-NaN.