GCAM Community Tutorial

Page Kyle and Patrick Luckow GCAM Modeling Community Meeting Joint Global Change Research Institute College Park, MD

September 30, 2010

1

General Outline   Preliminary: Software to Download   Part 1: Running the GCAM Main Scenario

  Location of key files   How to run the model   Looking at, interpreting, and exporting the output

  Part 2: Running alternative scenarios   Adding new “add-on” files to the configuration   Running policies: advanced technology, carbon emissions pricing,

and carbon emissions constraints   Running many scenarios in batch mode

  Part 3: Changing input files   Excel->CSV->XML conversion

  Part 4: Debugging   Part 5: Theory and meaning of parameters   Appendix: Additional resources

2

Preliminary: software to download

  XML Marker: http://www.symbolclick.com   One alternative is Oxygen XML Author:

http://www.oxygenxml.com/   Another is XMLSpy: http://www.altova.com/xmlspy.html

  Java Runtime Environment: http://www.java.com/en/download/manual.jsp

  Some program to diff files   WinMerge: http://winmerge.org/downloads/   Tortoise SVN: http://tortoisesvn.net/downloads

  [Optional] Microsoft Visual C++ Express Edition 2008: http://msdn.microsoft.com/en-us/visualc/default.aspx

3

1: Running the Main Scenario

1)  Navigate to the exe folder 2)  Open configuration_ref.xml

•  This is a permanently saved file (versioned—note the green check) that reads in files for the reference, or main, scenario

3)  Save this as configuration.xml •  This is the control file that is called

when the model is run; the configuration.xml file itself is over-written each time a new scenario is run. Configuration files that one wants to keep permanently can be saved under a different name

4)  Double-click Objects-MI.exe •  This is the executable file that runs

GCAM

4

1: The configuration file

  XML: a heirarchical structure for storing information   Flexible   Data in attributes (e.g. name=) and nodes may be used   Note: the picture above highlights only portions of the

configuration file that users will want to change 5

1: Running GCAM

6

  Command prompt window contains warning messages; these are also written out to exe/logs/main_log.txt   “UnmanagedLand” warning message

should be ignored   “Not creating technology rail coal”

message should be ignored

  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

1: Output   Two forms of output

  The XML output file   output/output.xml (by default)   Contains any “add-on” input files parsed into the base input

file, with newly calibrated shareweights (if calibration was active), in a new xml file   This can be used as a base input file for another run. Because the

shareweights are calculated from actual base year shares, re-running this output.xml file with calibration off will reproduce the results

  One can also look at this file to check that certain key parameters in add-on files were read correctly

  The output database   output/database.dbxml (by default)   Contains the results from the scenario in a database that can

be queried

7

1: XML output

  Read-in XML files can create new attributes and values, or over-write existing ones   The last file read in takes precedence over all others

8

1: DBXML output

9

  Open ModelInterface/ModelInterface.jar   File -> Open -> DB Open   output/database.dbxml

1: General energy system structure

10

Region 1

Energy Transformation Sectors

Primary Resources

End-Use Sectors

Final Service Demands

GDP Population

Region 2

Energy Transformation Sectors

Primary Resources

End-Use Sectors

Final Service Demands

GDP Population

Primary resources can be traded between regions

All energy losses and cost mark-ups are explicitly modeled in conversions

from primary resources to fuels consumed by end users

Modular structure: certain regions may have more detailed sectoral representations than others

Population and GDP are largely exogenous, and determine future levels of final service demands

1: Resources   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.

11

1: Energy transformation sectors   Electricity, refining, gas

processing, hydrogen production, and a number of other pass-through sectors

  Structure: supplysector / subsector / technology

  Technology parameters are specified in each period

  All technologies must have at least one input (either a resource or another sector)

  Subsector and technology market shares determined by two-level nested logit choice competition   Competition takes place on

the basis of levelized cost of providing the energy service.

12

1: Final Demands   Buildings, industry, transportation   Per-capita final demand, sector i in time period t:

  Non-per-capita demand:

13

  AEEI reduces the energy services required to meet a given level of final demand (in percent per year)   e.g. building shell efficiency,

industrial process improvements

1: GDP and Population   Population is based on UN forecasts through 2050, followed by IIASA

Technogarden scenario trajectory from 2050 to 2095.   GDP is based on the formulation:

14

1: Agricultural system structure

15

Region 1

Crop Supply Sectors

