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.