pygcam.xmlEditor

This module defines common variables, functions, and classes for manipulating XML files to setup GCAM modeling experiments. An introduction to the XML-Setup system is available on the GCAM XML-Setup page; command-line features are documented with the setup sub-command.

The basic approach is to create a directory for each defined scenario, in which modified files and a corresponding configuration XML file are stored.

To allow functions to be called in any order or combination, each checks for a local copy of the file to be edited, and if not present, copies the original file to the local directory. Local copies are modified in place. Each function updates the local config file so that it loads the modified file.

API

class pygcam.xmlEditor.XMLEditor(baseline, scenario, xmlOutputRoot, xmlSourceDir, refWorkspace, groupDir, srcGroupDir, subdir, parent=None, mcsMode=None, cleanXML=True)

Base class for scenario setup. Custom scenario processing classes must subclass this. Represents the information required to setup a scenario, i.e., to generate and/or copy the required XML files into the XML output dir.

absPath(relPath)

Convert relPath to an absolute path by treating it as relative to the current scenario’s “exe” directory.

Parameters:relPath – (str) a path relative to the current “exe” directory
Returns:(str) the absolute path corresponding to relPath.
add(tag, xpath, value)

Run the xpath query on the XML file with tag in the config file, and replace all values found with the result of adding value to them.

Parameters:
  • tag – (str) the tag identifying a scenario component
  • xpath – (str) an XPath query to run against the file indicated by tag
  • value – (float) a value to add to the results of the xpath query.
Returns:

none
addMarketConstraint(target, policy, dynamic=False, baselinePolicy=False)

Adds references to a pair of files comprising a policy, i.e., a policy definition file and a constraint file. References to the two files–assumed to be named XXX-{subsidy,tax}.xml and XXX-{subsidy,tax}-constraint.xml for policy target XXX–are added to the configuration file. Callable from XML setup files.

Parameters:
  • target – (str) the subject of the policy, e.g., corn-etoh, cell-etoh, ft-biofuel, biodiesel
  • policy – (str) one of subsidy or tax
  • dynamic – (str) True if the XML file was dynamically generated, and thus found in dyn-xml rather than local-xml
  • baselinePolicy – (bool) if True, the policy file is linked to the baseline directory rather than this scenario’s own directory.
Returns:

none
addScenarioComponent(name, xmlfile)

Add a new <ScenarioComponent> to the configuration file, at the end of the list of components.

Parameters:
  • name – (str) the name to assign to the new scenario component
  • xmlfile – (str) the location of the XML file, relative to the exe directory
Returns:

none
buildingElectrification(csvFile, xmlTag='building_electrification', xmlFile='building_electrification.xml')

Generate a building electrification policy XML file and incorporate it into the scenario’s config.xml.

Parameters:
  • csvFile – (str) the name of the CSV template file to read. Relative paths are assumed relative to {GCAM.ProjectDir}/etc. Absolute paths override this.
  • xmlTag – (str) a config file tag to use for the generated XML file.
  • xmlFile – (str) the name of the generated XML file.
Returns:
buildingTechEfficiency(csvFile, xmlTag='building_update', xmlFile='building_tech_improvements.xml', mode='mult')

Generate an XML file that implements building technology efficiency policies based on the CSV input file.

Parameters:
  • csvFile – (str) The name of the file to read. The given argument is interpreted as relative to “{GCAM.ProjectDir}/etc/”, but an absolute path can be provided to override this.
  • xmlTag – (str) the tag in the config.xml file to use to find the relevant GCAM input XML file.
  • xmlFile – (str) the name of the XML policy file to generate. The file is written to the “local-xml” dir for the current scenario, and it is added to the config.xml file.
  • mode – (str) Must be “mult” (the default) or “add”, controlling how CSV data are processed.
Returns:

none
cfgPath()

Compute the name of the GCAM config file for the current scenario.

Returns:(str) the pathname to the XML configuration file.
delMarketConstraint(target, policy)

Delete the two elements defining a market constraint from the configuration file. The filenames are constructed as indicated in the addMarketConstraint method. Callable from XML setup files.

Parameters:
  • target – (str) the subject of the policy, e.g., corn-etoh, cell-etoh, ft-biofuel, biodiesel
  • policy – (str) one of subsidy or tax
Returns:

none
deleteScenarioComponent(name, useCache=True)

Delete a <ScenarioComponent> identified by the <Value> element name.

Parameters:name – (str) the name of the ScenarioComponent to delete
Returns:none
freezeRegionPopulation(region, year, endYear=2100)

Freeze population subsequent to year at the value for that year.

getLocalCopy(configTag)

