Skip to content

Installing SMS++

Jump to bottom
Niccolò Iardella edited this page Mar 15, 2021 · 119 revisions

This guide contains detailed instructions that will help you installing the required tools and libraries needed to build SMS++.

[[TOC]]

Required tools

Building SMS++ requires the following tools:

  • A C++17-compliant C++ compiler. At the moment, SMS++ works with either GCC or Clang;
  • CMake, suggested for SMS++ but actually required for building some requirements;
  • Git and make.

In most cases, tools and requirements can be installed using common package managers like apt for Debian and Ubuntu distributions, or Homebrew for macOS.

In some cases, the packages available in the repositories are outdated or have some issues. For example, at the moment of writing, the NetCDF-C++ package for Debian and Ubuntu does not contain the config file required by CMake to find the library while building SMS++.

macOS

Building stuff on macOS requires Apple's Command Line Tools. You can obtain them by either installing XCode and launching it once, or by running in the terminal:

xcode-select --install

CLT include the Clang C/C++ compiler, Git and make.

We suggest using Homebrew for the other tools and requirements. Install it with:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Use it to install CMake:

brew install cmake

Debian/Ubuntu

The required tools can be installed using apt:

sudo apt install build-essential cmake git

build-essential includes GCC and make. If you prefer Clang, run:

sudo apt install clang
sudo update-alternatives --set cc /usr/bin/clang
sudo update-alternatives --set c++ /usr/bin/clang++

Other UNIX/Linux systems

We do not actively support other UNIX and Linux systems, but you can probably adapt the following instructions to your OS with little effort.

Windows

We do not support Windows systems for now.

Getting started

Before installing the required libraries you should assess which SMS++ modules you really need: different modules have different requirements, and by excluding some modules you might avoid installing unnecessary software.

Depending on how many modules you need, you can proceed in two ways:

  • Use the SMS++ project (aka umbrella) and comment out the modules you don't need from the CMakeLists.txt file. This is the best solution if you want to install everything except maybe a few modules.
  • Fetch, build and install the modules individually, starting from the SMS++ core library. This is the best approach if you need only the library and few other modules.

Once you decided which modules install and how, you will need to install the required software.

Requirements

Note: requirements are also specified in each module's README file. Moreover, the CMakeLists.txt file of the umbrella sums them up briefly.

The SMS++ core library requires the following libraries (here is why they are needed):

So, you will need at least those. The other submodules add the following (nested) requirements:

  • BundleSolver

    • NDOSolver/FiOracle: it's included as a subproject of BundleSolver, so it will be compiled with the umbrella by default. If you are installing BundleSolver individually, you will need to manually install this first. This library requires these libraries:
      • CoinUtils, required by Clp and Osi;
      • Clp, optional for NDOSolver/FiOracle and not needed by SMS++;
      • Osi, optional for NDOSolver/FiOracle but actually needed by BundleSolver;
      • CPLEX, optional requirement for Osi, but actually needed by the current configuration of BundleSolver.

  • MCFBlock

    • MCFClass: it's included as a submodule of the umbrella, so it will be compiled with it by default. If you are installing MCFBlock individually, you will need to manually install this first. Optionally, MCFClass requires CPLEX.

  • MILPSolver

    Both requirements are optional, but you will need at least one of them to obtain a useful solver.

  • SDDPBlock

Below you will find the steps for each requirement.

Boost

On macOS, Homebrew's repository includes an updated and working version:

brew install boost

On Ubuntu/Debian, if the repository has a supported version (at least 1.72) you can install it with:

# For the core library:
sudo apt install libboost-dev

# For StOpt (SDDPBlock) also do:
sudo apt install libboost-system-dev libboost-timer-dev

Otherwise you will need to build it from the source. Download the source from here and extract it, then navigate the extracted directory and run:

# If you only need SMS++ core library:
./bootstrap.sh --with-libraries=headers
sudo ./b2 install

