Simulation settings

## Set the option specifying the location of SOFUN manually it it's not set
settings_sims_simple <- list( 
  setup = "simple", 
  implementation  = "fortran", 
  dir_sofun = options()$rsofun.dir.sofun 
  )

Model setup

Use the demo_pmodel compilation for the simple setup

setup_sofun_simple <- list(
  model      = "demo_pmodel",
  dir        = options()$rsofun.dir.sofun,
  do_compile = FALSE,
  simsuite   = FALSE
  )

Prepare setup

This the simple setup, this just checks whether the model code is in place.

settings_sims_simple <- prepare_setup_sofun( settings = settings_sims_simple, setup = setup_sofun_simple )

## [1] "Copying executable provided by rsofun and compiled on a 64-bit UNIX machine with gfortran into the SOFUN run directory..."

Run the model

Run SOFUN in the simple setup.

## First update calibratable parameters.
knitr::opts_knit$set( root.dir = rprojroot::find_rstudio_root_file() )
params_opt <- readr::read_csv( paste0( path.package("rsofun"), "/extdata/params_opt_kphio_soilm_global.csv" ) ) # as an example
nothing <- update_params( params_opt, settings_sims_simple$dir_sofun )

## Check if executable is available, otherwise copy it from the R package's external data
## This is not done inside the function 'pmodel()'. It would slow it down unnecessarily
if (!file.exists( paste0( settings_sims_simple$dir_sofun, "/rundemo_pmodel"))){
  system( paste0( "cp extdata/rundemo_pmodel ", settings_sims_simple$dir_sofun ) )
}

## Run for different temperatures and plot
ppfd <- 800
vpd  <- 1000
co2  <- 400
elv  <- 0
fapar <- 1

## Fortran
## update parameter
params_opt <- dplyr::tibble( kphio=0.05 ) # , temp_ramp_edge=NA, soilm_par_a=NA, soilm_par_b=NA
nothing <- update_params( params_opt, options()$rsofun.dir.sofun )

ptm <- proc.time()
pmodel_fortran <- purrr::map( as.list( seq( 0, 35, length.out = 100 ) ), 
  ~pmodel( temp = ., vpd = vpd, co2 = co2, ppfd = ppfd, fapar = fapar, elv = elv, implementation = "fortran", sofundir = settings_sims_simple$dir_sofun ) )
time_for <- proc.time() - ptm

## R
ptm <- proc.time()
pmodel_R <- purrr::map( as.list( seq( 0, 35, length.out = 100 ) ), 
  ~rpmodel( tc = ., vpd = vpd, co2 = co2, elv = elv, kphio = 0.05, fapar = fapar, ppfd = ppfd, method_optci="prentice14", method_jmaxlim = "wang17", do_ftemp_kphio = FALSE ) 
  )
time_R <- proc.time() - ptm

plot(  seq( 0, 35, length.out = 100 ), pmodel_fortran %>% purrr::map_dbl("gpp"), ylim = c(0,300), type = "l", xlab = "Temperature (deg C)", ylab = "GPP (gC/d/m2)" )
lines( seq( 0, 35, length.out = 100 ), pmodel_R %>% purrr::map_dbl("gpp"), col = "red" )
legend( "topright", c("Fortran", "R"), lty = 1, col = c("black", "red"), bty = "n")

Simulation settings

The simulation settings define the model simulations for each site and the the user-defined local environment. Simulation settings are defined as a named list. The user specifies only variables that are identical across simulations within an ensemble. Other variables that differ between simulation within an ensemble (e.g. start and end year of the simulation, vegetation type C3 or C4, longitude and latitude of the site, soil type, etc.) are to be specified in the meta info file path_siteinfo (a CSV file created separately). The function prepare_setup_sofun() complements the simulation settings by these additional components as lists with elements for each site, nested within the simulation settings list.

In the example given here, we use a site meta information file for FLUXNET 2015 Tier 1 sites, provided along with the rsofun package. It’s located at the path /rsofun/extdata/siteinfo_example.csv. For demonstration, we define a set of site-scale simulations of length one. That is, for only one site, here “FR-Pue”. Note that FLUXNET 2015 data and MODIS FPAR data is provided along with the package rsofun for this one site for demonstration purposes only and provides data only for a reduced number of years (2007-2014). The site meta information file looks like this:

siteinfo <- readr::read_csv( paste0( path.package("rsofun"), "/extdata/siteinfo_example.csv" ) )
print( siteinfo )

## # A tibble: 1 x 13
##   sitename    lon     lat   elv year_start year_end years_data classid
##      <chr>  <dbl>   <dbl> <int>      <int>    <int>      <int>   <chr>
## 1   FR-Pue 3.5958 43.7414   270       2007     2014          8     EBF
## # ... with 5 more variables: whc <dbl>, c4 <chr>, koeppen_code <chr>,
## #   kgnumber <int>, koeppen_code_extr <chr>

