Installation

Prerequisites

The OCS2 library is written in C++11. It is tested under Ubuntu 20.04 with library versions as provided in the package sources.

Source code

The source code is hosted on GitHub: leggedrobotics/ocs2.

# Clone OCS2
git clone git@github.com:leggedrobotics/ocs2.git

Dependencies

  • C++ compiler with C++11 support

  • Eigen (v3.3)

  • Boost C++ (v1.71)

  • GLPK sudo apt install libglpk-dev

  • catkin sudo apt-get install catkin

  • pybind11_catkin, ROS package, installable via sudo apt install ros-noetic-pybind11-catkin

  • catkin-pkg package for python3. Install with sudo apt install python3-catkin-tools

  • Doxygen for documentation. Install with sudo apt install doxygen doxygen-latex

Optional Dependencies

  • For rigid multi-body dynamics library and self collision support clone Pinocchio and HPP-FCL into your workspace

# Clone pinocchio
git clone --recurse-submodules https://github.com/leggedrobotics/pinocchio.git
# Clone hpp-fcl
git clone --recurse-submodules https://github.com/leggedrobotics/hpp-fcl.git
# install dependencies
sudo apt install liburdfdom-dev liboctomap-dev libassimp-dev

  • For various robotic assets used in OCS2 unit tests and the robotic examples

# Clone ocs2_robotic_assets
git clone https://github.com/leggedrobotics/ocs2_robotic_assets.git

  • rqt_multiplot package can be used for visualizing the solver’s performance indices and other optimization outputs

sudo apt-get install ros-noetic-rqt-multiplot

  • RaiSim simulator can be used as a provider for rollouts. The corresponding ocs2_raisim package has additional requirements:

    RaiSim package, which needs to be installed from source by cloning it into your workspace:

    git clone --depth 1 https://github.com/raisimTech/raisimLib.git -b v1.1.01

    For installation, follow the instructions of the RaiSim webpage. Alternatively, in order to make the installation easy to find for catkin and easy to uninstall in the future, consider using CheckInstall which will install RaiSim as a debian package. For this, replace the original commands:

    cmake .. -DCMAKE_INSTALL_PREFIX=$LOCAL_INSTALL <other options>
make install -j4

    with:

    cmake .. <other options>     (Without INSTALL_PREFIX)
make -j4 && sudo checkinstall

    This will install RaiSim at the default location of /usr/local/lib which will also be automatically detected by catkin. When asked by checkinstall, change the package name to something appropriate (e.g. “raisim”) to it find later for package management, such as for uninstallation (dpkg -r <package_name>).

    For visualization, use RaiSim Unity, where pre-built executables are provided in the raisimLib/raisimUnity directory. For example, it can be used for debugging purposes to see if conversions between OCS2 and RaiSim are correct.

  • Grid Map catkin package, which may be installed with sudo apt install ros-noetic-grid-map-msgs.

  • ONNX Runtime is an inferencing and training accelerator. Here, it is used for deploying learned MPC-Net policies in C++ code. To locally install it, do the following:

    cd /tmp
wget https://github.com/microsoft/onnxruntime/releases/download/v1.7.0/onnxruntime-linux-x64-1.7.0.tgz
tar xf onnxruntime-linux-x64-1.7.0.tgz
mkdir -p ~/.local/bin ~/.local/include/onnxruntime ~/.local/lib ~/.local/share/cmake/onnxruntime
rsync -a /tmp/onnxruntime-linux-x64-1.7.0/include/ ~/.local/include/onnxruntime
rsync -a /tmp/onnxruntime-linux-x64-1.7.0/lib/ ~/.local/lib
rsync -a ~/git/ocs2/ocs2_mpcnet/ocs2_mpcnet_core/misc/onnxruntime/cmake/ ~/.local/share/cmake/onnxruntime

    We provide custom cmake config and version files to enable find_package(onnxruntime) without modifying LIBRARY_PATH and LD_LIBRARY_PATH. Note that the last command above assumes that you cloned OCS2 into the folder git in your user’s home directory.

  • Virtual environments are recommended when training MPC-Net policies:

    sudo apt-get install python3-venv

    Create an environment and give it access to the system site packages:

    mkdir venvs && cd venvs
python3 -m venv mpcnet

    Activate the environment and install the requirements:

    source ~/venvs/mpcnet/bin/activate
python3 -m pip install -r ~/git/ocs2/ocs2_mpcnet/ocs2_mpcnet_core/requirements.txt

    Newer graphics cards might require a CUDA capability which is currently not supported by the standard PyTorch installation. In that case check PyTorch Start Locally for a compatible version and, e.g., run:

    pip3 install torch==1.10.2+cu113 -f https://download.pytorch.org/whl/cu113/torch_stable.html

Installation

Build the library

Create a new catkin workspace:

# Create the directories
# Do not forget to change <...> parts
mkdir -p <directory_to_ws>/<catkin_ws_name>/src
cd <directory_to_ws>/<catkin_ws_name>/

# Initialize the catkin workspace
catkin init
catkin config --extend /opt/ros/noetic
catkin config -DCMAKE_BUILD_TYPE=RelWithDebInfo

Clone the OCS2 library:

# Navigate to the directory of src
# Do not forget to change <...> parts
cd <directory_to_ws>/<catkin_ws_name>/src
git clone git@github.com:leggedrobotics/ocs2.git

Build and run the unit tests:

# Build it
catkin build ocs2

# Source it
source <directory_to_ws>/<catkin_ws_name>/devel/setup.bash

# run tests
catkin run_tests ocs2

Build this Documentation

Assuming python catkin tools are installed, run the following command:

# Navigate to the directory of ocs2_doc
# Do not forget to change <...> parts
cd <directory_to_ws>/<catkin_ws_name>/src/ocs2/ocs2_doc

# make build directory
mkdir -p build
# Navigate to the build folder
cd build

# build docs
cmake ..
make

This will build the documentation and place it in the build/output/sphinx folder. Open the index.html in your web browser.