Merge pull request #808 from daymontas1/macro_update

khaeru · web-flow · commit 1f32d58804cb · 2025-05-26T13:27:24.000+02:00
Add an option to solve MACRO concurrently for all regions
diff --git a/RELEASE_NOTES.rst b/RELEASE_NOTES.rst
@@ -30,6 +30,7 @@ All changes
 
 - Some MESSAGEix :doc:`tutorials <tutorials>` are runnable with the :class:`.IXMP4Backend` introduced in :mod:`ixmp` version 3.11 (:pull:`894`, :pull:`941`).
   See `Support roadmap for ixmp4 <https://github.com/iiasa/message_ix/discussions/939>`__ for details.
+- Add the :py:`concurrent=...` model option to :class:`.MACRO` (:pull:`808`).
 - Adjust use of :ref:`type_tec <mapping-sets>` in :ref:`equation_emission_equivalence` (:pull:`930`, :issue:`929`, :pull:`935`).
 
   This change reduces the size of the ``EMISS`` variable,
diff --git a/doc/api.rst b/doc/api.rst
@@ -260,6 +260,14 @@ Model classes
    :exclude-members: items
    :show-inheritance:
 
+   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`).
+     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.
+
    .. autoattribute:: items
       :no-value:
 
diff --git a/message_ix/model/MACRO/macro_solve.gms b/message_ix/model/MACRO/macro_solve.gms
@@ -55,29 +55,40 @@ C.FX(node_macro, macro_base_period) = c0(node_macro) ;
 I.FX(node_macro, macro_base_period) = i0(node_macro) ;
 EC.FX(node_macro, macro_base_period) = y0(node_macro) - i0(node_macro) - c0(node_macro) ;
 
-* ------------------------------------------------------------------------------
-* solving the model region by region
-* ------------------------------------------------------------------------------
+$IFTHEN %MACRO_CONCURRENT% == "0"
 
-node_active(node) = no ;
+DISPLAY "Solve MACRO for each node in sequence";
 
-LOOP(node $ node_macro(node),
+node_active(node) = NO ;
 
-    node_active(node_macro) = no ;
-    node_active(node) = YES;
-*    DISPLAY node_active ;
+LOOP(node$node_macro(node),
+  node_active(node_macro) = NO ;
+  node_active(node) = YES ;
+*  DISPLAY node_active ;
 
-* ------------------------------------------------------------------------------
-* solve statement
-* ------------------------------------------------------------------------------
+  SOLVE MESSAGE_MACRO MAXIMIZING UTILITY USING NLP ;
+
+* Write model status summary for the current node
+*  status(node,'modelstat') = MESSAGE_MACRO.modelstat ;
+*  status(node,'solvestat') = MESSAGE_MACRO.solvestat ;
+*  status(node,'resUsd')    = MESSAGE_MACRO.resUsd ;
+*  status(node,'objEst')    = MESSAGE_MACRO.objEst ;
+*  status(node,'objVal')    = MESSAGE_MACRO.objVal ;
+);
+
+$ELSE
+
+DISPLAY "Solve MACRO for all nodes concurrently";
+
+node_active(node_macro) = YES;
 
-    SOLVE MESSAGE_MACRO MAXIMIZING UTILITY USING NLP ;
+SOLVE MESSAGE_MACRO MAXIMIZING UTILITY USING NLP;
 
-* write model status summary (by node)
-*    status(node,'modelstat') = MESSAGE_MACRO.modelstat ;
-*    status(node,'solvestat') = MESSAGE_MACRO.solvestat ;
-*    status(node,'resUsd')    = MESSAGE_MACRO.resUsd ;
-*    status(node,'objEst')    = MESSAGE_MACRO.objEst ;
-*    status(node,'objVal')    = MESSAGE_MACRO.objVal ;
+* Write model status summary for all nodes
+* status('all','modelstat') = MESSAGE_MACRO.modelstat;
+* status('all','solvestat') = MESSAGE_MACRO.solvestat;
+* status('all','resUsd')    = MESSAGE_MACRO.resUsd;
+* status('all','objEst')    = MESSAGE_MACRO.objEst;
+* status('all','objVal')    = MESSAGE_MACRO.objVal;
 
-) ;
+$ENDIF
diff --git a/message_ix/model/MACRO/setup.gms b/message_ix/model/MACRO/setup.gms
@@ -0,0 +1,21 @@
+* A scenario name is mandatory to load the gdx file - abort the run if not specified or file does not exist
+$IF NOT SET in       $ABORT "no input data file provided!"
+$IF NOT EXIST '%in%' $ABORT "input GDX file '%in%' does not exist!"
+$IF NOT SET out      $SETGLOBAL out "output/MsgOutput.gdx"
+
+* MACRO mode. This can take 3 possible values:
+*
+* - "none": MACRO is not run, MESSAGE is run in stand-alone mode.
+* - "linked": MESSAGE and MACRO are run in linked/iterative mode.
+*   This value is set in MESSAGE-MACRO_run.gms.
+* - "standalone": MACRO is run without MESSAGE.
+*   This value is set in MACRO_run.gms
+$IF NOT SET macromode $ABORT "The global setting/command line option --macromode must be set"
+
+* Option to solve MACRO either…
+*
+* - 0: in sequence
+* - 1: in parallel
+*
+* See macro_solve.gms
+$IF NOT SET MACRO_CONCURRENT $SETGLOBAL MACRO_CONCURRENT "0"
diff --git a/message_ix/model/MACRO_run.gms b/message_ix/model/MACRO_run.gms
@@ -1,17 +1,12 @@
-* a scenario name is mandatory to load the gdx file - abort the run if not specified or file does not exist
-$IF NOT SET in       $ABORT "no input data file provided!"
-$IF NOT EXIST '%in%' $ABORT "input GDX file '%in%' does not exist!"
-
-** option to run MACRO standalone or interactively linked (iterating) with MESSAGE **
-*$SETGLOBAL macromode "linked"
+* Run MACRO in stand-alone mode, without MESSAGE.
+* To run coupled with MESSAGE, use MESSAGE-MACRO_run.gms instead of this file.
 $SETGLOBAL macromode "standalone"
 
+$INCLUDE MACRO/setup.gms
 $INCLUDE MACRO/macro_data_load.gms
 $INCLUDE MACRO/macro_core.gms
 $INCLUDE MACRO/macro_calibration.gms
 $INCLUDE MACRO/macro_reporting.gms
 
 * dump all input data, processed data and results to a gdx file (with additional comment as name extension if provided)
-$IF NOT SET out      $SETGLOBAL out "output/MsgOutput.gdx"
 execute_unload "%out%"
-
diff --git a/message_ix/model/MESSAGE-MACRO_run.gms b/message_ix/model/MESSAGE-MACRO_run.gms
@@ -26,6 +26,9 @@ $INCLUDE includes/copyright.gms
 * (or ``model\output\MsgOutput.gdx`` if ``--out`` is not provided).
 ***
 
+* Run MESSAGE and MACRO in linked/iterative mode mode.
+* To run MACRO alone, use MACRO_run.gms instead of this file.
+* To run MESSAGE alone, use MESSAGE_run.gms or MESSAGE_master.gms instead of this file.
 $SETGLOBAL macromode "linked"
 $EOLCOM #
 $INCLUDE MESSAGE/model_setup.gms
@@ -34,6 +37,7 @@ $INCLUDE MESSAGE/model_setup.gms
 * load additional equations and parameters for MACRO                                                                   *
 *----------------------------------------------------------------------------------------------------------------------*
 
+$INCLUDE MACRO/setup.gms
 $INCLUDE MACRO/macro_data_load.gms
 $INCLUDE MACRO/macro_core.gms
 
diff --git a/message_ix/model/MESSAGE_master.gms b/message_ix/model/MESSAGE_master.gms
@@ -12,10 +12,12 @@ $ONGLOBAL
 ** scenario/case selection - this must match the name of the MsgData_<%%%>.gdx input data file **
 $SETGLOBAL data "<your datafile name here>"
 
-** MACRO mode
-* "none": MESSAGEix is run in stand-alone mode
-* "linked": MESSAGEix-MACRO is run in iterative mode **
-$SETGLOBAL macromode "none"
+* MACRO mode. This can take 3 possible values, only 2 of which are usable with this file:
+*
+* - "none": MACRO is not run, MESSAGE is run in stand-alone mode.
+* - "linked": MESSAGE and MACRO are run in linked/iterative mode.
+* - "standalone": MACRO is run without MESSAGE. Not valid when using this file; use MACRO_run.gms instead.
+$IF NOT SET macromode $SETGLOBAL macromode "none"
 
 ** define the time horizon over which the model optimizes (perfect foresight, myopic or rolling horizon) **
 * perfect foresight - 0
diff --git a/message_ix/models.py b/message_ix/models.py
@@ -1085,8 +1085,21 @@ def __init__(self, *args, **kwargs):
                 f"{self.name} requires GAMS >= {self.GAMS_min_version}; found {version}"
             )
 
+        # Additional command-line arguments to GAMS
+        solve_args = []
+        try:
+            concurrent = str(kwargs.pop("concurrent"))
+        except KeyError:
+            pass
+        else:
+            if concurrent not in ("0", "1"):
+                raise ValueError(f"{concurrent = }")
+            solve_args.append(f"--MACRO_CONCURRENT={concurrent}")
+
         super().__init__(*args, **kwargs)
 
+        self.solve_args.extend(solve_args)
+
     @classmethod
     def initialize(cls, scenario, with_data=False):
         """Initialize the model structure."""
diff --git a/message_ix/tests/test_macro.py b/message_ix/tests/test_macro.py
@@ -315,12 +315,29 @@ def test_calibrate(westeros_solved: Scenario, w_data_path: Path) -> None:
     assert not end_grow.isnull().any()
 
 
-def test_calibrate_roundtrip(westeros_solved: Scenario, w_data_path: Path) -> None:
+@pytest.mark.parametrize(
+    "kwargs",
+    (
+        {},  # Default concurrent=0
+        dict(concurrent=0),  # Explicit value, same as default
+        dict(concurrent=1),
+        pytest.param(
+            dict(concurrent=2),
+            marks=pytest.mark.xfail(raises=ValueError, reason="Invalid value"),
+        ),
+    ),
+)
+def test_calibrate_roundtrip(
+    westeros_solved: Scenario, w_data_path: Path, kwargs
+) -> None:
     """Ensure certain values occur after checking convergence.
 
     The specific values used here were re-checked in :pull:`924`.
     """
-    with_macro = westeros_solved.add_macro(w_data_path, check_convergence=True)
+    # this is a regression test with values observed on May 23, 2024
+    with_macro = westeros_solved.add_macro(
+        w_data_path, check_convergence=True, **kwargs
+    )
     npt.assert_allclose(
         with_macro.par("aeei")["value"].values,
         1e-3 * np.array([20.0, -7.5674349, 43.659505, 21.182828]),
