Update release notes with migration note; add storage items to docs

RELEASE_NOTES.rst

@@ -1,9 +1,18 @@
 Next release
 ============
 
+Migration notes
+---------------
+
+The :ref:`generic storage formulation <gams-storage>` introduces **new ixmp items** (sets, parameters, variables, and equations) to the MESSAGE model scheme.
+When loading a Scenario created with a version of message_ix older than x.x.x, these items will be initialized (and left empty), using at most one call to :meth:`~message_ix.Scenario.commit`.
+See :meth:`.MESSAGE.initialize`.
+
+
 All changes
 -----------
 
+- :pull:`190`: Add generic mathematical formulation of :ref:`technologies that store commodities <gams-storage>`, such as water and energy.
 - `#328 <https://github.com/iiasa/message_ix/pull/328>`_: Expand automatic reporting of emissions prices and mapping sets; improve robustness of :meth:`Reporter.convert_pyam`.
 - `#321 <https://github.com/iiasa/message_ix/pull/321>`_: Move :meth:`.Scenario.to_excel`, :meth:`.read_excel` to :class:`ixmp.Scenario`; they continue to work with message_ix.Scenario.
 - `#323 <https://github.com/iiasa/message_ix/pull/323>`_: Add `units`, `replace_vars` arguments to :meth:`.Reporter.convert_pyam`.

doc/source/api.rst

@@ -90,7 +90,7 @@ Model classes
    These configure the GAMS CPLEX solver (or another solver, if selected); see `the solver documentation <https://www.gams.com/latest/docs/S_CPLEX.html>`_ for possible values.
 
 .. autoclass:: MESSAGE
-   :members:
+   :members: initialize
    :exclude-members: defaults
    :show-inheritance:
 
@@ -131,6 +131,12 @@ Model classes
 
    .. autoattribute:: name
 
+.. autodata:: MESSAGE_ITEMS
+
+   Currently, these only include items required for :ref:`storage <gams-storage>`, in order to ensure that all scenarios are compatible with the MESSAGE GAMS implementation.
+
+   .. seealso:: :meth:`.MESSAGE.initialize`
+
 
 .. _utils:
 

message_ix/models.py

@@ -20,17 +20,21 @@
 # Common indices for some parameters in MESSAGE_ITEMS
 _idx_common = ['node', 'technology', 'level', 'commodity', 'year', 'time']
 
-# List of ixmp items for MESSAGE
 # NB only a partial list; see https://github.com/iiasa/message_ix/issues/254
+#: List of ixmp items for MESSAGE.
 MESSAGE_ITEMS = {
+    # Index sets
     # Storage level
     'level_storage': dict(ix_type='set'),
     # Storage reservoir technology
     'storage_tec': dict(ix_type='set'),
-    # Mapping of storage reservoir to charger/discharger
+
+    # Mapping set: mapping of storage reservoir to charger/discharger
     'map_tec_storage': dict(ix_type='set',
                             idx_sets=['node', 'technology', 'storage_tec',
                                       'level', 'commodity']),
+
+    # Parameters
     # Order of sub-annual time steps
     'time_order': dict(ix_type='par', idx_sets=['lvl_temporal', 'time']),
     # Relating content of storage in two different time steps (or
@@ -41,10 +45,10 @@
                   'time', 'time'],
         idx_names=['node', 'technology', 'level', 'commodity', 'year_first',
                    'year_last', 'time_first', 'time_last']),
-    # Storage losses as a percentage of installed capacity
-    'storage_self_discharge': dict(ix_type='par', idx_sets=_idx_common),
     # Initial amount of storage
     'storage_initial': dict(ix_type='par', idx_sets=_idx_common),
+    # Storage losses as a percentage of installed capacity
+    'storage_self_discharge': dict(ix_type='par', idx_sets=_idx_common),
 }
 
 
@@ -94,7 +98,12 @@ def read_version(cls):
 
     @classmethod
     def initialize(cls, scenario):
-        """Set up *scenario* with required sets and parameters for MESSAGE."""
+        """Set up *scenario* with required sets and parameters for MESSAGE.
+
+        See Also
+        --------
+        :data:`MESSAGE_ITEMS`
+        """
         # Initialize the ixmp items
         cls.initialize_items(scenario, MESSAGE_ITEMS)