CropLand

Secondary Agricultural Supply Sectors

Final Service Demands

GDP Population

Region 2

Crop Supply Sectors

CropLand

Secondary Agricultural Supply Sectors

Final Service Demands

GDP Population

Primary agricultural goods are assumed to be traded globally

Cropland determined by endogenous land allocation

Final demands include food demands and nonfood demands

1: Land Allocation

  Gray = exogenous; Green = unmanaged; Red = managed   Managed land competes with unmanaged land based on

implicit equilibrium profit rate

16

1: 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.

17

1: Exporting data

  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 dbxml 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

18

1: Exporting, importing runs

  File -> Manage DB   This allows one to rename,

export (as an xml file, that can be imported into another .dbxml file), import, or remove a run from the database

  The exported .xml files can also be used to look for specific data (the structure of the file is somewhat similar to the output.xml file)

19

1: 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 Mt C. 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 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)

20

2: Running alternative scenarios   Pretty much any study using GCAM will run alternative

scenarios   Not an optimization model   “Main” scenario should not be seen as a most likely scenario, or

even business as usual: it is only a starting point   Many possible variables of interest:

  Different technology RD&D 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 technology RD&D (Advanced and reference), carbon emissions pricing, and carbon emissions constraints

21

2: Configuration   Alternative scenarios

may be run using a calibrated output file as the base input file

22

  Change the base input file to the calibrated output file

  Add on the carbon policy or advanced technology file

  Change the scenario name

  Turn off calibration

  Calculate policy costs (if desired)

2: The input folder   All input variables for a model run are specified in the

input folder.   Carbon policies are in the input/policy folder   Technology scenarios are in the input/energy/… folders

23

  Any file that ends with “_adv.xml” is an advanced technology scenario in the given sector   The “us_” prefix

indicates a file that is designed for detailed US sectors. These files shouldn’t be used unless the base run had the corresponding detailed US sector.

2: Running policy scenarios

  Turning off calibration makes 1990 and 2005 solve in 1 iteration

24

  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 25

2: 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. This setting can be changed in the configuration file; each “point” greater than 2 corresponds to a new scenario run.

26

  In the example to the right, the resulting policy costs are as follows:   5 points: $12148   No intermediate points: $13578

  This scenario has a concave function: progressively higher marginal abatement costs at higher carbon prices

  Technology influences the shape of the MAC function

2: Advanced technology scenarios   Input files do not affect calibration, so these can be run

with calibration off   Figures show USA primary energy consumption by fuel,

1990-2095

27

2: Running in batch mode

28

1: Specify batch file

2: Turn on batch mode

Scenarios run: 1)  Ref 2)  Adv_EE 3)  ADV_supply 4)  Ref_15tax 5)  Adv_EE_15tax 6)  Adv_supply_15tax

3: Changing input files   XML files may be changed by hand

  Search and replace may be useful   However:

  This can be tedious   Directly changing XML files leaves no paper trail   The input parameters do not explain themselves

  XML files may also be re-built from CSV files

29

3: Re-building XML files 1.  Make desired changes to tables in CSV files, and re-save (probably with a

different file name) 2.  In ModelInterface: File -> Open -> Open CSV File 3.  Select CSV file 4.  Select header file; this should be the only .txt file in the same folder 5.  Save the resulting XML file (again, probably with a different name)

30

3: Check XML file

31

3: Run adjusted file

  Add the new file to the configuration file   Make sure the new file is in the correct place to be read

by the configuration file (i.e. not in the Input Module folder)

  Make sure the order among other add-on files in the configuration is correct; the last file to over-write a given parameter is the one that takes precedence

32

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   It will proceed accordingly

1.  Running the model 2.  Querying output 3.  Building XML files

33

4: Configuration/input errors

34

  The command prompt window rapidly disappears before you can read anything. The main log reads:

Running GCAM model code base version 1.1 revision 3728

Parsing input files... Could not find bool: simple-find-path Could not find bool: mergeFilesOnly

  The problem: the base input or batch file pathname or filename was incorrectly typed.

4: Configuration/input errors

35

  The command prompt window disappears while reading in the add-on files. The main log reads:

  The problem: the last file read was mis-typed. Note the second “.xml”—this is a common error.

4: Configuration/input errors

36

  The model stops running but the command prompt does not disappear:

  The problem: an advanced detailed US industry file was added on to a set of files (or base input) that didn’t include a detailed representation of US industry. The model gets to the first sector it doesn’t recognize and stops.

