merge remote main

.github/workflows/checks.yml

@@ -126,10 +126,10 @@ jobs:
       if: matrix.coverage
       run:
         |
-        echo PYTEST_ADDOPTS="$PYTEST_ADDOPTS --cov-report=xml" >> $GITHUB_ENV
+        echo PYTEST_ADDOPTS="$PYTEST_ADDOPTS --cov --cov-report=xml" >> $GITHUB_ENV
     - name: Test with pytest
       run: |
-        pytest --pyargs watertap
+        pytest --pyargs watertap --idaes-flowsheets --entry-points-group watertap.flowsheets
     - name: Upload coverage report as job artifact
       if: matrix.coverage
       uses: actions/upload-artifact@v4

docs/conf.py

@@ -35,9 +35,9 @@
 author = "NAWI"
 
 # The full version, including alpha/beta/rc tags
-release = "1.2.dev0"
+release = "1.3.dev0"
 # The short X.Y version
-version = "1.2.dev0"
+version = "1.3.dev0"
 # -- General configuration ---------------------------------------------------
 
 

docs/how_to_guides/how_to_use_debugging_solver_wrapper.rst

@@ -21,7 +21,7 @@ In a python module containing the model and script to solve that model, the user
 
 .. testcode::
 
-    from watertap.core.util.model_debug_mode import activate
+    from watertap_solvers.model_debug_mode import activate
     activate()
 
 

docs/how_to_guides/how_to_use_loopTool_to_explore_flowsheets.rst

@@ -2,9 +2,9 @@ How to use loopTool to explore flowsheets
 =========================================
 
 .. index::
-   pair: watertap.tools.analysis_tools.loop_tool;loop_tool
+   pair: parameter_sweep.loop_tool;loop_tool
 
-.. currentmodule:: watertap.tools.analysis_tools.loop_tool
+.. currentmodule:: parameter_sweep.loop_tool
 
 The loopTool is a wrapper for the parameter sweep (PS) tool set, and is designed to simplify setting up parametric sweeps, enabling sweeping over discrete design choices, and providing structured data management.  
 
@@ -143,7 +143,9 @@ The sweep_param_loop parameters will be iterated over one by one, to sweep over
             param: key on the flowsheet that can be found using m.find_component (e.g., fs.costing.reverse_osmosis.membrane_cost)
             lower_limit: lower value for sampling
             upper_limit: upper value for sampling
-            num_samples: number of samples to run 
+            num_samples: number of samples to run
+
+Please note that YAML only supports literals for numeric data types. Expression-like values such as ``150 * 0.8`` will be parsed as strings and cause errors once the YAML inputs have been loaded.
 
 **Defining diff_param_loop**
 
@@ -365,7 +367,7 @@ Example of code for setting up our example of RO with ERD
    # This imports the function created in the example for RO_with_energy_recovery above
    import ro_erd as ro_setup
    # import the loopTool and utility function for getting a working directory
-   from watertap.tools.analysis_tools.loop_tool.loop_tool import loopTool, get_working_dir
+   from parameter_sweep.loop_tool.loop_tool import loopTool, get_working_dir
 
    if __name__=='__main__': we will execute the loopTool script here, required for safe execution of parallel scripts
       # We assume our .yaml file is in the same directory as this script

docs/how_to_guides/how_to_use_ui_api.rst

@@ -2,21 +2,21 @@
 
 Add a flowsheet to the UI
 ==========================
-.. py:currentmodule:: watertap.ui.fsapi
+.. py:currentmodule:: idaes_flowsheet_processor.api
 
 This API is intended for model developers who would like to connect their flowsheets to the UI.
 Developers can select which variables to "export" to the UI for each component of the model, 
 and provide extra metadata (display name, description) for them. For flowsheets, they should also 
 specify how to build and solve the flowsheets.
 
-For reference, see :class:`FlowsheetInterface` and :class:`FlowsheetExport` in the `watertap.ui.fsapi` module.
+For reference, see :class:`FlowsheetInterface` and :class:`FlowsheetExport` in the `idaes_flowsheet_processor.api` module.
 
 ----
 
 In some Python module, define the function ``export_to_ui``, which will look
 similar to this::
 
