Note

This page is generated from inline documentation in MESSAGE/sets_maps_def.gms.

Sets and mappings

sets_maps_def.gms defines all sets and mappings used in MESSAGEix. The symbols in the Notation column of the tables below are used in the equations of the mathematical formulation, while the set names appear in 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\)	Periods, denoted by the final year, in the model horizon
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\)	Names of generic relations (linear constraints)
lvl_spatial		Spatial hierarchy levels, e.g. global, region, country, or grid cell.
lvl_temporal		Temporal hierarchy levels, e.g. year, season, day, or 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]

See Years, periods, and time slices.

[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 (\(\text{duration_time}_{\text{'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.

Index names

Where the same set is used 2 or more times to index multiple dimensions of the same parameter, these dimensions are given names (called index names) that differ from the name of the set. The table below contains a partial list of index names appearing in the documentation.

Set	Index name	Description
node	node_dest	Node to which a technology providers commodity output.
node	node_loc	Node where a technology operates.
node	node_origin	Node from which a technology receives commodity input.

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^{\text{RES}} \subseteq L\)	Levels related to fossil resources representation
level_renewable (level) [8]	\(l \in L^{\text{REN}} \subseteq L\)	Levels related to renewables representation
level_storage(level)	\(l \in L^{\text{STOR}} \subseteq L\)	Subsets of levels on which commodities are stored; excluded from commodity balances.
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^{\text{INV}} \subseteq T\)	Specific subset of investment technologies (all technologies with investment decisions and capacity constraints)
renewable_tec (tec) [12]	\(t \in T^{\text{REN}} \subseteq T\)	Specific subset of renewable-energy technologies (all technologies which draw their input from the renewable level)
storage_tec(tec)	\(t \in T^{\text{STOR}} \subseteq T\)	Subset of technologies that are storage container technologies (reservoirs)
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}^{\text{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
time_relative (time)	\(h \in H\)	Parent sub-annual time slices for considering relative time in parameter General parameters of the MESSAGEix implementation

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

Mapping 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 timeslices (used in storage)
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,mode,tec2,mode2,level,commodity,lvl_temporal)	Mapping of charge-discharge technologies tec to their storage container tec2, stored commodity and level.
map_time_commodity_storage(node,tec,level,commodity,mode,year_all,time)	Mapping of storage containers to their input commodity-level (not commodity-level of stored media)

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.