Advanced User Installation

Advanced users who plan to develop their own models or tools are encouraged to install IDAES using Git and GitHub as described in this section, rather than using the instructions in the getting started section. These advanced users will greatly benefit from improved version control and code integration capabilities.

Git and GitHub Basics

Git is a distributed version control system that keeps track of changes in a set of files, while GitHub is a hosting service for Git repositories that adds many other features that are useful for collaborative software development.

Both Git and GitHub are widely used and there are excellent tutorials and resources for each. See Atlassian Github tutorials , GitHub help, and Git documentation.

A limited reference for Git and GitHub terminology and commands is provided here, users that are new to Git and GitHub are strongly encouraged to use the more detailed resources above.

Installation with GitHub

The main IDAES GitHub repository is idaes-pse. This repository includes the core framework, model libraries, and integrated tools. It contains all of the release versions of IDAES and is frequently updated with new features.

The following instructions describe how to install and update the idaes-pse repository.

Github Setup

In order to use GitHub, you need to create a login on GitHub.

Fork the Repository

You use a “fork” of a repository (or “repo” for short) to create a space where you have complete control and can make changes without directly affecting the main repository.

../../_images/github-fork-repo_pse.png

Figure 1. Screenshot showing where to click to fork the Github repo

You should first visit the idaes-pse repo on Github at https://github.com/IDAES/idaes-pse/. Then you should click on the fork icon in the top right and click on your username. These steps will have created your own fork of the repo with the same name under your username.

Clone Your Fork

A “clone” is a copy of a Github repository on your local machine. This is what you need to do in order to actually edit and change the files. To make a clone of the fork you created in the previous step, change to a directory where you want to put the source code and run the command:

git clone https://github.com/MYNAME/idaes-pse.git
cd idaes-pse

Of course, replace MYNAME with your username. This will download all the files in the latest version of the repository onto your local disk.

Note

After the git clone, subsequent Git commands should be performed from the “idaes-pse” directory.

Add Upstream Remote

In order to guarantee that your fork can be synchronized with the “main” idaes-pse repo in the GitHub IDAES organization, you need to add a pointer to that repository as a remote. This repository will be called upstream and linked with the following command:

git remote add upstream https://github.com/IDAES/idaes-pse.git

To check to see if you added the remote correctly use the following command:

git remote -v

You should see that there are two remotes, origin and upstream. Both have two lines showing the remote name, the url, and the access (fetch or push). Origin is the pointer to your fork and was automatically added with the clone command, while upstream is the pointer to the main idaes-pse repo that you just added.

Create the Python Environment

Once you have the repo cloned, you can change into that directory (by default, it will be called “idaes-pse” like the repo) and install the Python packages.

But before you do that, you need to get the Python package manager fully up and running. We use a Python packaging system called Conda and we specifically use its minimal version Miniconda. If you do not already have Conda, please follow the installation instructions for your operating system in getting started.

After Miniconda is installed, we recommend creating a separate conda environment for IDAES. If you are unfamiliar with environments, a good starting guide is here. Create and activate a conda environment for the new IDAES installation with the following commands (we officially support python 3.7, but you may choose a version you prefer):

conda create -n idaes python=3.7
conda activate idaes

Note

When setting up a conda environment like this, you must conda activate idaes whenever you open a fresh terminal window and wish to use IDAES.

Finish the Installation

Now that conda and pip are installed, and you are in the “idaes” conda environment, you can run the following commands to install the requirements for IDAES and get the extensions (e.g. binaries for the solver IPOPT and other external function calls):

pip install .
idaes get-extensions

Warning

The IDAES binary extensions are not yet supported on Mac/OSX

Note

There are a few options for installing the requirements.

  1. pip install . - basic install using what is in setup.py

  2. pip install .[dev] - basic install as above and also installs the Sphinx doc tools for building the documentation locally

  3. pip install -r requirements.txt - same as # 1 but installs our “development” Pyomo and PyUtilib

  4. pip install -r requirements-dev.txt - same as # 3 with the Sphinx doc tools

Also note that these pip installs would override any package within the conda environment, so if you would like a specific package (e.g. git clone Pyomo), you should look at the requirements files and only install the packages you need.

You can test that everything is installed properly by running the tests with Pytest:

pytest -m "not integration"

The not integration tag skips some tests that are slow. If you like, you can run all of the tests with just pytest.

Update IDAES

The main branch of idaes-pse is frequently updated and a new IDAES release occurs quarterly. It is recommended that you update your fork and local repositories and conda environment periodically.

pip install -U idaes-pse
pip install -U .