idaes v2 migrate

How to migrate code to IDAES v2 API

This guide shows how to migrate IDAES client code developed using the IDAES v1 API so that it can be used with the IDAES v2 API.

List of v1 -> v2 API changes

Import Paths default Argument Heat Exchanger Naming

Import paths within the idaes package

The internal structure of the top-level idaes Python package has undergone significant changes in the v1 -> v2 transition, which resulted in changes to the IDAES import paths:

• In most cases, importable objects (subpackages/modules/classes/functions/...) available in v1 can still be imported from a different location (i.e. the import path has been modified)
• In other cases, the importable object does not have a direct equivalent in the v2 API (i.e. the import path has been removed)

IN most cases, a deprecation warning is available through the v1 compatibility tool which will direct users to the new location where appropriate. For a list of the import path changes, users can refer to the specifications defined here:

• Packages and modules (link)
• Classes and functions (link)

In the specifications, the v1 import paths are mapped to the corresponding v2 import path if a direct replacement is available; otherwise, they are be mapped to None, or the specification is defined using the without_direct_replacement method.

How to migrate

If the v1 import path has a direct replacement in v2, it is sufficient to modify the import paths from v1 to v2:

-from idaes.core.util import get_solver
+from idaes.core.solvers import get_solver

If the v1 import path has been removed, a non-direct alternative might still be available. If this is the case and the affected import path is not addressed in this guide, feel free to contact the IDAES team using one of the available support channels.

ProcessBlock init arguments

In IDAES v1, when creating instances of any class inheriting from ProcessBlock, options had to be supplied as a dictionary object passed to the default keyword argument (kwarg). In IDAES v2, the same options are are passed directly as keyword arguments.

How to migrate

If the dictionary passed to the default argument was defined inline as a dict literal (i.e. default={"key1": ..., "key2": ..., ...}), then the same key-value pairs should be passed directly as keyword arguments:

-pb = ProcessBlock(default={"dynamic": False})
+pb = ProcessBlock(dynamic=False)

If a pre-defined dictionary was used, the "dict unpacking" operator ** may be used:

my_opts = {"dynamic": False}
-pb = ProcessBlock(default=my_opts)
+pb = ProcessBlock(**my_opts)

HeatExchanger API

The HeatExchanger API has been streamlined in IDAES v2. The most notable differences with respect to the v1 API are:

• Instead of side_1 and side_2, the two sides of the heat exchanger are called hot_side and cold_side respectively
• Custom aliases for the two sides are specified as keyword argument (hot_side_name and cold_side_name resp.) when the HeatExchanger object is created
• Instead of inlet_1, outlet_1, inlet_2, outlet_2, the inlet and outlet for each side will be accessible as <side-name>_inlet and <side-name>_outlet resp., so if e.g. hx = HeatExchanger(hot_side_name="shell", cold_side_name="tube"), the following attributes will be set on the hx object:
  • shell_inlet
  • shell_outlet
  • tube_inlet
  • tube_outlet

How to migrate

For most cases, all that is required is to map the previous names for the sides of the heat exchanger and set the hot_side_name and cold_side_name attributes. This will allow you to continue to use the old names elsewhere in the flowsheet, including setting configuration arguments for each side of the heat exchanger. An example for a 0D heat exchanger is shown below:

-model.fs.heat_exchanger = HeatExchanger(default={
-    "delta_temperature_callback":delta_temperature_amtd_callback,
-    "shell":{"property_package": model.fs.properties},
-    "tube":{"property_package": model.fs.properties}})
+model.fs.heat_exchanger = HeatExchanger(
+    delta_temperature_callback=delta_temperature_amtd_callback,
+    hot_side_name="shell",
+    cold_side_name="tube",
+    shell={"property_package": model.fs.properties},
+    tube={"property_package": model.fs.properties})