Get the filename for the most local version (in terms of scenario hierarchy) of the XML file identified in the configuration file with configTag, and copy the file to our scenario dir if not already there.

Parameters:configTag – (str) the configuration file tag (name=”xxx”) of an XML file
Returns:(str, str) a tuple of the relative and absolute path of the local (i.e., within the current scenario) copy of the file.
industryTechEfficiency(csvFile, xmlTag='industry_update', xmlFile='industry_tech_improvements.xml', mode='mult')

Generate an XML file that implements industry technology efficiency policies based on the CSV input file.

Parameters:
  • csvFile – (str) The name of the file to read. The given argument is interpreted as relative to “{GCAM.ProjectDir}/etc/”, but an absolute path can be provided to override this.
  • xmlTag – (str) the tag in the config.xml file to use to find the relevant GCAM input XML file.
  • xmlFile – (str) the name of the XML policy file to generate. The file is written to the “local-xml” dir for the current scenario, and it is added to the config.xml file.
  • mode – (str) Must be “mult” (the default) or “add”, controlling how CSV data are processed.
Returns:

none
insertScenarioComponent(name, xmlfile, after)

Insert a <ScenarioComponent> to the configuration file, following the entry named by after.

Parameters:
  • name – (str) the name to assign to the new scenario component
  • xmlfile – (str) the location of the XML file, relative to the exe directory
  • after – (str) the name of the element after which to insert the new component
Returns:

none
insertStubTechParameter(regions, supplysector, subsector, stubTechnology, nodeName, attributeName, attributeValue, nodeValues, supplysectorTag='supplysector', subsectorTag='subsector', technologyTag='stub-technology', configFileTag='energy_transformation')

Insert a parameter for a given region/supplysector/subsector/stub-technology/period. Callable from XML setup files.

Parameters:
  • regions – (str or None) If a string, the GCAM region(s) to operate on. If None, the function is applied to all regions. Arg can be comma-delimited list of regions.
  • supplysector – (str) the name of a supply sector
  • supplysectorTag – (str) the tag for the supplysector level. Default is ‘supplysector’, but for electricity, this should be passed as supplysectorTag=’pass-through-sector’
  • subsectorTag – (str) the tag for the subsector level. Default is ‘subsector’, but for transportation, this should be passed as subsectorTag=’tranSubsector’
  • subsector – (str) the name of a sub-sector
  • stubTechnology – (str) the name of a technology to apply function to; if absent, the function is applied at the subsector level (optional)
  • technologyTag – (str) the tag for the technology level. Default is ‘stub-technology’, but for certain sectors it may be ‘technology’
  • nodeName – (str) defines the name of the node to insert.
  • attributeName – (str) defines any attributes that need to be added (e.g. @name) (optional)
  • attributeValue – (str) defines any attributevalues that need to be added (e.g. name=”coal”) (optional)
  • nodeValues – (dict-like or iterable of tuples of (year, nodeValue)) year can be a single year (as string or int), or a string specifying a range of years, of the form “xxxx-yyyy”, which implies 5 year timestep, or “xxxx-yyyy:s”, which provides an alternative timestep. If values is dict-like (e.g. a pandas Series) a list of tuples is created by calling values.items() after which the rest of the explanation above applies. The nodeValue can be anything coercible to float.
  • configFileTag – (str) the ‘name’ of a <File> element in the <ScenarioComponents> section of a config file. This determines which file is edited, so it must correspond to the indicated sector(s). Default is ‘energy_transformation’.
Returns:

none
insertStubTechRetirement(regions, supplysector, subsector, stubTechnologies, type, steepness, years, supplysectorTag='supplysector', subsectorTag='subsector', technologyTag='stub-technology', halflife=0, configFileTag='energy_transformation')

Insert a parameter for a given region/supplysector/subsector/stub-technology/period. Callable from XML setup files.

Parameters:
  • regions – (str or None) If a string, the GCAM region(s) to operate on. If None, the function is applied to all regions. Arg can be comma-delimited list of regions.
  • supplysector – (str) the name of a supply sector
  • supplysectorTag – (str) the tag for the supplysector level. Default is ‘supplysector’, but for electricity, this should be passed as supplysectorTag=’pass-through-sector’
  • subsectorTag – (str) the tag for the subsector level. Default is ‘subsector’, but for transportation, this should be passed as subsectorTag=’tranSubsector’
  • subsector – (str) the name of a sub-sector
  • stubTechnologies – (str) the name of a technology to apply function to; if absent, the function is applied at the subsector level (optional)
  • technologyTag – (str) the tag for the technology level. Default is ‘stub-technology’, but for certain sectors it may be ‘technology’
  • type – (str) defines the type of shutdown function. Can be either ‘profit’ or ‘s-curve’
  • steepness – (float) defines the steepness value used in the function
  • years – (string or int) the years to which to apply to the shutdown function
  • halflife – (int or None) defines the halflife value to use. By default set to None, but s-curve shutdown deciders need a halflife value
  • configFileTag – (str) the ‘name’ of a <File> element in the <ScenarioComponents> section of a config file. This determines which file is edited, so it must correspond to the indicated sector(s). Default is ‘energy_transformation’.
