GCAM Tutorial

December 5, 2019

PNNL-SA-148796
General Outline
• Preliminary: Software to Download
• Part 1: Running the GCAM Reference Scenario
• Part 2: Running alternative scenarios
• Part 3: Changing input files
• Part 4: Debugging
• Part 5: Additional Resources
• Part 6: Theory and meaning of parameters

2
Preliminary: software to download
• GCAM: https://github.com/JGCRI/gcam-core/releases
• Java Runtime Environment (64 bit) https://openjdk.java.net/13
 Windows: https://developers.redhat.com/products/openjdk/download
• To compile GCAM code:
 http://jgcri.github.io/gcam-doc/gcam-build.html
• R: https://cran.r-project.org/ and Rstudio https://www.rstudio.com

3
Preliminary: software to download
Optional but helpful
• On linux (or Mac), you can use vi, emacs, or your favorite text editor. On Mac/windows, XML files will
open in a text editor, but there are other options
 Windows: XML Marker: http://symbolclick.com/xmlmarker_1_1_setup.exe
 Mac: BBEdit: http://www.barebones.com/products/bbedit/
 Mac: XML Author: http://www.oxygenxml.com/
• On Mac and linux, you can use `diff` to compare files, but for more visual options:
 Windows: Tortoise Git: https://tortoisegit.org/download/
 Windows: WinMerge: http://winmerge.org/downloads/
 Mac or Windows: DiffMerge: https://sourcegear.com/diffmerge/downloads.php

