idaes v1 compat

IDAES v1 compatibility mode for IDAES v2

To facilitate the transition to IDAES v2, THIS_RELEASE includes support for the IDAES v1 compatibility mode: a separate set of tools that, when activated, allows custom code using the IDAES v1 API to run with fewer or no errors and/or more informative messages.

Frequently Asked Questions

I have custom code developed using IDAES v1. Will it still work with IDAES v2?

IDAES v2 introduced changes in the IDAES Python API that are not backward-compatible. This means that, if a custom model was developed using the IDAES v1 API, its source code will have to be modified for the model to work with current and future releases of the IDAES platform.

More concretely, it should be assumed that running unmodified IDAES v1 code in a Python environment where idaes-pse>1 will fail.

I have custom code developed with IDAES v1. How is the IDAES v1 compatibility mode supposed to help me use the code with IDAES v2?

The primary goal of the IDAES v1 compatibility mode is to help custom model developers perform the necessary modifications to make their models compatible with the IDAES v2 API.

This is implemented in multiple ways, including:

• When attempting to import an IDAES module/class/function using an outdated import path, a deprecation message is emitted, specifying the new import path (if the module/function/class has been relocated), and/or alerting that the module/function/class has been removed without a direct replacement
• When outdated APIs are used at runtime (instatiating objects or calling functions/methods with outdated arguments, etc), Python exceptions (e.g. TypeError, KeyError, ValueError, etc) are supplemented with or replaced by a more informative message with pointers to the correct usage

Refer to the How-to section in this document for a step-by-step example on how to use the IDAES v1 compatibility mode.

I have custom code developed with IDAES v1. Can I use the IDAES v1 compatibility mode to keep running my code with an IDAES v2 release without modifications?

The purpose of the IDAES v1 compatibility mode is to help model developers to make their models compatible with the IDAES v2 API.

As many of the IDAES v2 changes could not be implemented in a way that allowed backward compatibility, activating the IDAES v1 compatibility mode does not enable IDAES v1 code to run unmodified with an IDAES v2 release. Code developed with the IDAES v1 API will still need to be adapted to be used with IDAES v2.

My code already works with IDAES v2. How does the IDAES v1 compatibility in this release affect me?

The IDAES v1 compatibility available in this release is entirely opt-in and requires two separate steps to be activated. Unless those optional steps are performed, this release is solely and completely compatible with the IDAES v2 API. Note that the code might still be affected by changes introduced in this release that are unrelated to the v1 -> v2 API transition.

I have custom code developed using IDAES v1, but I'm unwilling/unable to adapt it to IDAES v2. What are my options?

The latest available release using the IDAES v1 API is 1.13.0. Barring unforeseen circumstances, the source code for this version will continue to be available on GitHub and PyPI.

However, the IDAES v1 series is entirely unsupported and no further updates are planned. Among other things, this means that:

• Installing and/or running the idaes-pse==1.* Python package might start failing at any time because to e.g. breaking changes in third-party dependencies. One way to (partially) address this is to create a complete snapshot of the environment where the code using IDAES v1 is known to be working, using e.g. container or VM images
• Due to limited resources, we will be unable to provide support for any question or support request related to continued use of IDAES v1

How-to: Using IDAES v1 compatibility mode to adapt custom code to IDAES v2

For the sake of example, the following instructions assume a Python script named my_idaes_code.py containing the custom code using the IDAES v1 API.

Step 0: creating and/or activating IDAES v2 environment

conda create --name idaes-v2-env python=3.10 --yes && conda activate idaes-v2-env
pip install idaes-pse==THIS_VERSION

As a test, try running the code in my_idaes_code.py in this environment. In all likelihood, the execution will fail upon encountering a generic Python exception such as ModuleNotFoundError, TypeError, AttributeError etc.

Step 1: installing compatibility package

First, ensure that the IDAES v2 environment has been activated. Then, run:

pip install https://github.com/IDAES/devtools@bwcompat

Step 2: activating IDAES v1 compatibility at runtime

Open my_idaes_code.py and add the following line at the top of the file. The line MUST be placed before any idaes module is imported.

from _idaes_v1_compat import activate; activate()
# the rest of my_models.py

After this, when my_idaes_code.py is run, a message should confirm that the IDAES v1 compatibility has been activated. After that, a number of deprecation warnings and other messages should be shown.

The execution might still fail overall, but the IDAES v1 compatibility mode allows multiple errors to be displayed within a single run (along with more informative messages), which significantly speeds up the IDAES v2 conversion workflow.

Step 3: adapting the code to IDAES v2

Using the messages shown, apply the necessary modifications to the code in my_idaes_code.py.

To test whether the code is compatible with the IDAES v2 API, comment or remove the from _idaes_v1_compat import ... line before running the code again. If errors still occur, repeat the process starting at Step 2.