Add commodity flow of capacity variables

RELEASE_NOTES.rst

@@ -4,6 +4,22 @@ Next release
 All changes
 -----------
 
+- Add representation of commodity flows associated with construction and retirement of technology capacity (:pull:`451`).
+
+  - New parameters
+    |input_cap|,
+    |input_cap_new|,
+    |input_cap_ret|,
+    |output_cap|,
+    |output_cap_new|, and
+    |output_cap_ret|.
+    When loading a Scenario created with :mod:`message_ix` version 3.11.0 or earlier,
+    these items are automatically initialized (and left empty),
+    using at most one call to :meth:`~message_ix.Scenario.commit`.
+    See :meth:`.MESSAGE.initialize`.
+  - Revise :ref:`equation_commodity_balance_aux` to include input and output flows based on |CAP| and |CAP_NEW|.
+  - New :class:`.MESSAGE` / :meth:`.Scenario.solve` option :py:`cap_comm=True` to enable this representation.
+
 - Document the :ref:`minimum version of Java <install-java>` required for :class:`ixmp.JDBCBackend <ixmp.backend.jdbc.JDBCBackend>` (:pull:`962`).
 - Improve type hinting (:pull:`963`).
 

doc/api.rst

@@ -249,6 +249,18 @@ Model classes
    :exclude-members: defaults
    :show-inheritance:
 
+   MESSAGE accepts the following *model_options* to control its behaviour:
+
+   - **cap_comm** (:class:`bool` or equivalent :class:`int` or :class:`float`):
+     If :any:`True`, include **comm** odity flows associated with **cap** acity changes of technologies
+     in :ref:`equation_commodity_balance_aux`.
+     If :any:`False` (the default), these flow are omitted,
+     and values of the associated parameters have no effect.
+     This corresponds to the GAMS compile-time variable ``MESSAGE_CAP_COMM``.
+
+     .. note:: For some models, this can significantly increase the linear program (LP) size
+        and thus the solve time.
+
    .. autoattribute:: items
       :no-value:
 
@@ -263,10 +275,10 @@ Model classes
    The MACRO class solves only the MACRO model in “standalone” mode—that is, without MESSAGE.
    It is also invoked from :class:`.MESSAGE_MACRO` to process *model_options* to control the behaviour of MACRO:
 
-   - **concurrent** (:class:`int` or :class:`float`, either :py:`0` or :py:`1`).
+   - **concurrent** (:class:`bool` or equivalent :class:`int` or :class:`float`).
      This corresponds to the GAMS compile-time variable ``MACRO_CONCURRENT``.
-     If set to :py:`0` (the default), MACRO is solved in a loop, once for each node in the Scenario.
-     If set to :py:`1`, MACRO is solved only once, for all nodes simultaneously.
+     If :any:`False` (the default), MACRO is solved in a loop, once for each node in the Scenario.
+     If :any:`True`, MACRO is solved only once, for all nodes simultaneously.
 
    .. autoattribute:: items
       :no-value:
@@ -279,7 +291,8 @@ Model classes
    MESSAGE_MACRO solves the MESSAGE and MACRO models iteratively, connecting changes in technology activity and resource demands (from MESSAGE) to changes in final demands and prices (from MACRO).
    This iteration continues until the solution *converges*; i.e. the two models reach a stable point for the values of these parameters.
 
-   MESSAGE_MACRO accepts three additional *model_options* that control the behaviour of this iteration algorithm:
+   MESSAGE_MACRO accepts all of the *model_options* recognized by :class:`.MESSAGE` and :class:`.MACRO`,
+   plus additional options that control the behaviour of this iteration algorithm:
 
    - **max_adjustment** (:class:`float`, default 0.2): the maximum absolute relative change in final demands between iterations.
      If MACRO returns demands that have changed by more than a factor outside the range (1 - `max_adjustment`, 1 + `max_adjustment`) since the previous iteration, then the change is confined to the limits of that range for the next run of MESSAGE.

doc/conf.py

@@ -67,6 +67,7 @@
 
    <abbr title="International Institute for Applied Systems Analysis">IIASA</abbr>
 
+.. |y0| replace:: :math:`y_0`
 .. |yA| replace:: :math:`y^A`
 .. |yV| replace:: :math:`y^V`
 """
@@ -77,13 +78,29 @@
 # sometimes multiple targets appear above a single heading, and that heading text would
 # be automatically used for the link text.
 for name in (
+    "ACT",
+    "CAP",
+    "CAP_NEW",
+    "LAND",
+    "STOCK_CHG",
     "duration_period",
     "duration_period_sum",
     "growth_new_capacity_up",
     "historical_new_capacity",
     "initial_new_capacity_up",
+    "input",
+    "input_cap",
+    "input_cap_new",
+    "input_cap_ret",
+    "output",
+    "output_cap",
+    "output_cap_new",
+    "output_cap_ret",
+    "land_input",
+    "land_output",
     "map_tec_lifetime",
     "remaining_capacity",
+    "technical_lifetime",
 ):
     rst_prolog += f"\n.. |{name}| replace:: :ref:`{name} <{name}>`"
 
@@ -222,8 +239,9 @@ def local_inv(name: str, *parts: str) -> Optional[str]:
 macros = {}
 macros.update(
     {
-        k.replace("_", ""): r"\text{{{k}}}"
+        k.replace("_", ""): rf"\text{{{k}}}"
         for k in """ACT
+COMMODITY_BALANCE
 STORAGE
 STORAGE_CHARGE
 duration_time_rel

message_ix/core.py

@@ -755,7 +755,8 @@ def solve(self, model="MESSAGE", solve_options={}, **kwargs):
             See the :class:`.MESSAGE` class and :obj:`.DEFAULT_CPLEX_OPTIONS`.
         kwargs :
             Other options control the execution of the underlying GAMS code; see the
-            :class:`.MESSAGE_MACRO` class and :class:`.GAMSModel`.
+            *model_options* described for :class:`.MESSAGE`, :class:`.MACRO`,
+            :class:`.MESSAGE_MACRO`, and :class:`.GAMSModel`.
         """
         super().solve(model=model, solve_options=solve_options, **kwargs)