4
Preliminary: software for AWS
• AWS Downloads
 X11 Forwarding Software
 Windows: Xming (https://sourceforge.net/projects/xming/)
 Mac: Xquartz (https://www.xquartz.org)
 Command Line Interface
 Windows: PuTTY (https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)
 Mac: Terminal (Included)
 Remote Server GUI
 Windows: WinSCP (https://winscp.net/eng/download.php)
 Mac: FileZilla (https://filezilla-project.org/)

5
1: Setting up AWS
• Amazon Web Services creates a copy of an existing server with a pre-compiled version of
GCAM.
• Download and place your private key file, “AWS-gcam-training.pem” in the folder “.ssh”
within your user directory. If it does not exist, create it by naming it “.ssh.”
 If explorer does not allow you to create it you may need to do this using the CMD: “mkdir .ssh”
 On Mac, save it wherever you like, ideally with a simple path
• Connect to the remote server
 Windows: WinSCP, PuTTY, Xming
 Mac: Terminal, Xquartz

6
1: Configuring and Using WinSCP
(Windows)
• Host name: IP address of AWS server
• Port: 22
• User Name: ec2-user

• In advanced settings, open SSH -> Authentication. Use the browser “…” to find your private
key file at “C:/Users/[username]/.ssh/”. When saved, WinSCP will automatically convert the
.pem file to a .ppk file, readable by both WinSCP and PuTTY.
• Once logged in you will be able to interact with files and folders as in a system browser

7
1: Configuring and Using FileZilla
(Mac)
• Open settings, open Connection -> SFTP. Click “Add keyfile…” to find your private key file.
When saved, FileZilla will ask to convert the .pem file to a supported format. Click “yes” and
save it with the file extension “.ppk”.
• Once logged in you will be able to interact with files and folders as in a system browser
• Click button in top left and add “new site”
 Host: IP address of AWS server
 Protocol: SFTP
 Port: 22
 Logon type: Normal
 User Name: ec2-user
 Password: left blank
• You will be asked if you trust this host. Click “OK”.

8
1: Using PuTTY to
Connect (Windows)
• Open your X11 software (Windows: XMing)
• Open PuTTY; it will open a configuration window. In the window enter
your IP address and the default port, 22.
• Under connection/SSH/Auth, click browse next to “Private key file for
authentication” to find your key file. Use the .ppk file saved by
WinSCP.
• Under connection/SSH/X11, check the box “enable X11 forwarding”
• Return to “Session” and click “save” to save your preferences in a
preset. In later logins, load this preset.
• Click “Open.” You will now have access to a terminal window
requesting login
• Enter your Username, “ec2-user.”
• Putty uses standard command line commands to navigate. For a list of
a few of these commands, see:
https://www.codecademy.com/articles/command-line-commands

9
1: Using Terminal to Connect
(Mac)
• Open you X11 software (Xquartz)
• Open a terminal window
• cd to the file location of your private key
 (you can drag and drop the path into the terminal)
 Type “chmod 400 AWS-gcam-training.pem”. This sets your permissions so only you can see your
private key. Only do this once.
• Type in “ssh -Y -i AWS-gcam-training.pem [email protected]”
 xx.xxx is the provided IP address of the AWS server

10
Part 1: Running the GCAM Reference Scenario
• Location of key files
• Building GCAM and the GCAM data system
• How to run the model
• Looking at, interpreting, and exporting the output
• Introduction to the diagnostics package

11
The GCAM repository
• If you have cloned the full GCAM
repository, you will see four folders:
Model code, project files
 cvs

 exe Executable and configuration

 input
Input files, including the data
system
 output
Model outputs, queries, diagnostic
package

12
Building GCAM
• Most users will not need to build GCAM and can use the pre-built package.

• If you do need to build GCAM, getting everything set up the first time can be
challenging, but it is typically easy after that. The instructions on the next slide
assume that you have gotten it set up correctly (including having installed all
of the libraries).
 For more information, see http://jgcri.github.io/gcam-doc/gcam-build.html

13
Building GCAM
• First, make sure you have installed Hector.
 From a command prompt, type `make install_hector`
 Or: `git submodule update --init ../../climate/source/hector`

• Then, build GCAM

 From Visual Studio, use the “Build Solution” option in the “Build”
menu.

 From Xcode, use the `Build` option in the `Product` menu.

 From a command prompt, type `make gcam`

 Note you can use the –j option to speed this up.

14
Building the GCAM data system
• From R,
 Navigate to the data system (input/gcamdata) and
open the project file (gcamdata.Rproj)
 Build the package (either from the Rstudio `Build &
Reload` option or by typing `library(gcamdata)`)
 Run the driver (`driver(write_output=FALSE,
write_xml=TRUE)`)

• From a command prompt,

 Navigate to the top of the repository (gcam-core)
 Type `make xml`

• xml outputs will be saved in `input/gcamdata/xml`

when the data system finishes
15
The GCAM Configuration File
• Default versions for 32 region GCAM (configuration_ref.xml) and GCAM-USA
(configuration_usa.xml) are provided in the `exe` folder.
• The configuration file defines the GCAM scenario that is run, including what
inputs to use, what mode to run, etc.
• Unless otherwise specified, GCAM will use `configuration.xml` in the `exe`
folder.
 This file does not exist when you download the gcam repository and will need to be
created.

16
The GCAM Configuration File
• Six different sections:
 Files
 Scenario Components
 Strings
 Bools
 Ints
 Doubles

17
The GCAM Configuration File: Files
Base input file. ScenarioComponents append to this.
For running multiple scenarios in sequence. Requires setting BatchMode bool to 1
For running climate target finder. Requires setting find-path bool to 1

xmldb is where the output will be saved

* Write-output: indicate whether to create the file

* Append-scenario-name: indicate whether to append the
scenario name to the name of the file being created
18
The GCAM Configuration File: Scenario Components

19
The GCAM Configuration File: Strings, Bools, Ints,
Doubles
No spaces or special characters
The debug file has a lot of detail but is only written for
one region

Always keep calibration on

If true, appends XML files listed in BatchFile
If true, uses policy-target-file
If true, calculates cost (area under the MAC
curve)

20
Running the GCAM Reference Scenario: Windows
1. Navigate to the `exe` folder.
2. Create a `configuration.xml` file by copying
the `configuration_ref.xml`.
3. Run GCAM:
1. From Visual Studio press the green play button
2. From windows explorer, double click `run-
gcam.bat`

21
Running the GCAM Reference Scenario: Mac
1. Navigate to the `exe` folder.
2. Create a `configuration.xml` file by
copying the `configuration_ref.xml`.
3. Run GCAM
1. From Xcode, hit the play button
2. From terminal, type `./Release/gcam` or
`./gcam.exe` (depending on how you’ve
compiled)
3. From Finder, double click `run-
gcam.command`

22
Running the GCAM Reference Scenario: Linux
1. Navigate to the `exe` folder.
2. Create a `configuration.xml` file by copying
the `configuration_ref.xml`.
3. Run GCAM
1. Type `./gcam.exe`

23
 Command prompt/terminal window
contains log messages
These are also written out to
Running GCAM exe/logs/main_log.txt. Main log will also
contain more information than is printed
to screen.
Input files are read in the order that
they appear in the configuration.xml
file.
Where multiple files refer to the same
parameter, the last one read in is the one
whose value is used.

Recursive and dynamic: each period

is solved independently, but
information from one period is passed
forward to the next
Deterministic: rerunning the model
with no changes to input files will
produce exactly the same outcome
24
Output
• The debug file
 exe/debugReference.xml (filename set in config and merged with scenario name)
 This writes out at the end of each time period, and contains a larger number of
parameters for debugging
 It is only written for one region, set in the configuration file
• The output database
 output/database_basexdb (set in configuration.xml)
 Contains the results from the scenario in a database that can be queried
 Results can also be exported from the database to xml

25
The output database

Open ModelInterface
File -> Open -> DB Open (output/database_basexdb) 26
What is in the GCAM Reference scenario?

27
Scenario Components: Climate, Socioeconomics

28
Climate
• Default model is Hector, but
MAGICC5.3 is still available as an
(unsupported) option.
• Some options (e.g., when emissions
switch from a historical file to GCAM
and when to start the carbon cycle)
are specified in an xml file. All other
options are controlled through the
Hector ini file.

29
GDP and population
• Population and GDP are based on SSP: Shared
Socioeconomic Pathways
 Population is strictly exogenous (i.e., not modified by other
modeled variables)

• GDP calculation uses the following formulation:

Popt1 • laborForceParticipation R ,t1
GDPR ,t1 = GDPR ,t 0 • ( ) • (1 + labor Pr odGrowthRate) (t1−t 0 )
Popt 0 • laborForceParticipation R ,t 0

 All parameters to the GDP function are currently exogenous

• If you want to change GDP, you will need to change the
income elasticities for the industry and cement sectors
to be consistent.

30
Scenario Components: Energy

31
General energy system structure
Region #1 Region #2
Primary resources are traded
Primary Resources Primary Resources
between regions

All energy losses and cost mark-ups

Energy Transformation are explicitly
Energymodeled in conversions
Transformation
Sectors from primarySectors
resources to fuels
consumed by end users

Modular structure: certain regions may

End-Use Sectors have more detailed
End-Use sectoral
Sectors
representations than others

Final Service Demands Final Service Demands

Population and GDP are largely

GDP Population Population
GDPexogenous, and determine future
levels of final service demands

32
Resources
• resources.xml
• Coal, oil, gas, wind, solar, geothermal, uranium,
MSW, limestone
• Resources are represented as supply curves: the
level of production at a range of given prices
 Prices are in 1975$ / GJ produced. Quantities are in
EJ.
 Supply curves may be graded, smooth (input as
parameters to a logistic power function), or unlimited
(e.g. solar, limestone)

• Where markets are shared between regions

(e.g.“global”), the supply curves of all contained
regions are aggregated
• Resources may be depletable, renewable, or
unlimited.
 Cumulative resource extraction is tracked for
depletable resources.

33
Energy supply
• en_supply.xml
• Domestic energy supply =
 Sum of all consumption within a region
 Production minus net exports

• These are generally uncalibrated “pass-

through sectors” used for tracking purposes
• They can be used to implement region-
specific energy price adders or subsidies
 We currently apply the same cost adders in all
regions.
 Regional energy prices are not currently calibrated;
instead, differences in price/cost across regions are
implicitly captured in the derived calibration
parameters (i.e., share weights)

34
Energy transformation sectors
• Five XML files
 electricity_water.xml
 hydrogen.xml
 heat.xml
 en_transformation.xml: refining, gas processing, and nuclear fuel
enrichment
 en_distribution.xml: delivered fuels

• Structure: supplysector / subsector / technology

 Subsector and technology market shares are currently
determined by two-level nested logit choice competition. Infinite
nesting is possible.

• Technology parameters are specified in each period

 Much of the technology-level information is found in the global-
technology-database, not in the technologies contained within
each region

• All technologies must have at least one input (either a

resource or another sector)

35
Energy end-use sectors
• Sector-specific XML files
 building_det.xml
 industry.xml
 cement.xml
 en_Fert.xml
 transportation_UCD_CORE.xml
• Each has its own structure
 Goal is to represent technologies
that consume energy and produce
physical services and outputs

Keywords specify assignments of

from specific to general end use
sectors (bld, ind, trn)

36
Scenario Components: Agriculture and Land Use

37
General structure
Region #1 Region #2
CropLand CropLand Cropland determined by
CropLand Basin 1
Basin 1 Basin 2 endogenous land allocation

Primary agricultural goods are

Crop Supply Sectors Crop Supply Sectors
assumed to be traded globally

Secondary Agricultural Secondary

Includes Agricultural
ruminant and non-
Supply Sectors ruminantSupply
meat and dairy products
Sectors

Final demands include food

Final Service Demands Final and
demands Service Demands
nonfood demands

GDP Population GDP Population

38
Land allocation
• Land data are read in 5 XML files that
correspond to the 5 “node” levels of the land
nesting diagram
 land_input_1.xml, land_input_2.xml, and
land_input_3_IRR.xml, land_input_4_IRR_MGMT.xml,
land_input_5_IRR_MGMT.xml

• Top-level base-year land allocations are fixed in

all future periods
• At lower levels, land allocations are endogenous
 In GCAM, the land use shares shift in response to
changes in relative land profit rates
 Calibration is performed on land use shares, not present-
day rates of land use change

39
Agricultural production
• Each ag production technology has a corresponding land leaf of
the same name
 The sharing/competition takes place in the land allocator, not in the ag sectors.
Share weights are ignored in the ag sectors.

• Exogenous variables
 Calibrated commodity price (1975$/kg)
 Calibrated output (Mt/yr)
 Calibrated land quantity (thous km2)
 Residue biomass supply curve
 Non-CO2 coefficients (kg gas per kg crop)
 MAC curves
 Fertilizer inputs (kg N per kg crop)
 Costs (1975$/kg)
 Future agricultural productivity growth rate (and therefore yield)
 Annual harvested area:cropland

• Key endogenous variables

 Future commodity prices
 Future profit rates and production volumes

40
Scenario Components: Non-CO2

41
Non-CO2 gases
• Non-CO2 gases are modeled as a by-product on existing activities, either driven by “input”
(e.g. fuel consumption) or “output” (e.g. service or energy production)
Can be read in as input-
emissions (Tg/yr) or as
emissions coefficients
(kg/GJ)
GDP control function:
emissions coefficients
are reduced as GDP
increases
MAC = marginal
abatement cost curve;
decreases coefficients
as carbon price
increases.

42
Queries
• Update single queries: allows a query to
focus on an individual element

• Edit query window

 Sum All: adds all types of the given element
together
 Group: builds an area chart and separates
each region into a separate chart
 XPATH: this is the syntax of the given query.
 Note that label re-write lists used in
“aggregated” queries are only accessible
through the query XML file.

43
Exporting data to Excel
• Drag and drop (e.g. into Excel)
• Highlight cells and cut and paste
• Use a batch query to export a large
number of queries directly into an Excel
spreadsheet
 The basex database file needs to be open for
this to work
 File -> Batch File. Select batch query file and
output workbook.
 This won’t work if the Excel workbook selected
is open while running the batch query
• rgcam/gcamreader
 R/python based tools to import GCAM results
directly into R/python.
 Available on github.com/jgcri

44
Running the diagnostics package
• The diagnostics package runs R scripts that generate a large number of figures
 Can be used for individual scenario analysis or comparisons between a “reference” and
alternative scenarios
 Currently, queries address end-use energy consumption, electricity, refining, primary
energy consumption, land use, emissions, fuel prices, GDP, and population
 More can be added in the Model_verification_queries.xml batch query file
• The diagnostics package is located in the output/gcam_diagnostics folder
 Instructions are found in the readme.txt file

45
Running the diagnostics package
• Check that the working directory is correct, and run the R script

46
Running the diagnostics package
• GCAM regions can be aggregated into world
regions for analysis and visualization
 use a label re-write list in the
model_verification_queries.xml file

47
Running the diagnostics package
• The default is to compare an “alternative” scenario to a “baseline”, or reference, scenario.

48
Exporting, importing runs
• File -> Manage DB
• This allows one to rename, export (as an
xml file, that can be imported into another
baseX file), import, or remove a run from
the database
• The exported .xml files can also be useful
for writing queries, as they contain all
available information that could be queried

49
Useful Miscellaneous Info
• All energy flows are represented in EJ/yr. Note that the “year” denominator is implicit, not
written out.
• Fuel carbon contents are in kgC/GJ.
• Emissions units
 CO2 is in MtC/yr. Multiply by 44/12 to convert to CO2
 Non-CO2 gases are generally in Tg (same as Mt). Exceptions are the hi-GWP gases (e.g. HFCs,
PFCs, SF6), which are in Gg (same as kt).
• Dollar units
 Prices of all energy and agricultural goods and services are in 1975$/GJ
 GDP is in 1990$/yr
 Carbon prices are in 1990$/tC. Multiply by 12/44 to convert to 1990$/tCO2.
 Fuel prices in policy scenarios do not include the emissions penalties. After converting to the
desired dollar year, these may be added to any technology as:
 C price ($/tC) * 1t / 1000kg * Fuel C content (kgC/GJ) * (1 – sequestration fraction)

50
Part 2: Running alternative scenarios
• Including additional “add-on” XML files
• Policies
• Running multiple scenarios in batch mode

51
Running alternative scenarios
• Most studies using GCAM will run alternative scenarios
 Not an optimization model
 “Reference” scenario should not be seen as a most likely scenario; it is simply a no
additional policy scenario starting from middle of the road socioeconomic and
technological assumptions
• Many possible variables of interest:
 Different technology futures
 Technology policies (e.g., standards, subsidies)
 CO2 and other GHG emissions pricing
 Emissions constraints
 Land use policies
 Future energy prices or taxation
 Different population, GDP pathways
• This section will focus on the provided policy files in the input/policy folder
52
The input folder
All input xml files for a model run are Folder structure
stored in the input folder gcamdata: generates the XML
files from an R package and a
set of csv based raw inputs
climate: information for the
Hector climate model
magicc: information for the
MAGICC climate model
policy: selected policies that can
be run
extra: additional files used for the
SSPs
solution: solver configuration files

53
Provided policy files
Carbon cap: constraint on annual CO2
emissions in each time period (Mt C)
Carbon tax: exogenous CO2 price in each
time period (1990$/t C)
Forcing target: radiative forcing (W/m2).
Overshoot allows end-of-century target to be
exceeded in prior years
FFICT: fossil fuel and industrial emissions
only
UCT: universal (includes land use change
emissions)

54
Configuration
• Alternative scenarios
may be run as follows:
 add additional XML files
at the end of the existing
ScenarioComponents
 Change the
scenarioName
 Indicate whether to use
target-finder (if running
an end-of-century climate
target)
 Indicate whether to
calculate abatement cost
curves
 Note for adding CO2
policies, start from
configuration_policy.xml 55
• A global policy is specified in one region, and all others share in the market.
 Regional policies can be specified in individual regions

• Carbon price: model solves for emissions, given a fixed price

• Carbon constraint: model solves for carbon price, given emissions pathway.
• Economic equilibrium is not influenced by which factor was specified 56
Cost curves
• Emissions abatement costs are calculated as the integral under the marginal
abatement cost schedule.
 By default, this is calculated as the area underneath the marginal abatement curve with
five points.

In the example to the right, the resulting

policy costs are as follows:
5 points: $12148
No intermediate points: $13578
This scenario exhibits progressively
higher marginal abatement costs with
respect to abatement level
Technology influences the shape of the
MAC function

57
Running in batch mode

Set the bool and

batch file name

Files in FileSet will be added to the

scenarioComponents in the config
file
scenarioName and
FileSet name append
(e.g., Base_tax)

58
Part 3: Changing Input Files
• The gcamdata system
• Modifying xml input files

59
The gcamdata system
Folder structure
xml: GCAM input files (in xml format)
outputs: csv files generated by the data system
R: code files used to generate GCAM input files
zchunk_L1*, zchunk_LA1*, zchunk_LB1*:
convert raw data to GCAM regions, sectors,
technologies
zchunk_L2*: generate all data needed for
GCAM
zchunk_batch*: generate xml input files
inst: external data used as inputs into the R code
data-raw: generates package related data

60
Modifying the xml input files
• The best approach for modifying GCAM depends on what you are changing,
what your intention is, and whether you want your modification to be put into
the GCAM master version
 Possible things to change:
 Parameter that is either specified in `input/gcamdata/inst/extdata` or the `constants.R` file in the
gcamdata package.
 Parameter or file that is derived in the gcamdata package
 Structure of a region or sector
 Possible intentions:
 Quick understanding
 Project or paper

61
Changing a parameter that is either specified in
`input/gcamdata/inst/extdata` or the `constants.R` file in
the gcamdata package
• If your goal is to simply understand the implications of that parameter, then just
change it, rebuild the data, and run with the updated parameter.
 Note 1: Make sure you first run the standard version so you have something to compare
to
 Note 2: Make sure you revert the change when you are done so it doesn’t make its way
into other simulations
• If your goal is to update the GCAM master version, then follow the steps above.

62
Changing a parameter that is either specified in
`input/gcamdata/inst/extdata` or the `constants.R` file in
the gcamdata package
• Your question:
Option what
#1: Change are the implications
the parameters of more rapidly to
in A23.globaltech_capital_adv.csv decreasing solar
get your desired costPV
costs?
and re-run the gcamdata system. The `solar_adv.xml` file will include your updated costs.
 Default cost of PV w/ storage in 2100: $985/kW
 Advanced cost PV w/ storage in 2100: $787/kW
 Your desired cost: $650/kW

63
Changing a parameter that is either specified in
`input/gcamdata/inst/extdata` or the `constants.R` file in
the gcamdata package
• If your goal is to simply understand the implications of that parameter, then just
change it, rebuild the data, and run with the updated parameter.
 Note 1: Make sure you first run the standard version so you have something to compare
to
 Note 2: Make sure you revert the change when you are done so it doesn’t make its way
into other simulations
• If your goal is to update the GCAM master version, then follow the steps above.
• If your goal is to write a paper comparing the model under different parameters:
 The option above will theoretically work, but it is difficult to reproduce and document.
 Instead, we recommend that you modify the data system to create a new xml file.
Additionally, creating a batch file to iterate through the different options is recommended.

64
Changing a parameter that is either specified in
`input/gcamdata/inst/extdata` or the `constants.R` file in
the gcamdata package
• Your
Optionquestion:
#2: Create what are the
a new chunk implications
by copying of more rapidly decreasing
`zchunk_batch_solar_adv_xml`, then modifysolar PVin
the data
that chunk to create a new xml file with your desired cost. You will need to rebuild and re-run the
costs?
data system to generate the new file.
 Default cost of PV w/ storage in 2100: $985/kW
 Advanced cost PV w/ storage in 2100: $787/kW
 Your desired cost: $650/kW Add code here to change the
cost (either overwriting data
in one of the files above or
reading in a new file).

Update file name here.

65
Changing a parameter or file that is derived in the
gcamdata package
• Regardless of your intention, you will need to modify the R code in the
gcamdata system.
• If you are just trying to understand the implications or are intending to modify
the GCAM core, then you can just modify the calculation in the relevant part of
the code.
• If your goal is to write a paper studying this parameter or the information in this
file, then you will want to ensure the data system includes/generates both the
original calculation/file and the new one.

66
Modifying the structure of a region or sector
• It is difficult to give general advice in this case, because exactly how you make
this change depends on what you are trying to do.
• Some general advice:
 Start small. Make the smallest change possible at each step so you can identify when
things go wrong.
 If possible use the “add-on” approach so your changes are in it’s own XML and
delete/replace some part of the model (GCAM-USA approach)
 You can create your test xml file in whatever manner is easiest (e.g., typing by hand or
copying and editing an existing one). However, if you are planning to use the end result
in a paper or in the GCAM master, then you will need to create it via the data system at
some point. This is likely to be easier sooner rather than later.
 Be very careful when changing calibration values.
 Use GitHub issues to ask for more help: https://github.com/jgcri/gcam-core/issues

67
Additional notes for developments you wish to get into the
GCAM master
• If you are intending for your change to become part of the GCAM master, you
will need to ensure that the GCAM coding style is used and that the code is
well documented.
 HINT: starting from an existing code file will help ensure the guidelines are met.
 More information is available at: http://jgcri.github.io/gcam-doc/dev-guide.html

68
Part 4: Debugging
• This section will focus on the most common problems
• It will not attempt to cover everything that could happen, because there would
be way too much to cover

69
Types of messages
• GCAM prints different levels of messages to help identify issues.
 WARNING: a notification of a potential problem; however, since this could be benign the
model will continue (e.g., unrecognized text string in an xml input file)
 ERROR: a notification of a likely problem. In some cases, the model will continue to run
(e.g., the sum of area read in for all land leafs in a region is more than 0.1% different
from the total area read in for that region); in other cases, the model will abort (e.g., if the
difference is more than 5%)
 SEVERE: Major issue that will prohibit the model from running properly (e.g., no world
within the scenario container)

70
Configuration/input errors
Problem: Immediate crash • Possible causes
 The gcamdata system has not yet been run
or did not produce XMLs
 The XMLInputFileName or BatchFileName
(or their pathways) are incorrect
 If running from code editor, the project’s
working directory needs to be set to the exe/
folder. Sometimes it defaults to the
cvs/objects/build/*/ folder

71
Configuration/input errors
• Problem: crash while reading in the ScenarioComponents XML files

Possible causes:
File was not found (look for typos in the file name)
File was not correctly formatted (when edited by hand) 72
Configuration/input errors
• Problem: crash after XML parsing, before first period

Possible causes:
Mis-spelled a technology name (Cement instead of cement).
Strings in GCAM are case-sensitive.
Missing technology
Added some land input in some region / basin / crop
combination that does not exist 73
Configuration/input errors
• Problem: message printed to screen about explicitly creating a market for CO2
(model will not abort, but will have solving problems later)

Cause: A carbon price must be read in with target finder in order to set up
dependencies. When implementing CO2 policy start with
configuration_policy.xml 74
Calibration Failures versus Solver Failures

Calibration failure: Read-in

values for supply and
demand don’t match

Solver failure: model cannot

find a set of prices where
supply and demand are equal
for all commodities
75
Errors from changes to input files
• Problem: the model does not calibrate or solve the base years:

Cause: Unbalanced supply and demand in calibration years. Check all

calibration data, including coefficients to debug. In this case, the base-year
electricity input-output coefficient of cement production was changed,
causing system-wide imbalances between electricity demand and supply. 76
Model not solving
• Problem: the model fails to solve in some period

Cause: solution issues can be difficult to decipher

Useful to make ”one” change at a time
Double check your configuration
Use supply / demand curves feature to check problem markets
(input/extra/supply_demand_curves.xml)
77
Model not solving
• Solver failures can be difficult to diagnose. Some things to try:
 Look for discontinuities or vertical supply or demand curves, either by thinking about
what you’ve changed that could have led to that OR by using the supply-demand
curve calculator to print the curves.

Well-behaved and intersecting.

Should solve easily.

78
Model not solving
• Solver failures can be difficult to diagnose. Some things to try:
 Look for discontinuities or vertical supply or demand curves, either by thinking about
what you’ve changed that could have led to that OR by using the supply-demand
curve calculator to print the curves.

Non-intersecting.
Will not solve.

79
Model not solving
• Solver failures can be difficult to diagnose. Some things to try:
 Look for discontinuities or vertical supply or demand curves, either by thinking about
what you’ve changed that could have led to that OR by using the supply-demand
curve calculator to print the curves.

Intersecting, but includes a discontinuity.

Can solve, but may be difficult.

80
Model not solving
• Solver failures can be difficult to diagnose. Some things to try:
 Look for discontinuities or vertical supply or demand curves, either by thinking about
what you’ve changed that could have led to that OR by using the supply-demand
curve calculator to print the curves.
 Increase the iteration count in the solver configuration file. [Note: there is no
guarantee this will work, but it is easy to try and has helped in the past]
 Ask for help on GitHub: https://github.com/jgcri/gcam-core/issues

81
Database open while trying to write
• The model can’t write to the output database

In prior versions, the database could be open while GCAM was writing to it;
this is no longer the case with the switch to the basexdb

82
Queries – general
• Message: “The query returned no results”
 Misspelling the name of a variable or sector
 The market may not exist (e.g. C price in a non-policy run)
 The syntax of the XPATH may be wrong (e.g. not enough slashes)
• Batch query error:

 The Excel workbook being written to was open during the export

83
Part 5: Additional Resources
• Online resources:
 GCAM documentation: http://jgcri.github.io/gcam-doc/toc.html
 Developer’s guide: http://jgcri.github.io/gcam-doc/dev_guide.html

• Asking for help:

 gcam-core GitHub issues: https://github.com/jgcri/gcam-core/issues
 gcam-doc GitHub issues: https://github.com/JGCRI/gcam-doc/issues

84
Part 6: What does it all mean?
• This section focuses on the meaning of several key input parameters found
throughout the input XML file set
 Elasticities
 Logit exponents
 Share-weights and interpolation rules
 Efficiencies and coefficients

85
Elasticity
• Price elasticity: The percent change in demand of a good divided by the
percent change in the price
• Income elasticity: The percent change in demand of a good divided by the
percent change in GDP
GDPt inc − elas P
Di ,t = Di , 2005 • ( ) • ( t ) p − elas
GDP2005 P2005

86
Service price elasticity ≠ fuel price elasticity

• Service price elasticities include ALL costs of providing the energy service
 Levelized capital costs, fixed O&M, variable O&M
 In passenger transportation, service costs may include time value costs

87
Efficiencies and coefficients
• Efficiency = output / input
• Coefficient = input / output
 Coefficients make more sense where there are multiple inputs
• Where the input-unit and output-unit are the same, these parameters are
unitless. For several sectors in GCAM, however, the input-unit and output-unit
differ, e.g.:
 Transportation coef: BTUs fuel per vehicle kilometer
 Cement coef: GJ of energy per kg of cement
 Fertilizer coef: GJ of energy per kg of N fertilizer
 Nuclear fuel efficiency: GJ of energy per kg of uranium

88
Logit-exponents and fuel-switching
• The logit exponents control the degree of switching between technologies or
fuels in response to price changes
 Low values = low fuel-switching = strong influence of base year shares even far into the
future
 High values tend towards winner-take-all responses in response to changes in costs

β
swi • Pi
Sharei =
∑
i
swi • Pi
β

89
Share-weights
• The roles of the share-weight
 Calibration parameter
 Phasing in new technologies
 Allows gradual movement away from the base year’s calibrated share weight values

Without any phase-

in, markets rapidly
transition in
response to
introductions of
new technologies

90
Interpolation
• Interpolation is primarily used for defining share-weight pathways into the future
 Fixed: carry the shareweight in the “from-year” to the “to-year” with no changes.
Requires a from-value.
 Linear: linearly interpolate. Requires a from-value and a to-value, which can be set
within the interpolation rule, or in the share-weight parameter.
 S-curve: s-curve shaped function. Requires a from-value and a to-value. Note that the
to-year doesn’t need to be a model time period, but if it isn’t, need to set the “to-value”
within the rule.

91
Thank you

92