THIS PAGE HAS BEEN LARGELY SUPERCEEDED BY THE 1.1: COMPILING GCAM CORE MODEL, WHICH PROVIDES STEP-BY-STEP INSTRUCTIONS THAT ARE LARGELY COMBINED HERE IN A SINGLE "MAKESCRIPT". FOLLOW THOSE INSTRUCTIONS FIRST SO THAT POTENTIAL TROUBLESHOOTING CAN BE ISOLATED TO A SPECIFIC STEP.

Download the GCAM core model (economy) and Hector (climate)

Because we are installing GCAM on a cluster to enable us to run multiple scenarios at once, running the model isn't as simple as just clicking on an icon, as we can do on a Windows PC. We must first build the code from source and create the input files from scratch with the gcam data system. This page will guide you through how to do this.

To begin, login to Rivanna using a web portal (e.g. Open OnDemand), secure shell terminal (e.g. MobaXterm), or a remote desktop environment (e.g. FastX). You can find more information about logging in on the Rivanna "Logging In" webpage. This wiki tutorial will demonstrate installing GCAM using MobaXterm.

Open a terminal window and clone this repository into your rivanna home directory:

git clone [email protected]:jayfuhrman/gcam-hpc-starterpack.git

You should now have a new folder (gcam-hpc-starterpack) in your home directory.

Download 1) the gcam-core zipfile from https://github.com/JGCRI/gcam-core, 2) the hector-gcam-integration zipfile from https://github.com/JGCRI/hector/archive/gcam-integration.zip, and 3) this (unzipped) gcam-hpc-starterpack directory. Place the two zipfiles and all the contents from this gcam-hpc-starterpack directory in your GCAM-install directory. Make sure you name your directories exactly the same as this tutorial, e.g. GCAM-install. An easy way to copy files from your local machine to your Rivanna account is using WinSCP, a free SSH file transfer protocol.

Install the dependency packages required to run the gcam data system

The gcam data system is an R package that creates the XML files read in by the GCAM model. When you compile the model from source for the first time, the provided scripts will run the GCAM data system to generate the required input files, which you will then use when running the model itself. However, we first need to install the GCAM datasystem's dependency packages directly through R.

Do this by starting a session in R from your terminal in Rivanna (hit the Enter key after each line):

module load goolf/7.1.0_3.1.4 R

R

[You should now have an R session open in your terminal window]

within R, type (or copy and paste) the following series of commands, again hitting Enter after each line:

install.packages(c("dplyr", "tidyr", "readr", "testthat", "assertthat", "roxygen2","data.table","devtools")) devtools::install_github("krlmlr/mockr")

During the install, you may be requested to specify a CRAN directory. Any one should work (try one of the US ones, and generally choose "yes" for all prompts)

after you've installed all the dependent R packages, quit R by typing:

q()

Substitute your computing ID and desired GCAM directory names into the provided shell scripts.

The makescript included here (here being the starterpack that you now have in your GCAM-install folder) should automatically move into place and unpack the zipfiles during the build process, creating a separate "GCAM-core" directory from which you will actually run the model.

Before attempting to compile/run GCAM, you will need to substitute your computing ID in two and only two files: makescript.sh and master.sh shell scripts. Additionally, you will need to change the permissions on all scripts (i.e., any file ending with ".sh") to make them executable (otherwise you will get a permission denied error)

Run the makescript

Now that you have appropriately set your file paths as specified above, run the makescript from your terminal window: ./makescript.sh

If everything works correctly, it could take up to 40 minutes to compile the GCAM core model, and generate the input files. You can confirm everything worked by checking for a new ".exe" file in your GCAM-core/exe directory (compilation), as well as a large number of ".xml" files in GCAM-core/input/gcamdata/xml (data system).

For simply rebuilding/recompiling GCAM (e.g., after Rivanna system maintenance), see here

Troubleshooting potential issues with gcamdata system

The latest versions of some R packages (in particular, dplyr) may not be compatible with gcamdata for syntax reasons. If your "makescript" finishes without populating the input/xml folder (i.e., all the input files GCAM needs to run) it is likely due to an issue with dplyr. Check the terminal window for an error message and see the link below for a potential fix.

https://github.com/JGCRI/gcam-core/issues/108

If gcam builds from source successfully, but gcamdata runs into an error, you don't need to build from source again (unless you feel like waiting another 30 minutes)! You can rerun just the data system to create the input files as follows:

cd [your gcam working directory]

module load goolf/7.1.0_3.1.4 R

make

GCAM datasystem should now run and populate input/xml with a bunch of .xml files.

Set classpath in bashrc file (may be a hidden file in Rivanna - and needs to be updated for every version of GCAM you load)

Before finally running GCAM, you will need to update the classpath in your bashrc file with your computing ID and gcam install location so that java won't throw an error when the model tries to call it. Open the bashrc file from the terminal as follows:

vi ~/.bashrc

insert the following line into the file exactly as written (substituting your computing ID and desired directory name into the brackets, of course):

export CLASSPATH=/home/[YOUR COMPUTING ID]/GCAM-core/libs/jars/*:/home/[YOUR COMPUTING ID]/GCAM-core/output/modelinterface/ModelInterface.jar

After making the changes, you can save and quit the bashrc file as follows:

hit the 'esc' key to exit from edit mode

then type:

:wq (Here, the "w" indicates "write" while the "q" means "quit")

Hit the enter key.

Your bashrc file should close and save the changes you've made.

You should now be able to run GCAM (instructions on how to do this are provided in the next page).