.. note:: This page is generated from inline documentation in ``MESSAGE/sets_maps_def.gms``.
.. _sets_maps_def:
Sets and mappings
=================
:file:`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.
.. _section_set_def:
Sets in the |MESSAGEix| implementation
--------------------------------------
.. list-table::
:widths: 20 12 68
:header-rows: 1
* - Set name
- Notation
- Explanatory comments
* - node [#node]_
- :math:`n \in N`
- Regions, countries, grid cells
* - commodity
- :math:`c \in C`
- Resources, electricity, water, land availability, etc.
* - level
- :math:`l \in L`
- Levels of the reference energy system or supply chain (primary, secondary, ... , useful)
* - grade
- :math:`g \in G`
- Grades of resource quality in the extraction & mining sector
* - technology [tec]
- :math:`t \in T`
- | Technologies that use input commodities to produce outputs;
| the short-hand notation "tec" is used in the GAMS implementation
* - mode [#mode]_
- :math:`m \in M`
- Modes of operation for specific technologies
* - emission
- :math:`e \in E`
- Greenhouse gases, pollutants, etc.
* - land_scenario
- :math:`s \in S`
- Scenarios of land use (for land-use model emulator)
* - land_type
- :math:`u \in U`
- Land-use types (e.g., field, forest, pasture)
* - year [year_all] [#year_all]_ [#period_year]_
- :math:`y \in Y`
- Periods, denoted by the final year, in the model horizon
* - time [#time]_
- :math:`h \in H`
- Subannual time periods (seasons, days, hours)
* - shares [#shares]_
- :math:`p \in P`
- Set of constraints on shares of technologies and commodities
* - relation [#relations]_
- :math:`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
- :math:`q \in Q`
- Identifies the 'quality' of the renewable energy potential (rating of non-dispatchable
technologies relative to aggregate commodity use)
.. [#node] 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 :class:`message_ix.Scenario`.
.. [#mode] For example, high electricity or high heat production modes of operation for combined heat and power plants.
.. [#year_all] 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 :class:`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".
.. [#period_year] See :doc:`/time`.
.. [#time] The set ``time`` collects all sub-annual temporal units across all levels of temporal disaggregation.
In a ``MESSAGE``-scheme :class:`ixmp.Scenario`, this set always includes an element "year",
and the duration of that element is 1 (:math:`\text{duration_time}_{\text{'year'}} = 1`).
.. [#shares] A generic formulation of share constraints is implemented in |MESSAGEix|,
see :ref:`share_constraints`.
.. [#relations] A generic formulation of linear constraints is implemented in |MESSAGEix|,
see :ref:`section_of_generic_relations`. 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 :ref:`parameter <parameter_def>`,
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.
.. list-table::
:widths: 18 18 64
:header-rows: 1
* - 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.
.. _mapping-sets:
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.
.. list-table::
:widths: 25 15 60
:header-rows: 1
* - Set name
- Notation
- Explanatory comments
* - level_resource (level) [#level_res]_
- :math:`l \in L^{\text{RES}} \subseteq L`
- Levels related to `fossil resources` representation
* - level_renewable (level) [#level_res]_
- :math:`l \in L^{\text{REN}} \subseteq L`
- Levels related to `renewables` representation
* - level_storage(level)
- :math:`l \in L^{\text{STOR}} \subseteq L`
- Subsets of levels on which commodities are :ref:`stored <gams-storage>`; excluded from :ref:`commodity balances <commodity_balance_lt>`.
* - type_node [#type_node]_
- :math:`\widehat{n} \in \widehat{N}`
- Category types for nodes
* - cat_node (type_node,node)
- :math:`n \in N(\widehat{n})`
- Category mapping between node types and nodes (all nodes that are subnodes of node :math:`\widehat{n}`)
* - type_tec [#type_tec]_
- :math:`\widehat{t} \in \widehat{T}`
- Category types for technologies
* - cat_tec (type_tec,tec) [#type_tec]_
- :math:`t \in T(\widehat{t})`
- Category mapping between tec types and technologies (all technologies mapped to the category ``type_tec`` :math:`\widehat{t}`)
* - inv_tec (tec) [#inv_tec]_
- :math:`t \in T^{\text{INV}} \subseteq T`
- Specific subset of investment technologies (all technologies with investment decisions and capacity constraints)
* - renewable_tec (tec) [#renewable_tec]_
- :math:`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)
- :math:`t \in T^{\text{STOR}} \subseteq T`
- Subset of technologies that are :ref:`storage <gams-storage>` container technologies (reservoirs)
* - addon(tec)
- :math:`t^a \in T^{A} \subseteq T`
- Specific subset of technologies that are an add-on to other (parent) technologies
* - type_addon
- :math:`\widehat{t^a} \in \widehat{T^A}`
- Category types for add-on technologies (that can be applied mutually exclusive)
* - cat_addon(type_addon,addon)
- :math:`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`` :math:`\widehat{t}`)
* - type_year
- :math:`\widehat{y} \in \widehat{Y}`
- Category types for year aggregations
* - cat_year(type_year,year_all)
- :math:`y \in Y(\widehat{y})`
- Category mapping years to respective categories (all years mapped to the category ``type_year`` :math:`\widehat{y}`)
* - type_emission
- :math:`\widehat{e} \in \widehat{E}`
- Category types for emissions (greenhouse gases, pollutants, etc.)
* - cat_emission (type_emission,emission)
- :math:`e \in E(\widehat{e})`
- Category mapping between emission types and emissions (all emissions mapped to the category ``type_emission`` :math:`\widehat{e}`)
* - type_tec_land (type_tec) [#type_tec_land]_
- :math:`\widehat{t} \in \widehat{T}^{\text{LAND}} \subseteq \widehat{T}`
- Mapping set of technology types and land use
* - balance_equality (commodity,level)
- :math:`c \in C, l \in L`
- Commodities and level related to :ref:`commodity_balance_lt`
* - time_relative (time)
- :math:`h \in H`
- Parent sub-annual time slices for considering relative time in parameter :ref:`duration_time_rel`
.. [#level_res] The constraint :ref:`extraction_equivalence` is active only for the levels included in this set,
and the constraint :ref:`commodity_balance` is deactivated for these levels.
.. [#type_node] The element "economy" is added by default as part of the ``MESSAGE``-scheme :class:`ixmp.Scenario`.
.. [#type_tec] 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 :class:`message_ix.Scenario`.
.. [#inv_tec] 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 :class:`message_ix.Scenario` to gdx.
.. [#renewable_tec] 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 :class:`message_ix.Scenario` to gdx.
.. [#type_tec_land] 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 :class:`message_ix.Scenario`.
.. _section_maps_def:
Mapping sets
------------
.. note::
These sets are **generated automatically** when exporting a ``MESSAGE``-scheme :class:`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``.
.. list-table::
:widths: 40 60
:header-rows: 1
* - 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 :ref:`storage <gams-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)
.. _section_maps_bounds:
Mapping sets (flags) for bounds
-------------------------------
There are a number of mappings sets generated when exporting a :class:`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``.
.. _section_maps_fixed:
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``.