Installation

To run pygcam, you need a Python 2.7 environment, Java, and GCAM. Follow the steps below to install these. Additional information is available below for Windows users.

Install support software

Anaconda

A convenient way to install and manage a Python environment is to use the free Anaconda distribution. You can use any installation of Python 2.7 if you prefer. Anaconda includes most of the scientific and statistical modules used by pygcam. Without Anaconda you may have to install more packages.

Java

You need a Java installation to run GCAM. If the link below doesn’t work, find the latest version of Java available from Oracle.

GCAM

You probably already have GCAM or you wouldn’t be reading this. But for completeness:

Setting up a structure for pygcam

A convenient way to manage GCAM is to create a folder called GCAM in your home directory (or anywhere you prefer). Copy the latest GCAM distribution (zip file) into this directory, and unzip the file.

Within this folder you might create a symbolic link called current which points to the current version of GCAM. This allows you to switch versions simply by changing the symbolic link. All pygcam configuration and project information will remain valid (unless, of course, the internal file structure of the GCAM distribution changes.)

Note that on Windows, the file explorer unhelpfully creates two folders with the same name. That is, if you unzip GCAM_4.2_r6539_User_Package_Windows.zip, you end up with a folder named GCAM_4.2_r6539_User_Package_Windows, and within it, another folder named GCAM_4.2_r6539_User_Package_Windows. In the file explorer, change the name of the outer folder to something else (‘x’ will do), and move the inner folder up one level. Delete the empty outer folder (‘x’, or whatever you called it.)

Install pygcam

There is a Python installer module called setup.py in the top level of the pygcam repository. You can running this script with various options to install, or uninstall pygcam.

  • If you are working with pygcam from a cloned git repository, you should install pygcam in ‘develop’ mode, which will create references to the source code and therefore will be updated whenever you update the repository. To do this, run the command:

    python setup.py develop

  • If you are not interested in maintaining links back to a source repository, you can run the standard installation procedure:

    python setup.py install

The setup.py script uses a Python module called setuptools. On Mac OS X and Linux, setup.py installs setuptools automatically. Unfortunately, automating this failed on Windows, so if the commands above fail, you will have to install setuptools.

  • To install setuptools manually, run this command in a terminal:

    conda install setuptools

Initialize the configuration file

The first time gt is run, it will create a default configuration file with all options present but commented out. Running gt -h, will print a usage message and create the initial configuration file (unless one is already present). The file is .pygcam.cfg found in your home directory.

Below are some key parameters you may wish to modify in your .pygcam.cfg file.

[DEFAULT]

# Set a default project to use if the "-P" flag is not specified to gt.
GCAM.DefaultProject = XXX

#
# Define parameters specific to project "XXX"
#
[XXX]
# Root directory in which to find user's project folders
GCAM.ProjectRoot    = %(Home)s/GCAM/XXX-dir

# The location of the default input file for the "run" sub-command
GCAM.ProjectXmlFile = %(GCAM.ProjectRoot)s/etc/project.xml

# These are used by the "query" sub-command
GCAM.QueryPath      = %(QueryDir)s:%(QueryDir)s/Main_Queries_Customized.xml
GCAM.RegionMapFile  = %(User.ProjectRoot)s/etc/Regions.txt

# Change this if desired to increase or decrease diagnostic messages.
# Possible values (from most to least verbose) are:
# DEBUG, INFO, WARNING, ERROR, CRITICAL
GCAM.LogLevel = DEBUG

# Sets the directory under which the "gcam" sub-command should create GCAM
# workspace directories before running GCAM
GCAM.RunWorkspaceRoot = %(Home)s/ws

# Tells gt where to look for plugins. Set to your project's plugin
# directory if you have any plugins to load.
# GCAM.PluginPath =

Default configuration variable dependencies

