Sets and mappings definition¶

This file contains the definition of all sets and mappings used in MESSAGEix. The short mathematical notation in the Notation column of the tables below is used in the mathematical description relative to the GAMS code.

Sets in the MESSAGEix implementation¶

Set name	Notation	Explanatory comments
node 1	\(n \in N\)	Regions, countries, grid cells
commodity	\(c \in C\)	Resources, electricity, water, land availability, etc.
level	\(l \in L\)	Levels of the reference energy system or supply chain (primary, secondary, … , useful)
grade	\(g \in G\)	Grades of resource quality in the extraction & mining sector
technology [tec]	\(t \in T\)	Technologies that use input commodities to produce outputs; the short-hand notation “tec” is used in the GAMS implementation
mode 2	\(m \in M\)	Modes of operation for specific technologies
emission	\(e \in E\)	Greenhouse gases, pollutants, etc.
land_scenario	\(s \in S\)	Scenarios of land use (for land-use model emulator)
land_type	\(u \in U\)	Land-use types (e.g., field, forest, pasture)
year [year_all] 3 4	\(y \in Y\)	Model horizon (including historical periods for vintage structure of installed capacity and dynamic constraints)
time 5	\(h \in H\)	Subannual time periods (seasons, days, hours)
shares 6	\(p \in P\)	Set of constraints on shares of technologies and commodities
relation 7	\(r \in R\)	Set of generic relations (linear constraints)
lvl_spatial		Set of spatial hierarchy levels (global, region, country, grid cell)
lvl_temporal		Set of temporal hierarchy levels (year, season, day, hour)
rating	\(q \in Q\)	Identifies the ‘quality’ of the renewable energy potential (rating of non-dispatchable technologies relative to aggregate commodity use)

1: The set node includes spatial units across all levels of spatial disaggregation (global, regions, countries, basins, grid cells). The hierarchical mapping is implemented via the mapping set map_spatial_hierarchy. This set always includes an element ‘World’ when initializing a MESSAGE-scheme message_ix.Scenario.
2: For example, high electricity or high heat production modes of operation for combined heat and power plants.
3: In the MESSAGEix implementation in GAMS, the set year_all denotes the “superset” of the entire horizon (historical and model horizon), and the set year is a dynamic subset of year_all. This facilitates an efficient implementation of the historical capacity build-up and the (optional) recursive-dynamic solution approach. When working with a message_ix.Scenario via the scientific programming API, the set of all periods is called year for a more concise notation. The specification of the model horizon is implemented using the mapping set cat_year and the type “firstmodelyear”.

4: In MESSAGEix, the key of an element in set year identifies the last year of the period, i.e., in a set \(year = [2000, 2005, 2010, 2015]\), the period ‘2010’ comprises the years \([2006, .. ,2010]\).
5: The set time collects all sub-annual temporal units across all levels of temporal disaggregation. In a MESSAGE-scheme ixmp.Scenario, this set always includes an element “year”, and the duration of that element is 1 (\(duration\_time_{'year'} = 1\)).
6: A generic formulation of share constraints is implemented in MESSAGEix, see Constraints on shares of technologies and commodities.
7: A generic formulation of linear constraints is implemented in MESSAGEix, see Section of generic relations (linear constraints). These constraints can be used for testing and development, but specific new features should be implemented by specific equations and parameters.

Category types and mappings¶

This feature is used to easily implement aggregation across groups of set elements. For example, by setting an upper bound over an emission type, the constraint enforces that the sum over all emission species mapped to that type via the mapping set cat_emission satisfies that upper bound.

Set name	Notation	Explanatory comments
level_resource (level) 8	\(l \in L^{RES} \subseteq L\)	Levels related to fossil resources representation
level_renewable (level) 8	\(l \in L^{REN} \subseteq L\)	Levels related to renewables representation
type_node 9	\(\widehat{n} \in \widehat{N}\)	Category types for nodes
cat_node (type_node,node)	\(n \in N(\widehat{n})\)	Category mapping between node types and nodes (all nodes that are subnodes of node \(\widehat{n}\))
type_tec 10	\(\widehat{t} \in \widehat{T}\)	Category types for technologies
cat_tec (type_tec,tec) 10	\(t \in T(\widehat{t})\)	Category mapping between tec types and technologies (all technologies mapped to the category `type_tec` \(\widehat{t}\))
inv_tec (tec) 11	\(t \in T^{INV} \subseteq T\)	Specific subset of investment technologies (all technologies with investment decisions and capacity constraints)
renewable_tec (tec) 12	\(t \in T^{REN} \subseteq T\)	Specific subset of renewable-energy technologies (all technologies which draw their input from the renewable level)
addon(tec)	\(t^a \in T^{A} \subseteq T\)	Specific subset of technologies that are an add-on to other (parent) technologies
type_addon	\(\widehat{t^a} \in \widehat{T^A}\)	Category types for add-on technologies (that can be applied mutually exclusive)
cat_addon(type_addon,addon)	\(t^a \in T^A(\widehat{t^a})\)	Category mapping add-on technologies to respective add-on technology types (all add-on technologies mapped to the category `type_addon` \(\widehat{t}\))
type_year	\(\widehat{y} \in \widehat{Y}\)	Category types for year aggregations
cat_year(type_year,year_all)	\(y \in Y(\widehat{y})\)	Category mapping years to respective categories (all years mapped to the category `type_year` \(\widehat{y}\))
type_emission	\(\widehat{e} \in \widehat{E}\)	Category types for emissions (greenhouse gases, pollutants, etc.)
cat_emission (type_emission,emission)	\(e \in E(\widehat{e})\)	Category mapping between emission types and emissions (all emissions mapped to the category `type_emission` \(\widehat{e}\))
type_tec_land (type_tec) 13	\(\widehat{t} \in \widehat{T}^{LAND} \subseteq \widehat{T}\)	Mapping set of technology types and land use
balance_equality (commodity,level)	\(c \in C, l \in L\)	Commodities and level related to Equation COMMODITY_BALANCE_LT
level_storage(level)	\(l \in L^{STOR} \subseteq L\)	Levels related to storage representation (excluded from Equation COMMODITY_BALANCE_LT)
storage_tec(tec)	\(t \in T^{STOR} \subseteq T\)	Set of storage container technologies (reservoirs)

