What’s New

Next release

  • ixmp is tested and compatible with Python 3.13 (PR #544).

  • Support for Python 3.8 is dropped (PR #544), as it has reached end-of-life.

  • ixmp locates GAMS API libraries needed for the Java code underlying JDBCBackend based on the system GAMS installation (PR #532). As a result:

    • JDBCBackend is usable on MacOS with newer, arm64-architecture processors and Python/GAMS compiled for arm64 (#473, #531).

    • GAMS API libraries are no longer (re-)packaged with ixmp in the directory ixmp/backend/jdbc/.

v3.9.0 (2024-06-04)

All changes

  • Increase minimum required version of genno dependency to 1.20 (PR #514).

  • To aid debugging when execution fails, GAMSModel also displays the path to the GAMS log file (PR #513).

v3.8.0 (2024-01-12)

Migration notes

Update code that imports from the following modules:

Code that imports from the old locations will continue to work, but will raise DeprecationWarning.

All changes

  • ixmp is tested and compatible with Python 3.12 (PR #504).

  • Support for Python 3.7 is dropped (PR #492), as it has reached end-of-life.

  • Rename ixmp.report and ixmp.util (PR #500).

  • New option record_version_packages to GAMSModel (PR #502). Versions of the named Python packages are recorded in a special set in GDX-format input and output files to help associate these files with generating code.

  • New reporting operators from_url(), get_ts(), and remove_ts() (PR #500).

  • New CLI command ixmp platform copy and CLI documentation (PR #500).

  • New argument indexed_by=... to Scenario.items() (thus Scenario.par_list() and similar methods) to iterate over (or list) only items that are indexed by a particular set (#402, PR #500).

  • New util.discard_on_error() and matching argument to TimeSeries.transact() to avoid locking TimeSeries / Scenario on failed operations with JDBCBackend (PR #488).

  • Work around limitations of JDBCBackend (PR #500):

    • Unit "" cannot be added with the Oracle driver (#425).

    • Certain items (variables) could not be initialized when providing idx_sets=..., even if those match the sets fixed by the underlying Java code. With this fix, a matching list is silently accepted; a different list raises NotImplementedError.

    • When a GAMSModel is solved with an LP status of 5 (optimal, but with infeasibilities after unscaling), JDBCBackend would attempt to read the output GDX file and fail, leading to an uninformative error message (#98). Now ModelError is raised describing the situation.

  • Improved type hinting for static typing of code that uses ixmp (#465, PR #500).

  • ixmp requires JPype1 1.4.0 or earlier, for Python 3.10 and earlier (PR #504). With JPype1 1.4.1 and later, memory management in CachingBackend may not function as intended (#463), which could lead to high memory use where many, large Scenario objects are created and used in a single Python program. (For Python 3.11 and later, any version of JPype1 from the prior minimum (1.2.1) to the latest is supported.)

v3.7.0 (2023-05-17)

All changes

v3.6.0 (2022-08-17)

All changes

  • Optionally tolerate failures to add individual items in store_ts() reporting computation (PR #451); use timeseries_only=True in check-out to function with Scenario with solution data stored.

  • Bugfix: Config squashed configuration values read from config.json, if the respective keys were registered in downstream packages, e.g. message_ix. Allow the values loaded from file to persist (PR #451).

  • Adjust to genno 1.12 and set this as the minimum required version for ixmp.reporting (PR #451).

  • Add enforce() to the Model API for enforcing structure/data consistency before Model.run() (PR #450).

v3.5.0 (2022-05-06)

All changes

  • Add new logo and diagram to the documentation (PR #446).

  • Raise an informative ValueError when adding infinite values with add_timeseries(); this is unsupported on JDBCBackend when connected to an Oracle database (PR #443, #442).

  • New attribute url for convenience in constructing TimeSeries/Scenario URLS (PR #444).

  • New store_ts() reporting computation for storing time-series data on a TimeSeries/Scenario (PR #444).

  • Improve performance in add_par() (PR #441).

  • Minimum requirements are increased for dependencies (PR #435):

    • Python 3.7 or greater. Python 3.6 reached end-of-life on 2021-12-31.

    • Pandas 1.2 (2020-12-26) or greater, the oldest version with a minimum Python version of 3.7.

  • Improvements to configuration (PR #435):

  • Security: upgrade Log4j to 2.17.1 in Java code underlying JDBCBackend to address CVE-2021-44228, a.k.a. “Log4Shell” (PR #445).

    The ixmp Python package is not network-facing per se (unless exposed as such by user code; we are not aware of any such applications), so remote code execution attacks are not a significant concern. However, users should still avoid running unknown or untrusted code provided by third parties with versions of ixmp prior to 3.5.0, as such code could be deliberately crafted to exploit the vulnerability.

v3.4.0 (2022-01-24)

Migration notes

ixmp.util.isscalar() is deprecated. Code should use numpy.isscalar().

All changes

v3.3.0 (2021-05-28)

Migration notes

rixmp is deprecated, though not yet removed, as newer versions of the R reticulate package allow direct import and use of the Python modules with full functionality. See the updated page for Usage in R via reticulate.

All changes

v3.2.0 (2021-01-24)

All changes

  • Increase JPype minimum version to 1.2.1 (PR #394).

  • Adjust test suite for pandas v1.2.0 (PR #391).

  • Raise clearer exceptions from add_par() for incorrect parameters; silently handle empty data (PR #374).

  • Depend on openpyxl instead of xlrd and xlsxwriter for Excel I/O; xlrd versions 2.0.0 and later do not support .xlsx (PR #389).

  • Add a parameter for exporting all model+scenario run versions to Platform.export_timeseries_data(), and fix a bug where exporting all runs happens uninteneded (PR #367).

  • Silence noisy output from ignored exceptions on JDBCBackend/JVM shutdown (PR #378).

  • Add a utility method, gams_version(), to check the installed version of GAMS (PR #376). The result is displayed by the ixmp show-versions CLI command/show_versions().

  • init_par() and related methods accept any sequence (not merely list) of str for the idx_sets and idx_names arguments (PR #376).

v3.1.0 (2020-08-28)

All changes

ixmp v3.1.0 coincides with message_ix v3.1.0.

v3.0.0 (2020-06-05)

ixmp v3.0.0 coincides with message_ix v3.0.0.

Migration notes

Excel input/output (I/O)

The file format used by Scenario.to_excel() and read_excel() is now fully specified; see File formats and input/output.

ixmp writes and reads items with more elements than the ~10⁶ row maximum of the Excel data format, by splitting these across multiple sheets.

The I/O code now explicitly checks for situations where the index sets and names for an item are ambiguous; see this example for how to initialize and read these items.

Updated dependencies

The minimum versions of the following dependencies are increased:

  • JPype1 0.7.5

  • pandas 1.0

  • dask 2.14 (for reporting)

Deprecations and deprecation policy

The following items, marked as deprecated in ixmp 2.0, are removed (PR #254):

  • $HOME/.local/ixmp/ as a configuration location. Configuration files are now placed in the standard $HOME/.local/share/ixmp/.

  • positional and dbtype= arguments to Platform/JDBCBackend.

  • first_model_year=, keep_sol=, and scen= arguments to clone(). Use shift_first_model_year, keep_solution, and scenario, respectively.

  • rixmp.legacy, an earlier version of the R interface that did not use reticulate.

Newly deprecated is:

  • cache keyword argument to Scenario. Caching is controlled at the Platform/Backend level, using the same keyword argument.

Starting with ixmp v3.0, arguments and other features marked as deprecated will follow a standard deprecation policy: they will be removed no sooner than the second major release following the release in which they are marked deprecated. For instance, a feature marked deprecated in ixmp version “10.5” would be retained in ixmp versions “11.x”, and removed only in version “12.0” or later.

All changes

v2.0.0 (2020-01-14)

ixmp v2.0.0 coincides with message_ix v2.0.0.

Migration notes

Support for Python 2.7 is dropped as it has reached end-of-life, meaning no further releases will be made even to fix bugs. See PEP-0373 and https://python3statement.org. ixmp users must upgrade to Python 3.

Configuration for ixmp and its storage backends has been streamlined. See the ref:Configuration section of the documentation for complete details on how to use ixmp platform add register local and remote databases. To migrate from pre-2.0 settings:

DB_CONFIG_PATH

…pointed to a directory containing database properties (.properties) files.

  • All Platform configuration is stored in one ixmp configuration file, config.json, and manipulated using the ixmp platform command and subcommands.

  • The Platform constructor accepts the name of a stored platform configuration.

  • Different storage backends may accept relative or absolute paths to backend-specific configuration files.

DEFAULT_DBPROPS_FILE

…gave a default backend via a file path.

  • On the command line, use ixmp platform add default NAME to set NAME as the default platform.

  • This platform is loaded when ixmp.Platform() is called without any arguments.

DEFAULT_LOCAL_DB_PATH

…pointed to a default local database.

  • ixmp.config always contains a platform named ‘local’ that is located below the configuration path, in the directory ‘localdb/default’.

  • To change the location for this platform, use e.g.: ixmp platform add local jdbc hsqldb PATH.

All changes

v0.2.0 (2019-06-25)

ixmp 0.2.0 provides full support for clone() across platforms (database instances), e.g. from a remote database to a local HSQL database. IAMC-style timeseries data is better supported, and can be used to store processed results, together with model variables and equations.

Other improvements include a new, dedicated ixmp.testing module, and user-supplied callbacks in solve(). The retixmp package using reticulate to access the ixmp API is renamed to rixmp and now has its own unit tests (the former rixmp package can be accessed as rixmp.legacy).

Release 0.2.0 coincides with MESSAGEix release 1.2.0.

All changes

  • Test rixmp (former retixmp) using the R testthat package (PR #135).

  • Cloning across platforms, better support of IAMC_style timeseries data, preparations for MESSAGEix release 1.2 in Java core (PR #142).

  • Support iterating with user-supplied callbacks (PR #115).

  • Recognize IXMP_DATA environment variable for configuration and local databases (PR #130).

  • Fully implement clone() across platforms (databases) (PR #129, PR #132).

  • New module ixmp.testing for reuse of testing utilities (PR #128, PR #137).

  • Add functions to view and add regions for IAMC-style timeseries data (PR #125).

  • Return absolute path from find_dbprops() (PR #123).

  • Switch to RTD Sphinx theme (PR #118).

  • Bugfix and extend functionality for working with IAMC-style timeseries data (PR #116).

  • Add functions to check if a Scenario has an item (set, par, var, equ) (PR #111).

  • Generalize the internal functions to format index dimensions for mapping sets and parameters (PR #110).

  • Improve documentation (PR #108).

  • Replace deprecated pandas .ix indexer with .iloc (PR #105).

  • Specify dependencies in setup.py (PR #103).

v0.1.3 (2018-11-21)

  • Connecting to multiple databases, updating MESSAGE-scheme scenario specifications to version 1.1 (PR #88).

  • Can now set logging level which is harmonized between Java and Python (PR #80).

  • Adding a deprecated-warning for ixmp.Scenario with scheme==’MESSAGE’ (PR #79).

  • Changing the API from mp.Scenario(...) to ixmp.Scenario(mp, ...) (PR #76).

  • Adding a function has_solution(), rename kwargs to …_solution (PR #73).

  • Bring retixmp available to other users (PR #69).

  • Support writing multiple sheets to Excel in utils.pd_write (PR #64).

  • Now able to connect to multiple databases (Platforms) (PR #61).

  • Add MacOSX support in CI (PR #58).

  • Add ability to load all scenario data into memory for fast subsequent computation (PR #52).