13 PEcAn Models
This section will contain information about all models and output variables that are supported by PEcAn.
Model Name | Available in the VM | Prescribed Inputs | Input Functions/Values | Restart Function |
---|---|---|---|---|
BioCro | Yes | Yes | Yes | No |
CLM | No | No | No | No |
DALEC | Yes | Yes | Yes | No |
ED2 | Yes | Yes | Yes | Yes |
FATES | No | Yes | No | |
GDAY | No | No | No | No |
LINKAGES | Yes | Yes | Yes | Yes |
LPJ-GUESS | No | Yes | No | No |
MAESPA | Yes | Yes | No | No |
PRELES | Yes | Yes | Partially | No |
SiPNET | Yes | Yes | Yes | Yes |
Available in the VM - Denotes if a model is publicly available with PEcAn.
Prescribed Inputs - Denotes whether or not PEcAn can prescribe inputs.
Input Functions/Values - Denotes whether or not PEcAn has functions to fully produce a model’s Input values.
Restart Function - Denotes status of model data assimilation capabilities.
Output Variables
PEcAn converts all model outputs to a single Output Standards. This standard evolved out of MsTMIP project, which is itself based on NACP, LBA, and other model-intercomparison projects. This standard was expanded for the PalEON MIP and the needs of the PEcAn modeling community to support variables not in these standards.
Model developers: do not add variables to your PEcAn output without first adding them to the PEcAn standard table! Also, do not create new variables equivalent to existing variables but just with different names or units.
13.0.1 BioCro
Model Information | |
---|---|
Home Page | https://github.com/ebimodeling/biocro/blob/master/README.md |
Source Code | https://github.com/ebimodeling/biocro |
License | University of Illinois/NCSA Open Source License |
Authors | Fernando E. Miguez, Deepak Jaiswal, Justin McGrath, David LeBauer, Scott Rohde, Dan Wang |
PEcAn Integration | David LeBauer, Dan Wang |
13.0.2 Introduction
BioCro is a model that estimates photosynthesis at the leaf, canopy, and ecosystem levels and determines plant biomass allocation and crop yields, using underlying physiological and ecological processes to do so.
13.0.3 PEcAn configuration file additions
The following sections of the PEcAn XML are relevant to the BioCro model:
model
revision
– Model version number
run
site/id
– ID associated with desired site from BETYdb site entryinputs
met/output
– Set as BIOCROmet/path
– Path to file containing meteorological data
13.0.4 Model specific input files
List of inputs required by model, such as met, etc.
13.0.5 Model configuration files
Genus-specific parameter files are secretly required. These are stored in the PEcAn.BIOCRO package and looked up under the hood.
write.configs.BIOCRO
looks for defaults in this order: first any file at a path specified by settings$pft$constants$file
, next by matching the genus name in datasets exported by the BioCro package, and last by matching the genus name in PEcAn.BIOCRO’s extdata/defaults directory.
When adding a new genus, it is necessary to provide a new default parameter file in PEcAn.BIOCRO inst/extdata/defaults
and also (for v<1.0) update the call_biocro()
function.
BioCro uses a config.xml file similar to ED2. At this time, no other template files are required.
13.0.6 Installation notes
BioCro can be run standalone using the model’s R package. Instructions for installing and using the package are in the GitHub repo’s README file.
13.0.7 CLM
Model Information | |
---|---|
Home Page | |
Source Code | |
License | |
Authors | |
PEcAn Integration |
Introduction
Introduction about model
PEcAn configuration file additions
Should list the model specific additions to the PEcAn file here
Model specific input files List of inputs required by model, such as met, etc.
Model configuration files
MODEL is configured using 3 files which are placed in the run folder, as well as a symbolic link to the met file.
- file1 : template for this file is located at models/MODEL/inst/file1 and is not modified.
- file2 : template for this file is located at models/MODEL/inst/file2 and is not modified.
- file3 : template for this file is in models/MODEL/inst/file3 or it is specified in the <model> section as <template>. The values in this template are replaced by those computed in the earlier stages of PEcAN.
Installation notes
This section contains notes on how to compile the model. The notes for the VM might work on other machines or configurations as well.
VM
13.0.8 DALEC
Model Information | |
---|---|
Home Page | |
Source Code | |
License | |
Authors | |
PEcAn Integration |
Introduction
Introduction about model
PEcAn configuration file additions
Should list the model specific additions to the PEcAn file here
Model specific input files
List of inputs required by model, such as met, etc.
Model configuration files
MODEL is configured using 3 files which are placed in the run folder, as well as a symbolic link to the met file.
- file1 : template for this file is located at models/MODEL/inst/file1 and is not modified.
- file2 : template for this file is located at models/MODEL/inst/file2 and is not modified.
- file3 : template for this file is in models/MODEL/inst/file3 or it is specified in the <model> section as <template>. The values in this template are replaced by those computed in the earlier stages of PEcAN.
Installation notes
This section contains notes on how to compile the model. The notes for the VM might work on other machines or configurations as well.
VM
13.0.9 ED2
Model Information | |
---|---|
Home Page | http://moorcroftlab.oeb.harvard.edu/ |
Source Code | https://github.com/EDmodel/ED2 |
License | |
Authors | Paul Moorcroft, … |
PEcAn Integration | Michael Dietze, Rob Kooper |
13.0.9.1 Introduction
Introduction about ED model
13.0.9.2 PEcAn configuration file additions
The following sections of the PEcAn XML are relevant to the ED model:
model
id
– BETY model ID. Each ID corresponds to a different revision of ED (see below)revision
– The revision (a.k.a. release) number of ED (e.g. “r82”). “rgit” indicates the latest code on the ED repository.edin
– Name of the template ED2IN configuration file. If this is a functional path that points to a specific file, that file is used. If no file is found following the path literally, the workflow will try the path relative to thePEcAn.ED2
package usingsystem.file
(recall that files ininst
are moved in the package root, but all other directory structure is preserved). If this is omitted,PEcAn.ED2::write.configs.ED2
will look for a file calledED2IN.<revision>
(e.g.ED2IN.rgit
,ED2IN.r86
) in thePEcAn.ED2
package.- Example:
<edin>ED2IN.rgit</edin>
will use theED2IN.rgit
file shipped withPEcAn.ED2
regardless of the revision of ED used. (Note however that if a file calledED2IN.rgit
exists in the workflow runtime directory, that file will be used instead).
- Example:
start.date
,end.date
– Run start and end date, respectivelymet.start
,met.end
– Start and end year of meteorology inputs. By default (if omitted), these are set to the years ofstart.date
andend.date
, respectively. Setting these values to a shorter interval thanstart.date
andend.date
will cause ED to loop the meteorology input over the specified years. This may be useful for, for example, spinning up ED under a set of constant climate conditions.phenol.scheme
phenol
phenol.start
phenol.end
all_pfts
– (Logical) If false or missing (default), only run ED2 with the PFTs configured via PEcAn (i.e. in the<pfts>
section of the XML). Iftrue
, run with all 17 of ED2’s PFTs, using ED2’s internal default parameters for all PFTs not configured through PEcAn. See below for more details.ed2in_tags
– Named list of additional tags in the ED2IN to be modified. These modifications override any of those set by other parts of the PEcAn workflow. These tags must be in all caps. Any tags that are not already in the ED2IN file will be added; this makes this an effective way to run newer versions of ED2 that have new ED2IN parameters without having to provide an entire new ED2IN. For example:barebones_ed2in
– Whether or not to try to annotate the ED2IN file with comments. If “true”, skip all comments and only write the tags themselves. If “false” (default), try to transfer comments from the template file into the target file.jobtemplate
prerun
– String of commands to be added to thejob.sh
model execution script before the model is run. Multiple commands should be separated by properbash
syntax – i.e. either with&&
or;
.One common use of this argument is to load modules on some HPC systems – for instance:
If your particular version of ED is failing early during execution with a mysterious “Segmentation fault”, that may indicate that its process is exceeding its stack limit. In this case, you may need to remove the stack limit restriction with a
prerun
command like the following:
postrun
– Same as<prerun>
, but for commands to be run after model execution.binary
– The full path to the ED2 binary on the target machine.binary_args
– Additional arguments to be passed to the ED2 binary. Some common arguments are:-s
– Delay OpenMPI initialization until the last possible moment. This is needed when running ED2 in a Docker container. It is included by default when the host israbbitmq
.-f /path/to/ED2IN
– Full path to a specific ED2IN namelist file. Typically, this is not needed because, by default, ED searches for the ED2IN in the current directory and the PEcAn workflow places the ED2IN file and a symbolic link to the ED executable in the same (run) directory for you.
run/site
lat
– Latitude coordinate of sitelon
– Longitude coordinate of site
inputs
met/path
– Path toED_MET_DRIVER_HEADER
filepss
: [required] location of patch filecss
: [required] location of cohort filesite
: [optional] location of site filelu
: [required] location of land use filethsums
: [required] location of thermal sums fileveg
: [required] location of vegetation datasoil
: [required] location of soil data
13.0.9.3 PFT configuration in ED2
ED2 has more detailed PFTs than many models, and a more complex system for configuring these PFTs. ED2 has 17 PFTs, based roughly on growth form (e.g. tree vs. grass), biome (tropical vs. temperate), leaf morphology (broad vs. needleleaf), leaf phenology (evergreen vs. deciduous), and successional status (e.g. early, mid, or late). Each PFT is assigned an integer (1-17), which is used by the ED model to assign default model parameters. The mappings of these integers onto PFT definitions are not absolute, and may change as the ED2 source code evolves. Unfortunately, the only authoritative source for these PFT definitions for any given ED2 version is the Fortran source code of that version. The following is the mapping as of ED2 commit 24e6df6a (October 2018):
- C4 grass
- Early-successional tropical
- Mid-successional tropical
- Late-successional tropical
- Temperate C3 grass
- Northern pine
- Southern pine
- Late-successional conifer
- Early-successional temperate deciduous
- Mid-successional temperate deciduous
- Late-successional temperate deciduous
- Agricultural (crop) 1
- Agricultural (crop) 2
- Agricultural (crop) 3
- Agricultural (crop) 4
- Subtropical C3 grass (C4 grass with C3 photosynthesis)
- “Araucaria” (non-optimized southern pine), or liana
ED2 parameter defaults are hard-coded in its Fortran source code.
However, most parameters can be modified via an XML file (determined by the ED2IN
IEDCNFGF
field; usually config.xml
in the same directory as the ED2IN
file).
The complete record of all parameters (defaults and user overrides) used by a given ED2 run is stored in a history.xml
file (usually in the same directory as the ED2IN
) – this is the file to check to make sure that an ED2 run is parameterized as you expect.
As with other models, PEcAn can set ED2 parameters using its built-in trait meta analysis.
The function specifically responsible for writing the config.xml
is PEcAn.ED2::write.config.xml.ED2
(which is called as part of the more general PEcAn.ED2::write.config.ED2
).
The configuration process proceeds as follows:
First, the mappings between PEcAn PFT names and ED2 PFT numbers are determined according to the following logic:
If the PFT has a
<ed2_pft_number>
XML tag, that number is used. For example:If
<ed2_pft_number>
is not provided, the code tries to cross-reference the PFTname
against thepftmapping.csv
data provided with thePEcAn.ED2
package. If the name is not matched (perfectly!), the function will exit with an error.
Second, the PFT number from the previous step is used to write that PFT’s parameters to the config.xml
.
The order of precedence for parameters is as follows (from highest to lowest):
Explicit user overrides. These are specified via a
Note that these values are passed through<constants>
tag in the PFT definition in thepecan.xml
. For example:PEcAn.ED2::convert.samples.ED
, so they should generally be given in PEcAn’s default units rather than ED2’s.- Samples from the PEcAn meta analysis.
These are also converted via
PEcAn.ED2::convert.samples.ED
. - ED2 defaults that PEcAn knows about.
These are stored in the
edhistory.csv
file inside ofPEcAn.ED2
This file is re-generated manually whenever there is a new version of ED2, so while we try our best to keep it up to date, there is no guarantee that it is. (Implicitly) Defaults in the ED2 Fortran source code. In general, our goal is to set all parameters through PEcAn (via steps 1-3), but if you are running PEcAn with new or experimental versions of ED2, you should be extra careful to make sure ED2 is running with the parameters you intend. Again, the best way to know which parameters ED2 is actually using is to check the
history.xml
file produced once the run starts.
The ED2IN
field INCLUDE_THESE_PFT
controls which of these PFTs are included in a given ED2 run.
By default, PEcAn will set this field to only include the PFTs specified by the user.
This is the recommended behavior because it ensures that all PFTs in ED2 were parameterized (one way or another, at least partially) through PEcAn.
However, if you would like ED2 to run with all 17 PFTs (NOTE: using ED2’s internal defaults for all PFTs not specified by the user!), you can set the <all_pfts>
XML tag (in the <model>
section) to true
:
13.0.9.4 Model specific input files
List of inputs required by model, such as met, etc.
13.0.9.5 Model configuration files
ED2 is configured using 2 files which are placed in the run folder.
- ED2IN : template for this file is located at models/ed/inst/ED2IN.<revision>. The values in this template that need to be modified are described below and are surrounded with @ symbols.
- config.xml : this file is generated by PEcAn. Some values are stored in the pecan.xml in <pfts><pft><constants> section as well as in <model> section.
An example of the template can be found in ED2IN.r82
The ED2IN template can contain the following variables. These will be replaced with actual values when the model configuration is written.
**@ENSNAME@** : run id of the simulation, used in template for NL%EXPNME
- **@START_MONTH@** : start of simulation UTC time, from <run><start.date>, used in template for NL%IMONTHA
- **@START_DAY@** : start of simulation UTC time, from <run><start.date>, used in template for NL%IDATEA
- **@START_YEAR@** : start of simulation UTC time, from <run><start.date>, used in template for NL%IYEARA
- **@END_MONTH@** : end of simulation UTC time, from <run><end.date>, used in template for NL%IMONTHZ
- **@END_DAY@** : end of simulation UTC time, from <run><end.date>, used in template for NL%IDATEZ
**@END_YEAR@** : end of simulation UTC time, from <run><end.date>, used in template for NL%IYEARZ
- **@SITE_LAT@** : site latitude location, from <run><site><lat>, used in template for NL%POI_LAT
**@SITE_LON@** : site longitude location, from <run><site><lon>, used in template for NL%POI_LON
- **@SITE_MET@** : met header location, from <run><site><met>, used in template for NL%ED_MET_DRIVER_DB
- **@MET_START@** : first year of met data, from <run><site><met.start>, used in template for NL%METCYC1
**@MET_END@** : last year of met data, from <run><site><met.end>, used in template for NL%METCYCF
- **@PHENOL_SCHEME@** : phenology scheme, if this variabe is 1 the following 3 fields will be used, otherwise they will be set to empty strings, from <model><phenol.scheme>, used in template for NL%IPHEN_SCHEME
- **@PHENOL_START@** : first year for phenology, from <model><phenol.start>, used in template for NL%IPHENYS1 and NL%IPHENYF1
@PHENOL_END@** : last year for phenology, from <model><phenol.end>, used in template for NL%IPHENYSF and NL%IPHENYFF
@PHENOL@** : path and prefix of the prescribed phenology data, from * <model><phenol>, used in template for NL%PHENPATH- **@SITE_PSSCSS@** : path and prefix of the previous ecosystem state, from <model><psscss>, used in template for NL%SFILIN
- **@ED_VEG@** : path and prefix of the vegetation database, used only to determine the land/water mask, from <model><veg>, used in template for NL%VEG_DATABASE
- **@ED_SOIL@** : path and prefix of the soil database, used to determine the soil type, from <model><soil>, used in template for NL%SOIL_DATABASE
**@ED_INPUTS@** : input directory with dataset to initialise chilling degrees and growing degree days, which is used to drive the cold-deciduous phenology, from <model><inputs>, used in template for NL%THSUMS_DATABASE
- **@FFILOUT@** : path and prefix for analysis files, generated from <run><host><outdir>/run.id/analysis, used in template for NL%FFILOUT
**@SFILOUT@** : path and prefix for history files, generated from <run><host><outdir>/run.id/history, used in template for NL%SFILOUT
**@CONFIGFILE@** : XML file containing additional parameter settings, this is always “config.xml”, used in template for NL%IEDCNFGF
- @OUTDIR@** : location where output files are written (without the runid**), from <run><host><outdir>, should not be used.
**@SCRATCH@** : local scratch space for outputs, generated /scratch/<username>/run$scratch, should not be used right now since it only works on ebi-cluster
13.0.9.6 Installation notes
This section contains notes on how to compile the model. The notes for the VM might work on other machines or configurations as well.
13.0.9.7 VM
13.0.9.8 BU geo
13.0.9.9 TACC lonestar
13.0.10 GDAY
Model Information | |
---|---|
Home Page | |
Source Code | |
License | |
Authors | |
PEcAn Integration |
Introduction
Introduction about model
PEcAn configuration file additions
Should list the model specific additions to the PEcAn file here
Model specific input files
List of inputs required by model, such as met, etc.
Model configuration files
MODEL is configured using 3 files which are placed in the run folder, as well as a symbolic link to the met file.
- file1 : template for this file is located at models/MODEL/inst/file1 and is not modified.
- file2 : template for this file is located at models/MODEL/inst/file2 and is not modified.
- file3 : template for this file is in models/MODEL/inst/file3 or it is specified in the <model> section as <template>. The values in this template are replaced by those computed in the earlier stages of PEcAN.
Installation notes
This section contains notes on how to compile the model. The notes for the VM might work on other machines or configurations as well.
VM
13.0.11 LINKAGES
Model Information | |
---|---|
Home Page | |
Source Code | |
License | |
Authors | |
PEcAn Integration |
Introduction
Introduction about model
PEcAn configuration file additions
Should list the model specific additions to the PEcAn file here
Model specific input files
List of inputs required by model, such as met, etc.
Model configuration files
MODEL is configured using 3 files which are placed in the run folder, as well as a symbolic link to the met file.
- file1 : template for this file is located at models/MODEL/inst/file1 and is not modified.
- file2 : template for this file is located at models/MODEL/inst/file2 and is not modified.
- file3 : template for this file is in models/MODEL/inst/file3 or it is specified in the <model> section as <template>. The values in this template are replaced by those computed in the earlier stages of PEcAN.
Installation notes
This section contains notes on how to compile the model. The notes for the VM might work on other machines or configurations as well.
VM
13.0.12 LPJ-GUESS
Model Information | |
---|---|
Home Page | |
Source Code | |
License | |
Authors | |
PEcAn Integration |
Introduction
Introduction about model
PEcAn configuration file additions
Should list the model specific additions to the PEcAn file here
Model specific input files
List of inputs required by model, such as met, etc.
Model configuration files
MODEL is configured using 3 files which are placed in the run folder, as well as a symbolic link to the met file.
- file1 : template for this file is located at models/MODEL/inst/file1 and is not modified.
- file2 : template for this file is located at models/MODEL/inst/file2 and is not modified.
- file3 : template for this file is in models/MODEL/inst/file3 or it is specified in the <model> section as <template>. The values in this template are replaced by those computed in the earlier stages of PEcAN.
Installation notes
This section contains notes on how to compile the model. The notes for the VM might work on other machines or configurations as well.
VM
13.0.13 MAESPA
Model Information | |
---|---|
Home Page | http://maespa.github.io/ |
Source Code | http://maespa.github.io/download.html |
License | |
Authors | Belinda Medlyn and Remko Duursma |
PEcAn Integration | Tony Gardella, Martim DeKauwe, Remki Duursma |
Introduction
PEcAn configuration file additions
Model specific input files
Model configuration files
MODEL is configured using 3 files which are placed in the run folder, as well as a symbolic link to the met file.
- file1 : template for this file is located at models/MODEL/inst/file1 and is not modified.
- file2 : template for this file is located at models/MODEL/inst/file2 and is not modified.
- file3 : template for this file is in models/MODEL/inst/file3 or it is specified in the <model> section as <template>. The values in this template are replaced by those computed in the earlier stages of PEcAN.
Installation notes
Installing the MAESPA model requires cloning the MAESPA Bitbucket Repository, executing the makefile, and ensuring that the Maeswarp R package is correctly installed.
To clone and compile the model, execute this code at the command line
git clone https://bitbucket.org/remkoduursma/maespa.git
cd maespa
make clean
make
maespa.out
is your executable. Example input files can be found in the inputfiles directory. Executing measpa.out from within one of the example directories will produce output.
MAESPA developers have also developed a wrapper package called Maeswrap
. The usual R package installation method install.packages
may present issues with downloading an unpacking a dependency package called rgl
. Here are a couple of solutions:
Solution 1
From the Command Line
sudo apt-get install r-cran-rgl
then from within R
install.packages("Maeswrap")
Solution 2
From the Command line
sudo apt-get install libglu1-mesa-dev
then from within R
install.packages("Maeswrap")
This section contains notes on how to compile the model. The notes for the VM might work on other machines or configurations as well.
VM
13.0.14 PRELES
Model Information | |
---|---|
Home Page | |
Source Code | |
License | |
Authors | |
PEcAn Integration |
Introduction
Introduction about model
PEcAn configuration file additions
Should list the model specific additions to the PEcAn file here
Model specific input files
List of inputs required by model, such as met, etc.
Model configuration files
MODEL is configured using 3 files which are placed in the run folder, as well as a symbolic link to the met file.
- file1 : template for this file is located at models/MODEL/inst/file1 and is not modified.
- file2 : template for this file is located at models/MODEL/inst/file2 and is not modified.
- file3 : template for this file is in models/MODEL/inst/file3 or it is specified in the <model> section as <template>. The values in this template are replaced by those computed in the earlier stages of PEcAN.
Installation notes
This section contains notes on how to compile the model. The notes for the VM might work on other machines or configurations as well.
VM
13.0.15 SiPNET
Model Information | |
---|---|
Home Page | |
Source Code | |
License | |
Authors | |
PEcAn Integration | Michael Dietze, Rob Kooper |
Introduction
Introduction about model
PEcAn configuration file additions
Should list the model specific additions to the PEcAn file here
Model specific input files
List of inputs required by model, such as met, etc.
Model configuration files
SIPNET is configured using 3 files which are placed in the run folder, as well as a symbolic link to the met file.
- sipnet.in : template for this file is located at models/sipnet/inst/sipnet.in and is not modified.
- sipnet.param-spatial : template for this file is located at models/sipnet/inst/template.param-spatial and is not modified.
- sipnet.param : template for this file is in models/sipnet/inst/template.param or it is specified in the <model> section as <default.param>. The values in this template are replaced by those computed in the earlier stages of PEcAN.
Installation notes
This section contains notes on how to compile the model. The notes for the VM might work on other machines or configurations as well.
SIPNET version unk:
if [ ! -e ${HOME}/sipnet_unk ]; then
cd
curl -o sipnet_unk.tar.gz http://isda.ncsa.illinois.edu/~kooper/PEcAn/models/sipnet_unk.tar.gz
tar zxf sipnet_unk.tar.gz
rm sipnet_unk.tar.gz
fi
cd ${HOME}/sipnet_unk/
make clean
make
sudo cp sipnet /usr/local/bin/sipnet.runk
make clean
SIPNET version 136:
if [ ! -e ${HOME}/sipnet_r136 ]; then
cd
curl -o sipnet_r136.tar.gz http://isda.ncsa.illinois.edu/~kooper/EBI/sipnet_r136.tar.gz
tar zxf sipnet_r136.tar.gz
rm sipnet_r136.tar.gz
sed -i 's#$(LD) $(LIBLINKS) \(.*\)#$(LD) \1 $(LIBLINKS)#' ${HOME}/sipnet_r136/Makefile
fi
cd ${HOME}/sipnet_r136/
make clean
make
sudo cp sipnet /usr/local/bin/sipnet.r136
make clean
VM