4: Configuration/input errors

37

  The model stops prints the same message over and over:

  The problem: same as prior slide, incomplete sectors were inadvertently created by reading in an “advanced” file where there had been no “input_ref” file read in beforehand

4: Errors from changes to input files

38

  The model does not calibrate or solve the base years:

  The problem: An efficiency was adjusted in the industry input file, for one technology in one region in 1990. Any adjustment to base year efficiencies or coefficients must be complemented with a change in the fuel demand or service output (i.e. don’t do this). All flows are balanced in 1990 and 2005.

4: Model not solving with policy   The model fails to solve in some period

39

  The problem: This often happens with constraints, though not as frequently with fixed tax paths. Often the solution is to specify the tax in the problematic period in order to get the sought emissions (through iterative runs with different carbon prices in the problematic period).

4: Queries – general   Message: “The query returned no results”

  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)   Nothing at all prints out (not even a warning message)

  The syntax of the XPATH is incorrect. Check that all parentheses are closed.

  Batch query error:

  The Excel workbook being written to was open during the export

40

4: Building XML files - general

41

  The model interface was expecting data where there was a missing value. The missing value/column was in the third column. Either:   The header file has too many entries with “+” symbols. The table

only has two columns, so one entry needs to be deleted from the header, or a column has to be added to the table.

  The data table has a missing value in the third column   Note that this warning message does not indicate which

table/header caused the problem.   Note that there is no corresponding problem for a table

where not all of the data is read (i.e. a header with too few entries). This will produce a valid XML file.

4: Building XML files - general

42

  There is a header in the headers file that doesn’t have the following entry: ,scenario,

What does it all mean?   This section focuses on the meaning of several key input

parameters found throughout the input set   Elasticities   Logit exponents   Share-weights and interpolation rules   Efficiencies and coefficients

43

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

44

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

45

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-type response

46

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

47

  Without any phase-in, markets rapidly transition in response to introductions of new technologies

Efficiencies and coefficients

  Efficiency = output / input   Coefficient = input / output

  Coefficients make more sense where there are multiple inputs; a shared denominator is more intuitive than a shared numerator

  Where the input-unit and output-unit are the same, these parameters are unitless. Several exceptions include:   Transportation coef: BTUs fuel per vehicle kilometer   Cement coef: GJ of energy per ton of cement   Nuclear fuel efficiency: GJ of energy per kg of uranium (equal to

EJ per Mt)

48

A: Data processing example   Parameters are imported from available data sources,

and converted into GCAM units   This example converts capital and O&M costs, and capacity

factors of wind turbines into levelized costs of energy, in 1975$/GJ, based on assumptions of capital recovery rate and equipment lifetime

49

discount rate 0.125 Assumed values lifetime 30 Values from data FCR 0.129 Calculated values

Exported to model Reference costs from GRPA FY2008

2005 2020 2035 2050 2065 2080 2095 Capital cost 2006$/kW 1167 1124 1083 1043 1004 967 932

0.25% 0.25% 0.25% 0.25% 0.25% 0.25% Fixed O&M 2006$/kW/yr 11.5 11.5 11.1 10.7 10.3 9.9 9.5 Variable O&M 2006$/MWh/yr 7 4.6 4.4 4.3 4.1 4.0 3.8

improvement 0.25% 0.25% 0.25% 0.25% 0.25% Capacity factor 0.4 0.45 0.46 0.47 0.48 0.49 0.5 Annual output MWh/kW/yr 3.50 3.94 4.03 4.12 4.20 4.29 4.38 Total O&M cost 2006$/kW/yr 36.03 29.63 28.93 28.24 27.56 26.89 26.23 Annual cost 1975$/yr 60.68 56.80 54.83 52.93 51.10 49.33 47.62 Annual output GJ/yr 12.61 14.19 14.51 14.82 15.14 15.45 15.77 NE cost 1975$/GJ 4.81 4.00 3.78 3.57 3.38 3.19 3.02 NE cost 2004$/kWh 0.053 0.044 0.042 0.039 0.037 0.035 0.033

A: Data tables for XML   The header file tells the model interface how to read the CSV files

50

INPUT_TABLE Variable ID

2001 minicam-non-energy-input input-cost

region supplysector subsector intermittent-technology 1990 2005 2020 2035 2050 2065 2080 2095

