Restructure the yaml file format to separate variable types from fuels

nomenclature/__init__.py

@@ -14,6 +14,12 @@
 # path to nomenclature definitions
 DEF_PATH = Path(__file__).parent / 'definitions'
 
+# auxiliary dictionary to add CCS subcategories
+CCS_TYPES = [
+    ('w/ CCS', 'with a CO2 capture component'),
+    ('w/o CCS', 'with freely vented CO2 emissions')
+]
+
 
 def _parse_yaml(path, file='**/*', ext='.yaml'):
     """Parse `file` in `path` (or all files in subfolders if `file='**/*'`)"""
@@ -28,9 +34,47 @@ def _parse_yaml(path, file='**/*', ext='.yaml'):
     return dct
 
 
-variables = _parse_yaml(DEF_PATH / 'variable')
+def _copy_dict(dct, description):
+    """Return a copy of `dct` after overwriting the `description`"""
+    _dct = dct.copy()
+    _dct['description'] = description
+    return _dct
+
+
+variables = dict()
 """Dictionary of variables"""
 
+# read all variable definitions to auxiliary dictionary
+_variables = _parse_yaml(DEF_PATH / 'variable')
+
+# explode <Fuels> tags to full lists
+fuel_types = _variables.pop('<Fuel>')
+d = 'description'
+for key, value in _variables.items():
+    # if the key contains the tag, loop over all fuel types to add mapping
+    if '<Fuel>' in key:
+        for f, attr in fuel_types.items():
+            # ignore the file attribute in the <Fuel> dictionary
+            if f == 'file':
+                continue
+
+            # change generic tag to specific item in key and description
+            _key = key.replace('<Fuel>', f)
+            _description = value[d].replace('<this fuel>', attr[d].lower())
+            variables[_key] = _copy_dict(value, _description)
+
+            # add CCS subcategories (if applicable)
+            if 'ccs' in attr and attr['ccs'] is True:
+                for sub, desc in CCS_TYPES:
+                    _key_ccs = f'{_key}|{sub}'
+                    _description_ccs = f'{_description} {desc}'
+                    variables[_key_ccs] = _copy_dict(value, _description_ccs)
+    # otherwise, move items from auxiliary to public dictionary
+    else:
+        variables[key] = _variables[key]
+
+# remove auxiliary dictionary
+del _variables
 
 regions = _parse_yaml(DEF_PATH / 'region')
 """Dictionary of all regions"""

nomenclature/definitions/variable/energy/energy-secondary.yaml

@@ -1,169 +1,13 @@
 # List of variables related to energy
 
+# The tag <Fuels> can be replaced by any item in the list in `fuel_types.yaml`
+
 Secondary Energy|Electricity:
    description: Total net electricity production
    unit: EJ/yr
 
-Secondary Energy|Electricity|Biomass:
-   description: Net electricity production from municipal solid waste,
-                purpose-grown biomass, crop residues, forest industry waste,
-                biogas
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Biomass|w/ CCS:
-   description: Net electricity production from municipal solid waste,
-                purpose-grown biomass, crop residues, forest industry waste
-                with a co2 capture component
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Biomass|w/o CCS:
-   description: Net electricity production from municipal solid waste,
-                purpose-grown biomass, crop residues, forest industry waste
-                with freely vented co2 emissions
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Coal:
-   description: Net electricity production from coal
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Coal|w/ CCS:
-   description: Net electricity production from coal with a co2 capture
-                component
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Coal|w/o CCS:
-   description: Net electricity production from coal with freely vented co2
-                emissions
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Fossil:
-   description: Net electricity production from fossil fuels
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas:
-   description: Net electricity production from natural gas (including methane from biomass or hydrogenation)
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|w/ CCS:
-   description: Net electricity production from natural gas (including methane from biomass or hydrogenation) with a co2 capture
-                component
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|w/o CCS:
-   description: Net electricity production from natural gas (including methane from biomass or hydrogenation) with freely vented
-                co2 emissions
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|Fossil:
-   description: Net electricity production from (fossil) natural gas
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|Fossil|w/ CCS:
-   description: Net electricity production from (fossil) natural gas with a co2 capture
-                component
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|Fossil|w/o CCS:
-   description: Net electricity production from (fossil) natural gas with freely vented
-                co2 emissions
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|Biomethane:
-   description: Net electricity production from biomethane (upgraded biogas)
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|Biomethane|w/ CCS:
-   description: Net electricity production from biomethane (upgraded biogas) with a co2 capture
-                component
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|Biomethane|w/o CCS:
-   description: Net electricity production from biomethane (upgraded biogas) with freely vented
-                co2 emissions
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|Synthetic Methane:
-   description: Net electricity production from synthetic methane (methanation of hydrogen)
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|Synthetic Methane|w/ CCS:
-   description: Net electricity production from synthetic methane (methanation of hydrogen) with a co2 capture
-                component
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Gas|Synthetic Methane|w/o CCS:
-   description: Net electricity production from synthetic methane (methanation of hydrogen) with freely vented
-                co2 emissions
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Hydrogen:
-   description: Net electricity production from hydrogen (via fuelcells or hydrogen OCGTs)
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Geothermal:
-   description: Net electricity production from all sources of geothermal
-                energy (e.g., hydrothermal, enhanced geothermal systems)
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Hydro:
-   description: Net hydroelectric production
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Non-Biomass Renewables:
-   description: Net electricity production from hydro, wind, solar, geothermal,
-                ocean, and other renewable sources (excluding bioenergy). this
-                is a summary category for all the non-biomass renewables.
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Nuclear:
-   description: Net electricity production from nuclear energy
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Ocean:
-   description: Net electricity production from ocean energy
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Oil:
-   description: Net electricity production from refined liquid oil products
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Oil|w/ CCS:
-   description: Net electricity production from refined liquids with a co2
-                capture component
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Oil|w/o CCS:
-   description: Net electricity production from refined liquids with freely
-                vented co2 emissions
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Other:
-   description: Net electricity production from other sources
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Solar:
-   description: Net electricity production from all sources of solar energy
-                (e.g., pv and concentrating solar power)
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Solar|CSP:
-   description: Net electricity production from concentrating solar power (csp)
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Solar|PV:
-   description: Net electricity production from solar photovoltaics (pv)
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Wind:
-   description: Net electricity production from wind energy (on- and offshore)
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Wind|Offshore:
-   description: Net electricity production from offshore wind energy
-   unit: EJ/yr
-
-Secondary Energy|Electricity|Wind|Onshore:
-   description: Net electricity production from onshore wind energy
+Secondary Energy|Electricity|<Fuel>:
+   description: Net electricity production from <this fuel>
    unit: EJ/yr
 
 Secondary Energy|Gases:

