Sub-commands for Monte Carlo Simulation¶

The pygcam.mcs sub-package provides additional plug-ins for the GCAM tool (gt) to support defining, running, and analyzing Monte Carlo Simulations (MCS) with GCAM.

The GCAM tool (gt) will automatically load the built-in sub-commands defined in pygcam.mcs if the file $HOME/.use_pygcam_mcs exists. This “sentinel” file allows the pygcam-mcs to be “turned off” to produce shorter help messages when not working with Monte Carlo simulations. Use the gt mcs sub-command to enable, disable, or check the status of MCS mode.

This page describes only the sub-commands provided by pygcam.mcs. See the GCAM tool (gt) documentation for more info.

Note

Quick links to sub-commands: addexp, analyze, cluster, delsim, explore, discrete, gensim, ippsetup, iterate, runsim, moirai

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]
          {batch,building,buildingElec,chart,compare,config,diff,gcam,gui,industry,init,mcs,mi,new,protect,query,res,run,setup,transport,zev}
          ...

Named Arguments¶

+b, --batch

Run the commands by submitting a batch job using the command given by config variable GCAM.BatchCommand. (Linux only)

Default: False

+B, --showBatch

Show the batch command to be run, but don’t run it. (Linux only)

Default: False

+D, --dirmap

A comma-delimited sequence of colon-delimited directory names of the form “/some/host/path:/a/container/path, /host:cont, …”, mapping host dirs to their mount point in a docker container.

+e, --enviroVars

Comma-delimited list of environment variable assignments to pass to queued batch job, e.g., -E “FOO=1,BAR=2”. (Linux only)

+j, --jobName

Specify a name for the queued batch job. Default is “gt”. (Linux only)

Default: “gt”

+l, --logLevel

Sets the log level for modules of the program. A default log level can be set for the entire program, or individual modules can have levels set using the syntax “module:level, module:level,…”, where the level names must be one of {debug,info,warning,error,fatal} (case insensitive).

Default: “INFO”

+L, --logFile

Sets the name of a log file for batch runs. Default is “gt-%j.out” where “%j” (in SLURM) is the jobid. If the argument is not an absolute pathname, it is treated as relative to the value of GCAM.LogDir.

+m, --minutes

Set the number of minutes to allocate for the queued batch job. Overrides config parameter GCAM.Minutes. (Linux only)

Default: 20.0

+M, --mcs

Possible choices: trial, gensim

Used only when running gcamtool from pygcam-mcs.

+P, --projectName

The project name (the config file section to read from), which defaults to the value of config variable GCAM.DefaultProject

Default: “”

+q, --queueName

Specify the name of the queue to which to submit the batch job. Default is given by config variable GCAM.DefaultQueue. (Linux only)

Default: “slurm”

+r, --resources

Specify resources for the queued batch command. Can be a comma-delimited list of assignments of the form NAME=value, e.g., -r ‘pvmem=6GB’. (Linux only)

Default: “”

+s, --set

Assign a value to override a configuration file parameter. For example, to set batch commands to start after a prior job of the same name completes, use –set “GCAM.OtherBatchArgs=-d singleton”. Enclose the argument in quotes if it contains spaces or other characters that would confuse the shell. Use multiple –set flags and arguments to set multiple variables.

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: batch, building, buildingElec, chart, compare, config, diff, gcam, gui, industry, init, mcs, mi, new, protect, query, res, run, setup, transport, zev

Sub-commands:¶

batch¶

Run a set of queries in batch mode and write results to the indicated CSV file.

gt batch [-h] [-c CSVPATH] [-d XMLDB] [-D] [-g GROUPDIR] [-q QUERYNAMES]
         [-Q QUERYPATH] [-s SCENARIO] [-x SANDBOX]

Named Arguments¶

-c, --csvPath

The pathname of the CSV file to which output should be written

-d, --xmldb