Africa electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Australia_NZ electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Canada electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 China electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Eastern Europe electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Former Soviet Union electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 India electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Japan electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Korea electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Latin America electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Middle East electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Southeast Asia electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 USA electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020 Western Europe electricity wind wind 4.811 4.811 4.002 3.780 3.571 3.376 3.192 3.020

2001,world/+{name}region,region/+{name}supplysector,supplysector/+{name}subsector,subsector/+{name}intermittent-technology,{year=1990}period/../minicam-non-energy-input/+input-cost,{year=2005}period/../minicam-non-energy-input/+input-cost,{year=2020}period/../minicam-non-energy-input/+input-cost,{year=2035}period/../minicam-non-energy-input/+input-cost,{year=2050}period/../minicam-non-energy-input/+input-cost,{year=2065}period/../minicam-non-energy-input/+input-cost,{year=2080}period/../minicam-non-energy-input/+input-cost,{year=2095}period/../minicam-non-energy-input/+input-cost,scenario,scenario/world,@intermittent-technology/period,@period/{name=non-energy}minicam-non-energy-input

  A header file is created with instructions on how to read each table

Each table has a header of the same number. The data in

the table starts three rows down from the table number.

Each entry in the header file (between two commas) corresponds to a column in the table, reading from left to right.

Data is read as heirarchical parent/child pairs

Data can be assigned to an {attribute} or a node. A node

defines the endpoint of a heirarchy (can take no “children”)

3: Adjusting queries   Changes can be made in the Main_queries.xml file, or by

opening up a database in the model GUI   Note that label re-write lists for aggregated queries can not be

accessed from the model GUI   X-Axis name is almost always year; y-axis name is the same as the

series name.   XPATH has the specific query instructions

51

3: Adjusting queries in XPATH   Generally, copy an existing query first (Ctrl-C, Ctrl-V), similar to the one that

is sought   Base query XPATH: *[@type='resource']//output/node()

  This queries output of all elements tagged as “resources”   To limit the query to coal: and ()

  *[@type='resource‘ and (@name=‘coal’)]//output/node()   To limit the query to fossil fuels: and (…or…)

  *[@type='resource‘ and (@name=‘coal’ or @name=‘crude oil’ or @name=‘unconventional oil’ or @name=‘natural gas’)]//output/node()

  To remove non-energy resources: and not (…or…)   *[@type='resource‘ and not (@name=‘Scavenging’ or @name=‘limestone’ or

@name=‘misc emissions sources’)]//output/node()   To aggregate across all of the fossil fuels: (:collapse:)

  *[@type='resource‘ (:collapse:) and (@name=‘coal’ or @name=‘crude oil’ or @name=‘unconventional oil’ or @name=‘natural gas’)]//output/node()

52

3: Adjusting queries in XPATH

  Where information is low in a heirarchy, one can choose how many levels of the heirarchy to show in the output:

  Base query XPATH: *[@type = 'sector' and ((@name='gas processing') )]//*[@type = 'technology']/*[@type='output' (:collapse:)]/physical-output/node()

  The double slash (//*) indicates to go down by more than one level   To also write out the subsector: only one /*   *[@type = 'sector' and ((@name='gas processing') )] /*[@type = 'subsector']/*[@type =

'technology']/*[@type='output' (:collapse:)]/physical-output/node()

53

Gasproduc+onbytechnologyscenario region sector technology 1990 2005 2020Main,date=2010‐23‐9T12:05:21‐04:00 USA gasprocessing biomassgasificaAon 0.031 0.160 0.159Main,date=2010‐23‐9T12:05:21‐04:00 USA gasprocessing coalgasificaAon 0.136 0.046 0.067Main,date=2010‐23‐9T12:05:21‐04:00 USA gasprocessing naturalgas 18.267 21.692 23.517

Gasproduc+onbytechnology

scenario region sector subsector technology 1990 2005 2020

Main,date=2010‐23‐9T12:05:21‐04:00 USA gasprocessing biomassgasificaAon biomassgasificaAon 0.031 0.160 0.159

Main,date=2010‐23‐9T12:05:21‐04:00 USA gasprocessing coalgasificaAon coalgasificaAon 0.136 0.046 0.067

Main,date=2010‐23‐9T12:05:21‐04:00 USA gasprocessing naturalgas naturalgas 18.267 21.692 23.517