nomenclature/definitions/variable/fuel_types.yaml

@@ -0,0 +1,124 @@
+# This list of fuels will replace any occurrence of `<Fuel>`
+# in a variable-definition yaml file
+
+# All fuels that have the attribute "ccs: True" have two sub-categories
+# "w/ CCS": with a CO2 capture component
+# "w/o CCS": with freely vented CO2 emissions
+
+<Fuel>:
+  Biomass:
+    description: Purpose-grown biomass, crop residues, forest industry waste,
+      solid waste from domestic, agricultural or municipal sources
+    ccs: True
+
+  Biomass|Traditional:
+    description: Traditional biomass (domestic and agricultural waste,
+      forest residues)
+    ccs: True
+
+  Biomass|New and Imported:
+    description: Biomass from dedicated energy crops and biomass imports
+    ccs: True
+
+  Fossil:
+    description: All fossil fuels (crude oil, coal, natural gas)
+    ccs: True
+
+  Coal:
+    description: Coal (including hard coal and lignite)
+    ccs: True
+
+  Coal|Lignite:
+    description: Lignite coal and sub-bituminous coal
+    ccs: True
+
+  Coal|Hard:
+    description: Hard coal
+    ccs: True
+
+  Gas:
+    description: Natural gas (including methane from biomass or hydrogenation)
+    ccs: True
+
+  Gas|OCGT:
+    description: Natural gas (including methane from biomass or hydrogenation)
+      in an open-cycle gas turbine (OCGT) power plant
+    ccs: True
+
+  Gas|CCGT:
+     description: Natural gas (including methane from biomass or hydrogenation)
+       in an combined-cycle gas turbine (CCGT) power plant
+     ccs: True
+
+  Gas|Fossil:
+    description: Natural gas (excluding methane from biomass or hydrogenation)
+    ccs: True
+
+  Gas|Biomethane:
+    description: Biomethane (upgraded biogas)
+    ccs: True
+
+  Gas|Synthetic Methane:
+    description: Synthetic methane (methanation of hydrogen)
+    ccs: True
+
+  Oil:
+    description: Refined liquid oil products
+    ccs: True
+
+  Nuclear:
+    description: Nuclear energy
+
+  Hydrogen:
+    description: Hydrogen
+
+  Non-Biomass Renewables:
+    description: Hydro, wind, solar, geothermal, ocean, and other renewable
+      sources excluding bioenergy
+
+  Hydro:
+    description: Hydropower
+
+  Hydro|Run of River:
+    description: Hydropower from run-of-river power plants
+      (ie. without storage capacity)
+
+  Hydro|Pumped Storage:
+    description: Hydropower systems with short-term storage capacity
+      (including pumping turbines)
+    notes: This hydropower system has two water reservoirs at different
+      elevations. The definition follows the convention established
+      by the ENTSO-E transparency platform (https://transparency.entsoe.eu).
+
+  Hydro|Reservoir:
+    description: Hydropower systems with seasonal storage capacity
+      (possibly including pumping turbines)
+    notes: This definition follows the convention established
+      by the ENTSO-E transparency platform (https://transparency.entsoe.eu).
+
+  Solar:
+    description: Solar energy including PV and CSP
+
+  Solar|CSP:
+    description: Concentrating/concentrated solar power (CSP)
+
+  Solar|PV:
+    description: Solar photovoltaics (PV)
+
+  Wind:
+    description: Wind energy (on- and offshore)
+
+  Wind|Offshore:
+    description: Offshore wind energy
+
+  Wind|Onshore:
+    description: Onshore wind energy
+
+  Geothermal:
+    description: Geothermal energy (including hydrothermal systems)
+
+  Ocean:
+    description: Ocean energy
+
+  Other:
+    description: Other energy sources and fuels not explicitely listed

nomenclature/tests/test_core.py

@@ -6,6 +6,19 @@ def test_variables():
     assert 'Emissions|CO2' in nc.variables
 
 
+def test_variables_fuel_types():
+    # check that exploding of <Fuel> to fuels works (including CCS subcategory)
+    obs = nc.variables['Secondary Energy|Electricity|Gas']
+    exp = 'Net electricity production from natural gas ' \
+          '(including methane from biomass or hydrogenation)'
+    assert obs['description'] == exp
+
+    obs = nc.variables['Secondary Energy|Electricity|Gas|w/ CCS']
+    exp = 'Net electricity production from natural gas (including methane ' \
+          'from biomass or hydrogenation) with a CO2 capture component'
+    assert obs['description'] == exp
+
+
 def test_regions():
     # check that regions dictionary is not empty and has specific element
     assert 'Europe' in nc.regions