Returns:

none
insertSubsectorParameter(regions, supplysector, subsector, nodeName, attributeName, attributeValue, nodeValue, supplysectorTag='supplysector', subsectorTag='subsector', configFileTag='energy_transformation')

Insert a parameter for a given region/supplysector/subsector/stub-technology/period. Callable from XML setup files.

Parameters:
  • regions – (str or None) If a string, the GCAM region(s) to operate on. If None, the function is applied to all regions. Arg can be comma-delimited list of regions.
  • supplysector – (str) the name of a supply sector
  • supplysectorTag – (str) the tag for the supplysector level. Default is ‘supplysector’, but for electricity, this should be passed as supplysectorTag=’pass-through-sector’
  • subsectorTag – (str) the tag for the subsector level. Default is ‘subsector’, but for transportation, this should be passed as subsectorTag=’tranSubsector’
  • subsector – (str) the name of a sub-sector
  • nodeName – (str) defines the name of the node to insert.
  • attributeName – (str) defines any attributes that need to be added (e.g. @name) (optional)
  • attributeValue – (str) defines any attribute values that need to be added (e.g. name=”coal”) (optional)
  • nodeValue – (string or float) values to insert into the node
  • configFileTag – (str) the ‘name’ of a <File> element in the <ScenarioComponents> section of a config file. This determines which file is edited, so it must correspond to the indicated sector(s). Default is ‘energy_transformation’.
Returns:

none
makeScenarioComponentsUnique()

Give all reference ScenarioComponents a unique “name” tag to facilitate manipulation via XPath queries. This is a no-op in GCAM version >= 4.3.

Returns:none
multiply(tag, xpath, value)

Run the xpath query on the XML file with tag in the config file, and replace all values found with the result of multiplying them by value.

Parameters:
  • tag – (str) the tag identifying a scenario component
  • xpath – (str) an XPath query to run against the file indicated by tag
  • value – (float) a value to multiply results of the xpath query by.
Returns:

none
protectLand(fraction, landClasses=None, otherArable=False, regions=None, unprotectFirst=False)

Modify land_input files to protect a constant fraction of unmanaged land of the given classes, in the given regions. Callable from XML setup files.

Parameters:
  • fraction – (float) the fraction of land in the given land classes to protect
  • landClasses – a string or a list of strings, or None. If None, all “standard” unmanaged land classes are modified.
  • otherArable – (bool) if True, land class ‘OtherArableLand’ is included in default land classes.
  • regions – a string or a list of strings, or None. If None, all regions are modified.
protectionScenario(scenarioName, unprotectFirst=True)

Implement the protection scenario scenarioName, defined in the file given by config variable GCAM.LandProtectionXmlFile. Callable from XML setup files.

Parameters:
  • scenarioName – (str) the name of a scenario defined in the land protection XML file.
  • unprotectFirst – (bool) if True, make all land “unprotected” before protecting.
Returns:

none
renameScenarioComponent(name, xmlfile)

Modify the name of a ScenarioComponent, located by the XML file path it holds. This is used in to create a local reference XML that has unique names for all scenario components, which allows all further modifications to refer only to the (now unique) names.

Parameters:
  • name – (str) the new name for the scenario component
  • xmlfile – (str) the XML file path used to locate the scenario component
Returns:

none
replaceValue(tag, xpath, value)

Replace the value indicated by xpath with value in the file identified with the config file name tag.

Parameters:
  • tag – (str) the name of a config file element
  • xpath – (str) an XPath query string
  • value – the value to use in place of that found by the xpath. (the value is converted to string, so you can pass ints or floats.)
setClimateOutputInterval(years)

Sets the the frequency at which climate-related outputs are saved to the XML database to the given number of years, e.g., <Value name="climateOutputInterval">1</Value>. Callable from XML setup files.

Parameters:years – (coercible to int) the number of years to set as the climate (GHG) output interval
Returns:none
setConfigValue(section, name, value)

Set the value of the item with name in section to the given value. Numeric values are converted to strings automatically.

Parameters:
  • section – (str) the name of a section in the configuration.xml file, e.g., “Strings”, “Bools”, “Ints”, etc.
  • name – (str) the name of the attribute on the element to change
  • value – the new value to set for the identified element
