crocoddyl 3.2.0

A fast and flexible implementation of Rigid Body Dynamics algorithms and their analytical derivatives

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++11/14/17/20 compliant
• Extensively tested
• Code generation in both C++ and Python via CppADCoGen

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

On ArchLinux

With your favorite AUR helper, eg. paru:

    paru -Syu crocoddyl

:dragon: From

Just run the following command in the terminal:

   conda install crocoddyl -c conda-forge

Conda installation supports .

From Nix

crocoddyl & python3Packages.crocoddyl are available in nixpkgs.

This repository is also a flake, so you may:

• run a python shell with crocoddyl: nix run github:loco-3d/crocoddyl
• use it in your own flake: crocoddyl.url = "github:loco-3d/crocoddyl";

The build cache use by CI and developers is gepetto.cachix.org

:snake: From

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)
   • pycppad                                        (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
   

You can disable the tests, examples, and benchmarks using the following CMake options: BUILD_TESTING, BUILD_EXAMPLES, and BUILD_BENCHMARK. Note that the tests, examples or benchmarks require example-robot-data.

:mag: Documentation

Crocoddyl's Doxygen documentation is available here. Alternatively, you can also check out the Jupyter notebooks. We suggest to explore at least these notebooks:

• notebooks/01_introduction_to_crocoddyl.ipynb
• notebooks/02_optimizing_a_cartpole_swingup.ipynb
• notebooks/03_optimizing_an_unicycle.ipynb
• notebooks/04_actuating_an_acrobot.ipynb
• notebooks/05_codegenerating_a_cartpole.ipynb
• notebooks/06_scaling_to_robotics.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 solvers (FDDP and Box-FDDP): [1], [2]
• Inverse-dynamics trajectory optimization and endpoint constrains: [3] [4]
• Multi-Contact Inertial Parameters Estimation and Localization in Legged Robots: [5]

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

[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.

[4] M. Parilli, S. Martinez, and C.Mastall. Endpoint-Explicit Differential Dynamic Programming via Exact Resolution, IEEE International Conference on Robotics and Automation (ICRA), 2025.

[5] S. Martinez, R. Griffin, and C.Mastalli. Multi-Contact Inertial Parameters Estimation and Localization in Legged Robots, IEEE Robotics and Automation Letters (RAL), 2025.

:computer: Questions and Issues

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

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