/crocoddyl

Crocoddyl is an optimal control library for robot control under contact sequence. Its solver is based on various efficient Differential Dynamic Programming (DDP)-like algorithms

Primary LanguageC++BSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

Crocoddyl Logo

Documentation Code style: black

Introduction

Crocoddyl is an optimal control library for robot control under contact sequence. Its solvers are based on novel and efficient differential dynamic programming (DDP) algorithms. Crocoddyl computes optimal trajectories and feedback gains. It uses Pinocchio for fast computation of robot dynamics and analytical derivatives.

If you want to learn more about Crocoddyl and its solvers, we suggest reading [1] [2] [3] and visiting PUBLICATIONS.md. If you want to follow the current developments and contribute, please directly refer to the devel branch.

๐ŸŠ Crocoddyl features

Crocoddyl is versatile:

  • Various optimal control solvers (DDP, FDDP, BoxFDDP, Ipopt, etc)
  • Analytical and sparse derivatives via Pinocchio
  • Differential geometry support leveraging Pinocchio
  • Various integrators, dynamics, costs and constraints
  • Numerical differentiation support
  • Automatic differentiation support via CppAD

Crocoddyl is efficient and flexible:

  • Cache friendly
  • Multi-threading support via OpenMP
  • Python bindings (including abstractions) via Boost Python
  • C++14/17/20 compliant
  • Extensively tested
  • Automatic code generation support via CppADCodeGen

๐Ÿง Installation

Crocoddyl can be easily installed on various Linux (Ubuntu, Fedora, etc.) and Unix distributions (Mac OS X, BSD, etc.). Below, there are different ways to install Crocoddyl.

๐Ÿ‰ From

Just run the following command in the terminal:

   conda install crocoddyl -c conda-forge

Conda installation supports conda install.

๐Ÿ From

Just run the following command in the terminal:

  pip install --user crocoddyl

๐Ÿข With ROS

Just clone it (with --recursive) into a catkin workspace and compile it.

๐Ÿ“ฆ From Debian / Ubuntu packages, with robotpkg

  1. If you have never added robotpkg's software repository, do it now:
    sudo tee /etc/apt/sources.list.d/robotpkg.list <<EOF
    deb [arch=amd64] http://robotpkg.openrobots.org/packages/debian/pub $(lsb_release -sc) robotpkg
    EOF
    
    curl http://robotpkg.openrobots.org/packages/debian/robotpkg.key | sudo apt-key add -
    sudo apt update
  2. Install Crocoddyl and its Python bindings:
    sudo apt install robotpkg-py3\*-crocoddyl
  3. Configure your environment variables:
    export PATH=/opt/openrobots/bin:$PATH
    export PKG_CONFIG_PATH=/opt/openrobots/lib/pkgconfig:$PKG_CONFIG_PATH
    export LD_LIBRARY_PATH=/opt/openrobots/lib:$LD_LIBRARY_PATH
    export PYTHONPATH=/opt/openrobots/lib/python3.10/site-packages:$PYTHONPATH

๐Ÿ“ From source

  1. Install Crocoddyl's mandatory dependencies:
  2. (optional) Install Crocoddyl's optional dependencies
    • OpenMP                                        (for multi-threading support)
    • CppADCogen                                (for code-generation support)
    • Ipopt                                               (for Ipopt support)
    • example-robot-data                     (for robotic examples, install Python loaders)
    • gepetto-viewer-corba                  (for display in Gepetto viewer, i.e., GepettoDisplay)
    • meshcat-python                            (for display in Meshcat, i.e., MeshcatDisplay)
    • whole_body_state_rviz_plugin    (for display in ROS, i.e., RvizDisplay)
    • crocoddyl_msgs                            (for display in ROS, i.e., RvizDisplay)
    • urdf_parser_py                              (for display in ROS, i.e., RvizDisplay)
    • jupyter                                            (for notebooks)
    • matplotlib                                       (for plotting)
  3. Clone it (with --recursive), create a build directory inside, and:
    cmake .. && make && make install

๐Ÿ” Documentation

Crocoddyl's Doxygen documentation is available here. Alternatively, you can also check out the Jupyter notebooks. Start in the following order.

Moreover, after installation, you could run the examples as follows:

python -m crocoddyl.examples.quadrupedal_gaits "display" "plot" # enable display and plot

or run examples, unit tests and benchmarks from your build directory as

cd build
make test
make -s examples-quadrupedal_gaits INPUT="display plot" # enable display and plot
make -s benchmarks-cpp-quadrupedal_gaits INPUT="100 walk" # number of trials ; type of gait

where it is possible to enable display and/or plots generated by our examples using the environment variables:

export CROCODDYL_DISPLAY=1
export CROCODDYL_PLOT=1

๐Ÿ”ญ Citing Crocoddyl

To cite Crocoddyl in your academic research, please use the following BibTeX lines:

@inproceedings{mastalli20crocoddyl,
  author={Mastalli, Carlos and Budhiraja, Rohan and Merkt, Wolfgang and Saurel, Guilhem and Hammoud, Bilal
  and Naveau, Maximilien and Carpentier, Justin and Righetti, Ludovic and Vijayakumar, Sethu and Mansard, Nicolas},
  title={{Crocoddyl: An Efficient and Versatile Framework for Multi-Contact Optimal Control}},
  booktitle = {IEEE International Conference on Robotics and Automation (ICRA)},
  year={2020}
}

Please consider citing our selected publications and contributions described in PUBLICATIONS.md.

Crocoddyl's contributions extend beyond efficient software development. Please also consider citing the algorithm contributions of our different solvers and formulations:

  • Feasibility-driven DDP (FDDP): [1]
  • Control-limited feasibility-driven DDP (Box-FDDP): [2]
  • Inverse-dynamics trajectory optimization and equality-constrained DDP solver (Intro solver): [3]

Finally, please also consider citing Pinocchio, which contributes to the efficient implementation of rigid body algorithms and their derivatives. For more details on how to cite Pinocchio visit: https://github.com/stack-of-tasks/pinocchio.

๐Ÿ“– Selected publications

[1] C. Mastalli, R. Budhiraja, W. Merkt, G. Saurel, B. Hammoud, M. Naveau, J. Carpentier, L. Righetti, S. Vijayakumar and N. Mansard. Crocoddyl: An Efficient and Versatile Framework for Multi-Contact Optimal Control, IEEE International Conference on Robotics and Automation (ICRA), 2020

[2] C. Mastalli, W. Merkt, J. Marti-Saumell, H. Ferrolho, J. Sola, N. Mansard and S. Vijayakumar. A Feasibility-Driven Approach to Control-Limited DDP, Autonomous Robots, 2022

[3] C. Mastalli, S. P. Chhatoi, T. Corbรจres, S. Tonneau and S. Vijayakumar. Inverse-Dynamics MPC via Nullspace Resolution, IEEE Transactions on Robotics, 2023

๐Ÿ’ป Questions and Issues

You have a question or an issue? Please open a new issue.

๐Ÿ” Steering Committee

Crocoddyl is managed by a steering committee which meets every two weeks to discuss ongoing developments. The committee is led by Carlos Mastalli, Nicolas Mansard, Guilhem Saurel and Justin Carpentier are other members of the committee.

ยฉ๏ธ Credits

โœ๏ธ Written by

๐Ÿ‘ท With contributions from

๐Ÿ† Acknowledgments

Crocoddyl development was supported by the EU MEMMO project and the EU RoboCom++ project. It is maintained by the Robot Motor Intelligence (RoMI) Lab @ Heriot-Watt University, the Gepetto team @ LAAS-CNRS, and the Willow team @ INRIA.