Returns:

none
setEnergyTechnologyCoefficients(subsector, technology, energyInput, values)

Set the coefficients in the global technology database for the given energy input of the given technology in the given subsector. Callable from XML setup files.

Parameters:
  • subsector – (str) the name of the subsector
  • technology – (str) The name of the technology, e.g., ‘cellulosic ethanol’, ‘FT biofuel’, etc.
  • energyInput – (str) the name of the minicam-energy-input
  • values – A sequence of tuples or object with items method returning (year, coefficient). For example, to set the coefficients for cellulosic ethanol for years 2020 and 2025 to 1.234, the pairs would be ((2020, 1.234), (2025, 1.234)).
Returns:

none
setGlobalTechNonEnergyCost(sector, subsector, technology, values)

Set the non-energy cost of for technology in the global-technology-database, given a list of values of (year, price). The price is applied to all years indicated by the range. Callable from XML setup files.

Parameters:
  • sector – (str) the name of a GCAM sector
  • subsector – (str) the name of a GCAM subsector within sector
  • technology – (str) the name of a GCAM technology in subsector
  • values – (dict-like or iterable of tuples of (year, price)) year can be a single year (as string or int), or a string specifying a range of years, of the form “xxxx-yyyy”, which implies 5 year timestep, or “xxxx-yyyy:s”, which provides an alternative timestep. If values is dict-like (e.g. a pandas Series) a list of tuples is created by calling values.items() after which the rest of the explanation above applies. The price can be anything coercible to float.
Returns:

none
setGlobalTechShareWeight(sector, subsector, technology, values, configFileTag='energy_transformation')

Create a modified version of en_transformation.xml with the given share-weights for technology in sector based on the data in values. Callable from XML setup files.

Parameters:
  • sector – (str) the name of a GCAM sector
  • technology – (str) the name of a GCAM technology in sector
  • values – (dict-like or iterable of tuples of (year, shareWeight)) year can be a single year (as string or int), or a string specifying a range of years, of the form “xxxx-yyyy”, which implies 5 year timestep, or “xxxx-yyyy:s”, which provides an alternative timestep. If values is dict-like (e.g. a pandas Series) a list of tuples is created by calling values.items() after which the rest of the explanation above applies. The shareWeight can be anything coercible to float.
  • xmlBasename – (str) the name of an xml file in the energy-xml folder to edit.
  • configFileTag – (str) the ‘name’ of a <File> element in the <ScenarioComponents> section of a config file. This must match xmlBasename.
Returns:

none
setGlobalTechShutdownRate(sector, subsector, technology, values)

Create a modified version of en_transformation.xml with the given shutdown rates for technology in sector based on the data in values. Callable from XML setup files.

Parameters:
  • sector – (str) the name of a GCAM sector
  • subsector – (str) the name of a GCAM subsector within sector
  • technology – (str) the name of a GCAM technology in subsector
  • values – (dict-like or iterable of tuples of (year, shutdownRate)) year can be a single year (as string or int), or a string specifying a range of years, of the form “xxxx-yyyy”, which implies 5 year timestep, or “xxxx-yyyy:s”, which provides an alternative timestep. If values is dict-like (e.g. a pandas Series) a list of tuples is created by calling values.items() after which the rest of the explanation above applies. The shutdownRate can be anything coercible to float.
Returns:

none
setInterpolationFunction(regions, supplysector, subsector, fromYear, toYear, funcName='linear', applyTo='share-weight', fromValue=None, toValue=None, stubTechnology=None, supplysectorTag='supplysector', subsectorTag='subsector', technologyTag='stub-technology', configFileTag='energy_transformation', delete=False)

Set the interpolation function for the share-weight of the subsector of supplysector (and optional technology) to funcName between years fromYear to toYear in region. Callable from XML setup files.

Parameters:
  • regions(s) – (str or None) If a string, the GCAM region(s) to operate on. Value can be a single region or a comma-delimited list of regions. If None, the function is applied to all regions found in the XML file.
  • supplysector – (str) the name of a supply sector
  • supplysectorTag – (str) the tag for the supplysector level. Default is ‘supplysector’, but for electricity, this should be passed as supplysectorTag=’pass-through-sector’
  • subsectorTag – (str) the tag for the subsector level. Default is ‘subsector’, but for transportation, this should be passed as subsectorTag=’tranSubsector’
  • subsector – (str) the name of a sub-sector
  • fromYear – (str or int) the year to start interpolating
  • toYear – (str or int) the year to stop interpolating
  • funcName – (str) the name of an interpolation function
  • applyTo – (str) what the interpolation function is applied to
  • fromValue – (str or number) the value to set in the <from-value> element (optional)
  • toValue – (str or number) the value to set in the <to-value> element (required for all but “fixed” interpolation function.)
  • stubTechnology – (str) the name of a technology to apply function to; if absent, the function is applied at the subsector level.
  • technologyTag – (str) the tag for the technology level. Default is ‘stub-technology’, but for certain sectors it may be ‘technology’
  • configFileTag – (str) the ‘name’ of a <File> element in the <ScenarioComponents> section of a config file. This determines which file is edited, so it must correspond to the indicated sector(s). Default is ‘energy_transformation’.
  • delete – (bool) if True, set delete=”1”, otherwise don’t.
