Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Python 2.7 library and scripts for interfacing with GCAM

Project Description


pygcam is a Python package that provides classes, functions, and scripts for working with GCAM.

Core functionality

  • Project workflow management framework that lets you define steps to run and run them all or run steps selectively.
  • The main gt (GCAM tool) script, which provides numerous sub-commands, and can be extended by writing plug-ins.
  • The gt sub-commands facilitate key steps in working with GCAM, including:
    • Setting up experiments by modifying XML input files and configuration.xml
    • Running GCAM, locally or by queueing jobs on a Linux cluster
    • Querying the GCAM database to extract results to CSV files
    • Interpolating between time-steps and computing differences between baseline and policy cases
    • Plotting results

Who do I talk to?

Release Notes

Version 1.0b12 (22 May 2017)

  • No new features, just updates to get documentation building properly on

Version 1.0b11 (17 May 2017)

  • Created “init” command to interactively set key config variables
  • Added config variables GCAM.LogFileFormat and GCAM.LogConsoleFormat to customize the messages produced by the logging system.
  • Added setPriceElasticity function, callable from scenarios.xml scripts
  • Improved GCAM installation script to work across all 3 GCAM platforms.
  • Fixed home drive / home directory access on Windows
  • Added “saveAs” attribute to query specification to allow a query to be rewritten (i.e., aggregated) different ways and saved to CSV files with different names.

Version 1.0b10 (9 Feb 2017)

  • Fixed bugs in pyinstaller versions

Version 1.0b9 (8 Feb 2017)

  • Changed default value of GCAM.SandboxRoot from {GCAM.Root}/ws to {GCAM.Root}/sandbox
  • Added “mi” sub-command to invoke ModelInterface from the command-line after creating a file that refers to the project’s custom query file (if GCAM.MI.QueryFile is set) or to the reference query file.
  • Various fixes for the “one-directory” version of pygcam installer
  • Improved script
  • Addressed matplotlib issue on Macs

Version 1.0b8 (31 Jan 2017)

  • Added label to identify default scenario group in listing groups via “gt run -G”

  • Added function to to create linked land-use change CO2 to carbon tax or cap policies:

    genLinkedBioCarbonPolicyFile(filename, market='global', regions=None, forTax=True, forCap=False)

  • Also added function (bioCarbonTax) callable from XML setup file to access this feature.

  • Added initial support to integrate pygcam-mcs (coming soon!)

Version 1.0b7 (6 Dec 2016)

  • Made the <scenariosFile> element optional in project.xml, using the value of GCAM.ScenarioSetupFile by default.

  • Added function callable from setup XML, <protectionScenario name=”xxx”/>, which indicates a protection scenario to use from the file defined by config variable GCAM.ProtectionXmlFile.

  • Reversed previous modification to handling of “gt config -e” (edit config file) which had placed quotes around the value of GCAM.TextEditor. This breaks commands like “emacs -nw” since this is now seen as the command name. Solution is for users with spaces within a command name to add the quotes in the config file, e.g.,

    GCAM.TextEditor = "c:/Programs/Some Path With Spaces/someEditor.exe"

  • Added check to prevent deletion of files within reference workspace, which could happen under specific circumstances with symbolic links.

  • Added new “srcGroupDir” attribute to <scenario> element to identify a directory holding static XML files for a scenario, allowing related scenarios to share these files without requiring copying or symlinks.

Version 1.0b5 (9 Nov 2016)

  • Minor adjustments to setup to label documentation with correct version and to allow symlink warning for Windows to be suppressed by setting config var GCAM.SymlinkWarning = False

Version 1.0b4 (9 Nov 2016)

  • Fixed lingering symlink issues on Windows version.

Version 1.0b3 (7 Nov 2016)

  • Fixed several problems with Windows version:
    • Whereas on Linux and OS X, the user’s home directory is unambiguous, Windows has both HOMESHARE and HOMEPATH, at least one of which should be non-empty, but neither is guaranteed correct. Thus for Windows, the user can define PYGCAM_HOME to be the folder in which to create the .pygcam.cfg` file. Pygcam looks for the first directory found searching in the order ``PYGCAM_HOME, HOMESHARE, and finally HOMEPATH.
    • Pygcam was attempting to symlink some files and failing if the Windows user didn’t have symlink permission. This has been corrected to copy in all cases if symlinks fail.
    • When copying is required, pygcam was copying more than was required from the reference workspace. (With v4.3, the “input” folder holds much more than just XML files…) The copying is now limited to folders containing XML files. (But it’s still best if you can arrange to have permission to create symbolic links, since that avoids all the copying.)

Version 1.0b2

  • If you were stymied by the installation process, you can try the new zipped all-in-one directory that bundles everything needed to run gcamtool (the “gt” command) without any additional downloads or installation steps other than setting your PATH variable. This works only for Mac and Windows. See for details.

  • A new feature of the “run” sub-command lets your run a scenario group on a cluster with one command. The baseline is queued and all policy scenarios are queued with a dependency on completion of the baseline job. Just specify the -D option to the run sub-command.

    You can run all scenarios for all scenario groups of a project this way by specifying the -D (or –distribute) and -a (or –allGroups) flags together. All baselines will start immediately with all policy scenarios queued as dependent on the corresponding baseline.

  • The requirement to install xmlstarlet has been eliminated: all XML manipulation is now coded in Python, but it’s still fast since it uses the same libxml2 library that xmlstartlet is based on.

  • All configuration variables have been updated with defaults appropriate for GCAM 4.3.

  • The “group” attribute of project <step> elements now is treated as a regular expression of an exact match is not found. So if you have, say, groups FuelShock-0.9 and FuelShock-1.0, you can declare a step like the following that applies to both groups:

    <step name="plotCI" runFor="policy" group="FuelShock"> ... some command ... </step>

  • Updated carbon tax generator. This can be called from a scenarios.xml file as follows (default values are shown):

    <function name="taxCarbon">initialValue, startYear=2020, endYear=2100, timestep=5, rate=0.05, regions=GCAM_32_REGIONS, market='global'</function>

    • The regions argument must be a list of regions in Python syntax, e.g., [“USA”] or [“USA”, “EU27”].
    • It creates the carbon tax policy in a file called carbon-tax-{market-name}.xml, which is added automatically to the current configuration file.
Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pygcam-1.0b12.tar.gz (585.1 kB) Copy SHA256 Checksum SHA256 Source May 22, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting