Structured flowsheet wrapper util (#1702)

Python subpackage idaes.core.util.structfs to add supporting functions for annotating a flowsheet to control it programmatically, and associated functions to extract useful information during or after the run for display by other tools. Accompanying documentation and tests.

---------

Co-authored-by: Sheng Pang <shengdevelop@gmail.com>
Co-authored-by: blnicho <blnicho@sandia.gov>
Co-authored-by: Keith Beattie <ksbeattie@lbl.gov>

Author: 4 people

.github/actions/setup-idaes/action.yml

@@ -58,6 +58,9 @@ runs:
         fi
 
         echo '::group::Output of test commands for IDAES binaries'
+        echo 'List IDAES binaries directory'
+        ls -l "$(idaes bin-directory)"
+        echo 'Try to run ipopt'
         "$(idaes bin-directory)"/ipopt -v
         echo '::endgroup::'
     - name: Install AMPL SCIP (${{ inputs.ampl-scip-pip-target }})

.github/workflows/core.yml

@@ -4,10 +4,10 @@ on:
   push:
     branches:
       - main
-      - '*_rel'
+      - "*_rel"
   schedule:
     # run daily at 5:00 am UTC (12 am ET/9 pm PT)
-    - cron: '0 5 * * *'
+    - cron: "0 5 * * *"
   repository_dispatch:
     # to run this, send a POST API call at repos/IDAES/idaes-pse/dispatches with the specified event_type
     # e.g. `gh repos/IDAES/idaes-pse/dispatches -F event_type=ci_run_tests`
@@ -38,7 +38,7 @@ concurrency:
 
 env:
   # default Python version to use for checks that do not require multiple versions
-  DEFAULT_PYTHON_VERSION: '3.10'
+  DEFAULT_PYTHON_VERSION: "3.10"
   IDAES_CONDA_ENV_NAME_DEV: idaes-pse-dev
   PYTEST_ADDOPTS: "--color=yes"
 
@@ -54,7 +54,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        
+
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
@@ -76,10 +76,10 @@ jobs:
     steps:
       - name: Checkout source
         uses: actions/checkout@v4
-        
+
       - name: Run Spell Checker
         uses: crate-ci/typos@v1.24.5
-        with: 
+        with:
           config: ./.github/workflows/typos.toml
 
   pytest:
@@ -90,7 +90,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.10', '3.11', '3.12', '3.13']
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
         os:
           - linux
           - win64
@@ -99,31 +99,30 @@ jobs:
             runner-image: ubuntu-24.04
           - os: win64
             runner-image: windows-2022
-          - python-version: '3.11'
+          - python-version: "3.11"
             # only generate coverage report for a single python version in the matrix
             # to avoid overloading Codecov
             cov-report: true
 
-            
     steps:
       - uses: actions/checkout@v5
-        
       - uses: ./.github/actions/display-debug-info
       - name: Set up Conda environment
         uses: conda-incubator/setup-miniconda@v3
         with:
           activate-environment: ${{ env.IDAES_CONDA_ENV_NAME_DEV }}
           python-version: ${{ matrix.python-version }}
           miniforge-version: latest
-
       - name: Set up idaes
         uses: ./.github/actions/setup-idaes
         with:
-          install-target:  -r requirements-dev.txt
+          install-target: -r requirements-dev.txt
       - name: Add pytest CLI options for coverage
         if: matrix.cov-report
         run: |
           echo PYTEST_ADDOPTS="$PYTEST_ADDOPTS --cov --cov-report=xml" >> "$GITHUB_ENV"
+      - name: Install pandoc
+        run: conda install -c conda-forge pandoc
       - name: Run pytest (not integration)
         run: |
           pytest --pyargs idaes -m "not integration"
@@ -134,7 +133,7 @@ jobs:
           name: coverage-report-${{ matrix.os }}
           path: coverage.xml
           if-no-files-found: error
-          
+
   upload-coverage:
     name: Upload coverage report (Codecov)
     needs: [pytest]
@@ -146,7 +145,7 @@ jobs:
     steps:
       # the checkout step is needed to have access to codecov.yml
       - uses: actions/checkout@v4
-        
+
       - uses: actions/download-artifact@v4
         with:
           name: coverage-report-${{ matrix.report-variant }}
@@ -170,13 +169,15 @@ jobs:
     needs: [code-formatting, spell-check]
     steps:
       - uses: actions/checkout@v4
-        
+
       - name: Set up Conda environment
         uses: conda-incubator/setup-miniconda@v3
         with:
           activate-environment: ${{ env.IDAES_CONDA_ENV_NAME_DEV }}
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
           miniforge-version: latest
+      - name: Install pandoc
+        run: conda install -c conda-forge pandoc
       - name: Set up idaes
         uses: ./.github/actions/setup-idaes
         with:
@@ -206,7 +207,7 @@ jobs:
       # NOTE: using Conda instead of actions/setup-python in this job is not strictly necessary
       # as it doesn't need to run on Windows or use the setup-idaes local action,
       # but we do it for consistency with the other jobs
-        
+
       - name: Set up Conda environment
         uses: conda-incubator/setup-miniconda@v3
         with:
@@ -216,7 +217,7 @@ jobs:
       - name: Set up idaes
         uses: ./.github/actions/setup-idaes
         with:
-          install-target:  -r requirements-dev.txt
+          install-target: -r requirements-dev.txt
       - name: Run pylint
         run: |
           echo "::group::Display pylint version"
@@ -240,7 +241,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
-        
+
       - name: Set up Conda environment
         uses: conda-incubator/setup-miniconda@v3
         with:
@@ -250,7 +251,7 @@ jobs:
       - name: Set up idaes
         uses: ./.github/actions/setup-idaes
         with:
-          install-target:  -r requirements-dev.txt
+          install-target: -r requirements-dev.txt
       - name: Create empty pytest.ini file
         run: |
           echo "" > pytest.ini

.github/workflows/typos.toml

@@ -58,3 +58,6 @@ PN = "PN"
 hd = "hd"
 Tge = "Tge"
 iy = "iy"
+
+# more chemE abbreviations
+HDA = "HDA"

docs/build.py

@@ -73,6 +73,7 @@ def run_apidoc(clean=True, dry_run=False, **kwargs):
             "apidoc",
             "../idaes",
             "../idaes/*tests*",
+            "../idaes/core/util/structfs",  # handled by apidoc2
         ],
         60,
         dry_run,