-    from watertap.ui.fsapi import FlowsheetInterface, FlowsheetCategory
+    from idaes_flowsheet_processor.api import FlowsheetInterface, FlowsheetCategory
     def export_to_ui():
         return FlowsheetInterface(
             name="NF-DSPM-DE",
@@ -194,4 +194,25 @@ entrypoint must be defined in setup.py with the path to the export file. For exa
         ]
 
 
-For a complete overview of all arguments, see :class:`FlowsheetInterface`.
+For a complete overview of all arguments, see :class:`FlowsheetInterface`.
+
+Testing flowsheet interfaces
+-------------------------------
+
+.. note::
+    The following requires the WaterTAP testing dependencies to be installed. This is done by default in a developer environment, or can be installed manually by running ``pip install "watertap[testing]"``.
+
+To verify that the flowsheet interfaces developed and distributed with WaterTAP function correctly, it is possible to use pytest to run a series of standardized tests against each interface. The ``idaes-flowsheets`` pytest plugin that enables this functionality is installed together with the rest of the WaterTAP testing dependencies. However, it must be activated by providing additional command-line flags when invoking pytest.
+
+.. code-block:: shell
+
+   # run tests for all flowsheet interfaces registered under the `watertap.flowsheets` entry point group
+   pytest --idaes-flowsheets --entry-point-group watertap.flowsheets
+
+   # run tests for one or more importable Python modules (useful when developing a new flowsheet interface as it also supports modules not yet registered as an entry point)
+   pytest --idaes-flowsheets --modules watertap.flowsheets.gac.gac_ui watertap.flowsheets.mvc.mvc_single_stage_ui
+
+.. note::
+   By default, the ``idaes-flowsheets`` pytest plugin will collect and run its tests *in addition* to the normally discovered pytest tests (e.g. test functions defined in ``test_*.py`` files throughout the current working directory). To disable normal (Python) pytest collection and only run ``idaes-flowsheets`` tests, use the ``-p no:python`` flag::
+
+        pytest --idaes-flowsheets --modules watertap.flowsheets.gac.gac_ui watertap.flowsheets.mvc.mvc_single_stage_ui -p no:python

docs/technical_reference/flowsheets/lsrro.rst

@@ -15,7 +15,7 @@ Moreover, LSRRO can be constructed using commercially available nanofiltration m
 
 
 Implementation
-==============
+--------------
 
 Figure 1 illustrates the LSRRO flowsheet. The LSRRO system comprises a conventional RO stage followed by low-salt-rejection (LSR) stages, where the saline permeate of each LSR stage is recycled to the inlet of the previous stage. Brine is concentrated further as it passes through each subsequent LSR stage.
 The first stage RO permeate is collected as purified water (Product Water) and the last LSR stage produces the final concentrated brine. 

docs/technical_reference/ui/index.rst

@@ -7,7 +7,7 @@ changes from the UI front-end.
 
 .. include:: <isonum.txt>
 
-.. py:currentmodule:: watertap.ui.fsapi
+.. py:currentmodule:: idaes_flowsheet_processor.api
 
 .. contents:: Contents
     :depth: 1

docs/technical_reference/unit_models/index.rst

@@ -32,6 +32,7 @@ Unit Models
    pump
    reverse_osmosis_0D
    reverse_osmosis_1D
+   steam_ejector
    stoichiometric_reactor
    thickener
    translators/index

docs/technical_reference/unit_models/steam_ejector.rst

