reaktoro-pse introduction

1. Overview

This is a package for configuring Reaktoro as a gray box model in Pyomo, IDAES-PSE, and WaterTAP modeling libraries. This package is not meant to replace or act as a higher level API for Reaktoro - it is only meant to enable setting up Reaktoro equilibrium problems as blocks on Pyomo models and automate transferring Reaktoro data into Pyomo variables.

2. Prerequisites

The user must familiarize thyself with Reaktoro options and usage, especially when selecting Reaktoro provided databases, database files, and activity models for aqueous, solid, and gas phases. This package does not automatically select any of these options, and will use ideal models by default.

• Please refer here for information on Reaktoro supported databases (all are supported)
• Please refer here for information on Reaktoro supported activity models (all are supported, included chain operations, or passing in pre-configured activity models)

By default the package will use:

• Database: PhreeqcDatabase
• Data file: pitzer.dat
• Aqueous activity models: ActivityModelIdealAqueous
• Gas activity models: ActivityModelIdealGas
• Solid activity models: ActivityModelIdealSolution
• Ion exchange activity modells: ActivityModelIonExchange

3. Inputs and outputs of the Reaktoro blocks

The Reaktoro blocks built by this package are designed to solve an equilibrium problem using user provided apparent species or true species, temperature, pressure, and pH, which are broken down to base elements and equilibrated within Reaktoro to provide exact speciation and equilibrium state. Using this state the block can return various information supported by Reaktoro:

• Chemical properties
• Aqueous properties
• Pyomo build properties, which are custom properties built in Pyomo that use chemical properties or aqueous properties as inputs

Note: Only Reaktoro properties that return a single floating point or real value are supported, as they will be directly matched to a Pyomo Var. Reaktoro functions that return arrays or strings are not supported.

4. Tutorials, Examples, and Comparisons

Currently, repo includes several tutorials and examples.

Tutorials:

1. Demonstration of working with Reaktoro block that shows

   • How to balance feed charge with ReaktoroBlock
   • Provide exact speciation
   • Build reaktoro block with speciation_block option

2. Demonstration add ReaktoroBlock to 1D Reverse Osmosis model

   • How to add indexed ReaktoroBlocks WaterTAP RO1D model for calculation of Osmotic pressure

Examples:

1. Example of adding ReaktoroBlock to basic desalination problem that demonstrates how to:
   • Setup up basic ReaktoroBlock
   • Calculate basic properties for Scaling Tendency, pH, and Osmotic pressure
   • Optimize system pH for operation at target Scaling Tendency
2. Example of thermal precipitation that demonstrates how to:
   • Configure different database from default
   • Get enthalpy and vapor pressure from Reaktoro
   • Setup precipitation calculation
   • Setup simulation for removal of Calcite over different temperatures and estimate required energy input
3. Example of ion exchange calculations that demonstrates how to:
   • Set up ReaktoroBlock for charge neutralizing the feed composition
   • Use outputs from speciation block as inputs into a second property block
   • Add Ion Exchange phase and species into ReaktoroBlock
   • Optimize addition of acid and bases for maximizing Calcium removal selectivity over Magnesium
4. Example of biogas combustion that demonstrates how to:
   • Set up ReaktoroBlock for customized database
   • Use Condensed phase

Comparisons of Reaktoro-pse to PhreeqC when simulating

These comparisons further demonstrate how to setup Reaktoro-pse for each type of calculation.

1. Water removal from solution (e.g evaporative processes)
2. Vapor pressure calculation at different temperatures
3. Precipitation of mineral phases
4. Mixing of two solution

5. Solvers

To-date, this has only been tested with cyipopt - other solvers have not been tested.

• For accessing other HSL linear solvers beyond MUMPS (such as MA27, MA57, etc. solver common to WaterTAP and IDAES-PSE) follow these instructions for adding it to cyipopt.

6. Known issues

Closing dual infeasibility

In some cases Ipopt might struggle to close unscaled dual infeasibility even when primal is reduced to <1e-8. This will be typically seen in the solver trace, that shows inf_pr being reduced to <1e-8 and inf_du stops being reduced and solver does not terminate or terminates with Solved to Acceptable level. This is a result of using approximated hessian in the GrayBox model causing issues in calculations of dual infeasibility error.

Solutions

A. Set Ipopt solver option "recalc_y" to "yes"

This option will force Ipopt to use least squares method to calculate dual infeasibility, potentially improving accuracy of its estimates and reduce it to below tolerance level. Details on the recalc_y and recalc_y_feas_tol.

cy_solver = get_solver(solver="cyipopt-watertap")
cy_solver.options['recalc_y']='yes'
cy_solver.options["recalc_y_feas_tol"] = 1e-2

B. Use exact derivatives instead of numeric

The numeric derivatives carry additional errors that reduce accuracy in estimates of dual infeasibility. You can check which outputs in your Reaktoro block are exact or numeric by using your_reaktor_block.display_jacobian_outputs().

If option "A" did not work, using exact derivatives can potentially solve this issue. This can be accomplished by using properties with exact derivatives listed in JacoibanRows class. These properties can be used to write Pyomo constraints that calculate the desired property. Some properties are already supported and examples are shown of how to build them in PyomoProperties class.

Supported PyomoProperties with exact derivatives:

• scalingTendencyDirect - this only designed to work with PhreeqC data bases
• phDirect
• osmoticPressure
• vaporPressure

These properties are accessed as any other property in ReaktoroBlock. Simply pass ('scalingTendencyDirect',phase) to outputs.

Failing due to iterates diverging

In some cases you might experience a failed solve with error

EXIT: Iterates diverging; problem might be unbounded.

This, in general, is a result of bad scaling. If your model solves with out a ReaktoroBlock, then the likely culprit is autoscaling for Jacobian (and possibly variables as well). In this case its recommend to provide manual scaling for the jacobian via user scaling option when building Reaktoro, for example as follows (check thermal_precipitation.py example):

jacobian_options={
    "user_scaling": {
        ("molarEnthalpy", None): 1,
        ("specificHeatCapacityConstP", None): 1,
    },
}

You can check the jacobian scaling by calling:

your_reaktoro_block.display_jacobian_scaling()

An alternative is to increase the divergence tolerance:

solver.options["diverging_iterates_tol"] = 1e30

7. Requesting new features or issues

Please include a minimal example using Reaktoro for your specific feature or issue request if possible. Please also include full traceback for errors the occur.

8. Compatibility

Reaktoro-pse depends on the following packages and/or versions:

• Python 3.9 through 3.12
• Reaktoro>=2.12.3
• CyIpopt 1.4.1
• Pyomo>=6.8.0
• idaes-pse>=2.5.0
• watertap>=1.0.0 - (required for watertap-cyipopt wrapper only)

9. Getting started (for contributors)

Prerequisites

• A Conda distribution compatible with conda-forge, e.g. Miniforge
• Git (needed by setuptools_scm to set the version dynamically during installation of the Python package distribution)

Installation

git clone https://github.com/watertap-org/reaktoro-pse.git
cd reaktoro-pse
conda create --yes -c conda-forge --name reaktoro-pse-dev python=3.11 reaktoro=2.12.3 cyipopt=1.4.1
conda activate reaktoro-pse-dev
pip install -r requirements-dev.txt

Running tests

conda activate reaktoro-pse-dev
pytest --pyargs reaktoro_pse --verbose

Before committing

black .