Merge branch 'nexus-upd' of https://github.com/iiasa/message-ix-models …

…into nexus-upd

.gitattributes

@@ -1,3 +1,6 @@
 # Reduce the number of merge conflicts
 doc/whatsnew.rst merge=union
+# Git LFS
+*.csv.gz filter=lfs diff=lfs merge=lfs -text
+*.xlsx filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text

.github/workflows/lint.yaml

@@ -17,12 +17,16 @@ jobs:
     with:
       # If the "Latest version testable on GitHub Actions" in pytest.yaml
       # is not the latest 3.x stable version, adjust here to match:
-      python-version: "3.10"
+      # python-version: "3.x"
+      # NB pint is normally implied by iam-units, but we force an earlier
+      #    version to work around https://github.com/hgrecco/pint/issues/1767
       type-hint-packages: >-
         genno
         iam-units
+        "pint < 0.21"
         pytest
         sdmx1
         types-PyYAML
+        types-tqdm
         "ixmp @ git+https://github.com/iiasa/ixmp.git@main"
         "message-ix @ git+https://github.com/iiasa/message_ix.git@main"

.github/workflows/pytest.yaml

@@ -22,15 +22,16 @@ jobs:
         # These should match the versions used in the "pytest" workflows of both
         # ixmp and message_ix.
         version:
-        - { os: macos-latest, python: "3.10" }
-        - { os: ubuntu-latest, python: "3.10" }
-        - { os: windows-latest, python: "3.10" }
+        - { os: macos-latest, python: "3.11" }
+        - { os: ubuntu-latest, python: "3.11" }
+        - { os: windows-latest, python: "3.11" }
         # Versions of both ixmp and message_ix to use
         upstream-version:
         # Temporarily disabled (iiasa/ixmp#477)
         # - v3.4.0  # Minimum version given in setup.cfg
         # - v3.5.0
-        # - v3.6.0  # Latest released version
+        # - v3.6.0
+        - v3.7.0  # Latest released version
         - main    # Development version
 
       fail-fast: false
@@ -39,6 +40,12 @@ jobs:
     name: ${{ matrix.version.os }}-py${{ matrix.version.python }}-upstream-${{ matrix.upstream-version }}
 
     steps:
+    - name: Cache test data
+      uses: actions/cache@v3
+      with:
+        path: message-local-data
+        key: ${{ matrix.version.os }}
+
     - name: Check out message-ix-models
       uses: actions/checkout@v3
       with:
@@ -62,12 +69,20 @@ jobs:
         pip install --upgrade "message-ix @ git+https://github.com/iiasa/message_ix.git@${{ matrix.upstream-version }}"
         pip install .[tests]
 
+    - name: Configure local data path
+      run: |
+        mkdir -p message-local-data/cache
+        mix-models config set "message local data" "$(realpath message-local-data)"
+        mix-models config show
+      shell: bash
+
     - name: Run test suite using pytest
       run: |
         pytest message_ix_models \
           -rA --verbose --color=yes --durations=20 \
           --cov-report=term-missing --cov-report=xml \
-          --numprocesses=auto
+          --numprocesses=auto \
+          --local-cache --jvmargs="-Xmx6G"
       shell: bash
 
     - name: Test documentation build using Sphinx

MANIFEST.in

@@ -0,0 +1 @@
+prune message_ix_models/data/test/MESSAGEix-GLOBIOM_1.1_R11_no-policy_baseline

doc/api/model-snapshot.rst

@@ -0,0 +1,35 @@
+.. currentmodule:: message_ix_models.model.snapshot
+
+Load MESSAGEix-GLOBIOM snapshots (:mod:`.model.snapshot`)
+*********************************************************
+
+This code allows to fetch *snapshots* containing completely parametrized MESSAGEix-GLOBIOM model instances, and load these into :class:`Scenarios <message_ix.Scenario>`.
+
+Usage
+=====
+
+From the command line, download data for a single snapshot::
+
+    $ mix-models snapshot fetch 0
+
+…where :program:`0` is the ID of a snapshot; see :data:`.SNAPSHOTS`.
+
+In code, use :func:`.snapshot.load`:
+
+.. code-block:: python
+
+    from message_ix import Scenario
+    from message_ix_models.model import snapshot
+
+    scenario = Scenario(...)
+
+    snapshot.load(scenario, 0)
+
+.. note:: For snapshot 0, contrary to the `description of the Zenodo item <https://10.5281/zenodo.5793870>`__, the file cannot be loaded using :meth:`.Scenario.read_excel`.
+   This limitation will be fixed in subsequent snapshots.
+
+Code reference
+==============
+
+.. automodule:: message_ix_models.model.snapshot
+   :members:

doc/api/util.rst

@@ -12,6 +12,8 @@ Submodules:
    context
    importlib
    _logging
+   node
+   pooch
    scenarioinfo
 
 Commonly used:
@@ -169,6 +171,15 @@ Commonly used:
    :members:
    :exclude-members: identify_nodes
 
+:mod:`.util.pooch`
+==================
+
+.. currentmodule:: message_ix_models.util.pooch
+
+.. automodule:: message_ix_models.util.pooch
+   :members:
+
+
 :mod:`.util.scenarioinfo`
 =========================
 

doc/conf.py

@@ -98,6 +98,7 @@ def setup(app: "sphinx.application.Sphinx") -> None:
         None,
     ),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "pooch": ("https://www.fatiando.org/pooch/latest/", None),
     "pytest": ("https://docs.pytest.org/en/stable/", None),
     "python": ("https://docs.python.org/3/", None),
     "sdmx": ("https://sdmx1.readthedocs.io/en/stable/", None),

doc/index.rst

@@ -32,6 +32,7 @@ Among other tasks, the tools allow modelers to:
    api/model-bare
    api/model-build
    api/model-emissions
+   api/model-snapshot
    api/disutility
    api/project
    api/tools

doc/water/index.rst

@@ -11,7 +11,7 @@ This work extends the water sector linkage described by Parkinson et al. (2019)
 CLI usage
 =========
 
-Use the :doc:`CLI <message_ix_models:cli>` command ``mix-data water`` to invoke the commands defined in :mod:`.water.cli`. Example:
+Use the :doc:`CLI </cli>` command ``mix-data water`` to invoke the commands defined in :mod:`.water.cli`. Example:
 ``mix-models --url=ixmp://ixmp_dev/ENGAGE_SSP2_v4.1.7/baseline_clone_test water cooling``
 model and scenario specifications can be either set manually in ``cli.py`` or specified in the ``--url`` option
 

doc/whatsnew.rst

@@ -1,8 +1,21 @@
 What's new
 **********
 
-.. Next release
-.. ============
+Next release
+============
+
+- Add code and CLI commands to :doc:`fetch and load MESSAGEix-GLOBIOM snapshots <api/model-snapshot>` (:pull:`102`).
+- Add :func:`.util.pooch.fetch`, a thin wrapper for using :doc:`Pooch <pooch:about>` (:pull:`102`).
+
+v2023.5.31
+==========
+
+- Adjust :mod:`sdmx` usage for version 2.10.0 (:pull:`101`).
+
+v2023.5.13
+==========
+
+- Adjust :func:`.generate_product` for pandas 2.0.0 (:pull:`98`).
 
 2023.4.2
 ========

message_ix_models/cli.py

@@ -18,6 +18,7 @@
 from pathlib import Path
 
 import click
+from ixmp.cli import main as ixmp_cli
 
 from message_ix_models.util._logging import mark_time
 from message_ix_models.util._logging import setup as setup_logging
@@ -101,11 +102,16 @@ def debug(ctx):
     log.debug(ctx.local_data)
 
 
+# Attach the ixmp "config" CLI
+main.add_command(ixmp_cli.commands["config"])
+
+
 #: List of submodules providing CLI (sub)commands accessible through `mix-models`.
 #: Each of these should contain a function named ``cli`` decorated with @click.command
 #: or @click.group.
 submodules = [
     "message_ix_models.model.cli",
+    "message_ix_models.model.snapshot",
     "message_ix_models.model.structure",
     "message_ix_models.model.water.cli",
 ]