Important notice: The master branch of the Optimization Suite does not currently include all projects because we are mid-way through the migration to new build system and only projects that have been migrated are included. This is being actively worked on, but it will be some time before all projects are migrated. In the meantime, the stable/1.9 branch builds out of the box using coinbrew.
An expanded version of this README that is updated with more details is available at
https://coin-or.github.io/user_introduction.html
The COIN-OR Optimization Suite is a collection of interoperable open source solvers from the respository of open source software maintained by the COIN-OR Foundation. It consists of the following projects.
- CoinUtils (COIN-OR utility library)
- Osi (Open Solver Interface)
- Clp (COIN-OR LP Solver)
- FlopCpp (C++-based algebraic modeling language)
- DyLP (LP solver based on dynamic simplex method)
- Vol (approximate LP solver based on Volume Algorithm)
- Cgl (Cut generation library)
- SYMPHONY (MILP solver framework)
- Cbc (COIN-OR branch-and-cut MILP solver)
- Smi (Stochastic modeling interface)
- CoinMP (Unified C API for Cbc and Clp)
- Bcp (Branch, cut, and price framework)
- Ipopt (Interior point algorithm for non-linear optimization)
- CHiPPS (COIN-OR High Performance Parallel Search framework)
- Dip (Decomposition-based MILP solver framework)
- CppAD (Automatic differentiation in C++)
- Bonmin (Solver for Convex MINLP)
- Couenne (Solver for non-convex MINLP)
- OS (Optimization Services)
- MibS (Mixed Integer Bilevel Solver)
Binaries for most platforms are available for download from Bintray. Binaries can also be installed on specific platforms, as follows. AMPL also kindly provides executables of some solvers for download at
http://ampl.com/products/solvers/open-source/.
We are working on some other better ways of getting binaries, such as conda packages, and will keep this README updated as things progress.
There is a Windows GUI installer available here for installing libraries compatible with Visual Studio (you will need to install the free Intel compiler redistributable libraries). This may get updated someday, but in the meantime, you can get binaries from BinTray.
There are Homebrew recipes for some projects available here. Just do
brew tap coin-or-tools/coinor
brew install Xyz
It is also easy to build binaries from source with coinbrew.
For Linux, there are now Debian and Fedora packages for most projects in the suite and we are investigating the possiblity of providing Linuxbrew packages.
- Click here for list of Debian packages.
- Click here for a list of Fedora packages. It is also easy to build binaries from source with coinbrew.
The Docker image available at
https://hub.docker.com/repository/docker/coinor/coin-or-optimization-suite
is another excellent way to use the COIN-OR Optimization Suite, although it is currently out of date. For details on how to obtain and use this image, see the project's Github page here.
Other ways of obtaining COIN include downloading it through a number of modeling language front-ends. For example, COIN-OR can be used through
- GAMS,
- MPL, and
- AMPL,
- MATLAB
- R: Packages available here or here or here
- Open Solver
- Solver Studio
Why download and build COIN yourself? There are many options for building COIN codes and the distributed binaries are built with just one set of options. We cannot distribute binaries linked to libraries licensed under the GPL, so you must build yourself if you want GMPL, command completion, command history, Haskell libraries, etc. Other advanced options that require specific hardware/software may also not be supported in distributed binaries (parallel builds, MPI) Once you understand how to get and build source, it is much faster to get bug fixes.
Most Linux distributions come with all the required tools installed. To obtain
the source code, the first step is to get the installer that will then
fetch the source for ProjName and all its dependencies. You do not need to
clone the repository first, just do the following! Open a terminal and execute
git clone https://www.github.com/coin-or/coinbrew
Next, to check out source code for and build all the necessary projects
(including dependencies), execute the script in the coinbrew
subdirectory. To execute the script, do
cd coinbrew
chmod u+x coinbrew
./coinbrew
(Note: The chmod command is only needed if the execute permission is not
automatically set by git on cloning). Once you run the script,
you will be prompted interactively to select a project to fetch and build. The
rest should happen automagically. Alternatively, the following command-line
incantation will execute the procedure non-interactively.
./coinbrew fetch --no-prompt ProjName@stable/x.y
./coinbrew build --no-prompt ProjName --prefix=/path/to/install/dir
Note that the prefix specified above is the directory where the packages will be
installed. If the specified prefix is writable, then all packages will be
automatically installed immediately after building. If no prefix is specified,
the package will be installed in the directory dist/. Options that would have
been passed to the configure script under the old build system can simply be
added to the command-line. For example, to build with debugging symbols, do
./coinbrew build --no-prompt ProjName --prefix=/path/to/install/dir --enable-debug
To get help with additional options available in running the script, do
./coinbrew --help
After installation, you will also need to add /path/to/install/dir/bin to your
PATH variable in your .bashrc and also add /path/to/install/dir/lib
to your LD_LIBRARY_PATH if you want to link to COIN libraries.
By far, the easiest way to build on Windows is with the GNU autotools and the GCC compilers. The first step is to install either
- Msys2
- CYGWIN
- Windows Subsystem for Linux Bash and the gcc compilers also come with the Anaconda Python distribution
If you don't already have CYGWIN installed and don't want to fool around with WSL (which is a great option if you already know your way around Unix), it is recommended to use MSys2, since it provides a minimal toolset that is easy to install. To get MSys2, either download the installer here or download and unzip MSys2 base from here (this is an out-of-date version, there may be a better place to get an archive version).
Following any of the above steps, you should have the bash command
(with Msys2, be sure to run msys2_shell.bat
or manually add msys64\usr\bin, msys64\mingw32\bin, and
msys64\mingw64\bin to your Windows path).
Once you have bash installed and in your PATH, open a Windows terminal and
type
bash
pacman -S make wget tar patch dos2unix diffutils git svn
git clone https://www.github.com/coin-or/coinbrew
Next, to check out source code for and build all the necessary projects
(including dependencies), execute the script in the COIN-OR-OptimizationSuite
subdirectory. To execute the script, do
cd coinbrew
chmod u+x coinbrew
./coinbrew
(Note: The chmod command is only needed if the execute permission is not
automatically set by git on cloning). Once you run the script,
you will be prompted interactively to select a project to fetch and build. The
rest should happen automagically. Alternatively, the following command-line
incantation will execute the procedure non-interactively.
./coinbrew fetch --no-prompt ProjName@stable/x.y
./coinbrew build --no-prompt ProjName --prefix=C:\path\to\install\dir
Note that the prefix specified above is the directory where the packages will be
installed. If the specified prefix is writable, then all packages will be
automatically installed immediately after building. If no prefix is specified,
the package will be installed in the directory dist/. Options that would have
been passed to the configure script under the old build system can simply be
added to the command-line. For example, to build with debugging symbols, do
./coinbrew build --no-prompt ProjName --prefix=C:\path\to\install\dir --enable-debug
To get help with additional options available in running the script, do
./coinbrew --help
To use the resulting binaries and/or libraries, you will need to add the
full path of the directory build\bin to your Windows executable
search PATH, or, alternatively, copy the conents of the build directory to
C:\Program Files (x86)\ProjName and add the directory
C:\Program Files (x86)\ProjName\bin
to your Windows executable search PATH. You may also consider adding
C:\Program Files (x86)\ProjName\lib to the LIB path and
C:\Program Files (x86)\ProjName\include to the INCLUDE path.
It is possible to use almost the exact same commands to build with the Visual
Studio compilers. Before doing any of the above commands in the Windows
terminal, first run the vcvarsall.bat script for your version of Visual
Studio. Note that you will also need a compatible Fortran compiler if you want
to build any projects requiring Fortran (ifort is recommended, but not
free). Then follow all the steps above, but replace the build command
with
./coinbrew build --no-prompt ProjName --prefix=C:\path\to\install\dir --enable-msvc
After obtaining source for the projects you want to build with coinbrew,
find the solution file in the directory MSVisualStudio. Note that some projects that require a Fortran compiler cannot be built this way.
OS X is a Unix-based OS and ships with many of the basic components needed to
build COIN-OR, but it's missing some things. For examples, the latest versions
of OS X come with the clang compiler but no Fortran compiler. You may also
be missing the wget utility and subversion and git clients (needed for
obtaining source code). The easiest way to get these missing utilitites is to
install Homebrew (see http://brew.sh). After installation, open a terminal and
do
brew install gcc wget svn git
To obtain the source code, the first step is to get the installer that will then fetch the source for ProjName and all its dependencies. You do not need to clone ProjName first, just do the following! Open a terminal and execute
git clone https://www.github.com/coin-or/coinbrew
Next, to check out source code for and build all the necessary projects
(including dependencies), execute the script in the coinbrew
subdirectory. To execute the script, do
cd coinbrew
chmod u+x coinbrew
./coinbrew
(Note: The chmod command is only needed if the execute permission is not
automatically set by git on cloning). Once you run the script,
you will be prompted interactively to select a project to fetch and build. The
rest should happen automagically. Alternatively, the following command-line
incantation will execute the procedure non-interactively.
./coinbrew fetch --no-prompt ProjName@stable/x.y
./coinbrew build --no-prompt ProjName --prefix=/path/to/install/dir
Note that the prefix specified above is the directory where the packages will be
installed. If the specified prefix is writable, then all packages will be
automatically installed immediately after building. If no prefix is specified,
the package will be installed in the directory dist/. Options that would have
been passed to the configure script under the old build system can simply be
added to the command-line. For example, to build with debugging symbols, do
./coinbrew build --no-prompt ProjName --prefix=/path/to/install/dir --enable-debug
To get help with additional options available in running the script, do
./coinbrew --help
After installation, you will also need to add /path/to/install/dir/bin to your
PATH variable in your .bashrc and also add /path/to/install/dir/lib
to your DYLD_LIBRARY_PATH if you want to link to COIN libraries.
All projects are now (or will soon be) managed using git. Within
the repository, the development branch is master, while branches named
stable/x.y contain long-running stable versions and tags names
releases/x.y.z indicate point releases.
The source tree for the root of project Xxx currently looks something like this
ProjName/
doxydoc/
INSTALL.md
README.md
AUTHORS
Dependencies
configure
Makefile.am
...
The ProjName subdirectory for project ProjName looks something like this.
src/
examples/
MSVisualStudio/
test/
AUTHORS
README
LICENSE
INSTALL
configure
Makefile.am
...
The files in this subdirectory are for building the library of the project
itself, with no dependencies, with the exception of the MSVisualStudio
directory, which contains solution files that include dependencies.
COIN numbers versions by a standard semantic versioning scheme: each version
has a major, minor, and patch/release number. All version within a
major.minor series are compatible. All versions within a major series are
backwards compatible. The versions with the stable/ subdirectory have two
digits, e.g., 1.1, whereas the releases have three digits, e.g., 2.1.0.
The first two digits of the release version number indicates the stable series
of which the release is a snapshot. The third digit is the release number in
that series.
There are a number of open-source projects that COIN projects can link to, but
whose source we do not distribute. We provide convenient scripts for
downloading these projects (shell scripts named ./get.ProjName and a build
harness for build them. We also produce libraries and pkg-config files. If you
need the capabilities of a particular third party library, simply run the
get.ProjName script before configuring for your build and it will be
automatically integrated. Beware of licensing in compatibilities if you plan
to redistribute the resulting binaries. The following are the supported
libraries.
- AMPL Solver Library (required to use solvers with AMPL)
- Blas (improves performance---usually available natively on Linux/OS X)
- Lapack (same as Blas)
- Glpk
- Metis
- MUMPS (required for Ipopt to build completely open source)
- Soplex
- SCIP
- HSL (an alternative to MUMPS that is not open source)
- FilterSQP
SYMPHONY, DIP, CHiPPS, and Cbc all include the ability to solve in
parallel.
-
CHiPPS uses MPI and is targeted at massive parallelism (it would be possible to develop a hybrid algorithm, however). To build in parallel, specify the location of MPI with the
--with-mpi-incdirand--with-mpi-libarguments tocoinbrew build, as follows:--enable-static \ --disable-shared \ --with-mpi-incdir=/usr/include/mpich2 \ --with-mpi-lib="-L/usr/lib -lmpich" \ MPICC=mpicc \ MPICXX=mpic++ \ -
SYMPHONY has both shared and distributed memory parallel modes, but we'll only discuss the shared memory capability here. It is enabled by default if the compiler supports OpenMP (
gccand Microsft'sclboth do, butclangdoes not). To disable share memory parallel mode, use the--disable-openmpargument tocoinbrew. -
Cbc has shared memory parallelism, which can be enabled with the
--enable-cbc-paralleltocoinbrew -
DIP currently has a shared memory parallel mode that works the same way as SYMPHONY's.
There are many configure options for customizing the builds, which is the advantage of learning to build yourself.
- Over-riding variables:
CC, CXX, F77, CXX_ADDFLAGS --prefix--enable-debug--enable-gnu-packages-CIndividual project also have their own options.ProjName/configure --helpwill list the options for project ProjName.- The options for individual projects can be given to the root
coinbrewscript---they will be passed on to subprojects automatically.
Some documentation on using the full optimization suite will someday be available at http://coin-or.github.io/. There is also a full tutorial on the Optimization Suite and much more at http://coral.ie.lehigh.edu/~ted/teaching/coin-or.
User's manuals and documentation for project ProjName can be obtained at either http://coin-or.github.io/ProjName or http://www.coin-or.org/ProjName. Doxygen source code documentation for some projects can also be obtained at http://coin-or.github.io/Doxygen
Support is available primarily through mailing lists and bug reports at http://github.com/coin-orProjName/issues/new.