Returns:

none
setPriceElasticity(regions, sectors, configFileTag, values)

Modify price-elasticity values for the given regions and sectors in sector based on the data in values. Callable from XML setup files.

Parameters:
  • regions – (str or list of str) the name(s) of a GCAM region or regions, or “global” to indicate that price elasticity should be set in all regions. (Or more precisely, the change should not be restricted by region.)
  • sector – (str or list of str) the name of a GCAM (demand) sector. In GCAM v4.3, this should be one of {“cement”, “industry”, “trn_aviation_intl”, “trn_freight”, “trn_pass”, “trn_shipping_intl”, “Exports_Meat”, “FoodDemand_Crops”, “FoodDemand_Meat”, “NonFoodDemand_Crops”, “NonFoodDemand_Forest”, “NonFoodDemand_Meat”}, however if input files have been customized, other values can be used.
  • configFileTag – (str) the ‘name’ of a <File> element in the <ScenarioComponents> section of a config file. This determines which file is edited, so it must correspond to the indicated sector(s).
  • values – (dict-like or iterable of tuples of (year, elasticity)) year can be a single year (as string or int), or a string specifying a range of years, of the form “xxxx-yyyy”, which implies 5 year timestep, or “xxxx-yyyy:s”, which provides an alternative timestep. If values is dict-like (e.g. a pandas Series) a list of tuples is created by calling values.items() after which the rest of the explanation above applies. The elasticity can be anything coercible to float.
Returns:

none
setRegionPopulation(region, values)

Set the population for the given region to the values for the given years. Callable from XML setup files.

Parameters:
  • region – (str) the name of one of GCAM’s regions.
  • values – (dict-like or iterable of tuples of (year, pop)), specifying the population to set for each year given.
Returns:

none
setRegionalNonCO2Emissions(region, sector, subsector, stubTechnology, species, values, configFileTag='nonco2_energy')

Create a modified version of all_energy_emissions.xml with the given values for for technology in sector based on the data in values. Callable from XML setup files.

Parameters:
  • sector – (str) the name of a GCAM sector
  • stubTechnology – (str) the name of a GCAM stub-technology in sector
  • values – (dict-like or iterable of tuples of (year, shareWeight)) year can be a single year (as string or int), or a string specifying a range of years, of the form “xxxx-yyyy”, which implies 5 year timestep, or “xxxx-yyyy:s”, which provides an alternative timestep. If values is dict-like (e.g. a pandas Series) a list of tuples is created by calling values.items() after which the rest of the explanation above applies. The shareWeight can be anything coercible to float.
  • species – (str) the name of the gas to set the emissions for
  • configFileTag – (str) the ‘name’ of a <File> element in the <ScenarioComponents> section of a config file. Default is “nonco2_energy” => all_energy_emissions.xml
Returns:

none
setRegionalShareWeights(regions, sector, subsector, values, stubTechnology=None, supplysectorTag='supplysector', subsectorTag='subsector', technologyTag='stub-technology', configFileTag='energy_transformation')

Create a modified version of the indicated file (default is en_transformation.xml) with the given share-weights for technology in sector based on the data in values. Note that this function affects regional technology definitions only. To affect definitions in the global technology database, use the function setGlobalTechShareWeight (below). Callable from XML setup files.

Parameters:
  • regions – if not None, changes are made in a specific region, or regions (a comma-delimited list of regions) otherwise (if None) they’re made in all global GCAM regions.
  • sector – (str) the name of a GCAM sector
  • subsector – (str) the name of a GCAM subsector
  • values – (dict-like or iterable of tuples of (year, shareWeight)) year can be a single year (as string or int), or a string specifying a range of years, of the form “xxxx-yyyy”, which implies 5 year timestep, or “xxxx-yyyy:s”, which provides an alternative timestep. If values is dict-like (e.g. a pandas Series) a list of tuples is created by calling values.items() after which the rest of the explanation above applies. The shareWeight can be anything coercible to float.
  • stubTechnology – (str) the name of a GCAM technology in the global technology database
  • technologyTag – (str) the tag for the technology level. Default is ‘stub-technology’, but for certain sectors it may be ‘technology’
  • supplysectorTag – (str) the tag for the supplysector level. Default is ‘supplysector’, but for electricity, this should be passed as supplysectorTag=’pass-through-sector’
  • subsectorTag – (str) the tag for the subsector level. Default is ‘subsector’, but for transportation, this should be passed as subsectorTag=’tranSubsector’
  • configFileTag – (str) the ‘name’ of a <File> element in the <ScenarioComponents> section of a config file.
