Tutorial, Part 1

1.0 Introduction

Note

The first step after installing pygcam is to run the gt init command to initialize your pygcam configuration file. You will need to know where you have GCAM installed, and where you would like to put “project” files, which describe your project, and “sandboxes”, which are where GCAM workspaces are dynamically created.

Command-line basics

The command-line interface to pygcam uses the GCAM tool (gt) script, which is installed when you install pygcam. The gt command itself is just a wrapper for all the task-specific options, referred to as “sub-commands”.

The gt command itself, and all sub-commands accept a variety of command-line options (a.k.a. “flags”) that consist of either - or + followed by a single letter, or starting with -- (2 dashes) followed by longer names. Most options offer both the short and long form. For example, you can get help for any command by specifying either -h or --help. The following two commands are equivalent:

$ gt init -h

$ gt init --help

Note

In this tutorial, typed commands are shown preceded by the standard Unix $ prompt. You should not type the $, just the command following it!

Either of these will produce this message, describing all available options and any required arguments:

usage: gt init [-h] [-c] [-C] [-g GCAMDIR] [--overwrite] [-P DEFAULTPROJECT]
               [-p PROJECTDIR] [-s SANDBOXDIR]

optional arguments:
  -h, --help            show this help message and exit
  -c, --create-project  Create the project structure for the given default
                        project. If neither -c/--create-project nor -C/--no-
                        create-project is specified, the user is queried
                        interactively.
  -C, --no-create-project
  -g GCAMDIR, --gcamDir GCAMDIR
                        The directory that is a GCAM v4.3 or v4.4 workspace.
                        Sets config var GCAM.RefWorkspace. By default, looks
                        for gcam-v4.4 (then v4.3) in ~, ~/GCAM, and ~/gcam,
                        where "~" indicates your home directory.
  --overwrite           Overwrite an existing config file. (Makes a backup
                        first in ~/.pygcam.cfg~, but user is required to
                        confirm overwriting the file.)
  -P DEFAULTPROJECT, --defaultProject DEFAULTPROJECT
                        Set the value of config var GCAM.DefaultProject to the
                        given value.
  -p PROJECTDIR, --projectDir PROJECTDIR
                        The directory in which to create pygcam project
                        directories. Sets config var GCAM.ProjectRoot. Default
                        is "~/GCAM/projects".
  -s SANDBOXDIR, --sandboxDir SANDBOXDIR
                        The directory in which to create pygcam project
                        directories. Sets config var GCAM.SandboxRoot. Default
                        is "~/GCAM/sandboxes".

There are many “global” options available to the GCAM tool (gt) command that apply to all sub-commands, such as overriding the default project to run on a specific project, setting the desired level of diagnostic output (the “log level”), and to run the command on a compute node on a cluster computing system. These are distinguished by having their short form start with a +, though their long form retains the -- prefix. (An exception to this rule is the -h flag, which uses the - prefix in all cases.) To see the global options, use the command:

$ gt -h

Of course, you can also refer to the GCAM tool (gt) page on this site.

Initialize your configuration file

If you haven’t done so already, run the init command to initialize your pygcam configuration file, .pygcam.cfg.

• On Linux and macOS, the configuration file is found in your home directory, i.e., the value of the environment variable HOME.
• On Windows, the configuration will be stored in the directory identified by the first of the following environment variables defined to have a non-empty value: PYGCAM_HOME, HOMESHARE, and HOMEPATH. The first variable, PYGCAM_HOME is known only to pygcam, while at least one of the other two should be set by Windows.

See Initializing the configuration file for further details.

You can also use the config command to retrieve pygcam’s idea of your home directory. Here’s how it looks on macOS (and similar on Linux/Unix):

# List all configuration variables that include the word "home" (case insensitive)
$ gt config home
[tutorial]
          $HOME = /Users/rjp
     $JAVA_HOME = /Library/Java/JavaVirtualMachines/jdk1.8.0_74.jdk/Contents/Home
           Home = /Users/rjp