8(1,2): The constraint Equation EXTRACTION_EQUIVALENCE is active only for the levels included in this set, and the constraint Auxiliary COMMODITY_BALANCE is deactivated for these levels.
9: The element “economy” is added by default as part of the MESSAGE-scheme ixmp.Scenario.
10(1,2): The element “all” in type_tec and the associated mapping to all technologies in the set cat_tec are added by default as part of the MESSAGE-scheme message_ix.Scenario.
11: The auxiliary set inv_tec (subset of technology) is a short-hand notation for all technologies with defined investment costs. This activates the investment cost part in the objective function and the constraints for all technologies where investment decisions are relevant. It is added by default when exporting MESSAGE-scheme message_ix.Scenario to gdx.
12: The auxiliary set renewable_tec (subset of technology) is a short-hand notation for all technologies with defined parameters relevant for the equations in the “Renewable” section. It is added by default when exporting MESSAGE-scheme message_ix.Scenario to gdx.
13: The mapping set type_tec_land is a dynamic subset of type_tec and specifies whether emissions from the land-use model emulator module are included when aggregrating over a specific technology type. The element “all” is added by default in a MESSAGE-scheme message_ix.Scenario.

Mappings sets¶

Note

These sets are generated automatically when exporting a MESSAGE-scheme ixmp.Scenario to gdx using the API. They are used in the GAMS model to reduce model size by excluding non-relevant variables and equations (e.g., activity of a technology outside of its technical lifetime). These are not meant to be edited through the API when editing scenarios. Not all the Mapping sets are shown in the list below, to access the full list of mapping sets, please refer to the documentation file found in message_ix\model\MESSAGE\sets_maps_def.gms.

Set name	Explanatory comments
map_node(node,location)	Mapping of nodes across hierarchy levels (location is in node)
map_time(time,time2)	Mapping of time periods across hierarchy levels (time2 is in time)
map_time_period(year_all,lvl_temporal,time,time2)	Mapping of the sequence of sub-annual timesteps (used in storage equations)
map_resource(node,commodity,grade,year_all)	Mapping of resources and grades to node over time
map_ren_grade(node,commodity,grade,year_all)	Mapping of renewables and grades to node over time
map_ren_com(node,tec,commodity,year_all)	Mapping of technologies to renewable energy source as input
map_rating(node,tec,commodity,level,rating,year_all)	Mapping of technologues to ratings bin assignment
map_commodity(node,commodity,level,year_all,time)	Mapping of commodity-level to node and time
map_stocks(node,commodity,level,year_all)	Mapping of commodity-level to node and time
map_tec(node,tec,year_all)	Mapping of technology to node and years
map_tec_time(node,tec,year_all,time)	Mapping of technology to temporal dissagregation (time)
map_tec_mode(node,tec,year_all,mode)	Mapping of technology to modes
map_tec_storage(node,tec,tec2,level,commodity)	Mapping of charge-discharge technologies `tec` to their storage container `tec2`, and `level` and `commodity` of storage

Mapping sets (flags) for bounds¶

There are a number of mappings sets generated when exporting a message_ix.Scenario to gdx. They are used as ‘flags’ to indicate whether a constraint is active. The names of these sets follow the format is_<constraint>_<dir>.

Such mapping sets are necessary because GAMS does not distinguish between 0 and ‘no value assigned’, i.e., it cannot differentiate between a bound of 0 and ‘no bound assigned’.

Note

These sets are also automatically generated. To see the full list of mapping sets for bounds, please refer to the documentation file found in message_ix\model\MESSAGE\sets_maps_def.gms.

Mapping sets (flags) for fixed variables¶

Similar to the mapping sets for bounds, there are mapping sets to indicate whether decision variables are pre-defined to a specific value, usually taken from a solution of another model instance. This can be used to represent imperfect foresight where a policy shift or parameter change is introduced in later years. The names of these sets follow the format is_fixed_<variable>.

Note

These sets are also automatically generated. To see the full list of mapping sets for fixed variables, please refere to the documentation file found in message_ix\model\MESSAGE\sets_maps_def.gms.