Installation¶
In this page
Requirements¶
Python (2.7+ recommended)
IBM CPLEX Optimization Studio (12.9+ recommended)
Numpy (1.12+ recommended)
For more details on installing Cplex and what version to use see this section on Installing Cplex.
Older Python or Cplex versions may work but have not been tested.
Installing Compass¶
If Numpy is not installed, you can install it with
python -m pip install numpy
This needs to be installed before the other requirements because a C extension needs the location of numpy headers to compile.
Note
Accessing pip through python -m pip is done to emphasize that on systems with multiple python installations (e.g. python 2.7 and python 3.6) Compass and Cplex must be installed to the same version of python. It is otherwise identical to just using pip. Using sudo can also invoke a different version of python depending on your environment.
Then simplest way to install Compass is using pip to install from the github repository. This can be done with the following command in the terminal:
python -m pip install git+https://github.com/yoseflab/Compass.git --upgrade
This command will also update Compass to the newest version. Alternatively, you can clone the Compass repository and run setup.py.
Now to test if everything is installed, simply run:
compass -h
You should see the help text print out if installation was succesful :) For more details on how to use Compass you can visit our tutorial.
Installing Cplex¶
Compass relies on CPLEX, an optimization engine developed by IBM and free for academic use. In particular Compass uses its Python API (distinct from Docplex).
CPLEX needs to be installed directly from IBM. We note that it may be simpler to download the installation files locally and SCP/File Transfer them over to the corresponding server.
Cplex Versions¶
The version of Cplex to install will depend on what version of Python you want to use Cplex with, as IBM has gradually phased out support for older Python versions with Cplex 12.10 dropping support for Python 2.x. As a non-exhaustive list of tested Cplex versions (followed by their part number):
Python 3.7 or 3.8: Cplex 20.10 (CJ8GXML)
Python 3.6: Cplex 12.10 (CJ6BPML)
Python 2.7: Cplex 12.9 (CJ4Z5ML)
To more directly find these versions of Cplex, you can use IBM’s software search page and enter the part numbers into the “Find by part number” search box.
Download¶
First navigate to the main page for CPLEX here
Compass requires the full edition of CPLEX, which is free for academic use. Click the ‘Get student and faculty editions’ link.
Register an account or Log In to an existing account. Once logged in, scroll down to the ‘Software’ section and to a download page for “ILOG CPLEX Optimization Studio”.
Here there are a bunch of options. Find the one corresponding to your operating system, for example “IBM ILOG CPLEX Optimization Studio 12.9 for Linux x86-64 Multilingual (CNZM2ML)” and check it. Then click ‘Download Now’ at the bottom of the page. Then you probably will need to click the ‘install / re-install Download Director’ popup on the bottom and follow the instructions there.
Finally, you will be able to download
cplex_studio129.linux-x86-64.bin (or the corresponding file for your version and OS) .
Linux Install Walkthrough¶
Once the file has been transferred, on the Ubuntu instance, execute the installer by running the following commands:
First install Java (required by CPLEX) if you haven’t already done so.
Note
You may not require sudo for the following two commands depending on your environment. Given the packages install without errors, Compass should function fine.
sudo apt-get install default-jre
Then:
cd ~
chmod +x cplex_studio129.linux-x86-64.bin
sudo ./cplex_studio129.linux-x86-64.bin
Follow the instructions in the installer, accepting the license
agreement and choosing to install to the default path
/opt/ibm/ILOG/CPLEX_Studio129.
Afterwards, if it has installed successfully, you can remove the installer file with .. code:: bash
rm ~/cplex_studio129.linux-x86-64.bin
Lastly, we need to install the Python module that comes with cplex. To do this, run these commands:
cd /opt/ibm/ILOG/CPLEX_Studio129/cplex/python/3.6/x86-64_linux
python setup.py install
Note
Note that this must install to the same version of python as Compass has/will be installed to. Otherwise Compass will be unable to import the Cplex python API.
If all is good, cplex will be installed! To test this simply open a python instance and run the following command
import cplex
If there are no errors, you’re good to go!
Installing on other Operating Systems¶
For installation on Windows or Mac the process will be similar. Navigate to [Cplex Install Directory]/cplex/python/[Python Version]/[OS] and run
python3 setup.py install
For more detailed instructions see IBM’s Knowledge Center and using the “Change version or product” to navigate to the version of Cplex you downloaded. Then see here for how to setup the Python API of Cplex. As before, if you can open a Python instance and run
import cplex
Then you are good to go!