# If you also need Boost.system and Boost.timer for SDDPBlock:
./bootstrap.sh --with-libraries=headers,system,timer
sudo ./b2 install

You can find more details on how to obtain and build Boost here.

NetCDF-C++

NetCDF-C++ is actually a wrapper library for NetCDF-C, so you will need both.

On macOS, Homebrew's repository includes a single, updated package that includes both NetCDF-C/C++:

brew install netcdf

On Ubuntu/Debian you can install them with:

sudo apt install libnetcdf-c++4-dev

In some Debian and Ubuntu versions, we found that the packages provided in the repositories were missing the configuration file needed by CMake to find the library while building SMS++. If CMake can't find NetCDF-C/C++ while configuring SMS++, try follow these instructions to build them manually.

  1. First install NetCDF's requirements:

    # On Debian/Ubuntu
sudo apt install libhdf5-dev libcurl4-openssl-dev

# On macOS
brew install hdf5

  2. Download the latest NetCDF-C release from here and extract it.

  3. In the extracted directory, configure and build the library with CMake:

    mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_UTILITIES=OFF -DENABLE_TESTS=OFF
make
sudo make install

  4. Download the latest NetCDF-C++ release from here and extract it.

  5. In the extracted directory, configure and build the library with CMake:

    export CPATH="/usr/include/hdf5/serial/"
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DNCXX_ENABLE_TESTS=OFF
make
sudo -E make install

You can find more details on how to obtain and build NetCDF-C/C++ here.

Eigen

On macOS, Homebrew's repository includes an updated and working version:

brew install eigen

On Ubuntu/Debian, the repository should contain an updated and working version:

sudo apt install libeigen3-dev

Otherwise you will need to install it from the source.

  1. Download the latest Eigen release from here and extract it.

  2. In the extracted directory, configure and install the library with CMake:

    mkdir build && cd build
cmake .. 
sudo make install

You can find more details on how to obtain and install Eigen here.

CPLEX

Install CPLEX using the installer provided by IBM for your OS. We recommend installing it in the default directory (e.g. /Applications/CPLEX_Studio<ver> for macOS or /opt/ibm/ILOG/CPLEX_Studio<ver> on Linux).

At the moment, MILPSolver's support for CPLEX 20.1.0 is not tested, so we recommend using CPLEX 12.10.

SCIP

We recommend installing the SCIP Optimization Suite using the installers you can find here.

Before installing the suite, you will need to install the requirements:

# On Debian/Ubuntu - see note below
sudo apt install libgfortran-7-dev libtbb-dev

# On macOS  - see note below
brew install gcc tbb

Note: The actual version of the GCC/Fortran library you need depends on the version of SCIP you want to install. The download page contains information about that.

COIN-OR libraries (CoinUtils, Osi, Clp)

On macOS, Homebrew's repository includes updated versions that you can use. However, they have two main downsides:

  1. CoinUtils package depends on OpenBLAS instead of using macOS's own BLAS implementation. So you will install an otherwise useless package.
  2. Osi package does not have CPLEX support, which is required by BundleSolver.

If you are fine with that, run:

brew install coinutils osi clp

On Ubuntu/Debian, the repository should contain packages you can use. Still, the Osi package does not support CPLEX. If you are fine with that, run:

sudo apt install coinor-libcoinutils-dev coinor-libosi-dev coinor-libclp-dev

If the precompiled libraries do not suit your needs, you have two choices:

  1. Use coinbrew, COIN-OR's own installation helper
  2. Fetch and build the libraries manually

Coinbrew

TODO

See the coinbrew page.

Manual install

In case you need to build the libraries manually, follow these instructions:

  1. On Debian/Linux only, install the requirements with apt:

    sudo apt install libbz2-dev liblapack-dev libopenblas-dev

  2. Download the latest CoinUtils release from here and extract it.

  3. In the extracted directory, configure and build the library with CMake:

    ./configure --prefix=/usr/local
