4 Getting Started

4.1 How PEcAn Works in a nutshell

PEcAn provides an interface to a variety of ecosystem models and attempts to standardize and automate the processes of model parameterization, execution, and analysis. First, you choose an ecosystem model, then the time and location of interest (a site), the plant community (or crop) that you are interested in simulating, and a source of atmospheric data from the BETY database (LeBauer et al, 2010). These are set in a “settings” file, commonly named pecan.xml which can be edited manually if desired. From here, PEcAn will take over and set up and execute the selected model using your settings. The key is that PEcAn uses models as-is, and all of the translation steps are done within PEcAn so no modifications are required of the model itself. Once the model is finished it will allow you to create graphs with the results of the simulation as well as download the results. It is also possible to see all past experiments and simulations.

There are two ways of using PEcAn, via the web interface and directly within R. Even for users familiar with R, using the web interface is a good place to start because it provides a high level overview of the PEcAn workflow. The quickest way to get started is to download the virtual machine or use an AWS instance.

4.2 Installing and running PEcAn

4.2.1 Using the Virtual Machine

PEcAn consists of a set of scripts and code that is compiled within a Linux operating system and saved in a “virtual machine” (VM). Virtual machines allow for running consistent set-ups without worrying about differences between operating systems, library dependencies, compiling the code, etc.

  1. Install VirtualBox This is the software that runs the virtual machine. You can find the download link and instructions at http://www.virtualbox.org. NOTE: On Windows you may see a warning about Logo testing, it is okay to ignore the warning.

  2. Download the PEcAn VM You can find the download link at http://opensource.ncsa.illinois.edu/projects/artifacts.php?key=PECAN, under the “Files” header. Click the “.ova” file to begin the download. Note that the file is ~7 GB, so this download can take several minutes to hours depending on your connection speed. Also, the VM requires >4 GB of RAM to operate correctly. Please check current usage of RAM and shutdown processes as needed.

  3. Import the VM Once the download is complete, open VirtualBox. In the VirtualBox menus, go to “File” → “Import Appliance” and locate the downloaded “.ova” file. In the Appliance Import Settings, make sure you select “Reinitialize the MAC address of all network cards” (picture below). This is not selected by default and can result in networking issues since multiple machines might claim to have the same network MAC Address. (NOTE: If you experience network connection difficulties in the VM with this enabled, try re-importing the VM without this setting selected). Finally, click “Import” to build the Virtual Machine from its image.

  1. Launch PEcAn Double click the icon for the PEcAn VM. A terminal window will pop up showing the machine booting up which may take a minute. It is done booting when you get to the pecan login: prompt. You do not need to login as the VM behaves like a server that we will be accessing through you web browser. Feel free to minimize the VM window.
  • If you do want to login to the VM, the credentials are as follows: username: carya, password: illinois (after the pecan tree, Carya illinoinensis).
  1. Open the PEcAn web interface With the VM running in the background, open any web browser on the same machine and navigate to localhost:6480/pecan/ to start the PEcAn workflow. (NOTE: The trailing backslash may be necessary depending on your browser)
  • To ssh into the VM, open up a terminal on your machine and execute ssh -l carya -p 6422 localhost. Username and password are the same as when you log into the machine.

4.2.2 Using Amazon Web Services (AWS)

