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<getting_started: Getting Started> section. These advanced users will greatly benefit from improved version control and code integration capabilities.
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.
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.
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.
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.
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.
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.
git clone, subsequent Git commands should be performed from the “idaes-pse” directory.
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.
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
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.
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
The IDAES binary extensions are not yet supported on Mac/OSX
There are a few options for installing the requirements.
pip install .- basic install using what is in setup.py
pip install .[dev]- basic install as above and also installs the Sphinx doc tools for building the documentation locally
pip install -r requirements.txt- same as # 1 but installs our “development” Pyomo and PyUtilib
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