Returns:

none
setStopPeriod(yearOrPeriod)

Sets the model stop period. If stopPeriod is <= 22, the stop period is set to the given value. If the value > 2000, the value is treated as a year and converted to the correct stop period for the configuration file. Callable from XML setup files.

Parameters:yearOrPeriod – (coercible to int) this argument is treated as a literal stop period if the value is < 1000. (N.B. 2015 = step 4, 2020 = step 5, and so on.) If yearOrPeriod >= 1000, it is treated as a year and converted to a stopPeriod for use in the GCAM configuration file.
Returns:none
Raises:SetupException
setup(args)

Calls setupStatic and/or setupDynamic, depending on flags set in args.

Parameters:args – (argparse.Namespace) arguments passed from the top-level call to setup
Returns:none
setupDynamic(args)

Create dynamic XML files in dyn-xml. These files are generated for policy scenarios when XML file contents must be computed from baseline results.

Parameters:args – (argparse.Namespace) arguments passed from the top-level call to setup sub-command
Returns:none
setupSolver(solutionTolerance=None, broydenTolerance=None, maxModelCalcs=None, maxIterations=None, year=2020)

Set the model solution tolerance to the given values for the solver “driver” (solutionTolerance) and, optionally for the Broyden component (broydenTolerance). Callable from XML setup files.

Parameters:
  • solutionTolerance – (coercible to float, > 0.0) the value to set for the driver tolerance
  • broydenTolerance – (coercible to float, > 0.0) the value to set for the Broyden component tolerance. (If both are provided, the function requires that componentTolerance <= driverTolerance.)
  • maxModelCalcs – (coercible to int, > 0) maximum number of calculations to run in the driver
  • maxIterations – (coercible to int, > 0) maximum number of iterations to allow in the Broyden component
Returns:

none
setupStatic(args)

Create static XML files in local-xml. By “static”, we mean files whose contents are independent of baseline results. In comparison, policy scenarios may generate dynamic XML files whose contents are computed from baseline results.

Parameters:args – (argparse.Namespace) arguments passed from the top-level call to setup sub-command.
Returns:none
stringReplace(xpath, oldstr, newstr)

Edit the text for the nodes identified by xpath (applied to the current config file), and change all occurrences of oldstr to newstr. Currently does not support regex. Callable from XML setup files.

Parameters:
  • xpath – (str) path to elements whose text should be changed
  • oldstr – (str) the substring to match
  • newstr – (str) the replacement string
Returns:

none
taxBioCarbon(market='global', regions=None, forTax=True, forCap=False)

Create the XML for a linked policy to include LUC CO2 in a CO2 cap or tax policy (or both). This function generates the equivalent of any of the 4 files in input/policy/: global_ffict.xml (forTax=False, forCap=False) global_ffict_in_constraint.xml (forTax=False, forCap=True) global_uct.xml (forTax=True, forCap=False) global_uct_in_constraint.xml (forTax=True, forCap=True)

However, unlike those files, the market need not be global, and the set of regions to which to apply the policy can be specified.

Parameters:
  • market – (str) the name of the market for which to create the linked policy
  • regions – (list of str or None) the regions to apply the policy to, or None to indicate all regions.
  • forTax – (bool) True if the linked policy should apply to a CO2 tax
  • forCap – (bool) True if the linked policy should apply to a CO2 cap
Returns:

(str) the generated XML text
taxCarbon(value, startYear=2020, endYear=2100, timestep=5, rate=0.05, regions=None, market='global')

Generate an XML file defining a global carbon tax starting at value and increasing by rate annually. Generate values for the give years. The first year in years is assumed to be the year at which the tax starts at value. The generated file is named ‘carbon-tax-{market}.xml’ and is added to the configuration. Callable from XML setup files.

Parameters:
  • value – (float) the initial value of the tax ($/tonne)
  • years – (list(int)) years to set carbon taxes. Default is 2020-2100 at 10 year time-steps.
  • rate – (float) annual rate of increase. Default is 0.05.
  • regions – (list(str)) the regions for which to create a C tax market. Default is all defined GCAM regions.
  • market – (str) the name of the market to create. Default is ‘global’.
