Introduction

The PEcAn.ED2 package features a number of utilities to facilitate running the ED model from inside R, including working with input files, running the ED executable, and processing the outputs. This tutorial describes these utilites and provides examples of common use cases.

Basic ED run

Installing the R package

The PEcAn.ED2 package and its PEcAn dependencies can be installed from GitHub as follows (all CRAN package dependencies should be installed automatically):

devtools::install_github("pecanproject/pecan", ref = "develop", subdir = "base/logger")
devtools::install_github("pecanproject/pecan", ref = "develop", subdir = "base/utils")
devtools::install_github("pecanproject/pecan", ref = "develop", subdir = "base/settings")
devtools::install_github("pecanproject/pecan", ref = "develop", subdir = "modules/data.atmosphere")
devtools::install_github("pecanproject/pecan", ref = "develop", subdir = "models/ed")

library(PEcAn.ED2)

Installing the ED2 model

The source code for the ED2 model is available on GitHub.

Alternatively, if you have Singularity container software installed, you can use a pre-built Singularity container available on Singularity Hub:

singularity pull --name ed2.simg shub://ashiklom/ED2

ED inputs

EDI

ED requires a global land use database to determine its land-sea mask, as well as a vegetation “thermal sums” database. These can be customized to some extent, but this package provides a version of the most common inputs. These inputs, stored in an “EDI” directory, can be downloaded via the download_edi function:

library(here)
rundir <- here("vignettes", "ed_run_data")
dir.create(rundir, showWarnings = FALSE)

edi_dir <- file.path(rundir, "EDI")
if (!file.exists(edi_dir)) {
  download_edi(edi_dir)
} else {
  message("EDI directory already exists. Skipping download.")
}

Meteorological data

To do the ED run described here, we’ll need some meteorological data. ED meteorological data are typically stored in HDF5 format and are described by a plain text header file (typically called ED_MET_DRIVER_HEADER).

To download the meteorological data, we’ll use the PEcAn.data.atmosphere package. Here, we grab the data for the first week of July 2005 and Harvard Forest, for which we’ll be running the simulation.

start_date <- "2006-07-01"
end_date <- "2006-07-08"
latitude <- 42.53
longitude <- -72.19

raw_met <- PEcAn.data.atmosphere::download.CRUNCEP(
  outfolder = file.path(rundir, "raw_met"),
  start_date = start_date,
  end_date = start_date,
  site_id = NULL,
  lat.in = latitude,
  lon.in = longitude
)

Next, we convert this raw data to the ED-specific format.

ed_met <- met2model.ED2(
  in.path = dirname(raw_met$file),
  in.prefix = "CRUNCEP",
  outfolder = file.path(rundir, "ed_met"),
  start_date = start_date,
  end_date = start_date,
  lat = latitude,
  lon = longitude,
  overwrite = TRUE
)

If you already have ED-specific meteorology available, PEcAn.ED2 provides utilities to interact with that file directly:

met_driver_raw <- "/path/to/ED_MET_DRIVER_HEADER"
met_driver_obj <- read_ed_metheader(met_driver_raw, check = FALSE)
met_driver_obj[[1]]$path_prefix <- "/path/to/new/location"
met_driver_obj[[1]]$xmin <- -90
met_driver_obj[[1]]$ymin <- 43

met_driver_path <- file.path(rundir, "ED_MET_DRIVER_HEADER")
write_ed_metheader(met_driver_obj, met_driver_path)

Vegetation inputs

A common way to initialize ED is through three interrelated vegetation initial condition files:

css – Cohort file, which describes all plant cohorts located within a patch, including its PFT, DBH, and stand density
pss – Patch file, which describes each patch within a site (single, plot-scale runs will often have only one patch)
site – Site file, which describes each site (single, plot-scale runs will often have only one site)

The package ships with simple functional examples of these objects (example_css/pss/site) and functions for quickly creating custom objects based on these examples (create_css/pss/site). Below, we create a css file with a single PFT with a specific DBH, but stick to the unmodified example pss and site files.

css <- create_css(list(pft = 11, dbh = 18.00))
pss <- example_pss
site <- example_site
veg_input <- create_ed_veg(css, pss, site, latitude, longitude, check = TRUE)

veg_prefix <- file.path(rundir, "veg_input", "test_veg")
write_ed_veg(veg_input, veg_prefix)

As with meteorology, PEcAn.ED2 also provides utilities for working with existing vegetation inputs.

veg_prefix <- "/path/to/site/files/prefix"
latitude <- 43.3724
longitude <- -89.9071
veg_input <- read_ed_veg(veg_prefix, latitude = latitude, longitude = longitude)

ED configuration file

Now that all inputs are taken care of, the final step is to create the ED configuration file (typically called ED2IN).

First, read a ED2IN template file:

ed2in_raw <- read_ed2in(system.file("ED2IN.rgit", package = "PEcAn.ED2"))

Then, set up the ED2IN with the required components.

ed2in <- modify_ed2in(
  ed2in_raw,
  veg_prefix = veg_prefix,
  latitude = latitude,
  longitude = longitude,
  met_driver = ed_met$file,
  EDI_path = file.path(rundir, "EDI"),
  start_date = start_date,
  end_date = end_date,
  run_dir = file.path(rundir, "run"),
  output_dir = file.path(rundir, "out"),
  runtype = "INITIAL",
  EXPNME = "ED test run"
)

It is also a good idea to check the ED2IN file for internal consistency.

check_ed2in(ed2in)

Assuming the ed2in object is valid, you then write it to a file to a desired directory. This doesn’t have to be the run directory (nor does the file have to be named ED2IN), but it’s a good idea to keep the ED2IN file close to the run outputs, as it provides useful metadata for the run.

ed2in_path <- file.path(rundir, "ED2IN")
write_ed2in(ed2in, ed2in_path)

Running ED

Assuming all of the inputs are correct, running ED is as simple as calling the run_ed_singularity function, which requires paths to the Singularity image and ED2IN file.

img_path <- "~/Projects/ED2/ed2.simg"
run_ed_singularity(img_path, ed2in_path)

Running ED from R

Alexey Shiklomanov