The following figure shows variable dependencies according to the default definitions. Variables lower in the figure depend on those above them. Thus, if you change a variable with “descendants”, you affect the definition of everything below it in the figure. See the generated ~/.pygcam.cfg for further information.

_images/ConfigVarStructure.jpg

Working with the pygcam source code

To examine or modify the pygcam Python code, you need to download the code using git.

Unix-like platforms

Unix-like platforms generally have git installed. Otherwise, install a current version for your platform. Do the following:

  • Open a terminal window. (Mac users can find this in /Application/Utilities/Terminal.app)

  • For this example, we will create a folder called x in our home directory to hold the git repository. Use any name you prefer. Run these commands to download a copy of the Python files:

    mkdir ~/bb
    cd ~/bb
    git clone git@bitbucket.org:plevin/pygcam.git
    
  • Configure Anaconda to know where the source code version of pygcam lives. TO BE DONE

Windows users

These are instructions are written assuming you have installed the Cygwin tools as described below. Use the following steps:

  • Install git (or a GUI version like Tortoise.)

  • Make a new folder to hold your git repository. For the sake of an example, we’ll make a new directory called bb (for bitbucket) in our home directory, but you can call this whatever you like.

    mkdir ~/bb    # ~ is shorthand for your home directory
    
  • Open a cygwin terminal run these commands to download the source code:

    cd ~/bb
    git clone git@bitbucket.org:plevin/pygcam.git
    

Tell python where pygcam is installed

To configure Anaconda to know where the source code version of pygcam is installed, do the following.

  • Run the following command to have Python print out the location of the “user site” directory, i.e., where we will create a ”.pth” file:

    python -c 'import site; site._script()' --user-site
    
  • Create a file in the “user site” directory called pygcam.pth. The line should contain a single line with the full pathname to the location to the top-level folder of the pygcam source code. (The file can be called anything as long as it ends in .pth.) You can do this with a text editor, or with the following commands, however be sure to replace pygcam-source-path with the path to the pygcam source, and user-site-path with the path displayed by the command above.

    # For this example, we assume that the user site (printed by the
    # command above) is /Users/rjp/.local/lib/python2.7/site-packages,
    # and we have cloned pygcam into the folder /Users/rjp/bb/pygcam:
    
    echo /Users/rjp/bb/pygcam > /Users/rjp/.local/lib/python2.7/site-packages/pygcam.pth
    

Using pygcam under Windows

The pygcam package was developed on Unix-like systems (Mac OS, Linux) and subsequently ported to Microsoft Windows. This page provides Windows-specific information.

Using Cygwin

Windows’ native command-line tools are fairly primitive. For folks new to running commmand-line programs, I recommend installing the (free, open-source) Cygwin package, which is a set of libraries and programs that provides a Linux-like experience under Windows.

Using bash will start you up the learning curve to use the GCAM Monte Carlo framework, which currently runs only on Linux systems. The bash shell (or your favorite alternative) offers numerous nice features. Exploring those is left as an exercise for the reader.

Cygwin provides an installer GUI that lets you select which packages to install. There is a huge set of packages, and you almost certainly won’t want all of it.

Download the appropriate setup.exe version (probably 64-bit). Run it and, for most people, you’ll just accept all the defaults. You might choose a nearby server for faster downloads.

I recommend installing just these for now (easy to add more later):

  • under Editors

    • nano (a very simple text editor useful for modifying config files and such)

    Editors popular with programmers include emacs and vim, though these have a steeper learning curve than nano.

  • Under shells:

    • bash (The GNU Bourne Again Shell – this is the terminal program)
    • bash-completion (saves a lot of typing)

Note

Don’t install python since we’re using Anaconda. Installing another version of Python just confuses things.

Optionally, if you plan to work with the code in the git repository, download git:

  • under Devel
    • git (select “git: Distributed version control system” and all the required libraries will be installed, too.)

Alternatively, you might try the free SourceTree application from Atlassian, which provides a nice user interface for git on Mac OS X and Windows.