# Show the value of the configuration variable "Home" (case sensitive)
$ gt config -x Home
/Users/rjp

Same as above, but on Windows:

$ gt config home
[tutorial]
    $ANACONDA_HOME = /cygdrive/c/Users/rjp/Anaconda2
         $CYG_HOME = /cygdrive/c/Users/rjp
             $HOME = C:\cygwin64\home\rjp
        $HOMEDRIVE = C:
         $HOMEPATH = \Users\rjp
              Home = C:/Users/rjp

$ gt config -x Home
C:/Users/rjp

The “run” sub-command

In this tutorial, we focus on the run sub-command, which performs actions defined in the project.xml file, the location of which is specified by the config parameter GCAM.ProjectXmlFile, which defaults to %(GCAM.ProjectDir)s/etc/project.xml.

The basic GCAM workflow consists of a defining and running a baseline scenario and one or more policy scenarios, and then comparing the policy cases to the baseline.

• The project.xml file describes all the workflow steps required to setup, run, and analyze the scenarios.
• The scenarios.xml file defines the required modifications to reference GCAM input and configuration XML files required to implement the desired scenarios. The file can define multiple “scenario groups”, each consisting of a baseline and one or more policy scenarios.

The entire workflow or select steps can be run using the run sub-command. If no options are specified, as in:

$ gt run

the default scenario group (identified in project.xml) of the default project (defined in your configuration file) will be run, starting with the scenario identified as the baseline, followed by all policy scenarios. All defined workflow steps will be executed in the order defined, for all scenarios.

The run sub-command provides many options, including the ability to select which scenario group to run and limit which scenarios and steps to run (or not run). Use the help flag (-h or --help) to see all the options:

$ gt run -h

We begin Part 1 of the tutorial by examining a minimal project called tutorial. The project and scenario XML files are installed for you by the init sub-command.

1.1 The project.xml file

The following project.xml file is included automatically when you run the init or new sub-commands.

Note

For complete documentation of all XML file formats, see XML File Formats.

<?xml version="1.0" encoding="UTF-8"?>
<!--
This file defines the "tutorial" project. Feel free to edit it to your liking.
Also see project2.xml, which offers a slightly more complex example.
-->
<projects xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="project-schema.xsd">
  <project name="ctax">
    <vars>
      <var name="startYear">2015</var>
      <var name="endYear">2050</var>  <!-- stops at 2050 so tutorial runs faster -->
      <var name="years" eval="1">{startYear}-{endYear}</var>
    </vars>
    <steps>
      <!--
      The names defined in steps can be used on the command-line to limit operations to
      these steps. Steps are run in the order defined in this file, regardless of the
      order specified to "gt run". If runFor="baseline", the step is run only for baseline
      scenarios. If runFor="policy", the step is run only for non-baseline scenarios. If
      not set (or set to any other value) the step is run for all scenarios.
       -->
      <step name="setup" runFor="baseline">
        @setup -b "{baseline}" -g "{scenarioGroup}" -S "{scenarioSubdir}" -w "{scenarioDir}"
               -p {endYear} -y {years}
      </step>
      <step name="gcam"  runFor="baseline">@gcam -s "{baseline}" -S "{projectXmlDir}"</step>
      <step name="query" runFor="baseline">
        @query -o "{batchDir}" -w "{scenarioDir}" -s "{scenario}" -q "{queryXmlFile}"
      </step>

      <!--
        Explicitly require policy setup, gcam, and query steps to run after baseline to
        allow baseline results to be used in constraints
      -->
      <step name="setup" runFor="policy">
            @setup -b "{baseline}" -s "{scenario}" -g {scenarioGroup} -S "{scenarioSubdir}"
                   -w "{scenarioDir}" -p {endYear} -y {years}
      </step>
      <step name="gcam"  runFor="policy">@gcam -s "{scenario}" -S "{projectXmlDir}"</step>
      <step name="query" runFor="policy">
        @query -o {batchDir} -w "{scenarioDir}" -s "{scenario}" -q "{queryXmlFile}"
      </step>

      <!--
        Compute and plot differences between query results for policy and baseline scenarios
      -->
      <step name="diff"  runFor="policy">
        @diff -D "{sandboxDir}" -y {years} -q "{queryXmlFile}" "{baseline}" "{scenario}"
      </step>
      <step name="plotDiff" runFor="policy">
        @chart {diffPlotArgs} --reference "{baseline}" --scenario "{scenario}" --fromFile "{diffPlots}"
      </step>

      <!-- Generate an XLSX workbook from all CSV query result files -->
      <step name="xlsx"  runFor="policy">
        @diff -D "{diffsDir}" -c -y {years} -o diffs.xlsx {diffsDir}/*.csv
      </step>
    </steps>

    <!--
      Define which queries to run. This creates a text file whose name is stored
      in a project variable, accessed as {queryXmlFile} in the "query" step.
    -->
    <queries varName="queryXmlFile">
      <query name="LUC_emissions_by_region"/>
      <query name="total_climate_forcing"/>
      <query name="global_mean_temperature"/>
    </queries>

    <vars>
      <!-- common arguments for 'diffPlots' -->
      <var name="diffPlotArgs" eval="1">-D "{diffsDir}" --outputDir figures --years {years} --label --ygrid --zeroLine</var>
    </vars>

    <tmpFile varName="diffPlots">
      <text>LUC_emissions_by_region-{scenario}-{reference}.csv -Y 'Tg CO$_2$' -m C_to_CO2 -i -n 4 -T '$\Delta$ LUC emissions' -I region -x by-region.png</text>

      <!-- Forcing and temperature change -->
      <text>total_climate_forcing-{scenario}-{reference}.csv   -Y 'W/m$^2$' --timeseries -T '$\Delta$ Total Climate Forcing'</text>
      <text>global_mean_temperature-{scenario}-{reference}.csv -Y 'Degrees C' --timeseries -T '$\Delta$ Global Mean Temperature'</text>
    </tmpFile>

  </project>
</projects>

The file above defines steps to run for the “tutorial” project (see line 8). Each <step> is given a name which can be specified on the command-line as a step to run or to skip. All non-skipped steps are run in the order indicated, for all relevant scenarios.

The file starts by defining two project variables (lines 10 and 11) for the startYear and endYear of our analysis, and by combining these into a third variable, years (line 12). The attribute eval="1" indicates that the value shown should be evaluated to convert the variables named in curly-braces to their text values.

Next, the workflow steps are defined. The steps shown, or variations thereof, will be used for most GCAM projects. Each step has a required name attribute, which is used to identify the step on the command-line when you want to run or skip specific steps. The text between the <step> and </step> elements is the command to run for that step, after performing variable substitution on the text. Commands that start with @ refer to built-in or plug-in commands, which can be run internally by GCAM tool (gt).

The runFor attribute is optional. If not specified, the step will be run for both baseline and policy (non-baseline) scenarios. You can indicate runFor="baseline" to run the step only for baseline scenarios, or runFor="policy" to run it only for non-baseline scenarios. Some steps (e.g., computing differences) make sense only for policy scenarios. (Baseline scenarios are indicated as such in the scenarios.xml file, which we will turn to shortly.)

List defined steps

Use the -l or --listSteps option to the run sub-command to list the defined project steps:

$ gt run --listSteps
Steps:
  setup
  gcam
  query
  diff
  plotDiff
  xlsx

1.2 The scenarios.xml file

The following scenarios.xml file is also included automatically when you run the init or new sub-commands. It defines one scenario group consisting of a baseline and 4 carbon tax policy scenarios:

<?xml version="1.0" encoding="UTF-8"?>

<!--
This file defines the "tutorial" scenarios. Feel free to edit it to your liking.
Also see scenarios2.xml, which offers a slightly more complex example.
-->

<scenarios name="uniqueName" defaultGroup="group"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="scenarios-schema.xsd">

    <scenarioGroup name="group" useGroupDir="0">
        <scenario name="base" baseline="1">
            <!-- unmodified GCAM reference scenario -->
        </scenario>

        <!-- $10/tonne tax on fossil/industrial CO2, increasing by 5% per year -->
        <scenario name="tax-10">
            <!-- Add a line to the XML config file to load this file -->
            <add name="carbon_tax">../input/policy/carbon_tax_10_5.xml</add>
        </scenario>

        <!-- $25/tonne tax on fossil/industrial CO2, increasing by 5% per year -->
        <scenario name="tax-25">
            <add name="carbon_tax">../input/policy/carbon_tax_25_5.xml</add>
        </scenario>

        <!-- $10/tonne as above, but also tax biogenic CO2 -->
        <scenario name="tax-bio-10">
            <add name="carbon_tax">../input/policy/carbon_tax_10_5.xml</add>
            <function name="taxBioCarbon"/>
        </scenario>

        <!-- $10/tonne as above, but also tax biogenic CO2 -->
        <scenario name="tax-bio-25">
            <add name="carbon_tax">../input/policy/carbon_tax_25_5.xml</add>
            <function name="taxBioCarbon"/>
        </scenario>
    </scenarioGroup>
</scenarios>

This scenarios file relies on files distributed with GCAM that define various levels of carbon taxes:

$ cd ~/GCAM/gcam-v5.1.1/input/policy
$ ls carbon*
carbon_tax_10_5.xml  carbon_tax_15_5.xml  carbon_tax_20_5.xml  carbon_tax_25_5.xml

The baseline defined above modifies nothing in the GCAM reference scenario. Each of the four policy scenarios differs from this baseline only by including in the XML configuration file and a file that implements a carbon tax that starts at $10 or $25 per tonne of fossil and industrial CO₂ in 2020, and increases by 5% per year.

The two scenarios tax-bio-10 and tax-bio-25 additionally call a built-in setup function that also applies the carbon tax to biogenic carbon.

List defined scenario groups and scenarios

Use the -G (or --listGroups) option to the run sub-command to list the defined scenario groups, and the -L (or --listScenarios) option to list defined scenario names. You can use these individually or together (with the -l/--listSteps if you wish, too):

$ gt run -l -L -G
Scenario groups:
  group (default)
Scenarios:
  base
  tax-10
  tax-25
  tax-bio-10
  tax-bio-25
Steps:
  setup
  gcam
  query
  diff
  plotDiff
  xlsx

We can see all actual step commands as well, without running them, using the -n or --noRun option to the run sub-command:

$ gt run -n
INFO pygcam.project: [base, 1, setup] @setup -b base -g group -S base -w /Users/rjp/tmp/tut/sandboxes/tutorial/base -p 2050 -y 2015-2050
INFO pygcam.project: [base, 2, gcam] @gcam -s base -S ../local-xml
INFO pygcam.project: [base, 3, query] @query -o /Users/rjp/tmp/tut/sandboxes/tutorial/base/queryResults -w /Users/rjp/tmp/tut/sandboxes/tutorial/base -s base -q "/tmp/tmphIQDum.queries.xml"
INFO pygcam.project: [tax-bio-10, 4, setup] @setup -b base -s tax-bio-10 -g group -S tax-bio-10 -w /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-10 -p 2050 -y 2015-2050
INFO pygcam.project: [tax-bio-10, 5, gcam] @gcam -s tax-bio-10 -S ../local-xml
INFO pygcam.project: [tax-bio-10, 6, query] @query -o /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-10/queryResults -w /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-10 -s tax-bio-10 -q "/tmp/tmpeLs3qD.queries.xml"
INFO pygcam.project: [tax-bio-10, 7, diff] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/ -y 2015-2050 -q /tmp/tmpeLs3qD.queries.xml base tax-bio-10
INFO pygcam.project: [tax-bio-10, 8, plotDiff] @chart -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-10/diffs --outputDir figures --years 2015-2050 --label --ygrid --zeroLine --reference base --scenario tax-bio-10 --fromFile /tmp/tmpr0FFMt.project.txt
INFO pygcam.project: [tax-bio-10, 9, xlsx] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-10/diffs -c -y 2015-2050 -o diffs.xlsx /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-10/diffs/*.csv
INFO pygcam.project: [tax-10, 4, setup] @setup -b base -s tax-10 -g group -S tax-10 -w /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10 -p 2050 -y 2015-2050
INFO pygcam.project: [tax-10, 5, gcam] @gcam -s tax-10 -S ../local-xml
INFO pygcam.project: [tax-10, 6, query] @query -o /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10/queryResults -w /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10 -s tax-10 -q "/tmp/tmpGhBkT2.queries.xml"
INFO pygcam.project: [tax-10, 7, diff] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/ -y 2015-2050 -q /tmp/tmpGhBkT2.queries.xml base tax-10
INFO pygcam.project: [tax-10, 8, plotDiff] @chart -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10/diffs --outputDir figures --years 2015-2050 --label --ygrid --zeroLine --reference base --scenario tax-10 --fromFile /tmp/tmp5Thk5Q.project.txt
INFO pygcam.project: [tax-10, 9, xlsx] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10/diffs -c -y 2015-2050 -o diffs.xlsx /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10/diffs/*.csv
INFO pygcam.project: [tax-bio-25, 4, setup] @setup -b base -s tax-bio-25 -g group -S tax-bio-25 -w /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-25 -p 2050 -y 2015-2050
INFO pygcam.project: [tax-bio-25, 5, gcam] @gcam -s tax-bio-25 -S ../local-xml
INFO pygcam.project: [tax-bio-25, 6, query] @query -o /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-25/queryResults -w /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-25 -s tax-bio-25 -q "/tmp/tmphyJVaz.queries.xml"
INFO pygcam.project: [tax-bio-25, 7, diff] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/ -y 2015-2050 -q /tmp/tmphyJVaz.queries.xml base tax-bio-25
INFO pygcam.project: [tax-bio-25, 8, plotDiff] @chart -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-25/diffs --outputDir figures --years 2015-2050 --label --ygrid --zeroLine --reference base --scenario tax-bio-25 --fromFile /tmp/tmpDh5O0u.project.txt
INFO pygcam.project: [tax-bio-25, 9, xlsx] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-25/diffs -c -y 2015-2050 -o diffs.xlsx /Users/rjp/tmp/tut/sandboxes/tutorial/tax-bio-25/diffs/*.csv
INFO pygcam.project: [tax-25, 4, setup] @setup -b base -s tax-25 -g group -S tax-25 -w /Users/rjp/tmp/tut/sandboxes/tutorial/tax-25 -p 2050 -y 2015-2050
INFO pygcam.project: [tax-25, 5, gcam] @gcam -s tax-25 -S ../local-xml
INFO pygcam.project: [tax-25, 6, query] @query -o /Users/rjp/tmp/tut/sandboxes/tutorial/tax-25/queryResults -w /Users/rjp/tmp/tut/sandboxes/tutorial/tax-25 -s tax-25 -q "/tmp/tmpqP4ZMs.queries.xml"
INFO pygcam.project: [tax-25, 7, diff] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/ -y 2015-2050 -q /tmp/tmpqP4ZMs.queries.xml base tax-25
INFO pygcam.project: [tax-25, 8, plotDiff] @chart -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-25/diffs --outputDir figures --years 2015-2050 --label --ygrid --zeroLine --reference base --scenario tax-25 --fromFile /tmp/tmppfe8mK.project.txt
INFO pygcam.project: [tax-25, 9, xlsx] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-25/diffs -c -y 2015-2050 -o diffs.xlsx /Users/rjp/tmp/tut/sandboxes/tutorial/tax-25/diffs/*.csv

Note

Note that the messages shown above are written using the internal logging facility, at the log level INFO. (As indicated on each line.) If you set the GCAM.LogLevel higher than INFO (i.e., to WARNING, ERROR or FATAL) these messages will be suppressed.

1.3 Selecting and skipping scenarios and steps

You can select which scenarios and steps to run using the -S and -s flags, respective. For example, to run “setup” and “gcam” steps only for the baseline scenario “base”, we would use the following command:

$ gt run -S base -s setup,gcam

If we run this with the the -n option, we can see what would be run:

$ gt run -S base -s setup -n
INFO pygcam.project: [base, 1, setup] @setup -b base -g group -S base -w /Users/rjp/tmp/tut/sandboxes/tutorial/base -p 2050 -y 2015-2050
INFO pygcam.project: [base, 2, gcam] @gcam -s base -S ../local-xml

Note

When listing multiple steps or scenarios, separate their names with a “,” and do not include spaces.

Sometimes we want to run most of the steps except for a few. Use the -K and -k flags to indicate which scenarios or steps, respectively, to skip. All other defined scenarios and steps will be run.

This command runs all steps other than setup and gcam for scenario base:

$ gt run -S tax-10 -k setup,gcam -n
INFO pygcam.project: [tax-10, 6, query] @query -o /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10/queryResults -w /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10 -s tax-10 -q "/tmp/tmpVPqhmn.queries.xml"
INFO pygcam.project: [tax-10, 7, diff] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/ -y 2015-2050 -q /tmp/tmpVPqhmn.queries.xml base tax-10
INFO pygcam.project: [tax-10, 8, plotDiff] @chart -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10/diffs --outputDir figures --years 2015-2050 --label --ygrid --zeroLine --reference base --scenario tax-10 --fromFile /tmp/tmpD2WMy4.project.txt
INFO pygcam.project: [tax-10, 9, xlsx] @diff -D /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10/diffs -c -y 2015-2050 -o diffs.xlsx /Users/rjp/tmp/tut/sandboxes/tutorial/tax-10/diffs/*.csv

1.4 Creating additional scenarios

We can add more tax scenarios to our file by copying and pasting the existing one, and changing a few numbers to other values, to also use the $15 and $20 per tonne files provide. These would look like this:

<scenario name="tax-15">
    <add name="carbon_tax">../input/policy/carbon_tax_15_5.xml</add>
</scenario>

<scenario name="tax-20">
    <add name="carbon_tax">../input/policy/carbon_tax_20_5.xml</add>
</scenario>

Copying and pasting isn’t a bad approach with our simple scenarios, which merely add one file each to the reference scenario. If our scenarios were much more involved, copying and pasting would become troublesome, particularly if we needed to make changes that affected all the scenarios.

Using iterators

You can create similar scenarios using “iterators”, which define a set of values to iterate over, with a new scenario (or scenario group) defined for each value of the iterator.

The following is equivalent to our “cut & paste” example above:

<scenarios name="uniqueName" defaultGroup="group"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="scenarios-schema.xsd">

      <!-- Our policy scenarios will use these levels of carbon taxes -->
    <iterator name="tax"   type="list" values="10,15,20,25"/>

    <scenarioGroup name="group" useGroupDir="0">
        <scenario name="base" baseline="1">
            <!-- unmodified GCAM reference scenario -->
        </scenario>

        <scenario name="tax-{tax}" iterator="tax">
            <!-- Add a line to the XML config file to load this file -->
            <add name="carbon_tax">../input/policy/carbon_tax_{tax}_5.xml</add>
        </scenario>

        <!-- As above, but also tax biogenic CO2 -->
        <scenario name="tax-bio-{tax}" iterator="tax">
            <add name="carbon_tax">../input/policy/carbon_tax_{tax}_5.xml</add>
            <function name="taxBioCarbon"/>
        </scenario>
    </scenarioGroup>
</scenarios>

The example above defines an iterator named “tax”, with values 10, 15, 20, and 25. The scenario group includes the same baseline as before, but now there are just two <scenario> definitions, one for fossil carbon and one for fossil and biogenic carbon. The term {tax} is replaced by each value of the iterator in turn, defining a new scenario, and indicating which file to include in the <add> element. Thus, by iterating over the tax levels, we have created 9 scenarios: one baseline and 8 policy scenarios.

The file shown above is included in your project’s etc directory by the init and new sub-commands, as scenarios-iterator.xml. You can cause GCAM tool (gt) to use this alternate scenarios either by renaming it to scenarios.xml (saving the old file, if you wish) or by editing your config file to include the following:

GCAM.ScenarioSetupFile  = %(GCAM.ProjectDir)s/etc/scenarios-iterator.xml

You can include this in the [DEFAULT] section, but then it would apply to all projects. Better to include it in the [tutorial] projects’s section only.

Editing .pygcam.cfg

In the next step, we will edit the configuration file. You can use any editor capable of working with plain text. (Word-processors such as Word introduce formatting information into the file which renders it unusable by pygcam.) On Linux, you might try the simple nano editor, or the more powerful (and complicated) vim or emacs editors popular with programmers.

On Windows, a good option is the free Notepad++. On the Mac, you can use TextEdit.app to edit plain text files.

You can use the command gt config -e to invoke a system-appropriate editor on the configuration file. On macOS and Windows, this command defaults to opening the config file with TextEdit.app (macOS) and NotePad++ (Windows). See the Configuration System page for firther details.

Checking iterator results

If you set the configuration file variable GCAM.ScenarioSetupOutputFile to the pathname of a file, the run sub-command will write the “expanded” scenario definitions to this file each time it runs. For example:

GCAM.ScenarioSetupOutputFile = %(Home)s/scenariosExpanded.xml

Results in the following:

# Set the logLevel high to suppress output, and use -n to avoid running
# actual commands. This has the side-effect of generating the XML file.
$ gt --logLevel=ERROR run -n
$ cat ~/scenariosExpanded.xml
<setup>
   <scenarioGroup name="group" useGroupDir="0" srcGroupDir="">
      <scenario name="base" baseline="1">
      </scenario>
      <scenario name="tax-10" baseline="0">
         <add name='carbon_tax'>../input/policy/carbon_tax_10_5.xml</add>
      </scenario>
      <scenario name="tax-15" baseline="0">
         <add name='carbon_tax'>../input/policy/carbon_tax_10_5.xml</add>
      </scenario>
      <scenario name="tax-20" baseline="0">
         <add name='carbon_tax'>../input/policy/carbon_tax_10_5.xml</add>
      </scenario>
      <scenario name="tax-25" baseline="0">
         <add name='carbon_tax'>../input/policy/carbon_tax_10_5.xml</add>
      </scenario>
      <scenario name="tax-bio-10" baseline="0">
         <add name='carbon_tax'>../input/policy/carbon_tax_10_5.xml</add>
         <function name='taxBioCarbon' dynamic='False'>None</function>
      </scenario>
      <scenario name="tax-bio-15" baseline="0">
         <add name='carbon_tax'>../input/policy/carbon_tax_10_5.xml</add>
         <function name='taxBioCarbon' dynamic='False'>None</function>
      </scenario>
      <scenario name="tax-bio-20" baseline="0">
         <add name='carbon_tax'>../input/policy/carbon_tax_10_5.xml</add>
         <function name='taxBioCarbon' dynamic='False'>None</function>
      </scenario>
      <scenario name="tax-bio-25" baseline="0">
         <add name='carbon_tax'>../input/policy/carbon_tax_10_5.xml</add>
         <function name='taxBioCarbon' dynamic='False'>None</function>
      </scenario>
   </scenarioGroup>
</setup>

In Tutorial, Part 2, we begin to use GCAM tool (gt) to run GCAM and analyze results.