Idaes-pse

New Features: DiagnosticsToolbox

DiagnosticsToolbox (`idaes.core.util.model_diagnostics.DiagnosticsToolbox` is a new self-guiding toolbox for assisting with diagnosing modeling issues. The toolbox contains a wide range of tools for identifying common modeling issues and conveying these to the user, and more features will be added in the coming months.

To try the new toolbox, use the following steps:

- `from idaes.core.util import DiagnosticsToolbox`
- Build an instance of your model
- Ensure your models has zero degrees of freedom (as best you can)
- `dt = DiagnostisticsToobox(model)`
- `dt.report_strucutral_issues()`
- Follow the prompts

Deprecations

- DegeneracyHunter is being deprecated in favor of the new DiagnosticsToolbox. The features and capabilities of DegeneracyHunter will be moved over to the DiagnositcsToolbox in the coming months.
- Removal of usage of Pyomo's `expr.current` due to deprecation upstream.
- Removed support for radial basis functions in ALAMOpy as these did not work in the current implementation. Those wishing to use radial basis functions should use Pysmo instead.

New Capabilities

- MSContactor model for unit operations involving mass transfer between 2 or more streams, such as membrane, solvent extraction and solids leaching operations.

Other Improvements

- Improved formulation for solubility products with additional parameters for better scaling of terms
- Better backward compatibility, verification and robustness testing of core models and APIs
- Added support for Separator models without energy balances

New IDAES Examples Repository

Starting with this release, the IDAES examples are developed in the new [IDAES/examples](https://github.com/IDAES/examples) repository.

Along with many content and usability improvements, the most significant changes are:

- To install the examples, after installing IDAES, run `pip install idaes-examples`
- The `idaes get-examples` command, previously used for this, has been removed
- The HTML version is now available at https://idaes-examples.readthedocs.io
- The previous URL, https://idaes.github.io/examples-pse, will not be updated and may be removed at some point in the future

For more details, refer to the resources available at [IDAES/examples](https://github.com/IDAES/examples).

Removal of Non-Functional Apps

A review of the code in the idaes/apps and idaes/models_extra folders was undertaken, and a number of tools were identified as being outdated or non-functional and no longer supported by their development teams. Due to this, the following tools have been removed:

idaes/apps/alamopy_depr (note that the new ALAMOpy interface remains avaialble in idaes/core/surrogates)
idaes/apps/helmet
idaes/apps/ripe
idaes/apps/roundingRegression
idaes/models_extra/carbon_capture

- Removal of deprecated features from IDAES v1
- Update to Pyomo v6.5 – this required a number of updates to support the new NL solver writer and to address some changes in Pyomo
- Creation of new testing suite for backward compatibility, model robustness and verification
- More general implementation of the Helmholtz EoS. This brings some new features like standard property diagrams, choice of mass or mole basis, and new state variable options
- Standardizing names in Heat Exchanger models (breaking change from v2.0.0a2):
- Control Volumes named `hot_side` and `cold_side`
- Ports names `hot_side_inlet`, `hot_side_outlet`, `cold_side_inlet` and `cold_side_outlet`
- Config Blocks names `hot_side_config` and `cold_side_config`
- Config arguments for user provided names for each side: `hot_side_name` and `cold_side_name`.
- Updating Keras surrogate tool to use v1.1 of OMLT
- New prototype API for model initialization (`idaes.core.initialization`)
- The new API uses "Model Initializer" objects instead of class methods, allowing for the definition of multiple initialization routines for a single model
- A number of common, model agnostic initialization routines have also been defined, including initialization from data, block-decomposition and a general hierarchical approach equivalent to the existing method for common unit models
- New metadata for thermophysical properties – `valid_range`
- This can be used to record the range of values over which a property value can be trusted, such as the range of experimental data used to regress parameters
- A number of new utility functions have been added to check for properties with values outside the valid range and to set bounds based on this metadata
- Updated construction of balance expressions in Control Volumes to remove unneeded terms
- In the past, unneeded terms were added as a constant 0 term, however they will now be dropped entirely from the expression
- This was necessary due to more strict unit checking in the new Pyomo solver writer which no longer ignores 0 terms
- Updates to metadata for thermophysical properties to better define known properties and units of measurement
- This results in more strict enforcement of standard naming for thermophysical and reaction properties
- Users can still define custom properties, but these must be done explicitly using the `define_custom_properties()` method instead of being implicitly created by `add_property()`
- Updated convergence tester utility tool to support definition of benchmark files (JSON format) and comparison of performance to benchmarks
- Set default iteration limit for IPOPT in IDAES config to 200 iterations
- Update scaling of example models to work with new Pyomo NL solver writer
- Improve testing of extensions and examples infrastructure to avoid need for downloading files
- Updated distillation column to centralize common functionality and remove a number of Pyomo warnings

IDAES v2 migration support

To help migrate their code to IDAES v2, the following support material is available:

- [How to migrate custom IDAES code from v1 to v2](https://github.com/IDAES/idaes-pse/wiki/idaes-v2-migrate)
- [IDAES v1 compatibility mode](https://github.com/IDAES/idaes-pse/wiki/idaes-v1-compat)

IDAES v2 changes and deprecations

- As a consequence of the standardization of the `HeatExchanger` API, support for old methods and attributes (i.e. `side_1`, `inlet_1`, `outlet_1` etc) has been removed
- Refer to the "IDAES v2 migration support" for more information
- Numerous instances where deprecated APIs were being used internally in IDAES, causing deprecation warnings to be emitted, have been removed
- Old process costing code has been fully deprecated and removed in favor of the new API

New features

- Improved support for defining new components for use in Helmholtz equations of state
- Standardized naming in heat exchanger models
- Documentation of process costing tools and examples
- Implementation of an IDAES Performance Testing Suite, which has been used to establish baseline performance metrics
- Improved metadata structure for defining Units of Measurement in property packages and updated all code to use the new format

Supported Python versions

- Support for Python 3.11 is planned for the upcoming February release
- Following the [NumPy NEP29 schedule](https://numpy.org/neps/nep-0029-deprecation_policy.html#drop-schedule), the February release of IDAES will also be the last to support Python 3.8

IDAES v2 Changes and Deprecations

- **Reminder** that support for IDAES v1 series will end in November, and backwards compatibility will be removed
- When instantiating a `ProcessBlock`, options can now be passed directly as keyword arguments (kwargs)
instead of having to be provided as a separate dictionary through the `default=` kwarg

New Features

- Initial binary releases for Mac OSX running on ARM chipsets
- New method for `StateBlock`s: users can now do `state.build_port()` to construct a `Port` linked to the given state block
- Many new examples and documentation

Deprecations and Moved Files:

- In preparation for the upcoming IDAES v2.0 release, the IDAES repository has been significantly reorganized to better group content and reduce the number of top-level directories
- In order to facilitate a smooth transition, the existing folder structure will remain in place until the v2.0 release in November with redirection links to the new location of most modules
- Importing a module from its old location will be redirected to the new location and a deprecation warning will be logged, with a pointer to the new location
- A new API has been implemented for costing of process equipment in IDAES
- The old costing methods will continue to be supported with deprecation warnings until the v2.0 release in November, after which they will be removed
- Users of these tools should begin converting their code to use the new costing APIs

General

- Added `reporting_units` option to the IDAES configuration dictionary to allow users to specify specific output units for quantities
- e.g. `report_units={“pressure”: pyo.units.bar}`
- All IDAES reporting functions will convert quantities to the units defined in this dictionary
- Added units of measurement to IDAES stream tables and reporting functions
- Unit model for carbon capture using MEA solvent, including detailed correlations for heat and mass transfer with enhancement factor
- Added support for units of measurement and scaling tools to the gas_solid_contactor model library
- Addition of a new lumped capacitance model for 0D heat exchangers which includes effects of conduction through the heat exchanger walls
- New models for solid oxide fuel cells and solid oxide electrolysis cells
- New models for natural gas pipelines
- Added full support for PySMO tools to the new surrogate modeling API
- Added support for multiple inputs and output to PySMO and associated data sampling tools
- Improved error handling for ALAMOpy in cases where ALAMO executable encounters errors
- New API for implementing costing of process equipment and flows
- Added new supported platforms for IDAES binaries