Returns:

none
updateConfigComponent(group, name, value=None, writeOutput=None, appendScenarioName=None)

Update the value of an arbitrary element in GCAM’s configuration.xml file, i.e., <{group}><Value name="{name}>{value}</Value></{group}>

Optional args are used only for <Files> group, which has entries like <Value write-output="1" append-scenario-name="0" name="outFileName">outFile.csv</Value> Values for the optional args can be passed as any of [0, 1, "0", "1", True, False].

Parameters:
  • group – (str) the name of a group of config elements in GCAM’s configuration.xml
  • name – (str) the name of the element to be updated
  • value – (str) the value to set between the <Value></Value> elements
  • writeOutput – (coercible to int) for <Files> group, this sets the optional write-output attribute
  • appendScenarioName – (coercible to int) for <Files> group, this sets the optional append-scenario-name attribute.
Returns:

none
updateScenarioComponent(name, xmlfile)

Set a new filename for a ScenarioComponent identified by the <Value> element name.

Parameters:
  • name – (str) the name of the scenario component to update
  • xmlfile – (str) the location of the XML file, relative to the exe directory, that should replace the existing value
Returns:

none
writePolicyConstraintFile(filename, policyName, region, targets, market=None, minPrice=None, policyElement='policy-portfolio-standard', policyType='subsidy', csvPath=None, scenario=None)

Generate XML constraint file from the parameters given.

Parameters:
  • filename – (str) the name of the XML file to create in the local-xml/{scenario} directory.
  • policyName – (str) the name of the policy, i.e., <policy-portfolio-standard name=”{policyName}”>
  • region – (str) the region to on which apply to the constraints
  • targets – iterable of (year, value) pairs, where year can be an int or a string of the form “y1-y2” indicating a year range sharing the same value.
  • market – (str) the name of the market; default is the region name
  • minPrice – (int or float) if not None, a <min-price> element is created with the value, using the first year in targets and fillout=”1”.
  • policyElement – (str) Defaults to “policy-portfolio-standard”
  • policyType – (str) Either “subsidy” or “tax”
  • csvPath – (str with pathname) the path to a file containing a ‘Scenario’ column and year columns with constraint values. Used to construct targets only if targets is None.
  • scenario – (str) the name of the scenario to extract from the csvFile. Used only if targets is None.
Returns:

none
pygcam.xmlEditor.copyIfMissing(src, dst, makedirs=False)

Copy file src to dst, but only if dst doesn’t already exist.

Parameters:
  • src – (str) pathname of the file to copy
  • dst – (str) pathname of the copy to create
  • makedirs – if True, make any missing directories
Returns:

none
pygcam.xmlEditor.expandYearRanges(seq)

Expand a sequence of (year, value) tuples, or a dict keyed by year, where the year argument may be a string containing identifying range of values with an optional “step” value indicated after a “:”. The default step is 5 years. For example, “2015-2030” expands to (2015, 2020, 2025, 2030), and “2015-2020:1” expands to (2015, 2016, 2017, 2018, 2019, 2020). When a range is given, the tuple is replaced with a sequence of tuples naming each year explicitly. Typical usage is for year, price in expandYearRanges(values): ....

Parameters:seq_or_dict – The sequence of (year, value) tuples, or any object with an items() method that returns (year, value) pairs.
Returns:A list of tuples with the expanded sequence.
pygcam.xmlEditor.extractStubTechnology(region, srcFile, dstFile, sector, subsector, technology, sectorElement='supplysector', fromRegion=False)

Extract a definition from the global-technology-database based on sector, subsector, and technology, defined in srcFile and create a new file, dstFile with the extracted bit as a stub-technology definition for the given region. If fromRegion is True, extract the stub-technology from the regional definition, rather than from the global-technology-database.

Parameters:
  • region – (str) the name of the GCAM region for which to copy the technology
  • srcFile – (str) the pathname of a source XML file with a global-technology-database
  • dstFile – (str) the pathname of the file to create
  • sector – (str) the name of a GCAM sector
  • subsector – (str) the name of a GCAM subsector within sector
  • technology – (str) the name of a GCAM technology within sector and subsector
  • sectorElement – (str) the name of the XML element to create (or search for, if fromRegion is True) between the <region> and <subsector> XML elements. Defaults to ‘supplysector’.
  • fromRegion – (bool) if True, the definition is extracted from a regional definition rather than from the global-technology-database.
Returns:

True on success, else False
pygcam.xmlEditor.makeDirPath(elements, require=False, create=False, mode=509)

Join the tuple of elements to create a path to a directory, optionally checking that it exists or creating intermediate directories as needed.

