Record message_ix version in scenario data & GDX

.github/workflows/pytest.yaml

@@ -31,8 +31,8 @@ jobs:
         - "3.8"   # Earliest version supported by message_ix
         - "3.9"
         - "3.10"
-        - "3.11"  # Latest version supported by message_ix
-        # - "3.12"  # Pending JPype support; see iiasa/ixmp#501
+        - "3.11"
+        - "3.12"  # Latest version supported by message_ix
 
         # Below this comment are newly released or development versions of
         # Python. For these versions, binary wheels are not available for some
@@ -62,6 +62,72 @@ jobs:
         cache: pip
         cache-dependency-path: "**/pyproject.toml"
 
+    - uses: ts-graphviz/[email protected]
+      with:
+        macos-skip-brew-update: true
+
+    - name: Cache GAMS installer and R packages
+      uses: actions/cache@v3
+      with:
+        path: |
+          gams
+        key: ${{ matrix.os }}-gams${{ env.GAMS_VERSION }}
+        restore-keys: |
+          ${{ matrix.os }}-
+
+    - uses: iiasa/actions/setup-gams@main
+      with:
+        version: ${{ env.GAMS_VERSION }}
+        license: ${{ secrets.GAMS_LICENSE }}
+
+    - name: Install Python package and dependencies
+      # By default, the below installs ixmp from the main branch. To run against
+      # other code, e.g. other branches for open PRs), temporarily edit as
+      # appropriate. DO NOT merge such changes to `main`.
+      run: |
+        pip install --upgrade "ixmp @ git+https://github.com/iiasa/ixmp.git@main"
+        pip install .[tests]
+
+    - name: Run test suite using pytest
+      env:
+        # For test_cli.test_dl; see code in message_ix.cli.dl
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        pytest message_ix \
+          -m "not nightly and not tutorial" \
+          -rA --verbose --color=yes --durations=20 \
+          --cov-report=xml \
+          --numprocesses=auto --dist=loadgroup
+      shell: bash
+
+    - name: Upload test coverage to Codecov.io
+      uses: codecov/codecov-action@v3
+
+  tutorials:
+    strategy:
+      matrix:
+        os:
+        - macos-latest
+        - ubuntu-latest
+        - windows-latest
+
+      fail-fast: false
+
+    runs-on: ${{ matrix.os }}
+    name: ${{ matrix.os }} tutorials
+
+    steps:
+    - name: Check out message_ix
+      uses: actions/checkout@v3
+      with:
+        fetch-depth: ${{ env.depth }}
+
+    - uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+        cache: pip
+        cache-dependency-path: "**/pyproject.toml"
+
     - name: Set RETICULATE_PYTHON
       # Use the environment variable set by the setup-python action, above.
       run: echo "RETICULATE_PYTHON=$pythonLocation" >> $GITHUB_ENV
@@ -74,16 +140,16 @@ jobs:
     - uses: r-lib/actions/setup-r@v2
       id: setup-r
 
-    - name: Cache GAMS installer, Python packages, and R packages
+    - name: Cache GAMS installer and R packages
       uses: actions/cache@v3
       with:
         path: |
           gams
           ${{ env.R_LIBS_USER }}
-        key: ${{ matrix.os }}-gams${{ env.GAMS_VERSION }}-R${{ steps.setup-r.outputs.installed-r-version }}
+        key: tutorial-${{ matrix.os }}-gams${{ env.GAMS_VERSION }}-R${{ steps.setup-r.outputs.installed-r-version }}
         restore-keys: |
-          ${{ matrix.os }}-gams${{ env.GAMS_VERSION }}-
-          ${{ matrix.os }}-
+          tutorial-${{ matrix.os }}-gams${{ env.GAMS_VERSION }}-
+          tutorial-${{ matrix.os }}-
 
     - uses: iiasa/actions/setup-gams@main
       with:
@@ -110,16 +176,12 @@ jobs:
       shell: Rscript {0}
 
     - name: Run test suite using pytest
-      env:
-        # For test_cli.test_dl; see code in message_ix.cli.dl
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      # Work around iiasa/ixmp#411
       run: |
         pytest message_ix \
-          -m "not nightly" \
+          -m "tutorial" \
           -rA --verbose --color=yes --durations=20 \
           --cov-report=xml \
-          --numprocesses=auto --dist=loadgroup || ( [ $? -eq 127 -a "${{ runner.os }}" = "Windows" ] && echo "Spurious exit code 127 from pytest" && exit 0)
+          --numprocesses=auto --dist=loadgroup
       shell: bash
 
     - name: Upload test coverage to Codecov.io

