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(mapper, cleanXML=True)

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

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)

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.ProjectEtc}. 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.ProjectEtc}”, 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

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)

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 after year at the value for that year.

getLocalCopy(configTag) → GcamPath

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. This is generally the first step in the XMLEditor methods that modify XML file content.

Parameters

  • configTag – (str) the configuration file tag (name=”xxx”) of an XML file

  • gp – (bool) whether to return the result as a GcamPath instance. If false, (the default) return a tuple of the relative and absolute pathnames.

Returns

(GcamPath) a GcamPath instance

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.ProjectEtc}”, 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

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.

  • unprotectFirst – (bool) whether to first remove all protection before applying new protections. Default is False.

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 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 the 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.)

  • sectors – (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

  • region – (str) a GCAM region name

  • sector – (str) the name of a GCAM sector

  • subsector – (str) the name of the subsector

  • stubTechnology – (str) the name of a GCAM stub-technology in sector

  • species – (str) the name of the gas for which to set the emissions

  • 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.

  • 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

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 or trial-xml. By “static”, we mean files whose contents are constant, 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 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)

  • startYear – (int) The first year in which to set carbon taxes.

  • endYear – (int) The last year in which to set carbon taxes.

  • timestep – (int) The time-step to use between start and end years. Default is 5 years.

  • 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 only, 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