Parameters:
  • elements – a tuple of pathname elements to join
  • require – if True, raise an error if the path doesn’t exist
  • create – if True, create the path if it doesn’t exist
  • mode – file mode used when making directories
Returns:

the joined path
Raises:

pygcam.error.SetupException
pygcam.xmlEditor.xmlEdit(filename, pairs, op='set', useCache=True)

Edit the XML file filename in place, applying the values to the given xpaths in the list of pairs.

Parameters:
  • filename – the file to edit in-place.
  • pairs – (iterable of (xpath, value) pairs) In each pair, the xpath selects elements or attributes to update with the given values.
  • op – (str) Operation to perform. Must be in (‘set’, ‘multiply’, ‘add’). Note that ‘multiply’ and ‘add’ are not available for xpaths selecting attributes rather than node values. For ‘multiply’ and ‘add’, the value should be passed as a float. For ‘set’, it can be a float or a string.
  • useCache – (bool) if True, the etree is sought first in the XmlCache. This avoids repeated parsing, but the file is always written (eventually) if updated by this function.
Returns:

True on success, else False
pygcam.xmlEditor.xmlIns(filename, xpath, elt)

Insert the element elt as a child to the node found with xpath. :param filename: (str) the file to edit :param xpath: (str) the xml element(s) to search for :param elt: (etree.Element) the node to insert :return: none

pygcam.xmlEditor.xmlSel(filename, xpath, asText=False)

Return True if the XML component identified by the xpath argument exists in filename. Useful for deciding whether to edit or insert an XML element.

Parameters:
  • filename – (str) the file to edit
  • xpath – (str) the xml element(s) to search for
  • asText – (str) if True, return the text of the node, if found, else None
Returns:

(bool) True if found, False otherwise. (see asText)

Sector-specific config editors

These classes subclass XMLEditor to create sector-specific setup functionality.

class pygcam.sectorEditors.BioenergyEditor(baseline, scenario, xmlOutputRoot, xmlSourceDir, workspaceDir, groupDir, srcGroupDir, subdir, parent=None, mcsMode=None, cleanXML=True)

BioenergyEditor adds knowledge of biomass and biofuels.

adjustForestResidueSupply(region, loPrice, loFract, hiPrice, hiFract)

Change supply curves for forest residues in the USA only. loPrice and hiPrice are the new prices to set; loFract and hiFract are the new fractions to assign to these prices.

adjustResidueSupply(loTarget, loPrice, loFract, hiTarget, hiPrice, hiFract, target)

Change supply curves for residues, as per arguments. loTarget and hiTarget identify the price to match in the XML file; loPrice and hiPrice are the new prices to set; loFract and hiFract are the new fractions to assign to these prices. Target must be one of {all, us-crops, us-corn, global-corn} Note that the standard reference supply curve for residue is: 0% at 1975$0; 25% at $1.2; 65% at $1.5; 100% at $10.

localizeCellEthanolTechnologyUSA()

Same as corn ethanol above, but for cellulosic ethanol

localizeCornEthanolTechnologyUSA()

Copy the stub-technology for corn ethanol to CornEthanolUSA.xml and CornEthanolUSA2.xml so they can be manipulated in the US only.

localizeFtBiofuelsTechnologyUSA()

Same as cellulosic ethanol above

purposeGrownOffInRegion(region)

Turn off the “isNewTechnology” flag for all land-leaf nodes to turn off purpose-grown biomass. The line(s) we need to edit in land_input_3.xml is: <isNewTechnology fillout=”1” year=”2020”>1</isNewTechnology>

setBiofuelBiomassCoefficients(fuelName, pairs)

Set new coefficients for biomass conversion for the given fuel

Parameters:
  • fuelName – The name of the liquid fuel, e.g., ‘cellulosic ethanol’, ‘FT biofuel’, etc.
  • pairs – A sequence of tuples of the form (year, coefficient). For example, to set the coefficients for cellulosic ethanol for years 2020 and 2025 to 1.234, the pairs would be ((2020, 1.234), (2025, 1.234)).
Returns:

nothing
setCellEthanolShareWeightUSA(year, shareweight)

Create modified version of cellEthanolUSA.xml with the given share-weight for the given fuel in the given year.

setCornEthanolCoefficients(cornCoef, gasCoef=None, elecCoef=None)

Set corn ethanol performance coefficients, i.e., the (regional) corn, gas, and electricity required per GJ of ethanol. These appear in two files, so we edit them both.

setCornEthanolCoefficientsUSA(cornCoef, gasCoef=None, elecCoef=None)

Set corn ethanol performance coefficients: (regional) corn, gas, and electricity required per GJ of ethanol. Modified from superclass version to operate on biofuelTechUSA.xml.