README.md

@@ -46,7 +46,7 @@ Other forms of documentation:
 
 ## License
 
-Copyright © 2018–2023 IIASA Energy, Climate, and Environment (ECE) Program
+Copyright © 2018–2024 IIASA Energy, Climate, and Environment (ECE) Program
 
 The MESSAGEix framework is licensed under the Apache License, Version 2.0 (the "License"); you may not use the files in this repository except in compliance with the License. You may obtain a copy of the License in [`LICENSE`](LICENSE) or at <http://www.apache.org/licenses/LICENSE-2.0>.
 

RELEASE_NOTES.rst

@@ -5,18 +5,20 @@ Migration notes
 ---------------
 Update code that imports from the following modules:
 
-- :py:`message_ix.reporting` → use :py:`message_ix.report`.
-- :py:`message_ix.reporting.computations` → use :py:`message_ix.report.operator`.
+- :py:`message_ix.reporting` → use :mod:`message_ix.report`.
+- :py:`message_ix.reporting.computations` → use :mod:`message_ix.report.operator`.
 
 Code that imports from the old locations will continue to work, but will raise :class:`DeprecationWarning`.
 
 All changes
 -----------
 
-- Add the :doc:`LPdiag tool <tools/lpdiag>` to diagnose and analyze numerical issues in linear programming (LP) problems stored in MPS-format files (:pull:`704`).
-- Drop support for Python 3.7, which `reached end-of-life on 2023-06-27 <https://peps.python.org/pep-0537/#lifespan>`__ (:pull:`738`).
+- :mod:`message_ix` is tested and compatible with `Python 3.12 <https://www.python.org/downloads/release/python-3120/>`__ (:pull:`767`).
+  Support for Python 3.7, which `reached end-of-life on 2023-06-27 <https://peps.python.org/pep-0537/#lifespan>`__, is dropped (:pull:`738`).
   :mod:`message_ix` now requires Python version 3.8 or greater.
 - Rename :mod:`message_ix.report` (:pull:`761`).
+- Add the :doc:`LPdiag tool <tools/lp_diag>` to diagnose and analyze numerical issues in linear programming (LP) problems stored in MPS-format files (:pull:`704`).
+- GDX files generated by :class:`.GAMSModel` (thus :class:`.MESSAGE`, :class:`.MACRO`, and :class:`.MESSAGE_MACRO`) will contain an ``ixmp_version`` set with information on the versions of :mod:`ixmp` and :mod:`message_ix` that generated the file (:issue:`747`, :pull:`767`).
 - New reporting operator :func:`.model_periods` and automatic keys ``y::model`` and ``y0`` (:pull:`738`).
 - Improve readability of LaTeX equations in docs (:pull:`721`).
 - Replace :py:`MESSAGE_ITEMS` and :py:`MACRO_ITEMS` with :attr:`.MESSAGE.items` and :attr:`.MACRO.items`, respectively (:pull:`761`).

doc/api.rst

@@ -139,6 +139,9 @@ Model classes
       # Model options are read from configuration file
       scen.solve()
 
+   GDX input and output files generated using this class will contain a 2-dimensional set named ``ixmp_version``, wherein the first element of each member is a package name from the :py:`record_version_packages` parameter, and the second is its version according to :func:`importlib.metadata.version`.
+   If the package is not installed, the string "(not installed)" is stored.
+
    The following tables list all model options:
 
    .. list-table:: Options in :class:`message_ix.models.GAMSModel` or overridden from :mod:`ixmp`
@@ -153,16 +156,16 @@ Model classes
         - See above.
       * - **model_file**
         - Path to GAMS source file.
-        - ``'{model_dir}/{model_name}_run.gms'``
+        - :py:`"{model_dir}/{model_name}_run.gms"`
       * - **in_file**
         - Path to write GDX input file.
-        - ``'{model_dir}/data/MsgData_{case}.gdx'``
+        - :py:`"{model_dir}/data/MsgData_{case}.gdx"`
       * - **out_file**
         - Path to read GDX output file.
-        - ``'{model_dir}/output/MsgOutput_{case}.gdx'``
+        - :py:`"{model_dir}/output/MsgOutput_{case}.gdx"`
       * - **solve_args**
         - Arguments passed directly to GAMS.