Login to Amazon Web Services (AWS) and select the EC2 Dashboard. If this is your first time using AWS you will need to set up an account before you are able to access the EC2 Dashboard. Important: You will need a credit card number and access to a phone to be able to verify AWS account registration. AWS is free for one year.

  1. Choose AMI
    • On the top right next to your name, make sure the location setting is on U.S. East (N. Virginia), not U.S. West (Oregon)
    • On the left click, click on EC2 (Virtual servers), then click on “AMIs”, also on the left
    • In the search window toggle to change “Owned by me” to “Public images”
    • Type “pecan” into the search window
    • Click on the toggle button on the left next to PEcAn1.4.6
    • Click on the “Launch” button at the top
  2. Choose an Instance Type
    • Select what type of machine you want to run. For this demo the default, t2.micro, will be adequate. Be aware that different machine types incur very different costs, from 1.3 cents/hour to over $5/hr https://aws.amazon.com/ec2/pricing/
    • Select t2.micro, then click “Next: Configure Instance Details”
  3. Configure Instance Details
    • The defaults are OK. Click “Next: Add Storage”
  4. Add Storage
    • The defaults are OK. Click “Next: Tag Instance”
  5. Tag Instance
    • You can name your instance if you want. Click “Next: Configure Security Group”
  6. Configure Security Group
    • You will need to add two new rules:
    • Click “Add Rule” then select “HTTP” from the pull down menu. This rule allows you to access the webserver on PEcAn.
    • Click “Add Rule”, leave the pull down on “Custom TCP Rule”, and then change the Port Range from 0 to 8787. Set “Source” to Anywhere. This rule allows you to access RStudio Server on PEcAn.
    • Click “Review and Launch” . You will then see this pop-up:

Select the default drive volume type and click Next

  1. Review and Launch
    • Review the settings and then click “Launch”, which will pop up a select/create Key Pair window.
  2. Key Pair
    • Select “Create a new key pair” and give it a name. You won’t actually need this key unless you need to SSH into your PEcAn server, but AWS requires you to create one. Click on “Download Key Pair” then on “Launch Instances”. Next click on “View Instances” at the bottom of the following page.

  1. Instances
    • You will see the status of your PEcAn VM, which will take a minute to boot up. Wait until the Instance State reads “running”. The most important piece of information here is the Public IP, which is the URL you will need in order to access your PEcAn instance from within your web browser (see Demo 1 below).
    • Be aware that it often takes ~1 hr for AWS instances to become fully operational, so if you get an error when you put the Public IP in you web browser, most of the time you just need to wait a bit longer. Congratulations! You just started a PEcAn server in the “cloud”!
  2. When you are done using PEcAn, you will want to return to the “Instances” menu to turn off your VM.
    • To STOP the instance (which will turn the machine off but keep your work), select your PEcAn instance and click Actions > Instance state > Stop. Be aware that a stopped instance will still accrue a small storage cost on AWS. To restart this instance at any point in the future you do not want to repeat all the steps above, but instead you just need to select your instance and then click Actions > Instance state > Start
    • To TERMINATE the instance (which will DELETE your PEcAn machine), select your instance and click Actions > Instance state > Terminate. Terminated instances will not incur costs. In most cases you will also want to go to the Volumes menu and delete the storage associated with your PEcAn VM.Remember, AWS is free for one year, but will automatically charge a fee in second year if account is not cancelled.

4.2.3 (Experimental) Using Docker

Follow the instructions here. Note that this is still experimental and may have a lot of bugs. If you find any bug please report it.

4.2.4 (Advanced) Installing by hand

Although we recommend using one of the above methods for setting up PEcAn, all PEcAn components use open-source tools and can be installed “manually”. Detailed instructions for manual installation of PEcAn on some common systems are available here.

4.3 PEcAn Demos

Once you have a running version of PEcAn, we recommend working through some of the following demos and vignettes to explore PEcAn’s many capabilities:

Type Title Web Link Source Rmd
Demo Basic Run html Rmd
Demo Uncertainty Analysis html Rmd
Demo Output Analysis html Rmd
Demo MCMC html Rmd
Demo Parameter Assimilation html Rmd
Demo State Assimilation html Rmd
Demo Sensitivity html Rmd
Vignette Allometries html Rmd
Vignette MCMC html Rmd
Vignette Meteorological Data html Rmd
Vignette Meta-Analysis html Rmd
Vignette Photosynthetic Response Curves html Rmd
Vignette Priors html Rmd
Vignette Leaf Spectra:PROSPECT inversion html Rmd