Home

WaterTAP Academy Installation Guide

This guide will step through the processes to get started with the WaterTAP Academy. Accessing the content for the WaterTAP Academy will require that you have (1) an Integrated Development Environment (IDE) to write and run Python code - we will be using Microsoft's VSCode but other IDEs are available, (2) a GitHub account, and (3) Python and WaterTAP installed on your local machine. Likewise, this installation guide will be broken down into the following parts:

• Part 1: Installing VSCode

  • Installing VSCode
  • Installing VSCode extensions

• Part 2: Creating a GitHub account

• Part 3: Installing Python and WaterTAP

  • Installing Miniforge
  • Creating a personal copy (fork) of the WaterTAP Academy repo
  • Creating the conda environment
  • Cloning the WaterTAP Academy repo
  • Cloning the WaterTAP repo
  • Installing WaterTAP dependencies
  • Setting up Jupyter Lab

• Part 4: Installing the IDAES Flowsheet Processor (Graphical User Interface)

Part 1: Installing VSCode

VSCode is the free Microsoft integrated development environment (IDE) we will be using for the WaterTAP Academy. In addition to installing the VSCode application, we need to install the Python and GitHub extensions. For an introductory tutorial on VSCode, visit their official Getting Started page.

1. Download the VSCode installer for your operating system and install VSCode.

2. Open VSCode.

On the left side of the application is the Activity Bar:

Click the icon with four squares to open the Extension browser:

3. Install extensions

VSCode extensions are add-ons that allow users to customize their workflow by integrating additional capabilities. Follow the instructions here to find and install the Python and Jupyter extensions. To be sure you install the right extensions, paste the following Extension IDs into the search bar: ms-python.python and ms-toolsai.jupyter.

Part 2: Creating a personal GitHub account

You must create a GitHub account to interact with issues, pull requests, and discussion boards. Visit the GitHub Getting Started page for instructions on how to create an account.

Part 3: Installing Python and WaterTAP

1. Installing Miniforge

Miniforge is a tool for managing Python packages and environments. Download Miniforge for your system from this website. The "latest" version is recommended. Be sure to take note of where Miniforge is being installed - this may be important for calling conda in step 4. For most users, it will default to a folder named miniforge3 within the C:\Users\YourUsername directory. If it defaults to C:\Users\YourUsername\AppData\Local, consider moving the installation inside of C:\Users\YourUsername to avoid potential issues with the file path length.

Run the downloaded installer to start the guided installation process. When prompted to choose options, it is OK to use the default (i.e. already selected) value(s).

Note

Be sure to install for "Just Me (recommended)" as opposed to "All Users (requires admin privileges)".

2. Forking the WaterTAP Academy repository

This creates a copy of the WaterTAP Academy Repository attached to your GitHub account that you can later modify for your own work without affecting the original repository. This may also come in handy later in the course when it comes time to share code for troubleshooting or other collaborative purposes.

By default, your fork will have the same name as the repository: "watertap_academy_fall_2025". To help distinguish your fork from main, rename it to "myfork-watertap_academy_fall_2025", and then hit "Create fork".

3. Opening a terminal window

Open a terminal window by searching for and running the "Miniforge Prompt" program. Alternatively, the terminal window can be opened directly in VSCode.

4. Creating the Conda environment

At the terminal prompt, run the following command to create the Conda environment that will be used for the tutorial:

conda create --yes --name watertap-academy -c conda-forge python=3.11 git

Note

If you encounter a "the term conda is not recognized" error, try running conda init --all in the Miniforge terminal. If this does not resolve the issue, open VSCode, press Ctrl + Shift + P, type "Preferences: Open Settings (JSON)" or "Preferences: Open User Settings (JSON)" into the command palette at the top of the screen, and then insert the following into the dictionary. The following code assumes Miniforge is installed under your %USERPROFILE% (C:\Users\YourUsername). The safest choice is to open a "Command Prompt" terminal in VSCode; "Powershell" terminals can be problematic.

{
    "terminal.integrated.profiles.windows": {
        "Miniforge": {
            "path": "C:\\Windows\\System32\\cmd.exe",
            "args": ["/K", "%USERPROFILE%\\miniforge3\\Scripts\\activate.bat"]
        }
    },
    "terminal.integrated.defaultProfile.windows": "Miniforge"
}

5. Activating the Conda environment

Run the following command to activate the newly created watertap-academy environment:

conda activate watertap-academy

The name of the active environment should be shown at the bottom left before the prompt:

Note

The environment will need to be reactivated every time you need to open another terminal window.

6. Cloning (downloading) the WaterTAP Academy repository locally

Download ("clone") the WaterTAP Academy repository from GitHub by running the following command:

git clone https://github.com/watertap-org/watertap_academy_fall_2025

Note

By default, this clone will create a folder within Users/your_username, so if you want to clone WaterTAP Academy to a different location (such as a folder for WaterTAP Academy), you must navigate to that directory before this step.

7. Creating a remote pointing to your fork of the WaterTAP Academy repository

Navigate to the WaterTAP Academy directory:

cd watertap_academy_fall_2025

Create a remote (pointer) to your fork of the WaterTAP Academy repo and make sure to replace "YourGitHubUsername" with your actual GitHub username. Alternatively, copy and paste the URL to your fork directly from your browser:

