Terminology¶
The following terminology is used throughout the pygcam documentation.
- API or Application Programming Interface
- The public classes, methods, and function provided by the
pygcammodule to facilitate construction of custom scripts, plug-ins, and setup extensions.
- Baseline scenario
- A scenario establishing a starting point from which changes are calculated based on running a policy scenario.
- gcamtool
- The main executable Python script that provides command-line access to
the features of
pygcam. It provides a set of “sub-commands” that perform specific workflow steps and allow you to run the steps defined in a project.
- Plug-in
- Python code that conforms to the pygcam.subcommand protocol, making it accessible by gcamtool. Plug-ins have access to several useful features of gcamtool, such as controlling logging verbosity and the ability to be run in batch-mode on cluster computing systems, and running within the same process as gcamtool.
- Project definition
- Defines one or more scenario groups, the workflow steps, and optional query definitions, and other data that is modified dynamically and stored in temporary files for use by project steps.
- Project file
- An XML file containing one or more project definitions.
If multiple projects are defined in a single project file, they share data,
workflow steps, and variables that are defined in the
<defaults>section. See also: project.xml.
- Query definitions
- A list of XML queries used to extract data from the GCAM database into CSV files. Query definitions can simply be references to queries by name, or they can include references to rewrite sets to cause rewrites to be added to the XML query on-the-fly. See also: queries.xml.
- Rewrite sets
- A set of transformations, defined in XML, to be applied to results of queries run against the GCAM database. These are typically used to aggregate query results into fewer categories. Rewrite sets allow commonly used sets of rewrite commands to be stored separately and assigned a name, allowing them to be referenced by queries defined in the project file or in a separate XML file. See also: rewriteSets.xml.
- Sandbox
- A dynamically generated directory containing all the files and directories (or links to them) required to run GCAM in isolation from other scenarios. See also: sandbox sub-command.
- Scenario
- A single set of input and output files for a specific run of GCAM. Scenarios can be baselines or policy scenarios. Each scenario is run in its own sandbox, allowing multiple scenarios to be run simultaneously, e.g., on a cluster computing system.
- Scenario group
- A set of scenarios consisting of one baseline scenario and one or more policy scenarios. A single project can have multiple scenario groups. The baseline for one scenario group can be used as the starting point for the baseline in another scenario group within the same project.
- Step
- A command defined in a project file to execute a single workflow step. Commands that begin with the “@” character refer to sub-commands within gcamtool. See also: run sub-command.
- Setup extension
- Python code defining a subclass of the XMLEditor class to perform project-specific setup steps, making them accessible from within setup XML files.
- Setup XML
- An XML file providing instructions for how to transform reference GCAM XML files as required to run desired scenarios. See also: scenarios.xml.