The XML database to query (default is computed as {GCAM.SandboxDir}/output/{GCAM.DbFile}. Overrides the -w flag.

-D, --noDelete

Don’t delete any temporary file created by extracting a query from a query file. Used mainly for debugging.

Default: False

-g, --groupDir

The scenario group directory name, if any. Used with to compute default for –workspace argument.

Default: “”

-q, --queryNames

A path-type delimited string holding the names of the queries to run

-Q, --queryPath

A path-type delimited string holding the names of XML query files holding the queries to extract

-s, --scenario

The scenario to run the query for

-x, --sandbox

The sandbox directory in which to find the XML database. Defaults to value of config variable GCAM.SandboxDir. Overridden by the -d flag.

Default: “”

building¶

Dump combinations of building energy use sectors, techs, and fuels.

gt building [-h] [-e] [-o OUTPUTFILE] [-s SECTORS] [-r REGIONS] [-u]
            [-y YEARS]

Named Arguments¶

-e, --electricOnly

Generate a template for electricity-based sources only.

Default: False

-o, --outputFile

The CSV file to create with lists of unique building sectors, subsectors, and technologies. Default is “[GCAM.CsvTemplateDir]/building_tech_template.csv” or “[GCAM.CsvTemplateDir]/building_elec_template.csv”, depending on the –electricOnly flag. Use an absolute path to generate the file to another location.

-s, --sectors

A comma-delimited list of sectors to include in the generated template. Use quotes around the argument if there are embedded blanks. By default, all known building technology sectors are included.

-r, --regions

A comma-delimited list of regions to include in the generated template. By default all regions are included.

-u, --GCAM-USA

If set, produce output compatible with GCAM-USA regions.

Default: False

-y, --years

A hyphen-separated range of timestep years to include in the generated template. Default is “2015-2100”

Default: “2015-2100”

buildingElec¶

Dump combinations of building energy use sectors, techs, and fuels.

gt buildingElec [-h] [-o OUTPUTFILE] [-s SECTORS] [-r REGIONS] [-u] [-y YEARS]

Named Arguments¶

-o, --outputFile

The CSV file to create with lists of unique building sectors, subsectors, and technologies. Default is “[GCAM.CsvTemplateDir]/building_elec_template.csv”. Use an absolute path to generate the file to another location.

Default: “building_elec_template.csv”

-s, --sectors

A comma-delimited list of sectors to include in the generated template. Use quotes around the argument if there are embedded blanks. By default, all known building technology sectors are included.

-r, --regions

A comma-delimited list of regions to include in the generated template. By default all regions are included.

-u, --GCAM-USA

If set, produce output compatible with GCAM-USA regions.

Default: False

-y, --years

A hyphen-separated range of timestep years to include in the generated template. Default is “2015-2100”

Default: “2015-2100”

chart¶

Generate charts from CSV files generated by GCAM batch queries

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

Generate one plot per region. Region names are read from the CSV file, so they reflect any regional aggregation produced by the query.

Default: False

-c, --columns

Specify the column whose values identify the segments in the stacked bar chart. (These appear in the legend.)

Default: “output”

-C, --constraint

Apply a constraint to limit the rows of data to plot. The constraint can be any constraint string that is valid for the DataFrame.query() method, e.g., -C ‘input == “biomass”’

-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

Prefix image filenames with sequential number for easy reference. Used only with –fromFile

Default: False

-f, --fromFile

A file from which to read argument strings, one per line. These are read as if chartGCAM.py were called on each line individually, but avoiding the ~2 sec startup time for the bigger python packages.

-F, --divisorFile

A file containing a floating point value to divide data by before plotting. See also -V.

--format

Specify a format for the Y-axis. Possible values are ‘.’ for float, ‘,’ for int with commas, or any format recognized by print, e.g., “%.2f” to Y values as floats with 2 decimal places.

-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

A column to use as the index column, or blank for None. This column is displayed on the X-axis of stacked barcharts. Default value is “region”.

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

Color for the text label, which defaults to lightgrey. Some users may prefer “black”, for example. (Implies -l)

-m, --multiplier

A value to multiply data by before generating the plot. The argument can be a floating point number or the name of any variable in pygcam.unitConversion.py. For example, “-m 3.667” and “-m C_to_CO2” are equivalent, and effectively convert values from Tg C to Tg CO2. Be sure to adjust the Y axis label. See also -M.

-M, --multiplierFile

A file containing a floating point value to multiply data by before plotting. See also -m.

-n, --ncol

The number of columns with which to display the legend. Default is 5.

Default: 5

-N, --scenario

When using the ‘–fromFile’ option, this argument is used to specify one or more scenario names (delimited by commas if more than one). These are substituted into each line read from the file as the value for “{scenario}” wherever it appears on each line read from the ‘fromFile’.

Default: “”

--negate

Multiply data by -1 before plotting, which can make interpretation of some figures more intuitive. The string “-negated” is added to the file label, displayed if the “-l” or “-L” flag is specified.

Default: False

-o, --outFile

The name of the image file to create. Format is determined from filename extension. All common formats are allowed, e.g., png, pdf, tif, and gif. Try it; it probably works. Default is the name of the data file substituting “.png” for “.csv”

Default: “”

-O, --open

Open the plot file after generating it.

Default: False

-p, --palette

The name of a color palette to use. Some good options include hls, husl, and Paired. See http://stanford.edu/~mwaskom/software/seaborn/tutorial/color_palettes.html

-r, --rotation

Set the rotation angle for X-axis labels. Defaults to 90 degrees (vertical). Use 0 for horizontal labels.

Default: 90

-R, --reference

When using the ‘–fromFile’ option, this argument is used to specify the name of the reference scenario. The “other” scenario is given using the “-N” option. These are substituted into each line read from the file as the value for “{scenario}” and “{reference}” (without the quotes) wherever they appear on each line read from the ‘fromFile’. Defaults to “reference”

Default: “reference”

--region

Plot values only for the given region.

-s, --skiprows

The number of rows of the CSV file to skip before reading the data (starting with a header row with column names.) Default is 1, which works for GCAM batch query output.

Default: 1

-S, --sumYears

Sum across the time horizon, typically by region. This results in a stacked bar plot. When not summed over years (the default) a stacked area plot is generated showing values grouped and summed by indexCol (-I) and presented by year.

Default: False

-t, --yearStep

The spacing of year labels on X-axis for time-series plots. Defaults to 5.

Default: 5

-T, --title

Adds a title to the plot. Default is no title. The string can have LaTeX math language in it, e.g., ‘CO$_2$’ causes the 2 to be subscripted, and ‘MJ$^{-1}$’ results in “MJ” with a superscripted exponent of -1. The string ‘$Delta$’ results in a capital Greek delta. See LaTeX documentation for more options. Be sure to enclose the title in single quotes so the “$” is not (mis)interpreted by the shell.

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

Draw an unstacked bar plot for the column given as an argument to this option, showing three groups of bars: the region, all other regions, and the total.

-U, --unstackedRegion

The region to plot separately from Rest of World in an unstacked plot. Ignored if –byRegion is specified, in which case a plot is created for all regions.

-v, --valueCol

Identify a single column (e.g., a year) to plot for bar plots.

-V, --divisor

A value to divide year column values by before plotting. The argument can be a floating point number or the name of any variable in pygcam.unitConversion.py. See also -F.

-x, --suffix

A suffix to append to the basename of the input csv file to create the name for the output file. For example, if processing my_data.csv, indicating -x ‘-by-region.pdf’ results in an output file named my_data-by-region.pdf.

-X, --xlabel

Defines a label for the X-axis; defaults to blank. LaTeX math language is supported. (See the -T flag for more info.)

Default: “”

-Y, --ylabel

Label for the Y-axis; defaults to “EJ”. LaTeX math language is supported. (See the -T flag for more info.)

Default: “EJ”

-y, --years

Takes a parameter of the form XXXX-YYYY, indicating start and end years of interest. Data for all other years are dropped.

Default: “”

--ymax

Set the scale of a figure by indicating the value to show as the maximum Y value. (By default, scale is set according to the data.)

--ymin

Set the scale of a figure by indicating the value (given as abs(value), but used as -value) to show as the minimum Y value

-z, --zeroLine

Whether to show a line at Y=0

Default: False

--legendY

The Y position of the legend. Useful for fixing poorly formatted figures. Note that to pass a negative value, use the syntax –legendY=”-xxx.xxx”, otherwise the hyphen is interpreted as indicating a command-line argument.

--barWidth

The relative width of bars. Helpful when plotting only 1 or 2 bar, so they aren’t obnoxiously wide. Default is 0.5

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

The directory in which to create the normalized versions of XML input files for comparison. Default is /tmp/xmlCompare

Default: “/tmp/xmlCompare”

config¶

List the values of configuration variables from: ~/.pygcam.cfg configuration file.

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¶

gt diff [-h] [-D WORKINGDIR] [-g GROUP] [-G GROUPSUM] [-i] [-l] [-o OUTFILE]
        [-c] [-p] [-q QUERYFILE] [-r REWRITESETSFILE] [-S] [-s SKIPROWS]
        [-y YEARS] [-Y STARTYEAR]
        csvFiles [csvFiles ...]

Positional Arguments¶

csvFiles: The files to process. For difference operations, the first file is treated as the reference file whose time-series data is subtracted from that of each other file. If missing, “.csv” suffixes are added to all arguments (the “.csv” is optional).

Named Arguments¶

-D, --workingDir

The directory to change to before performing any operations. Defaults to value of config variable GCAM.SandboxDir.

-g, --group

The name of the scenario group to process. If not specified, the group with attribute default=”1” is processed.

-G, --groupSum

Group data for each timestep (or interpolated annual values) by the given column, and sum all members of each group to produce a timeseries for each group. Takes precedence over the simpler “-S” (”–sum”) option.

Default: “”

-i, --interpolate

Interpolate (linearly) annual values between timesteps.

Default: False

-l, --splitLand

Split ‘Landleaf’ or ‘land_allocation’ column to create ‘land_use’ and ‘basin’ columns in output CSV

Default: False

-o, --outFile

The name of the “.csv” or “.xlsx” file containing the differences between each scenario and the reference. Default is “differences.csv”.

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

If the extension is “.xml” (case insensitive), the argument must be an XML file holding a list of queries to run, with optional mappings specified to rewrite output. This file has the same structure as the <queries> element in project.xml. If the file doesn’t end in “.xml”, it must be a text file listing the names of queries to process, one per line. NOTE: When –queryFile is specified, the two positional arguments are required: the names of the baseline and policy scenarios, in that order.

Default: “”

-r, --rewriteSetsFile

An XML file defining query maps by name (default taken from config parameter “GCAM.RewriteSetsFile”)

-S, --sum

Sum all timestep (or interpolated annual values) to produce a single time-series.

Default: False

-s, --skiprows

The number of rows to skip. Default is 1, which works for GCAM batch query output. Use -s0 for outFile.csv

Default: 1

-y, --years

Takes a parameter of the form XXXX-YYYY, indicating start and end years of interest. Other years are dropped (except for annual outputs.)

Default: “”

-Y, --startYear

The year at which to begin interpolation

Default: 0

gcam¶

Run GCAM for the indicated configFile, scenario, or workspace.

gt gcam [-h] [-C CONFIGFILE] [-g GROUP] [-n] [-s SCENARIO] [-x SANDBOX] [-W]
        [-w WORKSPACE] [-f FORCECREATE] [-r REFWORKSPACE] [-S SCENARIOSDIR]

Named Arguments¶

-C, --configFile

Specify the one or more GCAM configuration filenames, separated by commas. If multiple configuration files are given, the are run in succession in the same “job” on the cluster.

-g, --group

The scenario group name, if any.

Default: “”

-n, --noRun

Don’t run GCAM; just print the command that would be run.

Default: False

-s, --scenario

The scenario to run.

Default: “”

-x, --sandbox

Specify the path to the GCAM sandbox to use. If the named workspace doesn’t exist, an exception is raised. If not specified on the command-line, the path constructed as {GCAM.SandboxDir}/{optional-groupdir}/{scenario} is used, if scenario is defined.

-W, --noWrapper

Do not run gcam within a wrapper that detects errors as early as possible and terminates the model run. By default, the wrapper is used.

Default: False

-w, --workspace

The [‘-w’, ‘–workspace’] argument has been deprecated. Use -x / –sandbox instead.

-f, --forceCreate

The [‘-f’, ‘–forceCreate’] argument has been deprecated.

-r, --refWorkspace

The [‘-r’, ‘–refWorkspace’] argument has been deprecated.

-S, --scenariosDir

The [‘-S’, ‘–scenariosDir’] argument has been deprecated.

gui¶

Run the Graphical User Interface generated from the command-line interface.

gt gui [-h] [-d]

Named Arguments¶

-d, --debug

Set the dash (flask) debug flag.

Default: False

industry¶

Dump combinations of industry energy use sectors, techs, and fuels.

gt industry [-h] [-e] [-o OUTPUTFILE] [-s SECTORS] [-r REGIONS] [-u]
            [-y YEARS]

Named Arguments¶

-e, --electricOnly

Generate a template for electricity-based sources only.

Default: False

-o, --outputFile

The CSV file to create with lists of unique industry sectors, subsectors, and technologies. Default is “[GCAM.CsvTemplateDir]/industry_tech_template.csv” or “[GCAM.CsvTemplateDir]/industry_elec_template.csv”, depending on the –electricOnly flag. Use an absolute path to generate the file to another location.

-s, --sectors

A comma-delimited list of sectors to include in the generated template. Use quotes around the argument if there are embedded blanks. By default, all known industry technology sectors are included.

Default: “industrial energy use”

-r, --regions

A comma-delimited list of regions to include in the generated template. By default all regions are included.

-u, --GCAM-USA

If set, produce output compatible with GCAM-USA regions.

Default: False

-y, --years

A hyphen-separated range of timestep years to include in the generated template. Default is “2015-2100”

Default: “2015-2100”

init¶

Initialize key variables in the ~/.pygcam.cfg configuration file. Values not provided on the command-line are requested interactively.

gt init [-h] [-c | -C] [-g GCAMDIR] [--overwrite] [-P DEFAULTPROJECT]
        [-p PROJECTDIR] [-s SANDBOXDIR]

Named Arguments¶

-c, --create-project

Create the project structure for the given default project. If neither -c/–create-project nor -C/–no-create-project is specified, the user is queried interactively.

-C, --no-create-project

Do not create the project structure for the given default project. Mutually exclusive with -c / –create-project option.

-g, --gcamDir

The directory that is a GCAM v5.x or 4.x workspace. Sets config var GCAM.RefWorkspace. By default, looks for gcam-v5.4 (then known older versions) in ~, ~/GCAM, and ~/gcam, ~/Documents/GCAM, and ~/Documents/gcam, where “~” indicates your home directory.

--overwrite

Overwrite an existing config file. (Makes a backup first in ~/.pygcam.cfg~).

Default: False

-P, --defaultProject

Set the value of config var GCAM.DefaultProject to the given value.

-p, --projectDir

The directory in which to create pygcam project directories. Sets config var GCAM.ProjectRoot. Default is “~/GCAM/projects”.

-s, --sandboxDir

The directory in which to create pygcam project directories. Sets config var GCAM.SandboxRoot. Default is “~/GCAM/sandboxes”.

mcs¶

Enable or disable pygcam Monte Carlo Simulation sub-commands.

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¶

Run ModelInterface for the current project.

gt mi [-h] [-d] [-g] [-u] [-q QUERYFILE]

Named Arguments¶

-d, --useDefault

Use the Main_Queries.xml file from the GCAM reference workspace.

Default: False

-g, --glimpse

Use the GLIMPSE-ModelInterface rather than the standard one.

Default: False

-u, --updateProperties

Update the “model_interface.properties” file in the directory indicated by config var file GCAM.QueryDir so it refers to the query file indicated by config var GCAM.MI.QueryFile, or if this does not refer to an existing file, by var GCAM.MI.RefQueryFile.

Default: False

-q, --queryFile

Specify the XML file to read query definitions from.

new¶

Create the structure and files required for a new pygcam project.

gt new [-h] [-c] [--overwrite] [-r PATH] name

Positional Arguments¶

name: Create the structure for the named project, and copy example XML files into the “etc” directory.

Named Arguments¶

-c, --addToConfig

Add a section for the new project to $HOME/.pygcam.cfg after making a backup of the file in $HOME/.pygcam.cfg~

Default: False

--overwrite

If files that are to be copied to the project directory exist, overwrite them. By default, existing files are not overwritten.

Default: False

-r, --projectRoot

The directory in which to create a subdirectory for the named project. Default is the value of config variable GCAM.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.

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

Make a copy of the output file, if it exists (with an added ~ after filename) before writing new output. This option is ignored if a scenario file is specified.

Default: False

-f, --fraction

The fraction of land in the given land classes to protect. (Required, unless a scenario file is specified, in which case this option is ignored.)

--inPlace

Edit the file in place. This must be given explicitly, to avoid overwriting files by mistake.

Default: False

-l, --landClasses

The land class or classes to protect in the given regions. Multiple, comma-delimited land types can be given in a single argument, or the -l flag can be repeated to indicate additional land classes. By default, all unmanaged land classes are protected. Allowed land classes are [‘UnmanagedPasture’, ‘UnmanagedForest’, ‘Shrubland’, ‘Grassland’]. This option is ignored if a scenario file is specified.

-m, --mkdir

Make the output dir if necessary.

Default: False

-o, --outDir

The directory into which to write the modified files. Default is current directory.

Default: “.”

-O, --otherArable

Include OtherArableLand in the list of default land classes to protect. This flag is ignored if the -l (–landClasses) argument is used.

Default: False

-t, --template

Specify a template to use for output filenames. The keywords {fraction}, {filename}, {regions}, and {classes} (with surrounding curly braces) are replaced by the following values and used to form the name of the output files, written to the given output directory. fraction: 100 times the given fraction (i.e., int(fraction * 100)); filename: the name of the input file being processed (e.g., land_input_2.xml or land_input_3.xml); basename: the portion of the input filename prior to the extension (i.e., before ‘.xml’); regions: the given regions, separated by ‘-’, or the word ‘global’ if no regions are specified; classes: the given land classes, separated by ‘-’, or the word ‘unmanaged’ if no land classes are specified. The default pattern is “prot_{fraction}_{filename}”. This option is ignored if a scenario file is specified.

Default: “prot_{fraction}_{filename}”

-r, --regions

The region or regions for which to protect land. Multiple, comma-delimited regions can be given in a single argument, or the -r flag can be repeated to indicate additional regions. By default, all regions are protected. This option is ignored if a scenario file is specified.

-s, --scenario

The name of a land-protection scenario defined in the file given by the –scenarioFile argument or it’s default value.

-S, --scenarioFile

An XML file defining land-protection scenarios. Default is the value of configuration file parameter GCAM.LandProtectionXmlFile.

-w, --workspace

Specify the path to the GCAM workspace to use. The files in {workspace}/input/gcamdata/xml/land_input_{2,3,4,5}*.xml are used as inputs. Default is value of configuration parameter GCAM.RefWorkspace.

query¶

Run one or more GCAM database queries by generating and running the named XML queries.

gt query [-h] [-b BATCHFILE] [-B BATCHOUTPUT] [-d XMLDB] [-D] [-g GROUP] [-n]
         [-o OUTPUTDIR] [-p] [-q QUERYXMLFILE] [-Q QUERYPATH] [-r REGIONS]
         [-R REGIONMAP] [-s SCENARIO] [-S REWRITESETSFILE] [-x SANDBOX]
         [-w WORKSPACE]
         [queryName ...]

Positional Arguments¶

queryName: A file or files, each holding an XML query to run. (The “.xml” suffix will be added if needed.) If an argument is preceded by the “@” sign, it is read and its contents substituted as the values for this argument. That means you can store queries to run in a file (one per line) and just reference the file by preceding the filename argument with “@”.

Named Arguments¶

-b, --batchFile

An XML batch file to run. The file will typically contain multiple queries. By default, output is written to {outputDir}/{batchFile basename}.csv. Use ‘-B’ to change this.

-B, --batchOutput

Where to write the output of the XML batch file given by the ‘-b’ flag. Non-absolute paths are treated as relative to the given outputDir.

Default: “”

-d, --xmldb

The XML database to query (default is computed as {GCAM.SandboxDir}/output/{GCAM.DbFile}. Overrides the -w flag.

-D, --noDelete

Don’t delete any temporary file created by extracting a query from a query file. Used mainly for debugging.

Default: False

-g, --group

The name of a scenario group, if not the default one.

-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.QueryOutputDir”)

-p, --prequery

Generate the XMLDBDriver.properties file and associated batch file to be run by GCAM when GCAM.BatchMultipleQueries or GCAM.InMemoryDatabase are True.

Default: False

-q, --queryXmlFile

An XML file holding a list of queries to run, with optional mappings specified to rewrite output. This file has the same structure as the <queries> element in project.xml.

-Q, --queryPath

A semicolon-delimited list of directories or filenames to look in to find query files. Defaults to value of config parameter GCAM.QueryPath

-r, --regions

A comma-separated list of regions on which to run queries found in query files structured like Main_Queries.xml. If not specified, defaults to querying all 32 regions.

-R, --regionMap

A file containing tab-separated pairs of names, the first being a GCAM region and the second being the name to map this region to. Lines starting with “#” are treated as comments. Lines without a tab character are also ignored. This arg overrides the value of config variable GCAM.RegionMapFile.

-s, --scenario

The scenario to run the query/queries for (default is “Reference”) Note that this must refer to a scenario in the XML database.

Default: “Reference”

-S, --rewriteSetsFile

An XML file defining query maps by name (default taken from config parameter “GCAM.RewriteSetsFile”)

-x, --sandbox

The sandbox directory in which to find the XML database. Defaults to value of config variable GCAM.SandboxDir. Overridden by the -d flag.

Default: “”

-w, --workspace

The [‘-w’, ‘–workspace’] argument has been deprecated. Use -x / –sandbox instead.

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

A CSV or XML file defining the RES policy. Default is the value of configuration file parameter GCAM.RESDescriptionFile. If set to a relative pathname (i.e., not starting with “/”, “", or drive specifier “[a-zA-Z]:”), it is assumed to be relative to %(GCAM.ProjectDir)s/etc/. If a CSV file is given, it is converted to an intermediate RES policy XML file before translation to GCAM-readable input.

-o, --outputXML

The directory into which to write the modified files. Default is the value of configuration file parameter GCAM.RESImplementationXmlFile. If set to a relative pathname, it is assumed to be relative to %(GCAM.SandboxWorkspace)s/local-xml/{scenario}, in which case, the “-s/–scenario” argument is required.

-S, --scenario

The name of the scenario for which to generate the policy implementation XML file. Required if no argument is given to the “-o/–outputXML” flag, or if the argument is a relative pathname.

-d, --display

If set, the result of the RES policy is displayed in tabular format, and the program exits.

Default: False

-u, --GCAM-USA

If set, produce output compatible with GCAM-USA regions.

Default: False

run¶

Run the steps for a project defined in a project.xml file

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

Run the given scenarios by queueing them independently. If one of the scenarios is a baseline, it is queued first and the remaining scenarios are queued as dependent on the completion of the baseline job.

Default: False

-f, --projectFile

The XML file describing the project. If set, command-line argument takes precedence. Otherwise, value is taken from config file variable GCAM.ProjectFile, if defined, otherwise the default is ‘./project.xml’.

-g, --group

The name of the scenario group to process. If not specified, the group with attribute default=”1” is processed.

-G, --listGroups

List the scenario groups defined in the project file and exit.

Default: False

-k, --skipStep

Steps to skip. These must be names of steps defined in the project.xml file. Multiple steps can be given in a single (comma-delimited) argument, or the -k flag can be repeated to indicate additional steps. By default, all steps are run.

-K, --skipScenario

Scenarios to skip. Multiple scenarios can be given in a single (comma-delimited) argument, or the -K flag can be repeated to indicate additional scenarios. By default, all scenarios are run.

-l, --listSteps

List the steps defined for the given project and exit. Dynamic variables (created at run-time) are not displayed.

Default: False

-L, --listScenarios

List the scenarios defined for the given project and exit. Dynamic variables (created at run-time) are not displayed.

Default: False

-n, --noRun

Display the commands that would be run, but don’t run them.

Default: False

-q, --noQuit

Don’t quit if an error occurs when processing a scenario, just move on to processing the next scenario, if any.

Default: False

-s, --step

The steps to run. These must be names of steps defined in the project.xml file. Multiple steps can be given in a single (comma-delimited) argument, or the -s flag can be repeated to indicate additional steps. By default, all steps are run.

-S, --scenario

Which of the scenarios defined for the given project should be run. Multiple scenarios can be given in a single (comma-delimited) argument, or the -S flag can be repeated to indicate additional scenarios. By default, all active scenarios are run.

--vars

List variables and their values

Default: False

-x, --sandboxDir

The directory in which to create the run-time sandbox workspace. Defaults to value of {GCAM.SandboxProjectDir}/{scenarioGroup}.

setup¶

Setup a scenario by creating modified XML input files.

gt setup [-h] [--create-sandbox | --no-create-sandbox] [-d] [-f] [-g GROUP]
         [-m MODULEPATH | -M MODULESPEC] [-p STOPYEAR] [-R RESULTSDIR]
         [--run-scenario-setup | --no-run-scenario-setup] -s SCENARIO
         [--run-config-setup | --no-run-config-setup]
         [--run-non-config-setup | --no-run-non-config-setup] [-T] [-y YEARS]
         [-b BASELINE] [-G SRCGROUPDIR] [-r REFWORKSPACE] [-S SUBDIR]
         [--setupXml SETUPXML] [--stopPeriod STOPPERIOD] [-u USEGROUPDIR]
         [-w SANDBOX] [-x XMLSOURCEDIR] [-X XMLOUTPUTROOT]

Named Arguments¶

--create-sandbox, --no-create-sandbox

Whether to create the run-time sandbox directory from the reference workspace.: Default is to create sandbox. (default: True)

Default: True

-d, --dynamic-only

Generate only dynamic XML for dyn-xml: don’t create static XML.

Default: False

-f, --force-create

Re-create the sandbox, even if it already exists. Implies –createSandbox.

Default: False

-g, --group

The scenario group to process. Defaults to the group labeled default=”1”.

-m, --modulePath

The path to a scenario definition module. See -M/–moduleSpec flag for more info.

-M, --moduleSpec

The “dot spec” for the Python module holding the setup classes and a function called ‘scenarioMapper’ or a dictionary called ‘ClassMap’ which map scenario names to classes. If the function ‘scenarioMapper’ exists, it is used. If not, the ‘ClassMap’ is used. Default is “{xmlsrc}/subdir/scenarios.py” (if subdir is defined) or “{xmlsrc}/scenarios.py” (if subdir is undefined) under the current ProjectRoot.

-p, --stopYear

The year after which to stop running GCAM

-R, --resultsDir

The parent directory holding the GCAM output workspaces

--run-scenario-setup, --no-run-scenario-setup

Whether to run the commands in scenarios.xml for the current scenario. Default is to run scenario setup. (default: True)

Default: True

-s, --scenario

Identify the scenario to run.

--run-config-setup, --no-run-config-setup

Whether to run only scenario setup steps that add/insert/delete/replace elements in the <ScenarioComponents> section of the GCAM config XML file. Default is to run config setup. (default: True)

Default: True

--run-non-config-setup, --no-run-non-config-setup

Whether to run only scenario setup steps that do not add/insert/delete/replace elements in the <ScenarioComponents> section of the GCAM config XML file. (That is, commands that operate on other XML input files.) Default is “yes”. (default: True)

Default: True

-T, --static-only

Generate only static XML for local-xml: don’t create dynamic XML.

Default: False

-y, --years

Years to generate constraints for. Must be of the form XXXX-YYYY. Default is “2015-2100”

Default: “2015-2100”

-b, --baseline

The [‘-b’, ‘–baseline’] argument has been deprecated.

-G, --srcGroupDir

The [‘-G’, ‘–srcGroupDir’] argument has been deprecated.

-r, --refWorkspace

The [‘-r’, ‘–refWorkspace’] argument has been deprecated.

-S, --subdir

The [‘-S’, ‘–subdir’] argument has been deprecated.

--setupXml

The [’–setupXml’] argument has been deprecated.

--stopPeriod

The [’–stopPeriod’] argument has been deprecated. Use –stopYear instead.

-u, --useGroupDir

The [‘-u’, ‘–useGroupDir’] argument has been deprecated.

-w, --sandbox

The [‘-w’, ‘–sandbox’] argument has been deprecated.

-x, --xmlSourceDir

The [‘-x’, ‘–xmlSourceDir’] argument has been deprecated.

-X, --xmlOutputRoot

The [‘-X’, ‘–xmlOutputRoot’] argument has been deprecated.

transport¶

Write combinations of transport sectors, techs, and fuels to a template CSV file.

gt transport [-h] [-o OUTPUTFILE] [-p PREFIXES] [-s SECTORS] [-r REGIONS]
             [-y YEARS]

Named Arguments¶

-o, --outputFile

The CSV template file to create with transport sectors, subsectors, and technologies. Default is “[GCAM.CsvTemplateDir]/transport_tech_template.csv” Use an absolute path to generate the file to another location.

Default: “transport_tech_template.csv”

-p, --prefixes

A comma-delimited list of sector prefixes indicating which sectors to include in the generated template. Use quotes around the argument if there are embedded blanks.

-s, --sectors

A comma-delimited list of sectors to include in the generated template. Use quotes around the argument if there are embedded blanks. By default, all known transport technology sectors are included.

-r, --regions

A comma-delimited list of regions to include in the generated template. By default all regions are included.

-y, --years

A hyphen-separated range of timestep years to include in the generated template. Default is “2015-2100”

Default: “2015-2100”

zev¶

Generate an CSV template file that can be used to implement a ZEV policy on the sectors, transSubsectors and technologies as described on the command-line.

gt zev [-h] [-i INCLUDE] [-o OUTPUTCSV] [-r REGIONS] [-S SCENARIO] [-t TAG]
       [-u] [-y YEARS]

Named Arguments¶

-i, --include

A colon (“:”) delimited list of comma-delimited sectors, tranSubsectors, and technologies to include in the CSV template file. Example: “–include trn_pass_road_LDV_4W::BEV,FCEV” means include only two technologies (BEV,FCEV), but for any tranSubsector under the specified sector. Multiple -I arguments are allowed.

-o, --outputCSV

The directory into which to write the generated CSV template. Default is “zev_policy.csv”. If set to a relative pathname, it is assumed to be relative to %(GCAM.ProjectDir)s/etc.

Default: “zev_policy.csv”

-r, --regions

A comma-delimited list of regions to include in the generated template. By default all regions are included.

-S, --scenario

The name of the scenario for which to generate the policy implementation XML file. Required if no argument is given to the “-o/–outputXML” flag, or if the argument is a relative pathname.

-t, --tag

The config file tag identifying the transportation file to operate on.

Default: “transportation”

-u, --GCAM-USA

If set, produce output compatible with GCAM-USA regions.

Default: False

-y, --years

A hyphen-separated range of timestep years to include in the generated template. Default is “2015-2100”

Default: “2015-2100”