Merge pull request #352 from iiasa/v3.0-prep

Clean up prior to v3.0.0

.appveyor.yml

@@ -1,5 +1,11 @@
-# Continuous integration procedure for AppVeyor
-# Based on https://github.com/rmcgibbo/python-appveyor-conda-example
+# Continuous integration configuration for AppVeyor
+
+branches:
+  # Do not build PR branches in the main repo; only maintenance branches and
+  # the merge results of PRs
+  only:
+  - master
+  - 2.0.x
 
 environment:
   matrix:

.travis.yml

@@ -1,10 +1,21 @@
+# Continuous integration configuration for Travis
+# NB use https://config.travis-ci.com/explore to validate changes
+
+branches:
+  # Do not build PR branches in the main repo; only maintenance branches and
+  # the merge results of PRs
+  only:
+  - master
+  - 2.0.x
+
 language: minimal
 
 env:
   global:
   - PYENV=py37
-  # Encrypted values for MESSAGE_IX_CI_USER, MESSAGE_IX_CI_PW
-  - secure: "YlqCqO3t4XZbSjP7FseXGU0PWKxCTD+1kBwgRsA829yphaK0UEgDoCHVn0JvE1VDtb4E58eO0Ulnpc0MWhUDGe9dX7o5lpSufKGD+GLl/X00hYpahu17krxphAnqIyATQnY1RzQaqPGThkcx5SVJal1LAqNy5TzsLkYoCq7p1H0G4QlK9WeItlF/FLhrN27Zbi6/d1XYxgEataSHLfm7fb/uQJPj35r/DRwdyhmoDEOmtvbOL4+OQdLfdB56d1YLs5AIK2mMt/DhAoZvrwqWiway+87vxUuY/YIRVtgeukxxEhlp982YC6IFZdz149TS5107fAJpiTEUX2mdjNuzOcBGh6MTMwGVRsBSBfFPsmt9QF5Smwq6KVf9uxm0Sgwz5ih828Tg18YH5iYJ84Y1jF8l7kJw7N1nFKBYoTVB5un9z0iY3Dnw6LQDzJCvNGmdd4Ct38/vTj73Ltcr5hSzcDeE9VQs99z8gM1FCb45MbSYjg00YgfCzypuG5LibTmay89YcTRMIQ9OliQRCJyOB8l19Z1HYMn33nX8BN6IocWKSkeJexV1iNSPt0GZEnBRAccb7iJd/KD/tUeQvVtFbwJ/qSiQOduUb/GMEvcldXQeqsAQRSMvCdadlU2aQGjQF2XQJGlPhQf744RnevrTPm4HeIpvqLTeVvgJiF3h7Pw="
+  # Encrypted values for MESSAGE_IX_CI_USER, MESSAGE_IX_CI_PW,
+  # MESSAGE_IX_GH_USER, MESSAGE_IX_GH_PW
+  - secure: "IiNG8HMAFIrkeXnVMocSbAtXKgJ7SrZ9VduuAtdftImyBovbs2whtII5rL7qBg47mibREvY0ylUglmc5eLweEbZJO1zOVvNb8urk+cN4aljw9OubAlkpines9R0alhE1M2cOx94JYrNLPJyvMC8s40dVgCJzOM2kyP+cuf8Sr0vCgCAmbtsHSp7f3pkbvR+U7nSrPSHa/LHGtbQ2XJnhd8vvGeAn0oiP2c/Y6yCRhwI+EZYvh0uFSTf4XH6v/vs1zS+2qmWDMe5CUxXgXPtkPQqBhTmQDlbZXcnyoBIWtrpNAP8lXYv6piddizCg+HGpGkmef2pAnFwekQ6tCuQGyyamLlj6nFkljXHn1lbMoFPbRuH4N1vgh8h95r3HUo/Nfxdsza/PEs5HCOA03dU7rE6+ZrV5o0NRGf6cw0lR2evAmPBvkR66soWf3798T5JuUZib3fJ7XlBnhYisKw4Kr+IA6CJTlLVGZ1yd8YcW0bgUt881/kzC5lLjZEN3Is6PL5pkQO9H8tBLKuT0E+X5k6rJlxmuCtQawrpz+0LkoRjXWczH3SY4X7QU1N1Z7SGybNgsJCtwxYinq6QV1vHy2yhJjZtfn3iXtdU7mVyfGtOa3ZVkTO0MDWeDS2FiELz1hMV3zUC5rTZTkV4wLA88Cdijx9fiaW6tirVKhvMSwnI="
 
 os:
 - linux

INSTALL.rst

@@ -1,85 +1,123 @@
 Installation
-============
+************
 
-Install GAMS
-------------
+.. contents::
+   :local:
+
+Install system dependencies
+===========================
+
+GAMS (required)
+---------------
 
 |MESSAGEix| requires `GAMS`_.
 
-1. Download the latest version of `GAMS`_ for your operating system; run the
-   installer.
+1. Download GAMS for your operating system; either the `latest version`_ or `version 29`_ (see note below).
 
-   .. note:: MESSAGE-MACRO requires GAMS 24.8.1 or later (see
-      :attr:`.MESSAGE_MACRO.GAMS_min_version`).
+2. Run the installer.
 
