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


Explanatory comments

node [1]

\(n \in N\)

Regions, countries, grid cells


\(c \in C\)

Resources, electricity, water, land availability, etc.


\(l \in L\)

Levels of the reference energy system or supply chain (primary, secondary, … , useful)


\(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


\(e \in E\)

Greenhouse gases, pollutants, etc.


\(s \in S\)

Scenarios of land use (for land-use model emulator)


\(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)


Spatial hierarchy levels, e.g. global, region, country, or grid cell.


Temporal hierarchy levels, e.g. year, season, day, or hour.


\(q \in Q\)

Identifies the ‘quality’ of the renewable energy potential (rating of non-dispatchable technologies relative to aggregate commodity use)

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.


Index name




Node to which a technology providers commodity output.



Node where a technology operates.



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


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


\(l \in L^{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^{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)


\(t \in T^{STOR} \subseteq T\)

Subset of technologies that are storage container technologies (reservoirs)


\(t^a \in T^{A} \subseteq T\)

Specific subset of technologies that are an add-on to other (parent) technologies


\(\widehat{t^a} \in \widehat{T^A}\)

Category types for add-on technologies (that can be applied mutually exclusive)


\(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}\))


\(\widehat{y} \in \widehat{Y}\)

Category types for year aggregations


\(y \in Y(\widehat{y})\)

Category mapping years to respective categories (all years mapped to the category type_year \(\widehat{y}\))


\(\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

time_relative (time)

\(h \in H\)

Parent sub-annual time slices for considering relative time in parameter General parameters of the MESSAGEix implementation

Mapping sets


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


Mapping of nodes across hierarchy levels (location is in node)


Mapping of time periods across hierarchy levels (time2 is in time)


Mapping of the sequence of sub-annual timeslices (used in storage)


Mapping of resources and grades to node over time


Mapping of renewables and grades to node over time


Mapping of technologies to renewable energy source as input


Mapping of technologues to ratings bin assignment


Mapping of commodity-level to node and time


Mapping of commodity-level to node and time


Mapping of technology to node and years


Mapping of technology to temporal dissagregation (time)


Mapping of technology to modes


Mapping of charge-discharge technologies tec to their storage container tec2, stored commodity and level.


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


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


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.