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:

rundir <- file.path(tempdir(), "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,
  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
)

## [1] "vobjtovarid4: error #F: I could not find the requsted var (or dimvar) in the file!"
## [1] "var (or dimvar) name: mole_fraction_of_carbon_dioxide_in_air"
## [1] "file name: /tmp/RtmpL6bJPD/ed_run_data/raw_met/CRUNCEP.2006.nc"

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)

## Warning in utils::write.table(site, site_fname, quote = FALSE, row.names =
## FALSE, : appending column names to file

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",
  pecan_defaults = TRUE,
  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)