git remote add myfork-academy https://github.com/YourGitHubUsername/myfork-watertap_academy_fall_2025

We'll also change the name of the remote pointing to the main WaterTAP Academy repo from "origin" to "academy-repo". As a sanity check, ensure that you see "academy-repo" and "myfork-academy" after running the following code:

git remote rename origin academy-repo
git remote -v

Note

If you are in the VSCode terminal, typing code . while in the watertap_academy_fall_2025 directory will automatically open this folder.

8. Cloning the WaterTAP repository

Up to this point, we have set up the WaterTAP Academy repository locally, which will house all of the course material. We will now repeat these steps to set up the WaterTAP repository locally, which will house the core codebase. We'll start by cloning the WaterTAP repository.

In the terminal, navigate out of the WaterTAP Academy directory and then clone the WaterTAP repository from GitHub.

Note

By default, this clone will create a folder within Users/your_username, so if you want to clone WaterTAP to a different location (such as a folder for WaterTAP Academy), you must navigate to that directory during this step.

cd ..
git clone https://github.com/watertap-org/watertap

9. Renaming the WaterTAP remote

Navigate to the WaterTAP directory, and change the name from "origin" to "watertap-repo". As a sanity check, ensure that you see "watertap-repo" when running the following cell:

cd watertap
git remote rename origin watertap-repo
git remote -v

10. Installing the WaterTAP Python package and dependencies

Run the following command install WaterTAP plus the dependencies needed to run the Jupyter notebook tutorials:

pip install --editable ".[notebooks]"

Note

If you encounter an error stating Could not install packages due to an OSError: [Errno2] No such file or directory..., your filepath length likely exceeds the max filepath length set by Windows (260 characters). To resolve this issue, consider reinstalling Miniforge into the C:\Users\YourUsername directory, or, if you have admin privileges, you can modify the Windows Registry to enable long paths. Open a Powershell prompt with "Run as Administrator" and run the following command: Set-ItemProperty -Path "HKLM:System\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

11. Installing the IDAES solvers

Run the following command to install the IDAES solvers:

idaes get-extensions --verbose

12. Installing Reaktoro

Run the following commands to install Reaktoro, which is a tool that enables detailed chemistry integration.

pip uninstall -y numpy
pip install numpy==1.26.4
conda install -c conda-forge reaktoro=2.12.3 cyipopt=1.4.1
pip install git+https://github.com/watertap-org/reaktoro-pse.git

13. Registering the WaterTAP Conda environment with Jupyter

Run the following command to configure Jupyter to recognize the current WaterTAP environment:

python -m ipykernel install --user --name watertap-academy

14. Setting a password for Jupyter

Run the following command to set a password for the Jupyter server:

jupyter server password

The password doesn't need to be highly secure, since the Jupyter server runs entirely on your local machine, cannot be accessed from the network, and will only be active for the duration of this tutorial.

15. Starting the Jupyter server

Run the following command to start the Jupyter server from the current directory, specifying the introductory tutorial as the starting notebook:

jupyter lab tutorials\introduction.ipynb

Depending on your system, a browser window should open up, showing a password prompt. Enter the password chosen in the previous step. After confirming, the Jupyter Lab interface should be shown. Alternatively, Jupyter Lab can be opened inside of VSCode by navigating to the file directory.

16. Selecting the WaterTAP kernel to use to run the notebook

In the "Select Kernel" pop-up menu, select the watertap-academy entry (which corresponds to the registration command in Step 8).

Note

You might have to repeat this selection and/or ensure that the watertap-academy kernel is being used when launching (opening) other notebooks. The current kernel selection can be seen in the top-right corner of the notebook page.

17. Testing the installation

As a way to quickly test if the installation process above was successful, you can run the introduction.ipynb notebook automatically (i.e. not interactively). To do so, select Kernel > Restart Kernel and Run All Cells from the menu bar.

• The notebook should take a few minutes to finish running
• While running, the kernel indicator near the top-right corner will become "busy" (solid gray circle); when finished, it will switch back to the "idle" state (white with gray border)
• If there are no errors, all the cells of the notebooks should be populated with various outputs
• If there are errors, error messages (typically in red color) will be shown instead
• To "reset" the notebook to the initial empty state and run it again, select Kernel > Restart Kernel and Run All Cells from the menu bar

Part 4: Installing the IDAES Flowsheet Processor (Graphical User Interface)

Users can interact with WaterTAP through two interfaces. The primary method is through our code-based interface, which is built on top of Pyomo and IDAES and utilizes the full capabilities of WaterTAP, but there can be a steep learning curve. Alternatively, users can access our graphical user interface (GUI), which requires pre-built WaterTAP flowsheets and has less flexibility, but is much easier to use. This GUI is still in the early stages of its development and currently has the following capabilities:

1. Simulation and/or optimization of flowsheets built in WaterTAP
2. Sensitivity analysis for user-defined and ranges
3. Scenario analysis to compare results across various operating conditions
4. Basic visualization of simulation outputs.

To access the IDAES Flowsheet Processor, visit the documentation page for a one-click native install. Note that there are separate applications for WaterTAP, IDAES, and PrOMMiS flowsheets.