@@ -0,0 +1,76 @@
+Steam Jet Ejector
+================================
+This Steam Jet Ejector unit model:
+   * Simulates the performance of a steam jet ejector for thermal vapor compression.
+   * Uses semi-empirical correlations for entrainment ratio, pressure correction factor (PCF), and temperature correction factor (TCF), based on El-Dessouky (1997).
+   * Operates in steady-state only.
+   * Assumes the discharge mixture pressure equals its saturation pressure.
+
+.. index::
+   pair: watertap.unit_models.steam_ejector;steam_ejector
+
+.. currentmodule:: watertap.unit_models.steam_ejector
+
+Degrees of Freedom
+-------------------
+In addition to the inlet state variables (i.e., temperature, pressure, and component flowrates for motive steam and entrained vapor), the Steam Ejector model has at least 1 degree of freedom that must be fixed for the unit to be fully specified. Typically, the following variables are fixed:
+
+    * Entrainment ratio
+    * Compression ratio
+
+Model Structure
+------------------
+This Steam Ejector model consists of state blocks for the properties of the motive steam inlet, entrained vapor inlet, and discharge mixture. It incorporates semi-empirical equations to model key performance parameters.
+
+
+
+Sets
+----
+.. csv-table::
+   :header: "Description", "Symbol", "Indices"
+
+   "Time", ":math:`t`", "[0]"
+   "Inlet/Outlet", ":math:`x`", "['in', 'out']"
+   "Phases", ":math:`p`", "['Liq', 'Vap']"
+   "Components", ":math:`j`", "['H2O']"
+
+Performance Metrics
+--------------------
+.. csv-table::
+   :header: "Metric", "Equation"
+
+   "Entrainment Ratio", ":math:`Ra = \frac{\dot{m}_{motive}}{\dot{m}_{entrained}}`"
+   "Compression Ratio", ":math:`CR = \frac{P_s}{P_{ev}}`"
+
+Variables
+----------
+.. csv-table::
+   :header: "Description", "Symbol", "Variable Name", "Units", "Bounds"
+
+   "Entrainment Ratio", ":math:`Ra`", "entrainment_ratio", "Dimensionless", "<4"
+   "Compression Ratio", ":math:`CR`", "compression_ratio", "Dimensionless", ">1.89"
+   "Pressure Correction Factor", ":math:`PCF`", "PCF", "Dimensionless", "N/A"
+   "Temperature Correction Factor", ":math:`TCF`", "TCF", "Dimensionless", "N/A"
+   "Motive Steam Pressure", ":math:`P_m`", "properties_motive_steam[0].pressure", "kPa", "[100, 3500]"
+   "Entrained Vapor Pressure", ":math:`P_{ev}`", "properties_entrained_vapor[0].pressure", "kPa", "N/A"
+   "Discharge Mixture Pressure", ":math:`P_s`", "properties_discharge_mix[0].pressure", "kPa", "N/A"
+
+Equations
+---------
+.. csv-table::
+   :header: "Description", "Equation"
+
+   "Pressure Correction Factor", ":math:`PCF = 3 \times 10^{-7} P_m^2 - 0.0009 P_m + 1.6101`"
+   "Temperature Correction Factor", ":math:`TCF = 2 \times 10^{-8} T_{ev}^2 - 0.0006 T_{ev} + 1.0047`"
+   "Entrainment Ratio Model", ":math:`Ra \times TCF = 0.296 \frac{P_s^{1.19}}{P_{ev}^{1.04}} \left(\frac{P_m}{P_{ev}}\right)^{0.015} PCF`"
+   "Entrainment Ratio Definition", ":math:`Ra = \frac{\dot{m}_{motive}}{\dot{m}_{entrained}}`"
+   "Compression Ratio", ":math:`CR = \frac{P_s}{P_{ev}}`"
+
+
+Class Documentation
+-------------------
+* :mod:`watertap.unit_models.steam_ejector`
+
+References
+----------
+El-Dessouky, H., Modeling and simulation of thermal vapor compression desalination plant. Symposium on Desalination of Seawater with Nuclear Energy, Taejon, Republic of Korea, 26-30 May, 1997.

docs/technical_reference/unit_models/stoichiometric_reactor.rst

@@ -133,9 +133,11 @@ Variables
    "Reagent dose", reagent_dose,[reagent],kg/:math:`\text{m}^3`
    "Reagent density", density_reagent,[reagent],kg/:math:`\text{m}^3`
    "Reagent flow mass", flow_mass_reagent,[reagent],kg/s
+   "Reagent molar flow", flow_mol_reagent,[reagent],mol/s
    "Reagent flow volume", flow_vol_reagent,[reagent],:math:`\text{m}^3`/s
    "Stoichiometric coefficients for dissolution", dissolution_stoich_comp, "[reagent, :math:`j`]",dimensionless
    "Flow mass of precipitant",flow_mass_precipitate,[precipitant],kg/s
+   "Molar flow of precipitant",flow_mol_precipitate,[precipitant],mol/s
    "Mass concentration of precipitant",conc_mass_precipitate,[precipitant],kg/:math:`\text{m}^3`
    "Stoichiometric coefficients for precipitation", precipitation_stoich_comp, "[precipitant, :math:`j`]",dimensionless
    "Fraction of solids in waste stream",  waste_mass_frac_precipitate, None, fraction

pytest.ini

@@ -1,15 +1,15 @@
 [pytest]