To conduct P-model simulations with the Fortran implementation, respective model code needs to be downloaded separately from the Github sofun repository and placed in a separate directory (dir_sofun below). Builds of this Fortran code are available for public download at XXX in order to avoid having to compile from source.

settings_sims_sitescale <- list(
  path_siteinfo   = paste0( path.package("rsofun"), "/extdata/siteinfo_example.csv"),
  ensemble        = TRUE,
  setup           = "site",
  name            = "example",
  dir_sofun       = options()$rsofun.dir.sofun,
  path_output     = "~/sofun/output_example_sofun/",
  path_output_nc  = "~/sofun/output_nc_example_sofun/",
  path_input      = "~/sofun/input_example_sofun/",
  grid            = NA,
  implementation  = "fortran",
  in_ppfd         = TRUE,
  in_netrad       = FALSE,
  recycle         = 1,
  spinupyears     = 10,
  calibvars       = c("gpp"),  # needed later for calibration setup, any of "gpp", "fapar", and "transp"
  soilmstress     = TRUE,
  tempstress      = TRUE,
  loutdgpp        = TRUE,
  loutdwcont      = TRUE,
  loutdaet        = TRUE,
  loutdpet        = TRUE,
  loutdalpha      = TRUE
  )

• path_siteinfo: Path (character string) of a CSV file that contains all the information needed for defining simulations. One row for each simulation in an ensemble, typically sites. Specifying this element is required if ensemble = TRUE. Columns are as follows:
  • site name, must be: column number 1
  • longitude of site, column must be named ‘lon’
  • latitude of site, column must be named ‘lat’
  • elevation of site, column must be named ‘elv’
  • years for which simulation is to be done (corresponding to data availability from site), requires two columns named ‘year_start’ and ‘year_end’.