-        - .. code-block::
+        - .. code-block:: python
 
              [
                  '--in="{in_file}"',
@@ -172,6 +175,9 @@ Model classes
       * - **solve_options**
         - Options for the GAMS LP solver.
         - :data:`.DEFAULT_CPLEX_OPTIONS`
+      * - **record_version_packages**
+        - Python package versions to record.
+        - :py:`["message_ix", "ixmp"]`
 
    .. list-table:: Option defaults inherited from :class:`ixmp.model.gams.GAMSModel`
       :widths: 20 80
@@ -180,9 +186,9 @@ Model classes
       * - Option
         - Default value
       * - **case**
-        - ``'{scenario.model}_{scenario.scenario}'``
+        - :py:`"{scenario.model}_{scenario.scenario}"`
       * - **gams_args**
-        - ``['LogOption=4']``
+        - :py:`["LogOption=4"]`
       * - **check_solution**
         - :obj:`True`
       * - **comment**

doc/conf.py

@@ -15,7 +15,7 @@
 # -- Project information ---------------------------------------------------------------
 
 project = "MESSAGEix"
-copyright = "2018–2023, IIASA Energy, Climate, and Environment (ECE) Program"
+copyright = "2018–2024, IIASA Energy, Climate, and Environment (ECE) Program"
 author = "MESSAGEix Developers"
 
 # The major project version, used as the replacement for |version|.
@@ -159,6 +159,7 @@ def local_inv(name: str, *parts: str) -> Optional[str]:
     "message_doc": ("https://docs.messageix.org/projects/global/en/latest/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "pint": ("https://pint.readthedocs.io/en/stable/", None),
+    "plotnine": ("https://plotnine.readthedocs.io/en/stable", None),
     "pyam": ("https://pyam-iamc.readthedocs.io/en/stable/", None),
     "python": ("https://docs.python.org/3/", None),
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),

message_ix/macro.py

@@ -639,7 +639,7 @@ def calibrate(s, check_convergence: bool = True, **kwargs):
 
     # Test to make sure number of iterations is 1
     if check_convergence:
-        test = s.clone(s.model, "test to confirm MACRO converges")
+        test = s.clone(scenario=f"{s.scenario} test to confirm MACRO converges")
         kwargs.setdefault("gams_args", gams_args)
         test.solve(model="MESSAGE-MACRO", var_list=["N_ITER"], **kwargs)
         test.set_as_default()

message_ix/model/MESSAGE/data_load.gms

@@ -20,6 +20,12 @@ $LOAD balance_equality, time_relative
 $LOAD shares
 $LOAD addon, type_addon, cat_addon, map_tec_addon
 $LOAD storage_tec, level_storage, map_tec_storage
+
+* Version information; conditional load to allow older GDX files
+$ifthen gdxSetType ixmp_version
+$load ixmp_version
+$endif
+
 $GDXIN
 
 Execute_load '%in%'

message_ix/model/MESSAGE/sets_maps_def.gms

@@ -486,3 +486,5 @@ Sets
     is_fixed_activity(node,tec,vintage,year_all,mode,time) flag whether activity variable is fixed
     is_fixed_land(node,land_scenario,year_all)             flag whether land level is fixed
 ;
+
+Set ixmp_version(*,*) "Versions of Python packages used to generate this model";

message_ix/models.py

@@ -70,7 +70,7 @@ class Item:
     name: str
 
     #: Type of the item, for instance :attr:`ItemType.PAR <ixmp.backend.ItemType.PAR>`.
-    type: ItemType
+    type: "ixmp.backend.ItemType"
 
     #: String expression for :attr:`coords` and :attr:`dims`. Split on spaces and parsed
     #: using :data:`DIMS` so that, for instance, "nl yv" results in entries for
@@ -167,6 +167,8 @@ class GAMSModel(ixmp.model.gams.GAMSModel):
             # Disable the feature to put input/output GDX files, list files, etc. in a
             # temporary directory
             "use_temp_dir": False,
+            # Record versions of message_ix and ixmp in GDX I/O files
+            "record_version_packages": ("message_ix", "ixmp"),
         },
         ixmp.model.gams.GAMSModel.defaults,
     )

message_ix/report/__init__.py

@@ -203,7 +203,7 @@ def from_scenario(cls, scenario, **kwargs) -> "Reporter":
 
         Returns
         -------
