GCAM tool (gt)

The gt script unifies GCAM workflow managment functionality into a single script with sub-commands. Generic sub-commands are implemented directly by the pygcam library. Project-specific features can be added via plugins.

Note

Quick links to sub-commands: building, chart, config, diff, gcam, gui, init, mcs, mi, new, protect, query, run, setup, sandbox, transport

The sub-commands support all the major workflow setups, including

  • Modify XML files and configuration.xml to set up a modeling experiment (See the setup sub-command and GCAM XML-Setup for more information.)
  • Run GCAM in an automatically-created workspace, allowing multiple instances of GCAM to run simultaneously, e.g., on parallel computing systems (See the gcam sub-command.)
  • Execute batch queries against the XML database to extract GCAM results, with on-the-fly regionalization based on a simple region-mapping file. (See the query sub-command.)
  • Compute differences between policy and baseline scenarios, including linear annualization of values between time-steps, and (See the diff sub-command.)
  • Plot results, with flexible control of figure features including title, axis labels, scale, and so on. (See the chart sub-command.)
  • Manage (create, delete, rename, run commands in) automatically-created workspaces. (See the sandbox sub-command.)

In addition, the run sub-command allows workflow steps to be defined in an XML file so that individual or groups of steps can be executed for one or more scenarios. The run sub-command supports direct invocation of other workflow steps as well as running arbitrary programs of the user’s choosing.

Finally, gt allows all project steps to be run on a compute node in a High-Performance Computing environment by specifying +b or --batch on the command-line. (Note that this is not available on Mac OS X or Windows.)

For example, the command:

gt +b +P MyProject run -S MyScenario

runs all steps for scenario MyScenario in the project MyProject by queuing a batch job on the default queue. Arguments to gt allow the user to set various resource requirements and to select the queue to use.

The command to run to queue the batch job is taken from the configuration file parameter GCAM.BatchCommand. Example batch commands for the SLURM and PBS job management systems are provided in variables GCAM.QueueSLURM and GCAM.QueuePBS, respectively.

Command-line usage is described below. Note that some command-line (e.g., batch-related) options must precede the sub-command, whereas sub-command specific options must follow it.

Note

Note that arguments that pertain regardless of the sub-command (e.g., +P to identify the project name) are specified prior to the sub-command, and use + rather than -. This is to avoid conflicts between these “main” arguments and sub-command arguments. (An exception is gt -h, which retains the -.) Long-form argument names use two hyphens, as in --projectName.)

Usage

Extending gt using plug-ins

The gt script will load any python files whose name ends in _plugin.py, found in any of the directories indicated in the config file variable GCAM.PluginPath. The value of GCAM.PluginPath must be a sequence of directory names separated by colons (:) on Unix-like systems or by semi-colons (;) on Windows.

See pygcam.subcommand for documentation of the plug-in API.