-
Notifications
You must be signed in to change notification settings - Fork 228
idaes v1 compat
To facilitate the transition to IDAES v2, the IDAES v2 beta release series (2.0.0b2) 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.
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.
conda create --name idaes-v2-env python=3.10 --yes && conda activate idaes-v2-env
pip install idaes-pse --pre && idaes get-extensions --verbose
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.
First, ensure that the IDAES v2 environment has been activated. Then, run:
pip install https://github.com/IDAES/devtools@bwcompat
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.
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.
IDAES v2 introduced changes in the IDAES Python API that are not backward-compatible. This means that custom code developed using the IDAES v1 API will have to be modified (i.e. migrated to IDAES v2) 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 developers migrate their IDAES client code 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 to migrate code to v2.
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 developers migrate their IDAES code to 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 migrated to the v2 API to be used with current and future version of IDAES.
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 migrate 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
- Set up pre-commit
- Run pytest with coverage report
- Run Pylint locally
- Update the Pyomo version
- Install Pyomo from a local Git clone
- Set up GitHub authentication with GCM
- Handle warnings in pytest