Getting Started

The following sections provide information on how to setup your Conda environment and install WaterTAP-REFLO on your macOS, Linux, or Windows computer.

Using Conda environments

Conda environments are a way to create and manage multiple sets of packages and/or Python versions on the same system without incurring conflicts. Each Conda environment is a dedicated directory, separate from other Conda environments and the operating system’s own directories, containing its own collection of packages, executables, and Python installation, including the Python interpreter. Once a Conda environment is activated, using the conda activate command in a terminal/console, the environment’s own version of Python will be used to run commands or interactive sessions for the remainder of the session. For these reasons, Conda environments are especially useful to install and manage multiple projects (and/or multiple versions of the same project) on the same computer with minimal effort, as they provide a way to seamlessly switch between different projects without conflicts.

Using Conda environments is not mandatory to be able to install and use WaterTAP; however, it is strongly recommended. To use Conda environments, the conda package manager is required. Refer to the Conda installation guide for detailed steps on how to install Conda for your operating system.

Install on Linux, Windows, and Mac (ARM)

This section is for Linux, Windows, and Apple computers with ARM processors (also known as Apple Silicon, e.g., M1, M2). To check if your Mac is using an ARM processor, click the apple icon in the upper left corner of your screen. Then select “About This Mac” to view the type of processor in your computer.

Create a Conda environment (in this example, named watertap-reflo) where WaterTAP-REFLO and its runtime dependencies will be installed:

conda create --name watertap-reflo --yes python=3.10

Activate the watertap-reflo environment using the command given below. If the environment was activated successfully, the environment’s name will be displayed in the terminal prompt such as (watertap-reflo) project-directory $.

conda activate watertap-reflo

Install WaterTAP-REFLO in the Conda environment using pip:

pip install watertap-reflo

After installing WaterTAP-REFLO, the IDAES Extensions command can be used to automatically install the solvers distributed as part of the IDAES Extensions. Depending on your operating system, additional steps might be needed. For more information, refer to the IDAES installation guide. From the same environment where WaterTAP-REFLO was installed, run:

idaes get-extensions

Important

The conda activate command described above must be run each time a new terminal/console session is started.

Note

Typically, the idaes get-extensions command only needs to be run once for each system, as it will install the required files into a common, system-wide location.

Install on Mac (Intel)

Warning

Intel Mac is currently not being tested, and should therefore be considered unsupported. The steps described here should not be expected to work without issues, and are here for historical and/or informational purposes only.

This section is for Apple’s Mac computers with Intel processors. To check if your Mac is using an Intel processor, click the apple icon in the upper left corner of your screen. Then select About This Mac to view the type of processor in your computer.

Create a Conda environment (in this example, named watertap-reflo) where WaterTAP-REFLO and its runtime dependencies will be installed:

conda create --name watertap-reflo --yes python=3.10

Activate the watertap-reflo environment using the command given below. If the environment was activated successfully, the environment’s name will be displayed in the terminal prompt such as (watertap-reflo) project-directory $.

conda activate watertap-reflo

Install WaterTAP-REFLO in the Conda environment using pip:

pip install watertap-reflo

After installing WaterTAP-REFLO, we need to ensure we have the Xcode toolkit, build the PyNumero Pyomo extensions, and obtain solvers from conda-forge. To install Xcode, run:

xcode-select --install

To build PyNumero, from the same environment where WaterTAP-REFLO was installed, run the following commands:

conda install --yes cmake
pyomo build-extensions

The output of the second command should be something like:

INFO: Finished building Pyomo extensions.
INFO: The following extensions were built:
   [FAIL]  appsi
   [FAIL]  mcpp
   [ OK ]  pynumero

Next, we can obtain Ipopt and CBC from conda-forge:

conda install --yes -c conda-forge ipopt coincbc

Important

The conda activate command described above must be run each time a new terminal/console session is started.

Note

The pyomo build-extensions command only needs to be run once for each system as it builds and installs the required libraries into a common, system-wide location. After building PyNumero, you should not need cmake. You can remove it by running conda uninstall cmake.

For WaterTAP-REFLO developers

This section is for developers who plan to modify or contribute to REFLO’s codebase. Contributing to REFLO will involve opening a Pull Request (PR) in REFLO’s GitHub repository. For more information, refer to WaterTAP’s documentation on how to contribute to WaterTAP’s development. All of the same guidance presented there is applicable to REFLO.

Create a Conda environment (in this example, named watertap-reflo-dev) where WaterTAP-REFLO and all dependencies needed for development will be installed, then activate it:

conda create --name watertap-reflo-dev --yes python=3.11 && conda activate watertap-reflo-dev

Clone the WaterTAP-REFLO repository to your local development machine using git clone, then enter the newly created watertap-reflo subdirectory:

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

Install WaterTAP-REFLO and the development dependencies using pip and the requirements-dev.txt file:

pip install -r requirements-dev.txt

If needed, or if this is your first time installing IDAES, WaterTAP, or WaterTAP-REFLO on your machine, run the following line from the same environment where WaterTAP-REFLO was installed.

idaes get-extensions

Note

Typically, the idaes get-extensions command only needs to be run once for each system, as it will install the required files into a common, system-wide location. Depending on your operating system, you may need to follow additional steps described above to install solvers distributed through IDAES Extensions.

To verify that the installation was successful, try running the WaterTAP-REFLO test suite using pytest:

pytest