-2. Add GAMS to the ``PATH`` environment variable. This is **required** in order
-   for |MESSAGEix| to run the mathematical model core.
+3. Ensure that the ``PATH`` environment variable on your system includes the path to the GAMS program:
 
    - on Windows, in the GAMS installer…
 
-     - Check the box labeled “Use advanced installation mode.”
-     - Check the box labeled “Add GAMS directory to PATH environment variable”
-       on the Advanced Options page.
+      - Check the box labeled “Use advanced installation mode.”
+      - Check the box labeled “Add GAMS directory to PATH environment variable” on the Advanced Options page.
+
+   - on other platforms (macOS or Linux), add the following line to a file such as :file:`~/.bash_profile` (macOS), :file:`~/.bashrc`, or :file:`~/.profile`::
+
+       export PATH=$PATH:/path/to/gams-directory-with-gams-binary
+
+.. note::
+   MESSAGE-MACRO and MACRO require GAMS 24.8.1 or later (see :attr:`.MACRO.GAMS_min_version`)
+   The latest version is recommended.
+
+   GAMS is proprietary software and requires a license to solve optimization problems.
+   To run both the :mod:`message_ix` and :mod:`ixmp` tutorials and test suites, a “free demonstration” license is required; the free license is suitable for these small models.
+   Versions of GAMS up to `version 29`_ include such a license with the installer; since version 30, the free demo license is no longer included, but may be requested via the GAMS website.
+
+.. note::
+   If you only have a license for an older version of GAMS, install both the older and the latest versions.
+
 
-   - on macOS or Linux, add the following line to your ``.bash_profile`` (macOS)
-     or ``.bashrc`` (Linux)::
+Graphviz (optional)
+-------------------
+
+:meth:`.reporting.Reporter.visualize` uses `Graphviz`_, a program for graph visualization.
+Installing message_ix causes the python :mod:`graphviz` package to be installed.
+If you want to use :meth:`.visualize` or run the test suite, the Graphviz program itself must also be installed; otherwise it is **optional**.
+
+If you `Install MESSAGEix via Anaconda`_, Graphviz is installed automatically via `its conda-forge package`_.
+For other methods of installation, see the `Graphviz download page`_ for downloads and instructions for your system.
 
-          export PATH=$PATH:/path/to/gams-directory-with-gams-binary
 
 Install |MESSAGEix| via Anaconda
---------------------------------
+================================
 
-After installing GAMS, we recommend that new users install Anaconda, and then
-use it to install |MESSAGEix|. Advanced users may choose to install |MESSAGEix|
-from source code (next section).
+After installing GAMS, we recommend that new users install Anaconda, and then use it to install |MESSAGEix|.
+Advanced users may choose to install |MESSAGEix| from source code (next section).
 
-3. Install Python via `Anaconda`_. We recommend the latest version, i.e.,
-   Python 3.6+.
+4. Install Python via `Anaconda`_.
+   We recommend the latest version; currently Python 3.8.
 
-4. Open a command prompt. We recommend Windows users use the “Anaconda Prompt”
-   to avoid permissions issues when installing and using |MESSAGEix|. This
-   program is available in the Windows Start menu after installing Anaconda.
+5. Open a command prompt.
+   We recommend Windows users use the “Anaconda Prompt” to avoid permissions issues when installing and using |MESSAGEix|.
+   This program is available in the Windows Start menu after installing Anaconda.
 
-5. Install the ``message-ix`` package::
+6. Install the ``message-ix`` package::
 
     $ conda install -c conda-forge message-ix
 
+
 Install |MESSAGEix| from source
--------------------------------
+===============================
 
-3. Install :doc:`ixmp <ixmp:install>` from source.
+4. Install :doc:`ixmp <ixmp:install>` from source.
 
-4. (Optional) If you intend to contribute changes to |MESSAGEix|, first register
-   a Github account, and fork the `message_ix repository <https://github.com/iiasa/message_ix>`_. This will create a new repository ``<user>/message_ix``.
+5. (Optional) If you intend to contribute changes to |MESSAGEix|, first register a Github account, and fork the `message_ix repository <https://github.com/iiasa/message_ix>`_.
+   This will create a new repository ``<user>/message_ix``.
    (Please also see :doc:`contributing`.)
 
-5. Clone either the main repository, or your fork; using the `Github Desktop`_
-   client, or the command line::
+6. Clone either the main repository, or your fork; using the `Github Desktop`_ client, or the command line::
 
     $ git clone git@github.com:iiasa/message_ix.git
 
     # or:
     $ git clone git@github.com:USER/message_ix.git
 