-        message_ix.Reporter
+        .Reporter
             A reporter for `scenario`.
         """
         solved = scenario.has_solution()

message_ix/testing/__init__.py

@@ -1,13 +1,17 @@
 import io
 from itertools import product
-from typing import List, Union
+from typing import TYPE_CHECKING, List, Optional, Union
 
 import numpy as np
 import pandas as pd
 from ixmp import IAMC_IDX
 
 from message_ix import Scenario, make_df
 
+if TYPE_CHECKING:
+    import pytest
+
+
 SCENARIO = {
     "austria": dict(model="Austrian energy model", scenario="baseline"),
     "dantzig": {"model": "Canning problem (MESSAGE scheme)", "scenario": "standard"},
@@ -426,7 +430,13 @@ def make_dantzig(mp, solve=False, multi_year=False, **solve_opts):
 
 
 def make_westeros(
-    mp, emissions=False, solve=False, quiet=True, model_horizon=[700, 710, 720]
+    mp,
+    emissions=False,
+    solve=False,
+    quiet=True,
+    model_horizon=[700, 710, 720],
+    *,
+    request: Optional["pytest.FixtureRequest"] = None,
 ):
     """Return an :class:`message_ix.Scenario` for the Westeros model.
 
@@ -443,7 +453,15 @@ def make_westeros(
     """
     mp.add_unit("USD/kW")
     mp.add_unit("tCO2/kWa")
-    scen = Scenario(mp, version="new", **SCENARIO["westeros"])
+
+    # Scenario identifiers
+    args = SCENARIO["westeros"].copy()
+    args.setdefault("version", "new")
+    if request:
+        # Use a distinct scenario name for a particular test
+        args.update(scenario=request.node.name)
+
+    scen = Scenario(mp, **args)
 
     # Sets
     history = [690]

message_ix/tests/conftest.py

@@ -62,8 +62,10 @@ def ureg():
 
 
 @pytest.fixture
-def dantzig_reporter(message_test_mp, ureg):
-    scen = message_ix.Scenario(message_test_mp, **SCENARIO["dantzig"])
+def dantzig_reporter(request, message_test_mp, ureg):
+    scen = message_ix.Scenario(message_test_mp, **SCENARIO["dantzig"]).clone(
+        scenario=request.node.name
+    )
 
     if not scen.has_solution():
         scen.solve(quiet=True)

message_ix/tests/data/report-pyam-write.csv

@@ -1,9 +1,9 @@
 Model,Scenario,Region,Variable,Unit,1963
-Canning problem (MESSAGE scheme),standard,san-diego,Activity|canning_plant|production,,600.0
-Canning problem (MESSAGE scheme),standard,san-diego,Activity|transport_from_san-diego|to_chicago,,0.0
-Canning problem (MESSAGE scheme),standard,san-diego,Activity|transport_from_san-diego|to_new-york,,325.0
-Canning problem (MESSAGE scheme),standard,san-diego,Activity|transport_from_san-diego|to_topeka,,275.0
-Canning problem (MESSAGE scheme),standard,seattle,Activity|canning_plant|production,,350.0
-Canning problem (MESSAGE scheme),standard,seattle,Activity|transport_from_seattle|to_chicago,,300.0
-Canning problem (MESSAGE scheme),standard,seattle,Activity|transport_from_seattle|to_new-york,,0.0
-Canning problem (MESSAGE scheme),standard,seattle,Activity|transport_from_seattle|to_topeka,,0.0
+Canning problem (MESSAGE scheme),test_reporter_as_pyam,san-diego,Activity|canning_plant|production,,600.0
+Canning problem (MESSAGE scheme),test_reporter_as_pyam,san-diego,Activity|transport_from_san-diego|to_chicago,,0.0
+Canning problem (MESSAGE scheme),test_reporter_as_pyam,san-diego,Activity|transport_from_san-diego|to_new-york,,325.0
+Canning problem (MESSAGE scheme),test_reporter_as_pyam,san-diego,Activity|transport_from_san-diego|to_topeka,,275.0
+Canning problem (MESSAGE scheme),test_reporter_as_pyam,seattle,Activity|canning_plant|production,,350.0
+Canning problem (MESSAGE scheme),test_reporter_as_pyam,seattle,Activity|transport_from_seattle|to_chicago,,300.0
+Canning problem (MESSAGE scheme),test_reporter_as_pyam,seattle,Activity|transport_from_seattle|to_new-york,,0.0
+Canning problem (MESSAGE scheme),test_reporter_as_pyam,seattle,Activity|transport_from_seattle|to_topeka,,0.0

message_ix/tests/test_cli.py

@@ -8,7 +8,13 @@
 from message_ix import config
 
 
-def test_copy_model(message_ix_cli, tmp_path, tmp_env):
+def test_copy_model(monkeypatch, message_ix_cli, tmp_path, tmp_env):
+    # Use Pytest monkeypatch fixture; this ensures the original value is restored at the
+    # end of the test
+    monkeypatch.setattr(
+        config.values, "message_model_dir", config.get("message model dir")
+    )
+
     r = message_ix_cli("copy-model", str(tmp_path))
     assert r.exit_code == 0