make
sudo make install

  4. Download the latest Osi release from here and extract it.

  5. In the extracted directory, configure and build the library with CMake:

    # Set here your main CPLEX Studio directory.
# By default, on macOS it's /Applications/CPLEX_Studio<version>
# On Linux, it's /opt/ibm/ILOG/CPLEX_Studio<version>
CPLEX_DIR=<cplex-studio-dir>
CPLEX_LIB_DIR=`ls -bd1 $CPLEX_DIR/cplex/lib/*/static_pic | tail -n1`

./configure --prefix=/usr/local  \
     --with-cplex-incdir="$CPLEX_DIR/cplex/include/ilcplex" \
     --with-cplex-lib="-L$CPLEX_LIB_DIR -lcplex -lpthread -lm -ldl"
make
sudo make install

  6. Download the latest Clp release from here and extract it.

  7. In the extracted directory, configure and build the library with CMake:

    ./configure --prefix=/usr/local
make
sudo make install

StOpt

The Stochastic Control library is not available as a binary package. You will need to build and install from the source:

  1. Install Eigen, Boost.system and Boost.timer (see above).

  2. On Debian/Linux only, install the requirements with apt:

    sudo apt install zlib1g-dev libbz2-dev

  3. Download the latest StOpt source code from here and extract it.

  4. In the extracted directory, configure and build the library with CMake:

    mkdir build && cd build
cmake .. -DBUILD_PYTHON=OFF -DBUILD_TEST=OFF
make
sudo make install

You can find more details on how to obtain and install StOpt here.

SMS++

You can proceed in two ways, depending on how many modules you need:

  • Use the umbrella to fetch multiple modules at once;
  • Fetch, build and install the modules individually.

If you prefer, you can use the instructions in the README files of the individual projects.

Using the umbrella

  1. Fetch the SMS++ project and all its modules at once, with the command:

    git clone --recurse-submodules https://gitlab.com/smspp/smspp-project.git
cd smspp-project

    Alternatively, you can save some time by fetching only the modules you need:

    git clone https://gitlab.com/smspp/smspp-project.git
cd smspp-project
git submodule update --init SMS++ UCBlock tools # ...

  2. Optional: for the latest, unreleased code check out the develop branches:

    git submodule foreach --recursive "git checkout develop || git checkout master"

  3. Optional: edit the CMakeLists.txt file and comment the lines referring to the modules you don't need.

  4. Use CMake to configure and build the project:

    mkdir build && cd build
cmake ..

    You can specify some configuration options in the cmake command (see here).

  5. Build and install the project with:

    make
sudo make install # Optional

Alternatively, you can build the project without using CMake. See the Build and install with makefiles section in the README file of the project.

Build the individual modules

Repeat the following steps for each module you want to build (as an example, the steps apply to the SMS++ core library).

  1. Fetch the module with the command:

    git clone https://gitlab.com/smspp/smspp.git
cd smspp

  2. Optional: for the latest, unreleased code check out the develop branch:

    git checkout develop

  3. Use CMake to configure the module:

    mkdir build && cd build
cmake ..

    You can specify some configuration options in the cmake command (see here).

  4. Build and install the project with:

    make
sudo make install # See note below

    Note: Installation is required for other modules to find the library. As an alternative, you can use CMake's User Package Registry, see the relevant section in the customization guide.

The test environment

You can find a good example of the above steps for the installation of SMS++ and its requirements in our Test Environment.

You can either use the environment as-is or use its scripts as a reference for installing SMS++ in your machine. In particular, smsbuild script allows to build SMS++ in the two methods described above (with or without the umbrella) and provides several customization options.

Issues and troubleshooting

If you need support, you want to submit bugs or propose a new feature for a individual module, see the Getting help section of the README for that module.

If you need support on the project installation that is not covered by the troubleshooting page, or want propose a new module, you can open a new issue.

Clone this wiki locally