docs/conf.py

@@ -12,6 +12,7 @@
 
 # For importing from idaes.<modules..>
 sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("."))
 
 
 # -- General configuration ------------------------------------------------
@@ -36,8 +37,25 @@
     "sphinxarg.ext",
     "sphinx.ext.doctest",
     "sphinx_copybutton",
+    "nbsphinx",
+    # MystMD extensions
+    "myst_parser",
+    "autodoc2",
 ]
 
+# Myst autodoc2 (experimental)
+autodoc2_packages = [
+    "../idaes/core/util/structfs",
+]
+autodoc2_output_dir = "reference_guides/core/util"
+autodoc2_render_plugin = "myst"
+autodoc2_docstring_parser_regexes = [
+    # render docstrings in matching files as Markdown
+    ("../idaes/core/util/structfs/.*", "myst"),
+]
+autodoc2_no_index = True
+autodoc2_index_template = None  # don't write index.rst
+
 # Put type hints in the description, not signature
 autodoc_typehints = "description"
 
@@ -51,7 +69,10 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
 
 # The encoding of source files.
 #
@@ -62,7 +83,7 @@
 
 # General information about the project.
 project = "IDAES"
-copyright = "2016-2024, David Miller et al."
+copyright = "2016-2026, David Miller et al."
 author = "The IDAES project"
 
 
@@ -85,7 +106,14 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["apidoc/*tests*"]
+exclude_patterns = [
+    "apidoc/*tests*",
+    "../idaes/core/util/structfs",
+    "build",
+    "build/**",
+    "_build",
+    "_build/**",
+]
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
@@ -140,6 +168,11 @@ def __call__(self, app, docname, source):
     "pyomo": ("https://pyomo.readthedocs.io/en/stable/", None),
 }
 