• ensemble: TRUE if an ensemble of site-level simulations are to be run (This may become obsolte, this information is given already if the number of rows in the CSV file path_siteinfo is larger than one.)
• setup: String. One of "simple" (SOFUN used as a function, single time step, single location), "site" (site-scale simulation), or "lonlat" (spatial simulation on a longitude-latitude grid).
• name: a character string specifying the name of the ensemble (e.g. ‘fluxnet2015’) or of a single simulation.
• dir_sofun: Path (character string) where the model sits (corresponding to the parent directory of the respective git repository).
• path_output: Path (character string) where model output (ascii text files) is written to.
• path_output_nc: Path (character string) where NetCDF model output is written to.
• path_input: Path (character string) where model input is located.
• grid: Character string defining the type of grid used, e.g. halfdeg for half-degree resolution in lon. and lat. (only used in lonlat setup).
• implementation: Character string specifying whether Fortran (implementation= "fortran") or Python (implementation= "python") version is to be used.
• in_ppfd: Switch (TRUE of FALSE) whether PPFD should be read from data (prescribed) or simulated online using SPLASH and prescribed fractional cloud cover data.
• recycle: Periodicity (integer, number of years) of repeating forcing years during spinup (e.g. if the simulation start year is 1982 and recycle=3, then forcing years 1979-1981 are repeated during the duration of the model spinup, so that the last year of the spinup is forcing year 1981. For recycle=1 and simulation start year 1982, forcing year 1981 is used for all years of the model spinup. Here, ‘forcing year’ refers to the year AD in the climate, CO2, fAPAR, etc. data used as model forcing.
• spinupyears: Integer, number of model spinup years before the transient simulation. Use spinupyears > 0 if the model contains pool variables that that are simulated by dynamics that depend on their current state (typically soil water storage, or plant and soil carbon pools). Typically spinupyears = 10 is sufficient to bring soil water pools to equilibrium across the globe (unless you chose a large soil water holding capacity).
• calibvars: A vector of strings specifying which variables are to be calibrated. Use c() (used as default) for a standard model setup. See vignette calib_sofun.pdf for an example of a model calibration setup.
• soilmstress: Switch (TRUE of FALSE) defining whether soil moisture stress function is to be applied to GPP.
• tempstress: Switch (TRUE of FALSE) defining whether temperature stress function is to be applied to GPP.
• lout<var>: Switch (TRUE of FALSE) whether variable <var> is to be written to output (ascii text file for time series). To be anbandoned, only NetCDF output should be maintained.
• lout<var>: Switch (TRUE of FALSE) whether variable <var> is to be written to output (NetCDF file).

Input settings

Input settings define data sources used for SOFUN input. Two modes of specifying inputs are available. Either providing the input data directly (element data, not available for "lonlat" simulations), or by specifying a keyword for the source dataset as strings. E.g. "fluxnet2015" triggers specific functions that read input data from specifically formatted files, here all the site-level meteo data from FLUXNET 2015. Define the input settings as a list.

settings_input_sitescale <-  list(
  data                     = NA,
  temperature              = "fluxnet2015",
  precipitation            = "fluxnet2015",
  vpd                      = "fluxnet2015",
  ppfd                     = "fluxnet2015",
  netrad                   = "fluxnet2015",
  cloudcover               = NA,
  fapar                    = "MODIS_FPAR_MCD15A3H",
  splined_fapar            = TRUE,
  path_co2                 = paste0( path.package("rsofun"), "/extdata/cCO2_rcp85_const850-1765.dat" ),
  path_fluxnet2015         = paste0( path.package("rsofun"), "/extdata/" ),
  path_MODIS_FPAR_MCD15A3H = paste0( path.package("rsofun"), "/extdata/" ),

  ## below is information for downloading input data from remote server
  get_from_remote          = TRUE,
  path_remote_watch_wfdei  = "/work/bstocker/labprentice/data/watch_wfdei/",
  path_remote_co2          = "/work/bstocker/labprentice/data/co2/cCO2_rcp85_const850-1765.dat",
  path_remote_cru          = "/work/bstocker/labprentice/data/cru/ts_4.01/",
  path_remote_MODIS_FPAR_MCD15A3H  = "/work/bstocker/labprentice/data/fapar_MODIS_FPAR_MCD15A3H_fluxnet2015_gee_subset/",
  path_remote_MODIS_EVI_MOD13Q1 = "/work/bstocker/labprentice/data/evi_MODIS_EVI_MOD13Q1_fluxnet2015_gee_subset/",
  path_remote_fluxnet2015  = "/work/bstocker/labprentice/data/FLUXNET-2015_Tier1/20160128/point-scale_none_1d/original/unpacked/",
  path_remote_watch_wfdei  = "/work/bstocker/labprentice/data/watch_wfdei/",
  uname_remote             = "bstocker",
  address_remote           = "login.cx1.hpc.ic.ac.uk"
  )

• data: A named list of data frames, each containing the input data for one site with a column "date" specifying the date, and columns fapar, tempvarnam, precvarnam, vpdvarnam, ppfdvarnam, and netradvarnam specifying the fraction of absorbed photosynthetically active radiation, temperature, precipitation, vapour pressure deficit, photosynthetic photon flux density, and net radiation, respictively. Elements of the list data must be named according to site names. If data = NA, data will be read from files. If data is provided, all other elements of the input settings will be ignored.
• temperature: A character string specifying the source for temperature data. Any of "fluxnet2015", "watch_wfdei", and/or "cru". This can also be a vector of strings (e.g. c("fluxnet2015", "watch_wfdei"), to specify priorities: first take FLUXNET 2015 data for periods where data is available. For remaining years (given by date_start and date_end), use WATCH-WFDEI data. If "fluxnet2015" is specified for any of temperature, precipitation, vpd, ppfd, or netrad, then path_fluxnet2015 must be specified as well in the settings.
• precipitation: See temperature.
• vpd: See temperature.
• ppfd: See temperature.
• netrad: See temperature.
• fapar: A character string specifying the type of fAPAR data used as input. Implemented for use of data from CX1 are "MODIS_FPAR_MCD15A3H" and "MODIS_EVI_MOD13Q1". Use NA in case no fAPAR data is used as forcing (internally simulated fAPAR).
• splined_fapar: Logical defining whether splined fAPAR data is to be used. If FALSE, linearly interpolated fAPAR data is used.
• co2: A character string specifying which CO\(_2\) file should be used (globally uniform and identical for each site in an ensemble). All available CO\(_2\) forcing files are located on CX1 at /work/bstocker/labprentice/data/co2/. co2="cmip" specifies that the CMIP-standard CO2 file cCO2_rcp85_const850-1765.dat should be used.
• path_fluxnet2015: A character string specifying the path where standard FLUXNET 2015 CSV files are located.
• path_watch_wfdei: A character string specifying the path where standard WATCH-WFDEI NetCDF files are located.
• path_cru_ts4_01: A character string specifying the path where standard CRU NetCDF files are located.
• path<fapar>: A character string specifying the path where site-specific fapar files are located. This element is named according to the fapar setting (element fapar). E.g., an element named path_MODIS_FPAR_MCD15A3H is required if fapar = MODIS_FPAR_MCD15A3H.

Model setup

Define model setup as a list.

setup_sofun_sitescale <- list(
  model      = "pmodel",
  dir        = options()$rsofun.dir.sofun,
  do_compile = FALSE,
  simsuite   = FALSE
  )

• model: For Fortran version: A character string specifying the compilation option. The name of the executable is derived from this as "run<setup_sofun$model>".
• dir: A path (character) specifying the directory of where the executables are located (corresponds to the parent directory of the model git repository).
• do_compile: If TRUE, the model code is compiled as make <setup_sofun$model>. If FALSE, compiled executables are used (compiled with gfortran on a Mac 64-bit).
• simsuite: If TRUE, the SOFUN option for running an entire simulation suite (ensemble of simulations) with a single executable. (In the Fortran implementation, this this requires the main program file sofun_simsuite.f90 to be compiled instead of sofun.f90). This is to be preferred over a set of individual runs submitted individually when doing calibration runs because the cost across the entire ensemble (mod-obs error) can thus be calculated online.