Awesome

<img align="center" height="20" src="https://i.imgur.com/vAYeCzC.png"/> 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.

:crocodile: 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

:penguin: 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.

:dragon: From <img src="https://s3.amazonaws.com/conda-dev/conda_logo.svg" height="18">

Just run the following command in the terminal:

   conda install crocoddyl -c conda-forge

Conda installation supports .

:snake: From <img src="https://res.cloudinary.com/practicaldev/image/fetch/s--4-K6Sjm4--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://cdn-images-1.medium.com/max/1600/1%2A_Wkc-WkNu6GJAAQ26jXZOg.png" height="22">

Just run the following command in the terminal:

  pip install --user crocoddyl

:turtle: With ROS

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

:package: 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
   

:file_folder: From source

1. Install Crocoddyl's mandatory dependencies:
   • pinocchio
   • Eigen
   • eigenpy
   • Boost
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
   

:mag: Documentation

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

• examples/notebooks/unicycle_towards_origin.ipynb
• examples/notebooks/cartpole_swing_up.ipynb
• examples/notebooks/arm_manipulation.ipynb
• examples/notebooks/whole_body_manipulation.ipynb
• examples/notebooks/bipedal_walking.ipynb
• examples/notebooks/introduction_to_crocoddyl.ipynb

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

:telescope: 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.

:open_book: Selected publications

<a id="1">[1]</a> 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

<a id="2">[2]</a> 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

<a id="3">[3]</a> C. Mastalli, S. P. Chhatoi, T. Corbères, S. Tonneau and S. Vijayakumar. Inverse-Dynamics MPC via Nullspace Resolution, IEEE Transactions on Robotics, 2023

:computer: Questions and Issues

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

:mag: 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.

:copyright: Credits

:writing_hand: Written by

• Carlos Mastalli, Heriot-Watt University :uk: (project manager)
• Nicolas Mansard, LAAS-CNRS :fr:
• Rohan Budhiraja, LAAS-CNRS :fr: (alumnus)

:construction_worker: With contributions from

• Guilhem Saurel, LAAS-CNRS :fr:
• Wolfgang Merkt, University of Oxford :uk:
• Justin Carpentier, INRIA :fr:
• Andrea Del Prete, Università degli Studi di Trento :it:
• Wilson Jallet, INRIA :fr:
• Maximilien Naveau, MPI :de:
• Josep Martí Saumell, IRI: CSIC-UPC :es:
• Bilal Hammoud, MPI :de:
• Julian Eßer, Fraunhofer :de:

:trophy: 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.