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: chart, config, diff, gcam, gui, init, mcs, mi, new, protect, query, run, setup, sandbox
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¶
usage: gt [-h] [+b] [+B] [+D DIRMAP] [+e ENVIROVARS] [+j JOBNAME]
[+l LOGLEVEL] [+L LOGFILE] [+m MINUTES] [+M {trial,gensim}]
[+P name] [+q QUEUENAME] [+r RESOURCES] [+s name=value] [+v]
[--version] [--VERSION]
{building,chart,compare,config,diff,gcam,gui,init,mcs,mi,new,protect,query,res,run,sandbox,setup}
...
Named Arguments¶
+b, --batch |
Default: False |
+B, --showBatch | |
Show the batch command to be run, but don’t run it. (Linux only) Default: False | |
+D, --dirmap |
|
+e, --enviroVars | |
| |
+j, --jobName |
Default: “gt” |
+l, --logLevel |
Default: “INFO” |
+L, --logFile |
|
+m, --minutes |
Default: 20.0 |
+M, --mcs | Possible choices: trial, gensim Used only when running gcamtool from pygcam-mcs. |
+P, --projectName | |
Default: “” | |
+q, --queueName | |
Default: “slurm” | |
+r, --resources | |
Default: “” | |
+s, --set |
Default: [] |
+v, --verbose | Show diagnostic output Default: False |
--version | show program’s version number and exit |
--VERSION | Default: False |
Subcommands¶
For help on subcommands, use the “-h” flag after the subcommand name
subcommand | Possible choices: building, chart, compare, config, diff, gcam, gui, init, mcs, mi, new, protect, query, res, run, sandbox, setup |
Sub-commands:¶
building¶
Dump combinations of building energy use sectors, techs, and fuels.
gt building [-h] [-p PROJECT] [-o OUTPUTFILE] [-s SECTORS] [-r REGIONS] [-u]
[-y YEARS]
Named Arguments¶
-p, --project | The name of the project to use to locate GCAM reference files. Default is “gcam_res” Default: “gcam_res” |
-o, --outputFile | |
Default: “building_tech_template.csv” | |
-s, --sectors |
|
-r, --regions |
|
-u, --GCAM-USA | If set, produce output compatible with GCAM-USA regions. Default: False |
-y, --years |
Default: “2015-2100” |
chart¶
The chart
sub-command generates plots from GCAM-style “.csv” files.
Two types of plots are currently supported: (i) stacked bar plots based on summing values
over all years (with optional interpolation of annual values), by the given ‘indexCol’
(default is ‘region’), and (ii) stacked bar plots by year for some data column, where the data
are grouped by and summed across elements with the indicated ‘indexCol’. The first option is
indicated by using the -S
(--sumYears
) option. Numerous options allow the appearance to
be customized.
You can perform on-the-fly unit conversions using the -m
/ --multiplier
or
-V
/ --divisor
arguments, which cause all values in “year columns” to be
multiplied or divided, respectively, by the values provided. Values can be specified
as numeric constants or using symbolic constants defined in the pygcam.units
module.
gt chart [-h] [-b] [-B] [-c COLUMNS] [-C CONSTRAINT] [-d OUTPUTDIR]
[-D WORKINGDIR] [-e] [-f FROMFILE] [-F DIVISORFILE] [--format FORMAT]
[-g] [-i] [-I INDEXCOL] [-k] [-l] [-L LABELCOLOR] [-m MULTIPLIER]
[-M MULTIPLIERFILE] [-n NCOL] [-N SCENARIO] [--negate] [-o OUTFILE]
[-O] [-p PALETTE] [-r ROTATION] [-R REFERENCE] [--region REGION]
[-s SKIPROWS] [-S] [-t YEARSTEP] [-T TITLE] [--timeseries]
[--transparent] [-u UNSTACKEDCOL] [-U UNSTACKEDREGION] [-v VALUECOL]
[-V DIVISOR] [-x SUFFIX] [-X XLABEL] [-Y YLABEL] [-y YEARS]
[--ymax YMAX] [--ymin YMIN] [-z] [--legendY LEGENDY]
[--barWidth BARWIDTH]
[csvFile]
Positional Arguments¶
csvFile | The file containing the data to plot. |
Named Arguments¶
-b, --box | Draw a box around the plot. Default is no box. Default: False |
-B, --byRegion |
Default: False |
-c, --columns |
Default: “output” |
-C, --constraint | |
| |
-d, --outputDir | |
The directory into which to write image files. Default is “.” Default: “.” | |
-D, --workingDir | |
The directory to change to before performing any operations Default: “.” | |
-e, --enumerate | |
Default: False | |
-f, --fromFile |
|
-F, --divisorFile | |
| |
--format |
|
-g, --ygrid | Show light grey horizontal lines at the major Y-axis ticks. Default is no grid. Default: False |
-i, --interpolate | |
Interpolate (linearly) annual values between timesteps. Default: False | |
-I, --indexCol |
Default: “region” |
-k, --yticks | Show tick marks on Y-axis. Default is no tick marks. Default: False |
-l, --label | Add text along the right side of the figure showing the filename. Default: False |
-L, --labelColor | |
| |
-m, --multiplier | |
| |
-M, --multiplierFile | |
| |
-n, --ncol | The number of columns with which to display the legend. Default is 5. Default: 5 |
-N, --scenario |
Default: “” |
--negate |
Default: False |
-o, --outFile |
Default: “” |
-O, --open | Open the plot file after generating it. Default: False |
-p, --palette |
|
-r, --rotation |
Default: 90 |
-R, --reference | |
Default: “reference” | |
--region | Plot values only for the given region. |
-s, --skiprows |
Default: 1 |
-S, --sumYears |
Default: False |
-t, --yearStep |
Default: 5 |
-T, --title |
Default: “” |
--timeseries | Plot the data as a time series. Default: False |
--transparent | Save the plot with a transparent background. (Default is white.) Default: False |
-u, --unstackedCol | |
| |
-U, --unstackedRegion | |
| |
-v, --valueCol | Identify a single column (e.g., a year) to plot for bar plots. |
-V, --divisor |
|
-x, --suffix |
|
-X, --xlabel |
Default: “” |
-Y, --ylabel |
Default: “EJ” |
-y, --years |
Default: “” |
--ymax |
|
--ymin |
|
-z, --zeroLine | Whether to show a line at Y=0 Default: False |
--legendY |
|
--barWidth |
Default: 0.5 |
compare¶
- Compare two GCAM configuration files and the files they load to
- find differences. Files are compared using “diff” based on matching “name” tags.
gt compare [-h] [-o OUTPUTDIR] config1 exedir1 config2 exedir2
Positional Arguments¶
config1 | The first of two config files to compare. |
exedir1 | The “exe” from which config1 pathnames should be computed. |
config2 | The second of two config files to compare. |
exedir2 | The “exe” from which config2 pathnames should be computed. |
Named Arguments¶
-o, --outputDir | |
Default: “/tmp/xmlCompare” |
config¶
The config command list the values of configuration variables from ~/.pygcam.cfg.
With no arguments, it displays the values of all variables for the default project.
Use the -d
flag to show only values from the [DEFAULT]
section.
If an argument name
is provided, it is treated as a substring pattern, unless the
-x
flag is given (see below). All configuration variables containing the give name
are displayed with their values. The match is case-insensitive.
If the -x
or --exact
flag is specified, the argument is treated as an exact
variable name (case-sensitive) and only the value is printed. This is useful mainly
for scripting. For general use the substring matching is more convenient.
Examples:
$ gt config project
[MyProject]
GCAM.DefaultProject = MyProject
GCAM.ProjectRoot = /Users/rjp/bitbucket/myProject
GCAM.ProjectXmlFile = /Users/rjp/bitbucket/myProject/etc/project.xml
$ gt config -x GCAM.DefaultProject
MyProject
$ gt config sand
MyProject]
GCAM.SandboxRoot = /Users/rjp/ws/myProject
$ gt config sand -d
[DEFAULT]
GCAM.SandboxRoot = /Users/rjp/ws
gt config [-h] [-d] [-e] [-x] [-t] [name]
Positional Arguments¶
name | Show the names and values of all parameters whose name contains the given value. The match is case-insensitive. If not specified, all variable values are shown. Default: “” |
Named Arguments¶
-d, --useDefault | |
Indicates to operate on the DEFAULT section rather than the project section. Default: False | |
-e, --edit | Edit the configuration file. The command given by the value of config variable GCAM.TextEditor is run with the .pygcam.cfg file as an argument. Default: False |
-x, --exact | Treat the text not as a substring to match, but as the name of a specific variable. Match is case-sensitive. Prints only the value. Default: False |
-t, --test | Test the settings in the configuration file to ensure that the basic setup is ok, i.e., required parameters have values that make sense. If specified, no variables are displayed. Default: False |
diff¶
The diff
sub-command script computes the differences between results from two or
more CSV files generated from batch queries run on a GCAM database, saving
the results in either a CSV or XLSX file, according to the extension given to
the output file. If not provided, the output filename defaults to differences.csv.
If multiple otherFiles are given (i.e., the referenceFile plus 2 or more other files named on the command-line), the resulting CSV file will contain one difference matrix for each otherFile, with a label indicating which pair of files were used to produce each result.
When the output file is in XLSX format, each result is written to a separate worksheet. If the -c flag is specified, no differences are computed; rather, the .csv file contents are combined into a single .xlsx file.
gt diff [-h] [-D WORKINGDIR] [-g GROUPSUM] [-i] [-o OUTFILE] [-c] [-p]
[-q QUERYFILE] [-r REWRITESETSFILE] [-S] [-s SKIPROWS] [-y YEARS]
[-Y STARTYEAR]
csvFiles [csvFiles ...]
Positional Arguments¶
csvFiles |
|
Named Arguments¶
-D, --workingDir | |
The directory to change to before performing any operations Default: “.” | |
-g, --groupSum |
Default: “” |
-i, --interpolate | |
Interpolate (linearly) annual values between timesteps. Default: False | |
-o, --outFile |
Default: “differences.csv” |
-c, --convertOnly | |
Convert the given CSV files into an Excel workbook, one sheet per CSV file. Default: False | |
-p, --asPercentChange | |
Compute percent change rather than simple difference. Default: False | |
-q, --queryFile | |
Default: “” | |
-r, --rewriteSetsFile | |
| |
-S, --sum | Sum all timestep (or interpolated annual values) to produce a single time-series. Default: False |
-s, --skiprows |
Default: 1 |
-y, --years |
Default: “” |
-Y, --startYear | |
The year at which to begin interpolation Default: 0 |
gcam¶
The gcam
sub-command runs the GCAM executable on the designated configuration
file, scenario, or workspace. Typical use (e.g., from a project.xml
file) would
be to run GCAM by referencing a directory named the same as a scenario, holding a
file called config.xml
, as is generated by the setup
sub-command. (See
GCAM XML-Setup.)
If a workspace is specified on the command-line, it is used. Otherwise, if a
scenario is specified, the workspace defined by {GCAM.SandboxDir}/{scenario}
is used. If neither workspace nor scenario are defined, the value of config
variable GCAM.RefWorkspace
is used, i.e., GCAM is run in the reference
workspace.
If the workspace doesn’t exist, it is created based on the reference GCAM workspace,
defined by the configuration variable GCAM.RefWorkspace
. By default, read-only
directories (e.g., input and libs) are symbolically linked from the new workspace to
the reference one. (See the new sub-command for more information
on the creation of workspaces.)
Directories into which GCAM writes results (e.g., output and exe) are created in the new workspace, but read-only files within exe (e.g., the GCAM executable) are symbolically linked (with the same caveat for Windows users.)
Usage example:
gt gcam -S ~/MyProject/scenarios -s MyScenario -w ~/sandboxes/MyProject/MyScenario
would run the scenario MyScenario
in the newly created sandbox (workspace)
~/sandboxes/MyProject/MyScenario
using the configuration file
~/MyProject/scenarios/MyScenario/config.xml
.
gt gcam [-h] [-C CONFIGFILE] [-f] [-g GROUPDIR] [-n] [-r REFWORKSPACE]
[-s SCENARIO] [-S SCENARIOSDIR] [-w WORKSPACE] [-W]
Named Arguments¶
-C, --configFile | |
| |
-f, --forceCreate | |
Re-create the workspace, even if it already exists. Default: False | |
-g, --groupDir | The scenario group directory name, if any. Default: “” |
-n, --noRun | Don’t run GCAM; just print the command that would be run. Default: False |
-r, --refWorkspace | |
| |
-s, --scenario | The scenario to run. Default: “” |
-S, --scenariosDir | |
Default: “” | |
-w, --workspace | |
| |
-W, --noWrapper | |
Default: False |
gui¶
Run the Graphical User Interface (GUI) generated from the command-line interface in a local web server available at http://127.0.0.1:8050.
gt gui [-h] [-d]
Named Arguments¶
-d, --debug | Set the dash (flask) debug flag. Default: False |
init¶
Create the configuration file ~/.pygcam.cfg and initialize key variables, based on command-line arguments, or interactive prompts. See Initializing the configuration file for details.
gt init [-h] [-c | -C] [-g GCAMDIR] [--overwrite] [-P DEFAULTPROJECT]
[-p PROJECTDIR] [-s SANDBOXDIR]
Named Arguments¶
-c, --create-project | |
| |
-C, --no-create-project | |
| |
-g, --gcamDir |
|
--overwrite |
Default: False |
-P, --defaultProject | |
| |
-p, --projectDir | |
| |
-s, --sandboxDir | |
|
mcs¶
Enable or disable Monte Carlo Simulation (MCS) mode, or check whether MCS mode is currently enabled or disabled.
gt mcs [-h] {on,off,status}
Positional Arguments¶
mode | Possible choices: on, off, status Turn MCS mode on or off, or report current setting |
mi¶
Invoke ModelInterface from the command-line after changing directory to the value
of config variable GCAM.QueryDir
. If the file model_interface.properties
is found,
it is used as is, unless the -u/--updateProperties
flag is specified, in which case
the file is modified so that the queryFile
entry refers to the value of
GCAM.MI.QueryFile
, if this refer to an existing file, otherwise, by variable the
GCAM.MI.RefQueryFile
.
If the file model_interface.properties
is not found, it is created automatically
before invoking ModelInterface.
If the -d/--useDefault
flag is given, the model_interface.properties
file is
modified to refer to the GCAM reference Main_Queries.xml
file.
If you have a customized queries XML file, set the config variable GCAM.MI.QueryFile
to the path to this file and it will be loaded into ModelInterface via this command.
gt mi [-h] [-d] [-u]
Named Arguments¶
-d, --useDefault | |
Default: False | |
-u, --updateProperties | |
Default: False |
new¶
Create the directory structure and basic files required for a new pygcam project.
If a directory is specified with the -r
flag, the project is created with the
given name in that directory; otherwise the project is created in the directory
identified by the config variable GCAM.ProjectRoot
.
This sub-command creates examples of xmlsrc/scenarios.py
,
etc/protection.xml
, etc/project.xml
, etc/rewriteSets.xml
, and
etc/scenarios.xml
that can be edited to fit the needs of your project.
The file etc/Instructions.txt
is also created to provide further information.
If the -c
flag is given, a basic entry for the new project is added to the
users configuration file, $HOME/.pygcam.cfg
. Before modifying the config file,
a backup is created in $HOME/.pygcam.cfg~
. For example, the command
gt new -c foo
generates and entry like this:
[foo]
# Added by "new" sub-command Thu Sep 22 14:30:29 2016
GCAM.ProjectDir = %(GCAM.ProjectRoot)s/foo
GCAM.ScenarioSetupFile = %(GCAM.ProjectDir)s/etc/scenarios.xml
GCAM.RewriteSetsFile = %(GCAM.ProjectDir)s/etc/rewriteSets.xml
The example project defines two scenario groups, consisting of a baseline and 4 carbon tax scenarios. In one group, 90% of unmanaged land is protected (i.e., removed from consideration), as in the reference GCAM scenario. In the other scenario group, this protection is not performed, so all land is considered available for use.
gt new [-h] [-c] [--overwrite] [-r PATH] name
Positional Arguments¶
name |
|
Named Arguments¶
-c, --addToConfig | |
Default: False | |
--overwrite |
Default: False |
-r, --projectRoot | |
|
protect¶
Generate versions of GCAM’s land_input XML files that protect a given fraction of land of the given land types in the given regions by subtracting the required land area from the “managed” land classes, thereby removing them from consideration in land allocations.
Simple protection scenarios can be specified on the command-line. More complex scenarios can be specified in an XML file, landProtection.xml.
Examples:
# Create and modify copies of the reference land files, renaming them with
# "prot\_" prefix. Protect 80% of the "UnmanagedForest" and "UnmanagedPasture"
# land classes in the specified regions only.
CLASSES=UnmanagedForest,UnmanagedPasture
REGIONS='Australia_NZ,Canada,EU-12,EU-15,Japan,Middle East,Taiwan,USA'
OUTDIR="$HOME/tmp/xml"
gt protect -f 0.8 "$INFILES" -l "$CLASSES" -r "$REGIONS" -o "$OUTDIR" -t 'prot_{filename}'
# Run the land protection scenario "s1", described in the file ``$HOME/protect.xml``,
# placing the results in the directory ``$HOME/ws/workspace1``
gt protect -s s1 -S "$HOME/protect.xml" -w "$HOME/ws/workspace1"
gt protect [-h] [-b] [-f FRACTION] [--inPlace] [-l LANDCLASSES] [-m]
[-o OUTDIR] [-O] [-t TEMPLATE] [-r REGIONS] [-s SCENARIO]
[-S SCENARIOFILE] [-w WORKSPACE]
Named Arguments¶
-b, --backup |
Default: False |
-f, --fraction |
|
--inPlace |
Default: False |
-l, --landClasses | |
| |
-m, --mkdir | Make the output dir if necessary. Default: False |
-o, --outDir |
Default: “.” |
-O, --otherArable | |
Default: False | |
-t, --template |
Default: “prot_{fraction}_{filename}” |
-r, --regions |
|
-s, --scenario |
|
-S, --scenarioFile | |
| |
-w, --workspace | |
|
query¶
Run one or more GCAM database queries by generating and running the named XML queries. The results are placed in a file in the specified output directory with a name composed of the basename of the XML query file plus the scenario name. For example,
gt query -o. -s MyReference,MyPolicyCase liquids-by-region
would run the liquids-by-region
query on two scenarios, MyReference and
MyPolicyCase. Query results will be stored in the files
./liquids-by-region-MyReference.csv
and ./liquids-by-region-MyPolicyCase.csv
.
The named queries are located using the value of config variable GCAM.QueryPath
,
which can be overridden with the -Q
argument. The QueryPath consists of one or
more colon-delimited (on Unix) or semicolon-delimited (on Windows) elements that
can identify directories or XML files. The elements of QueryPath are searched in
order until the named query is found. If a path element is a directory, the filename
composed of the query + ‘.xml’ is sought in that directory. If the path element is
an XML file, a query with a title matching the query name (first literally, then by
replacing '_'
and '-'
characters with spaces) is sought. Note that query names are
case-sensitive.
gt query [-h] [-b BATCHFILE] [-B BATCHOUTPUT] [-d XMLDB] [-D] [-g GROUPDIR]
[-n] [-o OUTPUTDIR] [-p] [-q QUERYXMLFILE] [-Q QUERYPATH]
[-r REGIONS] [-R REGIONMAP] [-s SCENARIO] [-S REWRITESETSFILE]
[-w WORKSPACE]
[queryName [queryName ...]]
Positional Arguments¶
queryName |
|
Named Arguments¶
-b, --batchFile | |
| |
-B, --batchOutput | |
Default: “” | |
-d, --xmldb |
|
-D, --noDelete |
Default: False |
-g, --groupDir |
Default: “” |
-n, --noRun | Show the command to be run, but don’t run it Default: False |
-o, --outputDir | |
Where to output the result (default taken from config parameter “GCAM.OutputDir”) | |
-p, --prequery |
Default: False |
-q, --queryXmlFile | |
| |
-Q, --queryPath | |
| |
-r, --regions |
|
-R, --regionMap | |
| |
-s, --scenario |
Default: “Reference” |
-S, --rewriteSetsFile | |
| |
-w, --workspace | |
Default: “” |
res¶
- Generate an XML file that implements a RES policy on the electricity
- sector as described in the given XML input file.
gt res [-h] [-i INPUTFILE] [-o OUTPUTXML] [-S SCENARIO] [-d] [-u]
Named Arguments¶
-i, --inputFile | |
| |
-o, --outputXML | |
| |
-S, --scenario |
|
-d, --display |
Default: False |
-u, --GCAM-USA | If set, produce output compatible with GCAM-USA regions. Default: False |
run¶
This sub-command reads instructions from the file project.xml, the location of which is taken from the user’s ~/.pygcam.cfg file. The workflow steps indicated in the XML file and command-line determine which commands to run.
Examples:
Run all steps for the default scenario group for project ‘Foo’:
gt +P Foo run
Run all steps for scenario group ‘test’ for project ‘Foo’, but only for scenarios ‘baseline’ and ‘policy-1’:
gt +P Foo run -g test -S baseline,policy1
or, equivalently:
gt +P Foo run --group test --scenario baseline --step policy1
Run only the ‘setup’ and ‘gcam’ steps for scenario ‘baseline’ in the default scenario group:
gt +P Foo run -s setup,gcam -S baseline,policy-1
Same as above, but queue a batch job to run these commands on the queue ‘short’:
gt +b +q short +P Foo run -s setup,gcam -S baseline,policy-1
Note that the command above will run the two scenarios (‘baseline’ and
‘policy-1’) in a single batch job. To run scenarios in separate batch
jobs, use the -D
or --distribute
option to the run sub-commmand:
gt +q short +P Foo run -D -S baseline,policy-1
The “distribute” option knows that various project steps for non-baseline scenarios may depend on baseline scenarios, so the baseline is always run first, with the non-baseline scenarios queued as dependent on the successful completion of the baseline. If no scenarios are explicitly named, all scenarios in the group are run, as usual.
The -n
flag displays the commands that would be executed for a command, but
doesn’t run them:
gt +P Foo run -s setup,gcam -S baseline,policy-1 -n
gt run [-h] [-a] [-D] [-f PROJECTFILE] [-g GROUP] [-G] [-k SKIPSTEPS]
[-K SKIPSCENARIOS] [-l] [-L] [-n] [-q] [-s STEPS] [-S SCENARIOS]
[--vars] [-x SANDBOXDIR]
Named Arguments¶
-a, --allGroups | |
Run all scenarios for all defined groups. Default: False | |
-D, --distribute | |
Default: False | |
-f, --projectFile | |
| |
-g, --group |
|
-G, --listGroups | |
List the scenario groups defined in the project file and exit. Default: False | |
-k, --skipStep |
|
-K, --skipScenario | |
| |
-l, --listSteps | |
Default: False | |
-L, --listScenarios | |
Default: False | |
-n, --noRun | Display the commands that would be run, but don’t run them. Default: False |
-q, --noQuit |
Default: False |
-s, --step |
|
-S, --scenario |
|
--vars | List variables and their values Default: False |
-x, --sandboxDir | |
|
sandbox¶
The sandbox
sub-command allows you to create, delete, show the path of, or run a shell
command in a workspace. If the --scenario
argument is given, the operation is
performed on a scenario-specific workspace within a project directory. If --scenario
is not specified, the operation is performed on the project directory that contains
individual scenario workspaces. Note that the gcam sub-command
automatically creates workspaces as needed.
N.B. You can run sandbox
with the --path
option before performing any
operations to be sure of the directory that will be operated on, or use the
--noExecute
option to show the command that would be executed by --run
.
gt sandbox [-h] [--create] [--delete] [--recreate] [-g NAME] [-n] [-p]
[-r CMD] [-s SCENARIO]
Named Arguments¶
--create |
Default: False |
--delete |
Default: False |
--recreate |
Default: False |
-g, --groupDir | The name of the scenario group subdir Default: “” |
-n, --noExecute | |
Default: False | |
-p, --path | Print the absolute path to the identified sandbox. Default: False |
-r, --run | Run the given command in the identified sandbox. |
-s, --scenario | The scenario for the computed sandbox root. Default: “” |
setup¶
The setup
sub-command automates modification to copies of GCAM’s input XML
files and construction of a corresponding configuration XML file.
See GCAM XML-Setup for a detailed description.
gt setup [-h] [-b BASELINE] [-d] [-f] [-g GROUP] [-G SRCGROUPDIR]
[-m MODULEPATH] [-M MODULESPEC] [-p period-or-year] [-r REFWORKSPACE]
[-R RESULTSDIR] [-s SCENARIO] [-S SUBDIR] [--setupXml SETUPXML] [-T]
[-u] [-x XMLSOURCEDIR] [-X XMLOUTPUTROOT] [-w WORKSPACE] [-y YEARS]
Named Arguments¶
-b, --baseline |
|
-d, --dynamicOnly | |
Generate only dynamic XML for dyn-xml: don’t create static XML. Default: False | |
-f, --forceCreate | |
Re-create the workspace, even if it already exists. Default: False | |
-g, --group | The scenario group to process. Defaults to the group labeled default=”1”. |
-G, --srcGroupDir | |
| |
-m, --modulePath | |
The path to a scenario definition module. See -M flag for more info. | |
-M, --moduleSpec | |
| |
-p, --stop | The number of the GCAM period or the year to stop after |
-r, --refWorkspace | |
A reference workspace to use instead of the value of GCAM.RefWorkspace Default: “” | |
-R, --resultsDir | |
The parent directory holding the GCAM output workspaces | |
-s, --scenario |
|
-S, --subdir | A sub-directory to use instead of scenario name Default: “” |
--setupXml |
|
-T, --staticOnly | |
Generate only static XML for local-xml: don’t create dynamic XML. Default: False | |
-u, --useGroupDir | |
Use the group name as a sub directory below xmlsrc, local-xml, and dyn-xml Default: False | |
-x, --xmlSourceDir | |
The location of the xmlsrc directory. | |
-X, --xmlOutputRoot | |
The root directory into which to generate XML files. | |
-w, --workspace | |
The pathname of the workspace to operate on. | |
-y, --years |
Default: “2015-2100” |
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.