-addopts = --durations=100
-          --cov=watertap
+addopts = --durations=10
           --cov-config=.coveragerc
 testpaths = watertap
 log_file = pytest.log
 log_file_date_format = %Y-%m-%dT%H:%M:%S
 log_file_format = %(asctime)s %(levelname)-7s <%(filename)s:%(lineno)d> %(message)s
 log_file_level = INFO
 filterwarnings =
-    ignore::DeprecationWarning
-markers =
-    unit: mark test as unit tests.
-    component: mark test as longer, bigger, more complex than unit tests.
-    ui: mark test as relevant to the ui
+    error
+    # see IDAES/idaes-pse#1549
+   ignore:unclosed file .*Visualization-data.*SA-.*\.bin:ResourceWarning
+   # emitted sporadically during nbmake tests
+   ignore:unclosed <socket\.socket .*>:ResourceWarning
+   ignore:unclosed event loop .*:ResourceWarning

requirements-dev.txt

@@ -1,7 +1,16 @@
 black==24.3.0
 pre-commit
+
+# coverage
+pytest-cov
+
 # TODO pin exact version for pylint and astroid
 pylint<3
 astroid
-# Defer to setup.py contents
--e .[dev,notebooks,oli_api]
+
+# docs
+sphinx==7.1.*
+nbsphinx
+sphinx_rtd_theme
+
+-e .[testing,notebooks,oli_api]

setup.py

@@ -20,24 +20,14 @@
 cwd = Path(__file__).parent
 long_description = (cwd / "README.md").read_text()
 
-SPECIAL_DEPENDENCIES_FOR_RELEASE = [
-    "idaes-pse>=2.6.0,<2.7.0rc0",  # from PyPI
-]
-
-SPECIAL_DEPENDENCIES_FOR_PRERELEASE = [
-    # update with a tag from the nawi-hub/idaes-pse
-    # when a version of IDAES newer than the latest stable release from PyPI
-    # will become needed for the watertap development
-    "idaes-pse==2.6.0",
-]
 
 # Arguments marked as "Required" below must be included for upload to PyPI.
 # Fields marked as "Optional" may be commented out.
 
 setup(
     name="watertap",
     url="https://github.com/watertap-org/watertap",
-    version="1.2.dev0",
+    version="1.3.dev0",
     description="WaterTAP modeling library",
     long_description=long_description,
     long_description_content_type="text/markdown",
@@ -74,20 +64,16 @@
     packages=find_packages(
         include=("watertap*",),
     ),
-    python_requires=">=3.8",
+    python_requires=">=3.9",
     install_requires=[
         # primary requirements for unit and property models
-        # maintainers: switch to SPECIAL_DEPENDENCIES_FOR_RELEASE when cutting a release of watertap
-        *SPECIAL_DEPENDENCIES_FOR_PRERELEASE,
+        "idaes-pse >=2.7.0,<2.8.0rc0",
         "pyomo>=6.6.1",
-        "flexparser != 0.4",  # IDAES/idaes-pse#1524
+        "watertap-solvers",
         "pyyaml",  # watertap.core.wt_database
         # for parameter_sweep
-        "parameter-sweep>=0.1.dev5",
-        # for watertap.ui.api_model (though may be generally useful)
-        "pydantic >= 2, <3",
+        "parameter-sweep >=0.1.0",
         "numpy",
-        "importlib-resources",
     ],
     extras_require={
         "testing": [
@@ -96,6 +82,7 @@
             # treebeardtech/nbmake#121
             "nbmake != 1.5.1",
             "nbconvert",
+            "idaes-flowsheet-processor >=0.1.dev4",
         ],
         "notebooks": [
             "jupyter",
@@ -105,21 +92,6 @@
             "requests",
             "cryptography",  # for encrypting OLI credentials
         ],
-        "dev": [
-            "nbsphinx",  # jupyter notebook support for sphinx
-            "jinja2<3.1.0",  # see watertap-org/watertap#449
-            "Sphinx==7.1.*",  # docs
-            "sphinx_rtd_theme",  # docs
-            "urllib3 < 2",  # see watertap-org/watertap#1021,
-            # other requirements
-            "linkify-it-py",
-            "black",  # code formatting
-            # other requirements
-            "pytest",  # test framework
-            "pytest-cov",  # code coverage
-            # treebeardtech/nbmake#121
-            "nbmake != 1.5.1",
-        ],
     },
     package_data={  # Optional
         "": [