Skip to content

Latest commit

 

History

History
242 lines (190 loc) · 10.2 KB

README.md

File metadata and controls

242 lines (190 loc) · 10.2 KB
Raw

Build Status Documentation ROS integration CodeFactor License BSD-3-Clause DOI

A modern, light-weight, Eigen-based C++ interface to Nonlinear Programming solvers, such as Ipopt and Snopt.

An example nonlinear optimization problem to solve is defined as:


Features • Install • Examples • Contribute • Publications • Authors

Features

Combines the advantages of Ipopt / Snopt and Eigen:

Ipopt / Snopt Eigen
✔️ high-quality solvers for nonlinear optimization ✔️ modern, intuitive formulations of vectors and matrices
❌ C++ API inconvenient and error-prone (raw pointers, index management, jacobian construction) ✔️ highly efficient implementations
❌ linking and exporting difficult
  • Solver independent formulation of variables and constraints with Eigen (highly efficient)
  • Automatic index management by formulation of variable- and constraint-sets
  • Integration: pure cmake find_package(ifopt) or catkin/ROS (optional)
  • light-weight (~2k lines of code) makes it easy to use and extend

An optimization problem consists of multiple independent variable- and constraint-sets. Each set represents a common concept, e.g. a set of variables might represents spline coefficients, another footstep positions. Similarly, a constraint-set groups similar constraints together. ifopt allows users to define each of these sets independently in separate classes and then builds the overall problem from these sets. (No more worrying adapting indices when adding or removing sets).


find x0, x1                              (variable-sets 0 & 1)
s.t
  x0_lower  <= x0 <= x0_upper            (bounds on variable-set x0 \in R^2)

  {x0,x1} = arg min c0(x0,x1)+c1(x0,x1)  (cost-terms 0 and 1)

  g0_lower < g0(x0,x1) < g0_upper        (constraint-set 0 \in R^2)
  g1_lower < g1(x0,x1) < g0_upper        (constraint-set 1 \in R^1)

Supplying derivative information greatly increases solution speed. ifopt allows to define the derivative of each cost-term/constraint-set with respect to each variable-set independently. This ensures that when the order of variable-sets changes in the overall vector, this derivative information is still valid. These "Jacobian blocks" must be supplied through ConstraintSet::FillJacobianBlock() and are then used to build the complete Jacobian for the cost and constraints.


A graphical overview as UML can be seen here.

Install

The easiest way to install is through the ROS binaries and you're all set!

sudo apt-get install ros-<distro>-ifopt

Install dependencies

In case you don't use ROS or the binaries don't exist for your distro, you can easily build these packages from source. For this, install the required dependencies Cmake, Eigen and Ipopt using

sudo apt-get install cmake libeigen3-dev coinor-libipopt-dev

If you want to link to a local installation of Ipopt or to Snopt, see here.

Build with cmake

  • Install

    git clone https://github.com/ethz-adrl/ifopt.git && cd ifopt
mkdir build && cd build
cmake ..
make
sudo make install # copies files in this folder to /usr/local/*
# sudo xargs rm < install_manifest.txt # in case you want to uninstall the above

  • Use: To use in your cmake project, see this minimal CMakeLists.txt:

    find_package(ifopt)
# Formulate (ifopt:ifopt_core) and solve (ifopt::ifopt_ipopt) the problem
add_executable(main main.cpp)
# Pull in include directories, libraries, ... 
target_link_libraries(main PUBLIC ifopt::ifopt_ipopt)

Build with catkin

  • Install: Download catkin or catkin command line tools, then:

    cd catkin_ws/src
git clone https://github.com/ethz-adrl/ifopt.git
cd ..
catkin_make_isolated # `catkin build` if you are using catkin command-line tools 
source ./devel/setup.bash

  • Use: Include in your catkin project by adding to your CMakeLists.txt

    add_compile_options(-std=c++11)
find_package(catkin COMPONENTS ifopt) 
include_directories(${catkin_INCLUDE_DIRS})
target_link_libraries(foo ${catkin_LIBRARIES})

    Add the following to your package.xml:

    <package>
  <depend>ifopt</depend>
</package>

Examples

Unit tests & toy problem

Navigate to your build folder in which the Makefile resides, which depends on how you built the code:

cd ifopt/build  # plain cmake 
cd catkin_ws/build_isolated/ifopt/devel # catkin_make_isolated
cd catkin_ws/build/ifopt # catkin build

Make sure everything installed correctly by running the test target

make test

You should see ifopt_ipopt-example....Passed (or snopt if installed) as well as ifopt_core-test if gtest is installed.

If you have IPOPT installed and linked correctly, you can also run the binary example directly (again, first navigate to the build folder with the Makefile)

make test ARGS='-R ifopt_ipopt-example -V'

Output:

1.0 0.0

towr

A more involved problem, taken from towr, with multiple sets of variables and constraints to generate motions for legged robots produces the following:

Contribute

We love pull request, whether its interfaces to additional solvers, bug fixes, unit tests or updating the documentation. Please have a look at CONTRIBUTING.md for more information. See here the list of contributors who participated in this project.

Publications

If you use this work, please consider citing as follows:

@misc{ifopt,
  author       = {Alexander W Winkler},
  title        = {{Ifopt - A modern, light-weight, Eigen-based C++ interface to 
                   Nonlinear Programming solvers Ipopt and Snopt.}},
  year         = 2018,
  doi          = {10.5281/zenodo.1135046},
  url          = {https://doi.org/10.5281/zenodo.1135046}
}

The research project within which this code was developed:

Authors

Alexander W. Winkler - Initial Work/Maintainer

This was has been carried out at the following institutions:

               

Additional Information

Linking to custom Ipopt or Snopt

If you are building from source and want to use a locally installed version of Ipopt add the path to your Ipopt build folder to your ~/.bashrc, e.g.

export IPOPT_DIR=/home/your_name/Code/Ipopt-3.12.8/build

In case your OS doesn't provide the precompiled binaries or the required version, you can also easily install Ipopt from source as described here. This summary might work for you:

wget https://www.coin-or.org/download/source/Ipopt/Ipopt-3.11.10.zip
unzip Ipopt-3.11.10.zip
cd Ipopt-3.11.10/ThirdParty/Mumps
./get.Mumps  # HSL routines are faster (http://www.hsl.rl.ac.uk/ipopt/)
cd ../../
mkdir build && cd build
../configure --prefix=/usr/local
make
make test
make install
export IPOPT_DIR=`pwd`

If you need an interface to Snopt, point cmake to that build folder in your ~/.bashrc through e.g.

export SNOPT_DIR=/home/your_name/Code/Snopt

and run cmake as

cmake -DBUILD_SNOPT=ON ..