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
• Process Costing Tools

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})

Process Costing API

As part of the move to IDAES v2.0, a more flexible API for process costing has been deployed and the older API will be fully deprecated in v2.0.

An example of using the new tools can be found here.

How to migrate

Using a Costing Package

Below is an example of using the inbuilt example costing library (base on the textbook "Process and Product Design Principles: Synthesis, Analysis, and Evaluation" by Seider, Seader, Lewin, and Windagdo, 3rd Ed.) using the old and new APIs:

-m.fs.hx.get_costing(**kwargs)
+from idaes.models.costing.SSLW import SSLWCosting
+m.fs.costing = SSLWCosting()
+m.fs.hx.costing = UnitModelCostingBlock(
+    flowsheet_costing_block=m.fs.costing,
+    costing_method=SSLWCosting.cost_heat_exchanger,
+    costing_method_arguments=**kwargs)

The key differences are:

1. the need to import the desired costing package and explicitly declare the flowsheet level costing object,
2. the need to explicitly declare a UnitModelCostingBlock associated with the unit to be costed, and
3. the ability to explicitly define the costing method to use when costing the unit (which does not need to come from the same costing package as was used for the flowsheet costing object). Costing packages may implement a default mapping of unit operation types to costing methods, in which case this argument is optional.

Using Custom Costing Correlations

The new API supports custom costing correlations in a number of ways. Firstly, the costing_method argument above can be any user-defined method which implements the correlations for costing a piece of equipment. Thus, any existing custom costing correlations can be adapted to work in the new API with a minimum of effort.

For those looking to build custom costing packages, the inbuilt example can be used as a starting point. The key elements are:

• a build_global_params method which defines any global parameters that are required which corresponds to the previous global_costing_parameters function, and
• and a library of costing methods for different pieces of equipment as discussed above.