-6. Open a command prompt in the ``message_ix`` directory and type::
+7. Open a command prompt in the ``message_ix`` directory and type::
+
+    $ pip install --editable .[docs,reporting,tests,tutorial]
+
+   The ``--editable`` flag ensures that changes to the source code are picked up every time ``import message_ix`` is used in Python code.
+   The ``[docs,reporting,tests,tutorial]`` extra dependencies ensure additional dependencies are installed.
+
+8. (Optional) If you will be using :file:`MESSAGE_master.gms` outside of Python :mod:`message_ix` to run |MESSAGEix|, you will likely modify this file, but will not want to commit these changes to Git.
+   Set the Git “assume unchanged” bit for this file::
+
+    $ git update-index --assume-unchanged message_ix/model/MESSAGE_master.gms
+
+   To unset the bit, use ``--no-assume-unchanged``.
+   See the `Git documentation <https://www.git-scm.com/docs/git-update-index#_using_assume_unchanged_bit>`_ for more details.
 
-    $ pip install --editable .
+9. (Optional) Run the built-in test suite to check that |MESSAGEix| functions correctly on your system::
 
-7. (Optional) Run the built-in test suite to check that |MESSAGEix| functions
-   correctly on your system::
+    $ pytest
 
-    $ pip install --editable .[tests]
-    $ py.test tests
 
 Common issues
--------------
+=============
 
 No JVM shared library file (jvm.dll) found
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
 
 If you get an error containing “No JVM shared library file (jvm.dll) found” when creating a :class:`Platform` object (e.g. ``mp = ix.Platform(driver='HSQLDB')``), it is likely that you need to set the ``JAVA_HOME`` environment variable (see for example `these instructions`_).
 
 .. _`GAMS`: http://www.gams.com
+.. _`latest version`: https://www.gams.com/download/
+.. _`version 29`: https://www.gams.com/29/
+.. _`Graphviz`: https://www.graphviz.org/
+.. _`its conda-forge package`: https://anaconda.org/conda-forge/graphviz
+.. _`Graphviz download page`: https://www.graphviz.org/download/
 .. _`Anaconda`: https://www.anaconda.com/distribution/#download-section
 .. _`ixmp`: https://github.com/iiasa/ixmp
 .. _`Github Desktop`: https://desktop.github.com

MANIFEST.in

@@ -0,0 +1,3 @@
+exclude .*
+prune .github
+prune ci

RELEASE_NOTES.rst

@@ -1,5 +1,7 @@
-Next release
-============
+v3.0.0 (2020-06-07)
+===================
+
+:mod:`message_ix` v3.0.0 coincides with :mod:`ixmp` v3.0.0.
 
 Migration notes
 ---------------
@@ -8,6 +10,10 @@ The :ref:`generic storage formulation <gams-storage>` introduces **new ixmp item
 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`.
 
+See also the `migration notes for ixmp 3.0.0`_.
+
+.. _migration notes for ixmp 3.0.0: https://message.iiasa.ac.at/projects/ixmp/en/latest/whatsnew.html#v3-0-0-2020-06-05
+
 
 All changes
 -----------
@@ -27,7 +33,7 @@ All changes
 v2.0.0 (2020-01-14)
 ===================
 
-`message_ix` v2.0.0 coincides with `ixmp` v2.0.0.
+:mod:`message_ix` v2.0.0 coincides with :mod:`ixmp` v2.0.0.
 
 Migration notes
 ---------------

ci/pip-requirements.txt

@@ -6,4 +6,4 @@ JPype1 >= 0.7.5
 
 # pyam-iamc
 # Temporary: see https://github.com/IAMconsortium/pyam/issues/259
-git+git://github.com/IAMconsortium/pyam.git#egg=pyam-iamc
+git+git://github.com/IAMconsortium/pyam.git@v0.6.0#egg=pyam-iamc

doc/source/api.rst

@@ -47,6 +47,7 @@ Support for R usage of the core classes is provided through the `reticulate`_ pa
 
 .. autoclass:: message_ix.Scenario
    :members:
+   :exclude-members: add_macro
    :show-inheritance:
    :inherited-members:
 
@@ -63,6 +64,7 @@ Support for R usage of the core classes is provided through the `reticulate`_ pa
 
       add_cat
       add_horizon
+      add_macro
       add_spatial_sets
       cat
       cat_list
@@ -76,6 +78,11 @@ Support for R usage of the core classes is provided through the `reticulate`_ pa
       vintage_and_active_years
       years_active
 
+   .. automethod:: add_macro
+
+      .. warning:: MACRO support via :meth:`add_macro` is **experimental** in message_ix 3.0 and may not function as expected on all possible |MESSAGEix| models.
+         See `a list of known and pending issues <https://github.com/iiasa/message_ix/issues?q=is%3Aissue+is%3Aopen+label%3Amacro>`_ on GitHub.
+
 
 Model classes
 -------------
@@ -131,7 +138,13 @@ Model classes
       **var_list**       :obj:`None`
       ================== ===
 
+
 .. autoclass:: MACRO
+   :members:
+   :show-inheritance:
+
+   .. autoattribute:: name
+
 
 .. autoclass:: MESSAGE_MACRO
    :members:
@@ -150,6 +163,8 @@ Model classes
    - **max_iteration** (:class:`int`, default 50): the maximum number of iterations between the two models.
      If the solution does not converge after this many iterations, the linked model run fails and no valid result is produced.
 
+   .. seealso:: :meth:`.Scenario.add_macro`
+
    .. autoattribute:: name
 
 .. autoclass:: GAMSModel