+# nbsphinx notebook execution
+# other options are "never" and "always"
+nbsphinx_execute = "auto"
+
+
 # -- Options for HTML output ----------------------------------------------
 
 html_theme = "sphinx_book_theme"

docs/examples/index.rst

@@ -0,0 +1,15 @@
+Examples
+========
+
+.. toctree::
+    :maxdepth: 1
+
+    structfs/index
+
+.. note::
+
+    Most of the IDAES example flowsheets are available on the
+    `IDAES examples documentation pages <https://idaes-examples.readthedocs.io/en/latest/>`_.
+
+This section of the documentation contains some internal examples that are targeted at specific features,
+currently the "structured flowsheet" (structfs) functionality in :mod:`idaes.core.util.structfs`.

docs/examples/structfs/flash_flowsheet.py

@@ -0,0 +1,85 @@
+###############################################################################
+# The Institute for the Design of Advanced Energy Systems Integrated Platform
+# Framework (IDAES IP) was produced under the DOE Institute for the
+# Design of Advanced Energy Systems (IDAES).
+#
+# Copyright (c) 2018-2026 by the software owners: The Regents of the
+# University of California, through Lawrence Berkeley National Laboratory,
+# National Technology & Engineering Solutions of Sandia, LLC, Carnegie Mellon
+# University, West Virginia University Research Corporation, et al.
+# All rights reserved.  Please see the files COPYRIGHT.md and LICENSE.md
+# for full copyright and license information.
+#
+###############################################################################
+"""
+Simple Flash flowsheet for use in testing.
+"""
+
+from pyomo.environ import ConcreteModel, SolverFactory
+from idaes.core import FlowsheetBlock
+
+# Import idaes logger to set output levels
+import idaes.logger as idaeslog
+from idaes.models.properties.activity_coeff_models.BTX_activity_coeff_VLE import (
+    BTXParameterBlock,
+)
+from idaes.models.unit_models import Flash
+from idaes.core.util.structfs.fsrunner import FlowsheetRunner
+
+FS = FlowsheetRunner()
+
+# # Flash Unit Model
+#
+# Author: Jaffer Ghouse
+# Maintainer: Dan Gunter
+# Updated: 2023-06-01
+
+
+@FS.step("build")
+def build_model(ctx):
+    """Build the model."""
+    m = ConcreteModel()
+    m.fs = FlowsheetBlock(dynamic=False)
+    m.fs.properties = BTXParameterBlock(
+        valid_phase=("Liq", "Vap"), activity_coeff_model="Ideal", state_vars="FTPz"
+    )
+    m.fs.flash = Flash(property_package=m.fs.properties)
+    # assert degrees_of_freedom(m) == 7
+    ctx.model = m
+
+
+@FS.step("set_operating_conditions")
+def set_operating_conditions(ctx):
+    """Set operating conditions."""
+    m = ctx.model
+    m.fs.flash.inlet.flow_mol.fix(1)
+    m.fs.flash.inlet.temperature.fix(368)
+    m.fs.flash.inlet.pressure.fix(101325)
+    m.fs.flash.inlet.mole_frac_comp[0, "benzene"].fix(0.5)
+    m.fs.flash.inlet.mole_frac_comp[0, "toluene"].fix(0.5)
+    m.fs.flash.heat_duty.fix(0)
+    m.fs.flash.deltaP.fix(0)
+
+
+@FS.step("initialize")
+def init_model(ctx):
+    """ "Initialize the model."""
+    m = ctx.model
+    m.fs.flash.initialize(outlvl=idaeslog.INFO)
+
+
+@FS.step("set_solver")
+def set_solver(ctx):
+    """Set the solver."""
+    ctx.solver = SolverFactory("ipopt")
+
+
+@FS.step("solve_initial")
+def solve(ctx):
+    """Perform the initial model solve."""
+    ctx["results"] = ctx.solver.solve(ctx.model, tee=ctx["tee"])
+
+
+@FS.step("solve_optimization")
+def solve_o(ctx):
+    ctx["results"] = ctx.solver.solve(ctx.model, tee=ctx["tee"])